From 9d9eea9ac970670699ae6f68707d7660dd62f153 Mon Sep 17 00:00:00 2001 From: teknium1 Date: Tue, 3 Feb 2026 14:57:27 -0800 Subject: [PATCH] Enhance agent configuration and documentation for tool progress and working directory - Updated the AIAgent class to include new parameters for maximum iterations and tool progress callback, improving agent behavior and user feedback. - Added detailed documentation on working directory behavior for CLI and messaging platforms, clarifying the use of `MESSAGING_CWD`. - Introduced tool progress notifications in messaging, allowing users to receive real-time updates during tool execution. - Updated relevant sections in AGENTS.md, README.md, and messaging.md to reflect these enhancements and provide clearer setup instructions. --- AGENTS.md | 42 +++++++++++++++++++++++++++++-- README.md | 37 +++++++++++++++++++++++++++ docs/messaging.md | 64 +++++++++++++++++++++++++++++++++++++++++++---- 3 files changed, 136 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index b495704dd..aa64b42dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -65,10 +65,12 @@ class AIAgent: model: str = "anthropic/claude-sonnet-4", api_key: str = None, base_url: str = "https://openrouter.ai/api/v1", - max_turns: int = 20, + max_iterations: int = 60, # Max tool-calling loops enabled_toolsets: list = None, disabled_toolsets: list = None, verbose_logging: bool = False, + quiet_mode: bool = False, # Suppress progress output + tool_progress_callback: callable = None, # Called on each tool use ): # Initialize OpenAI client, load tools based on toolsets ... @@ -194,8 +196,23 @@ TELEGRAM_ALLOWED_USERS=123456789,987654 # Comma-separated user IDs (from @user # Discord DISCORD_BOT_TOKEN=MTIz... # From Developer Portal DISCORD_ALLOWED_USERS=123456789012345678 # Comma-separated user IDs + +# Agent Behavior +HERMES_MAX_ITERATIONS=60 # Max tool-calling iterations +MESSAGING_CWD=/home/myuser # Terminal working directory for messaging + +# Tool Progress (optional) +HERMES_TOOL_PROGRESS=true # Send progress messages +HERMES_TOOL_PROGRESS_MODE=new # "new" or "all" ``` +### Working Directory Behavior + +- **CLI (`hermes` command)**: Uses current directory (`.` → `os.getcwd()`) +- **Messaging (Telegram/Discord)**: Uses `MESSAGING_CWD` (default: home directory) + +This is intentional: CLI users are in a terminal and expect the agent to work in their current directory, while messaging users need a consistent starting location. + ### Security (User Allowlists): **IMPORTANT**: Without an allowlist, anyone who finds your bot can use it! @@ -208,6 +225,21 @@ Users can find their IDs: - **Telegram**: Message [@userinfobot](https://t.me/userinfobot) - **Discord**: Enable Developer Mode, right-click name → Copy ID +### Tool Progress Notifications + +When `HERMES_TOOL_PROGRESS=true`, the bot sends status messages as it works: +- `💻 \`ls -la\`...` (terminal commands show the actual command) +- `🔍 web_search...` +- `📄 web_extract...` + +Modes: +- `new`: Only when switching to a different tool (less spam) +- `all`: Every single tool call + +### Typing Indicator + +The gateway keeps the "typing..." indicator active throughout processing, refreshing every 4 seconds. This lets users know the bot is working even during long tool-calling sequences. + ### Platform Toolsets: Each platform has a dedicated toolset in `toolsets.py`: @@ -293,12 +325,18 @@ API keys are loaded from `~/.hermes/.env`: Terminal tool configuration (in `~/.hermes/config.yaml`): - `terminal.backend` - Backend: local, docker, singularity, modal, or ssh -- `terminal.cwd` - Working directory ("." = current directory) +- `terminal.cwd` - Working directory for CLI ("." = current directory) - `terminal.docker_image` - Image for Docker backend - `terminal.singularity_image` - Image for Singularity backend - `terminal.modal_image` - Image for Modal backend - SSH: `TERMINAL_SSH_HOST`, `TERMINAL_SSH_USER`, `TERMINAL_SSH_KEY` in .env +Agent behavior (in `~/.hermes/.env`): +- `HERMES_MAX_ITERATIONS` - Max tool-calling iterations (default: 60) +- `MESSAGING_CWD` - Working directory for messaging platforms (default: ~) +- `HERMES_TOOL_PROGRESS` - Enable tool progress messages (`true`/`false`) +- `HERMES_TOOL_PROGRESS_MODE` - Progress mode: `new` (tool changes) or `all` + ### Dangerous Command Approval The terminal tool includes safety checks for potentially destructive commands (e.g., `rm -rf`, `DROP TABLE`, `chmod 777`, etc.): diff --git a/README.md b/README.md index 047bec2e0..8a999cb1a 100644 --- a/README.md +++ b/README.md @@ -241,6 +241,33 @@ DISCORD_ALLOWED_USERS=123456789012345678 | `/new` or `/reset` | Start fresh conversation | | `/status` | Show session info | +#### Working Directory + +- **CLI (`hermes`)**: Uses current directory where you run the command +- **Messaging**: Uses `MESSAGING_CWD` (default: home directory `~`) + +```bash +# Set custom messaging working directory in ~/.hermes/.env +MESSAGING_CWD=/home/myuser/projects +``` + +#### Tool Progress Notifications + +Get real-time updates as the agent works: + +```bash +# Enable in ~/.hermes/.env +HERMES_TOOL_PROGRESS=true +HERMES_TOOL_PROGRESS_MODE=new # or "all" for every tool call +``` + +When enabled, you'll see messages like: +``` +💻 `ls -la`... +🔍 web_search... +📄 web_extract... +``` + See [docs/messaging.md](docs/messaging.md) for WhatsApp and advanced setup. ### ⏰ Scheduled Tasks (Cron) @@ -473,9 +500,19 @@ All variables go in `~/.hermes/.env`. Run `hermes config set VAR value` to set t | Variable | Description | |----------|-------------| | `TELEGRAM_BOT_TOKEN` | Telegram bot token (@BotFather) | +| `TELEGRAM_ALLOWED_USERS` | Comma-separated user IDs allowed to use bot | | `TELEGRAM_HOME_CHANNEL` | Default channel for cron delivery | | `DISCORD_BOT_TOKEN` | Discord bot token | +| `DISCORD_ALLOWED_USERS` | Comma-separated user IDs allowed to use bot | | `DISCORD_HOME_CHANNEL` | Default channel for cron delivery | +| `MESSAGING_CWD` | Working directory for terminal in messaging (default: ~) | + +**Agent Behavior:** +| Variable | Description | +|----------|-------------| +| `HERMES_MAX_ITERATIONS` | Max tool-calling iterations per conversation (default: 60) | +| `HERMES_TOOL_PROGRESS` | Send progress messages when using tools (`true`/`false`) | +| `HERMES_TOOL_PROGRESS_MODE` | `new` (only when tool changes) or `all` (every call) | **Context Compression:** | Variable | Description | diff --git a/docs/messaging.md b/docs/messaging.md index 5059401c2..fa3d447dd 100644 --- a/docs/messaging.md +++ b/docs/messaging.md @@ -164,7 +164,7 @@ There are **three ways** to configure the gateway (in order of precedence): ### 1. Environment Variables (`.env` file) - Recommended for Quick Setup -Add to your `.env` file in the project root: +Add to your `~/.hermes/.env` file: ```bash # ============================================================================= @@ -173,6 +173,7 @@ Add to your `.env` file in the project root: # Telegram - get from @BotFather on Telegram TELEGRAM_BOT_TOKEN=your_telegram_bot_token +TELEGRAM_ALLOWED_USERS=123456789,987654321 # Security: restrict to these user IDs # Optional: Default channel for cron job delivery TELEGRAM_HOME_CHANNEL=-1001234567890 @@ -180,6 +181,7 @@ TELEGRAM_HOME_CHANNEL_NAME="My Notes" # Discord - get from Discord Developer Portal DISCORD_BOT_TOKEN=your_discord_bot_token +DISCORD_ALLOWED_USERS=123456789012345678 # Security: restrict to these user IDs # Optional: Default channel for cron job delivery DISCORD_HOME_CHANNEL=123456789012345678 @@ -188,6 +190,26 @@ DISCORD_HOME_CHANNEL_NAME="#bot-updates" # WhatsApp - requires Node.js bridge setup WHATSAPP_ENABLED=true +# ============================================================================= +# AGENT SETTINGS +# ============================================================================= + +# Max tool-calling iterations per conversation (default: 60) +HERMES_MAX_ITERATIONS=60 + +# Working directory for terminal commands (default: home ~) +MESSAGING_CWD=/home/myuser + +# ============================================================================= +# TOOL PROGRESS NOTIFICATIONS +# ============================================================================= + +# Show progress messages as agent uses tools +HERMES_TOOL_PROGRESS=true + +# Mode: "new" (only when tool changes) or "all" (every tool call) +HERMES_TOOL_PROGRESS_MODE=new + # ============================================================================= # SESSION SETTINGS # ============================================================================= @@ -247,11 +269,43 @@ Each platform has its own toolset for security: | Platform | Toolset | Capabilities | |----------|---------|--------------| | CLI | `hermes-cli` | Full access (terminal, browser, etc.) | -| Telegram | `hermes-telegram` | Web, vision, skills, cronjobs | -| Discord | `hermes-discord` | Web search, vision, skills, cronjobs | -| WhatsApp | `hermes-whatsapp` | Web, terminal, vision, skills, cronjobs | +| Telegram | `hermes-telegram` | Full tools including terminal | +| Discord | `hermes-discord` | Full tools including terminal | +| WhatsApp | `hermes-whatsapp` | Full tools including terminal | -Discord has a more limited toolset because it often runs in public servers. +## User Experience Features + +### Typing Indicator + +The gateway keeps the "typing..." indicator active throughout processing, refreshing every 4 seconds. This lets users know the bot is working even during long tool-calling sequences. + +### Tool Progress Notifications + +When `HERMES_TOOL_PROGRESS=true`, the bot sends status messages as it works: + +``` +💻 `ls -la`... +🔍 web_search... +📄 web_extract... +🎨 image_generate... +``` + +Terminal commands show the actual command (truncated to 50 chars). Other tools just show the tool name. + +**Modes:** +- `new`: Only sends message when switching to a different tool (less spam) +- `all`: Sends message for every single tool call + +### Working Directory + +- **CLI (`hermes` command)**: Uses current directory where you run the command +- **Messaging**: Uses `MESSAGING_CWD` (default: home directory `~`) + +This is intentional: CLI users are in a terminal and expect the agent to work in their current directory, while messaging users need a consistent starting location. + +### Max Iterations + +If the agent hits the max iteration limit while working, instead of a generic error, it asks the model to summarize what it found so far. This gives you a useful response even when the task couldn't be fully completed. ## Cron Job Delivery