diff --git a/website/docs/developer-guide/agent-loop.md b/website/docs/developer-guide/agent-loop.md index b07fa04789..2d0df3278d 100644 --- a/website/docs/developer-guide/agent-loop.md +++ b/website/docs/developer-guide/agent-loop.md @@ -6,7 +6,7 @@ description: "Detailed walkthrough of AIAgent execution, API modes, tools, callb # Agent Loop Internals -The core orchestration engine is `run_agent.py`'s `AIAgent` class — roughly 9,200 lines that handle everything from prompt assembly to tool dispatch to provider failover. +The core orchestration engine is `run_agent.py`'s `AIAgent` class — roughly 10,700 lines that handle everything from prompt assembly to tool dispatch to provider failover. ## Core Responsibilities @@ -181,10 +181,7 @@ These tools modify agent state directly and return synthetic tool results withou The agent tracks iterations via `IterationBudget`: - Default: 90 iterations (configurable via `agent.max_turns`) -- Shared across parent and child agents — a subagent consumes from the parent's budget -- Two-tier budget pressure via `_get_budget_warning()`: - - At 70%+ usage (caution tier): appends `[BUDGET: Iteration X/Y. N iterations left. Start consolidating your work.]` to the last tool result - - At 90%+ usage (warning tier): appends `[BUDGET WARNING: Iteration X/Y. Only N iteration(s) left. Provide your final response NOW.]` +- Each agent gets its own budget. Subagents get independent budgets capped at `delegation.max_iterations` (default 50) — total iterations across parent + subagents can exceed the parent's cap - At 100%, the agent stops and returns a summary of work done ### Fallback Model @@ -224,7 +221,7 @@ After each turn: | File | Purpose | |------|---------| -| `run_agent.py` | AIAgent class — the complete agent loop (~9,200 lines) | +| `run_agent.py` | AIAgent class — the complete agent loop (~10,700 lines) | | `agent/prompt_builder.py` | System prompt assembly from memory, skills, context files, personality | | `agent/context_engine.py` | ContextEngine ABC — pluggable context management | | `agent/context_compressor.py` | Default engine — lossy summarization algorithm | diff --git a/website/docs/developer-guide/architecture.md b/website/docs/developer-guide/architecture.md index 53d8d72f7b..9e1d771ae3 100644 --- a/website/docs/developer-guide/architecture.md +++ b/website/docs/developer-guide/architecture.md @@ -32,8 +32,8 @@ This page is the top-level map of Hermes Agent internals. Use it to orient yours │ ┌──────┴───────┐ ┌──────┴───────┐ ┌──────┴───────┐ │ │ │ Compression │ │ 3 API Modes │ │ Tool Registry│ │ │ │ & Caching │ │ chat_compl. │ │ (registry.py)│ │ -│ │ │ │ codex_resp. │ │ 48 tools │ │ -│ │ │ │ anthropic │ │ 40 toolsets │ │ +│ │ │ │ codex_resp. │ │ 47 tools │ │ +│ │ │ │ anthropic │ │ 19 toolsets │ │ │ └──────────────┘ └──────────────┘ └──────────────┘ │ └─────────────────────────────────────────────────────────────────────┘ │ │ @@ -52,8 +52,8 @@ This page is the top-level map of Hermes Agent internals. Use it to orient yours ```text hermes-agent/ -├── run_agent.py # AIAgent — core conversation loop (~9,200 lines) -├── cli.py # HermesCLI — interactive terminal UI (~8,500 lines) +├── run_agent.py # AIAgent — core conversation loop (~10,700 lines) +├── cli.py # HermesCLI — interactive terminal UI (~10,000 lines) ├── model_tools.py # Tool discovery, schema collection, dispatch ├── toolsets.py # Tool groupings and platform presets ├── hermes_state.py # SQLite session/state database with FTS5 @@ -76,7 +76,7 @@ hermes-agent/ │ └── trajectory.py # Trajectory saving helpers │ ├── hermes_cli/ # CLI subcommands and setup -│ ├── main.py # Entry point — all `hermes` subcommands (~5,500 lines) +│ ├── main.py # Entry point — all `hermes` subcommands (~6,000 lines) │ ├── config.py # DEFAULT_CONFIG, OPTIONAL_ENV_VARS, migration │ ├── commands.py # COMMAND_REGISTRY — central slash command definitions │ ├── auth.py # PROVIDER_REGISTRY, credential resolution @@ -99,7 +99,7 @@ hermes-agent/ │ ├── process_registry.py # Background process management │ ├── file_tools.py # read_file, write_file, patch, search_files │ ├── web_tools.py # web_search, web_extract -│ ├── browser_tool.py # 11 browser automation tools +│ ├── browser_tool.py # 10 browser automation tools │ ├── code_execution_tool.py # execute_code sandbox │ ├── delegate_tool.py # Subagent delegation │ ├── mcp_tool.py # MCP client (~2,200 lines) @@ -109,7 +109,7 @@ hermes-agent/ │ └── environments/ # Terminal backends (local, docker, ssh, modal, daytona, singularity) │ ├── gateway/ # Messaging platform gateway -│ ├── run.py # GatewayRunner — message dispatch (~7,500 lines) +│ ├── run.py # GatewayRunner — message dispatch (~9,000 lines) │ ├── session.py # SessionStore — conversation persistence │ ├── delivery.py # Outbound message delivery │ ├── pairing.py # DM pairing authorization @@ -117,9 +117,10 @@ hermes-agent/ │ ├── mirror.py # Cross-session message mirroring │ ├── status.py # Token locks, profile-scoped process tracking │ ├── builtin_hooks/ # Always-registered hooks -│ └── platforms/ # 15 adapters: telegram, discord, slack, whatsapp, +│ └── platforms/ # 18 adapters: telegram, discord, slack, whatsapp, │ # signal, matrix, mattermost, email, sms, -│ # dingtalk, feishu, wecom, weixin, bluebubbles, homeassistant, webhook +│ # dingtalk, feishu, wecom, wecom_callback, weixin, +│ # bluebubbles, homeassistant, webhook, api_server │ ├── acp_adapter/ # ACP server (VS Code / Zed / JetBrains) ├── cron/ # Scheduler (jobs.py, scheduler.py) @@ -211,7 +212,7 @@ A shared runtime resolver used by CLI, gateway, cron, ACP, and auxiliary calls. ### Tool System -Central tool registry (`tools/registry.py`) with 47 registered tools across 20 toolsets. Each tool file self-registers at import time. The registry handles schema collection, dispatch, availability checking, and error wrapping. Terminal tools support 6 backends (local, Docker, SSH, Daytona, Modal, Singularity). +Central tool registry (`tools/registry.py`) with 47 registered tools across 19 toolsets. Each tool file self-registers at import time. The registry handles schema collection, dispatch, availability checking, and error wrapping. Terminal tools support 6 backends (local, Docker, SSH, Daytona, Modal, Singularity). → [Tools Runtime](./tools-runtime.md) @@ -223,7 +224,7 @@ SQLite-based session storage with FTS5 full-text search. Sessions have lineage t ### Messaging Gateway -Long-running process with 14 platform adapters, unified session routing, user authorization (allowlists + DM pairing), slash command dispatch, hook system, cron ticking, and background maintenance. +Long-running process with 18 platform adapters, unified session routing, user authorization (allowlists + DM pairing), slash command dispatch, hook system, cron ticking, and background maintenance. → [Gateway Internals](./gateway-internals.md) diff --git a/website/docs/developer-guide/context-compression-and-caching.md b/website/docs/developer-guide/context-compression-and-caching.md index c500612f65..29008ebb7d 100644 --- a/website/docs/developer-guide/context-compression-and-caching.md +++ b/website/docs/developer-guide/context-compression-and-caching.md @@ -53,7 +53,7 @@ Hermes has two separate compression layers that operate independently: ### 1. Gateway Session Hygiene (85% threshold) -Located in `gateway/run.py` (search for `_maybe_compress_session`). This is a **safety net** that +Located in `gateway/run.py` (search for `Session hygiene: auto-compress`). This is a **safety net** that runs before the agent processes a message. It prevents API failures when sessions grow too large between turns (e.g., overnight accumulation in Telegram/Discord). diff --git a/website/docs/developer-guide/cron-internals.md b/website/docs/developer-guide/cron-internals.md index 5eddcb7e8e..5d1cdc39c9 100644 --- a/website/docs/developer-guide/cron-internals.md +++ b/website/docs/developer-guide/cron-internals.md @@ -37,16 +37,25 @@ Jobs are stored in `~/.hermes/cron/jobs.json` with atomic write semantics (write ```json { - "id": "job_abc123", + "id": "a1b2c3d4e5f6", "name": "Daily briefing", "prompt": "Summarize today's AI news and funding rounds", - "schedule": "0 9 * * *", + "schedule": { + "kind": "cron", + "expr": "0 9 * * *", + "display": "0 9 * * *" + }, "skills": ["ai-funding-daily-report"], "deliver": "telegram:-1001234567890", - "repeat": null, + "repeat": { + "times": null, + "completed": 42 + }, "state": "scheduled", - "next_run": "2025-01-16T09:00:00Z", - "run_count": 42, + "enabled": true, + "next_run_at": "2025-01-16T09:00:00Z", + "last_run_at": "2025-01-15T09:00:00Z", + "last_status": "ok", "created_at": "2025-01-01T00:00:00Z", "model": null, "provider": null, diff --git a/website/docs/developer-guide/gateway-internals.md b/website/docs/developer-guide/gateway-internals.md index 0d97f13226..997930c0a4 100644 --- a/website/docs/developer-guide/gateway-internals.md +++ b/website/docs/developer-guide/gateway-internals.md @@ -12,7 +12,7 @@ The messaging gateway is the long-running process that connects Hermes to 14+ ex | File | Purpose | |------|---------| -| `gateway/run.py` | `GatewayRunner` — main loop, slash commands, message dispatch (~7,500 lines) | +| `gateway/run.py` | `GatewayRunner` — main loop, slash commands, message dispatch (~9,000 lines) | | `gateway/session.py` | `SessionStore` — conversation persistence and session key construction | | `gateway/delivery.py` | Outbound message delivery to target platforms/channels | | `gateway/pairing.py` | DM pairing flow for user authorization | diff --git a/website/docs/getting-started/installation.md b/website/docs/getting-started/installation.md index 5bdb6809e7..a28b1256e6 100644 --- a/website/docs/getting-started/installation.md +++ b/website/docs/getting-started/installation.md @@ -135,7 +135,7 @@ uv pip install -e "." | Extra | What it adds | Install command | |-------|-------------|-----------------| | `all` | Everything below | `uv pip install -e ".[all]"` | -| `messaging` | Telegram & Discord gateway | `uv pip install -e ".[messaging]"` | +| `messaging` | Telegram, Discord & Slack gateway | `uv pip install -e ".[messaging]"` | | `cron` | Cron expression parsing for scheduled tasks | `uv pip install -e ".[cron]"` | | `cli` | Terminal menu UI for setup wizard | `uv pip install -e ".[cli]"` | | `modal` | Modal cloud execution backend | `uv pip install -e ".[modal]"` | diff --git a/website/docs/getting-started/quickstart.md b/website/docs/getting-started/quickstart.md index 9646fbcc9f..c16aa30787 100644 --- a/website/docs/getting-started/quickstart.md +++ b/website/docs/getting-started/quickstart.md @@ -152,9 +152,7 @@ Want microphone input in the CLI or spoken replies in messaging? ```bash pip install "hermes-agent[voice]" - -# Optional but recommended for free local speech-to-text -pip install faster-whisper +# Includes faster-whisper for free local speech-to-text ``` Then start Hermes and enable it inside the CLI: diff --git a/website/docs/guides/automate-with-cron.md b/website/docs/guides/automate-with-cron.md index fba8a08284..b35897e897 100644 --- a/website/docs/guides/automate-with-cron.md +++ b/website/docs/guides/automate-with-cron.md @@ -254,7 +254,7 @@ The `--deliver` flag controls where results go: **Test with `/cron run`.** Before waiting for the schedule to trigger, use `/cron run ` to execute immediately and verify the output looks right. -**Schedule expressions.** Human-readable formats like `every 2h`, `30m`, and `daily at 9am` all work alongside standard cron expressions like `0 9 * * *`. +**Schedule expressions.** Supported formats: relative delays (`30m`), intervals (`every 2h`), standard cron expressions (`0 9 * * *`), and ISO timestamps (`2025-06-15T09:00:00`). Natural language like `daily at 9am` is not supported — use `0 9 * * *` instead. --- diff --git a/website/docs/guides/delegation-patterns.md b/website/docs/guides/delegation-patterns.md index e2eaa05cb7..4de7ebbd9e 100644 --- a/website/docs/guides/delegation-patterns.md +++ b/website/docs/guides/delegation-patterns.md @@ -216,7 +216,7 @@ Restricting toolsets keeps the subagent focused and prevents accidental side eff ## Constraints -- **Max 3 parallel tasks** — batches are capped at 3 concurrent subagents +- **Default 3 parallel tasks** — batches default to 3 concurrent subagents (configurable via `delegation.max_concurrent_children` in config.yaml) - **No nesting** — subagents cannot call `delegate_task`, `clarify`, `memory`, `send_message`, or `execute_code` - **Separate terminals** — each subagent gets its own terminal session with separate working directory and state - **No conversation history** — subagents see only what you put in `goal` and `context` diff --git a/website/docs/reference/cli-commands.md b/website/docs/reference/cli-commands.md index 95416d2127..a4b589379b 100644 --- a/website/docs/reference/cli-commands.md +++ b/website/docs/reference/cli-commands.md @@ -60,7 +60,10 @@ hermes [global-options] [subcommand/options] | `hermes sessions` | Browse, export, prune, rename, and delete sessions. | | `hermes insights` | Show token/cost/activity analytics. | | `hermes claw` | OpenClaw migration helpers. | -| `hermes web` | Launch the web dashboard for managing config, API keys, and sessions. | +| `hermes dashboard` | Launch the web dashboard for managing config, API keys, and sessions. | +| `hermes debug` | Debug tools — upload logs and system info for support. | +| `hermes backup` | Back up Hermes home directory to a zip file. | +| `hermes import` | Restore a Hermes backup from a zip file. | | `hermes profile` | Manage profiles — multiple isolated Hermes instances. | | `hermes completion` | Print shell completion scripts (bash/zsh). | | `hermes version` | Show version information. | @@ -80,10 +83,11 @@ Common options: | `-q`, `--query "..."` | One-shot, non-interactive prompt. | | `-m`, `--model ` | Override the model for this run. | | `-t`, `--toolsets ` | Enable a comma-separated set of toolsets. | -| `--provider ` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot-acp`, `copilot`, `anthropic`, `huggingface`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `deepseek`, `ai-gateway`, `opencode-zen`, `opencode-go`, `kilocode`, `xiaomi`, `alibaba`. | +| `--provider ` | Force a provider: `auto`, `openrouter`, `nous`, `openai-codex`, `copilot-acp`, `copilot`, `anthropic`, `gemini`, `huggingface`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`, `xiaomi`. | | `-s`, `--skills ` | Preload one or more skills for the session (can be repeated or comma-separated). | | `-v`, `--verbose` | Verbose output. | | `-Q`, `--quiet` | Programmatic mode: suppress banner/spinner/tool previews. | +| `--image ` | Attach a local image to a single query. | | `--resume ` / `--continue [name]` | Resume a session directly from `chat`. | | `--worktree` | Create an isolated git worktree for this run. | | `--checkpoints` | Enable filesystem checkpoints before destructive file changes. | @@ -160,7 +164,7 @@ Use `hermes gateway run` instead of `hermes gateway start` — WSL's systemd sup ## `hermes setup` ```bash -hermes setup [model|terminal|gateway|tools|agent] [--non-interactive] [--reset] +hermes setup [model|tts|terminal|gateway|tools|agent] [--non-interactive] [--reset] ``` Use the full wizard or jump into one section: @@ -448,6 +452,7 @@ View, tail, and filter Hermes log files. All logs are stored in `~/.hermes/logs/ | `--level ` | Minimum log level to show: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL`. | | `--session ` | Filter lines containing a session ID substring. | | `--since