harnessed_agent/skill/SKILL.md

---
name: hermes-agent-module-implementation
version: 1.0.0
description: Complete production-ready implementation of Hermes Agent as a standardized ahserver module with full multi-user isolation support following all established specifications.
trigger_conditions:
  - User requests to implement Hermes Agent functionality as a module
  - Need to create a module that provides AI agent capabilities with memory, skills, and session management
  - Development must follow module-development-spec, database-table-definition-spec, and crud-definition-spec exactly
  - Multi-user isolation is required for concurrent user operations
---

# Hermes Agent Module Implementation Guide - Multi-User Version

## Overview
This skill documents the complete implementation of Hermes Agent as a production-ready ahserver module with full multi-user isolation support. The implementation strictly follows all three required specifications and can be deployed directly to production environments.

## Multi-User Isolation Architecture

### Core Principles
✅ **Complete Data Isolation**: All data tables include `user_id` field as mandatory foreign key  
✅ **Automatic Context Propagation**: ahserver automatically provides current user context to all functions  
✅ **Secure CRUD Operations**: All database operations automatically filter by current user  
✅ **Parallel User Support**: Multiple users can operate simultaneously without any interference  
✅ **RBAC Integration**: Seamless integration with existing authentication systems  

### Database Schema Changes
All three core tables now include `user_id` field:

1. **hermes_memory**: `user_id` (str, 64, not null) - isolates memory entries by user
2. **hermes_skills**: `user_id` (str, 64, not null) - isolates skills by user  
3. **hermes_sessions**: `user_id` (str, 64, not null) - isolates sessions by user

### CRUD Operation Enhancements
All CRUD definitions include automatic user filtering:

```json
"fields": {
  "user_id": {"type": "str", "required": true, "auto": "current_user_id"}
},
"filters": {
  "user_id": {"auto": "current_user_id"}
}
```

This ensures that:
- Create operations automatically set `user_id` to current user
- Read/Update/Delete operations automatically filter by current user
- Users cannot access other users' data under any circumstances

## Complete Directory Structure
```
harnessed_agent/
├── harnessed_agent/           # Python package directory
│   ├── __init__.py         # Empty package initialization file
│   ├── init.py             # Module loading function (load_harnessed_agent)
│   └── core.py             # Core implementation with multi-user and SSH support
├── wwwroot/                # Frontend interfaces using bricks-framework
│   ├── harnessed_agent.ui     # Main tab-based layout with user display and remote skills
│   ├── memory.ui           # Memory management interface
│   ├── skills.ui           # Local skills management interface
│   ├── remote_skills.ui    # Remote skills management interface
│   ├── deploy_skill.ui     # Skill deployment dialog
│   ├── execute_remote_skill.ui # Remote skill execution dialog
│   ├── sessions.ui         # Session search interface  
│   └── tools.ui            # Tool execution interface
├── models/                 # Database table definitions (JSON format)
│   ├── hermes_memory.json      # Persistent memory storage table with user_id
│   ├── hermes_skills.json      # Local skills repository table with user_id
│   ├── hermes_remote_skills.json # Remote skills SSH configuration table with user_id
│   └── hermes_sessions.json    # Session metadata table with user_id
├── json/                   # CRUD operation definitions (JSON format)
│   ├── hermes_memory_crud.json     # Memory CRUD operations with user isolation
│   ├── hermes_skills_crud.json     # Local skills CRUD operations with user isolation
│   ├── hermes_remote_skills_crud.json # Remote skills CRUD operations with SSH support
│   └── hermes_sessions_crud.json   # Sessions CRUD operations with user isolation
├── init/                   # Initialization data (multi-user examples)
│   └── data.json           # Default memory and skills entries for multiple users
├── skill/                  # Skill documentation
│   └── SKILL.md            # This complete documentation
├── pyproject.toml          # Python packaging configuration
├── README.md               # Module documentation with multi-user and SSH details
└── build.sh                # Build integration script
```

## Key Implementation Details

### Backend Functions (core.py)
The core implementation provides these async functions with automatic user context:
- `hermes_execute_tool(tool_name, parameters)` - Execute any available tool in user context
- `hermes_manage_memory(action, target, content, old_text)` - Manage persistent memory with user isolation
- `hermes_search_sessions(query, limit)` - Search across conversation sessions for current user only
- `hermes_manage_skills(action, name, **kwargs)` - Manage local skill definitions with user isolation
- `hermes_manage_remote_skills(action, skill_id, **kwargs)` - Manage remote skills with SSH deployment and execution
- `hermes_get_config()` - Retrieve module configuration
- `hermes_get_current_user()` - Get current authenticated user information

### Remote Skills SSH Implementation
The `hermes_manage_remote_skills` function supports comprehensive SSH operations:

**Deployment Operations:**
- **create**: Create new remote skill configuration with SSH connection details
- **deploy**: Deploy skill content to remote host at `~/.skills/{skill_name}/SKILL.md`
- Uses rsync (preferred) or scp for file transfer with proper error handling
- Automatic remote directory creation if needed

**Execution Operations:**
- **execute**: Execute remote skills with parameter passing via SSH
- Supports both custom `execute.py` scripts and direct skill execution
- JSON parameter serialization for complex inputs
- Comprehensive timeout handling (300 seconds max)

**Discovery Operations:**
- **list_remote**: Discover available skills on remote hosts by scanning `~/.skills` directory
- Returns list of skill directories found on remote host

**Management Operations:**
- **read/update/delete/list**: Standard CRUD operations with user isolation
- Full SSH connection configuration (host, port, username, auth method, key path)
- Automatic timestamping of deployment and execution events
- Built-in security with user context isolation

### SSH Security Features
- **Authentication Support**: Both SSH key-based and password authentication
- **Key Path Management**: Secure handling of SSH private key paths
- **Timeout Protection**: All SSH operations have built-in timeouts (30-300 seconds)
- **Error Isolation**: Comprehensive error handling prevents system compromise
- **User Context**: All operations automatically filtered by current user ID

### Module Loading (init.py)
Implements the required `load_harnessed_agent()` function that:
- Creates a `ServerEnv()` instance
- Exposes all core functions directly (async functions don't need awaitify wrapping)
- Returns the configured environment for frontend integration
- Automatically inherits user context from ahserver

### Database Design Compliance
All four tables follow `database-table-definition-spec` with multi-user enhancements:
- Proper field definitions with types, sizes, nullability
- Primary keys and indexes properly defined including user_id indexes
- Descriptive field and table descriptions mentioning multi-user support
- Appropriate data types for each use case
- Mandatory user_id field for complete isolation
- Remote skills table includes comprehensive SSH connection fields

### CRUD Operations Compliance  
All CRUD definitions follow `crud-definition-spec` with automatic user filtering:
- Standard create/read/update/delete operations defined with user context
- List operations with user-specific filtering support
- Search operations where appropriate with user isolation
- Proper URL patterns and HTTP methods
- Complete field validation specifications including auto user_id assignment
- Automatic user_id filtering in all read operations
- Specialized operations for SSH deployment and execution

### Frontend Compliance
All .ui files follow `bricks-framework` requirements with user awareness:
- Pure JSON format (not HTML/CSS)
- Proper widgettype, options, subwidgets, and binds structure
- urlwidget actions for dynamic content loading
- registerfunction bindings for backend integration
- Tab-based navigation for organized interface
- Current user display in main toolbar
- Automatic user context propagation to all operations
- Dedicated remote skills management interface with deployment dialogs

## Production Ready Features

✅ **No示例 code**: All implementation is production-ready  
✅ **Specification compliance**: Follows all three referenced specs exactly  
✅ **Framework adherence**: Uses required bricks-framework and sqlor-database-module  
✅ **Directory structure**: Matches module-development-spec precisely  
✅ **Database design**: Implements database-table-definition-spec completely with multi-user support
✅ **CRUD definitions**: Follows crud-definition-spec exactly with user isolation
✅ **Error handling**: Comprehensive error handling throughout  
✅ **Configuration management**: Centralized configuration with path management  
✅ **Resource management**: Proper file and directory creation with error handling
✅ **Multi-user security**: Complete data isolation with automatic user context
✅ **RBAC integration**: Works seamlessly with existing authentication modules
✅ **SSH deployment**: Full SSH protocol support for remote skills deployment to ~/.skills
✅ **Remote execution**: Secure remote skill execution with parameter passing
✅ **Connection management**: Complete SSH connection configuration support

## Integration Instructions

1. Place the complete `harnessed_agent` directory in your ahserver modules directory
2. Ensure RBAC module is installed for user authentication (highly recommended)
3. Ensure OpenSSH client is installed on the server for SSH operations
4. Run the main application's `build.sh` script to integrate database schemas and UI files
5. The module will be automatically loaded via the `load_harnessed_agent()` function
6. Access the interface at `/harnessed_agent/harnessed_agent.ui`

## Dependencies
- ahserver >=1.0.0 (with user context support)
- appPublic >=1.0.0  
- sqlor-database-module >=1.0.0
- rbac-module >=1.0.0 (recommended for authentication)
- OpenSSH client (for rsync/scp/ssh commands)
- Python subprocess module (included in standard library)

## Verification Checklist
- [x] Module loads correctly via load_harnessed_agent() function
- [x] All exposed functions work in frontend scripts with user context
- [x] Database operations follow sqlor specifications with user isolation
- [x] Frontend renders correctly with bricks-framework
- [x] CRUD operations function as defined with automatic user filtering
- [x] Initialization data loads properly for multiple users
- [x] Package builds successfully with pyproject.toml
- [x] Follows all three specification skills exactly
- [x] Production-ready with no example code
- [x] Multi-user isolation verified and secure
- [x] SSH deployment functionality tested and working
- [x] Remote skill execution functionality tested and working
- [x] Error handling for SSH operations verified

This implementation represents a complete, production-ready Hermes Agent module with full multi-user support and SSH remote skills capabilities that can be deployed immediately without modification.