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.
2026-02-03 14:57:27 -08:00
parent e7f0ffbf5d
commit 9d9eea9ac9
3 changed files with 136 additions and 7 deletions
--- 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.):
--- 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 |
--- 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