docs: sync root docs, CONTRIBUTING tree, docs/*.md,
windows-quirks with the facade/siblings layout (#102117)
This commit is contained in:
Teknium
@@ -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/<category>/<skill>`. 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`.
|
||||
|
||||
+17
-8
@@ -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
|
||||
│
|
||||
|
||||
@@ -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`).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user