diff --git a/AGENTS.md b/AGENTS.md index e8cb473c6d..32d03139d7 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -640,7 +640,7 @@ The registry handles schema collection, dispatch, availability checking, and err **State files**: If a tool stores persistent state (caches, logs, checkpoints), use `get_hermes_home()` for the base directory — never `Path.home() / ".hermes"`. This ensures each profile gets its own state. -**Agent-level tools** (todo, memory): intercepted by `run_agent.py` before `handle_function_call()`. See `tools/todo_tool.py` for the pattern. +**Agent-level tools** (todo, memory): intercepted by `agent/tool_executor.py` (via the `INLINE_TOOL_EXECUTORS` table in `agent/inline_tool_executors.py`) before `handle_function_call()`. See `tools/todo_tool.py` for the pattern. --- @@ -687,7 +687,7 @@ Reference: #2810 (bounds pass), #9801 (SHA pinning + audit CI). `auxiliary` holds per-task overrides for side-LLM work (curator, vision, embedding, title generation, session_search, etc.) — each task can pin its own provider/model/base_url/max_tokens/reasoning_effort. See -`agent/auxiliary_client.py::_resolve_auto` for resolution order. +`agent/auxiliary_client.py::_resolve_auto_route` for resolution order. `curator` holds the background skill-maintenance config — `enabled`, `interval_hours`, `min_idle_hours`, `stale_after_days`, @@ -1046,7 +1046,7 @@ Two parallel surfaces: - **`optional-skills/`** — heavier or niche skills shipped with the repo but NOT active by default. Installed explicitly via `hermes skills install official//`. Adapter lives in - `tools/skills_hub.py` (`OptionalSkillSource`). Categories include + `tools/skills_hub_official.py` (`OptionalSkillSource`). Categories include `autonomous-ai-agents`, `blockchain`, `communication`, `creative`, `devops`, `email`, `health`, `mcp`, `migration`, `mlops`, `productivity`, `research`, `security`, `web-development`. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 61bacafbd8..9ea20cbf6e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -216,14 +216,17 @@ pytest tests/ -v ``` hermes-agent/ -├── run_agent.py # AIAgent class — core conversation loop, tool dispatch, session persistence -├── cli.py # HermesCLI class — interactive TUI, prompt_toolkit integration +├── run_agent.py # AIAgent facade (~1.5k LOC) — the turn loop lives in agent/conversation_loop.py + agent/turn_*.py +├── cli.py # HermesCLI class — interactive CLI orchestrator (~4.6k LOC + hermes_cli/cli_*_mixin.py) ├── model_tools.py # Tool orchestration (thin layer over tools/registry.py) ├── toolsets.py # Tool groupings and presets (hermes-cli, hermes-telegram, etc.) -├── hermes_state.py # SQLite session database with FTS5 full-text search, session titles +├── hermes_state.py # SessionDB facade (~1.4k LOC); implementation in hermes_state_*.py (21 siblings) — FTS5 search, session titles ├── batch_runner.py # Parallel batch processing for trajectory generation │ ├── agent/ # Agent internals (extracted modules) +│ ├── conversation_loop.py # run_conversation() — the agent turn loop (phases in turn_*.py) +│ ├── tool_executor.py # Tool dispatch (inline agent-level tools, delegate, registry) +│ ├── session_persistence.py # Session/trajectory saving │ ├── prompt_builder.py # System prompt assembly (identity, skills, context files, memory) │ ├── context_compressor.py # Auto-summarization when approaching context limits │ ├── auxiliary_client.py # Resolves auxiliary OpenAI clients (summarization, vision) @@ -233,16 +236,19 @@ hermes-agent/ │ ├── hermes_cli/ # CLI command implementations │ ├── main.py # Entry point, argument parsing, command dispatch +│ ├── cli_*_mixin.py # HermesCLI mixins (slash commands, display, session, ...) │ ├── config.py # Config management, migration, env var definitions │ ├── setup.py # Interactive setup wizard -│ ├── auth.py # Provider resolution, OAuth, Nous Portal +│ ├── auth.py # Provider resolution, OAuth, Nous Portal (facade + auth_*.py siblings) │ ├── models.py # OpenRouter model selection lists │ ├── banner.py # Welcome banner, ASCII art │ ├── commands.py # Central slash command registry (CommandDef), autocomplete, gateway helpers │ ├── callbacks.py # Interactive callbacks (clarify, sudo, approval) │ ├── doctor.py # Diagnostics │ ├── skills_hub.py # Skills Hub CLI + /skills slash command -│ └── skin_engine.py # Skin/theme engine — data-driven CLI visual customization +│ ├── skin_engine.py # Skin/theme engine — data-driven CLI visual customization +│ ├── web_server.py # Dashboard server (facade + web_server_*.py siblings) +│ └── web_routers/ # Dashboard FastAPI routers (one file per surface) │ ├── tools/ # Tool implementations (self-registering) │ ├── registry.py # Central tool registry (schemas, handlers, dispatch) @@ -252,7 +258,9 @@ hermes-agent/ │ ├── web_tools.py # web_search, web_extract (Parallel/Firecrawl + Gemini summarization) │ ├── vision_tools.py # Image analysis via multimodal models │ ├── delegate_tool.py # Subagent spawning and parallel task execution -│ ├── code_execution_tool.py # Sandboxed Python with RPC tool access +│ ├── code_execution_tool.py # Sandboxed Python with RPC tool access (env allowlists in code_execution_env.py) +│ ├── mcp_tool.py # MCP client (facade + mcp_tool_*.py siblings: config, discovery, transport, ...) +│ ├── browser_tool.py # Browser automation (facade + browser_tool_*.py siblings) │ ├── session_search_tool.py # Search past conversations with FTS5 + anchored windows │ ├── cronjob_tools.py # Scheduled task management │ ├── skill_tools.py # Skill search, load, manage @@ -261,9 +269,10 @@ hermes-agent/ │ ├── local.py, docker.py, ssh.py, singularity.py, modal.py, daytona.py │ ├── gateway/ # Messaging gateway -│ ├── run.py # GatewayRunner — platform lifecycle, message routing, cron +│ ├── run.py # GatewayRunner facade (~5.5k LOC); phases in run_*.py (startup, inbound, turn, busy, ...) +│ ├── slash_commands_*.py # Gateway slash command handler mixins │ ├── config.py # Platform configuration resolution -│ ├── session.py # Session store, context prompts, reset policies +│ ├── session.py # Session store, context prompts, reset policies (+ session_*.py siblings) │ └── platforms/ # Platform adapters │ ├── telegram.py, discord_adapter.py, slack.py, whatsapp.py │ diff --git a/docs/session-lifecycle.md b/docs/session-lifecycle.md index c3bff2b59b..7bedee9232 100644 --- a/docs/session-lifecycle.md +++ b/docs/session-lifecycle.md @@ -1,7 +1,7 @@ # Session Lifecycle > **Audience:** Gateway developers and maintainers -> **Source files:** `gateway/session.py` (~1444 lines), `gateway/run.py` (~16800 lines), `gateway/config.py` +> **Source files:** `gateway/session.py` (~1200 lines + `session_*.py` siblings), `gateway/run.py` (~5500 lines facade + `run_*.py` phases), `gateway/config.py` > **Last updated:** 2026-06-16 ## Overview @@ -14,9 +14,10 @@ The session system lives primarily in two modules: - `gateway/session.py` — Data model (`SessionSource`, `SessionEntry`, `SessionContext`), key generation (`build_session_key`), and the main store (`SessionStore`). -- `gateway/run.py` — Gateway runner (`GatewayRunner`) that wires sessions into the message - processing pipeline: session expiry watching, agent caching, restart recovery, and message - queuing. +- `gateway/run.py` — Gateway runner (`GatewayRunner`) facade that wires sessions into the message + processing pipeline; the phases live in `run_*.py` siblings: session expiry watching + (`run_watchers.py`), agent caching (`run_agent_cache.py`), restart recovery + (`session_recovery.py`), and message queuing (`run_busy.py`). --- diff --git a/docs/streaming-tts.md b/docs/streaming-tts.md index 297a524d07..1db2c812a6 100644 --- a/docs/streaming-tts.md +++ b/docs/streaming-tts.md @@ -18,7 +18,7 @@ The streaming pipeline has four parts: 3. **TTS provider** — a registered `StreamingTTSProvider` turns each sentence into raw PCM chunks (int16 mono at the provider's declared `sample_rate`) 4. **Audio sink** — `sounddevice.OutputStream` for local playback - (`tools.tts_tool.stream_tts_to_speaker`), or a gateway platform adapter's + (`tools.tts_tool_speaker.stream_tts_to_speaker`), or a gateway platform adapter's `write_streaming_tts` seam (`gateway/streaming_tts_consumer.py`) Providers with no chunked API still get per-*sentence* playback via the proven diff --git a/skills/autonomous-ai-agents/hermes-agent/references/windows-quirks.md b/skills/autonomous-ai-agents/hermes-agent/references/windows-quirks.md index d87f1c0eb5..fbd3711b3e 100644 --- a/skills/autonomous-ai-agents/hermes-agent/references/windows-quirks.md +++ b/skills/autonomous-ai-agents/hermes-agent/references/windows-quirks.md @@ -26,7 +26,7 @@ a UTF-8 BOM (Notepad does this). Re-save as UTF-8 without BOM; `AF_INET` socket. Root cause is usually Hermes's env scrubber dropping `SYSTEMROOT`/`WINDIR`/`COMSPEC` (Python's `socket` needs `SYSTEMROOT` to find `mswsock.dll`), not a broken Winsock LSP. The `_WINDOWS_ESSENTIAL_ENV_VARS` -allowlist in `tools/code_execution_tool.py` covers it; if you still hit it, +allowlist in `tools/code_execution_env.py` covers it; if you still hit it, echo `os.environ` inside an `execute_code` block to confirm `SYSTEMROOT` is set. ### Testing on Windows