SaylorTwift HF Staff commited on
Commit
e9c4f85
·
verified ·
1 Parent(s): a200053

Add files using upload-large-folder tool

Browse files
This view is limited to 50 files because it contains too many changes.   See raw diff
Files changed (50) hide show
  1. .coderabbit.yaml +18 -0
  2. .dockerignore +114 -0
  3. .env.example +544 -0
  4. .gitattributes +34 -35
  5. .gitignore +280 -0
  6. .mailmap +109 -0
  7. .npmrc +63 -0
  8. .nvmrc +1 -0
  9. .prettierignore +4 -0
  10. .prettierrc +11 -0
  11. .python-version +1 -0
  12. AGENTS.md +432 -0
  13. COMPAT_MANIFEST.md +0 -0
  14. CONTRIBUTING.es.md +602 -0
  15. CONTRIBUTING.md +1002 -0
  16. README.md +276 -0
  17. README.zh-CN.md +208 -0
  18. SECURITY.es.md +326 -0
  19. SECURITY.md +335 -0
  20. SOUL.md +1 -0
  21. cli.py +0 -0
  22. compat_manifest.json +0 -0
  23. docker-compose.yml +76 -0
  24. eslint.config.shared.mjs +106 -0
  25. evals/__init__.py +0 -0
  26. evals/acp_empty_session_wire.py +153 -0
  27. evals/anthropic_proxy_thinking_replay.py +103 -0
  28. evals/api_delegation_http_probe.py +102 -0
  29. evals/api_delegation_sync_probe.py +66 -0
  30. evals/approval_deny_dispatch.py +80 -0
  31. evals/auth_pool_controls.py +153 -0
  32. evals/auxiliary_resource_exhausted.py +110 -0
  33. evals/cli_deferred_notice.py +129 -0
  34. evals/cli_fallback_add_picker_error.py +135 -0
  35. evals/codex_masked_replay_review.py +138 -0
  36. evals/completion_backlog_probe.py +195 -0
  37. evals/cron_error_diagnostics.py +85 -0
  38. evals/cron_timeout_fork_race.py +93 -0
  39. evals/delivery_flood_wire.py +201 -0
  40. evals/desktop-reap-clock-pressure.cjs +12 -0
  41. evals/fanout_resource_bench.py +232 -0
  42. evals/gemini_type_array_probe.py +120 -0
  43. evals/goal_command_parity.py +51 -0
  44. evals/heartbeat_idle_wire.py +151 -0
  45. evals/kanban_graph_identity.py +86 -0
  46. evals/kanban_pr_acceptance_live.py +67 -0
  47. evals/kanban_scope_probe.py +60 -0
  48. evals/key_cmd_picker_live.py +182 -0
  49. evals/mcp_device_flow.py +172 -0
  50. evals/output_caps_local_capture.py +116 -0
.coderabbit.yaml ADDED
@@ -0,0 +1,18 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # CodeRabbit configuration.
2
+ #
3
+ # Auto-review is DISABLED repo-wide: the app was enabled at the org level on
4
+ # 2026-08-14 and immediately began reviewing every opened PR. This repo's
5
+ # merge gate is CI ("All required checks pass") plus maintainer review —
6
+ # CodeRabbit reviews carry no merge weight (protect-main ruleset requires
7
+ # 0 approving reviews), so auto-firing on the full PR firehose adds comment
8
+ # noise without gating value.
9
+ #
10
+ # The bot stays installed and summonable on demand: comment
11
+ # `@coderabbitai review` on any PR to request a one-off review, or
12
+ # `@coderabbitai ignore` to mute it on a PR it has already joined.
13
+ #
14
+ # To re-enable auto-review, flip `enabled: true` below (or delete this file —
15
+ # the app default is on).
16
+ reviews:
17
+ auto_review:
18
+ enabled: false
.dockerignore ADDED
@@ -0,0 +1,114 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Git
2
+ .git
3
+ .gitignore
4
+ .gitmodules
5
+
6
+ # Python
7
+ __pycache__
8
+ *.py[cod]
9
+ *$py.class
10
+ *.so
11
+ .Python
12
+ *.egg-info/
13
+ dist/
14
+ build/
15
+
16
+ # Virtual environments
17
+ venv/
18
+ env/
19
+ ENV/
20
+
21
+ # Dependencies
22
+ node_modules
23
+ **/node_modules
24
+ .venv
25
+ **/.venv
26
+ .notebooklm-cli-venv/
27
+ .notebooklm-playwright/
28
+ .pip-cache/
29
+ .uv-cache/
30
+
31
+ # Built artifacts that are regenerated inside the image. Excluded so local
32
+ # rebuilds on the developer's machine don't invalidate the npm-install layer
33
+ # that now depends on the full ui-tui/packages/hermes-ink/ tree being present.
34
+ ui-tui/dist/
35
+ ui-tui/packages/hermes-ink/dist/
36
+
37
+ # CI/CD
38
+ .github
39
+
40
+ # Environment files
41
+ .env
42
+ .env.*
43
+ # ...but keep the template: docker/stage2-hook.sh seeds $HERMES_HOME/.env from
44
+ # /opt/hermes/.env.example on first boot (OOF-285 — excluding it silently broke
45
+ # first-boot .env seeding and the API_SERVER_KEY generation that depends on it).
46
+ !.env.example
47
+
48
+ # IDE
49
+ .vscode/
50
+ .idea/
51
+ *.swp
52
+ *.swo
53
+
54
+ # Testing
55
+ .pytest_cache/
56
+ .coverage
57
+ htmlcov/
58
+
59
+ # Documentation
60
+ *.md
61
+
62
+ # Runtime data (bind-mounted at /opt/data; must not leak into build context)
63
+ data/
64
+ .hermes-docker/
65
+ .notebooklm-home/
66
+
67
+ # Compose/profile runtime state (bind-mounted; avoid ownership/secret issues)
68
+ hermes-config/
69
+ runtime/
70
+
71
+ # ---------- Not needed inside the Docker image ----------
72
+
73
+ # Desktop app source (Tauri/Electron); never installed in the container.
74
+ # apps/shared is the dashboard↔desktop websocket helper and is linked from
75
+ # web/package.json as a file: workspace dep — keep it in the build context.
76
+ apps/
77
+ !apps/shared/
78
+ !apps/shared/**
79
+
80
+ # Test suite — not shipped in production images
81
+ tests/
82
+
83
+ # Documentation site (Docusaurus)
84
+ website/
85
+
86
+ # Assets only used by the GitHub README
87
+ assets/
88
+ infographic/
89
+
90
+ # Plugin-level docs (hermes-achievements ships docs/ but the runtime doesn't read them)
91
+ plugins/hermes-achievements/docs/
92
+
93
+ # Nix / Homebrew / AUR packaging metadata — irrelevant to Docker
94
+ nix/
95
+ flake.nix
96
+ flake.lock
97
+ packaging/
98
+
99
+ # Design and planning documents
100
+ plans/
101
+ .plans/
102
+
103
+ # Repo-level dotfiles that are git-only or dev-tooling config
104
+ .envrc
105
+ .gitattributes
106
+ .hadolint.yaml
107
+ .mailmap
108
+
109
+ # Debug/export artifacts — must never reach image layers (COPY . .)
110
+ /log.txt
111
+ /sqlite_leak_fix.png
112
+ /*.png.bak
113
+ *.tar.gz
114
+ *.tgz
.env.example ADDED
@@ -0,0 +1,544 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Hermes Agent Environment Configuration
2
+ # Copy this file to .env and fill in your API keys
3
+
4
+ # =============================================================================
5
+ # LLM PROVIDER (Fireworks AI)
6
+ # =============================================================================
7
+ # Get your key at: https://app.fireworks.ai/settings/users/api-keys
8
+ # Address models directly by catalog ID, e.g.
9
+ # accounts/fireworks/models/kimi-k2p6, accounts/fireworks/models/glm-5p2
10
+ # FIREWORKS_API_KEY=
11
+ # =============================================================================
12
+ # LLM PROVIDER (OpenRouter)
13
+ # =============================================================================
14
+ # OpenRouter provides access to many models through one API
15
+ # All LLM calls go through OpenRouter - no direct provider keys needed
16
+ # Get your key at: https://openrouter.ai/keys
17
+ # OPENROUTER_API_KEY=
18
+
19
+ # Default model is configured in ~/.hermes/config.yaml (model.default).
20
+ # Use 'hermes model' or 'hermes setup' to change it.
21
+ # LLM_MODEL is no longer read from .env — this line is kept for reference only.
22
+ # LLM_MODEL=anthropic/claude-opus-4.6
23
+
24
+ # =============================================================================
25
+ # LLM PROVIDER (NovitaAI)
26
+ # =============================================================================
27
+ # NovitaAI — 90+ models, pay-per-use
28
+ # Get your key at: https://novita.ai/settings/key-management
29
+ # NOVITA_API_KEY=
30
+ # NOVITA_BASE_URL=https://api.novita.ai/openai/v1 # Override default base URL
31
+
32
+ # =============================================================================
33
+ # LLM PROVIDER (Google AI Studio / Gemini)
34
+ # =============================================================================
35
+ # Native Gemini API via Google's OpenAI-compatible endpoint.
36
+ # Get your key at: https://aistudio.google.com/app/apikey
37
+ # GOOGLE_API_KEY=your_google_ai_studio_key_here
38
+ # GEMINI_API_KEY=your_gemini_key_here # alias for GOOGLE_API_KEY
39
+ # Optional base URL override (default: Google's OpenAI-compatible endpoint)
40
+ # GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai
41
+
42
+ # =============================================================================
43
+ # LLM PROVIDER (Ollama Cloud)
44
+ # =============================================================================
45
+ # Cloud-hosted open models via Ollama's OpenAI-compatible endpoint.
46
+ # Get your key at: https://ollama.com/settings
47
+ # OLLAMA_API_KEY=your_ollama_key_here
48
+ # Optional base URL override (default: https://ollama.com/v1)
49
+ # OLLAMA_BASE_URL=https://ollama.com/v1
50
+
51
+ # =============================================================================
52
+ # LLM PROVIDER (z.ai / GLM)
53
+ # =============================================================================
54
+ # z.ai provides access to ZhipuAI GLM models (GLM-4-Plus, etc.)
55
+ # Get your key at: https://z.ai or https://open.bigmodel.cn
56
+ # GLM_API_KEY=
57
+ # GLM_BASE_URL=https://api.z.ai/api/paas/v4 # Override default base URL
58
+
59
+ # =============================================================================
60
+ # LLM PROVIDER (Kimi / Moonshot)
61
+ # =============================================================================
62
+ # Kimi Code provides access to Moonshot AI coding models (kimi-k2.5, etc.)
63
+ # Get your key at: https://platform.kimi.ai (Kimi Code console)
64
+ # Keys prefixed sk-kimi- use the Kimi Code API (api.kimi.com) by default.
65
+ # Legacy keys from platform.moonshot.ai need KIMI_BASE_URL override below.
66
+ # KIMI_API_KEY=
67
+ # KIMI_BASE_URL=https://api.kimi.com/coding/v1 # Default for sk-kimi- keys
68
+ # KIMI_BASE_URL=https://api.moonshot.ai/v1 # For legacy Moonshot keys
69
+ # KIMI_BASE_URL=https://api.moonshot.cn/v1 # For Moonshot China keys
70
+ # KIMI_CN_API_KEY= # Dedicated Moonshot China key
71
+
72
+ # =============================================================================
73
+ # LLM PROVIDER (Arcee AI)
74
+ # =============================================================================
75
+ # Arcee AI provides access to Trinity models (trinity-mini, trinity-large-*)
76
+ # Get an Arcee key at: https://chat.arcee.ai/
77
+ # ARCEEAI_API_KEY=
78
+ # ARCEE_BASE_URL= # Override default base URL
79
+
80
+ # =============================================================================
81
+ # LLM PROVIDER (MiniMax)
82
+ # =============================================================================
83
+ # MiniMax provides access to MiniMax models (global endpoint)
84
+ # Get your key at: https://www.minimax.io
85
+ # MINIMAX_API_KEY=
86
+ # MINIMAX_BASE_URL=https://api.minimax.io/v1 # Override default base URL
87
+
88
+ # MiniMax China endpoint (for users in mainland China)
89
+ # MINIMAX_CN_API_KEY=
90
+ # MINIMAX_CN_BASE_URL=https://api.minimaxi.com/v1 # Override default base URL
91
+
92
+ # =============================================================================
93
+ # LLM PROVIDER (OpenCode Zen)
94
+ # =============================================================================
95
+ # OpenCode Zen provides curated, tested models (GPT, Claude, Gemini, MiniMax, GLM, Kimi)
96
+ # Pay-as-you-go pricing. Get your key at: https://opencode.ai/auth
97
+ # OPENCODE_ZEN_API_KEY=
98
+ # OPENCODE_ZEN_BASE_URL=https://opencode.ai/zen/v1 # Override default base URL
99
+
100
+ # =============================================================================
101
+ # LLM PROVIDER (OpenCode Go)
102
+ # =============================================================================
103
+ # OpenCode Go provides access to open models (GLM-5, Kimi K2.5, MiniMax M2.5)
104
+ # $10/month subscription. Get your key at: https://opencode.ai/auth
105
+ # OPENCODE_GO_API_KEY=
106
+
107
+ # =============================================================================
108
+ # LLM PROVIDER (OpenCode Free)
109
+ # =============================================================================
110
+ # OpenCode Free provides keyless free models (Ox Alpha / x-preview-f-free,
111
+ # big-pickle, etc.). NO env var and NO account needed — requests are sent
112
+ # anonymously (the free tier rejects any unrecognized Authorization header).
113
+ # Select it with `hermes model` or `/model free`.
114
+
115
+ # =============================================================================
116
+ # LLM PROVIDER (Hugging Face Inference Providers)
117
+ # =============================================================================
118
+ # Hugging Face routes to 20+ open models via unified OpenAI-compatible endpoint.
119
+ # Free tier included ($0.10/month), no markup on provider rates.
120
+ # Get your token at: https://huggingface.co/settings/tokens
121
+ # Required permission: "Make calls to Inference Providers"
122
+ # HF_TOKEN=
123
+ # HF_BASE_URL=https://router.huggingface.co/v1 # Override default base URL
124
+ # OPENCODE_GO_BASE_URL=https://opencode.ai/zen/go/v1 # Override default base URL
125
+
126
+ # DeepInfra — 100+ top open models, pay-per-use.
127
+ # Get your key at: https://deepinfra.com/dash/api_keys
128
+ # DEEPINFRA_API_KEY=
129
+
130
+ # =============================================================================
131
+ # LLM PROVIDER (Qwen OAuth)
132
+ # =============================================================================
133
+ # Qwen OAuth reuses your local Qwen CLI login (qwen auth qwen-oauth).
134
+ # No API key needed — credentials come from ~/.qwen/oauth_creds.json.
135
+ # Optional base URL override:
136
+ # HERMES_QWEN_BASE_URL=https://portal.qwen.ai/v1
137
+
138
+ # =============================================================================
139
+ # LLM PROVIDER (Xiaomi MiMo)
140
+ # =============================================================================
141
+ # Xiaomi MiMo models (mimo-v2-pro, mimo-v2-omni, mimo-v2-flash).
142
+ # Get your key at: https://platform.xiaomimimo.com
143
+ # XIAOMI_API_KEY=your_key_here
144
+ # Optional base URL override:
145
+ # XIAOMI_BASE_URL=https://api.xiaomimimo.com/v1
146
+
147
+ # =============================================================================
148
+ # LLM PROVIDER (Upstage Solar)
149
+ # =============================================================================
150
+ # Upstage provides access to Upstage Solar models.
151
+ # Get your key at: https://console.upstage.ai/api-keys
152
+ # UPSTAGE_API_KEY=your_key_here
153
+ # Optional base URL override:
154
+ # UPSTAGE_BASE_URL=https://api.upstage.ai/v1
155
+
156
+ # =============================================================================
157
+ # LLM PROVIDER (Ramp Router)
158
+ # =============================================================================
159
+ # Ramp Router (router.com) — Responses-native LLM gateway; model IDs come
160
+ # from your account's live catalog (GET /v1/models).
161
+ # Get your key at: https://app.router.com/keys
162
+ # RAMP_ROUTER_API_KEY=your_key_here
163
+ # Optional base URL override:
164
+ # RAMP_ROUTER_BASE_URL=https://api.router.com/v1
165
+
166
+ # =============================================================================
167
+ # LLM PROVIDER (Nebius Token Factory)
168
+ # =============================================================================
169
+ # Nebius Token Factory — OpenAI-compatible inference for open models.
170
+ # Get your key at: https://tokenfactory.nebius.com/
171
+ # NEBIUS_API_KEY=your_key_here
172
+ # Optional base URL override:
173
+ # NEBIUS_BASE_URL=https://api.tokenfactory.nebius.com/v1
174
+
175
+ # =============================================================================
176
+ # LLM PROVIDER (Tencent Hy — TokenHub & TokenPlan)
177
+ # =============================================================================
178
+ # Tencent TokenHub (OpenAI-compatible): https://tokenhub.tencentmaas.com
179
+ # TOKENHUB_API_KEY=your_key_here
180
+ # TOKENHUB_BASE_URL=https://tokenhub.tencentmaas.com/v1
181
+ # Tencent TokenPlan (Anthropic Messages endpoint via LKEAP):
182
+ # TOKENPLAN_API_KEY=your_key_here
183
+ # TOKENPLAN_BASE_URL=https://api.lkeap.cloud.tencent.com/plan/anthropic
184
+
185
+ # =============================================================================
186
+ # TOOL API KEYS
187
+ # =============================================================================
188
+
189
+ # Exa API Key - AI-native web search and contents
190
+ # Get at: https://exa.ai
191
+ # EXA_API_KEY=
192
+
193
+ # Parallel API Key - AI-native web search and extract
194
+ # Get at: https://parallel.ai
195
+ # PARALLEL_API_KEY=
196
+
197
+ # Firecrawl API Key - Web search, extract, and crawl
198
+ # Get at: https://firecrawl.dev/
199
+ # FIRECRAWL_API_KEY=
200
+
201
+
202
+ # FAL.ai API Key - Image generation
203
+ # Get at: https://fal.ai/
204
+ # FAL_KEY=
205
+
206
+ # Honcho - Cross-session AI-native user modeling (optional)
207
+ # Builds a persistent understanding of the user across sessions and tools.
208
+ # Get at: https://app.honcho.dev
209
+ # Also requires ~/.honcho/config.json with enabled=true (see README).
210
+ # HONCHO_API_KEY=
211
+
212
+ # =============================================================================
213
+ # HYPERLIQUID OPTIONAL SKILL
214
+ # =============================================================================
215
+ # Optional defaults for the Hyperliquid skill in optional-skills/blockchain/hyperliquid
216
+ #
217
+ # Hyperliquid API base URL override
218
+ # Default: https://api.hyperliquid.xyz
219
+ # HYPERLIQUID_API_URL=https://api.hyperliquid-testnet.xyz
220
+ #
221
+ # Default address for account-level commands like state, fills, orders, and review
222
+ # HYPERLIQUID_USER_ADDRESS=0x0000000000000000000000000000000000000000
223
+
224
+ # =============================================================================
225
+ # TERMINAL TOOL CONFIGURATION
226
+ # =============================================================================
227
+ # Backend type: "local", "singularity", "docker", "modal", or "ssh"
228
+ # Terminal backend is configured in ~/.hermes/config.yaml (terminal.backend).
229
+ # Use 'hermes setup' or 'hermes config set terminal.backend docker' to change.
230
+ # Supported: local, docker, singularity, modal, ssh
231
+ #
232
+ # Only override here if you need to force a backend without touching config.yaml:
233
+ # TERMINAL_ENV=local
234
+
235
+ # Override the container runtime binary (e.g. to use Podman instead of Docker).
236
+ # Useful on systems where Docker's storage driver is broken or unavailable.
237
+ # HERMES_DOCKER_BINARY=/usr/local/bin/podman
238
+
239
+ # Container images (for singularity/docker/modal backends)
240
+ # TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
241
+ # TERMINAL_SINGULARITY_IMAGE=docker://nikolaik/python-nodejs:python3.11-nodejs20
242
+ TERMINAL_MODAL_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20
243
+
244
+
245
+ # Working directory for terminal commands
246
+ # For local backend: "." means current directory (resolved automatically)
247
+ # For remote backends (ssh/docker/modal/singularity): use an absolute path
248
+ # INSIDE the target environment, or leave unset for the backend's default
249
+ # (/root for modal, / for docker, ~ for ssh). Do NOT use a host-local path.
250
+ # Usually managed by config.yaml (terminal.cwd) — uncomment to override
251
+ # TERMINAL_CWD=.
252
+
253
+ # Default command timeout in seconds
254
+ TERMINAL_TIMEOUT=60
255
+
256
+ # Cleanup inactive environments after this many seconds
257
+ TERMINAL_LIFETIME_SECONDS=300
258
+
259
+ # =============================================================================
260
+ # SSH REMOTE EXECUTION (for TERMINAL_ENV=ssh)
261
+ # =============================================================================
262
+ # Run terminal commands on a remote server via SSH.
263
+ # Agent code stays on your machine, commands execute remotely.
264
+ #
265
+ # SECURITY BENEFITS:
266
+ # - Agent cannot read your .env file (API keys protected)
267
+ # - Agent cannot modify its own code
268
+ # - Remote server acts as isolated sandbox
269
+ # - Can safely configure passwordless sudo on remote
270
+ #
271
+ # TERMINAL_SSH_HOST=192.168.1.100
272
+ # TERMINAL_SSH_USER=agent
273
+ # TERMINAL_SSH_PORT=22
274
+ # TERMINAL_SSH_KEY=~/.ssh/id_rsa
275
+
276
+ # =============================================================================
277
+ # SUDO SUPPORT (works with ALL terminal backends)
278
+ # =============================================================================
279
+ # If set, enables sudo commands by piping password via `sudo -S`.
280
+ # Works with: local, docker, singularity, modal, and ssh backends.
281
+ #
282
+ # SECURITY WARNING: Password stored in plaintext. Only use on trusted machines.
283
+ #
284
+ # ALTERNATIVES:
285
+ # - For SSH backend: Configure passwordless sudo on the remote server
286
+ # - For containers: Run as root inside the container (no sudo needed)
287
+ # - For local: Configure /etc/sudoers for specific commands
288
+ # - For CLI: Leave unset - you'll be prompted interactively with 45s timeout
289
+ #
290
+ # SUDO_PASSWORD=your_password_here
291
+
292
+ # =============================================================================
293
+ # MODAL CLOUD BACKEND (Optional - for TERMINAL_ENV=modal)
294
+ # =============================================================================
295
+ # Modal uses CLI authentication, not environment variables.
296
+ # Run: pip install modal && modal setup
297
+ # This will authenticate via browser and store credentials locally.
298
+ # No API key needed in .env - Modal handles auth automatically.
299
+
300
+ # =============================================================================
301
+ # BROWSER TOOL CONFIGURATION (agent-browser + Browserbase)
302
+ # =============================================================================
303
+ # Browser automation requires Browserbase cloud service for remote browser execution.
304
+ # This allows the agent to navigate websites, fill forms, and extract information.
305
+ #
306
+ # STEALTH MODES:
307
+ # - Basic Stealth: ALWAYS active (random fingerprints, auto CAPTCHA solving)
308
+ # - Advanced Stealth: Requires BROWSERBASE_ADVANCED_STEALTH=true (Scale Plan only)
309
+
310
+ # Browserbase API Key - Cloud browser execution
311
+ # Get at: https://browserbase.com/
312
+ # BROWSERBASE_API_KEY=
313
+
314
+ # Browserbase Project ID - From your Browserbase dashboard
315
+ # BROWSERBASE_PROJECT_ID=
316
+
317
+ # Enable residential proxies for better CAPTCHA solving (default: true)
318
+ # Routes traffic through residential IPs, significantly improves success rate
319
+ BROWSERBASE_PROXIES=true
320
+
321
+ # Enable advanced stealth mode (default: false, requires Scale Plan)
322
+ # Uses custom Chromium build to avoid bot detection altogether
323
+ BROWSERBASE_ADVANCED_STEALTH=false
324
+
325
+ # Local browser engine (default: auto = Chrome)
326
+ # "auto" — use Chrome
327
+ # "lightpanda" — use Lightpanda (faster navigation, no screenshots)
328
+ # "chrome" — explicitly request Chrome
329
+ # Browser Use mode (default) spawns `lightpanda serve` itself; the built-in
330
+ # browser tools pass --engine to agent-browser v0.25.3+ and retry failed or
331
+ # empty Lightpanda results with Chrome. Ignored while a cloud provider,
332
+ # Camofox or browser.cdp_url is active (`hermes doctor` reports that).
333
+ # Also configurable via browser.engine in config.yaml.
334
+ # AGENT_BROWSER_ENGINE=auto
335
+
336
+ # Browser session timeout in seconds (default: 300)
337
+ # Sessions are cleaned up after this duration of inactivity
338
+ BROWSER_SESSION_TIMEOUT=300
339
+
340
+ # Browser inactivity timeout - auto-cleanup inactive sessions (default: 120 = 2 min)
341
+ # Browser sessions are automatically closed after this period of no activity
342
+ BROWSER_INACTIVITY_TIMEOUT=120
343
+
344
+ # Extra Chromium launch flags passed to agent-browser, comma- or newline-separated.
345
+ # Hermes auto-injects "--no-sandbox,--disable-dev-shm-usage" when it detects root
346
+ # or AppArmor-restricted unprivileged user namespaces (Ubuntu 23.10+, DGX Spark,
347
+ # many container images), so leave this unset unless you need extra flags.
348
+ # Setting this disables the auto-injection.
349
+ # AGENT_BROWSER_ARGS=--no-sandbox
350
+
351
+ # Camofox local anti-detection browser (Camoufox-based Firefox).
352
+ # Set CAMOFOX_URL to route the browser tools through a local Camofox server
353
+ # instead of agent-browser/Browserbase. See docs/user-guide/features/browser.md.
354
+ # CAMOFOX_URL=http://localhost:9377
355
+
356
+ # Externally managed Camofox sessions — when another app owns the visible
357
+ # Camofox browser, set these so Hermes shares the same userId/profile instead
358
+ # of creating its own isolated session.
359
+ # CAMOFOX_USER_ID=
360
+ # CAMOFOX_SESSION_KEY=
361
+ # Set to true to reuse an already-open Camofox tab for this identity before
362
+ # creating a new one (useful for gateway restarts).
363
+ # CAMOFOX_ADOPT_EXISTING_TAB=false
364
+
365
+ # =============================================================================
366
+ # SESSION LOGGING
367
+ # =============================================================================
368
+ # Session trajectories are automatically saved to logs/ directory
369
+ # Format: logs/session_YYYYMMDD_HHMMSS_UUID.json
370
+ # Contains full conversation history in trajectory format for debugging/replay
371
+
372
+ # =============================================================================
373
+ # VOICE TRANSCRIPTION & OPENAI TTS
374
+ # =============================================================================
375
+ # Required for voice message transcription (Whisper) and OpenAI TTS voices.
376
+ # Uses OpenAI's API directly (not via OpenRouter).
377
+ # Named VOICE_TOOLS_OPENAI_KEY to avoid interference with OpenRouter.
378
+ # Get at: https://platform.openai.com/api-keys
379
+ # VOICE_TOOLS_OPENAI_KEY=
380
+
381
+ # =============================================================================
382
+ # SLACK INTEGRATION
383
+ # =============================================================================
384
+ # Slack Bot Token - From Slack App settings (OAuth & Permissions)
385
+ # Get at: https://api.slack.com/apps
386
+ # SLACK_BOT_TOKEN=xoxb-...
387
+
388
+ # Slack App Token - For Socket Mode (App-Level Tokens in Slack App settings)
389
+ # SLACK_APP_TOKEN=xapp-...
390
+
391
+ # Slack allowed users (comma-separated Slack user IDs)
392
+ # SLACK_ALLOWED_USERS=
393
+
394
+ # =============================================================================
395
+ # TELEGRAM INTEGRATION
396
+ # =============================================================================
397
+ # Telegram Bot Token - From @BotFather (https://t.me/BotFather)
398
+ # TELEGRAM_BOT_TOKEN=
399
+ # TELEGRAM_ALLOWED_USERS= # Comma-separated user IDs
400
+ # TELEGRAM_HOME_CHANNEL= # Default chat for cron delivery
401
+ # TELEGRAM_HOME_CHANNEL_NAME= # Display name for home channel
402
+ # TELEGRAM_CRON_THREAD_ID= # Forum topic ID for cron deliveries; overrides TELEGRAM_HOME_CHANNEL_THREAD_ID for cron so replies work in topic mode
403
+
404
+ # Webhook mode (optional — for cloud deployments like Fly.io/Railway)
405
+ # Default is long polling. Setting TELEGRAM_WEBHOOK_URL switches to webhook mode.
406
+ # TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
407
+ # TELEGRAM_WEBHOOK_PORT=8443
408
+ # TELEGRAM_WEBHOOK_SECRET= # Recommended for production
409
+
410
+ # WhatsApp (built-in Baileys bridge — run `hermes whatsapp` to pair)
411
+ # WHATSAPP_ENABLED=false
412
+ # WHATSAPP_ALLOWED_USERS=15551234567
413
+
414
+ # Email (IMAP/SMTP — send and receive emails as Hermes)
415
+ # For Gmail: enable 2FA → create App Password at https://myaccount.google.com/apppasswords
416
+ # EMAIL_ADDRESS=hermes@gmail.com
417
+ # EMAIL_PASSWORD=xxxx xxxx xxxx xxxx
418
+ # EMAIL_IMAP_HOST=imap.gmail.com
419
+ # EMAIL_IMAP_PORT=993
420
+ # EMAIL_SMTP_HOST=smtp.gmail.com
421
+ # EMAIL_SMTP_PORT=587
422
+ # EMAIL_POLL_INTERVAL=15
423
+ # EMAIL_ALLOWED_USERS=your@email.com
424
+ # EMAIL_HOME_ADDRESS=your@email.com
425
+
426
+ # Gateway-wide: allow ALL users without an allowlist (default: false = deny)
427
+ # Only set to true if you intentionally want open access.
428
+ # GATEWAY_ALLOW_ALL_USERS=false
429
+
430
+ # =============================================================================
431
+ # RESPONSE PACING
432
+ # =============================================================================
433
+ # Human-like delays between message chunks on messaging platforms.
434
+ # Makes the bot feel less robotic.
435
+ # HERMES_HUMAN_DELAY_MODE=off # off | natural | custom
436
+ # HERMES_HUMAN_DELAY_MIN_MS=800 # Min delay in ms (custom mode)
437
+ # HERMES_HUMAN_DELAY_MAX_MS=2500 # Max delay in ms (custom mode)
438
+
439
+ # =============================================================================
440
+ # DEBUG OPTIONS
441
+ # =============================================================================
442
+ WEB_TOOLS_DEBUG=false
443
+ VISION_TOOLS_DEBUG=false
444
+ MOA_TOOLS_DEBUG=false
445
+ IMAGE_TOOLS_DEBUG=false
446
+
447
+ # =============================================================================
448
+ # CONTEXT COMPRESSION (Auto-shrinks long conversations)
449
+ # =============================================================================
450
+ # When conversation approaches model's context limit, middle turns are
451
+ # automatically summarized to free up space.
452
+ #
453
+ # Context compression is configured in ~/.hermes/config.yaml under compression:
454
+ # CONTEXT_COMPRESSION_ENABLED=true # Enable auto-compression (default: true)
455
+ # CONTEXT_COMPRESSION_THRESHOLD=0.85 # Compress at 85% of context limit
456
+ # Model is set via compression.summary_model in config.yaml (default: google/gemini-3-flash-preview)
457
+
458
+ # =============================================================================
459
+ # SKILLS HUB (GitHub integration for skill search/install/publish)
460
+ # =============================================================================
461
+
462
+ # GitHub Personal Access Token — for higher API rate limits on skill search/install
463
+ # Get at: https://github.com/settings/tokens (Fine-grained recommended)
464
+ # GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx
465
+
466
+ # GitHub App credentials (optional — for bot identity on PRs)
467
+ # GITHUB_APP_ID=
468
+ # GITHUB_APP_PRIVATE_KEY_PATH=
469
+ # GITHUB_APP_INSTALLATION_ID=
470
+
471
+ # Groq API key (free tier — used for Whisper STT in voice mode)
472
+ # GROQ_API_KEY=
473
+
474
+ # ElevenLabs API key (cloud STT/TTS — Scribe transcription)
475
+ # ELEVENLABS_API_KEY=
476
+
477
+ # =============================================================================
478
+ # STT PROVIDER SELECTION
479
+ # =============================================================================
480
+ # Default STT provider is "local" (faster-whisper) — runs on your machine, no API key needed.
481
+ # Install with: pip install faster-whisper
482
+ # Model downloads automatically on first use (~150 MB for "base").
483
+ # To use cloud providers instead, set GROQ_API_KEY, VOICE_TOOLS_OPENAI_KEY, or ELEVENLABS_API_KEY above.
484
+ # Provider priority: local > groq > openai > mistral > xai > elevenlabs
485
+ # Configure in config.yaml: stt.provider: local | groq | openai | mistral | xai | elevenlabs
486
+
487
+ # =============================================================================
488
+ # STT ADVANCED OVERRIDES (optional)
489
+ # =============================================================================
490
+ # Override default STT models per provider (normally set via stt.model in config.yaml)
491
+ # STT_GROQ_MODEL=whisper-large-v3-turbo
492
+ # STT_OPENAI_MODEL=whisper-1
493
+ # STT_ELEVENLABS_MODEL=scribe_v2
494
+
495
+ # Override STT provider endpoints (for proxies or self-hosted instances)
496
+ # GROQ_BASE_URL=https://api.groq.com/openai/v1
497
+ # STT_OPENAI_BASE_URL=https://api.openai.com/v1
498
+ # ELEVENLABS_STT_BASE_URL=https://api.elevenlabs.io/v1
499
+
500
+ # =============================================================================
501
+ # MICROSOFT TEAMS INTEGRATION
502
+ # =============================================================================
503
+ # Register a Bot in Azure: https://dev.botframework.com/ → "Register a bot"
504
+ # Or use Azure Portal: Azure Active Directory → App registrations → New registration
505
+ # Then add the bot to Teams via the Bot Framework or App Studio.
506
+ #
507
+ # TEAMS_CLIENT_ID= # Azure AD App (client) ID
508
+ # TEAMS_CLIENT_SECRET= # Azure AD client secret value
509
+ # TEAMS_TENANT_ID= # Azure AD tenant ID (or "common" for multi-tenant)
510
+ # TEAMS_ALLOWED_USERS= # Comma-separated AAD object IDs or UPNs
511
+ # TEAMS_ALLOW_ALL_USERS=false # Set true to skip the allowlist
512
+ # TEAMS_HOME_CHANNEL= # Default channel/chat ID for cron delivery
513
+ # TEAMS_HOME_CHANNEL_NAME= # Display name for the home channel
514
+ # TEAMS_PORT=3978 # Webhook listen port (Bot Framework default)
515
+
516
+ # =============================================================================
517
+ # GOOGLE CHAT INTEGRATION
518
+ # =============================================================================
519
+ # Connects via Cloud Pub/Sub pull subscription (no public URL required).
520
+ # Setup walkthrough: website/docs/user-guide/messaging/google_chat.md.
521
+ # 1. Create a GCP project, enable the Google Chat API and Cloud Pub/Sub.
522
+ # 2. Create a Service Account with roles/pubsub.subscriber on the
523
+ # subscription (NOT project-wide); download the JSON key.
524
+ # 3. Configure your Chat app at console.cloud.google.com/apis/credentials
525
+ # → Google Chat API → Configuration → Cloud Pub/Sub topic.
526
+ # 4. (Optional, for native attachment delivery) Each user runs
527
+ # `/setup-files` once in their own DM after Pub/Sub is wired up.
528
+ #
529
+ # GOOGLE_CHAT_PROJECT_ID= # GCP project hosting the topic (or set GOOGLE_CLOUD_PROJECT)
530
+ # GOOGLE_CHAT_SUBSCRIPTION_NAME= # Full path: projects/<id>/subscriptions/<name>
531
+ # GOOGLE_CHAT_SERVICE_ACCOUNT_JSON= # Path to SA JSON (or set GOOGLE_APPLICATION_CREDENTIALS)
532
+ # GOOGLE_CHAT_ALLOWED_USERS= # Comma-separated emails allowed to talk to the bot
533
+ # GOOGLE_CHAT_ALLOW_ALL_USERS=false # Set true to skip the allowlist
534
+ # GOOGLE_CHAT_HOME_CHANNEL= # Default space (spaces/XXXX) for cron delivery
535
+ # GOOGLE_CHAT_HOME_CHANNEL_NAME= # Display name for the home channel
536
+
537
+ # =============================================================================
538
+ # reddit-reading skill (optional) — app-only credentials, NOT a user login
539
+ # =============================================================================
540
+ # The skill works with no credentials via Reddit's public feeds (~1 request/minute).
541
+ # For faster access with scores and nested comments, register a free "script" app
542
+ # at https://www.reddit.com/prefs/apps and paste its id and secret here.
543
+ # REDDIT_CLIENT_ID=
544
+ # REDDIT_CLIENT_SECRET=
.gitattributes CHANGED
@@ -1,35 +1,34 @@
1
- *.7z filter=lfs diff=lfs merge=lfs -text
2
- *.arrow filter=lfs diff=lfs merge=lfs -text
3
- *.bin filter=lfs diff=lfs merge=lfs -text
4
- *.bz2 filter=lfs diff=lfs merge=lfs -text
5
- *.ckpt filter=lfs diff=lfs merge=lfs -text
6
- *.ftz filter=lfs diff=lfs merge=lfs -text
7
- *.gz filter=lfs diff=lfs merge=lfs -text
8
- *.h5 filter=lfs diff=lfs merge=lfs -text
9
- *.joblib filter=lfs diff=lfs merge=lfs -text
10
- *.lfs.* filter=lfs diff=lfs merge=lfs -text
11
- *.mlmodel filter=lfs diff=lfs merge=lfs -text
12
- *.model filter=lfs diff=lfs merge=lfs -text
13
- *.msgpack filter=lfs diff=lfs merge=lfs -text
14
- *.npy filter=lfs diff=lfs merge=lfs -text
15
- *.npz filter=lfs diff=lfs merge=lfs -text
16
- *.onnx filter=lfs diff=lfs merge=lfs -text
17
- *.ot filter=lfs diff=lfs merge=lfs -text
18
- *.parquet filter=lfs diff=lfs merge=lfs -text
19
- *.pb filter=lfs diff=lfs merge=lfs -text
20
- *.pickle filter=lfs diff=lfs merge=lfs -text
21
- *.pkl filter=lfs diff=lfs merge=lfs -text
22
- *.pt filter=lfs diff=lfs merge=lfs -text
23
- *.pth filter=lfs diff=lfs merge=lfs -text
24
- *.rar filter=lfs diff=lfs merge=lfs -text
25
- *.safetensors filter=lfs diff=lfs merge=lfs -text
26
- saved_model/**/* filter=lfs diff=lfs merge=lfs -text
27
- *.tar.* filter=lfs diff=lfs merge=lfs -text
28
- *.tar filter=lfs diff=lfs merge=lfs -text
29
- *.tflite filter=lfs diff=lfs merge=lfs -text
30
- *.tgz filter=lfs diff=lfs merge=lfs -text
31
- *.wasm filter=lfs diff=lfs merge=lfs -text
32
- *.xz filter=lfs diff=lfs merge=lfs -text
33
- *.zip filter=lfs diff=lfs merge=lfs -text
34
- *.zst filter=lfs diff=lfs merge=lfs -text
35
- *tfevents* filter=lfs diff=lfs merge=lfs -text
 
1
+ # Auto-generated files — collapse diffs and exclude from language stats
2
+ web/package-lock.json linguist-generated=true
3
+
4
+ # Enforce LF for scripts that run inside Linux containers.
5
+ # Without this, Windows checkout converts to CRLF and breaks `exec` in the
6
+ # container entrypoint with "no such file or directory".
7
+ *.sh text eol=lf
8
+ Dockerfile text eol=lf
9
+ *.dockerfile text eol=lf
10
+ docker/entrypoint.sh text eol=lf
11
+
12
+ # Enforce LF for all source/text files. Windows editors and tools default to
13
+ # CRLF; without normalization a Windows contributor's edit turns into a
14
+ # whole-file phantom diff (every line "changed" by its ending), breaks
15
+ # string-match patch tooling, and pollutes review. `text` normalizes to LF
16
+ # at check-in; `eol=lf` also checks out as LF so the working tree matches
17
+ # the index on every platform. PowerShell files are the deliberate
18
+ # exception (PS 5.1 tooling expects CRLF).
19
+ *.py text eol=lf
20
+ *.ts text eol=lf
21
+ *.tsx text eol=lf
22
+ *.js text eol=lf
23
+ *.mjs text eol=lf
24
+ *.cjs text eol=lf
25
+ *.jsx text eol=lf
26
+ *.json text eol=lf
27
+ *.yaml text eol=lf
28
+ *.yml text eol=lf
29
+ *.toml text eol=lf
30
+ *.md text eol=lf
31
+ *.css text eol=lf
32
+ *.html text eol=lf
33
+ *.svg text eol=lf
34
+ *.ps1 text eol=crlf
 
.gitignore ADDED
@@ -0,0 +1,280 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ .DS_Store
2
+ /venv/
3
+ /venv.old/
4
+ /venv.stale.runtime-*/
5
+ /bin/
6
+ /.hermes-runtime/
7
+ /_pycache/
8
+ *.pyc*
9
+ __pycache__/
10
+ act/
11
+ .act-sandbox-agent.*
12
+ .venv/
13
+ .venv
14
+ .vscode/
15
+ .env
16
+ .op.env
17
+ .env.local
18
+ .env.development.local
19
+ .env.test.local
20
+ .env.production.local
21
+ .env.development
22
+ .env.test
23
+ .hermes-docker/
24
+ .notebooklm-home/
25
+ .notebooklm-cli-venv/
26
+ .notebooklm-playwright/
27
+ .pip-cache/
28
+ .uv-cache/
29
+ compose.hermes.local.yml
30
+ export*
31
+ __pycache__/model_tools.cpython-310.pyc
32
+ __pycache__/web_tools.cpython-310.pyc
33
+ logs/
34
+ data/
35
+ # Bundled community plugin index seed (shipped as package data) — the bare
36
+ # `data/` pattern above would otherwise swallow it.
37
+ !hermes_cli/data/
38
+ .pytest_cache/
39
+ test_durations.json
40
+ .pytest-cache/
41
+ tmp/
42
+ temp_vision_images/
43
+ hermes-*/*
44
+ examples/
45
+ tests/quick_test_dataset.jsonl
46
+ tests/sample_dataset.jsonl
47
+ run_datagen_kimik2-thinking.sh
48
+ run_datagen_megascience_glm4-6.sh
49
+ run_datagen_sonnet.sh
50
+ source-data/*
51
+ run_datagen_megascience_glm4-6.sh
52
+ data/*
53
+ MagicMock/
54
+ # No trailing slash: also matches node_modules SYMLINKS (worktrees often
55
+ # symlink node_modules to the main checkout; the dir-only pattern let one
56
+ # slip into a commit and break `npm ci` on CI with ENOTDIR).
57
+ node_modules
58
+ browser-use/
59
+ agent-browser/
60
+ # Private keys
61
+ *.ppk
62
+ *.pem
63
+ privvy*
64
+ images/
65
+ __pycache__/
66
+ hermes_agent.egg-info/
67
+ wandb/
68
+ testlogs
69
+ playwright-report/
70
+ test-results/
71
+ # Playwright visual regression baselines — cached from main in CI, not committed
72
+ *-snapshots/
73
+
74
+ # CLI config (may contain sensitive SSH paths)
75
+ cli-config.yaml
76
+
77
+ # Skills Hub state (lives in ~/.hermes/skills/.hub/ at runtime, but just in case)
78
+ skills/.hub/
79
+ ignored/
80
+ .worktrees/
81
+ environments/benchmarks/evals/
82
+
83
+ # Web UI build output
84
+ hermes_cli/web_dist/
85
+ # Cross-process web UI build lock (flock target, always empty)
86
+ .web_ui_build.lock
87
+ apps/desktop/build/
88
+ apps/desktop/dist/
89
+
90
+ # tsc-emitted artifacts (a stray `tsc -b` compiles into src/, and vite then
91
+ # resolves the stale .js OVER the .tsx — never track these)
92
+ apps/desktop/src/**/*.js
93
+ apps/desktop/src/**/*.js.map
94
+ apps/desktop/src/**/*.d.ts
95
+ # EXCEPT bundled plain-ESM plugin entries (adopted SDK-consumer plugins,
96
+ # e.g. hermes-bots): plugin.js IS the source, not tsc output. No .tsx
97
+ # sibling exists, so the stale-shadow hazard above cannot apply.
98
+ !apps/desktop/src/plugins/*/plugin.js
99
+ !apps/desktop/src/global.d.ts
100
+ !apps/desktop/src/vite-env.d.ts
101
+
102
+ # Build/debug artifacts that must never be committed
103
+ /log.txt
104
+ /sqlite_leak_fix.png
105
+ /*.png.bak
106
+ *.tar.gz
107
+ *.tgz
108
+ apps/shared/src/**/*.js
109
+ apps/shared/src/**/*.js.map
110
+ apps/shared/src/**/*.d.ts
111
+ apps/desktop/release/
112
+ # stage-and-swap Desktop rebuild output (#86443); removed after the swap, but
113
+ # a killed build must not leave the checkout dirty
114
+ apps/desktop/.staging-*/
115
+ *.tsbuildinfo
116
+
117
+ # Web UI assets — synced from @nous-research/ui at build time via
118
+ # `npm run sync-assets` (see web/package.json).
119
+ web/public/fonts/
120
+ web/public/ds-assets/
121
+
122
+ # Release script temp files
123
+ .release_notes.md
124
+ mini-swe-agent/
125
+
126
+ # Nix
127
+ .direnv/
128
+ .nix-stamps/
129
+ result
130
+ website/static/api/skills-index.json
131
+ # skills.json + skills-meta.json are build artifacts emitted by
132
+ # website/scripts/extract-skills.py during prebuild — keep them out of
133
+ # git for the same reason as skills-index.json (large, generated, change
134
+ # every build).
135
+ website/static/api/skills.json
136
+ website/static/api/skills-meta.json
137
+ # plugins.json + plugins-meta.json are build artifacts emitted by
138
+ # website/scripts/extract-plugins.py during prebuild (Plugin Catalog page).
139
+ website/static/api/plugins.json
140
+ website/static/api/plugin-stars.json
141
+ website/static/api/plugin-catalog.json
142
+ website/static/api/plugins-meta.json
143
+ # automation-blueprints-index.json is a build artifact emitted by
144
+ # website/scripts/extract-automation-blueprints.py during prebuild.
145
+ website/static/api/automation-blueprints-index.json
146
+ models-dev-upstream/
147
+
148
+ # Local editor / agent tooling (machine-specific; keep in global config, not the repo)
149
+ .codex/
150
+ .cursor/
151
+ .gemini/
152
+ .zed/
153
+ .mcp.json
154
+ opencode.json
155
+ config/mcporter.json
156
+
157
+ hermes_cli/tui_dist/*
158
+ hermes_cli/scripts/
159
+ docs/superpowers/*
160
+ # Working directory for the Hermes Agent's session state (~/.hermes/ at runtime;
161
+ # also created in-repo when an agent operates in this checkout). Plans, audit
162
+ # logs, and per-session caches are never artifacts of the codebase.
163
+ .hermes/
164
+
165
+ # Desktop/bootstrap install marker written into the managed checkout root by the
166
+ # bootstrap installer. It is Hermes-managed runtime state, never a code change —
167
+ # ignore it so `hermes update`'s `git stash push --include-untracked` does not
168
+ # treat it as a local edit and autostash it on every run (#38529).
169
+ .hermes-bootstrap-complete
170
+
171
+ # Flat-install runtime state (checkout root == $HERMES_HOME, e.g. installs made
172
+ # with HERMES_INSTALL_DIR=$HERMES_HOME or by older installers): every root-level
173
+ # SQLite store (state.db, kanban.db, response_store.db, ...) with its
174
+ # WAL/SHM/journal sidecars and retired-WAL capture dirs, the legacy transcripts,
175
+ # the cron job store (jobs.json) and executions ledger, gateway lock/pid/state
176
+ # files, cache/spill directories, and the profile's own config/credential/
177
+ # memory/profile/pairing roots are Hermes-managed runtime state, never code
178
+ # changes. (`*-snapshots/` above already covers state-snapshots/.)
179
+ # Ignore them so `hermes update`'s `git stash push --include-untracked` cannot
180
+ # sweep the live state.db/-wal into the stash and unlink it under the running
181
+ # gateway (#110648). Nested installs keep all of this under $HERMES_HOME outside
182
+ # the checkout, where the `.hermes/` rule above already applies.
183
+ /*.db
184
+ /*.db-wal
185
+ /*.db-shm
186
+ /*.db-journal
187
+ /*.db.retired-wal-*/
188
+ /gateway/discord_message_recovery.db*
189
+ /sessions/
190
+ /browser-profile/
191
+ /cron/executions.db*
192
+ /cron/jobs.json
193
+ /cron.pid
194
+ /gateway.lock
195
+ /gateway.pid
196
+ /gateway_state.json
197
+ /processes.json
198
+ /hook_outputs/
199
+ /hooks/
200
+ /cache/
201
+ /checkpoints/
202
+ /pending_messages/
203
+ /plugin-data/
204
+ /kanban/
205
+ /config.yaml
206
+ /auth.json
207
+ /auth.lock
208
+ /auth/
209
+ /.anthropic_oauth.json
210
+ /google_token.json
211
+ /google_oauth_pending.json
212
+ /webhook_subscriptions.json
213
+ /channel_directory.json
214
+ /channel_aliases.json
215
+ /feishu_comment_pairing.json
216
+ /memories/
217
+ /profiles/
218
+ /credentials/
219
+ /mcp-tokens/
220
+ /pairing/
221
+ /platforms/
222
+
223
+ # Persistent dev sandbox dir (scripts/dev-sandbox.sh --persistent)
224
+ .hermes-sandbox/
225
+ # Sandbox dirs used by the install/update E2E (tests/install/). The suffix is
226
+ # the route name, so each route gets its own tree and two can run at once.
227
+ .hermes-sandbox-e2e*/
228
+
229
+ # Interrupted-update breadcrumb + recovery lock written next to the shared venv
230
+ # by `hermes update` / launch-time self-heal. Runtime state, never a code change
231
+ # — ignore so `git status` stays clean and update's autostash skips them.
232
+ .update-incomplete
233
+ .update-incomplete.lock
234
+
235
+ # Checkout fingerprint the __pycache__ tree was last validated against
236
+ # (launch-time stale-bytecode sweep). Runtime state, never a code change.
237
+ .bytecode-fingerprint
238
+ .bytecode-fingerprint.tmp
239
+
240
+ # Installer-written method stamp in the managed checkout root (scripts/install.sh).
241
+ # Runtime metadata only — never a code change. Ignore so `git status` stays clean
242
+ # and `hermes update`'s untracked autostash does not treat it as a local edit (#66189 / #54855).
243
+ /.install_method
244
+
245
+ # Tool Search live-test harness output — non-deterministic model transcripts,
246
+ # regenerated by evals/tool_search/tool_search_livetest*.py. Never an artifact of the repo.
247
+ evals/tool_search/out*/
248
+
249
+ # Per-release changelog drafts. These exist only transiently during a release
250
+ # cut (passed to `gh release create --notes-file`); the GitHub Release itself
251
+ # stores the published notes. They are not a build artifact and must never be
252
+ # committed to the repo root. See the hermes-release skill.
253
+ RELEASE_v*.md
254
+
255
+ # Desktop demo-run scratch output (hermes writes demo/*.txt during recorded
256
+ # walkthroughs). Throwaway artifacts, never part of the app.
257
+ apps/desktop/demo/
258
+
259
+ # PR infographics are rendered locally and embedded in PR descriptions via the
260
+ # image-provider (fal.media) URL — they are NEVER committed to the repo. The
261
+ # PR body is the archive. See the hermes-agent-dev skill's
262
+ # pr-infographic-workflow reference (storage rule + lapse #8 / #COMMIT-1).
263
+ #
264
+ # Spelling variants are listed because a single `infographic/` pattern was
265
+ # sidestepped by an `infograficos/` directory (#70552). .gitignore is only
266
+ # the first line of defence and cannot stop `git add -f` at all — the
267
+ # infographic-check CI job is what actually enforces this.
268
+ infographic/
269
+ infographics/
270
+ infograficos/
271
+ infografico/
272
+ native/fts5_cjk/*.so
273
+ # Runtime marker written by hermes update when a lazy dependency refresh is
274
+ # interrupted; consumed by launch-time recovery. Never commit it (was tracked
275
+ # by accident via 3a69e34702, removed in the #72002 salvage).
276
+ .lazy-refresh-incomplete
277
+ .skills_prompt_snapshot.json
278
+
279
+ # Disposable profile created by scripts/probe_active_session_exclusivity.py
280
+ .probe-home/
.mailmap ADDED
@@ -0,0 +1,109 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # .mailmap — canonical author mapping for git shortlog / git log / GitHub
2
+ # Format: Canonical Name <canonical@email> <commit@email>
3
+ # See: https://git-scm.com/docs/gitmailmap
4
+ #
5
+ # This maps commit emails to GitHub noreply addresses so that:
6
+ # 1. `git shortlog -sn` shows deduplicated contributor counts
7
+ # 2. GitHub's contributor graph can attribute commits correctly
8
+ # 3. Contributors with personal/work emails get proper credit
9
+ #
10
+ # When adding entries: use the contributor's GitHub noreply email as canonical
11
+ # so GitHub can link commits to their profile.
12
+
13
+ # === Teknium (multiple emails) ===
14
+ Teknium <127238744+teknium1@users.noreply.github.com> <teknium1@gmail.com>
15
+ Teknium <127238744+teknium1@users.noreply.github.com> <teknium@nousresearch.com>
16
+
17
+ # === Contributors — personal/work emails mapped to GitHub noreply ===
18
+ # Format: Canonical Name <GH-noreply> <commit-email>
19
+
20
+ # Verified via GH API email search
21
+ kshitijk4poor <82637225+kshitijk4poor@users.noreply.github.com> <kshitijkapoorr@gmail.com>
22
+ luyao618 <364939526@qq.com> <364939526@qq.com>
23
+ ethernet8023 <arilotter@gmail.com> <arilotter@gmail.com>
24
+ nicoloboschi <boschi1997@gmail.com> <boschi1997@gmail.com>
25
+ cherifya <chef.ya@gmail.com> <chef.ya@gmail.com>
26
+ BongSuCHOI <chlqhdtn98@gmail.com> <chlqhdtn98@gmail.com>
27
+ dsocolobsky <dsocolobsky@gmail.com> <dsocolobsky@gmail.com>
28
+ pefontana <fontana.pedro93@gmail.com> <fontana.pedro93@gmail.com>
29
+ Helmi <frank@helmschrott.de> <frank@helmschrott.de>
30
+ hata1234 <hata1234@gmail.com> <hata1234@gmail.com>
31
+
32
+ # Verified via PR investigation / salvage PR bodies
33
+ DeployFaith <agents@kylefrench.dev> <agents@kylefrench.dev>
34
+ flobo3 <floptopbot33@gmail.com> <floptopbot33@gmail.com>
35
+ gaixianggeng <gaixg94@gmail.com> <gaixg94@gmail.com>
36
+ KUSH42 <xush@xush.org> <xush@xush.org>
37
+ konsisumer <der@konsi.org> <der@konsi.org>
38
+ WorldInnovationsDepartment <vorvul.danylo@gmail.com> <vorvul.danylo@gmail.com>
39
+ m0n5t3r <iacobs@m0n5t3r.info> <iacobs@m0n5t3r.info>
40
+ sprmn24 <oncuevtv@gmail.com> <oncuevtv@gmail.com>
41
+ fancydirty <fancydirty@gmail.com> <fancydirty@gmail.com>
42
+ fxfitz <francis.x.fitzpatrick@gmail.com> <francis.x.fitzpatrick@gmail.com>
43
+ limars874 <limars874@gmail.com> <limars874@gmail.com>
44
+ AaronWong1999 <aaronwong1999@icloud.com> <aaronwong1999@icloud.com>
45
+ dippwho <dipp.who@gmail.com> <dipp.who@gmail.com>
46
+ duerzy <duerzy@gmail.com> <duerzy@gmail.com>
47
+ geoffwellman <geoff.wellman@gmail.com> <geoff.wellman@gmail.com>
48
+ hcshen0111 <shenhaocheng19990111@gmail.com> <shenhaocheng19990111@gmail.com>
49
+ jamesarch <han.shan@live.cn> <han.shan@live.cn>
50
+ stephenschoettler <stephenschoettler@gmail.com> <stephenschoettler@gmail.com>
51
+ Tranquil-Flow <tranquil_flow@protonmail.com> <tranquil_flow@protonmail.com>
52
+ Dusk1e <yusufalweshdemir@gmail.com> <yusufalweshdemir@gmail.com>
53
+ Awsh1 <ysfalweshcan@gmail.com> <ysfalweshcan@gmail.com>
54
+ WAXLYY <ysfwaxlycan@gmail.com> <ysfwaxlycan@gmail.com>
55
+ donrhmexe <don.rhm@gmail.com> <don.rhm@gmail.com>
56
+ hqhq1025 <1506751656@qq.com> <1506751656@qq.com>
57
+ BlackishGreen33 <s5460703@gmail.com> <s5460703@gmail.com>
58
+ tomqiaozc <zqiao@microsoft.com> <zqiao@microsoft.com>
59
+ MagicRay1217 <mingjwan@microsoft.com> <mingjwan@microsoft.com>
60
+ aaronagent <1115117931@qq.com> <1115117931@qq.com>
61
+ YoungYang963 <young@YoungdeMacBook-Pro.local> <young@YoungdeMacBook-Pro.local>
62
+ LongOddCode <haolong@microsoft.com> <haolong@microsoft.com>
63
+ Cafexss <coffeemjj@gmail.com> <coffeemjj@gmail.com>
64
+ Cygra <sjtuwbh@gmail.com> <sjtuwbh@gmail.com>
65
+ DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
66
+
67
+ # Duplicate email mapping (same person, multiple emails)
68
+ Sertug17 <104278804+Sertug17@users.noreply.github.com> <srhtsrht17@gmail.com>
69
+ yyovil <birdiegyal@gmail.com> <tanishq231003@gmail.com>
70
+ DomGrieco <dgrieco@redhat.com> <dgrieco@redhat.com>
71
+ dsocolobsky <dsocolobsky@gmail.com> <dylan.socolobsky@lambdaclass.com>
72
+ olafthiele <programming@olafthiele.com> <olafthiele@gmail.com>
73
+
74
+ # Verified via git display name matching GH contributor username
75
+ cokemine <aptx4561@gmail.com> <aptx4561@gmail.com>
76
+ dalianmao000 <dalianmao0107@gmail.com> <dalianmao0107@gmail.com>
77
+ emozilla <emozilla@nousresearch.com> <emozilla@nousresearch.com>
78
+ jjovalle99 <juan.ovalle@mistral.ai> <juan.ovalle@mistral.ai>
79
+ kagura-agent <kagura.chen28@gmail.com> <kagura.chen28@gmail.com>
80
+ spniyant <niyant@spicefi.xyz> <niyant@spicefi.xyz>
81
+ olafthiele <programming@olafthiele.com> <programming@olafthiele.com>
82
+ r266-tech <r2668940489@gmail.com> <r2668940489@gmail.com>
83
+ xingkongliang <tianliangjay@gmail.com> <tianliangjay@gmail.com>
84
+ win4r <win4r@outlook.com> <win4r@outlook.com>
85
+ zhouboli <zhouboli@gmail.com> <zhouboli@gmail.com>
86
+ yongtenglei <yongtenglei@gmail.com> <yongtenglei@gmail.com>
87
+
88
+ # Nous Research team
89
+ benbarclay <ben@nousresearch.com> <ben@nousresearch.com>
90
+ yoniebans <jonny@nousresearch.com> <jonny@nousresearch.com>
91
+
92
+ # GH contributor list verified
93
+ spideystreet <dhicham.pro@gmail.com> <dhicham.pro@gmail.com>
94
+ dorukardahan <dorukardahan@hotmail.com> <dorukardahan@hotmail.com>
95
+ MustafaKara7 <karamusti912@gmail.com> <karamusti912@gmail.com>
96
+ Hmbown <hmbown@gmail.com> <hmbown@gmail.com>
97
+ kamil-gwozdz <kamil@gwozdz.me> <kamil@gwozdz.me>
98
+ kira-ariaki <kira@ariaki.me> <kira@ariaki.me>
99
+ knopki <knopki@duck.com> <knopki@duck.com>
100
+ Unayung <unayung@gmail.com> <unayung@gmail.com>
101
+ SeeYangZhi <yangzhi.see@gmail.com> <yangzhi.see@gmail.com>
102
+ Julientalbot <julien.talbot@ergonomia.re> <julien.talbot@ergonomia.re>
103
+ lesterli <lisicheng168@gmail.com> <lisicheng168@gmail.com>
104
+ JiayuuWang <jiayuw794@gmail.com> <jiayuw794@gmail.com>
105
+ tesseracttars-creator <tesseracttars@gmail.com> <tesseracttars@gmail.com>
106
+ xinbenlv <zzn+pa@zzn.im> <zzn+pa@zzn.im>
107
+ SaulJWu <saul.jj.wu@gmail.com> <saul.jj.wu@gmail.com>
108
+ angelos <angelos@oikos.lan.home.malaiwah.com> <angelos@oikos.lan.home.malaiwah.com>
109
+ MestreY0d4-Uninter <241404605+MestreY0d4-Uninter@users.noreply.github.com> <MestreY0d4-Uninter@users.noreply.github.com>
.npmrc ADDED
@@ -0,0 +1,63 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # needed to prevent bad npm that has min-release-age but not exclude
2
+ engine-strict=true
3
+
4
+ min-release-age=14
5
+ # allow assistant-ui packages & a couple specific deps since they update a LOT.
6
+ # remove this when we stabilize (or we haven't updated in 2 wks)
7
+ min-release-age-exclude[]=@assistant-ui/*
8
+ min-release-age-exclude[]=assistant-cloud
9
+ min-release-age-exclude[]=assistant-stream
10
+ min-release-age-exclude[]=@radix-ui/*
11
+ min-release-age-exclude[]=radix-ui
12
+ min-release-age-exclude[]=safe-content-frame
13
+
14
+ # react-router 8.3.0 includes fixes for vulns. remove this when 8.3.0 is > 2wks old.
15
+ min-release-age-exclude[]=react-router
16
+
17
+ # eslint 10.8.0 includes fixes for vulns. remove this when 10.8.0 is > 2wks old.
18
+ min-release-age-exclude[]=eslint
19
+ min-release-age-exclude[]=@eslint/*
20
+
21
+ # tar 7.5.21 includes fixes for vulns. remove this when 7.5.21 is > 2wks old
22
+ min-release-age-exclude[]=tar
23
+
24
+ # concurrently 10.0.4 includes fixes for vulns. remove this when 10.0.4 is > 2wks old
25
+ min-release-age-exclude[]=concurrently
26
+
27
+ # fast-uri 3.1.4 includes fixes for vulns. remove this when 3.1.4 is > 2wks old
28
+ min-release-age-exclude[]=fast-uri
29
+
30
+ # minimatch 10.2.6 includes fixes for vulns. remove this when 10.2.6 is > 2wks old
31
+ min-release-age-exclude[]=minimatch
32
+
33
+
34
+ # brace-expansion 5.0.9 includes fixes for vulns. remove this when 5.0.9 is > 2wks old
35
+ min-release-age-exclude[]=brace-expansion
36
+
37
+ # js-yaml 4.3.1 includes fixes for GHSA-5p4m-2wfm-xmqj. remove when > 2wks old (rel 2026-07-31)
38
+ min-release-age-exclude[]=js-yaml
39
+
40
+ # nanoid 3.3.17 includes fixes for GHSA-2v37-7h3g-55p8. remove when > 2wks old (rel 2026-08-03)
41
+ min-release-age-exclude[]=nanoid
42
+
43
+ # mermaid 11.16.1 includes fixes for 5 GHSAs. remove when > 2wks old (rel 2026-08-04)
44
+ min-release-age-exclude[]=mermaid
45
+
46
+ # dompurify 3.4.13 includes fixes for GHSA-55q2-fjhq-7xh7. remove when > 2wks old (rel 2026-08-03)
47
+ min-release-age-exclude[]=dompurify
48
+
49
+ # vite 8.2.0 is the first release depending on rolldown >= 1.2.1, which fixes
50
+ # a rolldown panic that breaks `npm run build` in apps/desktop
51
+ # (rolldown/rolldown#10337 — a regression in 1.1.5, the version vite 8.1.5
52
+ # pins as ~1.1.5). @oxc-project/types is here because rolldown 1.2.1 pins it
53
+ # as `=0.142.0` — an exact pin, so no older release satisfies it and the age
54
+ # gate would fail the whole install with ETARGET.
55
+ # remove these once vite 8.2.0 is > 2wks old.
56
+ min-release-age-exclude[]=vite
57
+ min-release-age-exclude[]=rolldown
58
+ min-release-age-exclude[]=@rolldown/*
59
+ min-release-age-exclude[]=@oxc-project/types
60
+
61
+ # ink needs
62
+ min-release-age-exclude[]=lightningcss
63
+ min-release-age-exclude[]=postcss
.nvmrc ADDED
@@ -0,0 +1 @@
 
 
1
+ 26
.prettierignore ADDED
@@ -0,0 +1,4 @@
 
 
 
 
 
1
+ # Lockfiles must never be reformatted — main has a repo rule requiring
2
+ # team approval when lockfiles change, so an autofix PR touching one
3
+ # would hang waiting for review.
4
+ package-lock.json
.prettierrc ADDED
@@ -0,0 +1,11 @@
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "arrowParens": "avoid",
3
+ "bracketSpacing": true,
4
+ "endOfLine": "auto",
5
+ "printWidth": 120,
6
+ "semi": false,
7
+ "singleQuote": true,
8
+ "tabWidth": 2,
9
+ "trailingComma": "none",
10
+ "useTabs": false
11
+ }
.python-version ADDED
@@ -0,0 +1 @@
 
 
1
+ 3.11
AGENTS.md ADDED
@@ -0,0 +1,432 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Hermes Agent - Development Guide
2
+
3
+ Instructions for AI coding assistants and developers working on the hermes-agent codebase.
4
+ This root file holds only what applies everywhere. Each area has its own `AGENTS.md` (aim for
5
+ ~8k chars; `agent/subdirectory_hints.py` delivers up to 32k and truncates head/tail with a warning
6
+ past that); see the **routing table** at the end and read the area file before editing in that area.
7
+
8
+ **Never give up on the right solution.**
9
+
10
+ ## What Hermes Is
11
+
12
+ Hermes is a personal AI agent that runs the same agent core across a CLI, a messaging
13
+ gateway (Telegram, Discord, Slack, ~20 platforms), a TUI, and an Electron desktop app. It
14
+ learns across sessions (memory + skills), delegates to subagents, runs scheduled jobs, and
15
+ drives a real terminal and browser. It is extended primarily through **plugins and skills**,
16
+ not by growing the core.
17
+
18
+ Two invariants shape almost every design decision and are the lens for reviewing any change:
19
+
20
+ - **Per-conversation prompt caching is sacred.** A long-lived conversation reuses a cached
21
+ prefix every turn. Anything that mutates past context, swaps toolsets, reloads memories, or
22
+ rebuilds the system prompt mid-conversation invalidates that cache and multiplies the user's
23
+ cost. We do not do it; the ONE exception is context compression. Slash commands that mutate
24
+ system-prompt state (skills, tools, memory) must be **cache-aware**: default to deferred
25
+ invalidation (takes effect next session) with an opt-in `--now` flag (`/skills install --now`
26
+ is the canonical pattern).
27
+ - **The core is a narrow waist; capability lives at the edges.** Every model tool is sent on
28
+ every API call, so the bar for a new *core* tool is high. New capability should arrive as a
29
+ CLI command + skill, a service-gated tool, or a plugin — not as core surface.
30
+
31
+ ## Contribution Rubric — What We Want / What We Don't
32
+
33
+ The project's intent layer. It serves humans aiming a contribution AND the automated triage
34
+ sweeper, which may only close on `implemented_on_main`, `cannot_reproduce`, or `incoherent`.
35
+ Taste-based "out of scope" closes are a human maintainer's call; the sweeper's job is to
36
+ recognize design intent and *avoid wrongly closing a legitimate contribution*.
37
+
38
+ Read the balance right: Hermes ships a **lot**. Most merges are bug fixes to reported
39
+ behavior, and the product surface (platforms, providers, models, desktop/TUI features)
40
+ expands aggressively on purpose. The restraint below targets the **core agent + model tool
41
+ schema**, the one place where every addition is paid for on every API call. "Smallest
42
+ footprint" governs *how a capability is wired into the core*, not whether the product may
43
+ grow: expansive at the edges, conservative at the waist.
44
+
45
+ ### What we want
46
+
47
+ - **Fix real bugs, well.** Reproduce the symptom on current `main`, point to the exact line
48
+ where it manifests, and fix the whole bug class — sibling call paths included.
49
+ - **Expand reach at the edges.** New adapters, channels, providers, models, desktop/TUI/
50
+ dashboard features land routinely, including large ones — as long as they integrate with
51
+ the existing setup/config UX (`hermes tools`, `hermes setup`, auto-install) rather than
52
+ bolting on a raw env var.
53
+ - **Refactor god-files into clean modules.** Huge mechanical `+N/-N` extraction PRs are
54
+ wanted work. "Every line traces to the request" applies to *feature* PRs; a declared
55
+ refactor's request IS the extraction.
56
+ - **Keep the core narrow.** Prefer, in order: extend existing code → CLI command + skill →
57
+ service-gated tool (`check_fn`) → plugin → MCP server in the catalog → new core tool (last
58
+ resort). See the Footprint Ladder.
59
+ - **Extend, don't duplicate.** Check whether existing infrastructure covers the use case
60
+ before adding a module/manager/hook. When 3+ open PRs integrate the same *category*
61
+ (memory backends, providers, notifiers), design an ABC + orchestrator, wrap the existing
62
+ built-in as the first provider, and turn the competing PRs into plugins against it.
63
+ - **Behavior contracts over snapshots.** Tests assert how two pieces of data relate, never
64
+ freeze a current value (see Testing).
65
+ - **E2E validation, not just green unit mocks.** Anything touching resolution chains, config
66
+ propagation, security boundaries, remote backends, or file/network I/O must exercise the
67
+ real path with real imports against a temp `HERMES_HOME`. Mocks hide integration bugs.
68
+ - **Cache-, alternation-, and invariant-safe.** Preserve prompt caching, strict role
69
+ alternation (never two same-role messages in a row; never a synthetic user message injected
70
+ mid-loop), and a system prompt byte-stable for the life of a conversation.
71
+ - **Contributor credit preserved.** Salvage external work by cherry-picking (rebase-merge) so
72
+ authorship survives; build on top rather than reimplementing.
73
+
74
+ ### What we don't want (rejected even when well-built)
75
+
76
+ - **Speculative infrastructure.** Hooks/callbacks/extension points with no concrete consumer.
77
+ Adding a hook is easy; removing one after plugins depend on it is hard. A hook with a real,
78
+ stated use case is NOT speculative even if the consumer ships separately.
79
+ - **New `HERMES_*` env vars for non-secret config.** `.env` is for secrets only. Behavioral
80
+ settings (timeouts, thresholds, flags, display prefs) go in `config.yaml`; bridge to an
81
+ internal env var in code if the mechanism needs one. Reject "set X in your .env" docs
82
+ unless X is a credential.
83
+ - **A new core tool when terminal + file (or a skill) already do the job.** If the only
84
+ barrier is file visibility on a remote backend, fix the mount, not the toolset.
85
+ - **Lazy-reading escape hatches on instructional tools.** No `offset`/`limit` pagination on
86
+ tools that load content the agent must read fully (skills, prompts, playbooks) — models
87
+ read page 1 and skip the rest.
88
+ - **"Fixes" that destroy the feature they secure.** Read the original intent
89
+ (`git log -p -S`) before restricting behavior; find a fix that preserves the feature.
90
+ - **Outbound telemetry / usage attribution without opt-in gating.** No analytics,
91
+ third-party identifier tagging, or attribution tags until a generic user-facing opt-in
92
+ (config gate + setup prompt + `hermes tools` toggle) exists. Park behind a label.
93
+ - **Change-detector tests, cache-breaking mid-conversation, dead code wired in without E2E
94
+ proof, plugins that touch core files.** Plugins work within the ABCs/hooks we provide; if
95
+ one needs more, widen the generic plugin surface, never special-case it in core.
96
+ - **Third-party products integrated into the core tree.** Observability backends, vendor
97
+ SaaS connectors, analytics dashboards, and other "someone else's product" plugins do NOT
98
+ land under `plugins/` — every one becomes our burden against a fast-moving core for a
99
+ backend we don't own. Ship as a **standalone plugin repo** (`~/.hermes/plugins/` or pip
100
+ entry point), promoted in the Nous Research Discord `#plugins-skills-and-skins`. This is a
101
+ coupling decision, not a quality bar; such PRs are closed with a pointer to publish.
102
+
103
+ ### Before you call it a bug — verify the premise (and when NOT to close)
104
+
105
+ The most common reason a well-written PR is closed is a **wrong premise** or treating an
106
+ **intentional design as a gap**. These patterns tell a reviewer what to scrutinize and tell
107
+ the sweeper when a PR is NOT safe to close (when in doubt, leave it open for a human):
108
+
109
+ - **"Intentional design, not a gap."** Ask whether the isolation IS the design. Profiles are
110
+ independent islands on purpose: a PR adding live config inheritance from the default
111
+ profile was closed because coupling profiles is exactly what the design prevents (`--clone`
112
+ already covers "start from my default"). Read `git log -p -S "<symbol>"` before assuming
113
+ something is unfinished.
114
+ - **"The premise doesn't hold against how X actually works."** Trace the real runtime before
115
+ accepting a rationale. Real closes: a rate-limit "re-probe during cooldown" PR (the breaker
116
+ trips only on a *confirmed-empty* bucket, so re-probing hammers a bucket proven empty); a
117
+ usage fix whose new branch **never executes** because an earlier guard already popped the
118
+ state. If you can't point to the exact line where the bug manifests AND show the fix changes
119
+ that line's behavior, the premise is unverified.
120
+ - **"The absence was deliberate."** Restoring "missing" `__init__.py` files made a test tree
121
+ importable as a dotted package that shadowed the real plugin and deleted its `register()`
122
+ at import time. The omission was load-bearing.
123
+ - **"Overreached / resurrected an approach we moved past."** Scope creep beyond the agreed
124
+ base, or reviving a direction maintainers closed, is rejected even when it works. Offer the
125
+ rest as a focused follow-up.
126
+
127
+ Throughline: **verify the claim AND the intent against the codebase before writing or merging
128
+ a fix.** A reproduction on current `main` plus a line-level account beats a plausible
129
+ rationale. When unsure about intent, asking is cheaper than shipping a fix that fights the
130
+ design.
131
+
132
+ ### The Footprint Ladder (new capability decision)
133
+
134
+ Choose the highest (least-footprint) rung that correctly solves the problem:
135
+
136
+ 1. **Extend existing code** — a variation of something that exists. Zero new surface.
137
+ 2. **CLI command + skill** — config/state/infra expressible as shell commands; the agent runs
138
+ `hermes <subcommand>` guided by a skill. Default for subscriptions, scheduled tasks,
139
+ service setup (`hermes webhook`, `hermes cron`, `hermes tools`).
140
+ 3. **Service-gated tool (`check_fn`)** — needs structured params/returns AND only appears when
141
+ a prerequisite is configured (Home Assistant tools, memory-provider tools). This rung gates
142
+ reachability/opt-in process-wide; a capability that varies per SESSION (who is watching) is
143
+ a named toolset folded in by the toolset resolver, not a `check_fn` — see "Surface capability
144
+ is a property of the SESSION" below.
145
+ 4. **Plugin** — third-party/niche/user-specific; lives in `~/.hermes/plugins/` or a pip
146
+ package, discovered at runtime.
147
+ 5. **MCP server (in the catalog)** — genuinely a tool but not core-fundamental. Zero permanent
148
+ core-schema footprint, reusable by any MCP host, reached via the built-in MCP client.
149
+ 6. **New core tool** — only when fundamental, broadly useful to nearly every user, and
150
+ unreachable via terminal + file or an MCP server (terminal, read_file, web_search,
151
+ browser_navigate).
152
+
153
+ ### Surface capability is a property of the SESSION, never of the process env
154
+
155
+ A tool that works only because of *who is on the other end* (desktop panes, in-app browser,
156
+ message reactions, Projects) must resolve availability from the **session's own source**, not
157
+ from an env var on the backend. Client and backend are separate machines: the desktop app may
158
+ drive a locally spawned backend, one over SSH, one behind URL + token, or Hermes Cloud, and
159
+ only the first two carry `HERMES_DESKTOP=1`. An env-keyed gate is a silent no-op on the other
160
+ topologies — the tool is stripped from the schema while the platform hint tells the model it
161
+ is "inside the Hermes desktop app". The pattern:
162
+
163
+ - **The toolset is the surface gate.** Keep such tools off `_HERMES_CORE_TOOLS` and in a named
164
+ toolset (`desktop_ui`, `project`); the GUI gateway's `_load_enabled_toolsets(platform)`
165
+ folds it in when the session's platform says GUI. One resolver, every topology.
166
+ - **`check_fn` answers reachability or opt-in, not surface.** "Is the bridge wired?" — fine.
167
+ "Was I spawned by Electron?" — not. `check_fn` results are TTL-cached process-wide
168
+ (`tools/registry.py`); a per-session answer does not belong there.
169
+ - **Ask which identity you mean.** `HERMES_DESKTOP=1` legitimately means "this backend was
170
+ spawned by the app" (cron ticker, web-dist handling). It does NOT mean "a GUI is watching";
171
+ the embedded terminal pane (`hermes --tui` against that backend) is the counterexample.
172
+
173
+ Test: if the capability still makes sense with the client on another machine, it is
174
+ session-scoped. Assert the GUI session gets the tool **with the env var absent**.
175
+
176
+ ## Development Environment
177
+
178
+ ```bash
179
+ source .venv/bin/activate # or: source venv/bin/activate
180
+ ```
181
+ `scripts/run_tests.sh` probes `.venv`, then `venv`, then `$HOME/.hermes/hermes-agent/venv`
182
+ (worktrees sharing the main checkout's venv).
183
+
184
+ ## Project Structure
185
+
186
+ Counts shift constantly; the filesystem is canonical. Load-bearing entry points:
187
+
188
+ ```
189
+ hermes-agent/
190
+ ├── run_agent.py # AIAgent facade; the turn loop lives in agent/turn_*.py
191
+ ├── model_tools.py # Tool orchestration, discover_builtin_tools(), handle_function_call()
192
+ ├── toolsets.py # TOOLSETS dict, _HERMES_CORE_TOOLS
193
+ ├── cli.py # HermesCLI (REPL, slash dispatch) + hermes_cli/cli_*_mixin.py
194
+ ├── hermes_state.py # SessionDB facade; hermes_state_*.py siblings
195
+ ├── hermes_constants.py # get_hermes_home(), display_hermes_home() — profile-aware paths
196
+ ├── hermes_logging.py # agent.log / errors.log / gateway.log (profile-aware)
197
+ ├── batch_runner.py # Parallel batch processing
198
+ ├── agent/ # turn_*.py loop phases, providers, memory, compression, prompt builder
199
+ ├── hermes_cli/ # CLI subcommands, setup, config, plugins loader, skins, updater
200
+ │ └── web_routers/ # Dashboard FastAPI routers (one per surface); web_server.py mounts them
201
+ ├── tools/ # Tool implementations, auto-discovered via tools/registry.py
202
+ │ └── environments/ # Terminal backends (local, docker, ssh, modal, daytona, singularity)
203
+ ├── gateway/ # run.py facade + run_*.py phases + session*.py + platforms/
204
+ │ ├── platforms/ # One adapter per platform; see platforms/ADDING_A_PLATFORM.md
205
+ │ └── builtin_hooks/ # Always-registered gateway hooks (extension point; none shipped)
206
+ ├── plugins/ # memory/, context_engine/, model-providers/, kanban/, image_gen/, ...
207
+ ├── skills/ # Built-in skills (by category) optional-skills/: shipped, not active
208
+ ├── ui-tui/ # Ink (React) terminal UI — `hermes --tui`
209
+ ├── tui_gateway/ # Python JSON-RPC backend for TUI + Desktop — server.py + methods_*.py
210
+ ├── apps/desktop/ # Electron desktop app (+ apps/shared JSON-RPC client) web/: dashboard SPA
211
+ ├── acp_adapter/ # ACP server (VS Code / Zed / JetBrains)
212
+ ├── cron/ # jobs.py + scheduler.py (+ scheduler_*.py)
213
+ ├── evals/ # Offline benchmarks (codebase_navigability/, compaction/, ...)
214
+ ├── scripts/ # run_tests.sh, release.py, check_compat_pointers.py, ci/
215
+ ├── website/ # Docusaurus docs (developer-guide/ holds the long-form area docs)
216
+ └── tests/ # Pytest suite (~39k tests / ~3.7k files, Sep 2026)
217
+ ```
218
+
219
+ **User state:** `~/.hermes/config.yaml` (settings), `~/.hermes/.env` (secrets only),
220
+ `~/.hermes/logs/` (`agent.log` INFO+, `errors.log` WARNING+, `gateway.log`); all
221
+ profile-aware via `get_hermes_home()`. Browse logs with `hermes logs [--follow] [--level] [--session]`.
222
+
223
+ **Dependency chain:** `tools/registry.py` (no deps) ← `tools/*.py` (register at import) ←
224
+ `model_tools.py` (discovery) ← `run_agent.py`, `cli.py`, `batch_runner.py`, `environments/`.
225
+
226
+ ### Facade + siblings layout (Sep 2026 decomposition)
227
+
228
+ Every former god file is a **facade** (public entry points + the names other packages import)
229
+ plus **siblings** `<stem>_<topic>.py` in the same directory, each owning one topic. Largest
230
+ families: `hermes_state.py` (21), `gateway/run.py` (15), `tools/mcp_tool.py` (15),
231
+ `hermes_cli/kanban.py` (14), `hermes_cli/web_server.py` (13 + 24 routers), `hermes_cli/auth.py`
232
+ (12), `tools/browser_tool.py` (11), `cli.py` (12 `hermes_cli/cli_*_mixin.py`), `run_agent.py`
233
+ (`agent/turn_*.py`, `agent_init.py`, `conversation_loop.py`).
234
+
235
+ - **Find code by topic, not by facade:** `grep -rn "def name" <dir>/<stem>_*.py`. Reading the
236
+ facade first is the expensive way (`evals/codebase_navigability/`).
237
+ - **Siblings may import each other and late-import the facade** inside functions. A facade
238
+ never imports a sibling at module level *and* gets imported by that sibling at module level.
239
+ - **Patch where production reads.** Siblings often do `from <facade> import name` inside the
240
+ function so `monkeypatch.setattr(facade, "name", ...)` is the seam; a patch on the defining
241
+ module passes silently. Check the call site's binding before writing a patch target
242
+ (blind repointing to defining modules broke 130+ tests).
243
+ - **Compat pointers are OFF LIMITS in-tree.** Old import paths kept alive for external plugins
244
+ (`PLUGIN-COMPAT` blocks, `COMPAT_MANIFEST.md`, `compat_manifest.json`) must not be used by
245
+ in-tree code or tests; `scripts/check_compat_pointers.py` runs in CI, and
246
+ `-W error::hermes_cli.plugin_compat.HermesPluginCompatWarning` catches them in the suite.
247
+ They are removed 2026-09-14 by reverting one commit. Import from the defining module.
248
+ - **Don't recreate god files.** A file passing ~2,000 lines or a function passing ~300 lines /
249
+ cyclomatic complexity 30 is the signal to split along `<stem>_<topic>` FIRST, in its own
250
+ commit. New behaviour goes in a new or topical sibling — never appended to a facade.
251
+ - **No `if/elif` ladders ≥ 4 branches keyed on a name/kind** — use a dict/table → handler
252
+ (`_SLASH_DISPATCH` in `cli.py`, `_command_handler_table` in the gateway are the shape).
253
+ - **No re-export shims for internal moves** ("keep the old name importable"). Internal paths
254
+ are not API; external compat is handled ONCE by the compat layer, not per PR.
255
+ - **Moving a symbol means fixing its docs in the same PR:** grep `website/docs`,
256
+ `skills/`, and every `AGENTS.md` for the old `path.py` + symbol (23 doc files went stale
257
+ after the refactor). `evals/codebase_navigability/static_metrics.py <tree> <label>` measures
258
+ file/function/CC/elif distributions before/after a large PR in ~2 min.
259
+
260
+ ## Code Shape Rules (all languages)
261
+
262
+ - No "defense-in-depth" wrappers, `try/except: pass` around code that cannot fail, or flags
263
+ nobody sets. Docstrings/comments keep the WHY, cut the WHAT.
264
+ - **Never infer process identity from argv substrings** (`"serve" in cmdline`) — the bug class
265
+ behind ~10 fleet-update issues (#90778, #87594, #78089, #76129, #91964). Use the canonical
266
+ matchers `gateway.status.looks_like_gateway_command_line` and
267
+ `hermes_cli.update_cmd._hermes_holder_subcommand`; flag sets are DERIVED from the parser
268
+ (`_holder_value_flags()`), never hand-written; match FULL cmdlines and truncate only for
269
+ display. Details: `hermes_cli/AGENTS.md`.
270
+ - **Never hardcode `~/.hermes`.** `get_hermes_home()` for code paths, `display_hermes_home()`
271
+ for user-facing text (both from `hermes_constants`). Hardcoding breaks profiles (5 bugs in
272
+ PR #3575). Module-level constants are fine — they cache after `_apply_profile_override()`
273
+ sets `HERMES_HOME`. Profile operations themselves are HOME-anchored
274
+ (`_get_profiles_root()` = `Path.home()/.hermes/profiles`) so `hermes -p x profile list`
275
+ sees all profiles — intentional, not a bug.
276
+ - **Argparse alias dispatch:** `add_parser("list", aliases=["ls"])` sets `dest` to the literal
277
+ the user typed (`"ls"`). Dispatch must accept both (caught PTY-testing `hermes webhook ls`).
278
+ - **Don't wire in dead code without E2E validation.** Unshipped code was dead for a reason;
279
+ E2E the real resolution chain with real imports against a temp `HERMES_HOME` first.
280
+
281
+ ### TypeScript style (desktop, TUI, website, future TS packages)
282
+
283
+ Small nanostores over component state when state is shared or read by distant UI; each
284
+ feature owns its atoms (chat near chat, shared in `src/store`); rendering components use
285
+ `useStore`, non-rendering actions read `$atom.get()`; never thread state through three
286
+ components when the leaf can subscribe; persistence sits beside the atom that owns it. Route
287
+ roots stay thin (compose routes + shell, never controllers). No monolithic hooks — one narrow
288
+ job each; colocated action modules over god hooks. Pure side-effect callbacks use the terse
289
+ void form `onState={st => void setGatewayState(st)}`; async handlers make intent explicit
290
+ `onClick={() => void save()}`. Interfaces for public props and shared object shapes (not
291
+ `type X = {...}`); extend React primitives (`React.ComponentProps<'button'>`, `Omit`, `Pick`).
292
+ Table-driven beats condition ladders for ids/routes/views. `src/app` owns routes/pages,
293
+ `src/store` shared atoms, `src/lib` pure helpers.
294
+
295
+ ## Dependency Pinning Policy
296
+
297
+ All dependencies carry upper bounds (litellm compromise #2796/#2810; Mini Shai-Hulud worm,
298
+ May 2026). PyPI: `>=floor,<next_major` (`"httpx>=0.28.1,<1"`); pre-1.0: `<0.(minor+2)`
299
+ (`>=0.29,<0.32`). Git URLs: 40-char commit SHA. GitHub Actions: SHA + `# vN` comment. CI-only
300
+ pip: `==exact`. A bare `>=X.Y.Z` is rejected by CI and reviewers. Run `uv lock` after
301
+ changing `pyproject.toml`. Reference: #2810 (bounds), #9801 (SHA pinning + audit CI).
302
+
303
+ ## Commits, Merges, PRs
304
+
305
+ - **Squash merges from stale branches silently revert recent fixes.** Before squash-merging,
306
+ bring the branch to `main` (`git fetch origin main && git reset --hard origin/main`, re-apply
307
+ the PR's commits). Verify with `git diff HEAD~1..HEAD` after merging — unexpected deletions
308
+ are a red flag.
309
+ - Salvage by cherry-pick so contributor authorship survives (see rubric).
310
+ - Tests per fix: 1–2 INVARIANT tests (behaviour contract, proven red on base), never
311
+ change-detectors; ≤ 2 tests is the salvage bar too. Reject/rewrite in salvaged diffs:
312
+ appendages to facades, new god helpers, compat aliases, wrappers.
313
+
314
+ ## Testing (applies everywhere)
315
+
316
+ **ALWAYS use `scripts/run_tests.sh`**, never bare `pytest`. It enforces CI parity: credential
317
+ vars unset, `TZ=UTC`, `LANG=C.UTF-8`, `HERMES_HOME` → temp dir, and per-file subprocess
318
+ isolation via `scripts/run_tests_parallel.py` (no xdist; workers scale with CPU count) so
319
+ module-level dicts/ContextVars cannot leak between files. Direct `pytest` on a big machine
320
+ with API keys set has caused repeated "works locally, fails in CI" incidents (and the reverse).
321
+
322
+ ```bash
323
+ scripts/run_tests.sh # full suite
324
+ scripts/run_tests.sh tests/gateway/ # one directory
325
+ scripts/run_tests.sh tests/agent/test_foo.py -k test_x # runner is file-granular; -k narrows
326
+ scripts/run_tests.sh -v --tb=long # pytest flags pass through
327
+ ```
328
+
329
+ - **Flake policy:** a failing FILE is retried once in a fresh subprocess (`--file-retries`;
330
+ `HERMES_TEST_FILE_RETRIES=0` disables). Pass-on-retry is green but printed under `⚠ FLAKY`
331
+ with both outputs — a bug to fix, not noise. Timing tests must not assume a quiet runner:
332
+ wall-clock bounds ≥ 2s, event-based sync, no `assert not _wait_until(...)` races.
333
+ - **Placement mirrors the source tree.** A test lives in `tests/<top-level source dir>/` (`tests/hermes_cli/`,
334
+ `tests/agent/`, `tests/hermes_state/`, `tests/gateway/relay/`, ...); installer/updater script tests
335
+ under `tests/scripts/{install,desktop_update}/`. Only tests of root-level modules (`batch_runner`,
336
+ `utils`, `hermes_constants`, packaging) sit directly in `tests/`. No issue numbers in filenames —
337
+ cite the issue in the module docstring (`test_89315_x.py` → `test_x.py`, "Regression for #89315").
338
+ - **Placement (CI lanes):** `scripts/ci/classify_changes.py` picks jobs by changed files. A Python test
339
+ asserting about `package.json`, `package-lock.json`, `tsconfig.json`, or `.ts/.tsx/.js/
340
+ .mjs/.cjs` sources will not run on a JS-only PR (green on PR, red on `main` where the
341
+ classifier fails open). Such tests belong in the vitest suite, not `tests/*.py`.
342
+ - **Tests must not write to `~/.hermes/`.** The autouse `_isolate_hermes_home` fixture in
343
+ `tests/conftest.py` redirects `HERMES_HOME`; never hardcode `~/.hermes/` in tests. Profile
344
+ tests also mock `Path.home()` so `_get_profiles_root()` / `_get_default_hermes_home()` stay
345
+ in the temp dir (pattern: `tests/hermes_cli/test_profiles.py`):
346
+ ```python
347
+ @pytest.fixture
348
+ def profile_env(tmp_path, monkeypatch):
349
+ home = tmp_path / ".hermes"; home.mkdir()
350
+ monkeypatch.setattr(Path, "home", lambda: tmp_path)
351
+ monkeypatch.setenv("HERMES_HOME", str(home))
352
+ return home
353
+ ```
354
+ Tests that `patch.object(Path, "home", ...)` must ALSO set `HERMES_HOME` — code reads the
355
+ env var, not `Path.home()/.hermes`.
356
+
357
+ ### Don't fake the host OS
358
+
359
+ Behaviour that genuinely differs per host is tested ON that host with `@pytest.mark.linux_only`
360
+ / `macos_only` / `windows_only`, never by patching `sys.platform`. Host-independent things stay
361
+ unmarked: pure functions that take the platform as data (`hidden_windows_child_options(opts,
362
+ is_windows=True)`) and declaration/packaging invariants ("pyproject declares `tzdata` with a
363
+ `sys_platform == 'win32'` marker"). Setting a module-level `IS_WINDOWS` flag and calling
364
+ `windows_detach_flags()` IS a fake. The line: **if the test needs the interpreter to believe it
365
+ is on another OS to pass, it belongs on that OS.** A test that walks several platforms in
366
+ sequence is split — host-native arm on Linux, other arms as their own marked tests.
367
+
368
+ **Use the marker, never a bare `skipif`.** `scripts/ci/list_os_marked_tests.py` finds files for
369
+ the macOS/Windows lanes by grepping the marker *name*, then filters with `-m <marker>`. A
370
+ `skipif(sys.platform != "win32")` test skips on Linux AND is never imported on Windows — it runs
371
+ nowhere, silently. A file-local alias (`windows_only = pytest.mark.skipif(...)`) is listed but
372
+ `-m windows_only` deselects everything: green over zero coverage. Don't `pytest.skip()` non-host
373
+ rows of a platform `@parametrize` — split into one marked test per OS.
374
+
375
+ **Live Windows process-topology E2E (`wine2e` lane):** `windows-venv-e2e.yml` runs
376
+ `tests/hermes_cli/test_venv_holder_windows_live.py` on a real `windows-latest` runner (real
377
+ processes, no mocked psutil) ONLY on pushes to `wine2e/**` branches. Workflow: write probes
378
+ pinning CORRECT behavior, push to `wine2e/` to reproduce live on unfixed code, fix, iterate to
379
+ green, then open the PR with the live receipt. Extend it when touching that subsystem; assert
380
+ against the gateway ANCESTOR found by argv, not the direct parent (the venv shim makes every
381
+ spawn a launcher/worker chain).
382
+
383
+ ### Don't write change-detector tests
384
+
385
+ A change-detector fails whenever data *expected to change* is updated — model catalogs,
386
+ `_config_version`, enumeration counts, hardcoded model lists. It adds no coverage and taxes
387
+ every routine update. Don't: `assert "gemini-2.5-pro" in _PROVIDER_MODELS["gemini"]`,
388
+ `assert DEFAULT_CONFIG["_config_version"] == 21`, `assert len(models) == 8`. Do: `assert
389
+ "gemini" in _PROVIDER_MODELS and len(_PROVIDER_MODELS["gemini"]) >= 1` (plumbing works);
390
+ `assert raw["_config_version"] == DEFAULT_CONFIG["_config_version"]` (migration reaches
391
+ latest); `assert not (set(moonshot_models) & coding_plan_only_models)` (no leak); every
392
+ catalog model has a context-length entry (relationship). If it reads like a snapshot, delete
393
+ it; if it reads like a contract between two pieces of data, keep it. Reviewers reject new
394
+ change-detectors; authors convert them before re-review.
395
+
396
+ ### Never read source code in tests
397
+
398
+ A test that reads a `.py`/`.ts`/`.tsx` file's text tests the *shape of the source*, not
399
+ behavior — banned outright. It passes when the implementation is subtly broken (regex matches
400
+ a mis-wired call site) and fails on correct refactors; it can't run against bundled/minified
401
+ artifacts; it blocks structural cleanup; it gives false confidence. Don't
402
+ `fs.readFileSync('main.ts')` + `assert.match(source, /spawn\(...hiddenWindowsChildOptions/)`.
403
+ Do extract the logic into a pure/DI-testable function and call it:
404
+ ```ts
405
+ export function hiddenWindowsChildOptions(options = {}, isWindows = process.platform === 'win32') {
406
+ if (!isWindows || 'windowsHide' in options) return options
407
+ return { ...options, windowsHide: true }
408
+ }
409
+ ```
410
+ If the logic lives inline in a god-file and extraction feels disruptive, that is the signal to
411
+ extract, not to regex around it.
412
+
413
+ ## Routing Table — working in X → read X/AGENTS.md
414
+
415
+ | Area | Read | Covers |
416
+ |---|---|---|
417
+ | `run_agent.py`, `agent/` | `agent/AGENTS.md` | AIAgent + mixins, turn phases, caching integrity, message-flow invariants, compression, model/aux resolution |
418
+ | `cli.py`, `hermes_cli/`, `main.py` | `hermes_cli/AGENTS.md` | CLI mixins, `_SLASH_DISPATCH`, slash registry, config system + loaders, skins, `hermes update` pipeline, profiles / multiplex |
419
+ | `gateway/` | `gateway/AGENTS.md` | Adapters, two message guards, streaming contract, background notifications, gateway vs desktop lifecycle, token locks, scoped secrets |
420
+ | `tools/`, `toolsets.py`, `model_tools.py` | `tools/AGENTS.md` | Adding tools, registry, toolsets, delegation, cross-tool references, backends |
421
+ | `plugins/`, `hermes_cli/plugins*.py` | `plugins/AGENTS.md` | Plugin kinds, native compat contract, in-tree policy, Sep-2026 compat window |
422
+ | `tui_gateway/`, `ui-tui/` | `tui_gateway/AGENTS.md` | Process model, JSON-RPC transport, key surfaces, slash flow, dev commands |
423
+ | `web/`, `hermes_cli/web_routers/` | `web/AGENTS.md` | Dashboard embeds the real TUI; what React may and may not rebuild |
424
+ | `apps/desktop/` | `apps/desktop/AGENTS.md`, `apps/desktop/src/AGENTS.md` | Desktop judgment guide; `serve` backend, slash palette curation, Bot Mode canonical chat |
425
+ | `skills/`, `optional-skills/`, `agent/curator*.py` | `skills/AGENTS.md` | Frontmatter, HARDLINE authoring standards, curator |
426
+ | `cron/`, kanban (`hermes_cli/kanban*.py`, `tools/kanban_tools.py`, `plugins/kanban/`) | `cron/AGENTS.md` | Scheduler invariants, job fields, kanban board/dispatcher |
427
+ | `gateway/platforms/` new adapter | `gateway/platforms/ADDING_A_PLATFORM.md` | Step-by-step adapter guide |
428
+
429
+ Long-form background lives in `website/docs/developer-guide/` (agent-loop, prompt-assembly,
430
+ context-compression-and-caching, gateway-internals, tools-runtime, plugins/, cron-internals,
431
+ session-storage, ...). Workflow rules (PR/issue/review/salvage process) live in the
432
+ `hermes-agent-dev` skill, not here.
COMPAT_MANIFEST.md ADDED
The diff for this file is too large to render. See raw diff
 
CONTRIBUTING.es.md ADDED
@@ -0,0 +1,602 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Contribuir a Hermes Agent
2
+
3
+ ¡Gracias por contribuir a Hermes Agent! Esta guía cubre todo lo que necesitas: configurar tu entorno de desarrollo, entender la arquitectura, decidir qué construir y conseguir que tu PR sea aceptado.
4
+
5
+ ---
6
+
7
+ ## Prioridades de Contribución
8
+
9
+ Valoramos las contribuciones en este orden:
10
+
11
+ 1. **Correcciones de errores** — bloqueos, comportamiento incorrecto, pérdida de datos. Siempre la máxima prioridad.
12
+ 2. **Compatibilidad entre plataformas** — macOS, diferentes distribuciones de Linux y WSL2 en Windows. Queremos que Hermes funcione en todas partes.
13
+ 3. **Fortalecimiento de seguridad** — inyección de shell, inyección de prompts, traversal de rutas, escalada de privilegios. Ver [Consideraciones de Seguridad](#consideraciones-de-seguridad).
14
+ 4. **Rendimiento y robustez** — lógica de reintento, manejo de errores, degradación elegante.
15
+ 5. **Nuevas habilidades** — pero solo las ampliamente útiles. Ver [¿Debería ser una Habilidad o una Herramienta?](#debería-ser-una-habilidad-o-una-herramienta)
16
+ 6. **Nuevas herramientas** — raramente necesarias. La mayoría de las capacidades deberían ser habilidades. Ver más abajo.
17
+ 7. **Documentación** — correcciones, aclaraciones, nuevos ejemplos.
18
+
19
+ ---
20
+
21
+ ## ¿Debería ser una Habilidad o una Herramienta?
22
+
23
+ Esta es la pregunta más común para los nuevos colaboradores. La respuesta casi siempre es **habilidad**.
24
+
25
+ ### Hazlo una Habilidad cuando:
26
+
27
+ - La capacidad se puede expresar como instrucciones + comandos de shell + herramientas existentes
28
+ - Envuelve una CLI externa o API que el agente puede llamar a través de `terminal` o `web_extract`
29
+ - No necesita integración personalizada de Python ni gestión de claves API integrada en el agente
30
+ - Ejemplos: búsqueda en arXiv, flujos de trabajo de git, gestión de Docker, procesamiento de PDF, email a través de herramientas CLI
31
+
32
+ ### Hazlo una Herramienta cuando:
33
+
34
+ - Requiere integración de extremo a extremo con claves API, flujos de autenticación o configuración de múltiples componentes gestionada por el harness del agente
35
+ - Necesita lógica de procesamiento personalizada que debe ejecutarse con precisión en cada ocasión (no "mejor esfuerzo" de la interpretación del LLM)
36
+ - Maneja datos binarios, streaming o eventos en tiempo real que no pueden pasar por el terminal
37
+ - Ejemplos: automatización de navegador (gestión de sesiones Browserbase), TTS (codificación de audio + entrega en plataforma), análisis de visión (manejo de imágenes base64)
38
+
39
+ ### ¿Debería la Habilidad estar incluida?
40
+
41
+ Las habilidades incluidas (en `skills/`) se envían con cada instalación de Hermes. Deben ser **ampliamente útiles para la mayoría de los usuarios**:
42
+
43
+ - Manejo de documentos, investigación web, flujos de trabajo de desarrollo comunes, administración de sistemas
44
+ - Usadas regularmente por una amplia gama de personas
45
+
46
+ Si tu habilidad es oficial y útil pero no universalmente necesaria (ej., una integración de servicio de pago, una dependencia pesada), ponla en **`optional-skills/`** — se envía con el repositorio pero no está activada por defecto. Los usuarios pueden descubrirla a través de `hermes skills browse` (etiquetada como "oficial") e instalarla con `hermes skills install` (sin advertencia de terceros, confianza integrada).
47
+
48
+ Si tu habilidad es especializada, contribuida por la comunidad o de nicho, es mejor para un **Skills Hub** — súbela a un registro de habilidades y compártela en el [Discord de Nous Research](https://discord.gg/NousResearch). Los usuarios pueden instalarla con `hermes skills install`.
49
+
50
+ ---
51
+
52
+ ## Proveedores de Memoria: Publicar como Plugin Independiente
53
+
54
+ **Ya no aceptamos nuevos proveedores de memoria en este repositorio.** El conjunto de proveedores integrados en `plugins/memory/` (honcho, mem0, supermemory, byterover, hindsight, holographic, openviking, retaindb) está cerrado. Si quieres añadir un nuevo backend de memoria, publícalo como un **repositorio de plugin independiente** que los usuarios instalen en `~/.hermes/plugins/` (o a través de un entry point de pip).
55
+
56
+ Los plugins de memoria independientes:
57
+
58
+ - Implementan el mismo ABC `MemoryProvider` (`agent/memory_provider.py`) — `sync_turn`, `prefetch`, `shutdown` y opcionalmente `post_setup(hermes_home, config)` para integración con el asistente de configuración
59
+ - Usan el mismo sistema de descubrimiento — `discover_memory_providers()` los recoge desde directorios de plugins de usuario/proyecto y entry points de pip
60
+ - Se integran con `hermes memory setup` a través de `post_setup()` — sin necesidad de tocar el código base
61
+ - Pueden registrar sus propios subcomandos CLI a través de `register_cli(subparser)` en un archivo `cli.py`
62
+ - Obtienen todos los mismos hooks de ciclo de vida y plomería de configuración que los proveedores incluidos en el árbol
63
+
64
+ Los PRs que añadan un nuevo directorio bajo `plugins/memory/` serán cerrados con un puntero para publicar el proveedor como su propio repositorio. Los proveedores en árbol existentes se mantienen; las correcciones de errores para ellos son bienvenidas.
65
+
66
+ Esto no es una barra de calidad — es una decisión de acoplamiento y mantenimiento. Los proveedores de memoria son el tipo de plugin más común y no deberían vivir todos en este árbol.
67
+
68
+ ---
69
+
70
+ ## Configuración del Desarrollo
71
+
72
+ ### Prerequisitos
73
+
74
+ | Requisito | Notas |
75
+ |-----------|-------|
76
+ | **Git** | Con la extensión `git-lfs` instalada |
77
+ | **Python 3.11–3.13** | uv lo instalará si falta |
78
+ | **uv** | Gestor de paquetes Python rápido ([instalar](https://docs.astral.sh/uv/)) |
79
+ | **Node.js 20+** | Opcional — necesario para herramientas de navegador y puente WhatsApp (coincide con los engines de `package.json` raíz) |
80
+
81
+ ### Clonar e instalar
82
+
83
+ ```bash
84
+ git clone https://github.com/NousResearch/hermes-agent.git
85
+ cd hermes-agent
86
+
87
+ # Crear venv con Python 3.11
88
+ uv venv venv --python 3.11
89
+ export VIRTUAL_ENV="$(pwd)/venv"
90
+
91
+ # Instalar con todos los extras (mensajería, cron, menús CLI, herramientas de desarrollo)
92
+ uv pip install -e ".[all,dev]"
93
+
94
+ # Opcional: herramientas de navegador
95
+ npm install
96
+ ```
97
+
98
+ ### Configurar para desarrollo
99
+
100
+ ```bash
101
+ mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
102
+ cp cli-config.yaml.example ~/.hermes/config.yaml
103
+ touch ~/.hermes/.env
104
+
105
+ # Añadir al menos una clave de proveedor LLM:
106
+ echo "OPENROUTER_API_KEY=***" >> ~/.hermes/.env
107
+ ```
108
+
109
+ ### Ejecutar
110
+
111
+ ```bash
112
+ # Enlace simbólico para acceso global
113
+ mkdir -p ~/.local/bin
114
+ ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
115
+
116
+ # Verificar
117
+ hermes doctor
118
+ hermes chat -q "Hola"
119
+ ```
120
+
121
+ ### Ejecutar tests
122
+
123
+ ```bash
124
+ # Preferido — coincide con CI (entorno hermético, 4 workers xdist); ver AGENTS.md
125
+ scripts/run_tests.sh
126
+
127
+ # Alternativa (activa el venv primero). El wrapper sigue recomendándose
128
+ # para paridad con GitHub Actions antes de abrir un PR:
129
+ pytest tests/ -v
130
+ ```
131
+
132
+ ---
133
+
134
+ ## Estructura del Proyecto
135
+
136
+ ```
137
+ hermes-agent/
138
+ ├── run_agent.py # Clase AIAgent — bucle de conversación central, despacho de herramientas, persistencia de sesión
139
+ ├── cli.py # Clase HermesCLI — TUI interactiva, integración prompt_toolkit
140
+ ├── model_tools.py # Orquestación de herramientas (capa delgada sobre tools/registry.py)
141
+ ├── toolsets.py # Agrupaciones y presets de herramientas (hermes-cli, hermes-telegram, etc.)
142
+ ├── hermes_state.py # Base de datos de sesiones SQLite con búsqueda de texto completo FTS5, títulos de sesión
143
+ ├── batch_runner.py # Procesamiento en lote paralelo para generación de trayectorias
144
+ │
145
+ ├── agent/ # Internos del agente (módulos extraídos)
146
+ │ ├── prompt_builder.py # Ensamblaje del prompt del sistema (identidad, habilidades, archivos de contexto, memoria)
147
+ │ ├── context_compressor.py # Auto-resumición al acercarse a los límites de contexto
148
+ │ ├── auxiliary_client.py # Resuelve clientes OpenAI auxiliares (resumición, visión)
149
+ │ ├── display.py # KawaiiSpinner, formateo del progreso de herramientas
150
+ │ ├── model_metadata.py # Longitudes de contexto del modelo, estimación de tokens
151
+ │ └── trajectory.py # Ayudantes para guardar trayectorias
152
+ │
153
+ ├── hermes_cli/ # Implementaciones de comandos CLI
154
+ │ ├── main.py # Punto de entrada, análisis de argumentos, despacho de comandos
155
+ │ ├── config.py # Gestión de configuración, migración, definiciones de variables de entorno
156
+ │ ├── setup.py # Asistente de configuración interactivo
157
+ │ ├── auth.py # Resolución de proveedor, OAuth, Nous Portal
158
+ │ ├── models.py # Listas de selección de modelos de OpenRouter
159
+ │ ├── banner.py # Banner de bienvenida, arte ASCII
160
+ │ ├── commands.py # Registro central de comandos de barra (CommandDef), autocompletado, ayudantes del gateway
161
+ │ ├── callbacks.py # Callbacks interactivos (aclarar, sudo, aprobación)
162
+ │ ├── doctor.py # Diagnósticos
163
+ │ ├── skills_hub.py # CLI del Skills Hub + comando de barra /skills
164
+ │ └── skin_engine.py # Motor de skins/temas — personalización visual de CLI basada en datos
165
+ │
166
+ ├── tools/ # Implementaciones de herramientas (auto-registradas)
167
+ │ ├── registry.py # Registro central de herramientas (esquemas, manejadores, despacho)
168
+ │ ├── approval.py # Detección de comandos peligrosos + aprobación por sesión
169
+ │ ├── terminal_tool.py # Orquestación del terminal (sudo, ciclo de vida del entorno, backends)
170
+ │ ├── file_operations.py # read_file, write_file, búsqueda, patch, etc.
171
+ │ ├── web_tools.py # web_search, web_extract (Paralelo/Firecrawl + resumición Gemini)
172
+ │ ├── vision_tools.py # Análisis de imágenes a través de modelos multimodales
173
+ │ ├── delegate_tool.py # Lanzamiento de subagentes y ejecución paralela de tareas
174
+ │ ├── code_execution_tool.py # Python sandboxado con acceso a herramientas vía RPC
175
+ │ ├── session_search_tool.py # Búsqueda en conversaciones pasadas con FTS5 + ventanas ancladas
176
+ │ ├── cronjob_tools.py # Gestión de tareas programadas
177
+ │ ├── skill_tools.py # Búsqueda, carga y gestión de habilidades
178
+ │ └── environments/ # Backends de ejecución del terminal
179
+ │ ├── base.py # ABC BaseEnvironment
180
+ │ ├── local.py, docker.py, ssh.py, singularity.py, modal.py, daytona.py
181
+ │
182
+ ├── gateway/ # Gateway de mensajería
183
+ │ ├── run.py # GatewayRunner — ciclo de vida de plataformas, enrutamiento de mensajes, cron
184
+ │ ├── config.py # Resolución de configuración de plataformas
185
+ │ ├── session.py # Almacén de sesiones, prompts de contexto, políticas de reset
186
+ │ └── platforms/ # Adaptadores de plataformas
187
+ │ ├── telegram.py, discord_adapter.py, slack.py, whatsapp.py
188
+ │
189
+ ├── scripts/ # Scripts del instalador y puente
190
+ │ ├── install.sh # Instalador Linux/macOS
191
+ │ ├── install.ps1 # Instalador Windows PowerShell
192
+ │ └── whatsapp-bridge/ # Puente WhatsApp Node.js (Baileys)
193
+ │
194
+ ├── skills/ # Habilidades incluidas (copiadas a ~/.hermes/skills/ en la instalación)
195
+ ├── optional-skills/ # Habilidades opcionales oficiales (descubribles vía hub, no activadas por defecto)
196
+ ├── tests/ # Suite de tests
197
+ ├── website/ # Sitio de documentación (hermes-agent.nousresearch.com)
198
+ │
199
+ ├── cli-config.yaml.example # Configuración de ejemplo (copiada a ~/.hermes/config.yaml)
200
+ └── AGENTS.md # Guía de desarrollo para asistentes de codificación IA
201
+ ```
202
+
203
+ ### Configuración del usuario (almacenada en `~/.hermes/`)
204
+
205
+ | Ruta | Propósito |
206
+ |------|-----------|
207
+ | `~/.hermes/config.yaml` | Configuración (modelo, terminal, toolsets, compresión, etc.) |
208
+ | `~/.hermes/.env` | Claves API y secretos |
209
+ | `~/.hermes/auth.json` | Credenciales OAuth (Nous Portal) |
210
+ | `~/.hermes/skills/` | Todas las habilidades activas (incluidas + instaladas desde hub + creadas por el agente) |
211
+ | `~/.hermes/memories/` | Memoria persistente (MEMORY.md, USER.md) |
212
+ | `~/.hermes/state.db` | Base de datos de sesiones SQLite |
213
+ | `~/.hermes/sessions/` | Índice de enrutamiento del gateway (`sessions.json`), migas de pan de solicitudes, transcripciones `*.jsonl` del gateway y exportaciones explícitas con `/save`. Ya no se escriben snapshots JSON automáticos; los archivos existentes se conservan y state.db es canónica. |
214
+ | `~/.hermes/cron/` | Datos de trabajos programados |
215
+ | `~/.hermes/whatsapp/session/` | Credenciales del puente WhatsApp |
216
+
217
+ ---
218
+
219
+ ## Descripción General de la Arquitectura
220
+
221
+ ### Bucle Central
222
+
223
+ ```
224
+ Mensaje del usuario → AIAgent._run_agent_loop()
225
+ ├── Construir prompt del sistema (prompt_builder.py)
226
+ ├── Construir kwargs de API (modelo, mensajes, herramientas, configuración de razonamiento)
227
+ ├── Llamar al LLM (API compatible con OpenAI)
228
+ ├── Si tool_calls en la respuesta:
229
+ │ ├── Ejecutar cada herramienta a través del despacho del registro
230
+ │ ├── Añadir resultados de herramientas a la conversación
231
+ │ └── Volver a la llamada al LLM
232
+ ├── Si respuesta de texto:
233
+ │ ├── Persistir sesión en DB
234
+ │ └── Devolver final_response
235
+ └── Compresión de contexto si se acerca al límite de tokens
236
+ ```
237
+
238
+ ### Patrones de Diseño Clave
239
+
240
+ - **Herramientas auto-registradas**: Cada archivo de herramienta llama a `registry.register()` en el momento de importación. `model_tools.py` activa el descubrimiento importando todos los módulos de herramientas.
241
+ - **Agrupación en toolsets**: Las herramientas se agrupan en toolsets (`web`, `terminal`, `file`, `browser`, etc.) que pueden habilitarse/deshabilitarse por plataforma.
242
+ - **Persistencia de sesión**: Todas las conversaciones se almacenan en SQLite (`hermes_state.py`) con búsqueda de texto completo y títulos de sesión únicos.
243
+ - **Inyección efímera**: Los prompts del sistema y los mensajes de relleno se inyectan en el momento de la llamada API, nunca se persisten en la base de datos ni en los logs.
244
+ - **Abstracción de proveedor**: El agente funciona con cualquier API compatible con OpenAI. La resolución del proveedor ocurre en el momento de la inicialización.
245
+ - **Enrutamiento de proveedor**: Al usar OpenRouter, `provider_routing` en config.yaml controla la selección del proveedor.
246
+
247
+ ---
248
+
249
+ ## Estilo de Código
250
+
251
+ - **PEP 8** con excepciones prácticas (no imponemos longitud de línea estricta)
252
+ - **Comentarios**: Solo cuando se explica la intención no obvia, compromisos o peculiaridades de API. No narres lo que hace el código
253
+ - **Manejo de errores**: Captura excepciones específicas. Registra con `logger.warning()`/`logger.error()` — usa `exc_info=True` para errores inesperados
254
+ - **Multiplataforma**: Nunca asumas Unix. Ver [Compatibilidad Multiplataforma](#compatibilidad-multiplataforma)
255
+
256
+ ---
257
+
258
+ ## Añadir una Nueva Herramienta
259
+
260
+ Antes de escribir una herramienta, pregúntate: [¿debería ser una habilidad en su lugar?](#debería-ser-una-habilidad-o-una-herramienta)
261
+
262
+ Las herramientas se auto-registran en el registro central. Cada archivo de herramienta co-localiza su esquema, manejador y registro:
263
+
264
+ ```python
265
+ """my_tool — Breve descripción de lo que hace esta herramienta."""
266
+
267
+ import json
268
+ from tools.registry import registry
269
+
270
+
271
+ def my_tool(param1: str, param2: int = 10, **kwargs) -> str:
272
+ """Manejador. Devuelve un resultado en cadena (a menudo JSON)."""
273
+ result = do_work(param1, param2)
274
+ return json.dumps(result)
275
+
276
+
277
+ MY_TOOL_SCHEMA = {
278
+ "type": "function",
279
+ "function": {
280
+ "name": "my_tool",
281
+ "description": "Qué hace esta herramienta y cuándo debería usarla el agente.",
282
+ "parameters": {
283
+ "type": "object",
284
+ "properties": {
285
+ "param1": {"type": "string", "description": "Qué es param1"},
286
+ "param2": {"type": "integer", "description": "Qué es param2", "default": 10},
287
+ },
288
+ "required": ["param1"],
289
+ },
290
+ },
291
+ }
292
+
293
+
294
+ def _check_requirements() -> bool:
295
+ """Devuelve True si las dependencias de esta herramienta están disponibles."""
296
+ return True
297
+
298
+
299
+ registry.register(
300
+ name="my_tool",
301
+ toolset="my_toolset",
302
+ schema=MY_TOOL_SCHEMA,
303
+ handler=lambda args, **kw: my_tool(**args, **kw),
304
+ check_fn=_check_requirements,
305
+ )
306
+ ```
307
+
308
+ **Conectar a un toolset (requerido):** Las herramientas integradas se auto-descubren: cualquier
309
+ archivo `tools/*.py` que contenga una llamada de nivel superior `registry.register(...)` es
310
+ importado por `discover_builtin_tools()` en `tools/registry.py` cuando `model_tools`
311
+ se carga. **No** hay una lista de importaciones manual en `model_tools.py` que mantener.
312
+
313
+ Todavía debes añadir el nombre de la herramienta a la lista apropiada en `toolsets.py`
314
+ (por ejemplo `_HERMES_CORE_TOOLS` o un toolset dedicado); de lo contrario la herramienta
315
+ se registra pero nunca se expone al agente.
316
+
317
+ Consulta `AGENTS.md` (sección **Adding New Tools**) para rutas conscientes del perfil y
318
+ orientación sobre plugins vs. núcleo.
319
+
320
+ ---
321
+
322
+ ## Añadir una Habilidad
323
+
324
+ Las habilidades incluidas viven en `skills/` organizadas por categoría. Las habilidades opcionales oficiales usan la misma estructura en `optional-skills/`:
325
+
326
+ ```
327
+ skills/
328
+ ├── research/
329
+ │ └── arxiv/
330
+ │ ├── SKILL.md # Requerido: instrucciones principales
331
+ │ └── scripts/ # Opcional: scripts auxiliares
332
+ │ └── search_arxiv.py
333
+ ├── productivity/
334
+ │ └── ocr-and-documents/
335
+ │ ├── SKILL.md
336
+ │ ├── scripts/
337
+ │ └── references/
338
+ └── ...
339
+ ```
340
+
341
+ ### Formato de SKILL.md
342
+
343
+ ```markdown
344
+ ---
345
+ name: my-skill
346
+ description: Breve descripción (mostrada en los resultados de búsqueda de habilidades)
347
+ version: 1.0.0
348
+ author: Tu Nombre
349
+ license: MIT
350
+ platforms: [macos, linux] # Opcional — restringir a plataformas de SO específicas
351
+ required_environment_variables: # Opcional — metadatos de configuración segura al cargar
352
+ - name: MY_API_KEY
353
+ prompt: Clave API
354
+ help: Dónde obtenerla
355
+ required_for: funcionalidad completa
356
+ prerequisites: # Requisitos de tiempo de ejecución heredados opcionales
357
+ env_vars: [MY_API_KEY]
358
+ commands: [curl, jq]
359
+ metadata:
360
+ hermes:
361
+ tags: [Categoría, Subcategoría, Palabras clave]
362
+ related_skills: [other-skill-name]
363
+ fallback_for_toolsets: [web]
364
+ requires_toolsets: [terminal]
365
+ ---
366
+
367
+ # Título de la Habilidad
368
+
369
+ Introducción breve.
370
+
371
+ ## Cuándo Usar
372
+ Condiciones de activación — ¿cuándo debería el agente cargar esta habilidad?
373
+
374
+ ## Referencia Rápida
375
+ Tabla de comandos o llamadas API comunes.
376
+
377
+ ## Procedimiento
378
+ Instrucciones paso a paso que el agente sigue.
379
+
380
+ ## Problemas Conocidos
381
+ Modos de fallo conocidos y cómo manejarlos.
382
+
383
+ ## Verificación
384
+ Cómo confirma el agente que funcionó.
385
+ ```
386
+
387
+ ### Estándares de autoría de habilidades (OBLIGATORIOS)
388
+
389
+ Todo skill nuevo o modernizado — incluido, opcional o contribuido — debe cumplir estos estándares antes del merge:
390
+
391
+ 1. **`description` ≤ 60 caracteres, una oración, termina con punto.** Las descripciones largas saturan la UI de listado de habilidades. Indica la capacidad, no la implementación. Sin palabras de marketing ("potente", "completo", "fluido", "avanzado").
392
+
393
+ 2. **Las herramientas referenciadas en el cuerpo de SKILL.md deben ser herramientas nativas de Hermes o servidores MCP que la habilidad espere explícitamente.** Usa los nombres de herramientas en comillas invertidas: `` `terminal` ``, `` `web_extract` ``, `` `web_search` ``, `` `read_file` ``, `` `write_file` ``, etc.
394
+
395
+ 3. **El campo `platforms:` auditado contra las importaciones reales del script.** Las habilidades que usen primitivos solo de POSIX deben declarar sus plataformas soportadas.
396
+
397
+ 4. **`author` da crédito primero al colaborador humano.**
398
+
399
+ 5. **El cuerpo de SKILL.md usa el orden moderno de secciones:** título, intro de 2-3 oraciones, luego: `## Cuándo Usar`, `## Prerequisitos`, `## Cómo Ejecutar`, `## Referencia Rápida`, `## Procedimiento`, `## Problemas Conocidos`, `## Verificación`.
400
+
401
+ 6. **Los scripts van en `scripts/`, las referencias en `references/`, las plantillas en `templates/`.**
402
+
403
+ 7. **Los tests viven en `tests/skills/test_<skill>_skill.py`** y usan solo stdlib + pytest + `unittest.mock`. Sin llamadas de red en vivo.
404
+
405
+ 8. **Las adiciones a `.env.example` están aisladas en un bloque claramente delimitado.**
406
+
407
+ ---
408
+
409
+ ## Añadir una Skin / Tema
410
+
411
+ Hermes usa un sistema de skins basado en datos — no se necesitan cambios de código para añadir una nueva skin.
412
+
413
+ **Opción A: Skin de usuario (archivo YAML)**
414
+
415
+ Crea `~/.hermes/skins/<nombre>.yaml`:
416
+
417
+ ```yaml
418
+ name: mitema
419
+ description: Breve descripción del tema
420
+
421
+ colors:
422
+ banner_border: "#HEX"
423
+ banner_title: "#HEX"
424
+ banner_accent: "#HEX"
425
+ banner_dim: "#HEX"
426
+ banner_text: "#HEX"
427
+ response_border: "#HEX"
428
+
429
+ spinner:
430
+ waiting_faces: ["(⚔)", "(⛨)"]
431
+ thinking_faces: ["(⚔)", "(⌁)"]
432
+ thinking_verbs: ["forjando", "planeando"]
433
+
434
+ branding:
435
+ agent_name: "Mi Agente"
436
+ welcome: "Mensaje de bienvenida"
437
+ response_label: " ⚔ Agente "
438
+ prompt_symbol: "⚔"
439
+
440
+ tool_prefix: "╎"
441
+ ```
442
+
443
+ Todos los campos son opcionales — los valores faltantes se heredan de la skin predeterminada.
444
+
445
+ **Opción B: Skin integrada**
446
+
447
+ Añade al dict `_BUILTIN_SKINS` en `hermes_cli/skin_engine.py`. Usa el mismo esquema que arriba pero como dict de Python.
448
+
449
+ **Activar:**
450
+ - CLI: `/skin mitema` o establece `display.skin: mitema` en config.yaml
451
+
452
+ ---
453
+
454
+ ## Compatibilidad Multiplataforma
455
+
456
+ Hermes se ejecuta en Linux, macOS y Windows nativo (además de WSL2). Al escribir código
457
+ que toca el SO, asume que *cualquier* plataforma puede alcanzar tu ruta de código.
458
+
459
+ > **Antes de hacer PR:** ejecuta `scripts/check-windows-footguns.py` para detectar
460
+ > los patrones inseguros comunes de Windows en tu diff. Es basado en grep y barato;
461
+ > CI también lo ejecuta en cada PR.
462
+
463
+ ### Reglas críticas
464
+
465
+ 1. **Nunca llames `os.kill(pid, 0)` para comprobaciones de liveness.** En Windows **NO es una operación sin efecto**. Usa `psutil.pid_exists(pid)` en su lugar.
466
+
467
+ 2. **Usa `shutil.which()` antes de hacer shell — no asumas que Windows tiene las herramientas que tiene Linux.** `ps`, `kill`, `grep`, `awk`, etc. simplemente no existen en Windows.
468
+
469
+ 3. **`termios` y `fcntl` son solo de Unix.** Siempre captura tanto `ImportError` como `NotImplementedError`.
470
+
471
+ 4. **Codificación de archivos.** Windows puede guardar archivos `.env` en `cp1252`. Siempre maneja errores de codificación.
472
+
473
+ 5. **Gestión de procesos.** `os.setsid()`, `os.killpg()`, `os.fork()`, `os.getuid()` y el manejo de señales POSIX difieren en Windows.
474
+
475
+ 6. **Señales que no existen en Windows:** `SIGALRM`, `SIGCHLD`, `SIGHUP`, `SIGUSR1`, `SIGUSR2`, etc.
476
+
477
+ 7. **Separadores de ruta.** Usa `pathlib.Path` en lugar de concatenación de cadenas con `/`.
478
+
479
+ 8. **Los enlaces simbólicos necesitan privilegios elevados en Windows** (a menos que el Modo Desarrollador esté activado).
480
+
481
+ 9. **Los modos de archivo POSIX (0o600, 0o644, etc.) NO se aplican en NTFS** por defecto.
482
+
483
+ 10. **Los daemons de fondo desacoplados en Windows necesitan `pythonw.exe`, NO `python.exe`.**
484
+
485
+ ---
486
+
487
+ ## Consideraciones de Seguridad
488
+
489
+ Hermes tiene acceso al terminal. La seguridad importa.
490
+
491
+ ### Protecciones existentes
492
+
493
+ | Capa | Implementación |
494
+ |------|---------------|
495
+ | **Piping de contraseña sudo** | Usa `shlex.quote()` para prevenir inyección de shell |
496
+ | **Detección de comandos peligrosos** | Patrones regex en `tools/approval.py` con flujo de aprobación del usuario |
497
+ | **Inyección de prompts en cron** | Escáner en `tools/cronjob_tools.py` bloquea patrones de anulación de instrucciones |
498
+ | **Lista de denegación de escritura** | Rutas protegidas resueltas a través de `os.path.realpath()` para prevenir bypass de enlaces simbólicos |
499
+ | **Skills Guard** | Escáner de seguridad para habilidades instaladas desde el hub (`tools/skills_guard.py`) |
500
+ | **Sandbox de ejecución de código** | El proceso hijo `execute_code` se ejecuta con claves API eliminadas del entorno |
501
+ | **Fortalecimiento de contenedor** | Docker: todas las capacidades eliminadas, sin escalada de privilegios, límites de PID, tmpfs de tamaño limitado |
502
+
503
+ ### Al contribuir código sensible a la seguridad
504
+
505
+ - **Siempre usa `shlex.quote()`** al interpolar entrada del usuario en comandos de shell
506
+ - **Resuelve enlaces simbólicos** con `os.path.realpath()` antes de comprobaciones de control de acceso basadas en rutas
507
+ - **No registres secretos.** Las claves API, tokens y contraseñas nunca deben aparecer en la salida de log
508
+ - **Captura excepciones amplias** alrededor de la ejecución de herramientas para que un solo fallo no bloquee el bucle del agente
509
+ - **Prueba en todas las plataformas** si tu cambio toca rutas de archivos, gestión de procesos o comandos de shell
510
+
511
+ ### Política de fijación de dependencias (fortalecimiento de la cadena de suministro)
512
+
513
+ Tras el [compromiso de la cadena de suministro de litellm](https://github.com/BerriAI/litellm/issues/24512) en marzo de 2026 y la [campaña del gusano Mini Shai-Hulud](https://socket.dev/blog/tanstack-npm-packages-compromised-mini-shai-hulud-supply-chain-attack) en mayo de 2026, todas las dependencias deben seguir estas reglas:
514
+
515
+ | Tipo de fuente | Tratamiento requerido | Justificación |
516
+ |---|---|---|
517
+ | **Paquete PyPI** | `>=suelo,<siguiente_mayor` | Las versiones de PyPI son inmutables una vez publicadas, pero pueden empujarse nuevas versiones en tu rango. |
518
+ | **URL de Git** | SHA completo del commit | Las ramas y etiquetas son refs mutables; el SHA está direccionado por contenido. |
519
+ | **GitHub Actions** | SHA completo del commit + comentario de versión | Las etiquetas de acción son refs mutables. Fija como `uses: owner/action@<sha> # vX.Y.Z` |
520
+ | **Instalaciones pip solo de CI** | `==exacto` | Builds de CI herméticos; el cambio es aceptable. |
521
+
522
+ **Cada nueva dependencia de PyPI en un PR debe tener un límite superior `<siguiente_mayor`.** Los PRs que añadan especificaciones `>=X.Y.Z` sin límite superior serán rechazados.
523
+
524
+ ---
525
+
526
+ ## Proceso de Pull Request
527
+
528
+ ### Nomenclatura de ramas
529
+
530
+ ```
531
+ fix/descripcion # Correcciones de errores
532
+ feat/descripcion # Nuevas funcionalidades
533
+ docs/descripcion # Documentación
534
+ test/descripcion # Tests
535
+ refactor/descripcion # Reestructuración de código
536
+ ```
537
+
538
+ ### Antes de enviar
539
+
540
+ 1. **Ejecutar tests**: `scripts/run_tests.sh` (recomendado; igual que CI) o `pytest tests/ -v` con el venv del proyecto activado
541
+ 2. **Probar manualmente**: Ejecuta `hermes` y ejercita la ruta de código que cambiaste
542
+ 3. **Verificar impacto multiplataforma**: Si tocas E/S de archivos, gestión de procesos o manejo del terminal, considera macOS, Linux y WSL2
543
+ 4. **Mantén los PRs enfocados**: Un cambio lógico por PR. No mezcles una corrección de error con una refactorización con una nueva funcionalidad.
544
+
545
+ ### Descripción del PR
546
+
547
+ Incluye:
548
+ - **Qué** cambió y **por qué**
549
+ - **Cómo probarlo** (pasos de reproducción para errores, ejemplos de uso para funcionalidades)
550
+ - **Qué plataformas** probaste
551
+ - Referencia cualquier issue relacionado
552
+
553
+ ### Mensajes de commit
554
+
555
+ Usamos [Conventional Commits](https://www.conventionalcommits.org/):
556
+
557
+ ```
558
+ <tipo>(<alcance>): <descripción>
559
+ ```
560
+
561
+ | Tipo | Usar para |
562
+ |------|-----------|
563
+ | `fix` | Correcciones de errores |
564
+ | `feat` | Nuevas funcionalidades |
565
+ | `docs` | Documentación |
566
+ | `test` | Tests |
567
+ | `refactor` | Reestructuración de código (sin cambio de comportamiento) |
568
+ | `chore` | Build, CI, actualizaciones de dependencias |
569
+
570
+ Alcances: `cli`, `gateway`, `tools`, `skills`, `agent`, `install`, `whatsapp`, `security`, etc.
571
+
572
+ Ejemplos:
573
+ ```
574
+ fix(cli): prevenir bloqueo en save_config_value cuando el modelo es una cadena
575
+ feat(gateway): añadir aislamiento de sesión multi-usuario de WhatsApp
576
+ fix(security): prevenir inyección de shell en el piping de contraseña sudo
577
+ test(tools): añadir tests unitarios para file_operations
578
+ ```
579
+
580
+ ---
581
+
582
+ ## Reportar Issues
583
+
584
+ - Usa [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
585
+ - Incluye: SO, versión de Python, versión de Hermes (`hermes --version`), traza de error completa
586
+ - Incluye pasos para reproducir
587
+ - Verifica los issues existentes antes de crear duplicados
588
+ - Para vulnerabilidades de seguridad, por favor reporta de forma privada
589
+
590
+ ---
591
+
592
+ ## Comunidad
593
+
594
+ - **Discord**: [discord.gg/NousResearch](https://discord.gg/NousResearch) — para preguntas, mostrar proyectos y compartir habilidades
595
+ - **GitHub Discussions**: Para propuestas de diseño y discusiones de arquitectura
596
+ - **Skills Hub**: Sube habilidades especializadas a un registro y compártelas con la comunidad
597
+
598
+ ---
599
+
600
+ ## Licencia
601
+
602
+ Al contribuir, aceptas que tus contribuciones serán licenciadas bajo la [Licencia MIT](LICENSE).
CONTRIBUTING.md ADDED
@@ -0,0 +1,1002 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Contributing to Hermes Agent
2
+
3
+ Thank you for contributing to Hermes Agent! This guide covers everything you need: setting up your dev environment, understanding the architecture, deciding what to build, and getting your PR merged.
4
+
5
+ ---
6
+
7
+ ## Contribution Priorities
8
+
9
+ We value contributions in this order:
10
+
11
+ 1. **Bug fixes** — crashes, incorrect behavior, data loss. Always top priority.
12
+ 2. **Cross-platform compatibility** — macOS, different Linux distros, and WSL2 on Windows. We want Hermes to work everywhere.
13
+ 3. **Security hardening** — shell injection, prompt injection, path traversal, privilege escalation. See [Security](#security-considerations).
14
+ 4. **Performance and robustness** — retry logic, error handling, graceful degradation.
15
+ 5. **New skills** — but only broadly useful ones. See [Should it be a Skill or a Tool?](#should-it-be-a-skill-or-a-tool)
16
+ 6. **New tools** — rarely needed. Most capabilities should be skills. See below.
17
+ 7. **Documentation** — fixes, clarifications, new examples.
18
+
19
+ ---
20
+
21
+ ## Before You Start: Search First
22
+
23
+ A quick search before you build saves your time and keeps the PR queue clean — duplicates are common here, so it's worth a minute up front.
24
+
25
+ - **Search both open *and* merged PRs and issues** for your topic or error symptom — the duplicate-check in the PR template fires at review time, after you've already done the work:
26
+ ```bash
27
+ gh search issues --repo NousResearch/hermes-agent "<your terms>"
28
+ gh search prs --repo NousResearch/hermes-agent --state all "<your terms>"
29
+ ```
30
+ Or use the web UI: [issues](https://github.com/NousResearch/hermes-agent/issues?q=) · [PRs (all states)](https://github.com/NousResearch/hermes-agent/pulls?q=is%3Apr).
31
+ - **The issue tracker can lag the code.** Many requested features are already implemented in-tree, so also search the source (`search_files`, or your editor's grep) for the capability before proposing it.
32
+ - **If an open PR already addresses it**, consider reviewing or improving that one instead of opening a competing duplicate.
33
+ - **For larger work**, comment on the issue to signal you're working on it, so others don't start the same thing.
34
+
35
+ Related: #38284 covers the agent-side analog — Hermes itself checking existing issues and PRs before deep self-troubleshooting. This section is the human-contributor complement.
36
+
37
+ ---
38
+
39
+ ## Should it be a Skill or a Tool?
40
+
41
+ This is the most common question for new contributors. The answer is almost always **skill**.
42
+
43
+ ### Make it a Skill when:
44
+
45
+ - The capability can be expressed as instructions + shell commands + existing tools
46
+ - It wraps an external CLI or API that the agent can call via `terminal` or `web_extract`
47
+ - It doesn't need custom Python integration or API key management baked into the agent
48
+ - Examples: arXiv search, git workflows, Docker management, PDF processing, email via CLI tools
49
+
50
+ ### Make it a Tool when:
51
+
52
+ - It requires end-to-end integration with API keys, auth flows, or multi-component configuration managed by the agent harness
53
+ - It needs custom processing logic that must execute precisely every time (not "best effort" from LLM interpretation)
54
+ - It handles binary data, streaming, or real-time events that can't go through the terminal
55
+ - Examples: browser automation (Browserbase session management), TTS (audio encoding + platform delivery), vision analysis (base64 image handling)
56
+
57
+ ### Should the Skill be bundled?
58
+
59
+ Bundled skills (in `skills/`) ship with every Hermes install. They should be **broadly useful to most users**:
60
+
61
+ - Document handling, web research, common dev workflows, system administration
62
+ - Used regularly by a wide range of people
63
+
64
+ If your skill is official and useful but not universally needed (e.g., a paid service integration, a heavyweight dependency), put it in **`optional-skills/`** — it ships with the repo but isn't activated by default. Users can discover it via `hermes skills browse` (labeled "official") and install it with `hermes skills install` (no third-party warning, built-in trust).
65
+
66
+ If your skill is specialized, community-contributed, or niche, it's better suited for a **Skills Hub** — upload it to a skills registry and share it in the [Nous Research Discord](https://discord.gg/NousResearch). Users can install it with `hermes skills install`.
67
+
68
+ ---
69
+
70
+ ## Memory Providers: Ship as a Standalone Plugin
71
+
72
+ **We are no longer accepting new memory providers into this repo.** The set of built-in providers under `plugins/memory/` (honcho, mem0, supermemory, byterover, hindsight, holographic, openviking, retaindb) is closed. If you want to add a new memory backend, publish it as a **standalone plugin repo** that users install into `~/.hermes/plugins/` (or via a pip entry point).
73
+
74
+ Standalone memory plugins:
75
+
76
+ - Implement the same `MemoryProvider` ABC (`agent/memory_provider.py`) — `sync_turn`, `prefetch`, `shutdown`, and optionally `post_setup(hermes_home, config)` for setup-wizard integration
77
+ - Use the same discovery system — `discover_memory_providers()` picks them up from user/project plugin directories and pip entry points
78
+ - Integrate with `hermes memory setup` via `post_setup()` — no need to touch core code
79
+ - Can register their own CLI subcommands via `register_cli(subparser)` in a `cli.py` file
80
+ - Get all the same lifecycle hooks and config plumbing as in-tree providers
81
+
82
+ PRs that add a new directory under `plugins/memory/` will be closed with a pointer to publish the provider as its own repo. Existing in-tree providers stay; bug fixes to them are welcome.
83
+
84
+ This isn't a quality bar — it's a coupling-and-maintenance decision. Memory providers are the most common plugin type and they shouldn't all live in this tree.
85
+
86
+ ---
87
+
88
+ ## Third-Party Product Integrations: Ship as a Standalone Plugin
89
+
90
+ The same rule extends to **any plugin that integrates someone else's product or project** — observability/metrics backends, vendor SaaS connectors, analytics dashboards, paid-service tie-ins, and similar third-party integrations. **These do not land in this repo.**
91
+
92
+ The reason is maintenance load, not quality. Every external product absorbed into the core tree becomes ours to keep working against a fast-moving codebase, for a backend we don't own and can't control. Hermes ships a lot and the core moves quickly; coupling third-party products into it creates an open-ended burden on the maintainers.
93
+
94
+ Publish these as a **standalone plugin repo** instead:
95
+
96
+ - Implement the relevant ABC and use the existing plugin discovery path (`~/.hermes/plugins/`, project `.hermes/plugins/`, or a pip entry point) — see [Build a Hermes Plugin](https://hermes-agent.nousresearch.com/docs/guides/build-a-hermes-plugin)
97
+ - Register lifecycle hooks (`pre_tool_call`, `post_tool_call`, `pre_llm_call`, `post_llm_call`, `on_session_start`, `on_session_end`), tools (`ctx.register_tool`), and CLI subcommands (`ctx.register_cli_command`) through the surface we already expose — no core changes needed
98
+ - If your plugin needs a capability the framework doesn't expose, that's a feature request to **widen the generic plugin surface** (a new hook or `ctx` method) — never special-case your plugin in core
99
+ - Promote it in the [Nous Research Discord](https://discord.gg/NousResearch) `#plugins-skills-and-skins` channel so users can find and install it
100
+
101
+ A well-built third-party-product plugin can clear automated review and still be closed for this reason — it's a placement decision, not a verdict on the code. PRs that add such a directory under `plugins/` will be closed with a pointer to publish it as its own repo.
102
+
103
+ ---
104
+
105
+ ## Development Setup
106
+
107
+ ### Prerequisites
108
+
109
+ | Requirement | Notes |
110
+ |-------------|-------|
111
+ | **Git** | With the `git-lfs` extension installed |
112
+ | **Python 3.11–3.13** | uv will install it if missing |
113
+ | **uv** | Fast Python package manager ([install](https://docs.astral.sh/uv/)) |
114
+ | **Node.js 20+** | Optional — needed for browser tools and WhatsApp bridge (matches root `package.json` engines) |
115
+
116
+ ### Install with the standard installer
117
+
118
+ For most contributors, the best development bootstrap is the same path users
119
+ take: run the standard installer, then work inside the repository it cloned.
120
+ The installer creates the Hermes venv, wires the `hermes` command, stamps the
121
+ install method for `hermes update`, and clones the full git project into
122
+ `$HERMES_HOME/hermes-agent` (usually `~/.hermes/hermes-agent`). That keeps your
123
+ development environment on the same layout the CLI, updater, lazy dependency
124
+ installer, gateway, and docs assume.
125
+
126
+ ```bash
127
+ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
128
+ cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
129
+
130
+ # Add dev/test extras on top of the standard install.
131
+ uv pip install -e ".[all,dev]"
132
+
133
+ # Optional: docs site + workspace dependencies.
134
+ npm install
135
+ ```
136
+
137
+ After that, create branches and run tests from that checkout:
138
+
139
+ ```bash
140
+ git checkout -b fix/description
141
+ scripts/run_tests.sh
142
+ ```
143
+
144
+ ### Manual clone fallback
145
+
146
+ Use this only if you intentionally do not want Hermes' managed install layout
147
+ (for example, a throwaway clone inside a container or CI job). If you install
148
+ this way, make sure you run the `hermes` entrypoint from this venv; running the
149
+ system `python3 -m hermes_cli.main` can pick up unrelated system Python
150
+ packages.
151
+
152
+ Create the venv **outside** the cloned source tree. A venv that lives inside
153
+ the directory the agent operates from can be wiped by a relative-path command
154
+ the agent runs against its own checkout (`rm -rf venv`, `uv venv venv`, etc.),
155
+ which silently destroys the running runtime mid-session. Keeping it outside the
156
+ tree means no relative path from the workspace resolves to it.
157
+
158
+ ```bash
159
+ git clone https://github.com/NousResearch/hermes-agent.git
160
+ cd hermes-agent
161
+
162
+ # Create venv with Python 3.11, OUTSIDE the source tree
163
+ uv venv ~/.hermes/venvs/hermes-dev --python 3.11
164
+ export VIRTUAL_ENV="$HOME/.hermes/venvs/hermes-dev"
165
+ export PATH="$VIRTUAL_ENV/bin:$PATH"
166
+
167
+ # Install with all extras (messaging, cron, CLI menus, dev tools)
168
+ uv pip install -e ".[all,dev]"
169
+
170
+ # Optional: workspace / docs dependencies
171
+ npm install
172
+ ```
173
+
174
+ ### Configure for development
175
+
176
+ ```bash
177
+ mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills}
178
+ cp cli-config.yaml.example ~/.hermes/config.yaml
179
+ touch ~/.hermes/.env
180
+
181
+ # Add at minimum an LLM provider key:
182
+ echo "OPENROUTER_API_KEY=***" >> ~/.hermes/.env
183
+ ```
184
+
185
+ ### Run
186
+
187
+ ```bash
188
+ # The standard installer already put `hermes` on PATH.
189
+ hermes doctor
190
+ hermes chat -q "Hello"
191
+ ```
192
+
193
+ If you used the manual clone fallback, run `./hermes` from the checkout or
194
+ symlink this clone's venv explicitly:
195
+
196
+ ```bash
197
+ mkdir -p ~/.local/bin
198
+ ln -sf "$(pwd)/venv/bin/hermes" ~/.local/bin/hermes
199
+ ```
200
+
201
+ ### Run tests
202
+
203
+ ```bash
204
+ # Preferred — matches CI (hermetic `env -i`, per-file subprocess isolation
205
+ # via run_tests_parallel.py, worker count auto-scaled); see AGENTS.md
206
+ scripts/run_tests.sh
207
+
208
+ # Alternative (activate the venv first). The wrapper is still recommended
209
+ # for parity with GitHub Actions before you open a PR:
210
+ pytest tests/ -v
211
+ ```
212
+
213
+ ---
214
+
215
+ ## Project Structure
216
+
217
+ ```
218
+ hermes-agent/
219
+ ├── run_agent.py # AIAgent facade (~1.5k LOC) — the turn loop lives in agent/conversation_loop.py + agent/turn_*.py
220
+ ├── cli.py # HermesCLI class — interactive CLI orchestrator (~4.6k LOC + hermes_cli/cli_*_mixin.py)
221
+ ├── model_tools.py # Tool orchestration (thin layer over tools/registry.py)
222
+ ├── toolsets.py # Tool groupings and presets (hermes-cli, hermes-telegram, etc.)
223
+ ├── hermes_state.py # SessionDB facade (~1.4k LOC); implementation in hermes_state_*.py (21 siblings) — FTS5 search, session titles
224
+ ├── batch_runner.py # Parallel batch processing for trajectory generation
225
+ │
226
+ ├── agent/ # Agent internals (extracted modules)
227
+ │ ├── conversation_loop.py # run_conversation() — the agent turn loop (phases in turn_*.py)
228
+ │ ├── tool_executor.py # Tool dispatch (inline agent-level tools, delegate, registry)
229
+ │ ├── session_persistence.py # Session/trajectory saving
230
+ │ ├── prompt_builder.py # System prompt assembly (identity, skills, context files, memory)
231
+ │ ├── context_compressor.py # Auto-summarization when approaching context limits
232
+ │ ├── auxiliary_client.py # Resolves auxiliary OpenAI clients (summarization, vision)
233
+ │ ├── display.py # KawaiiSpinner, tool progress formatting
234
+ │ ├── model_metadata.py # Model context lengths, token estimation
235
+ │ └── trajectory.py # Trajectory saving helpers
236
+ │
237
+ ├── hermes_cli/ # CLI command implementations
238
+ │ ├── main.py # Entry point, argument parsing, command dispatch
239
+ │ ├── cli_*_mixin.py # HermesCLI mixins (slash commands, display, session, ...)
240
+ │ ├── config.py # Config management, migration, env var definitions
241
+ │ ├── setup.py # Interactive setup wizard
242
+ │ ├── auth.py # Provider resolution, OAuth, Nous Portal (facade + auth_*.py siblings)
243
+ │ ├── models.py # OpenRouter model selection lists
244
+ │ ├── banner.py # Welcome banner, ASCII art
245
+ │ ├── commands.py # Central slash command registry (CommandDef), autocomplete, gateway helpers
246
+ │ ├── callbacks.py # Interactive callbacks (clarify, sudo, approval)
247
+ │ ├── doctor.py # Diagnostics
248
+ │ ├── skills_hub.py # Skills Hub CLI + /skills slash command
249
+ │ ├── skin_engine.py # Skin/theme engine — data-driven CLI visual customization
250
+ │ ├── web_server.py # Dashboard server (facade + web_server_*.py siblings)
251
+ │ └── web_routers/ # Dashboard FastAPI routers (one file per surface)
252
+ │
253
+ ├── tools/ # Tool implementations (self-registering)
254
+ │ ├── registry.py # Central tool registry (schemas, handlers, dispatch)
255
+ │ ├── approval.py # Dangerous command detection + per-session approval
256
+ │ ├── terminal_tool.py # Terminal orchestration (sudo, env lifecycle, backends)
257
+ │ ├── file_operations.py # read_file, write_file, search, patch, etc.
258
+ │ ├── web_tools.py # web_search, web_extract (Parallel/Firecrawl + Gemini summarization)
259
+ │ ├── vision_tools.py # Image analysis via multimodal models
260
+ │ ├── delegate_tool.py # Subagent spawning and parallel task execution
261
+ │ ├── code_execution_tool.py # Sandboxed Python with RPC tool access (env allowlists in code_execution_env.py)
262
+ │ ├── mcp_tool.py # MCP client (facade + mcp_tool_*.py siblings: config, discovery, transport, ...)
263
+ │ ├── browser_tool.py # Browser automation (facade + browser_tool_*.py siblings)
264
+ │ ├── session_search_tool.py # Search past conversations with FTS5 + anchored windows
265
+ │ ├── cronjob_tools.py # Scheduled task management
266
+ │ ├── skill_tools.py # Skill search, load, manage
267
+ │ └── environments/ # Terminal execution backends
268
+ │ ├── base.py # BaseEnvironment ABC
269
+ │ ├── local.py, docker.py, ssh.py, singularity.py, modal.py, daytona.py
270
+ │
271
+ ├── gateway/ # Messaging gateway
272
+ │ ├── run.py # GatewayRunner facade (~5.5k LOC); phases in run_*.py (startup, inbound, turn, busy, ...)
273
+ │ ├── slash_commands_*.py # Gateway slash command handler mixins
274
+ │ ├── config.py # Platform configuration resolution
275
+ │ ├── session.py # Session store, context prompts, explicit resets (+ session_*.py siblings)
276
+ │ └── platforms/ # Platform adapters
277
+ │ ├── telegram.py, discord_adapter.py, slack.py, whatsapp.py
278
+ │
279
+ ├── scripts/ # Installer and bridge scripts
280
+ │ ├── install.sh # Linux/macOS installer
281
+ │ ├── install.ps1 # Windows PowerShell installer
282
+ │ └── whatsapp-bridge/ # Node.js WhatsApp bridge (Baileys)
283
+ │
284
+ ├── skills/ # Bundled skills (copied to ~/.hermes/skills/ on install)
285
+ ├── optional-skills/ # Official optional skills (discoverable via hub, not activated by default)
286
+ ├── tests/ # Test suite
287
+ ├── website/ # Documentation site (hermes-agent.nousresearch.com)
288
+ │
289
+ ├── cli-config.yaml.example # Example configuration (copied to ~/.hermes/config.yaml)
290
+ └── AGENTS.md # Development guide for AI coding assistants
291
+ ```
292
+
293
+ ### User configuration (stored in `~/.hermes/`)
294
+
295
+ | Path | Purpose |
296
+ |------|---------|
297
+ | `~/.hermes/config.yaml` | Settings (model, terminal, toolsets, compression, etc.) |
298
+ | `~/.hermes/.env` | API keys and secrets |
299
+ | `~/.hermes/auth.json` | OAuth credentials (Nous Portal) |
300
+ | `~/.hermes/skills/` | All active skills (bundled + hub-installed + agent-created) |
301
+ | `~/.hermes/memories/` | Persistent memory (MEMORY.md, USER.md) |
302
+ | `~/.hermes/state.db` | SQLite session database |
303
+ | `~/.hermes/sessions/` | Gateway routing index (`sessions.json`), request-dump breadcrumbs, gateway `*.jsonl` transcripts, and explicit `/save` exports. Automatic per-session JSON snapshots are no longer written; state.db is canonical. |
304
+ | `~/.hermes/cron/` | Scheduled job data |
305
+ | `~/.hermes/whatsapp/session/` | WhatsApp bridge credentials |
306
+
307
+ ---
308
+
309
+ ## Architecture Overview
310
+
311
+ ### Core Loop
312
+
313
+ ```
314
+ User message → AIAgent._run_agent_loop()
315
+ ├── Build system prompt (prompt_builder.py)
316
+ ├── Build API kwargs (model, messages, tools, reasoning config)
317
+ ├── Call LLM (OpenAI-compatible API)
318
+ ├── If tool_calls in response:
319
+ │ ├── Execute each tool via registry dispatch
320
+ │ ├── Add tool results to conversation
321
+ │ └── Loop back to LLM call
322
+ ├── If text response:
323
+ │ ├── Persist session to DB
324
+ │ └── Return final_response
325
+ └── Context compression if approaching token limit
326
+ ```
327
+
328
+ ### Key Design Patterns
329
+
330
+ - **Self-registering tools**: Each tool file calls `registry.register()` at import time. `model_tools.py` triggers discovery by importing all tool modules.
331
+ - **Toolset grouping**: Tools are grouped into toolsets (`web`, `terminal`, `file`, `browser`, etc.) that can be enabled/disabled per platform.
332
+ - **Session persistence**: All conversations are stored in SQLite (`hermes_state.py`) with full-text search and unique session titles. Automatic per-session JSON snapshots have been removed. Existing files are left untouched; use `/save json` or `hermes sessions export` for an explicit export.
333
+ - **Ephemeral injection**: System prompts and prefill messages are injected at API call time, never persisted to the database or logs.
334
+ - **Provider abstraction**: The agent works with any OpenAI-compatible API. Provider resolution happens at init time (Nous Portal OAuth, OpenRouter API key, or custom endpoint).
335
+ - **Provider routing**: When using OpenRouter, `provider_routing` in config.yaml controls provider selection (sort by throughput/latency/price, allow/ignore specific providers, data retention policies). These are injected as `extra_body.provider` in API requests.
336
+
337
+ ---
338
+
339
+ ## Code Style
340
+
341
+ - **PEP 8** with practical exceptions (we don't enforce strict line length)
342
+ - **Comments**: Only when explaining non-obvious intent, trade-offs, or API quirks. Don't narrate what the code does — `# increment counter` adds nothing
343
+ - **Error handling**: Catch specific exceptions. Log with `logger.warning()`/`logger.error()` — use `exc_info=True` for unexpected errors so stack traces appear in logs
344
+ - **Cross-platform**: Never assume Unix. See [Cross-Platform Compatibility](#cross-platform-compatibility)
345
+
346
+ ---
347
+
348
+ ## Adding a New Tool
349
+
350
+ Before writing a tool, ask: [should this be a skill instead?](#should-it-be-a-skill-or-a-tool)
351
+
352
+ Tools self-register with the central registry. Each tool file co-locates its schema, handler, and registration:
353
+
354
+ ```python
355
+ """my_tool — Brief description of what this tool does."""
356
+
357
+ import json
358
+ from tools.registry import registry
359
+
360
+
361
+ def my_tool(param1: str, param2: int = 10, **kwargs) -> str:
362
+ """Handler. Returns a string result (often JSON)."""
363
+ result = do_work(param1, param2)
364
+ return json.dumps(result)
365
+
366
+
367
+ MY_TOOL_SCHEMA = {
368
+ "type": "function",
369
+ "function": {
370
+ "name": "my_tool",
371
+ "description": "What this tool does and when the agent should use it.",
372
+ "parameters": {
373
+ "type": "object",
374
+ "properties": {
375
+ "param1": {"type": "string", "description": "What param1 is"},
376
+ "param2": {"type": "integer", "description": "What param2 is", "default": 10},
377
+ },
378
+ "required": ["param1"],
379
+ },
380
+ },
381
+ }
382
+
383
+
384
+ def _check_requirements() -> bool:
385
+ """Return True if this tool's dependencies are available."""
386
+ return True
387
+
388
+
389
+ registry.register(
390
+ name="my_tool",
391
+ toolset="my_toolset",
392
+ schema=MY_TOOL_SCHEMA,
393
+ handler=lambda args, **kw: my_tool(**args, **kw),
394
+ check_fn=_check_requirements,
395
+ )
396
+ ```
397
+
398
+ **Wire into a toolset (required):** Built-in tools are auto-discovered: any
399
+ `tools/*.py` file that contains a top-level `registry.register(...)` call is
400
+ imported by `discover_builtin_tools()` in `tools/registry.py` when `model_tools`
401
+ loads. There is **no** manual import list in `model_tools.py` to maintain.
402
+
403
+ You must still add the tool name to the appropriate list in `toolsets.py`
404
+ (for example `_HERMES_CORE_TOOLS` or a dedicated toolset); otherwise the tool
405
+ registers but is never exposed to the agent. If you introduce a new toolset,
406
+ add it in `toolsets.py` and wire it into the relevant platform presets.
407
+
408
+ See `AGENTS.md` (section **Adding New Tools**) for profile-aware paths and
409
+ plugin vs core guidance.
410
+
411
+ ---
412
+
413
+ ## Adding a Skill
414
+
415
+ Bundled skills live in `skills/` organized by category. Official optional skills use the same structure in `optional-skills/`:
416
+
417
+ ```
418
+ skills/
419
+ ├── research/
420
+ │ └── arxiv/
421
+ │ ├── SKILL.md # Required: main instructions
422
+ │ └── scripts/ # Optional: helper scripts
423
+ │ └── search_arxiv.py
424
+ ├── productivity/
425
+ │ └── ocr-and-documents/
426
+ │ ├── SKILL.md
427
+ │ ├── scripts/
428
+ │ └── references/
429
+ └── ...
430
+ ```
431
+
432
+ ### SKILL.md format
433
+
434
+ ```markdown
435
+ ---
436
+ name: my-skill
437
+ description: Brief description (shown in skill search results)
438
+ version: 1.0.0
439
+ author: Your Name
440
+ license: MIT
441
+ platforms: [macos, linux] # Optional — restrict to specific OS platforms
442
+ # Valid: macos, linux, windows
443
+ # Omit to load on all platforms (default)
444
+ required_environment_variables: # Optional — secure setup-on-load metadata
445
+ - name: MY_API_KEY
446
+ prompt: API key
447
+ help: Where to get it
448
+ required_for: full functionality
449
+ prerequisites: # Optional legacy runtime requirements
450
+ env_vars: [MY_API_KEY] # Backward-compatible alias for required env vars
451
+ commands: [curl, jq] # Advisory only; does not hide the skill
452
+ metadata:
453
+ hermes:
454
+ tags: [Category, Subcategory, Keywords]
455
+ related_skills: [other-skill-name]
456
+ fallback_for_toolsets: [web] # Optional — show only when toolset is unavailable
457
+ requires_toolsets: [terminal] # Optional — show only when toolset is available
458
+ ---
459
+
460
+ # Skill Title
461
+
462
+ Brief intro.
463
+
464
+ ## When to Use
465
+ Trigger conditions — when should the agent load this skill?
466
+
467
+ ## Prerequisites
468
+ Env vars, install steps, MCP setup, API key sourcing.
469
+
470
+ ## How to Run
471
+ Canonical invocation through the `terminal` tool.
472
+
473
+ ## Quick Reference
474
+ Table of common commands or API calls.
475
+
476
+ ## Procedure
477
+ Step-by-step instructions the agent follows.
478
+
479
+ ## Pitfalls
480
+ Known failure modes and how to handle them.
481
+
482
+ ## Verification
483
+ How the agent confirms it worked.
484
+ ```
485
+
486
+ ### Platform-specific skills
487
+
488
+ Skills can declare which OS platforms they support via the `platforms` frontmatter field. Skills with this field are automatically hidden from the system prompt, `skills_list()`, and slash commands on incompatible platforms.
489
+
490
+ ```yaml
491
+ platforms: [macos] # macOS only (e.g., iMessage, Apple Reminders)
492
+ platforms: [macos, linux] # macOS and Linux
493
+ platforms: [windows] # Windows only
494
+ ```
495
+
496
+ If the field is omitted or empty, the skill loads on all platforms (backward compatible). See `skills/apple/` for examples of macOS-only skills.
497
+
498
+ ### Conditional skill activation
499
+
500
+ Skills can declare conditions that control when they appear in the system prompt, based on which tools and toolsets are available in the current session. This is primarily used for **fallback skills** — alternatives that should only be shown when a primary tool is unavailable.
501
+
502
+ Four fields are supported under `metadata.hermes`:
503
+
504
+ ```yaml
505
+ metadata:
506
+ hermes:
507
+ fallback_for_toolsets: [web] # Show ONLY when these toolsets are unavailable
508
+ requires_toolsets: [terminal] # Show ONLY when these toolsets are available
509
+ fallback_for_tools: [web_search] # Show ONLY when these specific tools are unavailable
510
+ requires_tools: [terminal] # Show ONLY when these specific tools are available
511
+ ```
512
+
513
+ **Semantics:**
514
+ - `fallback_for_*`: The skill is a backup. It is **hidden** when the listed tools/toolsets are available, and **shown** when they are unavailable. Use this for free alternatives to premium tools.
515
+ - `requires_*`: The skill needs certain tools to function. It is **hidden** when the listed tools/toolsets are unavailable. Use this for skills that depend on specific capabilities (e.g., a skill that only makes sense with terminal access).
516
+ - If both are specified, both conditions must be satisfied for the skill to appear.
517
+ - If neither is specified, the skill is always shown (backward compatible).
518
+
519
+ **Examples:**
520
+
521
+ ```yaml
522
+ # DuckDuckGo search — shown when Firecrawl (web toolset) is unavailable
523
+ metadata:
524
+ hermes:
525
+ fallback_for_toolsets: [web]
526
+
527
+ # Smart home skill — only useful when terminal is available
528
+ metadata:
529
+ hermes:
530
+ requires_toolsets: [terminal]
531
+
532
+ # Local browser fallback — shown when Browserbase is unavailable
533
+ metadata:
534
+ hermes:
535
+ fallback_for_toolsets: [browser]
536
+ ```
537
+
538
+ The filtering happens at prompt build time in `agent/prompt_builder.py`. The `build_skills_system_prompt()` function receives the set of available tools and toolsets from the agent and uses `_skill_should_show()` to evaluate each skill's conditions.
539
+
540
+ ### Skill setup metadata
541
+
542
+ Skills can declare secure setup-on-load metadata via the `required_environment_variables` frontmatter field. Missing values do not hide the skill from discovery; they trigger a CLI-only secure prompt when the skill is actually loaded.
543
+
544
+ ```yaml
545
+ required_environment_variables:
546
+ - name: TENOR_API_KEY
547
+ prompt: Tenor API key
548
+ help: Get a key from https://developers.google.com/tenor
549
+ required_for: full functionality
550
+ ```
551
+
552
+ The user may skip setup and keep loading the skill. Hermes only exposes metadata (`stored_as`, `skipped`, `validated`) to the model — never the secret value.
553
+
554
+ Legacy `prerequisites.env_vars` remains supported and is normalized into the new representation.
555
+
556
+ ```yaml
557
+ prerequisites:
558
+ env_vars: [TENOR_API_KEY] # Legacy alias for required_environment_variables
559
+ commands: [curl, jq] # Advisory CLI checks
560
+ ```
561
+
562
+ Gateway and messaging sessions never collect secrets in-band; they instruct the user to run `hermes setup` or update `~/.hermes/.env` locally.
563
+
564
+ **When to declare required environment variables:**
565
+ - The skill uses an API key or token that should be collected securely at load time
566
+ - The skill can still be useful if the user skips setup, but may degrade gracefully
567
+
568
+ **When to declare command prerequisites:**
569
+ - The skill relies on a CLI tool that may not be installed (e.g., `himalaya`, `openhue`, `ddgs`)
570
+ - Treat command checks as guidance, not discovery-time hiding
571
+
572
+ See `skills/gifs/gif-search/` and `skills/email/himalaya/` for examples.
573
+
574
+ ### Skill authoring standards (HARDLINE)
575
+
576
+ Every new or modernized skill — bundled, optional, or contributed — must meet these standards before merge. Reviewers reject PRs that violate them.
577
+
578
+ 1. **`description` ≤ 60 characters, one sentence, ends with a period.** Long descriptions bloat the skill listing UI and dilute the model's attention when many skills are loaded. State the capability, not the implementation. No marketing words ("powerful", "comprehensive", "seamless", "advanced"). Don't repeat the skill name. Verify with:
579
+ ```python
580
+ import re, pathlib
581
+ m = re.search(r'^description: (.*)$',
582
+ pathlib.Path('skills/<cat>/<name>/SKILL.md').read_text(),
583
+ re.MULTILINE)
584
+ assert len(m.group(1)) <= 60, len(m.group(1))
585
+ ```
586
+
587
+ Good: `Search arXiv papers by keyword, author, category, or ID.`
588
+ Bad: `A powerful and comprehensive skill that allows the agent to search arXiv for relevant academic papers using various criteria including keywords, authors, and categories.`
589
+
590
+ 2. **Tools referenced in SKILL.md prose must be native Hermes tools or MCP servers the skill explicitly expects.** When the skill needs a capability, point at the proper tool by name in backticks: `` `terminal` ``, `` `web_extract` ``, `` `web_search` ``, `` `read_file` ``, `` `write_file` ``, `` `patch` ``, `` `search_files` ``, `` `vision_analyze` ``, `` `browser_navigate` ``, `` `delegate_task` ``, `` `image_generate` ``, `` `text_to_speech` ``, `` `cronjob` ``, `` `memory` ``, `` `skill_view` ``, `` `todo` ``, `` `execute_code` ``.
591
+
592
+ Do NOT name shell utilities the agent already has wrapped:
593
+
594
+ | Don't say | Say |
595
+ |---|---|
596
+ | `grep`, `rg` | `search_files` |
597
+ | `cat`, `head`, `tail` | `read_file` |
598
+ | `sed`, `awk` | `patch` |
599
+ | `find`, `ls` | `search_files` (with `target='files'`) |
600
+ | `curl` for content extraction | `web_extract` |
601
+ | `echo > file`, `cat <<EOF` | `write_file` |
602
+
603
+ If the skill depends on an MCP server, name the MCP server and document its setup in `## Prerequisites`. Third-party CLIs (e.g. `ffmpeg`, `gh`, a specific SDK) are fine to invoke from inside script files, but the prose should frame the interaction as "invoke through the `terminal` tool", not as a manual shell session.
604
+
605
+ 3. **`platforms:` gating audited against actual script imports.** Skills that use POSIX-only primitives (`fcntl`, `termios`, `os.setsid`, `os.kill(pid, 0)` for liveness, `/proc`, hardcoded `/tmp` paths, `signal.SIGKILL`, bash heredocs, `osascript`, `apt`, `systemctl`) must declare their supported platforms via the `platforms:` frontmatter. Default posture is to fix it cross-platform first — `tempfile.gettempdir()`, `pathlib.Path`, `psutil.pid_exists()`, Python-level filtering instead of `grep`. Gate to a narrower set only when the dependency is genuinely platform-bound (e.g. `osascript` is macOS-only, `/proc` is Linux-only).
606
+
607
+ 4. **`author` credits the human contributor first.** For external contributions, the contributor's real name + GitHub handle goes first (`Jane Doe (jane-doe)`); "Hermes Agent" is the secondary collaborator. If the contributor's commit shows "Hermes Agent" as author because they used Hermes to draft the skill, replace it with their actual name — credit the human, not the tool.
608
+
609
+ 5. **SKILL.md body uses the modern section order.** `# <Skill> Skill` title, 2-3 sentence intro stating what it does and what it doesn't do, then:
610
+ - `## When to Use` — trigger conditions
611
+ - `## Prerequisites` — env vars, install steps, MCP setup, API key sourcing
612
+ - `## How to Run` — canonical invocation through the `terminal` tool
613
+ - `## Quick Reference` — flat command/API reference
614
+ - `## Procedure` — numbered steps with copy-paste commands
615
+ - `## Pitfalls` — known limits, rate limits, things that look broken but aren't
616
+ - `## Verification` — single command that proves the skill works
617
+
618
+ Target ~200 lines for a complex skill, ~100 lines for a simple one. Cut redundant intro fluff, marketing prose, and re-explanations of env vars already documented in `## Prerequisites`.
619
+
620
+ 6. **Scripts go in `scripts/`, references in `references/`, templates in `templates/`.** Don't expect the model to inline-write parsers, XML walkers, or non-trivial logic every call — ship a helper script. Reference scripts from SKILL.md by path relative to the skill directory.
621
+
622
+ 7. **Tests live at `tests/skills/test_<skill>_skill.py`** and use only stdlib + pytest + `unittest.mock`. No live network calls. Run via `scripts/run_tests.sh tests/skills/test_<skill>_skill.py -q`. Must pass under the hermetic CI env (no API keys leaking through). Use `monkeypatch` and `tmp_path` for any env-var or filesystem dependencies.
623
+
624
+ 8. **`.env.example` additions are isolated to a clearly delimited block.** Don't touch the surrounding file — contributor-supplied `.env.example` versions are usually stale, and edits outside the skill's own block will be dropped during salvage. Comment all values with `#` (it's documentation, not live config).
625
+
626
+ ### Skill guidelines
627
+
628
+ - **No external dependencies unless absolutely necessary.** Prefer stdlib Python, curl, and existing Hermes tools (`web_extract`, `terminal`, `read_file`).
629
+ - **Progressive disclosure.** Put the most common workflow first. Edge cases and advanced usage go at the bottom.
630
+ - **Include helper scripts** for XML/JSON parsing or complex logic — don't expect the LLM to write parsers inline every time.
631
+ - **Test it.** Run `hermes --toolsets skills -q "Use the X skill to do Y"` and verify the agent follows the instructions correctly.
632
+
633
+ ---
634
+
635
+ ## Adding a Skin / Theme
636
+
637
+ Hermes uses a data-driven skin system — no code changes needed to add a new skin.
638
+
639
+ **Option A: User skin (YAML file)**
640
+
641
+ Create `~/.hermes/skins/<name>.yaml`:
642
+
643
+ ```yaml
644
+ name: mytheme
645
+ description: Short description of the theme
646
+
647
+ colors:
648
+ banner_border: "#HEX" # Panel border color
649
+ banner_title: "#HEX" # Panel title color
650
+ banner_accent: "#HEX" # Section header color
651
+ banner_dim: "#HEX" # Muted/dim text color
652
+ banner_text: "#HEX" # Body text color
653
+ response_border: "#HEX" # Response box border
654
+
655
+ spinner:
656
+ waiting_faces: ["(⚔)", "(⛨)"]
657
+ thinking_faces: ["(⚔)", "(⌁)"]
658
+ thinking_verbs: ["forging", "plotting"]
659
+ wings: # Optional left/right decorations
660
+ - ["⟪⚔", "⚔⟫"]
661
+
662
+ branding:
663
+ agent_name: "My Agent"
664
+ welcome: "Welcome message"
665
+ response_label: " ⚔ Agent "
666
+ prompt_symbol: "⚔"
667
+
668
+ tool_prefix: "╎" # Tool output line prefix
669
+ ```
670
+
671
+ All fields are optional — missing values inherit from the default skin.
672
+
673
+ **Option B: Built-in skin**
674
+
675
+ Add to `_BUILTIN_SKINS` dict in `hermes_cli/skin_engine.py`. Use the same schema as above but as a Python dict. Built-in skins ship with the package and are always available.
676
+
677
+ **Activating:**
678
+ - CLI: `/skin mytheme` or set `display.skin: mytheme` in config.yaml
679
+ - Config: `display: { skin: mytheme }`
680
+
681
+ See `hermes_cli/skin_engine.py` for the full schema and existing skins as examples.
682
+
683
+ ---
684
+
685
+ ## Cross-Platform Compatibility
686
+
687
+ Hermes runs on Linux, macOS, and native Windows (plus WSL2). When writing code
688
+ that touches the OS, assume *any* platform can hit your code path.
689
+
690
+ > **Before you PR:** run `scripts/check-windows-footguns.py` to catch the
691
+ > common Windows-unsafe patterns in your diff. It's grep-based and cheap;
692
+ > CI runs it on every PR too.
693
+
694
+ ### Critical rules
695
+
696
+ 1. **Never call `os.kill(pid, 0)` for liveness checks.** `os.kill(pid, 0)`
697
+ is a standard POSIX idiom to check "is this PID alive" — the signal 0
698
+ is a no-op permission check. **On Windows it is NOT a no-op.** Python's
699
+ Windows `os.kill` maps `sig=0` to `CTRL_C_EVENT` (they collide at the
700
+ integer value 0) and routes it through `GenerateConsoleCtrlEvent(0, pid)`,
701
+ which broadcasts Ctrl+C to the **entire console process group** containing
702
+ the target PID. "Probe if alive" silently becomes "kill the target and
703
+ often unrelated processes sharing its console." See [bpo-14484](https://bugs.python.org/issue14484)
704
+ (open since 2012 — will never be fixed for compat reasons).
705
+
706
+ **Preferred:** use `psutil` (a core dependency — always available):
707
+
708
+ ```python
709
+ import psutil
710
+ if psutil.pid_exists(pid):
711
+ # process is alive — safe on every platform
712
+ ...
713
+ ```
714
+
715
+ If you specifically need the hermes wrapper (it has a stdlib fallback
716
+ for scaffold-phase imports before pip install finishes), use
717
+ `gateway.status._pid_exists(pid)`. It calls `psutil.pid_exists` first
718
+ and falls back to a hand-rolled `OpenProcess + WaitForSingleObject`
719
+ dance on Windows only when psutil is somehow missing.
720
+
721
+ Audit grep for new callsites: `rg "os\.kill\([^,]+,\s*0\s*\)"`. Any hit
722
+ in non-test code is presumptively a Windows silent-kill bug.
723
+
724
+ 2. **Use `shutil.which()` before shelling out — don't assume Windows has
725
+ tools Linux has.** `wmic` was removed in Windows 10 21H1 and later. `ps`,
726
+ `kill`, `grep`, `awk`, `fuser`, `lsof`, `pgrep`, and most POSIX CLI tools
727
+ simply don't exist on Windows. Test availability with
728
+ `shutil.which("tool")` and fall back to a Windows-native equivalent —
729
+ usually PowerShell via `subprocess.run(["powershell", "-NoProfile",
730
+ "-Command", ...])`.
731
+
732
+ For process enumeration: PowerShell's `Get-CimInstance Win32_Process` is
733
+ the modern replacement for `wmic process`. See
734
+ `hermes_cli/gateway.py::_scan_gateway_pids` for the pattern.
735
+ ```
736
+
737
+ 3. **File encoding.** Windows may save `.env` files in `cp1252`. Always
738
+ handle encoding errors:
739
+ ```python
740
+ try:
741
+ load_dotenv(env_path)
742
+ except UnicodeDecodeError:
743
+ load_dotenv(env_path, encoding="latin-1")
744
+ ```
745
+ Config files (`config.yaml`) may be saved with a UTF-8 BOM by Notepad and
746
+ similar editors — use `encoding="utf-8-sig"` when reading files that
747
+ could have been touched by a Windows GUI editor.
748
+
749
+ 4. **Process management.** `os.setsid()`, `os.killpg()`, `os.fork()`,
750
+ `os.getuid()`, and POSIX signal handling differ on Windows. Guard with
751
+ `platform.system()`, `sys.platform`, or `hasattr(os, "setsid")`:
752
+ ```python
753
+ if platform.system() != "Windows":
754
+ kwargs["preexec_fn"] = os.setsid
755
+ else:
756
+ kwargs["creationflags"] = subprocess.CREATE_NEW_PROCESS_GROUP
757
+ ```
758
+
759
+ **Preferred:** for killing a process AND its children (what `os.killpg`
760
+ does on POSIX), use `psutil` — it works on every platform:
761
+ ```python
762
+ import psutil
763
+ try:
764
+ parent = psutil.Process(pid)
765
+ # Kill children first (leaf-up), then the parent.
766
+ for child in parent.children(recursive=True):
767
+ child.kill()
768
+ parent.kill()
769
+ except psutil.NoSuchProcess:
770
+ pass
771
+ ```
772
+
773
+ 5. **Signals that don't exist on Windows: `SIGALRM`, `SIGCHLD`, `SIGHUP`,
774
+ `SIGUSR1`, `SIGUSR2`, `SIGPIPE`, `SIGQUIT`, `SIGKILL`.** Python's
775
+ `signal` module raises `AttributeError` at import time if you reference
776
+ them on Windows. Use `getattr(signal, "SIGKILL", signal.SIGTERM)` or
777
+ gate the whole block behind a platform check. `loop.add_signal_handler`
778
+ raises `NotImplementedError` on Windows — always catch it.
779
+
780
+ 6. **Path separators.** Use `pathlib.Path` instead of string concatenation
781
+ with `/`. Forward slashes work almost everywhere on Windows, but
782
+ `subprocess.run(["cmd.exe", "/c", ...])` and other shell contexts can
783
+ require backslashes — convert with `str(path)` at the subprocess boundary,
784
+ not inside Python logic.
785
+
786
+ 7. **Symlinks need elevated privileges on Windows** (unless Developer Mode is
787
+ on). Tests that create symlinks need `@pytest.mark.skipif(sys.platform ==
788
+ "win32", reason="Symlinks require elevated privileges on Windows")`.
789
+
790
+ 8. **POSIX file modes (0o600, 0o644, etc.) are NOT enforced on NTFS** by
791
+ default. Tests that assert on `stat().st_mode & 0o777` must skip on
792
+ Windows — the concept doesn't translate. Use ACLs (`icacls`, `pywin32`)
793
+ for Windows secret-file protection if needed.
794
+
795
+ 9. **Detached background daemons on Windows need `pythonw.exe`, NOT
796
+ `python.exe`.** `python.exe` always allocates or attaches to a console,
797
+ which makes it vulnerable to `CTRL_C_EVENT` broadcasts from any sibling
798
+ process. `pythonw.exe` is the no-console variant. Combine with
799
+ `CREATE_NO_WINDOW | DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP |
800
+ CREATE_BREAKAWAY_FROM_JOB` in `subprocess.Popen(creationflags=...)`.
801
+ See `hermes_cli/gateway_windows.py::_spawn_detached` for the reference
802
+ implementation.
803
+
804
+ 10. **`subprocess.Popen` with `.cmd` or `.bat` shims needs `shutil.which`
805
+ to resolve.** Passing `"agent-browser"` to `Popen` on Windows finds
806
+ the extensionless POSIX shebang shim in `node_modules/.bin/`, which
807
+ `CreateProcessW` can't execute — you'll get `WinError 193 "not a valid
808
+ Win32 application"`. Use `shutil.which("agent-browser", path=local_bin)`
809
+ which honors PATHEXT and picks the `.CMD` variant on Windows.
810
+
811
+ 11. **Don't use shell shebangs as a way to run Python.** `#!/usr/bin/env
812
+ python` only works when the file is executed through a Unix shell.
813
+ `subprocess.run(["./myscript.py"])` on Windows fails even if the file
814
+ has a shebang line. Always invoke Python explicitly:
815
+ `[sys.executable, "myscript.py"]`.
816
+
817
+ 12. **Shell commands in installers.** If you change `scripts/install.sh`,
818
+ make the equivalent change in `scripts/install.ps1`. The two scripts
819
+ are the canonical example of "works on Linux does not mean works on
820
+ Windows" and have drifted multiple times — keep them in lockstep.
821
+
822
+ 13. **Known paths that are OneDrive-redirected on Windows:** Desktop,
823
+ Documents, Pictures, Videos. The "real" path when OneDrive Backup is
824
+ enabled is `%USERPROFILE%\OneDrive\Desktop` (etc.), NOT
825
+ `%USERPROFILE%\Desktop` (which exists as an empty husk). Resolve the
826
+ real location via `ctypes` + `SHGetKnownFolderPath` or by reading the
827
+ `Shell Folders` registry key — never assume `~/Desktop`.
828
+
829
+ 14. **CRLF vs LF in generated scripts.** Windows `cmd.exe` and `schtasks`
830
+ parse line-by-line; mixed or LF-only line endings can break multi-line
831
+ `.cmd` / `.bat` files. Use `open(path, "w", encoding="utf-8",
832
+ newline="\r\n")` — or `open(path, "wb")` + explicit bytes — when
833
+ generating scripts Windows will execute.
834
+
835
+ 15. **Two different quoting schemes in one command line.** `subprocess.run
836
+ (["schtasks", "/TR", some_cmd])` → schtasks itself parses `/TR`, AND
837
+ the `some_cmd` string is re-parsed by `cmd.exe` when the task fires.
838
+ Different parsers, different escape rules. Use two separate quoting
839
+ helpers and never cross them. See `hermes_cli/gateway_windows.py::
840
+ _quote_cmd_script_arg` and `_quote_schtasks_arg` for the reference
841
+ pair.
842
+
843
+ ### Testing cross-platform
844
+
845
+ Tests that excercise behavior on specific platforms must run on their target platforms.
846
+
847
+ ```python
848
+ @pytest.mark.linux_only
849
+ @pytest.mark.macos_only
850
+ @pytest.mark.windows_only
851
+ ```
852
+ Avoid monkeypatching `sys.platform` unless absolutely needed, but if you do, also patch `platform.system()` / `platform.release()` / `platform.mac_ver()`.
853
+ Symlinks, 0o600 permissions, SIGALRM, os.setsid/fork are all unix-only.
854
+
855
+ ---
856
+
857
+ ## Security Considerations
858
+
859
+ Hermes has terminal access. Security matters.
860
+
861
+ ### Existing protections
862
+
863
+ | Layer | Implementation |
864
+ |-------|---------------|
865
+ | **Sudo password piping** | Uses `shlex.quote()` to prevent shell injection |
866
+ | **Dangerous command detection** | Regex patterns in `tools/approval.py` with user approval flow |
867
+ | **Cron prompt injection** | Scanner in `tools/cronjob_tools.py` blocks instruction-override patterns |
868
+ | **Write deny list** | Protected paths (`~/.ssh/authorized_keys`, `/etc/shadow`) resolved via `os.path.realpath()` to prevent symlink bypass |
869
+ | **Skills guard** | Security scanner for hub-installed skills (`tools/skills_guard.py`) |
870
+ | **Code execution sandbox** | `execute_code` child process runs with API keys stripped from environment |
871
+ | **Container hardening** | Docker: all capabilities dropped, no privilege escalation, PID limits, size-limited tmpfs |
872
+
873
+ ### When contributing security-sensitive code
874
+
875
+ - **Always use `shlex.quote()`** when interpolating user input into shell commands
876
+ - **Resolve symlinks** with `os.path.realpath()` before path-based access control checks
877
+ - **Don't log secrets.** API keys, tokens, and passwords should never appear in log output
878
+ - **Catch broad exceptions** around tool execution so a single failure doesn't crash the agent loop
879
+ - **Test on all platforms** if your change touches file paths, process management, or shell commands
880
+
881
+ If your PR affects security, note it explicitly in the description.
882
+
883
+ ### Dependency pinning policy (supply chain hardening)
884
+
885
+ After the [litellm supply chain compromise](https://github.com/BerriAI/litellm/issues/24512) in March 2026 and the [Mini Shai-Hulud worm campaign](https://socket.dev/blog/tanstack-npm-packages-compromised-mini-shai-hulud-supply-chain-attack) in May 2026, all dependencies must follow these rules:
886
+
887
+ | Source type | Required treatment | Rationale |
888
+ |---|---|---|
889
+ | **PyPI package** | `>=floor,<next_major` | PyPI versions are immutable once published, but new versions can be pushed into your range. A `<next_major` ceiling stops a 1.x install from upgrading to a malicious 2.0.0. |
890
+ | **Git URL** (atroposlib, tinker, yc-bench, Baileys) | Full commit SHA | Branches and tags are mutable refs; SHA is content-addressed. |
891
+ | **GitHub Actions** | Full commit SHA + version comment | Action tags are mutable refs (e.g. tj-actions/changed-files March 2025). Pin as `uses: owner/action@<sha> # vX.Y.Z` |
892
+ | **CI-only pip installs** | `==exact` | Hermetic CI builds; churn is acceptable. |
893
+
894
+ **Every new PyPI dependency in a PR must have a `<next_major` upper bound.** PRs adding unbounded `>=X.Y.Z` specs will be rejected by reviewers. The `supply-chain-audit.yml` CI workflow also flags dependency manifest changes for manual review.
895
+
896
+ **How to determine the ceiling:**
897
+ - If the package is at version `1.x.y`, use `<2`.
898
+ - If the package is at version `0.x.y` (pre-1.0), use `<0.(current_minor + 2)` — e.g. if current is `0.29.x`, use `<0.32`. This gives ~2 minor versions of headroom while keeping the window small enough that a hostile takeover version is unlikely to land inside it.
899
+ - Exception: packages with very stable APIs (e.g. `aiohttp-socks`) can use `<1` at reviewer discretion.
900
+
901
+ **Examples:**
902
+ ```toml
903
+ # ✅ Correct — post-1.0
904
+ "openai>=2.21.0,<3"
905
+ "pydantic>=2.12.5,<3"
906
+
907
+ # ✅ Correct — pre-1.0 (tight minor window)
908
+ "asyncpg>=0.29,<0.32"
909
+ "aiosqlite>=0.20,<0.23"
910
+ "hindsight-client>=0.4.22,<0.5"
911
+
912
+ # ❌ Rejected — no upper bound
913
+ "some-package>=1.2.3"
914
+
915
+ # ❌ Rejected — too tight (blocks legitimate patches)
916
+ "some-package==1.2.3"
917
+
918
+ # ❌ Rejected — too loose for pre-1.0 (allows 80 minor versions)
919
+ "some-package>=0.20,<1"
920
+ ```
921
+
922
+ **Reference PRs:** #2796 (litellm removal), #2810 (upper bounds pass), #9801 (SHA pinning + supply-chain-audit CI).
923
+
924
+ ---
925
+
926
+ ## Pull Request Process
927
+
928
+ ### Branch naming
929
+
930
+ ```
931
+ fix/description # Bug fixes
932
+ feat/description # New features
933
+ docs/description # Documentation
934
+ test/description # Tests
935
+ refactor/description # Code restructuring
936
+ ```
937
+
938
+ ### Before submitting
939
+
940
+ 1. **Run tests**: `scripts/run_tests.sh` (recommended; same as CI) or `pytest tests/ -v` with the project venv activated
941
+ 2. **Test manually**: Run `hermes` and exercise the code path you changed
942
+ 3. **Check cross-platform impact**: If you touch file I/O, process management, or terminal handling, consider macOS, Linux, and WSL2
943
+ 4. **Keep PRs focused**: One logical change per PR. Don't mix a bug fix with a refactor with a new feature.
944
+
945
+ ### PR description
946
+
947
+ Include:
948
+ - **What** changed and **why**
949
+ - **How to test** it (reproduction steps for bugs, usage examples for features)
950
+ - **What platforms** you tested on
951
+ - Reference any related issues
952
+
953
+ ### Commit messages
954
+
955
+ We use [Conventional Commits](https://www.conventionalcommits.org/):
956
+
957
+ ```
958
+ <type>(<scope>): <description>
959
+ ```
960
+
961
+ | Type | Use for |
962
+ |------|---------|
963
+ | `fix` | Bug fixes |
964
+ | `feat` | New features |
965
+ | `docs` | Documentation |
966
+ | `test` | Tests |
967
+ | `refactor` | Code restructuring (no behavior change) |
968
+ | `chore` | Build, CI, dependency updates |
969
+
970
+ Scopes: `cli`, `gateway`, `tools`, `skills`, `agent`, `install`, `whatsapp`, `security`, etc.
971
+
972
+ Examples:
973
+ ```
974
+ fix(cli): prevent crash in save_config_value when model is a string
975
+ feat(gateway): add WhatsApp multi-user session isolation
976
+ fix(security): prevent shell injection in sudo password piping
977
+ test(tools): add unit tests for file_operations
978
+ ```
979
+
980
+ ---
981
+
982
+ ## Reporting Issues
983
+
984
+ - Use [GitHub Issues](https://github.com/NousResearch/hermes-agent/issues)
985
+ - Include: OS, Python version, Hermes version (`hermes --version`), full error traceback
986
+ - Include steps to reproduce
987
+ - Check existing issues before creating duplicates
988
+ - For security vulnerabilities, please report privately
989
+
990
+ ---
991
+
992
+ ## Community
993
+
994
+ - **Discord**: [discord.gg/NousResearch](https://discord.gg/NousResearch) — for questions, showcasing projects, and sharing skills
995
+ - **GitHub Discussions**: For design proposals and architecture discussions
996
+ - **Skills Hub**: Upload specialized skills to a registry and share them with the community
997
+
998
+ ---
999
+
1000
+ ## License
1001
+
1002
+ By contributing, you agree that your contributions will be licensed under the [MIT License](LICENSE).
README.md ADDED
@@ -0,0 +1,276 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: mit
3
+ tags:
4
+ - agent
5
+ - coding-agent
6
+ - cli
7
+ - llm
8
+ - tool-use
9
+ ---
10
+
11
+ > **This is a source mirror.** This Hugging Face repository is not a model checkpoint — it's a read-only mirror of the [`NousResearch/hermes-agent`](https://github.com/NousResearch/hermes-agent) GitHub repository, a self-improving AI agent built by Nous Research. It is hosted here for visibility on the Hub; the canonical repository, issue tracker, and pull requests all live on GitHub. Please file issues and contribute there, not here.
12
+
13
+ <p align="center">
14
+ <img src="assets/banner.png" alt="Hermes Agent" width="100%">
15
+ </p>
16
+
17
+ # Hermes Agent ☤
18
+ <p align="center">
19
+ <a href="https://hermes-agent.nousresearch.com/">Hermes Agent</a> | <a href="https://hermes-agent.nousresearch.com/">Hermes Desktop</a>
20
+ </p>
21
+ <p align="center">
22
+ <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
23
+ <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
24
+ <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
25
+ <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Built%20by-Nous%20Research-blueviolet?style=for-the-badge" alt="Built by Nous Research"></a>
26
+ <a href="README.zh-CN.md"><img src="https://img.shields.io/badge/Lang-中文-red?style=for-the-badge" alt="中文"></a>
27
+ <a href="README.ur-pk.md"><img src="https://img.shields.io/badge/Lang-اردو-green?style=for-the-badge" alt="اردو"></a>
28
+ <a href="README.es.md"><img src="https://img.shields.io/badge/Lang-Español-orange?style=for-the-badge" alt="Español"></a>
29
+ </p>
30
+
31
+ **The self-improving AI agent built by [Nous Research](https://nousresearch.com).** It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.
32
+
33
+ Use any model you want — [Nous Portal](https://portal.nousresearch.com), OpenRouter, OpenAI, your own endpoint, and [many others](https://hermes-agent.nousresearch.com/docs/integrations/providers). Switch with `hermes model` — no code changes, no lock-in.
34
+
35
+ <table>
36
+ <tr><td><b>A real terminal interface</b></td><td>Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.</td></tr>
37
+ <tr><td><b>Lives where you do</b></td><td>Telegram, Discord, Slack, WhatsApp, Signal, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.</td></tr>
38
+ <tr><td><b>A closed learning loop</b></td><td>Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. <a href="https://github.com/plastic-labs/honcho">Honcho</a> dialectic user modeling. Compatible with the <a href="https://agentskills.io">agentskills.io</a> open standard.</td></tr>
39
+ <tr><td><b>Scheduled automations</b></td><td>Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.</td></tr>
40
+ <tr><td><b>Delegates and parallelizes</b></td><td>Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.</td></tr>
41
+ <tr><td><b>Runs anywhere, not just your laptop</b></td><td>Seven terminal backends — local, Docker, SSH, Singularity, Modal, Daytona, and Vercel Sandbox. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.</td></tr>
42
+ <tr><td><b>Research-ready</b></td><td>Batch trajectory generation, trajectory compression for training the next generation of tool-calling models.</td></tr>
43
+ </table>
44
+
45
+ ---
46
+
47
+ ## Quick Install
48
+
49
+ ### Linux, macOS, WSL2, Termux
50
+
51
+ ```bash
52
+ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
53
+ ```
54
+
55
+ ### Windows (native, PowerShell)
56
+
57
+ > **Heads up:** Native Windows runs Hermes without WSL — CLI, gateway, TUI, and tools all work natively. If you'd rather use WSL2, the Linux/macOS one-liner above works there too. Found a bug? Please [file issues](https://github.com/NousResearch/hermes-agent/issues).
58
+
59
+ Run this in PowerShell:
60
+
61
+ ```powershell
62
+ iex (irm https://hermes-agent.nousresearch.com/install.ps1)
63
+ ```
64
+
65
+ The installer handles everything: uv, Python 3.11, Node.js, ripgrep, ffmpeg, **and a portable Git Bash** (MinGit, unpacked to `%LOCALAPPDATA%\hermes\git` — no admin required, completely isolated from any system Git install). Hermes uses this bundled Git Bash to run shell commands.
66
+
67
+ If you already have Git installed, the installer detects it and uses that instead. Otherwise a ~45MB MinGit download is all you need — it won't touch or interfere with any system Git.
68
+
69
+ > **Android / Termux:** The tested manual path is documented in the [Termux guide](https://hermes-agent.nousresearch.com/docs/getting-started/termux). On Termux, Hermes installs a curated `.[termux]` extra because the full `.[all]` extra currently pulls Android-incompatible voice dependencies.
70
+ >
71
+ > **Windows:** Native Windows is fully supported — the PowerShell one-liner above installs everything. If you'd rather use WSL2, the Linux command works there too. Native Windows install lives under `%LOCALAPPDATA%\hermes`; WSL2 installs under `~/.hermes` as on Linux.
72
+
73
+ After installation:
74
+
75
+ ```bash
76
+ source ~/.bashrc # reload shell (or: source ~/.zshrc)
77
+ hermes # start chatting!
78
+ ```
79
+
80
+ ### Troubleshooting
81
+
82
+ #### Windows Defender or antivirus flags `uv.exe` as malware
83
+
84
+ If your antivirus (Bitdefender, Windows Defender, etc.) quarantines `uv.exe` from the Hermes `bin` folder (`%LOCALAPPDATA%\hermes\bin\uv.exe`), this is a **false positive**. The file is Astral's `uv` — the Rust Python package manager Hermes bundles to manage its Python environment. ML-based antivirus engines commonly flag unsigned Rust binaries that download and install packages.
85
+
86
+ **To verify your copy is authentic:**
87
+
88
+ ```powershell
89
+ # Install GitHub CLI if needed
90
+ winget install --id GitHub.cli
91
+
92
+ # Login to GitHub
93
+ gh auth login
94
+
95
+ # Run verification
96
+ $uv = "$env:LOCALAPPDATA\hermes\bin\uv.exe"
97
+ $ver = (& $uv --version).Split(' ')[1]
98
+ [Net.ServicePointManager]::SecurityProtocol = [Net.SecurityProtocolType]::Tls12
99
+ $zip = "$env:TEMP\uv.zip"
100
+ Invoke-WebRequest "https://github.com/astral-sh/uv/releases/download/$ver/uv-x86_64-pc-windows-msvc.zip" -OutFile $zip -UseBasicParsing
101
+ gh attestation verify $zip --repo astral-sh/uv
102
+ Expand-Archive $zip "$env:TEMP\uv_x" -Force
103
+ (Get-FileHash "$env:TEMP\uv_x\uv.exe").Hash -eq (Get-FileHash $uv).Hash
104
+ ```
105
+
106
+ If attestation says "Verification succeeded" and the last line prints `True`, you're good.
107
+
108
+ **To whitelist Hermes:**
109
+ - **Windows Defender:** Run PowerShell as Admin → `Add-MpPreference -ExclusionPath "$env:LOCALAPPDATA\hermes\bin"`
110
+ - **Bitdefender:** Add an exception in the Bitdefender console (Protection > Antivirus > Settings > Manage Exceptions)
111
+ - Whitelist the **folder**, not the file hash — Hermes updates `uv` and the hash changes every version
112
+
113
+ For more context, see the upstream Astral reports: [astral-sh/uv#13553](https://github.com/astral-sh/uv/issues/13553), [astral-sh/uv#15011](https://github.com/astral-sh/uv/issues/15011), [astral-sh/uv#10079](https://github.com/astral-sh/uv/issues/10079).
114
+
115
+ ---
116
+
117
+ ## Getting Started
118
+
119
+ ```bash
120
+ hermes # Interactive CLI — start a conversation
121
+ hermes model # Choose your LLM provider and model
122
+ hermes tools # Configure which tools are enabled
123
+ hermes config set # Set individual config values
124
+ hermes config get # Print individual config values
125
+ hermes gateway # Start the messaging gateway (Telegram, Discord, etc.)
126
+ hermes setup # Run the full setup wizard (configures everything at once)
127
+ hermes claw migrate # Migrate from OpenClaw (if coming from OpenClaw)
128
+ hermes update # Update to the latest version
129
+ hermes doctor # Diagnose any issues
130
+ ```
131
+
132
+ 📖 **[Full documentation →](https://hermes-agent.nousresearch.com/docs/)**
133
+
134
+ ---
135
+
136
+ ## Skip the API-key collection — Nous Portal
137
+
138
+ Hermes works with whatever provider you want — that's not changing. But if you'd rather not collect five separate API keys for the model, web search, image generation, TTS, and a cloud browser, **[Nous Portal](https://portal.nousresearch.com)** covers all of them under one subscription:
139
+
140
+ - **300+ models** — pick any of them with `/model <name>`
141
+ - **Tool Gateway** — web search (Firecrawl), image generation (FAL), text-to-speech (OpenAI), cloud browser (Browser Use), all routed through your sub. No extra accounts.
142
+
143
+ One command from a fresh install:
144
+
145
+ ```bash
146
+ hermes setup --portal
147
+ ```
148
+
149
+ That logs you in via OAuth, sets Nous as your provider, and turns on the Tool Gateway. Check what's wired up any time with `hermes portal info`. Full details on the [Tool Gateway docs page](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway).
150
+
151
+ You can still bring your own keys per-tool whenever you want — the gateway is per-backend, not all-or-nothing.
152
+
153
+ ---
154
+
155
+ ## CLI vs Messaging Quick Reference
156
+
157
+ Hermes has two entry points: start the terminal UI with `hermes`, or run the gateway and talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or Email. Once you're in a conversation, many slash commands are shared across both interfaces.
158
+
159
+ | Action | CLI | Messaging platforms |
160
+ | ------------------------------ | --------------------------------------------- | -------------------------------------------------------------------------------- |
161
+ | Start chatting | `hermes` | Run `hermes gateway setup` + `hermes gateway start`, then send the bot a message |
162
+ | Start fresh conversation | `/new` or `/reset` | `/new` or `/reset` |
163
+ | Change model | `/model [provider:model]` | `/model [provider:model]` |
164
+ | Set a personality | `/personality [name]` | `/personality [name]` |
165
+ | Retry or undo the last turn | `/retry`, `/undo` | `/retry`, `/undo` |
166
+ | Compress context / check usage | `/compress`, `/usage`, `/insights [--days N]` | `/compress`, `/usage`, `/insights [days]` |
167
+ | Browse skills | `/skills` or `/<skill-name>` | `/<skill-name>` |
168
+ | Interrupt current work | `Ctrl+C` or send a new message | `/stop` or send a new message |
169
+ | Platform-specific status | `/platforms` | `/status`, `/sethome` |
170
+
171
+ For the full command lists, see the [CLI guide](https://hermes-agent.nousresearch.com/docs/user-guide/cli) and the [Messaging Gateway guide](https://hermes-agent.nousresearch.com/docs/user-guide/messaging).
172
+
173
+ ---
174
+
175
+ ## Documentation
176
+
177
+ All documentation lives at **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**:
178
+
179
+ | Section | What's Covered |
180
+ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
181
+ | [Quickstart](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | Install → setup → first conversation in 2 minutes |
182
+ | [CLI Usage](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | Commands, keybindings, personalities, sessions |
183
+ | [Configuration](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | Config file, providers, models, all options |
184
+ | [Messaging Gateway](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant |
185
+ | [Security](https://hermes-agent.nousresearch.com/docs/user-guide/security) | Command approval, DM pairing, container isolation |
186
+ | [Tools & Toolsets](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ tools, toolset system, terminal backends |
187
+ | [Skills System](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | Procedural memory, Skills Hub, creating skills |
188
+ | [Memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | Persistent memory, user profiles, best practices |
189
+ | [MCP Integration](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | Connect any MCP server for extended capabilities |
190
+ | [Cron Scheduling](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | Scheduled tasks with platform delivery |
191
+ | [Context Files](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | Project context that shapes every conversation |
192
+ | [Architecture](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | Project structure, agent loop, key classes |
193
+ | [Contributing](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | Development setup, PR process, code style |
194
+ | [CLI Reference](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) | All commands and flags |
195
+ | [Environment Variables](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | Complete env var reference |
196
+
197
+ ---
198
+
199
+ ## Migrating from OpenClaw
200
+
201
+ If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys.
202
+
203
+ **During first-time setup:** The setup wizard (`hermes setup`) automatically detects `~/.openclaw` and offers to migrate before configuration begins.
204
+
205
+ **Anytime after install:**
206
+
207
+ ```bash
208
+ hermes claw migrate # Interactive migration (full preset)
209
+ hermes claw migrate --dry-run # Preview what would be migrated
210
+ hermes claw migrate --preset user-data # Migrate without secrets
211
+ hermes claw migrate --overwrite # Overwrite existing conflicts
212
+ ```
213
+
214
+ What gets imported:
215
+
216
+ - **SOUL.md** — persona file
217
+ - **Memories** — MEMORY.md and USER.md entries
218
+ - **Skills** — user-created skills → `~/.hermes/skills/openclaw-imports/`
219
+ - **Command allowlist** — approval patterns
220
+ - **Messaging settings** — platform configs, allowed users, working directory
221
+ - **API keys** — allowlisted secrets (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs)
222
+ - **TTS assets** — workspace audio files
223
+ - **Workspace instructions** — AGENTS.md (with `--workspace-target`)
224
+
225
+ See `hermes claw migrate --help` for all options, or use the `openclaw-migration` skill for an interactive agent-guided migration with dry-run previews.
226
+
227
+ ---
228
+
229
+ ## Contributing
230
+
231
+ We welcome contributions! See the [Contributing Guide](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) for development setup, code style, and PR process.
232
+
233
+ Quick start for contributors — use the standard installer, then work from the
234
+ full git checkout it creates at `$HERMES_HOME/hermes-agent` (usually
235
+ `~/.hermes/hermes-agent`). This matches the layout used by `hermes update`, the
236
+ managed venv, lazy dependencies, gateway, and docs tooling.
237
+
238
+ ```bash
239
+ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
240
+ cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
241
+ uv pip install -e ".[all,dev]"
242
+ scripts/run_tests.sh
243
+ ```
244
+
245
+ Manual clone fallback (for throwaway clones/CI where you intentionally do not
246
+ want the managed install layout):
247
+
248
+ Create the venv outside the cloned source tree — a venv inside the directory
249
+ the agent operates from can be wiped by a relative-path command the agent runs
250
+ against its own checkout, destroying the running runtime mid-session.
251
+
252
+ ```bash
253
+ curl -LsSf https://astral.sh/uv/install.sh | sh
254
+ uv venv ~/.hermes/venvs/hermes-dev --python 3.11
255
+ source ~/.hermes/venvs/hermes-dev/bin/activate
256
+ uv pip install -e ".[all,dev]"
257
+ scripts/run_tests.sh
258
+ ```
259
+
260
+ ---
261
+
262
+ ## Community
263
+
264
+ - 💬 [Discord](https://discord.gg/NousResearch)
265
+ - 📚 [Skills Hub](https://agentskills.io)
266
+ - 🐛 [Issues](https://github.com/NousResearch/hermes-agent/issues)
267
+ - 🔌 [computer-use-linux](https://github.com/avifenesh/computer-use-linux) — Linux desktop-control MCP server for Hermes and other MCP hosts, with AT-SPI accessibility trees, Wayland/X11 input, screenshots, and compositor window targeting.
268
+ - 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.
269
+
270
+ ---
271
+
272
+ ## License
273
+
274
+ MIT — see [LICENSE](LICENSE).
275
+
276
+ Built by [Nous Research](https://nousresearch.com).
README.zh-CN.md ADDED
@@ -0,0 +1,208 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ <p align="center">
2
+ <img src="assets/banner.png" alt="Hermes Agent" width="100%">
3
+ </p>
4
+
5
+ # Hermes Agent ☤
6
+
7
+ <p align="center">
8
+ <a href="https://hermes-agent.nousresearch.com/docs/"><img src="https://img.shields.io/badge/Docs-hermes--agent.nousresearch.com-FFD700?style=for-the-badge" alt="Documentation"></a>
9
+ <a href="https://discord.gg/NousResearch"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord"></a>
10
+ <a href="https://github.com/NousResearch/hermes-agent/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-green?style=for-the-badge" alt="License: MIT"></a>
11
+ <a href="https://nousresearch.com"><img src="https://img.shields.io/badge/Built%20by-Nous%20Research-blueviolet?style=for-the-badge" alt="Built by Nous Research"></a>
12
+ <a href="README.md"><img src="https://img.shields.io/badge/Lang-English-lightgrey?style=for-the-badge" alt="English"></a>
13
+ <a href="README.ur-pk.md"><img src="https://img.shields.io/badge/Lang-اردو-green?style=for-the-badge" alt="اردو"></a>
14
+ </p>
15
+
16
+ **由 [Nous Research](https://nousresearch.com) 构建的自进化 AI 代理。** 它是唯一内置学习闭环的智能代理——从经验中创建技能,在使用中改进技能,主动持久化知识,搜索过往对话,并在跨会话中逐步构建对你的深度理解。可以在 $5 的 VPS 上运行,也可以在 GPU 集群上运行,或者使用几乎零成本的 Serverless 基础设施。它不绑定你的笔记本——你可以在 Telegram 上与它对话,而它在云端 VM 上工作。
17
+
18
+ 支持任意模型——[Nous Portal](https://portal.nousresearch.com)、[OpenRouter](https://openrouter.ai)(200+ 模型)、[NVIDIA NIM](https://build.nvidia.com)(Nemotron)、[小米 MiMo](https://platform.xiaomimimo.com)、[z.ai/GLM](https://z.ai)、[Kimi/Moonshot](https://platform.moonshot.ai)、[MiniMax](https://www.minimax.io)、[Hugging Face](https://huggingface.co)、OpenAI,或自定义端点。使用 `hermes model` 即可切换——无需改代码,无锁定。
19
+
20
+ <table>
21
+ <tr><td><b>真正的终端界面</b></td><td>完整的 TUI,支持多行编辑、斜杠命令自动补全、对话历史、中断重定向和流式工具输出。</td></tr>
22
+ <tr><td><b>随你所在</b></td><td>Telegram、Discord、Slack、WhatsApp、Signal 和 CLI——全部从单个网关进程运行。语音备忘录转写、跨平台对话连续性。</td></tr>
23
+ <tr><td><b>闭环学习</b></td><td>代理管理记忆并定期自我提醒。复杂任务后自动创建技能。技能在使用中自我改进。FTS5 会话搜索配合 LLM 摘要实现跨会话回溯。<a href="https://github.com/plastic-labs/honcho">Honcho</a> 辩证式用户建模。兼容 <a href="https://agentskills.io">agentskills.io</a> 开放标准。</td></tr>
24
+ <tr><td><b>定时自动化</b></td><td>内置 cron 调度器,支持向任何平台投递。日报、夜间备份、周审计——全部用自然语言描述,无人值守运行。</td></tr>
25
+ <tr><td><b>委派与并行</b></td><td>生成隔离子代理处理并行工作流。编写 Python 脚本通过 RPC 调用工具,将多步管道压缩为零上下文开销的轮次。</td></tr>
26
+ <tr><td><b>随处运行</b></td><td>六种终端后端——本地、Docker、SSH、Daytona、Singularity 和 Modal。Daytona 和 Modal 提供 Serverless 持久化——代理环境空闲时休眠、按需唤醒,空闲期间几乎零成本。$5 VPS 或 GPU 集群都能跑。</td></tr>
27
+ <tr><td><b>研究就绪</b></td><td>批量轨迹生成、轨迹压缩——用于训练下一代工具调用模型。</td></tr>
28
+ </table>
29
+
30
+ ---
31
+
32
+ ## 快速安装
33
+
34
+ ```bash
35
+ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
36
+ ```
37
+
38
+ 支持 Linux、macOS、WSL2 和 Android (Termux)。安装程序会自动处理平台特定的配置。
39
+
40
+ > **Android / Termux:** 已测试的手动安装路径请参考 [Termux 指南](https://hermes-agent.nousresearch.com/docs/getting-started/termux)。在 Termux 上,Hermes 会安装精选的 `.[termux]` 扩展,因为完整的 `.[all]` 扩展会拉取 Android 不兼容的语音依赖。
41
+ >
42
+ > **Windows:** 在 PowerShell 中运行:
43
+ > ```powershell
44
+ > iex (irm https://hermes-agent.nousresearch.com/install.ps1)
45
+ > ```
46
+ > 安装完成后,可能需要重启终端,然后运行 `hermes` 开始对话。
47
+
48
+ 安装后:
49
+
50
+ ```bash
51
+ source ~/.bashrc # 重新加载 shell(或: source ~/.zshrc)
52
+ hermes # 开始对话!
53
+ ```
54
+
55
+ ---
56
+
57
+ ## 快速入门
58
+
59
+ ```bash
60
+ hermes # 交互式 CLI — 开始对话
61
+ hermes model # 选择 LLM 提供商和模型
62
+ hermes tools # 配置启用的工具
63
+ hermes config set # 设置单个配置项
64
+ hermes gateway # 启动消息网关(Telegram、Discord 等)
65
+ hermes setup # 运行完整设置向导(一次性配置所有内容)
66
+ hermes claw migrate # 从 OpenClaw 迁移(如果来自 OpenClaw)
67
+ hermes update # 更新到最新版本
68
+ hermes doctor # 诊断问题
69
+ ```
70
+
71
+ 📖 **[完整文档 →](https://hermes-agent.nousresearch.com/docs/)**
72
+
73
+ ---
74
+
75
+ ## 省去到处收集 API Key — Nous Portal
76
+
77
+ Hermes 始终允许你使用任意服务商,这点不会改变。但如果你不想为模型、网页搜索、图像生成、TTS、云浏览器分别去申请五个不同的 API Key,**[Nous Portal](https://portal.nousresearch.com)** 用一个订阅就能覆盖全部:
78
+
79
+ - **300+ 模型** — 用 `/model <name>` 随时切换
80
+ - **Tool Gateway** — 网页搜索(Firecrawl)、图像生成(FAL)、文本转语音(OpenAI)、云浏览器(Browser Use),全部通过订阅托管。无需额外注册任何账户。
81
+
82
+ 全新安装时一条命令即可:
83
+
84
+ ```bash
85
+ hermes setup --portal
86
+ ```
87
+
88
+ 它会通过 OAuth 登录、把 Nous 设为推理服务商,并启用 Tool Gateway。随时用 `hermes portal info` 查看路由状态。完整说明见 [Tool Gateway 文档](https://hermes-agent.nousresearch.com/docs/user-guide/features/tool-gateway)。
89
+
90
+ 你随时可以按工具单独切回自己的 API Key — Gateway 是按工具粒度生效的,不是一刀切。
91
+
92
+ ---
93
+
94
+ ## CLI 与消息平台 快速对照
95
+
96
+ Hermes 有两种入口:用 `hermes` 启动终端 UI,或运行网关从 Telegram、Discord、Slack、WhatsApp、Signal 或 Email 与之对话。进入对话后,许多斜杠命令在两种界面中通用。
97
+
98
+ | 操作 | CLI | 消息平台 |
99
+ |------|-----|----------|
100
+ | 开始对话 | `hermes` | 运行 `hermes gateway setup` + `hermes gateway start`,然后给机器人发消息 |
101
+ | 开始新对话 | `/new` 或 `/reset` | `/new` 或 `/reset` |
102
+ | 更换模型 | `/model [provider:model]` | `/model [provider:model]` |
103
+ | 设置人格 | `/personality [name]` | `/personality [name]` |
104
+ | 重试或撤销上一轮 | `/retry`、`/undo` | `/retry`、`/undo` |
105
+ | 压缩上下文 / 查看用量 | `/compress`、`/usage`、`/insights [--days N]` | `/compress`、`/usage`、`/insights [days]` |
106
+ | 浏览技能 | `/skills` 或 `/<skill-name>` | `/skills` 或 `/<skill-name>` |
107
+ | 中断当前工作 | `Ctrl+C` 或发送新消息 | `/stop` 或发送新消息 |
108
+ | 平台特定状态 | `/platforms` | `/status`、`/sethome` |
109
+
110
+ 完整命令列表请参阅 [CLI 指南](https://hermes-agent.nousresearch.com/docs/user-guide/cli) 和 [消息网关指南](https://hermes-agent.nousresearch.com/docs/user-guide/messaging)。
111
+
112
+ ---
113
+
114
+ ## 文档
115
+
116
+ 所有文档位于 **[hermes-agent.nousresearch.com/docs](https://hermes-agent.nousresearch.com/docs/)**:
117
+
118
+ | 章节 | 内容 |
119
+ |------|------|
120
+ | [快速开始](https://hermes-agent.nousresearch.com/docs/getting-started/quickstart) | 安装 → 设置 → 2 分钟内开始首次对话 |
121
+ | [CLI 使用](https://hermes-agent.nousresearch.com/docs/user-guide/cli) | 命令、快捷键、人格、会话 |
122
+ | [配置](https://hermes-agent.nousresearch.com/docs/user-guide/configuration) | 配置文件、提供商、模型、所有选项 |
123
+ | [消息网关](https://hermes-agent.nousresearch.com/docs/user-guide/messaging) | Telegram、Discord、Slack、WhatsApp、Signal、Home Assistant |
124
+ | [安全](https://hermes-agent.nousresearch.com/docs/user-guide/security) | 命令审批、DM 配对、容器隔离 |
125
+ | [工具与工具集](https://hermes-agent.nousresearch.com/docs/user-guide/features/tools) | 40+ 工具、工具集系统、终端后端 |
126
+ | [技能系统](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) | 过程记忆、技能中心、创建技能 |
127
+ | [记忆](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) | 持久记忆、用户画像、最佳实践 |
128
+ | [MCP 集成](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp) | 连接任意 MCP 服务器扩展能力 |
129
+ | [定时调度](https://hermes-agent.nousresearch.com/docs/user-guide/features/cron) | 定时任务与平台投递 |
130
+ | [上下文文件](https://hermes-agent.nousresearch.com/docs/user-guide/features/context-files) | 影响每次对话的项目上下文 |
131
+ | [架构](https://hermes-agent.nousresearch.com/docs/developer-guide/architecture) | 项目结构、代理循环、关键类 |
132
+ | [贡献](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) | 开发设置、PR 流程、代码风格 |
133
+ | [CLI 参考](https://hermes-agent.nousresearch.com/docs/reference/cli-commands) | 所有命令和标志 |
134
+ | [环境变量](https://hermes-agent.nousresearch.com/docs/reference/environment-variables) | 完整环境变量参考 |
135
+
136
+ ---
137
+
138
+ ## 从 OpenClaw 迁移
139
+
140
+ 如果你来自 OpenClaw,Hermes 可以自动导入你的设置、记忆、技能和 API 密钥。
141
+
142
+ **首次安装时:** 安装向导(`hermes setup`)会自动检测 `~/.openclaw` 并在配置开始前提供迁移选项。
143
+
144
+ **安装后任意时间:**
145
+
146
+ ```bash
147
+ hermes claw migrate # 交互式迁移(完整预设)
148
+ hermes claw migrate --dry-run # 预览将要迁移的内容
149
+ hermes claw migrate --preset user-data # 仅迁移用户数据,不含密钥
150
+ hermes claw migrate --overwrite # 覆盖已有冲突
151
+ ```
152
+
153
+ 导入内容:
154
+ - **SOUL.md** — 人格文件
155
+ - **记忆** — MEMORY.md 和 USER.md 条目
156
+ - **技能** — 用户创建的技能 → `~/.hermes/skills/openclaw-imports/`
157
+ - **命令白名单** — 审批模式
158
+ - **消息设置** — 平台配置、允许用户、工作目录
159
+ - **API 密钥** — 白名单中的密钥(Telegram、OpenRouter、OpenAI、Anthropic、ElevenLabs)
160
+ - **TTS 资产** — 工作区音频文件
161
+ - **工作区指令** — AGENTS.md(使用 `--workspace-target`)
162
+
163
+ 使用 `hermes claw migrate --help` 查看所有选项,或使用 `openclaw-migration` 技能进行交互式代理引导迁移(含干运行预览)。
164
+
165
+ ---
166
+
167
+ ## 贡献
168
+
169
+ 欢迎贡献!请参阅 [贡献指南](https://hermes-agent.nousresearch.com/docs/developer-guide/contributing) 了解开发设置、代码风格和 PR 流程。
170
+
171
+ 贡献者快速开始——使用标准安装器,然后在它创建的完整 git checkout 中开发:
172
+ `$HERMES_HOME/hermes-agent`(通常是 `~/.hermes/hermes-agent`)。这会匹配
173
+ `hermes update`、托管 venv、lazy dependencies、gateway 和 docs tooling 使用的布局。
174
+
175
+ ```bash
176
+ curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
177
+ cd "${HERMES_HOME:-$HOME/.hermes}/hermes-agent"
178
+ uv pip install -e ".[all,dev]"
179
+ scripts/run_tests.sh
180
+ ```
181
+
182
+ 手动克隆备用路径(用于一次性 clone / CI,或你明确不想使用 managed install layout 时):
183
+
184
+ ```bash
185
+ curl -LsSf https://astral.sh/uv/install.sh | sh
186
+ uv venv venv --python 3.11
187
+ source venv/bin/activate
188
+ uv pip install -e ".[all,dev]"
189
+ python -m pytest tests/ -q
190
+ ```
191
+
192
+ ---
193
+
194
+ ## 社区
195
+
196
+ - 💬 [Discord](https://discord.gg/NousResearch)
197
+ - 📚 [技能中心](https://agentskills.io)
198
+ - 🐛 [问题反馈](https://github.com/NousResearch/hermes-agent/issues)
199
+ - 💡 [讨论区](https://github.com/NousResearch/hermes-agent/discussions)
200
+ - 🔌 [HermesClaw](https://github.com/AaronWong1999/hermesclaw) — 社区微信桥接:在同一微信账号上运行 Hermes Agent 和 OpenClaw。
201
+
202
+ ---
203
+
204
+ ## 许可证
205
+
206
+ MIT — 详见 [LICENSE](LICENSE)。
207
+
208
+ 由 [Nous Research](https://nousresearch.com) 构建。
SECURITY.es.md ADDED
@@ -0,0 +1,326 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Política de Seguridad de Hermes Agent
2
+
3
+ Este documento describe el modelo de confianza de Hermes Agent, identifica el
4
+ único límite de seguridad que el proyecto trata como estructural y define el
5
+ alcance para los informes de vulnerabilidades.
6
+
7
+ ## 1. Reportar una Vulnerabilidad
8
+
9
+ Reporta de forma privada a través de [GitHub Security Advisories](https://github.com/NousResearch/hermes-agent/security/advisories/new)
10
+ o **security@nousresearch.com**. No abras issues públicos para
11
+ vulnerabilidades de seguridad. **Hermes Agent no opera un programa de
12
+ recompensas por errores.**
13
+
14
+ Un informe útil incluye:
15
+
16
+ - Una descripción concisa y evaluación de severidad.
17
+ - El componente afectado, identificado por ruta de archivo y rango de líneas
18
+ (ej. `path/to/file.py:120-145`).
19
+ - Detalles del entorno (`hermes --version`, SHA del commit, SO, versión de Python).
20
+ - Una reproducción contra `main` o el último release.
21
+ - Una declaración de qué límite de confianza del §2 se cruza.
22
+
23
+ Por favor lee el §2 y el §3 antes de enviar. Los informes que demuestren
24
+ límites de una heurística en proceso que esta política no trate como un
25
+ límite serán cerrados como fuera de alcance bajo el §3 — pero consulta el §3.2:
26
+ siguen siendo bienvenidos como issues o pull requests regulares, simplemente no
27
+ a través del canal de seguridad privado.
28
+
29
+ ---
30
+
31
+ ## 2. Modelo de Confianza
32
+
33
+ Hermes Agent es un agente personal de un solo inquilino. Su postura es
34
+ por capas, y las capas no tienen el mismo peso. Los reportadores y
35
+ operadores deben razonar sobre ellas en los mismos términos.
36
+
37
+ ### 2.1 Definiciones
38
+
39
+ - **Proceso del agente.** El intérprete Python que ejecuta Hermes Agent,
40
+ incluyendo cualquier módulo Python que haya cargado (habilidades, plugins,
41
+ manejadores de hooks).
42
+ - **Backend de terminal.** Un objetivo de ejecución conectado para la
43
+ herramienta `terminal()`. El predeterminado ejecuta comandos directamente en el host.
44
+ Otros backends ejecutan comandos dentro de un contenedor, sandbox en la nube o
45
+ host remoto.
46
+ - **Superficie de entrada.** Cualquier canal a través del cual el contenido entra en el
47
+ contexto del agente: entrada del operador, fetches web, email, mensajes del gateway,
48
+ lecturas de archivos, respuestas del servidor MCP, resultados de herramientas.
49
+ - **Envolvente de confianza.** El conjunto de recursos a los que un operador ha otorgado
50
+ implícitamente acceso a Hermes Agent al ejecutarlo — típicamente, todo lo que
51
+ la propia cuenta de usuario del operador puede alcanzar en el host.
52
+ - **Postura.** Una declaración explícita en la documentación o código de Hermes Agent
53
+ sobre cómo una capa consumidora (adaptador, UI, escritor de archivos,
54
+ shell) debe tratar la salida del agente — ej. "el dashboard renderiza
55
+ la salida del agente como HTML inerte."
56
+
57
+ ### 2.2 El Límite: Aislamiento a Nivel de SO
58
+
59
+ **El único límite de seguridad contra un LLM adversario es el
60
+ sistema operativo.** Nada dentro del proceso del agente constituye
61
+ contención — ni la puerta de aprobación, ni la redacción de salida, ni ningún
62
+ escáner de patrones, ni ninguna lista de herramientas permitidas. Cualquier componente dentro
63
+ del proceso que filtre la salida del LLM es una heurística operando sobre una
64
+ cadena influenciada por el atacante, y esta política lo trata como tal.
65
+
66
+ Hermes Agent admite dos posturas de aislamiento a nivel de SO. Abordan
67
+ diferentes amenazas y un operador debe elegir deliberadamente.
68
+
69
+ #### Aislamiento del backend de terminal
70
+
71
+ Un backend de terminal no predeterminado ejecuta comandos de shell emitidos por el LLM
72
+ dentro de un contenedor, host remoto o sandbox en la nube. Las herramientas de archivos
73
+ (`read_file`, `write_file`, `patch`) también se ejecutan a través de este backend,
74
+ ya que están implementadas sobre el contrato del shell — no pueden
75
+ alcanzar rutas que el backend no exponga.
76
+
77
+ Lo que confina: todo lo que el agente hace emitiendo operaciones de shell o
78
+ de archivos. Lo que **no** confina: todo lo que el agente hace en su propio
79
+ proceso Python. Eso incluye la herramienta de ejecución de código (lanzada como
80
+ subproceso del host), subprocesos MCP (lanzados desde el entorno del agente),
81
+ carga de plugins, despacho de hooks y carga de habilidades (todos importados en el
82
+ intérprete del agente).
83
+
84
+ El aislamiento del backend de terminal es la postura correcta cuando la preocupación es
85
+ que el LLM emita comandos de shell destructivos o escrituras de herramientas de archivo no deseadas, y el
86
+ operador es de confianza.
87
+
88
+ #### Envoltura del proceso completo
89
+
90
+ La envoltura del proceso completo ejecuta todo el árbol de procesos del agente dentro de un
91
+ sandbox. Cada ruta de código — shell, ejecución de código, MCP, herramientas de archivos,
92
+ plugins, hooks, carga de habilidades — está sujeta a la misma política de sistema de archivos,
93
+ red, proceso e (donde sea aplicable) inferencia.
94
+
95
+ Hermes Agent admite esto de dos maneras:
96
+
97
+ - **La propia imagen Docker de Hermes Agent y la configuración de Compose.** Más
98
+ liviana; el agente se ejecuta en un contenedor estándar con montajes y
99
+ política de red configurados por el operador.
100
+ - **[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)**.
101
+ OpenShell proporciona sandboxes por sesión con política declarativa
102
+ a través de capas de sistema de archivos, red (egreso L7), proceso/syscall e
103
+ enrutamiento de inferencia. Las políticas de red e inferencia son
104
+ recargables en caliente. Las credenciales se inyectan desde un almacén de Proveedor
105
+ y nunca tocan el sistema de archivos del sandbox.
106
+
107
+ Bajo una envoltura de proceso completo, las heurísticas en proceso de Hermes Agent
108
+ (§2.4) funcionan como prevención de accidentes en capas sobre un límite real.
109
+ Esta es la postura soportada cuando el agente ingiere contenido de superficies
110
+ que el operador no controla — la web abierta, email entrante, canales de
111
+ múltiples usuarios, servidores MCP no confiables — y para despliegues en
112
+ producción o compartidos.
113
+
114
+ Los operadores que ejecuten el backend local predeterminado con superficies de entrada
115
+ no confiables, o que ejecuten un sandbox de backend de terminal esperando que contenga
116
+ rutas de código que no pasan por el shell, están operando fuera de la postura de
117
+ seguridad soportada.
118
+
119
+ ### 2.3 Alcance de Credenciales
120
+
121
+ Hermes Agent filtra el entorno que pasa a sus componentes en proceso de
122
+ menor confianza: subprocesos de shell, subprocesos MCP y el proceso hijo
123
+ de ejecución de código. Las credenciales como las claves API del proveedor y los
124
+ tokens del gateway se eliminan por defecto; las variables declaradas explícitamente
125
+ por el operador o por una habilidad cargada se pasan.
126
+
127
+ Esto reduce la exfiltración casual. No es contención. Cualquier
128
+ componente que se ejecute dentro del proceso del agente (habilidades, plugins, manejadores
129
+ de hooks) puede leer lo que el agente mismo puede leer, incluidas las
130
+ credenciales en memoria. La mitigación contra un componente en proceso comprometido
131
+ es la revisión del operador antes de instalar (§2.4, §2.5), no el
132
+ saneamiento del entorno.
133
+
134
+ ### 2.4 Heurísticas en Proceso
135
+
136
+ Los siguientes componentes filtran o advierten sobre el comportamiento del LLM. Son
137
+ útiles. No son límites.
138
+
139
+ - La **puerta de aprobación** detecta patrones de shell destructivos comunes
140
+ y le pide al operador confirmación antes de la ejecución. El shell es Turing-
141
+ completo; una lista de denegación sobre cadenas de shell es estructuralmente
142
+ incompleta. La puerta detecta errores en modo cooperativo, no salidas
143
+ adversariales.
144
+ - **La redacción de salida** elimina patrones similares a secretos de la visualización.
145
+ Un productor de salida motivado la evitará.
146
+ - **Skills Guard** escanea el contenido de habilidades instalables en busca de patrones
147
+ de inyección. Es una ayuda de revisión; el límite para habilidades de terceros
148
+ es la revisión del operador antes de instalar. Revisar una habilidad significa
149
+ leer su código Python y scripts, no solo su descripción SKILL.md —
150
+ las habilidades ejecutan Python arbitrario en el momento de importación.
151
+
152
+ ### 2.5 Modelo de Confianza de Plugins
153
+
154
+ Los plugins se cargan en el proceso del agente y se ejecutan con todos los privilegios
155
+ del agente: pueden leer las mismas credenciales, llamar a las mismas
156
+ herramientas, registrar los mismos hooks e importar los mismos módulos que
157
+ cualquier cosa incluida en el árbol. El límite para los plugins de terceros es
158
+ la revisión del operador antes de instalar — la misma regla que las habilidades (§2.4),
159
+ mencionado por separado porque los plugins son arquitectónicamente más pesados
160
+ y a menudo incluyen sus propios servicios en segundo plano, oyentes de red
161
+ y dependencias.
162
+
163
+ Un plugin malicioso o con errores no es una vulnerabilidad en Hermes Agent
164
+ en sí mismo. Los errores en la ruta de instalación o descubrimiento de plugins de Hermes Agent
165
+ que impidan al operador ver lo que está instalando están en alcance bajo el §3.1.
166
+
167
+ ### 2.6 Superficies Externas
168
+
169
+ Una **superficie externa** es cualquier canal fuera del proceso del agente local
170
+ a través del cual un llamador puede despachar trabajo del agente, resolver
171
+ aprobaciones o recibir salida del agente. Cada superficie tiene su propio
172
+ modelo de autorización, pero las reglas a continuación se aplican uniformemente.
173
+
174
+ **Superficies en Hermes Agent:**
175
+
176
+ - **Adaptadores de plataforma del gateway.** La mayoría de las integraciones
177
+ de mensajería se distribuyen como plugins empaquetados en
178
+ `plugins/platforms/<name>/` (Telegram, Discord, Slack, email, SMS, etc.).
179
+ Los tipos base compartidos y un conjunto menor de adaptadores
180
+ legacy/directos viven en `gateway/platforms/` (`base.py`, Signal, servidor
181
+ API, webhooks, …), con descubrimiento y carga diferida vía
182
+ `gateway/platform_registry.py`.
183
+ - **Superficies HTTP expuestas en red.** El adaptador del servidor API, el
184
+ plugin del dashboard, los endpoints HTTP del plugin kanban, y cualquier
185
+ otro plugin que vincule un socket de escucha.
186
+ - **Adaptadores de Editor / IDE.** El adaptador ACP (`acp_adapter/`) e
187
+ integraciones equivalentes que aceptan solicitudes de un proceso cliente local.
188
+ - **El gateway TUI (`tui_gateway/`).** Backend JSON-RPC para la
189
+ UI de terminal Ink, alcanzado a través de IPC local.
190
+
191
+ **Reglas uniformes:**
192
+
193
+ 1. **Se requiere autorización en cada superficie que cruce un límite de confianza.** Para
194
+ superficies de mensajería y HTTP en red, el límite es la red: la autorización
195
+ significa una lista de llamadores permitidos configurada por el operador. Para superficies
196
+ de editor e IPC local (ACP, gateway TUI), el límite es la cuenta de usuario del host:
197
+ la autorización significa depender del control de acceso a nivel de SO (permisos
198
+ de archivos, vinculaciones solo a loopback) y no exponer la superficie más allá
199
+ del usuario local sin una capa de autenticación de red explícita.
200
+ 2. **Se requiere una lista de permitidos para cada adaptador de red habilitado.**
201
+ Los adaptadores deben rechazar despachar trabajo del agente, resolver
202
+ aprobaciones o transmitir salida hasta que se establezca una lista de permitidos. Las rutas
203
+ de código que fallan de forma abierta cuando no hay lista de permitidos configurada son errores de código en
204
+ alcance bajo el §3.1.
205
+ 3. **Los identificadores de sesión son manejadores de enrutamiento, no límites de autorización.**
206
+ Conocer el ID de sesión de otro llamador no otorga acceso a sus aprobaciones o salida;
207
+ la autorización siempre se vuelve a verificar contra la lista de permitidos (o equivalente
208
+ a nivel de SO).
209
+ 4. **Dentro del conjunto autorizado, todos los llamadores tienen la misma confianza.**
210
+ Hermes Agent no modela capacidades por llamador dentro de un único adaptador.
211
+ Los operadores que necesiten separación de capacidades deben ejecutar instancias
212
+ de agente separadas con listas de permitidos separadas.
213
+ 5. **Vincular una superficie solo local a una interfaz no-loopback es una decisión de
214
+ operador de emergencia (§3.2).** El dashboard y otros servidores HTTP de plugins
215
+ son predeterminados a loopback; exponerlos a través de `--host 0.0.0.0` o equivalente
216
+ hace que el fortalecimiento de exposición pública (§4) sea responsabilidad del operador.
217
+
218
+ ---
219
+
220
+ ## 3. Alcance
221
+
222
+ ### 3.1 En Alcance
223
+
224
+ - Escape de una postura de aislamiento a nivel de SO declarada (§2.2): una
225
+ ruta de código controlada por el atacante alcanzando estado que la postura
226
+ afirmó confinar.
227
+ - Acceso no autorizado a superficie externa: un llamador fuera del conjunto de
228
+ autorización configurado (lista de permitidos, o equivalente a nivel de SO
229
+ para superficies de IPC local) despachando trabajo, recibiendo salida o
230
+ resolviendo aprobaciones (§2.6).
231
+ - Exfiltración de credenciales: filtración de credenciales del operador o
232
+ material de autorización de sesión a un destino fuera del envolvente de
233
+ confianza, a través de un mecanismo que debería haberlo prevenido
234
+ (error de saneamiento de entorno, registro del adaptador, error de transporte
235
+ que vacía credenciales a un upstream, etc.).
236
+ - Violaciones de la documentación del modelo de confianza: código que se comporta
237
+ contrariamente a lo que esta política, la propia documentación de Hermes Agent o
238
+ las expectativas razonables del operador predecirían — incluyendo casos donde
239
+ Hermes Agent ha documentado una postura sobre cómo su salida debe ser
240
+ renderizada por una capa consumidora (dashboard, adaptador de gateway,
241
+ escritor de archivos, shell) y una ruta de código rompe esa postura.
242
+
243
+ ### 3.2 Fuera de Alcance
244
+
245
+ "Fuera de alcance" aquí significa "no es una vulnerabilidad de seguridad bajo esta
246
+ política." No significa "no vale la pena reportarlo." Las mejoras a las
247
+ heurísticas en proceso, ideas de fortalecimiento y correcciones de UX son bienvenidas como
248
+ issues o pull requests regulares — la puerta de aprobación siempre puede detectar
249
+ más patrones, la redacción puede volverse más inteligente, el comportamiento del adaptador
250
+ puede apretarse siempre. Estos elementos simplemente no van a través del canal de
251
+ divulgación privada y no reciben avisos.
252
+
253
+ - **Bypasses de heurísticas en proceso (§2.4)** — bypasses de regex de la puerta de aprobación,
254
+ bypasses de redacción, bypasses de patrones de Skills Guard, e informes
255
+ análogos contra heurísticas futuras. Estos componentes no son límites;
256
+ vencerlos no es una vulnerabilidad bajo esta política.
257
+ - **Inyección de prompts per se.** Hacer que el LLM emita salida inusual
258
+ — a través de contenido inyectado, alucinación, artefactos de entrenamiento,
259
+ o cualquier otra causa — no es en sí mismo una vulnerabilidad. "Logré
260
+ inyección de prompts" sin un resultado encadenado del §3.1 no es un informe
261
+ procesable bajo esta política.
262
+ - **Consecuencias de una postura de aislamiento elegida.** Los informes de que
263
+ una ruta de código que opera dentro del alcance de su postura puede hacer lo que esa
264
+ postura permite no son vulnerabilidades. Ejemplos: herramientas de shell o archivos
265
+ que alcanzan estado del host bajo el backend local; subprocesos de ejecución de código
266
+ o MCP que alcanzan estado del host bajo aislamiento de backend de terminal que solo
267
+ sandboxea el shell; informes cuyas precondiciones requieren acceso de escritura preexistente
268
+ a archivos de configuración o credenciales propiedad del operador (esos ya están dentro
269
+ del envolvente de confianza).
270
+ - **Configuraciones documentadas de emergencia.** Compensaciones seleccionadas por el operador
271
+ que deshabilitan explícitamente protecciones: `--insecure` y flags equivalentes
272
+ en el dashboard u otros componentes, aprobaciones deshabilitadas,
273
+ backend local en producción, perfiles de desarrollo que evitan
274
+ la seguridad de hermes-home, y similares. Los informes contra esas
275
+ configuraciones no son vulnerabilidades — eso es el trabajo del flag.
276
+ - **Habilidades y plugins contribuidos por la comunidad.** Las habilidades de terceros
277
+ (incluyendo el repositorio de habilidades de la comunidad) y los plugins de terceros
278
+ están en la superficie de revisión del operador, no en la superficie de confianza de Hermes Agent
279
+ (§2.4, §2.5). Una habilidad o plugin que haga algo
280
+ malicioso es el modo de falla esperado de uno que no fue
281
+ revisado, no una vulnerabilidad en Hermes Agent. Los errores en la ruta de
282
+ instalación de habilidades o plugins de Hermes Agent que impidan al
283
+ operador ver lo que está instalando están en alcance bajo el §3.1.
284
+ - **Exposición pública sin controles externos.** Exponer el
285
+ gateway o la API a la internet pública sin autenticación,
286
+ VPN o firewall.
287
+ - **Restricciones de lectura/escritura a nivel de herramienta en una postura donde el shell está
288
+ permitido.** Si una ruta es alcanzable a través de la herramienta terminal, los informes
289
+ de que otras herramientas de archivos pueden alcanzarla no añaden nada.
290
+
291
+ ---
292
+
293
+ ## 4. Fortalecimiento del Despliegue
294
+
295
+ La decisión de fortalecimiento más importante es hacer coincidir el aislamiento
296
+ (§2.2) con la confianza del contenido que el agente ingerirá. Más allá de eso:
297
+
298
+ - Ejecuta el agente como usuario no-root. La imagen de contenedor proporcionada
299
+ hace esto por defecto.
300
+ - Mantén las credenciales en el archivo de credenciales del operador con permisos
301
+ estrictos, nunca en la configuración principal, nunca en control de versiones.
302
+ Bajo OpenShell, usa el almacén de Proveedores en lugar de un archivo de
303
+ credenciales en disco.
304
+ - No expongas el gateway o la API a la internet pública sin
305
+ VPN, Tailscale o protección de firewall. Bajo OpenShell, usa la
306
+ capa de política de red para restringir el egreso.
307
+ - Configura una lista de llamadores permitidos para cada adaptador de red expuesto
308
+ que habilites (§2.6).
309
+ - Revisa las habilidades y plugins de terceros antes de instalar (§2.4,
310
+ §2.5). Para las habilidades, esto significa leer el Python y los scripts,
311
+ no solo SKILL.md. Los informes de Skills Guard y el registro de auditoría
312
+ de instalación son la superficie de revisión.
313
+ - Hermes Agent incluye guardias de cadena de suministro para lanzamientos de servidores
314
+ MCP y para cambios de dependencias / paquetes incluidos en CI; consulta
315
+ `CONTRIBUTING.es.md` para más detalles.
316
+
317
+ ---
318
+
319
+ ## 5. Divulgación
320
+
321
+ - **Ventana de divulgación coordinada:** 90 días desde el informe, o hasta que se
322
+ publique una corrección, lo que ocurra primero.
323
+ - **Canal:** el hilo GHSA o correspondencia por email con
324
+ security@nousresearch.com.
325
+ - **Crédito:** los reportadores reciben crédito en las notas de versión a menos que
326
+ se solicite anonimato.
SECURITY.md ADDED
@@ -0,0 +1,335 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Hermes Agent Security Policy
2
+
3
+ This document describes Hermes Agent's trust model, names the one
4
+ security boundary the project treats as load-bearing, and defines the
5
+ scope for vulnerability reports.
6
+
7
+ ## 1. Reporting a Vulnerability
8
+
9
+ Report privately via [GitHub Security Advisories](https://github.com/NousResearch/hermes-agent/security/advisories/new)
10
+ or **security@nousresearch.com**. Do not open public issues for
11
+ security vulnerabilities. **Hermes Agent does not operate a bug
12
+ bounty program.**
13
+
14
+ A useful report includes:
15
+
16
+ - A concise description and severity assessment.
17
+ - The affected component, identified by file path and line range
18
+ (e.g. `path/to/file.py:120-145`).
19
+ - Environment details (`hermes --version`, commit SHA, OS, Python
20
+ version).
21
+ - A reproduction against `main` or the latest release.
22
+ - A statement of which trust boundary in §2 is crossed.
23
+
24
+ Please read §2 and §3 before submitting. Reports that demonstrate
25
+ limits of an in-process heuristic this policy does not treat as a
26
+ boundary will be closed as out-of-scope under §3 — but see §3.2:
27
+ they are still welcome as regular issues or pull requests, just not
28
+ through the private security channel.
29
+
30
+ ---
31
+
32
+ ## 2. Trust Model
33
+
34
+ Hermes Agent is a single-tenant personal agent. Its posture is
35
+ layered, and the layers are not equally load-bearing. Reporters and
36
+ operators should reason about them in the same terms.
37
+
38
+ ### 2.1 Definitions
39
+
40
+ - **Agent process.** The Python interpreter running Hermes Agent,
41
+ including any Python modules it has loaded (skills, plugins,
42
+ hook handlers).
43
+ - **Terminal backend.** A pluggable execution target for the
44
+ `terminal()` tool. The default runs commands directly on the host.
45
+ Other backends run commands inside a container, cloud sandbox, or
46
+ remote host.
47
+ - **Input surface.** Any channel through which content enters the
48
+ agent's context: operator input, web fetches, email, gateway
49
+ messages, file reads, MCP server responses, tool results.
50
+ - **Trust envelope.** The set of resources an operator has implicitly
51
+ granted Hermes Agent access to by running it — typically, whatever
52
+ the operator's own user account can reach on the host.
53
+ - **Stance.** An explicit statement in Hermes Agent's documentation
54
+ or code about how a consuming layer (adapter, UI, file writer,
55
+ shell) should treat agent output — e.g. "the dashboard renders
56
+ agent output as inert HTML."
57
+
58
+ ### 2.2 The Boundary: OS-Level Isolation
59
+
60
+ **The only security boundary against an adversarial LLM is the
61
+ operating system.** Nothing inside the agent process constitutes
62
+ containment — not the approval gate, not output redaction, not any
63
+ pattern scanner, not any tool allowlist. Any in-process component
64
+ that screens LLM output is a heuristic operating on an
65
+ attacker-influenced string, and this policy treats it as such.
66
+
67
+ Hermes Agent supports two OS-level isolation postures. They address
68
+ different threats and an operator should choose deliberately.
69
+
70
+ #### Terminal-backend isolation
71
+
72
+ A non-default terminal backend runs LLM-emitted shell commands
73
+ inside a container, remote host, or cloud sandbox. The file tools
74
+ (`read_file`, `write_file`, `patch`) also run through this backend,
75
+ since they are implemented on top of the shell contract — they
76
+ cannot reach paths the backend doesn't expose.
77
+
78
+ What this confines: anything the agent does by issuing shell or
79
+ file operations. What this does **not** confine: everything the
80
+ agent does in its own Python process. That includes the
81
+ code-execution tool (spawned as a host subprocess), MCP subprocesses
82
+ (spawned from the agent's environment), plugin loading, hook
83
+ dispatch, and skill loading (all imported into the agent
84
+ interpreter).
85
+
86
+ Terminal-backend isolation is the right posture when the concern is
87
+ LLM-emitted destructive shell or unwanted file-tool writes, and the
88
+ operator is otherwise trusted.
89
+
90
+ #### Whole-process wrapping
91
+
92
+ Whole-process wrapping runs the entire agent process tree inside a
93
+ sandbox. Every code path — shell, code-execution, MCP, file tools,
94
+ plugins, hooks, skill loading — is subject to the same filesystem,
95
+ network, process, and (where applicable) inference policy.
96
+
97
+ Hermes Agent supports this in two ways:
98
+
99
+ - **Hermes Agent's own Docker image and Compose setup.** Lighter-
100
+ weight; the agent runs in a standard container with operator-
101
+ configured mounts and network policy.
102
+ - **[NVIDIA OpenShell](https://github.com/NVIDIA/OpenShell)**.
103
+ OpenShell provides per-session sandboxes with declarative policy
104
+ across filesystem, network (L7 egress), process/syscall, and
105
+ inference-routing layers. Network and inference policies are
106
+ hot-reloadable. Credentials are injected from a Provider store
107
+ and never touch the sandbox filesystem.
108
+
109
+ Under a whole-process wrapper, Hermes Agent's in-process heuristics
110
+ (§2.4) function as accident-prevention layered on top of a real
111
+ boundary. This is the supported posture when the agent ingests
112
+ content from surfaces the operator does not control — the open web,
113
+ inbound email, multi-user channels, untrusted MCP servers — and for
114
+ production or shared deployments.
115
+
116
+ Operators running the default local backend with untrusted input
117
+ surfaces, or running a terminal-backend sandbox and expecting it to
118
+ contain code paths that don't go through the shell, are operating
119
+ outside the supported security posture.
120
+
121
+ ### 2.3 Credential Scoping
122
+
123
+ Hermes Agent filters the environment it passes to its lower-trust
124
+ in-process components: shell subprocesses, MCP subprocesses,
125
+ cron job scripts, and the code-execution child. Credentials like
126
+ provider API keys and gateway tokens are stripped by default;
127
+ variables explicitly declared by the operator or by a loaded
128
+ skill are passed through.
129
+
130
+ This reduces casual exfiltration. It is not containment. Any
131
+ component running inside the agent process (skills, plugins, hook
132
+ handlers) can read whatever the agent itself can read, including
133
+ in-memory credentials. The mitigation against a compromised
134
+ in-process component is operator review before install (§2.4,
135
+ §2.5), not environment scrubbing.
136
+
137
+ ### 2.4 In-Process Heuristics
138
+
139
+ The following components screen or warn about LLM behavior. They
140
+ are useful. They are not boundaries.
141
+
142
+ - The **approval gate** detects common destructive shell patterns
143
+ and prompts the operator before execution. Shell is Turing-
144
+ complete; a denylist over shell strings is structurally
145
+ incomplete. The gate catches cooperative-mode mistakes, not
146
+ adversarial output.
147
+ - **Output redaction** strips secret-like patterns from display.
148
+ A motivated output producer will defeat it.
149
+ - **Skills Guard** scans installable skill content for injection
150
+ patterns. It is a review aid; the boundary for third-party skills
151
+ is operator review before install. Reviewing a skill means
152
+ reading its Python code and scripts, not just its SKILL.md
153
+ description — skills execute arbitrary Python at import time.
154
+
155
+ ### 2.5 Plugin Trust Model
156
+
157
+ Plugins load into the agent process and run with full agent
158
+ privileges: they can read the same credentials, call the same
159
+ tools, register the same hooks, and import the same modules as
160
+ anything shipped in-tree. The boundary for third-party plugins is
161
+ operator review before install — the same rule as skills (§2.4),
162
+ called out separately because plugins are architecturally heavier
163
+ and often ship their own background services, network listeners,
164
+ and dependencies.
165
+
166
+ A malicious or buggy plugin is not a vulnerability in Hermes Agent
167
+ itself. Bugs in Hermes Agent's plugin-install or plugin-discovery
168
+ path that prevent the operator from seeing what they're installing
169
+ are in scope under §3.1.
170
+
171
+ ### 2.6 External Surfaces
172
+
173
+ An **external surface** is any channel outside the local agent
174
+ process through which a caller can dispatch agent work, resolve
175
+ approvals, or receive agent output. Each surface has its own
176
+ authorization model, but the rules below apply uniformly.
177
+
178
+ **Surfaces in Hermes Agent:**
179
+
180
+ - **Gateway platform adapters.** Most messaging integrations ship as
181
+ bundled plugins under `plugins/platforms/<name>/` (Telegram, Discord,
182
+ Slack, email, SMS, etc.). Shared base types and a smaller set of
183
+ legacy/direct adapters live under `gateway/platforms/`
184
+ (`base.py`, Signal, API server, webhooks, …), with discovery and
185
+ deferred loading via `gateway/platform_registry.py`.
186
+ - **Network-exposed HTTP surfaces.** The API server adapter, the
187
+ dashboard plugin, the kanban plugin's HTTP endpoints, and any
188
+ other plugin that binds a listening socket.
189
+ - **Editor / IDE adapters.** The ACP adapter (`acp_adapter/`) and
190
+ equivalent integrations that accept requests from a local client
191
+ process.
192
+ - **The TUI gateway (`tui_gateway/`).** JSON-RPC backend for the
193
+ Ink terminal UI, reached over local IPC.
194
+
195
+ **Uniform rules:**
196
+
197
+ 1. **Authorization is required at every surface that crosses a
198
+ trust boundary.** For messaging and network HTTP surfaces, the
199
+ boundary is the network: authorization means an operator-
200
+ configured caller allowlist. For editor and local-IPC surfaces
201
+ (ACP, TUI gateway), the boundary is the host's user account:
202
+ authorization means relying on OS-level access control (file
203
+ permissions, loopback-only binds) and not exposing the surface
204
+ beyond the local user without an explicit network auth layer.
205
+ 2. **An allowlist is required for every enabled network-exposed
206
+ adapter.** Adapters must refuse to dispatch agent work, resolve
207
+ approvals, or relay output until an allowlist is set. Code paths
208
+ that fail open when no allowlist is configured are code bugs in
209
+ scope under §3.1.
210
+ 3. **Session identifiers are routing handles, not authorization
211
+ boundaries.** Knowing another caller's session ID does not grant
212
+ access to their approvals or output; authorization is always
213
+ re-checked against the allowlist (or OS-level equivalent).
214
+ 4. **Within the authorized set, all callers are equally trusted.**
215
+ Hermes Agent does not model per-caller capabilities inside a
216
+ single adapter. Operators who need capability separation should
217
+ run separate agent instances with separate allowlists.
218
+ 5. **Binding a local-only surface to a non-loopback interface is a
219
+ break-glass operator decision (§3.2).** The dashboard and other
220
+ plugin HTTP servers default to loopback; exposing them via
221
+ `--host 0.0.0.0` or equivalent makes public-exposure hardening
222
+ (§4) the operator's responsibility.
223
+
224
+ ---
225
+
226
+ ## 3. Scope
227
+
228
+ ### 3.1 In Scope
229
+
230
+ - Escape from a declared OS-level isolation posture (§2.2): an
231
+ attacker-controlled code path reaching state that the posture
232
+ claimed to confine.
233
+ - Unauthorized external-surface access: a caller outside the
234
+ configured authorization set (allowlist, or OS-level equivalent
235
+ for local-IPC surfaces) dispatching work, receiving output, or
236
+ resolving approvals (§2.6).
237
+ - Credential exfiltration: leakage of operator credentials or
238
+ session authorization material to a destination outside the
239
+ trust envelope, via a mechanism that should have prevented it
240
+ (environment scrubbing bug, adapter logging, transport error
241
+ that flushes credentials to an upstream, etc.).
242
+ - Trust-model documentation violations: code behaving contrary to
243
+ what this policy, Hermes Agent's own documentation, or reasonable
244
+ operator expectations would predict — including cases where
245
+ Hermes Agent has documented a stance about how its output should
246
+ be rendered by a consuming layer (dashboard, gateway adapter,
247
+ file writer, shell) and a code path breaks that stance.
248
+
249
+ ### 3.2 Out of Scope
250
+
251
+ "Out of scope" here means "not a security vulnerability under this
252
+ policy." It does not mean "not worth reporting." Improvements to the
253
+ in-process heuristics, hardening ideas, and UX fixes are welcome as
254
+ regular issues or pull requests — the approval gate can always catch
255
+ more patterns, redaction can always get smarter, adapter behavior
256
+ can always be tightened. These items just don't go through the
257
+ private-disclosure channel and don't receive advisories.
258
+
259
+ - **Bypasses of in-process heuristics (§2.4)** — approval-gate regex
260
+ bypasses, redaction bypasses, Skills Guard pattern bypasses, and
261
+ analogous reports against future heuristics. These components are
262
+ not boundaries; defeating them is not a vulnerability under this
263
+ policy.
264
+ - **Prompt injection per se.** Getting the LLM to emit unusual
265
+ output — via injected content, hallucination, training artifacts,
266
+ or any other cause — is not itself a vulnerability. "I achieved
267
+ prompt injection" without a chained §3.1 outcome is not an
268
+ actionable report under this policy.
269
+ - **Consequences of a chosen isolation posture.** Reports that a
270
+ code path operating within its posture's scope can do what that
271
+ posture permits are not vulnerabilities. Examples: shell or file
272
+ tools reaching host state under the local backend; code-execution
273
+ or MCP subprocesses reaching host state under terminal-backend
274
+ isolation that only sandboxes shell; reports whose preconditions
275
+ require pre-existing write access to operator-owned configuration
276
+ or credential files (those are already inside the trust envelope).
277
+ - **Documented break-glass settings.** Operator-selected trade-offs
278
+ that explicitly disable protections: `--insecure` and equivalent
279
+ flags on the dashboard or other components, disabled approvals,
280
+ local backend in production, development profiles that bypass
281
+ hermes-home security, and similar. Reports against those
282
+ configurations are not vulnerabilities — that's the flag's job.
283
+ - **Community-contributed skills and plugins.** Third-party skills
284
+ (including the community skills repository) and third-party
285
+ plugins are in the operator's review surface, not Hermes Agent's
286
+ trust surface (§2.4, §2.5). A skill or plugin doing something
287
+ malicious is the expected failure mode of one that wasn't
288
+ reviewed, not a vulnerability in Hermes Agent. Bugs in Hermes
289
+ Agent's skill-install or plugin-install path that prevent the
290
+ operator from seeing what they're installing are in scope under
291
+ §3.1.
292
+ - **Public exposure without external controls.** Exposing the
293
+ gateway or API to the public internet without authentication,
294
+ VPN, or firewall.
295
+ - **Tool-level read/write restrictions on a posture where shell is
296
+ permitted.** If a path is reachable via the terminal tool, reports
297
+ that other file tools can reach it add nothing.
298
+
299
+ ---
300
+
301
+ ## 4. Deployment Hardening
302
+
303
+ The single most important hardening decision is matching isolation
304
+ (§2.2) to the trust of the content the agent will ingest. Beyond
305
+ that:
306
+
307
+ - Run the agent as a non-root user. The supplied container image
308
+ does this by default.
309
+ - Keep credentials in the operator credential file with tight
310
+ permissions, never in the main config, never in version control.
311
+ Under OpenShell, use the Provider store rather than an on-disk
312
+ credential file.
313
+ - Do not expose the gateway or API to the public internet without
314
+ VPN, Tailscale, or firewall protection. Under OpenShell, use the
315
+ network policy layer to restrict egress.
316
+ - Configure a caller allowlist for every network-exposed adapter
317
+ you enable (§2.6).
318
+ - Review third-party skills and plugins before install (§2.4,
319
+ §2.5). For skills, this means reading the Python and scripts,
320
+ not just SKILL.md. Skills Guard reports and the install audit
321
+ log are the review surface.
322
+ - Hermes Agent includes supply-chain guards for MCP server
323
+ launches and for dependency / bundled-package changes in CI; see
324
+ `CONTRIBUTING.md` for specifics.
325
+
326
+ ---
327
+
328
+ ## 5. Disclosure
329
+
330
+ - **Coordinated disclosure window:** 90 days from report, or until a
331
+ fix is released, whichever comes first.
332
+ - **Channel:** the GHSA thread or email correspondence with
333
+ security@nousresearch.com.
334
+ - **Credit:** reporters are credited in release notes unless
335
+ anonymity is requested.
SOUL.md ADDED
@@ -0,0 +1 @@
 
 
1
+ You are Hermes Agent, built by Nous Research. Be direct: match the length of your reply to the weight of the ask — a one-line question gets a one-line answer, and finished work gets a short report of what changed, what's verified, and what's left, never a replay of the process. No filler ("Great question," "I'd be happy to"), no restating the request back, no re-summarizing what you already said, no narrating tool calls the user can see. Plain claims over adjectives; when unsure, say so plainly. Agree because it's right, not because the user said it. Depth is earned — give it when the user asks for detail, teaches, or the stakes demand it, not by default.
cli.py ADDED
The diff for this file is too large to render. See raw diff
 
compat_manifest.json ADDED
The diff for this file is too large to render. See raw diff
 
docker-compose.yml ADDED
@@ -0,0 +1,76 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #
2
+ # docker-compose.yml for Hermes Agent
3
+ #
4
+ # Usage:
5
+ # HERMES_UID=$(id -u) HERMES_GID=$(id -g) docker compose up -d
6
+ #
7
+ # Set HERMES_UID / HERMES_GID to the host user that owns ~/.hermes so
8
+ # files created inside the container stay readable/writable on the host.
9
+ # The s6-overlay stage2 hook remaps the internal `hermes` user to these
10
+ # values via usermod/groupmod; each supervised service then drops to that
11
+ # user via `s6-setuidgid`.
12
+ #
13
+ # Security notes:
14
+ # - The dashboard service binds to 127.0.0.1 by default. It stores API
15
+ # keys; exposing it on LAN without auth is unsafe. If you want remote
16
+ # access, use an SSH tunnel or put it behind a reverse proxy that
17
+ # adds authentication — do NOT pass --insecure --host 0.0.0.0.
18
+ # - If you override entrypoint, keep `/init` as the first command in
19
+ # the chain (or let docker use the image's default ENTRYPOINT,
20
+ # which is `["/init", "/opt/hermes/docker/main-wrapper.sh"]`).
21
+ # `/init` is s6-overlay's PID 1 — it runs the cont-init.d scripts
22
+ # (chown, profile reconcile, dashboard toggle) and sets up the
23
+ # supervision tree before any service starts. Bypassing it skips
24
+ # all of that setup and the gateway will not work correctly.
25
+ # - The gateway's API server is off unless you uncomment API_SERVER_KEY
26
+ # and API_SERVER_HOST. See docs/user-guide/api-server.md before doing
27
+ # this on an internet-facing host.
28
+ #
29
+ services:
30
+ gateway:
31
+ build: .
32
+ image: hermes-agent
33
+ container_name: hermes
34
+ restart: unless-stopped
35
+ network_mode: host
36
+ volumes:
37
+ - ~/.hermes:/opt/data
38
+ environment:
39
+ - HERMES_UID=${HERMES_UID:-10000}
40
+ - HERMES_GID=${HERMES_GID:-10000}
41
+ # To expose the OpenAI-compatible API server beyond localhost,
42
+ # uncomment BOTH lines (API_SERVER_KEY is mandatory for auth):
43
+ # - API_SERVER_HOST=0.0.0.0
44
+ # - API_SERVER_KEY=${API_SERVER_KEY}
45
+ # Microsoft Teams — uncomment and fill in to enable Teams gateway.
46
+ # Register your bot at https://dev.botframework.com/ to get these values.
47
+ # - TEAMS_CLIENT_ID=${TEAMS_CLIENT_ID}
48
+ # - TEAMS_CLIENT_SECRET=${TEAMS_CLIENT_SECRET}
49
+ # - TEAMS_TENANT_ID=${TEAMS_TENANT_ID}
50
+ # - TEAMS_ALLOWED_USERS=${TEAMS_ALLOWED_USERS}
51
+ # - TEAMS_PORT=${TEAMS_PORT:-3978}
52
+ # Google Chat — uncomment and fill in to enable the Google Chat gateway.
53
+ # See website/docs/user-guide/messaging/google_chat.md for the full setup.
54
+ # The SA JSON path must point to a file mounted into the container —
55
+ # add a volume entry above (e.g. ``- ~/.hermes/google-chat-sa.json:/secrets/google-chat-sa.json:ro``)
56
+ # then set GOOGLE_CHAT_SERVICE_ACCOUNT_JSON to that mount path.
57
+ # - GOOGLE_CHAT_PROJECT_ID=${GOOGLE_CHAT_PROJECT_ID}
58
+ # - GOOGLE_CHAT_SUBSCRIPTION_NAME=${GOOGLE_CHAT_SUBSCRIPTION_NAME}
59
+ # - GOOGLE_CHAT_SERVICE_ACCOUNT_JSON=${GOOGLE_CHAT_SERVICE_ACCOUNT_JSON}
60
+ # - GOOGLE_CHAT_ALLOWED_USERS=${GOOGLE_CHAT_ALLOWED_USERS}
61
+ command: ["gateway", "run"]
62
+
63
+ dashboard:
64
+ image: hermes-agent
65
+ container_name: hermes-dashboard
66
+ restart: unless-stopped
67
+ network_mode: host
68
+ depends_on:
69
+ - gateway
70
+ volumes:
71
+ - ~/.hermes:/opt/data
72
+ environment:
73
+ - HERMES_UID=${HERMES_UID:-10000}
74
+ - HERMES_GID=${HERMES_GID:-10000}
75
+ # Localhost-only. For remote access, tunnel via `ssh -L 9119:localhost:9119`.
76
+ command: ["dashboard", "--host", "127.0.0.1", "--no-open"]
eslint.config.shared.mjs ADDED
@@ -0,0 +1,106 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ /**
2
+ * Shared ESLint flat config for all Hermes TS workspaces.
3
+ *
4
+ * Usage in a workspace's eslint.config.mjs:
5
+ *
6
+ * import config from '../../eslint.config.shared.mjs'
7
+ *
8
+ * export default [
9
+ * ...config,
10
+ * // workspace-specific overrides here
11
+ * ]
12
+ */
13
+
14
+ import js from '@eslint/js'
15
+ import tseslint from 'typescript-eslint';
16
+ import perfectionist from 'eslint-plugin-perfectionist'
17
+ import hooksPlugin from 'eslint-plugin-react-hooks'
18
+ import unusedImports from 'eslint-plugin-unused-imports'
19
+ import globals from 'globals'
20
+
21
+ export default [
22
+ {
23
+ ignores: ['**/node_modules/**', '**/dist/**', 'src/**/*.js', '**/package-lock.json']
24
+ },
25
+ js.configs.recommended,
26
+ {
27
+ files: ['**/*.{ts,tsx}'],
28
+ languageOptions: {
29
+ globals: {
30
+ ...globals.node
31
+ },
32
+ parser: tseslint.parser,
33
+ parserOptions: {
34
+ ecmaFeatures: { jsx: true },
35
+ ecmaVersion: 'latest',
36
+ sourceType: 'module'
37
+ }
38
+ },
39
+ plugins: {
40
+ '@typescript-eslint': tseslint.plugin,
41
+ perfectionist,
42
+ 'react-hooks': hooksPlugin,
43
+ 'unused-imports': unusedImports
44
+ },
45
+ rules: {
46
+ '@typescript-eslint/consistent-type-imports': ['error', { prefer: 'type-imports' }],
47
+ '@typescript-eslint/no-unused-vars': 'off',
48
+ curly: ['error', 'all'],
49
+ 'no-fallthrough': ['error', { allowEmptyCase: true }],
50
+ 'no-undef': 'off',
51
+ 'no-unused-vars': 'off',
52
+ 'padding-line-between-statements': [
53
+ 1,
54
+ {
55
+ blankLine: 'always',
56
+ next: [
57
+ 'block-like',
58
+ 'block',
59
+ 'return',
60
+ 'if',
61
+ 'class',
62
+ 'continue',
63
+ 'debugger',
64
+ 'break',
65
+ 'multiline-const',
66
+ 'multiline-let'
67
+ ],
68
+ prev: '*'
69
+ },
70
+ {
71
+ blankLine: 'always',
72
+ next: '*',
73
+ prev: ['case', 'default', 'multiline-const', 'multiline-let', 'multiline-block-like']
74
+ },
75
+ { blankLine: 'never', next: ['block', 'block-like'], prev: ['case', 'default'] },
76
+ { blankLine: 'always', next: ['block', 'block-like'], prev: ['block', 'block-like'] },
77
+ { blankLine: 'always', next: ['empty'], prev: 'export' },
78
+ { blankLine: 'never', next: 'iife', prev: ['block', 'block-like', 'empty'] }
79
+ ],
80
+ 'perfectionist/sort-exports': ['error', { order: 'asc', type: 'natural' }],
81
+ 'perfectionist/sort-imports': [
82
+ 'error',
83
+ {
84
+ groups: ['side-effect', 'builtin', 'external', 'internal', 'parent', 'sibling', 'index'],
85
+ order: 'asc',
86
+ type: 'natural'
87
+ }
88
+ ],
89
+ 'perfectionist/sort-jsx-props': ['error', { order: 'asc', type: 'natural' }],
90
+ 'perfectionist/sort-named-exports': ['error', { order: 'asc', type: 'natural' }],
91
+ 'perfectionist/sort-named-imports': ['error', { order: 'asc', type: 'natural' }],
92
+ 'react-hooks/exhaustive-deps': 'warn',
93
+ 'react-hooks/rules-of-hooks': 'error',
94
+ 'unused-imports/no-unused-imports': 'error'
95
+ }
96
+ },
97
+ {
98
+ files: ['**/*.js', '**/*.cjs', '**/*.mjs'],
99
+ ignores: ['**/node_modules/**', '**/dist/**'],
100
+ languageOptions: {
101
+ ecmaVersion: 'latest',
102
+ globals: { ...globals.node },
103
+ sourceType: 'module'
104
+ }
105
+ }
106
+ ]
evals/__init__.py ADDED
File without changes
evals/acp_empty_session_wire.py ADDED
@@ -0,0 +1,153 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Native ACP stdio + SQLite probe; local HTTP model fixture, never paid inference.
2
+
3
+ Run with the project Python from the checkout being measured. --output saves the
4
+ wire transcript and database measurements. No production predicates are patched.
5
+ """
6
+ import argparse
7
+ import json
8
+ import os
9
+ from pathlib import Path
10
+ import queue
11
+ import sqlite3
12
+ import subprocess
13
+ import sys
14
+ import tempfile
15
+ import threading
16
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
17
+
18
+
19
+ def main():
20
+ parser = argparse.ArgumentParser()
21
+ parser.add_argument('--output', required=True)
22
+ args = parser.parse_args()
23
+ repo = Path(__file__).resolve().parents[1]
24
+ requests = []
25
+
26
+ class Model(BaseHTTPRequestHandler):
27
+ def log_message(self, *args):
28
+ pass
29
+
30
+ def do_GET(self):
31
+ self.reply({'object': 'list', 'data': [{'id': 'fixture-model', 'object': 'model'}]})
32
+
33
+ def do_POST(self):
34
+ body = json.loads(self.rfile.read(int(self.headers['Content-Length'])))
35
+ requests.append({'path': self.path, 'body': body})
36
+ if body.get('stream'):
37
+ chunk = {'id': 'fixture-stream', 'object': 'chat.completion.chunk',
38
+ 'created': 1, 'model': 'fixture-model',
39
+ 'choices': [{'index': 0, 'delta': {'role': 'assistant',
40
+ 'content': 'Local fixture reply.'}, 'finish_reason': 'stop'}]}
41
+ data = ('data: ' + json.dumps(chunk) + '\n\ndata: [DONE]\n\n').encode()
42
+ self.send_response(200)
43
+ self.send_header('Content-Type', 'text/event-stream')
44
+ self.send_header('Content-Length', str(len(data)))
45
+ self.end_headers()
46
+ self.wfile.write(data)
47
+ return
48
+ self.reply({'id': 'fixture-completion', 'object': 'chat.completion',
49
+ 'created': 1, 'model': 'fixture-model',
50
+ 'choices': [{'index': 0, 'message': {'role': 'assistant',
51
+ 'content': 'Local fixture reply.'}, 'finish_reason': 'stop'}],
52
+ 'usage': {'prompt_tokens': 10, 'completion_tokens': 5, 'total_tokens': 15}})
53
+
54
+ def reply(self, body):
55
+ data = json.dumps(body).encode()
56
+ self.send_response(200)
57
+ self.send_header('Content-Type', 'application/json')
58
+ self.send_header('Content-Length', str(len(data)))
59
+ self.end_headers()
60
+ self.wfile.write(data)
61
+
62
+ server = ThreadingHTTPServer(('127.0.0.1', 0), Model)
63
+ threading.Thread(target=server.serve_forever, daemon=True).start()
64
+ home = Path(tempfile.mkdtemp(prefix='hermes-acp-empty-'))
65
+ hermes = home / '.hermes'
66
+ hermes.mkdir()
67
+ (hermes / 'config.yaml').write_text(
68
+ 'model:\n provider: custom\n default: fixture-model\n'
69
+ f' base_url: http://127.0.0.1:{server.server_port}/v1\n'
70
+ ' api_key: local-fixture-key\n api_mode: chat_completions\n'
71
+ 'mcp_servers: {}\nmemory:\n memory_enabled: false\n user_profile_enabled: false\n'
72
+ 'agent:\n max_iterations: 1\n disabled_toolsets: [all]\n'
73
+ )
74
+ env = {k: os.environ[k] for k in ('PATH', 'LANG', 'TZ') if k in os.environ}
75
+ env.update(HOME=str(home), HERMES_HOME=str(hermes), PYTHONPATH=os.pathsep.join([str(repo), os.environ.get('PYTHONPATH', '')]),
76
+ HERMES_ACP_SKIP_CONFIGURED_MCP='1', OPENAI_API_KEY='local-fixture-key',
77
+ OPENAI_BASE_URL=f'http://127.0.0.1:{server.server_port}/v1')
78
+ stderr = open(str(args.output) + '.stderr', 'w', encoding='utf-8')
79
+ proc = subprocess.Popen([sys.executable, '-m', 'acp_adapter'], cwd=repo, env=env,
80
+ stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=stderr, text=True)
81
+ received = queue.Queue()
82
+ wire = []
83
+
84
+ def reader():
85
+ for line in proc.stdout:
86
+ received.put(line)
87
+ threading.Thread(target=reader, daemon=True).start()
88
+
89
+ def rpc(method, params):
90
+ request_id = len(wire) + 1
91
+ request = {'jsonrpc': '2.0', 'id': request_id, 'method': method, 'params': params}
92
+ wire.append({'sent': request})
93
+ proc.stdin.write(json.dumps(request) + '\n')
94
+ proc.stdin.flush()
95
+ while True:
96
+ response = json.loads(received.get(timeout=120))
97
+ wire.append({'received': response})
98
+ if response.get('id') == request_id:
99
+ if 'error' in response:
100
+ raise RuntimeError(response)
101
+ return response['result']
102
+
103
+ def rows():
104
+ with sqlite3.connect(hermes / 'state.db') as db:
105
+ return db.execute('SELECT id, source, message_count FROM sessions ORDER BY id').fetchall()
106
+
107
+ result = {'repo': str(repo), 'home': str(home)}
108
+ try:
109
+ rpc('initialize', {'protocolVersion': 1, 'clientCapabilities': {},
110
+ 'clientInfo': {'name': 'local-acp-probe', 'version': '1'}})
111
+ opened = rpc('session/new', {'cwd': str(home), 'mcpServers': []})
112
+ sid = opened['sessionId']
113
+ result['after_open'] = rows()
114
+ result['model_requests_after_open'] = len(requests)
115
+ result['prompt_response'] = rpc('session/prompt', {'sessionId': sid,
116
+ 'prompt': [{'type': 'text', 'text': 'Reply with a short greeting; do not use tools.'}]})
117
+ result['after_prompt'] = rows()
118
+ forked = rpc('session/fork', {'sessionId': sid, 'cwd': str(home), 'mcpServers': []})
119
+ result['fork_id'] = forked['sessionId']
120
+ result['after_fork'] = rows()
121
+ with sqlite3.connect(hermes / 'state.db') as db:
122
+ result['messages'] = db.execute('SELECT session_id, role, content FROM messages ORDER BY id').fetchall()
123
+ for session_id in (sid, result['fork_id']):
124
+ assert [(r[1], r[2]) for r in result['messages'] if r[0] == session_id] == [
125
+ ('user', 'Reply with a short greeting; do not use tools.'),
126
+ ('assistant', 'Local fixture reply.')]
127
+ assert any(r[0] == sid and r[2] > 0 for r in result['after_prompt'])
128
+ assert any(r[0] == result['fork_id'] and r[2] > 0 for r in result['after_fork'])
129
+ legacy = rpc('session/new', {'cwd': str(home), 'mcpServers': []})['sessionId']
130
+ with sqlite3.connect(hermes / 'state.db') as db:
131
+ db.execute("INSERT OR IGNORE INTO sessions (id, source, started_at) VALUES (?, 'acp', 1)",
132
+ (legacy,))
133
+ moved = home / 'moved'
134
+ moved.mkdir()
135
+ rpc('session/load', {'sessionId': legacy, 'cwd': str(moved), 'mcpServers': []})
136
+ with sqlite3.connect(hermes / 'state.db') as db:
137
+ result['existing_empty_metadata'] = db.execute(
138
+ 'SELECT model_config, message_count FROM sessions WHERE id = ?', (legacy,)).fetchone()
139
+ assert json.loads(result['existing_empty_metadata'][0])['cwd'] == str(moved)
140
+ assert result['existing_empty_metadata'][1] == 0
141
+ assert result['after_open'] == [], 'session/new created an empty durable row'
142
+ finally:
143
+ proc.terminate()
144
+ proc.wait(timeout=20)
145
+ stderr.close()
146
+ server.shutdown()
147
+ result.update(wire=wire, model_requests=requests)
148
+ Path(args.output).write_text(json.dumps(result, indent=2), encoding='utf-8')
149
+ print(json.dumps({k: v for k, v in result.items() if k not in ('wire', 'model_requests', 'messages')}, indent=2))
150
+
151
+
152
+ if __name__ == '__main__':
153
+ main()
evals/anthropic_proxy_thinking_replay.py ADDED
@@ -0,0 +1,103 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Local wire-contract probe: which thinking blocks a real AIAgent replays to an
2
+ Anthropic-compatible relay. Synthetic SSE fixtures; NOT live-provider proof.
3
+
4
+ Run with the repo interpreter in an isolated HOME/HERMES_HOME:
5
+ python evals/anthropic_proxy_thinking_replay.py <out.json>
6
+ """
7
+ import json
8
+ import os
9
+ import sys
10
+ import tempfile
11
+ import threading
12
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
13
+ from pathlib import Path
14
+
15
+ ROOT = Path(__file__).resolve().parents[1]
16
+ sys.path.insert(0, str(ROOT))
17
+
18
+ HISTORY = [
19
+ {"role": "user", "content": "inspect the repo"},
20
+ {"role": "assistant", "content": "checking", "reasoning_details": [
21
+ {"type": "thinking", "thinking": "unsigned proxy reasoning"},
22
+ {"type": "thinking", "thinking": "foreign signed", "signature": "sig-from-elsewhere"},
23
+ ], "tool_calls": [{"id": "call_1", "type": "function",
24
+ "function": {"name": "terminal", "arguments": "{\"command\": \"ls\"}"}}]},
25
+ {"role": "tool", "tool_call_id": "call_1", "content": "README.md"},
26
+ {"role": "assistant", "content": "done"},
27
+ ]
28
+
29
+
30
+ def _sse(events):
31
+ return "".join(f"event: {e['type']}\ndata: {json.dumps(e)}\n\n" for e in events).encode()
32
+
33
+
34
+ def scenario(model, path="/anthropic"):
35
+ import run_agent
36
+ requests = []
37
+
38
+ class Handler(BaseHTTPRequestHandler):
39
+ def log_message(self, *_a):
40
+ pass
41
+
42
+ def do_POST(self):
43
+ payload = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
44
+ if self.path.endswith("/messages"): # skip the Ollama /api/show capability probe
45
+ requests.append(payload)
46
+ msg = {"id": "msg_local", "type": "message", "role": "assistant", "model": payload.get("model"),
47
+ "content": [], "stop_reason": None, "stop_sequence": None,
48
+ "usage": {"input_tokens": 10, "output_tokens": 0}}
49
+ events = [
50
+ {"type": "message_start", "message": msg},
51
+ {"type": "content_block_start", "index": 0, "content_block": {"type": "text", "text": ""}},
52
+ {"type": "content_block_delta", "index": 0, "delta": {"type": "text_delta", "text": "local fixture reply"}},
53
+ {"type": "content_block_stop", "index": 0},
54
+ {"type": "message_delta", "delta": {"stop_reason": "end_turn", "stop_sequence": None},
55
+ "usage": {"output_tokens": 3}},
56
+ {"type": "message_stop"},
57
+ ]
58
+ raw = _sse(events)
59
+ self.send_response(200)
60
+ self.send_header("Content-Type", "text/event-stream")
61
+ self.send_header("Content-Length", str(len(raw)))
62
+ self.end_headers()
63
+ self.wfile.write(raw)
64
+
65
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
66
+ threading.Thread(target=server.serve_forever, daemon=True).start()
67
+ agent = run_agent.AIAgent(
68
+ model=model, provider="custom", base_url=f"http://127.0.0.1:{server.server_port}{path}",
69
+ api_key="local-fixture-key", enabled_toolsets=["terminal"], max_iterations=1, quiet_mode=True,
70
+ reasoning_config={"enabled": True, "effort": "high"}, skip_context_files=True, skip_memory=True,
71
+ skip_background_review=True, save_trajectories=False, session_id=f"proxy-thinking-{model.replace('/', '-')}",
72
+ )
73
+ agent._api_max_retries = 1
74
+ try:
75
+ result = agent.run_conversation("reply briefly", system_message="Local wire probe.",
76
+ conversation_history=[dict(m) for m in HISTORY])
77
+ finally:
78
+ agent.close()
79
+ server.shutdown()
80
+ server.server_close()
81
+ wire = requests[0] if requests else {}
82
+ assistant_turns = [m for m in wire.get("messages", []) if m.get("role") == "assistant"]
83
+ thinking = [
84
+ {k: b.get(k) for k in ("type", "thinking", "signature") if k in b}
85
+ for m in assistant_turns for b in (m.get("content") if isinstance(m.get("content"), list) else [])
86
+ if b.get("type") in ("thinking", "redacted_thinking")
87
+ ]
88
+ return {"model": model, "api_mode": agent.api_mode, "completed": result.get("completed"),
89
+ "requests": len(requests), "wire_thinking_blocks": thinking,
90
+ "thinking_param": wire.get("thinking"), "tool_count": len(wire.get("tools") or [])}
91
+
92
+
93
+ def main():
94
+ out = {"surface": "real AIAgent + Anthropic SDK against a synthetic local relay; not provider proof",
95
+ "scenarios": [scenario("deepseek-ai/deepseek-v4-pro"), scenario("some-vendor/other-model")]}
96
+ Path(sys.argv[1]).write_text(json.dumps(out, indent=2) + "\n", encoding="utf-8")
97
+ print(json.dumps(out, indent=2))
98
+
99
+
100
+ if __name__ == "__main__":
101
+ with tempfile.TemporaryDirectory(prefix="proxy-thinking-") as home:
102
+ os.environ.update(HOME=home, HERMES_HOME=home, HERMES_DISABLE_PLUGINS="1")
103
+ main()
evals/api_delegation_http_probe.py ADDED
@@ -0,0 +1,102 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Loopback HTTP + real API executor/session bindings, with inference replaced.
2
+
3
+ No paid model calls. Captures what the runtime hands the model, not provider behavior.
4
+ """
5
+ import asyncio
6
+ import inspect
7
+ import json
8
+ import os
9
+ from pathlib import Path
10
+ from unittest.mock import MagicMock
11
+
12
+ from aiohttp import web
13
+ from aiohttp.test_utils import TestClient, TestServer
14
+
15
+
16
+ async def probe():
17
+ from gateway.config import PlatformConfig
18
+ from gateway.platforms.api_server import APIServerAdapter
19
+ from gateway.session_context import get_session_env
20
+ from gateway.wake import persist_delegation_delivery
21
+ from hermes_state import SessionDB
22
+ from tools.delegate_tool_dispatch import _resolve_async_wake_sid
23
+ import gateway.session_context as sc
24
+
25
+ db = SessionDB(db_path=Path(os.environ["HERMES_HOME"]) / "state.db")
26
+ db.create_session("parent", source="api_server")
27
+ db.append_message("parent", "user", "request")
28
+ db.append_message("parent", "assistant", "acknowledged")
29
+ db.end_session("parent", "compression")
30
+ db.create_session("child", source="api_server", parent_session_id="parent")
31
+ adapter = APIServerAdapter(PlatformConfig(enabled=True, extra={"key": "fixture-api-key"}))
32
+ adapter._session_db = db
33
+ captured = []
34
+
35
+ def create_agent(**kwargs):
36
+ agent = MagicMock()
37
+ agent.session_id = kwargs.get("session_id")
38
+ agent.session_prompt_tokens = agent.session_completion_tokens = agent.session_total_tokens = 0
39
+ def run(**turn):
40
+ sid = get_session_env("HERMES_SESSION_CHAT_ID", "")
41
+ args = [sid]
42
+ if len(inspect.signature(_resolve_async_wake_sid).parameters) > 1:
43
+ args.append(sc.session_history_delivery_supported())
44
+ captured.append({"session_id": sid, "target": _resolve_async_wake_sid(*args), "history": turn.get("conversation_history")})
45
+ callback = kwargs.get("stream_delta_callback")
46
+ if callback:
47
+ callback("fixture reply")
48
+ return {"final_response": "fixture reply", "session_id": sid, "messages": [], "api_calls": 1}
49
+ agent.run_conversation.side_effect = run
50
+ return agent
51
+ adapter._create_agent = create_agent
52
+ app = web.Application()
53
+ app.router.add_post("/v1/chat/completions", adapter._handle_chat_completions)
54
+ app.router.add_post("/v1/runs", adapter._handle_runs)
55
+ records = []
56
+ runs = []
57
+ async with TestClient(TestServer(app)) as client:
58
+ for stream in (False, True):
59
+ for explicit in (False, True):
60
+ headers = {"Authorization": "Bearer fixture-api-key"}
61
+ if explicit:
62
+ headers["X-Hermes-Session-Id"] = "parent"
63
+ response = await client.post("/v1/chat/completions", headers=headers, json={"messages": [{"role": "user", "content": "continue"}], "stream": stream})
64
+ body = await response.text()
65
+ records.append({"stream": stream, "explicit": explicit, "status": response.status, "header": response.headers.get("X-Hermes-Session-Id"), "runtime": captured[-1] if captured else None, "body": body[:120]})
66
+ calls_before = len(captured)
67
+ evt = {"type": "async_delegation", "delegation_id": "unit-http"}
68
+ delivery_error = None
69
+ try:
70
+ await asyncio.gather(*(persist_delegation_delivery(adapter, text="DELIVERY_RESULT", session_id="parent", evt=evt) for _ in range(2)))
71
+ except Exception as exc:
72
+ delivery_error = type(exc).__name__
73
+ calls_after = len(captured)
74
+ response = await client.post("/v1/chat/completions", headers={"Authorization": "Bearer fixture-api-key", "X-Hermes-Session-Id": "parent"}, json={"messages": [{"role": "user", "content": "read result"}]})
75
+ await response.read()
76
+ resumed_history = captured[-1]["history"]
77
+ snapshot = [{"role": "user", "content": "caller snapshot"}]
78
+ adapter._response_store.put("resp-seed", {"conversation_history": snapshot, "session_id": "parent"})
79
+ db.create_session("declared", source="api_server", session_key="fixture-key")
80
+ db.append_message("declared", "assistant", "DECLARED_HISTORY")
81
+ for name, body, extra_headers in (
82
+ ("session", {"session_id": "parent"}, {}),
83
+ ("caller_history", {"session_id": "parent", "conversation_history": snapshot}, {}),
84
+ ("response_chain", {"previous_response_id": "resp-seed"}, {}),
85
+ ("declared_key", {}, {"X-Hermes-Session-Key": "fixture-key"}),
86
+ ):
87
+ count = len(captured)
88
+ response = await client.post("/v1/runs", headers={"Authorization": "Bearer fixture-api-key", **extra_headers}, json={"input": "continue", **body})
89
+ await response.read()
90
+ async def wait_for_run():
91
+ while len(captured) == count:
92
+ await asyncio.sleep(0.01)
93
+ if response.status == 202:
94
+ await asyncio.wait_for(wait_for_run(), 10)
95
+ runs.append({"name": name, "status": response.status, "runtime": captured[-1] if len(captured) > count else None})
96
+ result = {"requests": records, "runs": runs, "delivery_error": delivery_error, "unsolicited_calls": calls_after-calls_before, "resumed_history": resumed_history, "durable_child_rows": len(db.get_messages("child"))}
97
+ db.close()
98
+ return result
99
+
100
+
101
+ if __name__ == "__main__":
102
+ print(json.dumps(asyncio.run(probe()), indent=2, default=str))
evals/api_delegation_sync_probe.py ADDED
@@ -0,0 +1,66 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Model-free API delegation delivery probe; run in an isolated HERMES_HOME.
2
+
3
+ Uses real request-context binding, dispatch policy and SQLite persistence. This
4
+ is local mechanism evidence, not provider inference or native Windows evidence.
5
+ """
6
+ import asyncio
7
+ import inspect
8
+ import json
9
+ import os
10
+ from pathlib import Path
11
+ from types import SimpleNamespace
12
+
13
+
14
+ async def probe():
15
+ from gateway.platforms.api_server import APIServerAdapter
16
+ from gateway.session_context import clear_session_vars
17
+ from gateway.wake import persist_delegation_delivery
18
+ from hermes_state import SessionDB
19
+ from tools.delegate_tool_dispatch import _resolve_async_wake_sid
20
+
21
+ decisions = {}
22
+ for name, capable in (("headerless", ""), ("explicit", "1")):
23
+ kw = dict(chat_id="api-parent", session_id="api-parent")
24
+ if "session_history_delivery" in inspect.signature(APIServerAdapter._bind_api_server_session).parameters:
25
+ kw["session_history_delivery"] = capable
26
+ tokens = APIServerAdapter._bind_api_server_session(**kw)
27
+ try:
28
+ args = ["api-parent"]
29
+ if len(inspect.signature(_resolve_async_wake_sid).parameters) > 1:
30
+ args.append(capable == "1")
31
+ decisions[name] = _resolve_async_wake_sid(*args)
32
+ finally:
33
+ clear_session_vars(tokens)
34
+ db = SessionDB(db_path=Path(os.environ["HERMES_HOME"]) / "state.db")
35
+ db.create_session("api-parent", source="api_server")
36
+ db.create_session("stranger", source="api_server")
37
+ adapter = SimpleNamespace(_ensure_session_db=lambda: db)
38
+ evt = {"type": "async_delegation", "delegation_id": "probe-unit-1"}
39
+ await asyncio.gather(*(persist_delegation_delivery(adapter, text="OWNER_RESULT", session_id="api-parent", evt=evt) for _ in range(2)))
40
+ decisions["replayed_rows"] = len(db.get_messages("api-parent"))
41
+ db.end_session("api-parent", "compression")
42
+ db.create_session("api-child", source="api_server", parent_session_id="api-parent")
43
+ try:
44
+ await persist_delegation_delivery(adapter, text="LATE_RESULT", session_id="api-parent", evt={**evt, "delegation_id": "probe-unit-2"})
45
+ decisions["rotation"] = "persisted"
46
+ except Exception as exc:
47
+ decisions["rotation"] = type(exc).__name__
48
+ decisions["child_rows"] = len(db.get_messages("api-child"))
49
+ db.acquire_session_turn_lease("api-child", "fixture-client-turn", wait_seconds=0)
50
+ busy_evt = {**evt, "delegation_id": "busy-unit"}
51
+ try:
52
+ await persist_delegation_delivery(adapter, text="BUSY_RESULT", session_id="api-child", evt=busy_evt)
53
+ decisions["busy_delivery"] = "inserted"
54
+ except Exception as exc:
55
+ decisions["busy_delivery"] = type(exc).__name__
56
+ finally:
57
+ db.release_session_turn_lease("api-child", "fixture-client-turn")
58
+ await persist_delegation_delivery(adapter, text="BUSY_RESULT", session_id="api-child", evt=busy_evt)
59
+ decisions["after_release_rows"] = len(db.get_messages("api-child"))
60
+ decisions["stranger_rows"] = len(db.get_messages("stranger"))
61
+ db.close()
62
+ return decisions
63
+
64
+
65
+ if __name__ == "__main__":
66
+ print(json.dumps(asyncio.run(probe()), indent=2))
evals/approval_deny_dispatch.py ADDED
@@ -0,0 +1,80 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Offline production-dispatch receipt; never invokes a privileged binary.
2
+
3
+ Run with the shared Python environment and a source tree argument to compare
4
+ base/head. The executable named sudo is an owned temporary marker script.
5
+ """
6
+ import json
7
+ import os
8
+ from pathlib import Path
9
+ import shlex
10
+ import sys
11
+ import tempfile
12
+
13
+ source = Path(sys.argv[1]).resolve()
14
+ with tempfile.TemporaryDirectory(prefix="hermes-deny-dispatch-") as directory:
15
+ home = Path(directory)
16
+ os.environ.clear()
17
+ # The terminal's own NOPASSWD probe must also resolve to our inert fixture.
18
+ os.environ.update(PATH=directory + ":/usr/bin:/bin", HOME=directory, HERMES_HOME=directory,
19
+ HERMES_INTERACTIVE="1", TERMINAL_ENV="local")
20
+ (home / "config.yaml").write_text(
21
+ 'approvals:\n mode: "off"\n deny: ["sudo *", "printf SAFE", "git status"]\n'
22
+ 'security:\n tirith_enabled: false\n', encoding="utf-8")
23
+ executable = home / "sudo"
24
+ executable.write_text('#!/bin/sh\nprintf "OWNED_EXECUTABLE_REACHED\\n"\n', encoding="utf-8")
25
+ executable.chmod(0o700)
26
+ # Prefer GNU env when the host's default env implements different -S syntax.
27
+ if Path("/usr/bin/gnuenv").exists():
28
+ (home / "env").symlink_to("/usr/bin/gnuenv")
29
+ sys.path.insert(0, str(source))
30
+ from tools import terminal_tool # noqa: F401
31
+ from tools.registry import registry
32
+ from tools import approval_context
33
+
34
+ binary = shlex.quote(str(executable))
35
+ cases = [binary + " -n id -u", "env -i " + binary + " -n id -u",
36
+ "command " + binary + " -n id -u",
37
+ "true && " + binary + " -n id -u",
38
+ "bash -c " + shlex.quote(binary + " -n id -u"),
39
+ "printf '%s\\n' 'sudo -n id -u'",
40
+ "env -S 'printf %s; sudo -n id'", "env -S printf SAFE",
41
+ "env -S git status", "echo ok # ; bash -c " + shlex.quote(binary + " -n id"),
42
+ "env -S 'printf %s' 'sudo -n id'", "env -S printf BENIGN",
43
+ "env -S " + shlex.quote("bash -c " + shlex.quote(binary + " -n id")),
44
+ "echo ok # ignored\n bash -c " + shlex.quote(binary + " -n id")]
45
+ cases += [
46
+ r"env -S 'printf\_SAFE'", r"env -S 'printf\_SAFE\c ignored'",
47
+ "env -S 'printf SAFE # ignored'", "env -S 'printf # ignored' SAFE",
48
+ "env -a marker printf SAFE", "env --argv0 marker printf SAFE",
49
+ "env --argv0=marker printf SAFE", "env -amarker printf SAFE",
50
+ r"env -a marker -S 'printf\_SAFE'",
51
+ "env -S '\"printf\"\\_SAFE'", "env -S \"'printf' SAFE\"",
52
+ r"env -S 'printf\_\_SAFE'", r"env -S 'printf\c ignored' SAFE",
53
+ "env -a sudo printf BENIGN", "env --argv0 sudo printf BENIGN",
54
+ "env -S 'printf %s \"sudo\\_-n\\_id\"'",
55
+ r"env -S 'printf BENIGN\c bash -c sudo'",
56
+ "env -S 'printf BENIGN # bash -c sudo'",
57
+ r"env -S 'printf %s \${IGNORED}'",
58
+ ]
59
+ rows = []
60
+ for command in cases:
61
+ result = registry.dispatch("terminal", {"command": command, "workdir": directory, "timeout": 10})
62
+ if isinstance(result, str):
63
+ result = json.loads(result)
64
+ rows.append({"command": command, "result": result})
65
+ # Optional assertions keep the same harness usable for before/after receipts.
66
+ expected_outputs = {5: 'sudo -n id -u', 6: 'sudo;-n;id;', 9: 'ok',
67
+ 10: 'sudo -n id', 11: 'BENIGN', 27: 'BENIGN', 28: 'BENIGN',
68
+ 29: 'sudo -n id', 30: 'BENIGN', 31: 'BENIGN', 32: '${IGNORED}'}
69
+ if '--verify' in sys.argv:
70
+ for index, row in enumerate(rows):
71
+ result = row['result']
72
+ if index in expected_outputs:
73
+ assert result.get('exit_code') == 0, row
74
+ assert result.get('output', '').strip() == expected_outputs[index], row
75
+ else:
76
+ assert result.get('status') == 'blocked', row
77
+ assert 'user-defined deny rule' in result.get('error', ''), row
78
+ assert not result.get('output'), row
79
+ print(json.dumps({"source": str(source), "config": approval_context._get_approval_config(),
80
+ "rows": rows}, indent=2))
evals/auth_pool_controls.py ADDED
@@ -0,0 +1,153 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Live PTY auth controls with isolated homes and a loopback OAuth server.
2
+
3
+ Usage: python evals/auth_pool_controls.py REPO OUTPUT_JSON
4
+ No vendor requests or real credentials are used. The token URL alone is redirected;
5
+ the production parser, command, pool refresh, HTTP client, and persistence execute.
6
+ """
7
+ import argparse
8
+ import base64
9
+ import json
10
+ import os
11
+ from pathlib import Path
12
+ import sys
13
+ import tempfile
14
+ import threading
15
+ import time
16
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
17
+ from urllib.parse import parse_qs
18
+
19
+ import errno
20
+ import pty
21
+ import subprocess
22
+
23
+
24
+ def main():
25
+ parser = argparse.ArgumentParser(description=__doc__)
26
+ parser.add_argument("repo")
27
+ parser.add_argument("output")
28
+ args = parser.parse_args()
29
+ requests = []
30
+ response_status = 200
31
+
32
+ class Endpoint(BaseHTTPRequestHandler):
33
+ def do_POST(self):
34
+ payload = parse_qs(self.rfile.read(int(self.headers["Content-Length"])).decode())
35
+ requests.append({"grant_type": payload.get("grant_type"),
36
+ "target_grant": (payload.get("refresh_token") == ["fixture-refresh-1"]
37
+ or self.headers.get("x-nous-refresh-token") == "fixture-refresh-1")})
38
+ body = ({"access_token": nous_new_token if self.path == "/api/oauth/token" else "fixture-new-access",
39
+ "refresh_token": "fixture-new-refresh", "expires_in": 3600, "scope": "inference:invoke"}
40
+ if response_status == 200 else {"error": "invalid_grant" if response_status == 401 else "unavailable"})
41
+ self.send_response(response_status)
42
+ self.send_header("Content-Type", "application/json")
43
+ self.end_headers()
44
+ self.wfile.write(json.dumps(body).encode())
45
+
46
+ def log_message(self, format, *values):
47
+ pass
48
+
49
+ def token(subject):
50
+ encode = lambda value: base64.urlsafe_b64encode(json.dumps(value).encode()).decode().rstrip("=")
51
+ return encode({"alg": "none"}) + "." + encode({"sub": subject, "exp": int(time.time()) + 3600,
52
+ "scope": "inference:invoke"}) + ".fixture"
53
+
54
+ nous_new_token = token("singleton-renewed")
55
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Endpoint)
56
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
57
+ thread.start()
58
+ cases = [
59
+ ("target-reset", "openrouter", ["reset", "openrouter", "row1"], None),
60
+ ("all-reset", "openrouter", ["reset", "openrouter"], None),
61
+ ("ambiguous-reset", "openrouter", ["reset", "openrouter", "shared"], None),
62
+ ("priority", "openrouter", ["priority", "openrouter", "row1", "0"], None),
63
+ ("priority-clamp", "openrouter", ["priority", "openrouter", "row0", "99"], None),
64
+ ("priority-missing", "openrouter", ["priority", "openrouter", "missing", "0"], None),
65
+ ("add-priority", "openrouter", ["add", "openrouter", "--api-key", "fixture-new", "--label", "new", "--priority", "0"], None),
66
+ ("refresh-api-key", "openrouter", ["refresh", "openrouter", "row1"], None),
67
+ ("refresh-ambiguous", "openai-codex", ["refresh", "openai-codex"], None),
68
+ *[(f"refresh-{status}", "openai-codex", ["refresh", "openai-codex", "row1"], status)
69
+ for status in (200, 503, 401)],
70
+ ]
71
+ cases.extend((name, "nous", ["refresh", "nous", target], None) for name, target in
72
+ (("nous-independent", "row0"), ("nous-singleton", "row1")))
73
+ results = []
74
+ try:
75
+ for name, provider, command, status in cases:
76
+ response_status = status or 200
77
+ requests.clear()
78
+ with tempfile.TemporaryDirectory(prefix="auth-pool-pty-") as temp:
79
+ home = Path(temp)
80
+ now = time.time()
81
+ rows = [dict(id=f"row{i}", label="shared" if name == "ambiguous-reset" else f"account{i}",
82
+ source="manual:device_code" if provider == "openai-codex" else "manual",
83
+ auth_type="oauth" if provider == "openai-codex" else "api_key",
84
+ access_token=f"fixture-access-{i}", refresh_token=f"fixture-refresh-{i}",
85
+ priority=i, last_status="exhausted", last_status_at=now,
86
+ last_error_code=429, last_error_reset_at=now+3600) for i in range(2)]
87
+ providers = {}
88
+ if provider == "nous":
89
+ for row in rows:
90
+ row.update(auth_type="oauth", source="manual:device_code")
91
+ state = dict(access_token=token("singleton"), refresh_token="fixture-refresh-1",
92
+ expires_at=now+3600, portal_base_url=f"http://127.0.0.1:{server.server_port}",
93
+ scope="inference:invoke", inference_base_url="https://inference-api.nousresearch.com/v1")
94
+ rows[1].update(source="device_code", **state)
95
+ providers["nous"] = state
96
+ store = home / "auth.json"
97
+ store.write_text(json.dumps({"version": 1, "providers": providers, "active_provider": provider, "credential_pool": {provider: rows}}), encoding="utf-8")
98
+ env = {k: v for k, v in os.environ.items() if not any(t in k for t in
99
+ ("TOKEN", "API_KEY", "SECRET", "PASSWORD", "HERMES", "PYTEST"))}
100
+ env.update(HOME=temp, HERMES_HOME=temp, HERMES_SHARED_AUTH_DIR=str(home / "shared"), PYTHONPATH=str(Path(args.repo).absolute()), TERM="xterm")
101
+ bootstrap = ("import sys, httpx; original_send=httpx.Client.send; "
102
+ "httpx.Client.send=lambda self, request, **kw: original_send(self, request, **kw) "
103
+ "if request.url.host == '127.0.0.1' else (_ for _ in ()).throw(AssertionError('NONLOCAL_NETWORK')); "
104
+ "from hermes_cli import auth_codex; "
105
+ f"auth_codex.CODEX_OAUTH_TOKEN_URL='http://127.0.0.1:{server.server_port}/token'; "
106
+ "from hermes_cli.main import main; "
107
+ f"sys.argv=['hermes','auth',*{command!r}]; main()")
108
+ master, slave = pty.openpty()
109
+ child = subprocess.Popen([sys.executable, "-c", bootstrap], cwd=args.repo,
110
+ env=env, stdin=slave, stdout=slave, stderr=slave)
111
+ os.close(slave)
112
+ chunks = []
113
+ while True:
114
+ try:
115
+ chunk = os.read(master, 65536)
116
+ if not chunk:
117
+ break
118
+ chunks.append(chunk)
119
+ except OSError as exc:
120
+ if exc.errno != errno.EIO:
121
+ raise
122
+ break
123
+ os.close(master)
124
+ output = b"".join(chunks).decode("utf-8")
125
+ exit_code = child.wait(timeout=30)
126
+ disk = json.loads(store.read_text(encoding="utf-8"))["credential_pool"][provider]
127
+ results.append({"case": name, "exit": exit_code, "output": output,
128
+ "wire": list(requests), "secrets_printed": "fixture-" in output or ".fixture" in output,
129
+ "disk": [{k: e.get(k) for k in ("id", "priority", "last_status", "last_error_reset_at", "request_count")}
130
+ for e in disk],
131
+ "target_refresh_rotated": any(e["id"] == "row1" and e.get("refresh_token") == "fixture-new-refresh" for e in disk),
132
+ "target_rotated": any(e["id"] == "row1" and e.get("access_token") == (nous_new_token if provider == "nous" else "fixture-new-access") for e in disk),
133
+ "independent_tokens_preserved": all(next(e for e in disk if e["id"] == "row0").get(k) == rows[0].get(k) for k in ("access_token", "refresh_token")),
134
+ "sibling_cooldown_preserved": next(e for e in disk if e["id"] == "row0").get("last_error_reset_at") == now+3600})
135
+ finally:
136
+ server.shutdown()
137
+ thread.join(timeout=5)
138
+ server.server_close()
139
+ Path(args.output).write_text(json.dumps({"repo": args.repo, "cases": results}, indent=2), encoding="utf-8")
140
+ independent = next(r for r in results if r["case"] == "nous-independent")
141
+ assert independent["exit"] != 0 and not independent["wire"], independent
142
+ assert independent["independent_tokens_preserved"] and independent["sibling_cooldown_preserved"], independent
143
+ singleton = next(r for r in results if r["case"] == "nous-singleton")
144
+ assert singleton["exit"] == 0 and singleton["target_rotated"] and singleton["target_refresh_rotated"], singleton
145
+ assert len(singleton["wire"]) == 1 and singleton["wire"][0]["target_grant"], singleton
146
+ assert singleton["sibling_cooldown_preserved"] and singleton["independent_tokens_preserved"], singleton
147
+ assert all(not r["secrets_printed"] and "NONLOCAL_NETWORK" not in r["output"] for r in results)
148
+ print(json.dumps([{"case": r["case"], "exit": r["exit"], "posts": len(r["wire"]),
149
+ "target_rotated": r["target_rotated"], "secrets_printed": r["secrets_printed"]} for r in results], indent=2))
150
+
151
+
152
+ if __name__ == "__main__":
153
+ main()
evals/auxiliary_resource_exhausted.py ADDED
@@ -0,0 +1,110 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Local HTTP contract probe; no vendor request or personal Hermes state.
2
+
3
+ Run from the repository with its Python interpreter. JSON output identifies the
4
+ loaded module, observed SDK error, request order, and preserved message payload.
5
+ """
6
+
7
+ import argparse
8
+ import asyncio
9
+ import json
10
+ import os
11
+ from pathlib import Path
12
+ import sys
13
+ import tempfile
14
+ import threading
15
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
16
+
17
+
18
+ def main():
19
+ parser = argparse.ArgumentParser()
20
+ parser.add_argument("--spelling", default="ResourceExhausted")
21
+ parser.add_argument("--mode", choices=("sync", "async", "sse"), default="sync")
22
+ parser.add_argument("--status", type=int, default=403)
23
+ args = parser.parse_args()
24
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
25
+ requests = []
26
+ message = f"{args.spelling}: Worker local total request limit reached (32/32)"
27
+ messages = [{"role": "user", "content": "Summarize: keep the deployment decision."}]
28
+
29
+ class Handler(BaseHTTPRequestHandler):
30
+ def log_message(self, *args):
31
+ pass
32
+
33
+ def do_POST(self):
34
+ body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
35
+ if "messages" not in body: # capability probes (/api/show) are not chat requests
36
+ self.send_response(404)
37
+ self.end_headers()
38
+ return
39
+ requests.append(body)
40
+ primary = body["model"] == "primary-probe"
41
+ if primary and args.mode == "sse":
42
+ data = 'data: ' + json.dumps({"error": {"message": message}}) + '\n\ndata: [DONE]\n\n'
43
+ status, kind = 200, "text/event-stream"
44
+ elif primary:
45
+ data = json.dumps({"error": {"message": message, "type": "provider_error"}})
46
+ status, kind = args.status, "application/json"
47
+ else:
48
+ data = json.dumps({"id": "local-summary", "object": "chat.completion", "created": 0,
49
+ "model": body["model"], "choices": [{"index": 0, "finish_reason": "stop",
50
+ "message": {"role": "assistant", "content": "Deployment decision preserved."}}]})
51
+ status, kind = 200, "application/json"
52
+ encoded = data.encode()
53
+ self.send_response(status)
54
+ self.send_header("Content-Type", kind)
55
+ self.send_header("Content-Length", str(len(encoded)))
56
+ self.end_headers()
57
+ self.wfile.write(encoded)
58
+
59
+ with tempfile.TemporaryDirectory(prefix="aux-resource-") as home:
60
+ os.environ["HOME"] = home
61
+ os.environ["HERMES_HOME"] = home
62
+ # Two listeners: a payment/quota error is credential-wide, so the fallback must be a
63
+ # different backend identity (distinct base_url) exactly as NIM -> OpenRouter is in the field.
64
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
65
+ fallback_server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
66
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
67
+ fallback_thread = threading.Thread(target=fallback_server.serve_forever, daemon=True)
68
+ thread.start()
69
+ fallback_thread.start()
70
+ base_url = f"http://127.0.0.1:{server.server_port}/v1"
71
+ fallback_url = f"http://127.0.0.1:{fallback_server.server_port}/v1"
72
+ # The primary is the real ``nvidia`` profile pointed at the local listener; the fallback is a
73
+ # named custom provider (its own credential label, like a second vendor in the field).
74
+ config = {"model": {"provider": "local-fallback", "model": "fallback-probe"},
75
+ "providers": {"local-fallback": {"base_url": fallback_url, "api_key": "local-probe"}},
76
+ "auxiliary": {"compression": {"provider": "nvidia", "model": "primary-probe",
77
+ "base_url": base_url, "api_key": "local-probe", "api_mode": "chat_completions",
78
+ "fallback_chain": [{"provider": "local-fallback", "model": "fallback-probe"}]}}}
79
+ # JSON is valid YAML and keeps this standalone probe dependency-free.
80
+ Path(home, "config.yaml").write_text(json.dumps(config), encoding="utf-8")
81
+ import logging
82
+ if os.environ.get("AUX_PROBE_DEBUG"):
83
+ logging.basicConfig(level=logging.DEBUG, stream=sys.stderr)
84
+ import agent.auxiliary_client as aux
85
+
86
+ result = {"module": aux.__file__, "mode": args.mode, "status": args.status,
87
+ "spelling": args.spelling, "surface": "local HTTP contract, not live provider"}
88
+ try:
89
+ if args.mode == "async":
90
+ response = asyncio.run(aux.async_call_llm(task="compression", messages=messages, max_tokens=64))
91
+ else:
92
+ with aux.aux_progress_hook((lambda: None) if args.mode == "sse" else None):
93
+ response = aux.call_llm(task="compression", messages=messages, max_tokens=64)
94
+ result["content"] = response.choices[0].message.content
95
+ except Exception as exc:
96
+ result["error"] = type(exc).__name__
97
+ result["error_status"] = getattr(exc, "status_code", None)
98
+ result["error_message"] = str(exc)
99
+ finally:
100
+ for srv, thr in ((server, thread), (fallback_server, fallback_thread)):
101
+ srv.shutdown()
102
+ srv.server_close()
103
+ thr.join()
104
+ result["models"] = [request["model"] for request in requests]
105
+ result["messages_preserved"] = all(request["messages"] == messages for request in requests)
106
+ print(json.dumps(result))
107
+
108
+
109
+ if __name__ == "__main__":
110
+ main()
evals/cli_deferred_notice.py ADDED
@@ -0,0 +1,129 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Drive the real CLI with a FIFO update-cache result under a Linux PTY.
2
+
3
+ Run from the checkout with the project Python. No provider requests are sent.
4
+ The FIFO releases the real cached update result only after the prompt renders.
5
+ """
6
+ import argparse
7
+ import errno
8
+ import json
9
+ import os
10
+ from pathlib import Path
11
+ import pty
12
+ import select
13
+ import signal
14
+ import struct
15
+ import subprocess
16
+ import sys
17
+ import tempfile
18
+ import termios
19
+ import time
20
+ import fcntl
21
+
22
+
23
+ def run_case(root, output, name, behind, early=False, cancel=False):
24
+ with tempfile.TemporaryDirectory(prefix="hermes_test_notice_") as home:
25
+ hh = Path(home) / ".hermes"
26
+ hh.mkdir()
27
+ (hh / "config.yaml").write_text(
28
+ "model:\n default: test-model\n provider: custom\n"
29
+ " base_url: http://127.0.0.1:9/v1\n"
30
+ "display:\n interface: cli\n skip_banner: false\n"
31
+ "memory:\n provider: ''\n", encoding="utf-8")
32
+ cache = hh / ".update_check"
33
+ # The version comes from the checkout, not an invented cache identity.
34
+ from hermes_cli.banner import VERSION
35
+ payload = json.dumps({"ts": time.time(), "behind": behind,
36
+ "rev": None, "ver": VERSION}).encode()
37
+ if early:
38
+ cache.write_bytes(payload)
39
+ else:
40
+ os.mkfifo(cache)
41
+ env = {"PATH": os.environ["PATH"], "HOME": home, "HERMES_HOME": str(hh),
42
+ "PYTHONPATH": str(root), "PYTHONUNBUFFERED": "1",
43
+ "TERM": "xterm-256color", "LANG": "C.UTF-8",
44
+ "OPENAI_API_KEY": "local-not-used", "PROMPT_TOOLKIT_NO_CPR": "1"}
45
+ master, slave = pty.openpty()
46
+ fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", 40, 120, 0, 0))
47
+ bootstrap = ("import hermes_cli.main as m; import hermes_cli.banner as b; "
48
+ "print('LOADED', m.__file__, b.__file__, flush=True); m.main()")
49
+ proc = subprocess.Popen([sys.executable, "-c", bootstrap, "chat"], cwd=root,
50
+ env=env, stdin=slave, stdout=slave, stderr=slave,
51
+ start_new_session=True)
52
+ os.close(slave)
53
+ data = bytearray()
54
+
55
+ def pump_until(predicate, timeout=30):
56
+ deadline = time.monotonic() + timeout
57
+ while time.monotonic() < deadline:
58
+ if predicate(bytes(data)):
59
+ return True
60
+ if select.select([master], [], [], 0.1)[0]:
61
+ try:
62
+ chunk = os.read(master, 65536)
63
+ except OSError as exc:
64
+ if exc.errno == errno.EIO:
65
+ return predicate(bytes(data))
66
+ raise
67
+ if not chunk:
68
+ return predicate(bytes(data))
69
+ data.extend(chunk)
70
+ return predicate(bytes(data))
71
+
72
+ try:
73
+ ready = pump_until(lambda b: b"\x1b[?2004h" in b)
74
+ assert ready, f"{name}: prompt did not render: {data[-1500:]!r}"
75
+ offset = len(data)
76
+ if not early and not cancel:
77
+ fd = os.open(cache, os.O_WRONLY | os.O_NONBLOCK)
78
+ os.write(fd, payload)
79
+ os.close(fd)
80
+ pump_until(lambda b: b"to update" in b[offset:] or b"update available" in b[offset:], 3)
81
+ # prompt_toolkit prints above the prompt via run_in_terminal (input detached,
82
+ # cooked mode); type only after the prompt is redrawn, like a user would.
83
+ redraw = len(data)
84
+ pump_until(lambda b: b"\x1b[?2004h" in b[redraw:], 3)
85
+ elif cancel:
86
+ os.write(master, b"\x03")
87
+ os.write(master, b"/quit\r")
88
+ exited = pump_until(lambda b: proc.poll() is not None, 60)
89
+ proc.wait(timeout=30)
90
+ text = bytes(data).decode(errors="replace")
91
+ (output / f"{name}.pty").write_bytes(data)
92
+ result = {"case": name, "ready": ready, "exited": exited,
93
+ "returncode": proc.returncode, "garbled": "?[1;33m" in text,
94
+ "notice": "commits behind" in text or "update available" in text,
95
+ "loaded_worktree": str(root / "hermes_cli/banner.py") in text,
96
+ "raw_path": str(output / f"{name}.pty")}
97
+ assert result["loaded_worktree"] and proc.returncode == 0, result
98
+ return result
99
+ finally:
100
+ (output / f"{name}.pty").write_bytes(data)
101
+ if proc.poll() is None:
102
+ os.killpg(proc.pid, signal.SIGKILL)
103
+ proc.wait(timeout=30)
104
+ os.close(master)
105
+
106
+
107
+ def main():
108
+ parser = argparse.ArgumentParser()
109
+ parser.add_argument("--output", type=Path, required=True)
110
+ parser.add_argument("--root", required=True)
111
+ parser.add_argument("--expect", choices=("clean", "garbled"), required=True)
112
+ args = parser.parse_args()
113
+ root = Path(args.root).resolve()
114
+ args.output.mkdir(parents=True, exist_ok=True)
115
+ cases = [("late-count", 3, False, False), ("late-current", 0, False, False),
116
+ ("late-unknown-count", -1, False, False), ("early-count", 3, True, False),
117
+ ("cancel-pending", 3, False, True)]
118
+ results = [run_case(root, args.output, *case) for case in cases]
119
+ (args.output / "results.json").write_text(json.dumps(results, indent=2) + "\n")
120
+ print(json.dumps(results, indent=2))
121
+ for row in results:
122
+ expected_notice = row["case"] not in ("late-current", "cancel-pending")
123
+ assert row["notice"] == expected_notice, row
124
+ expected_garble = args.expect == "garbled" and row["case"].startswith("late-") and expected_notice
125
+ assert row["garbled"] == expected_garble, row
126
+
127
+
128
+ if __name__ == "__main__":
129
+ main()
evals/cli_fallback_add_picker_error.py ADDED
@@ -0,0 +1,135 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Drive the real ``hermes fallback add`` under a Linux PTY into an ordinary picker error.
2
+
3
+ Run from the checkout with the project Python. No provider requests are sent: the picker
4
+ target is a saved custom provider with ``discover_models: false``. The auth store is made
5
+ unreadable AFTER the provider menu renders (the pre-picker snapshot has already happened), so
6
+ the canonical picker writes the temporary primary route to config.yaml and then fails inside
7
+ ``deactivate_provider`` with a plain ``PermissionError`` -- not ``SystemExit``.
8
+
9
+ The invariant under test: config.yaml ``model`` must equal the pre-picker primary afterwards.
10
+ """
11
+ import argparse
12
+ import errno
13
+ import json
14
+ import os
15
+ from pathlib import Path
16
+ import pty
17
+ import re
18
+ import select
19
+ import signal
20
+ import struct
21
+ import subprocess
22
+ import sys
23
+ import tempfile
24
+ import termios
25
+ import time
26
+ import fcntl
27
+
28
+ PRIMARY = {"provider": "openrouter", "default": "primary/model-a",
29
+ "base_url": "https://openrouter.ai/api/v1", "api_mode": "chat_completions"}
30
+ CONFIG = (
31
+ "model:\n provider: openrouter\n default: primary/model-a\n"
32
+ " base_url: https://openrouter.ai/api/v1\n api_mode: chat_completions\n"
33
+ "custom_providers:\n - name: LocalLab\n base_url: http://127.0.0.1:9/v1\n"
34
+ " model: lab-model\n discover_models: false\n models:\n - lab-model\n"
35
+ "memory:\n provider: ''\n")
36
+
37
+
38
+ def _persisted_model(root: Path, env: dict) -> dict:
39
+ """``config.yaml`` ``model`` section as the CLI itself reads it (owner module, same env)."""
40
+ out = subprocess.run(
41
+ [sys.executable, "-c", "import json; from hermes_cli.config import load_config; "
42
+ "print(json.dumps(load_config().get('model')))"],
43
+ cwd=root, env=env, capture_output=True, text=True, check=True)
44
+ return json.loads(out.stdout.strip().splitlines()[-1])
45
+
46
+
47
+ def run(root: Path, output: Path) -> dict:
48
+ with tempfile.TemporaryDirectory(prefix="hermes_test_fallback_") as home:
49
+ hh = Path(home) / ".hermes"
50
+ hh.mkdir()
51
+ (hh / "config.yaml").write_text(CONFIG, encoding="utf-8")
52
+ (hh / ".env").write_text("OPENROUTER_API_KEY=local-not-used\n", encoding="utf-8")
53
+ auth = hh / "auth.json"
54
+ auth.write_text(json.dumps({"version": 1, "providers": {}, "active_provider": "nous"}))
55
+ # A stub ``curses`` package forces every menu onto its numbered fallback so the PTY
56
+ # exchange is line-oriented (the curses UI is not what is under test here).
57
+ shim = Path(home) / "shim" / "curses"
58
+ shim.mkdir(parents=True)
59
+ (shim / "__init__.py").write_text("raise ImportError('curses disabled for PTY harness')\n")
60
+ env = {"PATH": os.environ["PATH"], "HOME": home, "HERMES_HOME": str(hh),
61
+ "PYTHONPATH": f"{shim.parent}{os.pathsep}{root}", "PYTHONUNBUFFERED": "1",
62
+ "TERM": "dumb", "LANG": "C.UTF-8"}
63
+ master, slave = pty.openpty()
64
+ fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", 50, 120, 0, 0))
65
+ proc = subprocess.Popen([sys.executable, "-m", "hermes_cli.main", "fallback", "add"],
66
+ cwd=root, env=env, stdin=slave, stdout=slave, stderr=slave,
67
+ start_new_session=True)
68
+ os.close(slave)
69
+ data = bytearray()
70
+
71
+ def pump_until(predicate, timeout=60):
72
+ deadline = time.monotonic() + timeout
73
+ while time.monotonic() < deadline:
74
+ if predicate(bytes(data)):
75
+ return True
76
+ if select.select([master], [], [], 0.1)[0]:
77
+ try:
78
+ chunk = os.read(master, 65536)
79
+ except OSError as exc:
80
+ if exc.errno == errno.EIO:
81
+ return predicate(bytes(data))
82
+ raise
83
+ if not chunk:
84
+ return predicate(bytes(data))
85
+ data.extend(chunk)
86
+ return predicate(bytes(data))
87
+
88
+ try:
89
+ assert pump_until(lambda b: b"Choice [default" in b), data[-2000:]
90
+ text = bytes(data).decode(errors="replace")
91
+ row = re.search(r"(\d+)\. LocalLab", text)
92
+ assert row, text[-3000:]
93
+ # Snapshot is done (menu is up); now make the auth store unreadable so the picker's
94
+ # own deactivate_provider() fails with an ordinary OSError after writing the model.
95
+ auth.chmod(0)
96
+ os.write(master, f"{row.group(1)}\r".encode())
97
+ offset = len(data)
98
+ assert pump_until(lambda b: b"Choice [" in b[offset:]), data[-2000:]
99
+ os.write(master, b"1\r")
100
+ exited = pump_until(lambda b: proc.poll() is not None, 90)
101
+ proc.wait(timeout=30)
102
+ auth.chmod(0o600)
103
+ model_after = _persisted_model(root, env)
104
+ text = bytes(data).decode(errors="replace")
105
+ return {"exited": exited, "returncode": proc.returncode,
106
+ "picker_error_surfaced": "PermissionError" in text,
107
+ "model_after": model_after, "primary_restored": model_after == PRIMARY,
108
+ "auth_active_provider": json.loads(auth.read_text()).get("active_provider"),
109
+ "restore_note": "Could not fully restore" in text,
110
+ "raw_path": str(output / "fallback-add-picker-error.pty")}
111
+ finally:
112
+ output.mkdir(parents=True, exist_ok=True)
113
+ (output / "fallback-add-picker-error.pty").write_bytes(data)
114
+ if proc.poll() is None:
115
+ os.killpg(proc.pid, signal.SIGKILL)
116
+ proc.wait(timeout=30)
117
+ os.close(master)
118
+
119
+
120
+ def main():
121
+ parser = argparse.ArgumentParser()
122
+ parser.add_argument("--root", required=True)
123
+ parser.add_argument("--output", type=Path, required=True)
124
+ parser.add_argument("--expect", choices=("stranded", "restored"), required=True)
125
+ args = parser.parse_args()
126
+ result = run(Path(args.root).resolve(), args.output)
127
+ (args.output / "results.json").write_text(json.dumps(result, indent=2) + "\n")
128
+ print(json.dumps(result, indent=2))
129
+ assert result["exited"] and result["returncode"] != 0, result
130
+ assert result["picker_error_surfaced"], result
131
+ assert result["primary_restored"] == (args.expect == "restored"), result
132
+
133
+
134
+ if __name__ == "__main__":
135
+ main()
evals/codex_masked_replay_review.py ADDED
@@ -0,0 +1,138 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Local HTTP contract review of masked-error recovery; NOT live-provider proof.
2
+
3
+ Run in an isolated HOME/HERMES_HOME under the campaign test lock. Responses are
4
+ explicit synthetic fixtures; the client, transport, and AIAgent loop are real.
5
+ """
6
+ import copy
7
+ import hashlib
8
+ import json
9
+ import os
10
+ from pathlib import Path
11
+ import sys
12
+ import threading
13
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
14
+
15
+ ROOT = Path(__file__).resolve().parents[1]
16
+ sys.path.insert(0, str(ROOT))
17
+ import run_agent
18
+ from agent import error_classifier
19
+ from openai import APIError
20
+ import httpx
21
+
22
+ ITEM = {"type": "reasoning", "id": "rs_review", "encrypted_content": "signed-control-opaque-do-not-alter", "summary": []}
23
+ ERROR = {"message": "Request blocked.", "type": "invalid_request_error", "param": None, "code": "invalid_prompt"}
24
+
25
+
26
+ def digest(value):
27
+ return hashlib.sha256(json.dumps(value, sort_keys=True).encode()).hexdigest()
28
+
29
+
30
+ def scenario(name, provider="openai-codex", replay=True):
31
+ requests = []
32
+
33
+ class Handler(BaseHTTPRequestHandler):
34
+ def log_message(self, *_args):
35
+ pass
36
+
37
+ def do_POST(self):
38
+ payload = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
39
+ if "input" not in payload:
40
+ raw = json.dumps({"id": "chat-local", "object": "chat.completion", "created": 1,
41
+ "model": "gpt-5-codex", "choices": [{"index": 0, "finish_reason": "stop",
42
+ "message": {"role": "assistant", "content": "local auxiliary fixture"}}]}).encode()
43
+ self.send_response(200)
44
+ self.send_header("Content-Type", "application/json")
45
+ self.send_header("Content-Length", str(len(raw)))
46
+ self.end_headers()
47
+ self.wfile.write(raw)
48
+ return
49
+ requests.append(payload)
50
+ has_replay = any(i.get("type") == "reasoning" for i in payload["input"])
51
+ error = copy.deepcopy(ERROR)
52
+ if name == "explicit_encrypted":
53
+ error.update(code="invalid_encrypted_content", message="The encrypted content could not be verified.")
54
+ reject = name in {"unrelated_block", "failed_frame"} or (name not in {"success", "failed_frame"} and has_replay)
55
+ if reject and name == "failed_frame":
56
+ # The shape openai/codex issues show for a blocked turn: response.in_progress, then a
57
+ # ``response.failed`` terminal frame carrying the error (no HTTP status).
58
+ failed = {"id": "resp_review", "object": "response", "created_at": 1, "status": "failed",
59
+ "model": "gpt-5-codex", "output": [], "error": error}
60
+ events = [{"type": "response.created", "response": dict(failed, status="in_progress", error=None), "sequence_number": 0},
61
+ {"type": "response.in_progress", "response": dict(failed, status="in_progress", error=None), "sequence_number": 1},
62
+ {"type": "response.failed", "response": failed, "sequence_number": 2}]
63
+ raw = "".join("data: " + json.dumps(e) + "\n\n" for e in events).encode()
64
+ self.send_response(200)
65
+ self.send_header("Content-Type", "text/event-stream")
66
+ elif reject:
67
+ raw = json.dumps({"error": error}).encode()
68
+ self.send_response(400)
69
+ self.send_header("Content-Type", "application/json")
70
+ else:
71
+ response = {"id": "resp_review", "object": "response", "created_at": 1,
72
+ "status": "completed", "model": "gpt-5-codex", "output": [
73
+ {"id": "msg_review", "type": "message", "role": "assistant", "status": "completed",
74
+ "content": [{"type": "output_text", "text": "local fixture success", "annotations": []}]}],
75
+ "usage": {"input_tokens": 10, "output_tokens": 3, "total_tokens": 13}}
76
+ created = dict(response, status="in_progress", output=[])
77
+ events = [{"type": "response.created", "response": created, "sequence_number": 0},
78
+ {"type": "response.output_item.done", "item": response["output"][0], "output_index": 0, "sequence_number": 1},
79
+ {"type": "response.completed", "response": response, "sequence_number": 2}]
80
+ raw = "".join("data: " + json.dumps(e) + "\n\n" for e in events).encode()
81
+ self.send_response(200)
82
+ self.send_header("Content-Type", "text/event-stream")
83
+ self.send_header("Content-Length", str(len(raw)))
84
+ self.send_header("x-request-id", f"local-{name}-{len(requests)}")
85
+ self.end_headers()
86
+ self.wfile.write(raw)
87
+
88
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
89
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
90
+ thread.start()
91
+ agent = run_agent.AIAgent(
92
+ model="gpt-5-codex", provider=provider, api_mode="codex_responses",
93
+ base_url=f"http://127.0.0.1:{server.server_port}/v1", api_key="local-fixture-key",
94
+ enabled_toolsets=["terminal"], max_iterations=2, quiet_mode=True,
95
+ reasoning_config={"effort": "high"}, skip_context_files=True,
96
+ skip_memory=True, skip_background_review=True, save_trajectories=False,
97
+ session_id=f"local-review-{name}-{provider}-{replay}",
98
+ )
99
+ agent._api_max_retries = 3 # show whether a deterministic rejection burns identical retries
100
+ history = [{"role": "user", "content": "hello"}, {"role": "assistant", "content": "hello"}]
101
+ if replay:
102
+ history[1]["codex_reasoning_items"] = [copy.deepcopy(ITEM)]
103
+ try:
104
+ result = agent.run_conversation("reply briefly", system_message="Local contract review.", conversation_history=history)
105
+ reasoning_counts = [sum(i.get("type") == "reasoning" for i in p["input"]) for p in requests]
106
+ stable = {k: len({digest(p.get(k)) for p in requests}) <= 1
107
+ for k in ["reasoning", "instructions", "tools"]}
108
+ signed_before = [i for i in requests[0]["input"] if i.get("type") == "reasoning"] if requests else []
109
+ return {"name": name, "provider": provider, "replay": replay, "completed": result.get("completed"),
110
+ "requests": len(requests), "reasoning_counts": reasoning_counts,
111
+ "stable_retry_fields": stable, "reasoning_parameters": [p.get("reasoning") for p in requests],
112
+ "tool_count": len(requests[0].get("tools", [])) if requests else 0,
113
+ "signed_payload_unchanged": [i.get("encrypted_content") for i in signed_before] == ([ITEM["encrypted_content"]] if replay else []),
114
+ "replay_enabled_after": agent._codex_reasoning_replay_enabled,
115
+ "canonical_replay_after": any(m.get("codex_reasoning_items") for m in result["messages"])}
116
+ finally:
117
+ agent.close()
118
+ server.shutdown()
119
+ server.server_close()
120
+ thread.join()
121
+
122
+
123
+ def main():
124
+ print(json.dumps({"run_agent": run_agent.__file__, "classifier": error_classifier.__file__,
125
+ "home": os.environ["HERMES_HOME"]}))
126
+ results = [scenario("success"), scenario("masked_replay"), scenario("explicit_encrypted"),
127
+ scenario("unrelated_block"), scenario("unrelated_block", replay=False),
128
+ scenario("masked_replay", provider="custom"), scenario("failed_frame"), scenario("failed_frame", replay=False)]
129
+ e = APIError("Request blocked.", request=httpx.Request("POST", "http://127.0.0.1"), body=ERROR)
130
+ output = {"surface": "real AIAgent and SDK against synthetic local HTTP/SSE server; not provider proof",
131
+ "statusless_reason": error_classifier.classify_api_error(e, provider="openai-codex").reason.value,
132
+ "scenarios": results}
133
+ Path(sys.argv[1]).write_text(json.dumps(output, indent=2) + "\n", encoding="utf-8")
134
+ print(json.dumps(output, indent=2))
135
+
136
+
137
+ if __name__ == "__main__":
138
+ main()
evals/completion_backlog_probe.py ADDED
@@ -0,0 +1,195 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Local I/O probe for completion batching, not a hosted-model or native UI test.
2
+
3
+ Run with the repo's Python: evals/completion_backlog_probe.py REPO OUTPUT.json.
4
+ Real shell children feed ProcessRegistry; production CLI/poller/post-turn routing
5
+ feeds a loopback HTTP turn sink. The sink replaces chat/_run_prompt_submit, NOT
6
+ ownership, consumption, queue draining, batching, or formatting.
7
+ """
8
+ import argparse
9
+ import contextlib
10
+ import json
11
+ import os
12
+ from pathlib import Path
13
+ import queue
14
+ import shlex
15
+ import sys
16
+ import tempfile
17
+ import threading
18
+ import time
19
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
20
+ from types import SimpleNamespace
21
+ from unittest.mock import patch
22
+ from urllib.request import Request, urlopen
23
+
24
+
25
+ def probe(surface, scenario, directory):
26
+ from cli import HermesCLI
27
+ from tools import process_registry as pr
28
+ from tools.process_registry_notifications import format_process_notification
29
+ from tui_gateway import server
30
+
31
+ directory = Path(directory)
32
+ directory.mkdir(parents=True, exist_ok=True)
33
+ registry = pr.ProcessRegistry()
34
+ received, statuses = [], []
35
+
36
+ class Sink(BaseHTTPRequestHandler):
37
+ def do_POST(self):
38
+ received.append(json.loads(self.rfile.read(int(self.headers['Content-Length']))))
39
+ self.send_response(200)
40
+ self.end_headers()
41
+ self.wfile.write(b'{"accepted":true}')
42
+
43
+ def log_message(self, *_args):
44
+ return
45
+
46
+ wire = ThreadingHTTPServer(('127.0.0.1', 0), Sink)
47
+ thread = threading.Thread(target=wire.serve_forever, daemon=True)
48
+ thread.start()
49
+ session = {'session_key': 'backlog-owner', 'history_lock': threading.RLock()}
50
+ cli = HermesCLI.__new__(HermesCLI)
51
+ cli.session_id = session['session_key']
52
+ cli._session_db = None
53
+ cli._pending_input = queue.Queue()
54
+ cli._pending_resume_sessions = []
55
+ cli._typed_voice_stop = lambda _text: False
56
+ cli.handle_bang_shell = lambda _text: False
57
+ cli._print_user_message_preview = lambda _text: None
58
+ cli._turn_summary_begin = lambda: None
59
+ cli._app = SimpleNamespace(invalidate=lambda: None)
60
+ cli._tui_after_turn = lambda: None
61
+
62
+ def submit(text):
63
+ request = Request(f'http://127.0.0.1:{wire.server_port}/turn',
64
+ data=json.dumps({'text': str(text)}).encode(),
65
+ headers={'Content-Type': 'application/json'})
66
+ with urlopen(request, timeout=10) as response:
67
+ assert response.status == 200
68
+ session['running'] = False
69
+ return True
70
+
71
+ def tui_submit(_rid, _sid, _session, text, **_kwargs):
72
+ return submit(text)
73
+
74
+ cli.chat = lambda text, **_kwargs: submit(text)
75
+ processes = []
76
+ try:
77
+ with contextlib.ExitStack() as stack:
78
+ stack.enter_context(patch.object(pr, 'process_registry', registry))
79
+ stack.enter_context(patch.object(pr, 'CHECKPOINT_PATH', directory / 'processes.json'))
80
+ stack.enter_context(patch.object(server, '_sessions', {'ui-owner': session}))
81
+ stack.enter_context(patch.object(server, '_get_db', lambda: None))
82
+ stack.enter_context(patch.object(server, '_emit', lambda *args: statuses.append(args)))
83
+ stack.enter_context(patch.object(server, '_run_prompt_submit', tui_submit))
84
+ stack.enter_context(patch.object(server, '_drain_queued_prompt', lambda *_a: False))
85
+ count = 1 if scenario == 'single' else 12
86
+ gate = directory / 'release'
87
+ for index in range(count):
88
+ code = ('import pathlib,time,sys; p=pathlib.Path(sys.argv[1]); '
89
+ '\nwhile not p.exists(): time.sleep(.01)\n'
90
+ f'print("BACKLOG_{index}"); sys.exit({7 if index == count - 1 else 0})')
91
+ process = registry.spawn_local(
92
+ f'{shlex.quote(sys.executable)} -c {shlex.quote(code)} {shlex.quote(str(gate))}',
93
+ cwd=str(directory), session_key='backlog-owner')
94
+ process.notify_on_complete = True
95
+ processes.append(process)
96
+ gate.touch()
97
+ deadline = time.monotonic() + 30
98
+ while registry.completion_queue.qsize() < count and time.monotonic() < deadline:
99
+ time.sleep(.01)
100
+ assert registry.completion_queue.qsize() == count
101
+ raw = list(registry.completion_queue.queue)
102
+ delegation = None
103
+ if scenario == 'mixed':
104
+ from tools import async_delegation as ad
105
+ delegation = {'type': 'async_delegation', 'delegation_id': f'deleg-{surface}',
106
+ 'session_key': 'backlog-owner', 'goal': 'Fixture delegation',
107
+ 'status': 'completed', 'summary': 'DELEGATION_RESULT',
108
+ 'dispatched_at': time.time(), 'completed_at': time.time()}
109
+ ad._persist_dispatch(delegation)
110
+ ad._persist_completion(delegation, {'status': 'completed'})
111
+ watch = {'type': 'watch_match', 'session_key': 'backlog-owner',
112
+ 'session_id': processes[0].id, 'pattern': 'READY', 'output': 'WATCH_READY'}
113
+ while not registry.completion_queue.empty():
114
+ registry.completion_queue.get_nowait()
115
+ raw = raw[:4] + [watch] + raw[4:8] + [delegation] + raw[8:]
116
+ for event in raw:
117
+ registry.completion_queue.put(event)
118
+ expected = [format_process_notification(event) for event in raw]
119
+ if scenario == 'foreign':
120
+ session['session_key'] = cli.session_id = 'another-owner'
121
+ server._sessions['actual-owner'] = {'session_key': 'backlog-owner'}
122
+ if surface == 'cli':
123
+ cli._drain_process_notifications('cli-idle')
124
+ if scenario == 'consumed':
125
+ for process in processes:
126
+ assert registry.wait(process.id, timeout=1)["status"] == "exited"
127
+ while not cli._pending_input.empty():
128
+ cli._tui_process_one_input(cli._pending_input.get_nowait())
129
+ elif surface == 'post-turn':
130
+ if scenario == 'consumed':
131
+ for process in processes:
132
+ assert registry.wait(process.id, timeout=1)["status"] == "exited"
133
+ server._run_post_turn_followups('probe', 'ui-owner', session, {}, None)
134
+ else:
135
+ if scenario == 'consumed':
136
+ for process in processes:
137
+ assert registry.wait(process.id, timeout=1)["status"] == "exited"
138
+ stop = threading.Event()
139
+ # Skip unrelated scheduled jobs; exercise the production poller loop.
140
+ stack.enter_context(patch.object(server, '_maybe_fire_tui_loop_tick', lambda *_a: None))
141
+ stack.enter_context(patch.object(server, '_maybe_fire_tui_heartbeat_tick', lambda *_a: None))
142
+ stack.enter_context(patch.object(server, '_notif_poll_kanban', lambda *_a: None))
143
+ poller = threading.Thread(target=server._notification_poller_loop,
144
+ args=(stop, 'ui-owner', session))
145
+ poller.start()
146
+ deadline = time.monotonic() + (1 if scenario == 'foreign' else 10)
147
+ while time.monotonic() < deadline:
148
+ if scenario != 'foreign' and registry.completion_queue.empty():
149
+ break
150
+ time.sleep(.01)
151
+ stop.set()
152
+ poller.join(10)
153
+ assert not poller.is_alive()
154
+ texts = [item['text'] for item in received]
155
+ delegation_delivered = None
156
+ if delegation:
157
+ with ad._transaction() as conn:
158
+ row = conn.execute("SELECT delivery_state, delivery_attempts FROM async_delegations WHERE delegation_id=?",
159
+ (delegation['delegation_id'],)).fetchone()
160
+ delegation_delivered = tuple(row) == ('delivered', 1)
161
+ return {'surface': surface, 'scenario': scenario, 'children': count,
162
+ 'wire_turns': len(texts), 'texts': texts,
163
+ 'delegation_delivered_once': delegation_delivered,
164
+ 'payload_order': [next((i for i, turn in enumerate(texts) if payload in turn), -1) for payload in expected],
165
+ 'all_payloads_preserved': all(any(text in turn for turn in texts) for text in expected),
166
+ 'single_exact': texts == expected if count == 1 else None,
167
+ 'queue_remaining': registry.completion_queue.qsize(),
168
+ 'status_events': len(statuses)}
169
+ finally:
170
+ wire.shutdown()
171
+ wire.server_close()
172
+ thread.join()
173
+ for process in processes:
174
+ if not process.exited:
175
+ registry.kill_process(process.id)
176
+
177
+
178
+ def main():
179
+ parser = argparse.ArgumentParser()
180
+ parser.add_argument('repo')
181
+ parser.add_argument('output')
182
+ args = parser.parse_args()
183
+ sys.path.insert(0, args.repo)
184
+ with tempfile.TemporaryDirectory(prefix='completion-probe-') as home:
185
+ os.environ['HERMES_HOME'] = home
186
+ os.environ['HOME'] = home
187
+ results = [probe(surface, scenario, Path(home) / surface / scenario)
188
+ for surface in ('cli', 'poller', 'post-turn')
189
+ for scenario in ('backlog', 'single', 'consumed', 'foreign', 'mixed')]
190
+ Path(args.output).write_text(json.dumps(results, indent=2), encoding="utf-8")
191
+ print(json.dumps([{k: v for k, v in row.items() if k != 'texts'} for row in results], indent=2))
192
+
193
+
194
+ if __name__ == '__main__':
195
+ main()
evals/cron_error_diagnostics.py ADDED
@@ -0,0 +1,85 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Local-I/O A/B for #104538; no inference, external APIs, or deliveries.
2
+
3
+ Run with the project Python and pass a checkout to probe (defaults to this tree).
4
+ Exit 1 on the unfixed checkout: the persisted traceback and listed reason are absent.
5
+ The injected provider-setup seam performs a real SDK connection to a non-listening
6
+ loopback socket; this does not diagnose the original macOS/Gmail incident.
7
+ """
8
+
9
+ import contextlib
10
+ import io
11
+ import json
12
+ import os
13
+ from pathlib import Path
14
+ import socket
15
+ import sys
16
+ import tempfile
17
+ from unittest.mock import patch
18
+
19
+
20
+ def main():
21
+ checkout = Path(sys.argv[1]).resolve() if len(sys.argv) > 1 else Path(__file__).resolve().parents[1]
22
+ for key in list(os.environ):
23
+ if key.startswith(("HERMES_", "OPENAI_", "OPENROUTER_", "ANTHROPIC_")) or any(
24
+ part in key for part in ("API_KEY", "TOKEN", "SECRET", "PASSWORD")
25
+ ):
26
+ os.environ.pop(key, None)
27
+ with tempfile.TemporaryDirectory(prefix="cron-diagnostics-") as home:
28
+ os.environ.update(HOME=home, HERMES_HOME=home)
29
+ sys.path.insert(0, str(checkout))
30
+ from cron import jobs, scheduler
31
+ from hermes_cli.cli_commands_mixin import CLICommandsMixin
32
+ from openai import OpenAI
33
+ from tools.cronjob_job_args import _format_job
34
+
35
+ with socket.socket() as held:
36
+ held.bind(("127.0.0.1", 0))
37
+ port = held.getsockname()[1]
38
+
39
+ def connection_failure(*args):
40
+ with OpenAI(api_key="local-probe", base_url=f"http://127.0.0.1:{port}/v1", max_retries=0, timeout=1) as client:
41
+ try:
42
+ client.chat.completions.create(model="local-probe", messages=[{"role": "user", "content": "probe"}])
43
+ except Exception as exc:
44
+ raise RuntimeError("Connection error.") from exc
45
+
46
+ job = jobs.create_job(prompt="Check status", schedule="every 1h", model="local-probe", deliver="local")
47
+ with patch.object(scheduler, "_resolve_cron_agent_setup", connection_failure):
48
+ success, output, response, error = scheduler.run_job(job)
49
+ path = jobs.save_job_output(job["id"], output)
50
+ saved = path.read_text(encoding="utf-8")
51
+ jobs.mark_job_run(job["id"], success, error=error)
52
+ formatted = _format_job(jobs.get_job(job["id"]))
53
+ console = io.StringIO()
54
+ with contextlib.redirect_stdout(console):
55
+ CLICommandsMixin._cron_list(object(), "list", {"all": False})
56
+ checks = {
57
+ "persisted_traceback": "Traceback (most recent call last)" in saved,
58
+ "persisted_connection_cause": "Connection refused" in saved,
59
+ "listed_run_reason": formatted.get("last_error") == error,
60
+ "slash_list_reason": f"error: {error}" in console.getvalue(),
61
+ "concise_return": not success and not response and error == "RuntimeError: Connection error.",
62
+ "separate_failure_fields": formatted["last_delivery_error"] is None and formatted["last_fire_error"] is None,
63
+ "private_output": os.name == "nt" or path.stat().st_mode & 0o077 == 0,
64
+ }
65
+ script = Path(home) / "scripts" / "healthy.py"
66
+ script.parent.mkdir(parents=True, exist_ok=True)
67
+ script.write_text("print('healthy local control')\n", encoding="utf-8")
68
+ healthy = jobs.create_job(prompt="Local control", schedule="every 1h", script=str(script), no_agent=True, deliver="local")
69
+ ok, _, final, healthy_error = scheduler.run_job(healthy)
70
+ checks["healthy_run"] = ok and "healthy local control" in final and healthy_error is None
71
+ secret_error = "RuntimeError: https://user:password@localhost/api?token=secret-token"
72
+ jobs.mark_job_run(job["id"], False, error=secret_error)
73
+ secret_listing = _format_job(jobs.get_job(job["id"]))
74
+ visible = secret_listing.get("last_error") or ""
75
+ checks["listed_credentials_redacted"] = (
76
+ "localhost" in visible and "password" not in visible and "secret-token" not in visible
77
+ )
78
+ jobs.mark_job_run(job["id"], True)
79
+ checks["success_clears_error"] = jobs.get_job(job["id"])["last_error"] is None
80
+ print(json.dumps({"checkout": str(checkout), "checks": checks}, indent=2))
81
+ assert all(checks.values()), checks
82
+
83
+
84
+ if __name__ == "__main__":
85
+ main()
evals/cron_timeout_fork_race.py ADDED
@@ -0,0 +1,93 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Linux live cron race probe: real PID map, synchronized fork, owned-only cleanup.
2
+
3
+ Run with the repository's Python and a disposable HERMES_HOME. No provider calls.
4
+ The scheduling hook retains psutil's real snapshot; it never invents process state.
5
+ """
6
+ import ctypes
7
+ import json
8
+ import os
9
+ from pathlib import Path
10
+ import sys
11
+ import tempfile
12
+ import time
13
+
14
+
15
+ def main():
16
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
17
+ import psutil
18
+
19
+ # Confine adoption to this disposable probe, not the test runner or gateway.
20
+ if ctypes.CDLL(None, use_errno=True).prctl(36, 1, 0, 0, 0) != 0:
21
+ raise OSError(ctypes.get_errno(), "PR_SET_CHILD_SUBREAPER")
22
+ with tempfile.TemporaryDirectory(prefix="cron-owned-fork-") as root:
23
+ os.environ["HERMES_HOME"] = root
24
+ os.environ["HERMES_CRON_SCRIPT_TIMEOUT"] = "2"
25
+ from cron.scheduler_script import _run_job_script
26
+
27
+ scripts = Path(root, "scripts")
28
+ scripts.mkdir()
29
+ release, marker = Path(root, "release"), Path(root, "pids.json")
30
+ script = scripts / "spawner.py"
31
+ script.write_text(
32
+ "import subprocess,sys,time,os,json\nfrom pathlib import Path\n"
33
+ "def spawn():\n"
34
+ " return subprocess.Popen([sys.executable,'-c','import time;time.sleep(15)'],"
35
+ "start_new_session=True,stdin=subprocess.DEVNULL,stdout=subprocess.DEVNULL,stderr=subprocess.DEVNULL)\n"
36
+ "first=spawn()\n"
37
+ f"Path({str(marker)!r}).write_text(json.dumps([os.getpid(),first.pid]))\n"
38
+ f"while not Path({str(release)!r}).exists():time.sleep(0.001)\n"
39
+ "late=spawn()\n"
40
+ f"Path({str(marker)!r}).write_text(json.dumps([os.getpid(),first.pid,late.pid]))\n"
41
+ "time.sleep(15)\n",
42
+ encoding="utf-8",
43
+ )
44
+ original = psutil._ppid_map
45
+ schedules = []
46
+
47
+ def scheduling_map():
48
+ mapping = original()
49
+ release.touch()
50
+ deadline = time.monotonic() + 2
51
+ while time.monotonic() < deadline:
52
+ try:
53
+ ids = json.loads(marker.read_text(encoding="utf-8"))
54
+ if len(ids) == 3 or psutil.Process(ids[0]).status() == psutil.STATUS_STOPPED:
55
+ break
56
+ except (FileNotFoundError, ValueError, psutil.NoSuchProcess):
57
+ pass
58
+ time.sleep(0.001)
59
+ schedules.append(len(mapping))
60
+ return mapping
61
+
62
+ psutil._ppid_map = scheduling_map
63
+ try:
64
+ start = time.monotonic()
65
+ result = _run_job_script(str(script), workdir=root)
66
+ elapsed = time.monotonic() - start
67
+ finally:
68
+ psutil._ppid_map = original
69
+ states = {}
70
+ owned = psutil.Process().children(recursive=True)
71
+ try:
72
+ ids = json.loads(marker.read_text(encoding="utf-8"))
73
+ for pid in ids:
74
+ try:
75
+ states[pid] = psutil.Process(pid).status()
76
+ except psutil.NoSuchProcess:
77
+ states[pid] = "gone"
78
+ print(json.dumps({"result": result, "elapsed": elapsed, "states": states,
79
+ "real_snapshot_sizes": schedules}), flush=True)
80
+ assert result[1].startswith("Script timed out after 2s:"), result
81
+ assert len(ids) >= 2, "pre-existing detached child did not start"
82
+ assert all(state in ("gone", psutil.STATUS_ZOMBIE) for state in states.values()), states
83
+ finally:
84
+ for process in owned:
85
+ try:
86
+ process.kill()
87
+ process.wait(timeout=5)
88
+ except psutil.NoSuchProcess:
89
+ pass
90
+
91
+
92
+ if __name__ == "__main__":
93
+ main()
evals/delivery_flood_wire.py ADDED
@@ -0,0 +1,201 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Local-wire delivery ledger A/B, not a real Telegram bot or model run.
2
+
3
+ Run: python evals/delivery_flood_wire.py OUTPUT_DIR
4
+ Uses the real Telegram SDK, adapter final-send path, runner and SQLite stores.
5
+ Only the Telegram HTTP endpoint is replaced; waits and process ownership are real.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import asyncio
10
+ import json
11
+ import math
12
+ import os
13
+ from pathlib import Path
14
+ import sqlite3
15
+ import subprocess
16
+ import sys
17
+ import threading
18
+ import time
19
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
20
+ from urllib.parse import parse_qs
21
+
22
+ ROOT = Path(__file__).resolve().parents[1]
23
+ sys.path.insert(0, str(ROOT))
24
+
25
+
26
+ class Wire:
27
+ def __init__(self):
28
+ self.calls = []
29
+ self.deadlines = {}
30
+ wire = self
31
+
32
+ class Handler(BaseHTTPRequestHandler):
33
+ def log_message(self, *args):
34
+ pass
35
+
36
+ def do_POST(self):
37
+ raw = self.rfile.read(int(self.headers.get('Content-Length', 0)))
38
+ data = {k: v[0] for k, v in parse_qs(raw.decode()).items()}
39
+ method = self.path.rsplit('/', 1)[-1].lower()
40
+ status = 200
41
+ result = True
42
+ if method == 'getme':
43
+ result = {'id': 123456, 'is_bot': True, 'first_name': 'Fixture', 'username': 'fixture_bot'}
44
+ elif method == 'sendmessage':
45
+ now = time.time()
46
+ chat = data['chat_id']
47
+ if chat in {'101', '201'} and chat not in wire.deadlines:
48
+ wire.deadlines[chat] = now + 61
49
+ if chat in wire.deadlines and now < wire.deadlines[chat]:
50
+ status = 429
51
+ result = {'ok': False, 'error_code': 429, 'description': 'Too Many Requests',
52
+ 'parameters': {'retry_after': math.ceil(wire.deadlines[chat] - now)}}
53
+ elif chat == '403':
54
+ status = 403
55
+ result = {'ok': False, 'error_code': 403, 'description': 'Forbidden: bot was blocked by the user'}
56
+ else:
57
+ result = {'message_id': len(wire.calls) + 1, 'date': int(now),
58
+ 'chat': {'id': int(chat), 'type': 'private'}, 'text': data.get('text', '')}
59
+ wire.calls.append({'at': now, 'method': method, 'status': status, **data})
60
+ body = json.dumps(result if status != 200 else {'ok': True, 'result': result}).encode()
61
+ self.send_response(status)
62
+ self.send_header('Content-Type', 'application/json')
63
+ self.send_header('Content-Length', str(len(body)))
64
+ self.end_headers()
65
+ self.wfile.write(body)
66
+
67
+ self.server = ThreadingHTTPServer(('127.0.0.1', 0), Handler)
68
+ self.thread = threading.Thread(target=self.server.serve_forever, daemon=True)
69
+ self.thread.start()
70
+ self.url = f'http://127.0.0.1:{self.server.server_port}/bot'
71
+
72
+ def close(self):
73
+ self.server.shutdown()
74
+ self.server.server_close()
75
+ self.thread.join()
76
+
77
+
78
+ async def setup(url):
79
+ from gateway.config import GatewayConfig, Platform, PlatformConfig
80
+ from gateway.run import GatewayRunner
81
+ from gateway.session import SessionStore
82
+ from plugins.platforms.telegram.adapter import TelegramAdapter
83
+ from telegram import Bot
84
+ runner = object.__new__(GatewayRunner)
85
+ runner.session_store = SessionStore(Path(os.environ['HERMES_HOME']) / 'sessions', GatewayConfig())
86
+ runner._profile_adapters = {}
87
+ runner._running = True
88
+ adapter = TelegramAdapter(PlatformConfig(enabled=True, token='123456:fixture', extra={}))
89
+ adapter._bot = Bot('123456:fixture', base_url=url)
90
+ await adapter._bot.initialize()
91
+ runner.adapters = {Platform.TELEGRAM: adapter}
92
+ adapter.gateway_runner = runner
93
+ return runner, adapter
94
+
95
+
96
+ async def produce(runner, adapter, chat):
97
+ from gateway.config import Platform
98
+ from gateway.platforms.event import MessageEvent
99
+ from gateway.session import SessionSource
100
+ source = SessionSource(platform=Platform.TELEGRAM, chat_id=chat, thread_id='77')
101
+ entry = await runner.async_session_store.get_or_create_session(source)
102
+ await runner.async_session_store.mark_resume_pending(entry.session_key)
103
+ event = MessageEvent(text='deliver a final answer', source=source, message_id='10')
104
+ results = []
105
+ await adapter._send_final_text(event, entry.session_key, 'LEDGER_' + chat, {'thread_id': '77'},
106
+ False, 0, results.append)
107
+ return entry.session_key
108
+
109
+
110
+ def rows():
111
+ with sqlite3.connect(Path(os.environ['HERMES_HOME']) / 'state.db') as conn:
112
+ conn.row_factory = sqlite3.Row
113
+ return [dict(row) for row in conn.execute('SELECT * FROM delivery_obligations ORDER BY chat_id')]
114
+
115
+
116
+ async def cleanup(runner, adapter):
117
+ runner._running = False
118
+ tasks = list(getattr(runner, '_flood_redelivery_tasks', {}).values())
119
+ for task in tasks:
120
+ task.cancel()
121
+ await asyncio.gather(*tasks, return_exceptions=True)
122
+ await adapter._bot.shutdown()
123
+
124
+
125
+ async def scenario(wire, mode):
126
+ from gateway import delivery_ledger as dl
127
+ from gateway.config import Platform
128
+ runner, adapter = await setup(wire.url)
129
+ try:
130
+ if mode == 'runtime':
131
+ key = await produce(runner, adapter, '101')
132
+ await produce(runner, adapter, '102')
133
+ # A foreign bot's row cannot be claimed by the connected default bot.
134
+ dl.record_obligation(obligation_id='foreign', session_key=key, platform='telegram',
135
+ chat_id='999', thread_id='77', content='FOREIGN', adapter_profile='other')
136
+ dl.mark_failed('foreign', 'flood_control:0.01')
137
+ dl.record_obligation(obligation_id='permanent', session_key=key, platform='telegram',
138
+ chat_id='403', thread_id='77', content='PERMANENT')
139
+ dl.mark_failed('permanent', 'Forbidden: bot was blocked by the user')
140
+ await runner._redeliver_failed_obligations_for_platform(Platform.TELEGRAM)
141
+ else:
142
+ # Real child owns the failed row and exits; no patched liveness predicate.
143
+ proc = await asyncio.to_thread(subprocess.run,
144
+ [sys.executable, str(Path(__file__).resolve()), '--produce', wire.url],
145
+ env=os.environ.copy(), cwd=str(ROOT), stdin=subprocess.DEVNULL,
146
+ capture_output=True, text=True, encoding='utf-8', errors='replace', timeout=20)
147
+ if proc.returncode:
148
+ raise RuntimeError(proc.stderr)
149
+ key = json.loads(proc.stdout)['key']
150
+ await runner._redeliver_pending_obligations()
151
+ early = rows()
152
+ early_calls = list(wire.calls)
153
+ await asyncio.sleep(64)
154
+ after = rows()
155
+ # Explicit repeated sweeps cannot resend a confirmed delivery.
156
+ await runner._redeliver_failed_obligations_for_platform(Platform.TELEGRAM)
157
+ await runner._redeliver_failed_obligations_for_platform(Platform.TELEGRAM)
158
+ final = rows()
159
+ entry = await runner.async_session_store.get_or_create_session(
160
+ __import__('gateway.session', fromlist=['SessionSource']).SessionSource(
161
+ platform=Platform.TELEGRAM, chat_id='101' if mode == 'runtime' else '201', thread_id='77'))
162
+ return {'mode': mode, 'early': early, 'early_wire': early_calls, 'after_timer': after,
163
+ 'final': final, 'wire': list(wire.calls), 'resume_pending': entry.resume_pending,
164
+ 'deadlines': dict(wire.deadlines)}
165
+ finally:
166
+ await cleanup(runner, adapter)
167
+
168
+
169
+ async def run_mode(output, mode):
170
+ home = output / mode
171
+ home.mkdir(parents=True, exist_ok=True)
172
+ os.environ['HERMES_HOME'] = str(home)
173
+ (home / 'config.yaml').write_text('gateway:\n delivery_ledger: true\n')
174
+ wire = Wire()
175
+ try:
176
+ result = await scenario(wire, mode)
177
+ (output / f'{mode}.json').write_text(json.dumps(result, indent=2))
178
+ return result
179
+ finally:
180
+ wire.close()
181
+
182
+
183
+ async def main():
184
+ if sys.argv[1] == '--produce':
185
+ runner, adapter = await setup(sys.argv[2])
186
+ try:
187
+ key = await produce(runner, adapter, '201')
188
+ print(json.dumps({'key': key}))
189
+ finally:
190
+ await cleanup(runner, adapter)
191
+ return
192
+ output = Path(sys.argv[1]).resolve()
193
+ output.mkdir(parents=True, exist_ok=True)
194
+ for mode in ('runtime', 'boot'):
195
+ result = await run_mode(output, mode)
196
+ print(json.dumps({'mode': mode, 'states': [(r['chat_id'], r['state'], r['attempts']) for r in result['final']],
197
+ 'wire_requests': len(result['wire']), 'resume_pending': result['resume_pending']}))
198
+
199
+
200
+ if __name__ == '__main__':
201
+ asyncio.run(main())
evals/desktop-reap-clock-pressure.cjs ADDED
@@ -0,0 +1,12 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ // Replay scheduling pressure without changing Date.now() results:
2
+ // NODE_OPTIONS="--require=$PWD/evals/desktop-reap-clock-pressure.cjs" \
3
+ // npm run test:desktop:platforms -w apps/desktop -- electron/backend-ownership.test.ts
4
+ // The old 1ms fixtures can expire before their first record is processed.
5
+ const now = Date.now.bind(Date)
6
+ const gate = new Int32Array(new SharedArrayBuffer(4))
7
+ Date.now = function () {
8
+ if (new Error().stack.includes('/electron/backend-ownership.ts:')) {
9
+ Atomics.wait(gate, 0, 0, 5)
10
+ }
11
+ return now()
12
+ }
evals/fanout_resource_bench.py ADDED
@@ -0,0 +1,232 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Fan-out resource benchmark for hermes-agent.
3
+
4
+ Spawns N in-process child AIAgents via the REAL delegate_task code path
5
+ (tools.delegate_tool.delegate_task) against a local fake OpenAI server, with
6
+ children editing python files across W distinct git worktrees so the LSP
7
+ (pyright) path is exercised for real. Measures, for the host process:
8
+
9
+ threads, RSS MB, open fds, TCP ESTAB sockets, child processes (pyright,
10
+ kernels), state.db growth, wall time.
11
+
12
+ Usage:
13
+ python evals/fanout_resource_bench.py --repo <checkout> --children 24 --worktrees 6 --label before
14
+
15
+ Prints one JSON line; append several and compare with --compare a.json b.json.
16
+ """
17
+ from __future__ import annotations
18
+
19
+ import argparse
20
+ import http.server
21
+ import json
22
+ import os
23
+ import shutil
24
+ import socket
25
+ import subprocess
26
+ import sys
27
+ import tempfile
28
+ import threading
29
+ import time
30
+
31
+ # --------------------------------------------------------------------------
32
+ # Fake OpenAI chat-completions server: each child does
33
+ # turn 1: call write_file on <its worktree>/hermes_cli/bench_<i>.py
34
+ # turn 2: call execute_code print(1)
35
+ # turn 3: final text
36
+ # --------------------------------------------------------------------------
37
+ _REPLY_KB = [0]
38
+
39
+
40
+ class _Fake(http.server.BaseHTTPRequestHandler):
41
+ def log_message(self, format, *args): # quiet
42
+ pass
43
+
44
+ def do_POST(self):
45
+ n = int(self.headers.get("Content-Length", 0))
46
+ body = json.loads(self.rfile.read(n) or b"{}")
47
+ msgs = body.get("messages", [])
48
+ goal = next((m["content"] for m in msgs if m.get("role") == "user"), "")
49
+ try:
50
+ plan = json.loads(goal)
51
+ except Exception:
52
+ plan = {}
53
+ n_tool = sum(1 for m in msgs if m.get("role") == "tool")
54
+ if n_tool == 0 and plan.get("file"):
55
+ tc = {"id": "c1", "type": "function", "function": {"name": "write_file", "arguments": json.dumps({"path": plan["file"], "content": "import os\nx: int = 'bad'\n"})}}
56
+ msg = {"role": "assistant", "content": None, "tool_calls": [tc]}
57
+ finish = "tool_calls"
58
+ elif n_tool == 1 and plan.get("file"):
59
+ tc = {"id": "c2", "type": "function", "function": {"name": "execute_code", "arguments": json.dumps({"code": "print(1)"})}}
60
+ msg = {"role": "assistant", "content": None, "tool_calls": [tc]}
61
+ finish = "tool_calls"
62
+ else:
63
+ msg = {"role": "assistant", "content": "done " + ("x" * (_REPLY_KB[0] * 1024))}
64
+ finish = "stop"
65
+ if body.get("stream") is True:
66
+ self.send_response(200)
67
+ self.send_header("Content-Type", "text/event-stream")
68
+ self.end_headers()
69
+ delta = {"role": "assistant", "content": msg.get("content") or ""}
70
+ if msg.get("tool_calls"):
71
+ tc = msg["tool_calls"][0]
72
+ delta["tool_calls"] = [{"index": 0, "id": tc["id"], "type": "function", "function": tc["function"]}]
73
+ for chunk in (
74
+ {"id": "m", "object": "chat.completion.chunk", "choices": [{"index": 0, "delta": delta, "finish_reason": None}]},
75
+ {"id": "m", "object": "chat.completion.chunk", "choices": [{"index": 0, "delta": {}, "finish_reason": finish}],
76
+ "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}},
77
+ ):
78
+ self.wfile.write(f"data: {json.dumps(chunk)}\n\n".encode())
79
+ self.wfile.write(b"data: [DONE]\n\n")
80
+ self.wfile.flush()
81
+ return
82
+ resp = {"id": "x", "object": "chat.completion", "created": 0, "model": body.get("model", "m"),
83
+ "choices": [{"index": 0, "message": msg, "finish_reason": finish}],
84
+ "usage": {"prompt_tokens": 10, "completion_tokens": 5, "total_tokens": 15}}
85
+ data = json.dumps(resp).encode()
86
+ self.send_response(200)
87
+ self.send_header("Content-Type", "application/json")
88
+ self.send_header("Content-Length", str(len(data)))
89
+ self.end_headers()
90
+ self.wfile.write(data)
91
+
92
+
93
+ def _serve():
94
+ srv = http.server.ThreadingHTTPServer(("127.0.0.1", 0), _Fake)
95
+ threading.Thread(target=srv.serve_forever, daemon=True).start()
96
+ return srv
97
+
98
+
99
+ def _count_live(cls_name: str) -> int:
100
+ import gc
101
+ return sum(1 for o in gc.get_objects() if type(o).__name__ == cls_name)
102
+
103
+
104
+ def _snap(pid: int, db_path: str) -> dict:
105
+ st = open(f"/proc/{pid}/status", encoding="utf-8").read()
106
+ g = lambda k: int(st.split(k + ":")[1].split()[0])
107
+ tcp = subprocess.run(f"ss -tanp 2>/dev/null | grep -c 'pid={pid},'", shell=True, capture_output=True, text=True).stdout.strip()
108
+ kids = subprocess.run(["ps", "-o", "args=", "--ppid", str(pid)], capture_output=True, text=True).stdout
109
+ return {
110
+ "threads": g("Threads"), "rss_mb": g("VmRSS") // 1024, "fds": len(os.listdir(f"/proc/{pid}/fd")),
111
+ "tcp": int(tcp or 0), "pyright": kids.count("pyright"), "kernels": kids.count("hermes_kernel_runner"),
112
+ "db_mb": round(os.path.getsize(db_path) / 2**20, 1) if os.path.exists(db_path) else 0,
113
+ "httpx_clients": _count_live("Client"), "transports": _count_live("HTTPTransport"), "session_dbs": _count_live("SessionDB"), "live_agents": _count_live("AIAgent"),
114
+ }
115
+
116
+
117
+ def main() -> None:
118
+ ap = argparse.ArgumentParser()
119
+ ap.add_argument("--repo", required=True)
120
+ ap.add_argument("--children", type=int, default=24)
121
+ ap.add_argument("--worktrees", type=int, default=6)
122
+ ap.add_argument("--label", default="")
123
+ ap.add_argument("--out", default="")
124
+ ap.add_argument("--compare", nargs=2)
125
+ ap.add_argument("--reply-kb", type=int, default=0, help="pad each child's final reply to N KB (transcript-size realism)")
126
+ a = ap.parse_args()
127
+ if a.compare:
128
+ b, c = (json.load(open(p, encoding="utf-8")) for p in a.compare)
129
+ print(f"| metric | {b['label']} | {c['label']} | delta |\n|---|---|---|---|")
130
+ for k in ("threads", "rss_mb", "fds", "tcp", "pyright", "kernels", "db_mb", "httpx_clients", "transports", "session_dbs"):
131
+ bv, cv = b["peak"][k], c["peak"][k]
132
+ print(f"| {k} (peak) | {bv} | {cv} | {cv - bv:+} |")
133
+ for k in ("rss_mb", "live_agents", "db_mb", "threads"):
134
+ bv, cv = b["after"].get(k), c["after"].get(k)
135
+ if bv is not None and cv is not None:
136
+ print(f"| {k} (after, children done) | {bv} | {cv} | {cv - bv:+} |")
137
+ print(f"| wall_s | {b['wall_s']} | {c['wall_s']} | {c['wall_s'] - b['wall_s']:+.1f} |")
138
+ return
139
+
140
+ _REPLY_KB[0] = a.reply_kb
141
+ home = tempfile.mkdtemp(prefix="hermes_bench_home_")
142
+ os.environ["HERMES_HOME"] = home
143
+ os.environ["TERMINAL_ENV"] = "local"
144
+ os.environ.pop("OPENROUTER_API_KEY", None)
145
+ sys.path.insert(0, a.repo)
146
+ os.chdir(a.repo)
147
+ pyright = shutil.which("pyright-langserver", path=os.path.expanduser("~/.hermes/lsp/bin") + os.pathsep + os.environ.get("PATH", ""))
148
+ with open(os.path.join(home, "config.yaml"), "w", encoding="utf-8") as f:
149
+ f.write("lsp:\n enabled: true\n wait_timeout: 5.0\n install_strategy: manual\n")
150
+ if pyright:
151
+ f.write(f" servers:\n pyright:\n command: [{json.dumps(pyright)}, \"--stdio\"]\n")
152
+ f.write("delegation:\n max_concurrent_children: 64\n subagent_auto_approve: true\n")
153
+
154
+ # W git worktrees, each a real python project (pyproject + package) so pyright roots resolve.
155
+ wts = []
156
+ base = tempfile.mkdtemp(prefix="hermes_bench_wt_")
157
+ for w in range(a.worktrees):
158
+ d = os.path.join(base, f"wt{w}")
159
+ os.makedirs(os.path.join(d, "hermes_cli"))
160
+ subprocess.run(["git", "init", "-q", d], check=True)
161
+ open(os.path.join(d, "pyproject.toml"), "w", encoding="utf-8").write("[project]\nname='b'\n")
162
+ open(os.path.join(d, "hermes_cli", "__init__.py"), "w", encoding="utf-8").write("")
163
+ wts.append(d)
164
+
165
+ srv = _serve()
166
+ port = srv.server_address[1]
167
+ from run_agent import AIAgent
168
+ from tools import delegate_tool
169
+
170
+ from hermes_state import SessionDB
171
+ db_path = os.path.join(home, "state.db")
172
+ from pathlib import Path
173
+ session_db = SessionDB(db_path=Path(db_path))
174
+ parent = AIAgent(api_key="bench", base_url=f"http://127.0.0.1:{port}/v1", model="bench-model",
175
+ quiet_mode=True, skip_context_files=True, skip_memory=True,
176
+ enabled_toolsets=["delegation", "file", "code_execution"],
177
+ session_db=session_db, session_id="bench-root")
178
+ # Children reference parent_session_id; the parent row is normally created
179
+ # lazily on the parent's first turn, which this harness never runs.
180
+ parent._ensure_db_session()
181
+ pid = os.getpid()
182
+ before = _snap(pid, db_path)
183
+ peak = dict(before)
184
+ stop = threading.Event()
185
+
186
+ def sampler():
187
+ while not stop.wait(0.5):
188
+ s = _snap(pid, db_path)
189
+ for k, v in s.items():
190
+ peak[k] = max(peak[k], v)
191
+ threading.Thread(target=sampler, daemon=True).start()
192
+
193
+ tasks = [{"goal": json.dumps({"file": os.path.join(wts[i % len(wts)], "hermes_cli", f"bench_{i}.py")}),
194
+ "context": "bench"} for i in range(a.children)]
195
+ t0 = time.monotonic()
196
+ res = delegate_tool.delegate_task(tasks=tasks, parent_agent=parent, background=False)
197
+ wall = round(time.monotonic() - t0, 1)
198
+ if os.environ.get("BENCH_DEBUG"):
199
+ sys.__stderr__.write(str(res)[:3000] + "\n")
200
+ time.sleep(2.0)
201
+ stop.set()
202
+ import gc
203
+ gc.collect()
204
+ after = _snap(pid, db_path)
205
+ try:
206
+ parsed = json.loads(res)
207
+ items = parsed if isinstance(parsed, list) else parsed.get("results") or parsed.get("tasks") or []
208
+ ok = sum(1 for r in items if str(r.get("status", "")) in ("completed", "success"))
209
+ except Exception:
210
+ ok = None
211
+ try:
212
+ session_db.checkpoint() if hasattr(session_db, "checkpoint") else None
213
+ except Exception:
214
+ pass
215
+ out = {"label": a.label, "children": a.children, "worktrees": a.worktrees, "ok": ok, "wall_s": wall,
216
+ "before": before, "peak": peak, "after": after}
217
+ sys.__stderr__.write("BENCH " + json.dumps(out) + "\n"); sys.__stderr__.flush()
218
+ if a.out:
219
+ open(a.out, "w", encoding="utf-8").write(json.dumps(out, indent=1))
220
+ try:
221
+ from agent.lsp import shutdown_service
222
+ shutdown_service()
223
+ from tools.code_kernel import shutdown_all_kernels
224
+ shutdown_all_kernels()
225
+ except Exception:
226
+ pass
227
+ shutil.rmtree(base, ignore_errors=True)
228
+ os._exit(0)
229
+
230
+
231
+ if __name__ == "__main__":
232
+ main()
evals/gemini_type_array_probe.py ADDED
@@ -0,0 +1,120 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Offline A/B native adapter + Google SDK schema validation (no API calls).
2
+
3
+ Run with httpx and google-genai==1.47.0 installed:
4
+ python evals/gemini_type_array_probe.py --base origin/main
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import argparse
9
+ import copy
10
+ import importlib
11
+ import json
12
+ import os
13
+ from pathlib import Path
14
+ import subprocess
15
+ import sys
16
+ import tempfile
17
+ import threading
18
+ import types
19
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
20
+
21
+
22
+ class WireCapture(BaseHTTPRequestHandler):
23
+ requests = []
24
+
25
+ def do_POST(self):
26
+ size = int(self.headers["Content-Length"])
27
+ self.requests.append(json.loads(self.rfile.read(size)))
28
+ # Intentionally stop at the wire boundary; never fake a model response.
29
+ self.send_response(418)
30
+ self.end_headers()
31
+ self.wfile.write(b"Local schema capture only")
32
+
33
+ def log_message(self, *_):
34
+ pass
35
+
36
+
37
+ def wire_translate(adapter, tools):
38
+ server = ThreadingHTTPServer(("127.0.0.1", 0), WireCapture)
39
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
40
+ thread.start()
41
+ try:
42
+ with adapter.GeminiNativeClient(
43
+ api_key="local-probe-not-a-secret",
44
+ base_url=f"http://127.0.0.1:{server.server_port}/v1beta",
45
+ ) as client:
46
+ try:
47
+ client.chat.completions.create(
48
+ model="gemini-2.5-flash", tools=tools,
49
+ messages=[{"role": "user", "content": "Schema validation probe"}],
50
+ )
51
+ except adapter.GeminiAPIError as exc:
52
+ assert exc.status_code == 418
53
+ return WireCapture.requests.pop()["tools"]
54
+ finally:
55
+ server.shutdown()
56
+ server.server_close()
57
+ thread.join()
58
+
59
+
60
+ def probe(label, translate):
61
+ from google.genai.types import FunctionDeclaration
62
+
63
+ cases = {
64
+ "nullable": {"type": ["number", "null"]},
65
+ "nullable_enum": {"type": ["integer", "null"], "enum": [1, 2]},
66
+ "union_enum": {"type": ["string", "integer"], "enum": ["one", 2]},
67
+ "nested_items": {"type": "array", "items": {"type": ["string", "null"]}},
68
+ "nested_anyof": {"anyOf": [{"type": ["string", "integer"]}, {"type": "boolean"}]},
69
+ "constrained_union": {"type": ["string", "integer"], "anyOf": [{"enum": ["one"]}, {"enum": ["two"]}]},
70
+ "structural_union": {"type": ["array", "object", "string"], "items": {"type": "integer"}, "properties": {"name": {"type": "string"}}, "required": ["name"]},
71
+ "scalar_control": {"type": "number"},
72
+ }
73
+ results = {}
74
+ for name, node in cases.items():
75
+ parameters = {"type": "object", "properties": {"value": node}}
76
+ original = copy.deepcopy(parameters)
77
+ try:
78
+ wire = translate([{"type": "function", "function": {"name": "probe", "parameters": parameters}}])
79
+ declaration = wire[0]["functionDeclarations"][0]
80
+ # Validate the actual adapter declaration, not a reconstructed schema.
81
+ FunctionDeclaration.model_validate(json.loads(json.dumps(declaration)))
82
+ results[name] = "accepted"
83
+ except (TypeError, ValueError) as exc:
84
+ results[name] = f"{type(exc).__name__}: {str(exc).splitlines()[0]}"
85
+ assert parameters == original, name
86
+ print(json.dumps({"label": label, "results": results}, indent=2))
87
+ return results
88
+
89
+
90
+ def main():
91
+ parser = argparse.ArgumentParser(description=__doc__)
92
+ parser.add_argument("--base", default="origin/main")
93
+ args = parser.parse_args()
94
+ root = Path(__file__).resolve().parents[1]
95
+ sys.path.insert(0, str(root))
96
+ for name in list(sys.modules):
97
+ if name == "agent" or name.startswith(("agent.", "tools", "hermes")):
98
+ del sys.modules[name]
99
+ with tempfile.TemporaryDirectory(prefix="gemini-schema-home-") as home:
100
+ os.environ["HERMES_HOME"] = home
101
+ adapter = importlib.import_module("agent.gemini_native_adapter")
102
+ baseline = types.ModuleType("baseline_gemini_schema")
103
+ source = subprocess.check_output(
104
+ ["git", "show", f"{args.base}:agent/gemini_schema.py"], cwd=root, text=True,
105
+ )
106
+ exec(compile(source, f"{args.base}:agent/gemini_schema.py", "exec"), baseline.__dict__)
107
+ fixed = adapter.sanitize_gemini_tool_parameters
108
+ adapter.sanitize_gemini_tool_parameters = baseline.sanitize_gemini_tool_parameters
109
+ before = probe(args.base, lambda tools: wire_translate(adapter, tools))
110
+ adapter.sanitize_gemini_tool_parameters = fixed
111
+ after = probe("worktree", lambda tools: wire_translate(adapter, tools))
112
+ assert before["scalar_control"] == "accepted"
113
+ assert all(result != "accepted" for name, result in before.items() if name != "scalar_control")
114
+ assert all(result == "accepted" for result in after.values())
115
+ print(f"PASS: {len(before) - 1} failing base cases repaired; scalar control and inputs preserved.")
116
+ print("LOCAL SDK VALIDATION ONLY: no Google API call or Windows Desktop exercise.")
117
+
118
+
119
+ if __name__ == "__main__":
120
+ main()
evals/goal_command_parity.py ADDED
@@ -0,0 +1,51 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """CLI /goal semantic oracle, with real storage and no model calls.
2
+
3
+ Run against base and candidate in fresh processes with distinct temporary homes:
4
+ python evals/goal_command_parity.py ROOT NEW_HOME OUTPUT_JSON
5
+ Compare state and queued prompts; output includes presentation differences.
6
+ """
7
+ import importlib
8
+ import json
9
+ import os
10
+ from pathlib import Path
11
+ import queue
12
+ import sys
13
+
14
+ root, home, out = map(Path, sys.argv[1:4])
15
+ home.mkdir(parents=True, exist_ok=False)
16
+ os.environ['HERMES_HOME'] = str(home)
17
+ os.environ['HERMES_NIX_BUILD'] = '1'
18
+ sys.path.insert(0, str(root))
19
+ commands = importlib.import_module("hermes_cli.cli_commands_mixin")
20
+ GoalManager = importlib.import_module("hermes_cli.goals").GoalManager
21
+
22
+ manager = GoalManager(session_id='cli-oracle', default_max_turns=17)
23
+ cli = commands.CLICommandsMixin()
24
+ cli._get_goal_manager = lambda: manager
25
+ cli._pending_input = queue.Queue()
26
+ cli.conversation_history = []
27
+ printed = []
28
+ commands._cp = lambda *lines: printed.extend(lines)
29
+ rows = []
30
+ command_args = ['', 'show', 'pause', 'resume', 'clear', 'draft',
31
+ 'Maintain the service\nconstraints: keep data\nstop when: credentials missing',
32
+ 'show', 'pause', 'resume', 'wait nope', 'wait', 'wait 0',
33
+ f'wait {os.getpid()} running probe', 'status', 'unwait', 'unwait',
34
+ 'gate list', 'gate remove nope', 'gate clear', 'done', 'status']
35
+ for arg in command_args:
36
+ printed.clear()
37
+ cli._handle_goal_command('/goal' + (' ' + arg if arg else ''))
38
+ state = manager.state
39
+ prompts = []
40
+ while not cli._pending_input.empty():
41
+ prompts.append(cli._pending_input.get_nowait())
42
+ contract = state.contract if state else None
43
+ rows.append({'command': arg.replace(str(os.getpid()), '<PID>'),
44
+ 'active': manager.has_goal(),
45
+ 'goal': state.goal if state else None,
46
+ 'status': state.status if state else None,
47
+ 'contract': contract.to_dict() if contract else None,
48
+ 'prompt_count': len(prompts), 'prompts': prompts,
49
+ 'output': '\n'.join(printed).replace(str(os.getpid()), '<PID>')})
50
+ out.write_text(json.dumps(rows, indent=2, default=str))
51
+ print(json.dumps(rows, indent=2, default=str))
evals/heartbeat_idle_wire.py ADDED
@@ -0,0 +1,151 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Wire-contract probe: real poller, SQLite, adapter lifecycle; fake model/transport.
2
+
3
+ Run from the repo with a clean environment and a temporary HERMES_HOME:
4
+ .venv/bin/python evals/heartbeat_idle_wire.py
5
+ Pass --base-poller /tmp/run_goals_base.py to compare the old poller. No network.
6
+ """
7
+
8
+ import argparse
9
+ import asyncio
10
+ import json
11
+ import os
12
+ import sys
13
+ from pathlib import Path
14
+ from types import SimpleNamespace
15
+ from unittest.mock import patch
16
+
17
+ sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
18
+
19
+ from gateway.config import GatewayConfig, Platform, PlatformConfig # noqa: E402
20
+ from gateway.platforms.base import BasePlatformAdapter, SendResult # noqa: E402
21
+ from gateway.platforms.event import MessageEvent # noqa: E402
22
+ from gateway.run import GatewayRunner # noqa: E402
23
+ from gateway.session import SessionSource, SessionStore, build_session_key # noqa: E402
24
+ from hermes_cli import heartbeat # noqa: E402
25
+
26
+
27
+ class WireAdapter(BasePlatformAdapter):
28
+ async def connect(self, *, is_reconnect=False):
29
+ return True
30
+
31
+ async def disconnect(self):
32
+ pass
33
+
34
+ async def get_chat_info(self, chat_id):
35
+ return {}
36
+
37
+ async def send(self, chat_id, content, reply_to=None, metadata=None):
38
+ self.wire.append(content)
39
+ return SendResult(success=True, message_id=str(len(self.wire)))
40
+
41
+
42
+ async def main(base_poller):
43
+ assert os.environ.get("HERMES_HOME"), "Use a temporary HERMES_HOME"
44
+ runner = object.__new__(GatewayRunner)
45
+ runner._running_agents = {}
46
+ runner._run_in_executor_with_context = asyncio.to_thread
47
+ adapter = WireAdapter(PlatformConfig(enabled=True, typing_indicator=False), Platform.TELEGRAM)
48
+ adapter.wire = []
49
+ runner._adapter_for_source = lambda source: adapter
50
+ source = SessionSource(platform=Platform.TELEGRAM, chat_id="42", user_id="42", chat_type="dm")
51
+ key = build_session_key(source)
52
+ watch = {key: (source, "wire-session")}
53
+ if base_poller:
54
+ scope = {"__name__": "heartbeat_base"}
55
+ exec(compile(Path(base_poller).read_text(encoding="utf-8"), base_poller, "exec"), scope)
56
+ runner._heartbeat_poll_once = scope["GatewayGoalsMixin"]._heartbeat_poll_once.__get__(runner)
57
+ await runner._warm_goals_session_db("wire-contract")
58
+ clock = SimpleNamespace(now=1000.0)
59
+ received = []
60
+ release = asyncio.Event()
61
+
62
+ async def handler(event):
63
+ event._heartbeat_execution_started = True # fake agent execution boundary
64
+ received.append(event.text)
65
+ await release.wait()
66
+ return "wire reply"
67
+
68
+ async def drain():
69
+ while adapter._background_tasks:
70
+ await asyncio.gather(*list(adapter._background_tasks))
71
+
72
+ def snapshot():
73
+ return {"turns": len(received), "queue_depth": runner._queue_depth(key, adapter=adapter),
74
+ "fire_count": heartbeat.HeartbeatManager("wire-session").state.fire_count}
75
+
76
+ adapter.set_message_handler(handler)
77
+ await adapter.connect()
78
+ with patch.object(heartbeat, "time", SimpleNamespace(time=lambda: clock.now)):
79
+ heartbeat.HeartbeatManager("wire-session").set("check status", 60)
80
+ for _ in range(15):
81
+ clock.now += 60
82
+ await runner._heartbeat_poll_once(watch)
83
+ await asyncio.sleep(0)
84
+ print(json.dumps({"phase": "15 minute polls, first turn held", **snapshot()}))
85
+ release.set()
86
+ await adapter.handle_message(MessageEvent(text="real-user-wire-input", source=source))
87
+ await drain()
88
+ print(json.dumps({"phase": "user wake drain", "wire_sends": len(adapter.wire), **snapshot()}))
89
+ if not base_poller:
90
+ assert len(received) == 2 and len(adapter.wire) == 2
91
+ assert snapshot()["queue_depth"] == 0
92
+ # A genuinely idle 15-minute gap coalesces to one, even with repeated polls.
93
+ heartbeat.HeartbeatManager("wire-session").set("check status", 60)
94
+ before = len(received)
95
+ clock.now += 900
96
+ for _ in range(5):
97
+ await runner._heartbeat_poll_once(watch)
98
+ await drain()
99
+ assert len(received) - before == 1
100
+ assert heartbeat.HeartbeatManager("wire-session").state.fire_count == 1
101
+ print(json.dumps({"phase": "idle 15-minute gap + 5 same-time polls", "new_turns": 1,
102
+ "queue_depth": snapshot()["queue_depth"], "fire_count": 1}))
103
+ # A pinned route must not enter the pre-claim executor recovery gap.
104
+ # The callback represents competing traffic changing the last active topic.
105
+ recovery = []
106
+ adapter._topic_recovery_fn = lambda source: recovery.append(source) or "foreign-topic"
107
+ clock.now += 60
108
+ await runner._heartbeat_poll_once(watch)
109
+ assert key in adapter._active_sessions and recovery == []
110
+ await drain()
111
+ print(json.dumps({"phase": "pinned route", "recovery_calls": len(recovery)}))
112
+ # Admission can be cancelled before the fake agent boundary is reached.
113
+ clock.now += 60
114
+ before = heartbeat.HeartbeatManager("wire-session").state.to_json()
115
+ turns_before = len(received)
116
+ await runner._heartbeat_poll_once(watch)
117
+ await adapter.cancel_session_processing(key)
118
+ await drain()
119
+ assert len(received) == turns_before
120
+ assert heartbeat.HeartbeatManager("wire-session").state.to_json() == before
121
+ print(json.dumps({"phase": "cancelled admission", "claim_refunded": True}))
122
+ runner.config = GatewayConfig()
123
+ runner.session_store = SessionStore(
124
+ sessions_dir=Path(os.environ["HERMES_HOME"]) / "sessions", config=runner.config)
125
+ runner.adapters = {Platform.TELEGRAM: adapter}
126
+ runner._profile_adapters = {}
127
+ runner._recover_telegram_topic_thread_id = adapter._topic_recovery_fn
128
+ event = MessageEvent(text="pinned heartbeat", source=source,
129
+ metadata={"gateway_session_key": key})
130
+ resolved = await runner._hmwa_resolve_session(event, source)
131
+ assert resolved is not None and resolved[2] == key and recovery == []
132
+ print(json.dumps({"phase": "runner pinned route", "session_key": resolved[2],
133
+ "recovery_calls": len(recovery)}))
134
+ # Route mismatch is a real adapter rejection, not a fabricated return value.
135
+ adapter._session_key_profile = lambda source: "different-profile"
136
+ route_sid = resolved[1].session_id
137
+ heartbeat.HeartbeatManager(route_sid).set("check status", 60)
138
+ clock.now += 60
139
+ before = heartbeat.HeartbeatManager(route_sid).state.to_json()
140
+ await runner._heartbeat_poll_once(watch)
141
+ assert watch[key][1] == route_sid
142
+ assert heartbeat.HeartbeatManager(route_sid).state.to_json() == before
143
+ assert snapshot()["queue_depth"] == 0
144
+ print(json.dumps({"phase": "rejected route", "claim_refunded": True}))
145
+ await adapter.disconnect()
146
+
147
+
148
+ if __name__ == "__main__":
149
+ parser = argparse.ArgumentParser()
150
+ parser.add_argument("--base-poller")
151
+ asyncio.run(main(parser.parse_args().base_poller))
evals/kanban_graph_identity.py ADDED
@@ -0,0 +1,86 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Credential-free SQLite integration probe; run with --repo PATH."""
2
+ import argparse
3
+ from concurrent.futures import ThreadPoolExecutor
4
+ import importlib
5
+ import json
6
+ import os
7
+ from pathlib import Path
8
+ import subprocess
9
+ import sys
10
+ import tempfile
11
+ import threading
12
+
13
+
14
+ def main():
15
+ parser = argparse.ArgumentParser()
16
+ parser.add_argument("--repo", type=Path, required=True)
17
+ parser.add_argument("--child", action="store_true")
18
+ args = parser.parse_args()
19
+ if not args.child:
20
+ with tempfile.TemporaryDirectory(prefix="kanban-identity-") as home:
21
+ env = {"HOME": home, "HERMES_HOME": home + "/hermes", "PATH": os.defpath,
22
+ "LANG": "C.UTF-8", "TZ": "UTC", "PYTHONDONTWRITEBYTECODE": "1"}
23
+ return subprocess.run(
24
+ [sys.executable, str(Path(__file__).resolve()), "--repo", str(args.repo), "--child"],
25
+ cwd=args.repo, env=env, check=False,
26
+ ).returncode
27
+ sys.path.insert(0, str(args.repo))
28
+ from hermes_cli import kanban_db as kb, kanban_db_connect as kbc
29
+ from hermes_cli.kanban_db_dispatch import dispatch_once
30
+ from tools.kanban_tools import _handle_create
31
+ from hermes_cli.kanban_decompose import _apply_fanout, _Routing
32
+ graph = importlib.import_module("hermes_cli.kanban_db_graph") if (args.repo / "hermes_cli/kanban_db_graph.py").exists() else kb
33
+ decompose = graph.decompose_triage_task
34
+ specs = [{"title": "work", "assignee": "default"}]
35
+ with kbc.connect_closing() as conn:
36
+ parent = kb.create_task(conn, title="prerequisite", tenant="business-a")
37
+ root = kb.create_task(conn, title="root", triage=True, tenant="business-a", parents=[parent])
38
+ downstream = kb.create_task(conn, title="downstream", parents=[root], tenant="business-a")
39
+ child = kb.create_task(conn, title="manual child", parents=[parent])
40
+ tool = json.loads(_handle_create({"title": "tool child", "assignee": "default", "parents": [parent]}))
41
+ assert tool["ok"]
42
+ out = {"db_tenant": kb.get_task(conn, child).tenant,
43
+ "tool_tenant": kb.get_task(conn, tool["task_id"]).tenant}
44
+ first = decompose(conn, root, root_assignee="default", children=specs)
45
+ assert first and kb.get_task(conn, first[0]).tenant == "business-a"
46
+ assert conn.execute("SELECT 1 FROM task_links WHERE parent_id=? AND child_id=?", (parent, root)).fetchone()
47
+ assert conn.execute("SELECT 1 FROM task_links WHERE parent_id=? AND child_id=?", (root, downstream)).fetchone()
48
+ out["legitimate_prelinked_first_fanout"] = True
49
+ with kb.write_txn(conn):
50
+ conn.execute("UPDATE tasks SET status='triage' WHERE id=?", (root,))
51
+ out["repeat_refused"] = decompose(conn, root, root_assignee="default", children=specs) is None
52
+ with kb.write_txn(conn):
53
+ conn.execute("UPDATE tasks SET status='done' WHERE id=?", (root,))
54
+ conn.execute("UPDATE task_events SET created_at=0 WHERE task_id=?", (root,))
55
+ kb.gc_events(conn, older_than_seconds=1)
56
+ with kb.write_txn(conn):
57
+ conn.execute("UPDATE tasks SET status='triage' WHERE id=?", (root,))
58
+ out["retention_repeat_refused"] = decompose(conn, root, root_assignee="default", children=specs) is None
59
+ ids = list(conn.execute("SELECT id FROM tasks ORDER BY id"))
60
+ for _ in range(3):
61
+ dispatch_once(conn, max_spawn=0)
62
+ out["three_dispatch_ticks_stable"] = ids == list(conn.execute("SELECT id FROM tasks ORDER BY id"))
63
+ ingress_root = kb.create_task(conn, title="ingress", tenant="business-a", triage=True)
64
+ routing = _Routing("default", "default", True, [], {"default"})
65
+ assert _apply_fanout(ingress_root, {"tasks": specs}, routing, "probe").ok
66
+ with kb.write_txn(conn):
67
+ conn.execute("UPDATE tasks SET status='triage' WHERE id=?", (ingress_root,))
68
+ out["fanout_ingress_repeat_refused"] = not _apply_fanout(ingress_root, {"tasks": specs}, routing, "probe").ok
69
+ race_root = kb.create_task(conn, title="race", tenant="business-a", triage=True)
70
+ barrier = threading.Barrier(2)
71
+ def race():
72
+ with kbc.connect_closing() as conn:
73
+ barrier.wait(timeout=10)
74
+ return decompose(conn, race_root, root_assignee="default", children=specs)
75
+ with ThreadPoolExecutor(max_workers=2) as pool:
76
+ outcomes = list(pool.map(lambda _: race(), range(2)))
77
+ out["concurrent_winners"] = sum(value is not None for value in outcomes)
78
+ with kbc.connect_closing() as conn:
79
+ out["integrity"] = conn.execute("PRAGMA integrity_check").fetchone()[0]
80
+ assert out["three_dispatch_ticks_stable"] and out["concurrent_winners"] == 1 and out["integrity"] == "ok"
81
+ print(json.dumps(out, sort_keys=True))
82
+ return 0
83
+
84
+
85
+ if __name__ == "__main__":
86
+ raise SystemExit(main())
evals/kanban_pr_acceptance_live.py ADDED
@@ -0,0 +1,67 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Local HTTP/lifecycle probe; no external GitHub writes or inference.
2
+ Run: python evals/kanban_pr_acceptance_live.py ROOT
3
+ """
4
+ import importlib.util
5
+ import json
6
+ import os
7
+ from pathlib import Path
8
+ import sys
9
+ import tempfile
10
+
11
+ root = Path(sys.argv[1]).resolve()
12
+ sys.path.insert(0, str(root))
13
+ os.environ.pop('HERMES_DELEGATED_CHILD_CONTEXT', None)
14
+ import pytest
15
+ from hermes_cli import kanban_db as kb
16
+ from hermes_cli.kanban_db_connect import connect
17
+ import inspect
18
+
19
+ def create(conn, title):
20
+ if 'completion_contract' in inspect.signature(kb.create_task).parameters:
21
+ return kb.create_task(conn, title=title, completion_contract='acme/repo')
22
+ tid = kb.create_task(conn, title=title)
23
+ if 'completion_contract' not in {r[1] for r in conn.execute('PRAGMA table_info(tasks)')}:
24
+ conn.execute('ALTER TABLE tasks ADD COLUMN completion_contract TEXT')
25
+ conn.execute('UPDATE tasks SET completion_contract=? WHERE id=?', ('acme/repo', tid))
26
+ conn.commit()
27
+ return tid
28
+
29
+ fixture_root = Path(sys.argv[2]) if len(sys.argv) > 2 else root
30
+ spec = importlib.util.spec_from_file_location('http_fixture', fixture_root / 'tests/hermes_cli/test_kanban_pr_acceptance.py')
31
+ fixture = importlib.util.module_from_spec(spec)
32
+ spec.loader.exec_module(fixture)
33
+ patch = pytest.MonkeyPatch()
34
+ with tempfile.TemporaryDirectory(prefix='hermes-pr-live-') as home:
35
+ setup = fixture.github.__wrapped__(Path(home), patch)
36
+ state = next(setup)
37
+ reports = []
38
+ try:
39
+ with connect() as conn:
40
+ for outcome in ('failure', 'cancelled', 'timed_out', 'success'):
41
+ state.update(conclusion=outcome)
42
+ tid = create(conn, 'PR acceptance live')
43
+ accepted = kb.complete_task(conn, tid, metadata={'published_pr': 'https://github.com/acme/repo/pull/7'})
44
+ row = conn.execute("SELECT payload FROM task_events WHERE task_id=? AND kind='pr_acceptance' ORDER BY id DESC", (tid,)).fetchone()
45
+ receipt = json.loads(row[0]) if row else None
46
+ reports.append({'case': outcome, 'accepted': accepted, 'status': kb.get_task(conn, tid).status, 'receipt': receipt})
47
+ for outcome in (('success', 'failure') if 'completion_contract' in inspect.signature(kb.create_task).parameters else ()):
48
+ tid = kb.create_task(conn, title='Concurrent ownership', completion_contract='acme/repo')
49
+ owner = kb.claim_task(conn, tid)
50
+ run_id = owner.current_run_id
51
+ def reclaim():
52
+ with connect() as other:
53
+ kb.block_task(other, tid, reason='Reassigned during acceptance')
54
+ kb.unblock_task(other, tid)
55
+ state['replacement'] = kb.claim_task(other, tid).current_run_id
56
+ state.update(conclusion=outcome, race=reclaim)
57
+ accepted = kb.complete_task(conn, tid, expected_run_id=run_id, metadata={'published_pr': 'https://github.com/acme/repo/pull/7'})
58
+ reports.append({'case': 'CAS-'+outcome, 'accepted': accepted, 'run_id': kb.get_task(conn, tid).current_run_id,
59
+ 'receipts': conn.execute("SELECT count(*) FROM task_events WHERE task_id=? AND kind='pr_acceptance'", (tid,)).fetchone()[0]})
60
+ del state['race']
61
+ print(json.dumps({'reports': reports, 'requests': state['requests']}, indent=2))
62
+ finally:
63
+ try:
64
+ next(setup)
65
+ except StopIteration:
66
+ pass
67
+ patch.undo()
evals/kanban_scope_probe.py ADDED
@@ -0,0 +1,60 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Credential-free app-server/MCP scope probe; writes only its temporary board."""
2
+ import json
3
+ import os
4
+ from pathlib import Path
5
+ import subprocess
6
+ import shutil
7
+ import sys
8
+ import tempfile
9
+
10
+ repo = Path(sys.argv[1]).resolve()
11
+ if len(sys.argv) == 2:
12
+ with tempfile.TemporaryDirectory(prefix="kanban-transport-") as home:
13
+ env = {"HOME": home, "HERMES_HOME": home + "/hermes", "PATH": os.environ["PATH"], "PYTHONDONTWRITEBYTECODE": "1"}
14
+ p = subprocess.run([sys.executable, __file__, str(repo), "isolated"], cwd=home, env=env, stdin=subprocess.DEVNULL)
15
+ sys.exit(p.returncode)
16
+ sys.path.insert(0, str(repo))
17
+ from hermes_cli import kanban_db as kb
18
+ from hermes_cli.kanban_db_connect import connect
19
+ from agent.transports.codex_app_server import CodexAppServerClient
20
+
21
+ home = Path(os.environ["HOME"])
22
+ hh = Path(os.environ["HERMES_HOME"])
23
+ hh.mkdir(exist_ok=True)
24
+ (hh / "config.yaml").write_text("toolsets: [kanban]\n")
25
+ db = home / "assigned.db"
26
+ conn = connect(db)
27
+ own, foreign = [kb.create_task(conn, title=x) for x in ("owner", "foreign")]
28
+ for t in (own, foreign):
29
+ kb.claim_task(conn, t)
30
+ task = kb.get_task(conn, own)
31
+ os.environ.update({"HERMES_KANBAN_DB": str(db), "HERMES_KANBAN_BOARD": "default", "HERMES_KANBAN_TASK": own, "HERMES_KANBAN_RUN_ID": str(task.current_run_id), "HERMES_KANBAN_CLAIM_LOCK": task.claim_lock})
32
+ ch = home / "codex"
33
+ ch.mkdir()
34
+ (ch / "config.toml").write_text(
35
+ 'model="fixture"\nmodel_provider="fixture"\n'
36
+ '[model_providers.fixture]\nname="fixture"\nbase_url="http://127.0.0.1:9/v1"\nwire_api="responses"\n'
37
+ '[mcp_servers.hermes-mcp]\ncommand=' + json.dumps(sys.executable) + '\nargs=["-m","agent.transports.hermes_tools_mcp_server"]\nstartup_timeout_sec=40\n'
38
+ '[mcp_servers.hermes-mcp.env]\nPYTHONPATH=' + json.dumps(str(repo)) + '\nHERMES_HOME=' + json.dumps(str(hh)) + '\n'
39
+ )
40
+ report = {}
41
+ with CodexAppServerClient(codex_bin=shutil.which("codex") or "codex", codex_home=str(ch)) as c:
42
+ try:
43
+ report["initialize"] = c.initialize(capabilities={"experimentalApi": True})
44
+ except Exception:
45
+ print(json.dumps({"stderr": c._stderr_lines, "args": c._proc.args, "rc": c._proc.poll()}), flush=True)
46
+ raise
47
+ script = "import os,sys,json;sys.path.insert(0," + repr(str(repo)) + ");from tools import kanban_tools as kt;print(json.dumps({'marker':os.getenv('HERMES_DELEGATED_CHILD_CONTEXT'),'db':os.getenv('HERMES_KANBAN_DB'),'mutation':json.loads(kt._handle_complete({'task_id':" + repr(own) + ",'summary':'must refuse'}))}))"
48
+ report["native_child"] = c.request("command/exec", {"command": [sys.executable, "-c", script], "cwd": str(home), "sandboxPolicy": {"type": "dangerFullAccess"}}, timeout=40)
49
+ thread = c.request("thread/start", {"model": "fixture", "modelProvider": "fixture", "cwd": str(home), "approvalPolicy": "never", "sandbox": "workspace-write"}, timeout=50)
50
+ thread_id = thread["thread"]["id"]
51
+ status = c.request("mcpServerStatus/list", {"threadId": thread_id}, timeout=50)
52
+ report["mcp_servers"] = [{"name": x.get("name"), "tools": list(x.get("tools", {}))} for x in status.get("data", [])]
53
+ for name, tid in (("foreign", foreign), ("own", own)):
54
+ report[name] = c.request("mcpServer/tool/call", {"threadId": thread_id, "server": "hermes-mcp", "tool": "kanban_complete", "arguments": {"task_id": tid, "summary": "supervised parent handoff"}}, timeout=50)
55
+ report["stderr"] = c._stderr_lines[-8:]
56
+ report["readback"] = {"own": kb.get_task(conn, own).status, "foreign": kb.get_task(conn, foreign).status, "integrity": conn.execute("PRAGMA integrity_check").fetchone()[0]}
57
+ print(json.dumps(report, indent=2))
58
+ assert report["readback"] == {"own": "done", "foreign": "running", "integrity": "ok"}, report
59
+ native = json.loads(report["native_child"]["stdout"])
60
+ assert native["marker"] == "1" and native["db"] == str(db) and "error" in native["mutation"], report
evals/key_cmd_picker_live.py ADDED
@@ -0,0 +1,182 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ #!/usr/bin/env python3
2
+ """Live key_cmd catalog A/B: local authenticated HTTP, real helper, CLI PTY.
3
+
4
+ Run with the Hermes venv Python and --repo CHECKOUT --output RECEIPT_DIR.
5
+ No user environment/config is inherited by Hermes children. Unix PTY required.
6
+ """
7
+ import argparse
8
+ import http.server
9
+ import json
10
+ import os
11
+ from pathlib import Path
12
+ import pty
13
+ import re
14
+ import select
15
+ import shlex
16
+ import subprocess
17
+ import sys
18
+ import tempfile
19
+ import threading
20
+ import time
21
+
22
+ CATALOG = ["live-configured", "live-discovered-b", "live-discovered-c"]
23
+ TOKEN = "local-eval-token-not-a-secret"
24
+
25
+
26
+ def rows_worker():
27
+ from hermes_cli.config import load_config
28
+ from hermes_cli.model_switch_providers import (
29
+ _PickerBuild, _lap_custom_provider_rows, _lap_user_provider_rows,
30
+ )
31
+ cfg = load_config()
32
+ b = _PickerBuild(current_provider="", current_base_url="", current_model="",
33
+ max_models=None, for_picker=True, force_fresh_nous_tier=False,
34
+ probe_custom_providers=True, probe_current_custom_provider=False,
35
+ refresh=False, excluded=set(), curated={})
36
+ if cfg.get("providers"):
37
+ _lap_user_provider_rows(b, cfg["providers"])
38
+ else:
39
+ _lap_custom_provider_rows(b, cfg["custom_providers"])
40
+ print("RECEIPT_ROWS=" + json.dumps(b.results))
41
+
42
+
43
+ def cli_pty(repo, env):
44
+ master, slave = pty.openpty()
45
+ import fcntl
46
+ import struct
47
+ import termios
48
+ fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", 45, 140, 0, 0))
49
+ proc = subprocess.Popen([sys.executable, "-m", "hermes_cli.main", "model"],
50
+ cwd=repo, env=env, stdin=slave, stdout=slave, stderr=slave,
51
+ start_new_session=True)
52
+ os.close(slave)
53
+ data = bytearray()
54
+ selected = False
55
+ deadline = time.monotonic() + 45
56
+ try:
57
+ while time.monotonic() < deadline:
58
+ if select.select([master], [], [], 0.2)[0]:
59
+ try:
60
+ chunk = os.read(master, 65536)
61
+ except OSError:
62
+ break
63
+ if not chunk:
64
+ break
65
+ data.extend(chunk)
66
+ text = data.decode(errors="replace")
67
+ if not selected and ("Select provider:" in text or "Choice [1-" in text):
68
+ os.write(master, b"\r")
69
+ selected = True
70
+ if selected and (re.search(r"Found \d+ model", text)
71
+ or "Could not fetch models" in text):
72
+ # Let the actual picker render before cancelling; never save a selection.
73
+ end = time.monotonic() + 0.7
74
+ while time.monotonic() < end:
75
+ if select.select([master], [], [], 0.1)[0]:
76
+ data.extend(os.read(master, 65536))
77
+ os.write(master, b"\x03")
78
+ break
79
+ if proc.poll() is not None:
80
+ break
81
+ finally:
82
+ if proc.poll() is None:
83
+ proc.terminate()
84
+ proc.wait(timeout=10)
85
+ os.close(master)
86
+ text = data.decode(errors="replace")
87
+ found = re.search(r"Found (\d+) model", text)
88
+ if not found:
89
+ raise RuntimeError("CLI failed to reach model picker:\n" + text[-12000:])
90
+ return int(found.group(1)), text
91
+
92
+
93
+ def main():
94
+ ap = argparse.ArgumentParser(description=__doc__)
95
+ ap.add_argument("--repo", type=Path, required=True)
96
+ ap.add_argument("--output", type=Path, required=True)
97
+ ap.add_argument("--expect", choices=["before", "after"])
98
+ args = ap.parse_args()
99
+ repo = args.repo.resolve()
100
+ args.output.mkdir(parents=True, exist_ok=True)
101
+ requests = []
102
+ phase = ""
103
+
104
+ class Handler(http.server.BaseHTTPRequestHandler):
105
+ def do_GET(self):
106
+ authorized = self.headers.get("Authorization") == "Bearer " + TOKEN
107
+ requests.append({"phase": phase, "path": self.path, "authorized": authorized})
108
+ body = json.dumps({"data": [{"id": m} for m in CATALOG]} if authorized
109
+ else {"error": "authorization required"}).encode()
110
+ self.send_response(200 if authorized else 401)
111
+ self.send_header("Content-Type", "application/json")
112
+ self.send_header("Content-Length", str(len(body)))
113
+ self.end_headers()
114
+ self.wfile.write(body)
115
+
116
+ def log_message(self, format, *args):
117
+ return
118
+
119
+ server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)
120
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
121
+ thread.start()
122
+ results = {}
123
+ try:
124
+ for schema in ("providers", "custom_providers"):
125
+ for surface in ("cli", "rows"):
126
+ phase = f"{schema}/{surface}"
127
+ with tempfile.TemporaryDirectory(prefix="hermes-keycmd-live-") as tmp:
128
+ home = Path(tmp)
129
+ state = home / ".hermes"
130
+ state.mkdir()
131
+ mint_log = home / "helper-invocations"
132
+ helper = home / "mint.py"
133
+ helper.write_text("from pathlib import Path\n"
134
+ f"with Path({str(mint_log)!r}).open('a') as f: f.write('mint\\n')\n"
135
+ f"print({TOKEN!r})\n")
136
+ entry = {"name": "Live Keycmd", "base_url": f"http://127.0.0.1:{server.server_port}/v1",
137
+ "key_cmd": f"{shlex.quote(sys.executable)} {shlex.quote(str(helper))}",
138
+ "model": CATALOG[0], "models": {CATALOG[0]: {}},
139
+ "models_discovered": True}
140
+ slug = "live-keycmd" if schema == "providers" else "custom:live-keycmd"
141
+ cfg = {"model": {"provider": slug, "default": CATALOG[0]},
142
+ schema: {slug: entry} if schema == "providers" else [entry]}
143
+ # JSON is valid YAML; no third-party harness dependencies.
144
+ (state / "config.yaml").write_text(json.dumps(cfg))
145
+ env = {"HOME": str(home), "HERMES_HOME": str(state),
146
+ "PATH": "/usr/bin:/bin", "TERM": "xterm-256color", "LANG": "C.UTF-8",
147
+ "PYTHONPATH": str(repo), "PYTHONUNBUFFERED": "1"}
148
+ if surface == "cli":
149
+ count, transcript = cli_pty(repo, env)
150
+ results[phase] = {"model_count": count}
151
+ else:
152
+ code = ("import runpy; ns=runpy.run_path(" + repr(str(Path(__file__).resolve()))
153
+ + "); ns['rows_worker']()")
154
+ proc = subprocess.run([sys.executable, "-c", code], cwd=repo, env=env,
155
+ stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=45)
156
+ transcript = proc.stdout + proc.stderr
157
+ if proc.returncode:
158
+ raise RuntimeError(transcript)
159
+ rows = json.loads(next(s.split("=", 1)[1] for s in proc.stdout.splitlines()
160
+ if s.startswith("RECEIPT_ROWS=")))
161
+ assert len(rows) == 1, rows
162
+ results[phase] = {"model_count": rows[0]["total_models"], "models": rows[0]["models"]}
163
+ results[phase]["helper_invocations"] = len(mint_log.read_text().splitlines()) if mint_log.exists() else 0
164
+ (args.output / (phase.replace("/", "-") + ".txt")).write_text(transcript)
165
+ receipt = {"repo": str(repo), "sha": subprocess.check_output(
166
+ ["git", "rev-parse", "HEAD"], cwd=repo, text=True).strip(),
167
+ "server_catalog": CATALOG, "results": results, "requests": requests}
168
+ (args.output / "receipt.json").write_text(json.dumps(receipt, indent=2) + "\n")
169
+ print(json.dumps(receipt, indent=2))
170
+ if args.expect:
171
+ expected = 1 if args.expect == "before" else len(CATALOG)
172
+ assert all(row["model_count"] == expected for row in results.values()), results
173
+ assert all(row["helper_invocations"] > 0 for row in results.values()) if args.expect == "after" else True
174
+ assert all(any(r["phase"] == p and r["authorized"] == (args.expect == "after")
175
+ for r in requests) for p in results), requests
176
+ finally:
177
+ server.shutdown()
178
+ server.server_close()
179
+
180
+
181
+ if __name__ == "__main__":
182
+ main()
evals/mcp_device_flow.py ADDED
@@ -0,0 +1,172 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Local RFC 8628 wire fixture; no external credentials or provider claims.
2
+
3
+ Run: python evals/mcp_device_flow.py --repo /path/to/checkout
4
+ """
5
+ from __future__ import annotations
6
+
7
+ import argparse
8
+ from contextlib import contextmanager
9
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
10
+ import json
11
+ import os
12
+ from pathlib import Path
13
+ import subprocess
14
+ import sys
15
+ import tempfile
16
+ import threading
17
+ import time
18
+ from urllib.parse import parse_qs
19
+
20
+ DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code"
21
+
22
+
23
+ @contextmanager
24
+ def oauth_fixture(mode="success"):
25
+ wire = []
26
+
27
+ class Handler(BaseHTTPRequestHandler):
28
+ def log_message(self, *args):
29
+ pass
30
+
31
+ def reply(self, status, data, headers=None):
32
+ body = json.dumps(data).encode()
33
+ self.send_response(status)
34
+ self.send_header("Content-Type", "application/json")
35
+ self.send_header("Content-Length", str(len(body)))
36
+ for key, value in (headers or {}).items():
37
+ self.send_header(key, value)
38
+ self.end_headers()
39
+ self.wfile.write(body)
40
+
41
+ def do_GET(self): # noqa: N802
42
+ wire.append({"path": self.path, "method": "GET"})
43
+ if self.path == "/mcp":
44
+ if self.headers.get("Authorization") == "Bearer fixture-access":
45
+ return self.reply(200, {"authenticated": True})
46
+ return self.reply(401, {}, {"WWW-Authenticate": f'Bearer resource_metadata="{base}/prm"'})
47
+ if self.path == "/prm" or "oauth-protected-resource" in self.path:
48
+ return self.reply(200, {"resource": base + ("/wrong" if mode == "resource" else "/mcp"),
49
+ "authorization_servers": [base]})
50
+ if "oauth-authorization-server" in self.path:
51
+ metadata = {"issuer": base + ("/wrong" if mode == "issuer" else ""),
52
+ "authorization_endpoint": base + "/authorize", "token_endpoint": base + "/token",
53
+ "response_types_supported": ["code"], "code_challenge_methods_supported": ["S256"],
54
+ "grant_types_supported": [DEVICE_GRANT, "refresh_token"]}
55
+ if mode != "unsupported":
56
+ metadata["device_authorization_endpoint"] = base + "/device"
57
+ if mode != "preregistered":
58
+ metadata["registration_endpoint"] = base + "/register"
59
+ else:
60
+ metadata.pop("authorization_endpoint")
61
+ return self.reply(200, metadata)
62
+ self.reply(404, {})
63
+
64
+ def do_POST(self): # noqa: N802
65
+ raw = self.rfile.read(int(self.headers.get("Content-Length", 0)))
66
+ data = json.loads(raw) if "json" in self.headers.get("Content-Type", "") else {
67
+ key: value[0] for key, value in parse_qs(raw.decode()).items()}
68
+ wire.append({"path": self.path, "method": "POST", "data": data, "at": time.monotonic()})
69
+ if self.path == "/register":
70
+ if DEVICE_GRANT not in data.get("grant_types", []):
71
+ return self.reply(400, {"error": "invalid_client_metadata"})
72
+ return self.reply(201, {**data, "client_id": "fixture-client"})
73
+ if self.path == "/device":
74
+ return self.reply(200, {"device_code": "fixture-device-secret", "user_code": "TEST-CODE",
75
+ "verification_uri": base + "/verify", "interval": 0.01,
76
+ "expires_in": 0.1 if mode == "expiry" else 30})
77
+ if self.path == "/token":
78
+ polls = sum(row["path"] == "/token" for row in wire)
79
+ if mode == "preregistered" and data.get("client_secret") != "fixture-client-secret":
80
+ return self.reply(401, {"error": "invalid_client"})
81
+ if mode in {"denied", "expiry", "malformed"}:
82
+ if mode == "malformed":
83
+ return self.reply(200, {"access_token": {"secret": "fixture-device-secret"}})
84
+ return self.reply(400, {"error": "access_denied" if mode == "denied" else "authorization_pending",
85
+ "error_description": "fixture-device-secret MUST NOT BE PRINTED"})
86
+ if polls <= 2 and mode == "success":
87
+ return self.reply(400, {"error": "authorization_pending" if polls == 1 else "slow_down"})
88
+ return self.reply(200, {"access_token": "fixture-access", "refresh_token": "fixture-refresh",
89
+ "token_type": "Bearer", "expires_in": 3600})
90
+ if self.path == "/mcp":
91
+ if self.headers.get("Authorization") != "Bearer fixture-access":
92
+ return self.reply(401, {}, {"WWW-Authenticate": f'Bearer resource_metadata="{base}/prm"'})
93
+ method = data.get("method")
94
+ if "id" not in data:
95
+ return self.reply(202, {})
96
+ result = {"initialize": {"protocolVersion": data.get("params", {}).get("protocolVersion"),
97
+ "capabilities": {"tools": {}},
98
+ "serverInfo": {"name": "fixture", "version": "1"}},
99
+ "tools/list": {"tools": [{"name": "fixture_echo", "description": "Fixture tool",
100
+ "inputSchema": {"type": "object", "properties": {}}}]}}
101
+ return self.reply(200, {"jsonrpc": "2.0", "id": data["id"], "result": result.get(method, {})})
102
+ self.reply(404, {})
103
+
104
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Handler)
105
+ base = f"http://127.0.0.1:{server.server_port}"
106
+ worker = threading.Thread(target=server.serve_forever, daemon=True)
107
+ worker.start()
108
+ try:
109
+ yield base, wire
110
+ finally:
111
+ server.shutdown()
112
+ server.server_close()
113
+ worker.join()
114
+
115
+
116
+ def run_cli(repo, mode):
117
+ with tempfile.TemporaryDirectory(prefix="hermes-device-wire-") as directory, oauth_fixture(mode) as (base, wire):
118
+ home = Path(directory)
119
+ oauth = {"flow": "device", "cimd": False, "scope": "fixture.read", "timeout": 15}
120
+ if mode == "preregistered":
121
+ oauth.update(client_id="fixture-client", client_secret="fixture-client-secret")
122
+ config = {"mcp_servers": {"fixture": {"url": base + "/mcp", "auth": "oauth", "oauth": oauth}}}
123
+ (home / "config.yaml").write_text(json.dumps(config))
124
+ previous = {}
125
+ if mode == "persistence":
126
+ token_dir = home / "mcp-tokens"
127
+ token_dir.mkdir()
128
+ previous = {"fixture.json": '{"access_token":"old-fixture","token_type":"Bearer"}',
129
+ "fixture.client.json": '{"client_id":"old-client"}',
130
+ "fixture.meta.json": '{"issuer":"https://old.example"}'}
131
+ for filename, value in previous.items():
132
+ (token_dir / filename).write_text(value)
133
+ env = {key: value for key, value in os.environ.items()
134
+ if not key.startswith("HERMES_") and not any(part in key for part in ("API_KEY", "TOKEN", "SECRET"))}
135
+ env.update(HOME=str(home), HERMES_HOME=str(home), PYTHONPATH=str(repo), PYTHONDONTWRITEBYTECODE="1")
136
+ command = ["reauth", "fixture"] if mode == "preregistered" else ["login", "fixture", "--flow", "device"]
137
+ argv = [sys.executable, "-m", "hermes_cli.main", "mcp", *command]
138
+ if mode == "persistence":
139
+ # Inject a filesystem write error after real registration/metadata writes.
140
+ argv = [sys.executable, "-c", '''
141
+ from tools import mcp_oauth
142
+ write = mcp_oauth._write_json
143
+ def fail_token(path, data):
144
+ if path.name == "fixture.json":
145
+ raise OSError("fixture disk failure")
146
+ return write(path, data)
147
+ mcp_oauth._write_json = fail_token
148
+ from hermes_cli.main import main
149
+ main()
150
+ ''', "mcp", *command]
151
+ result = subprocess.run(argv,
152
+ cwd=repo, env=env, stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=40)
153
+ token_path = home / "mcp-tokens" / "fixture.json"
154
+ refresh_output = None
155
+ if token_path.exists() and not previous:
156
+ tokens = json.loads(token_path.read_text())
157
+ tokens["expires_at"] = time.time() - 60
158
+ token_path.write_text(json.dumps(tokens))
159
+ refreshed = subprocess.run([sys.executable, "-m", "hermes_cli.main", "mcp", "test", "fixture"],
160
+ cwd=repo, env=env, stdin=subprocess.DEVNULL, capture_output=True, text=True, timeout=30)
161
+ refresh_output = refreshed.stdout + refreshed.stderr
162
+ return {"mode": mode, "returncode": result.returncode, "output": result.stdout + result.stderr,
163
+ "token_persisted": token_path.exists(), "refresh_output": refresh_output, "wire": wire,
164
+ "state_preserved": all((home / "mcp-tokens" / k).read_text() == v for k, v in previous.items())}
165
+
166
+
167
+ if __name__ == "__main__":
168
+ parser = argparse.ArgumentParser()
169
+ parser.add_argument("--repo", type=Path, required=True)
170
+ parser.add_argument("--mode", default="success")
171
+ args = parser.parse_args()
172
+ print(json.dumps(run_cli(args.repo, args.mode), indent=2))
evals/output_caps_local_capture.py ADDED
@@ -0,0 +1,116 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Zero-cost local SDK wire capture. Fixtures are not vendor inference evidence.
2
+
3
+ Run from a checkout with HERMES_HOME pointing to a disposable directory.
4
+ """
5
+ import json
6
+ import os
7
+ from pathlib import Path
8
+ import threading
9
+ from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
10
+
11
+ from openai import OpenAI
12
+ from anthropic import Anthropic
13
+
14
+ captures = []
15
+
16
+
17
+ class Capture(BaseHTTPRequestHandler):
18
+ def do_GET(self):
19
+ self.send_response(200)
20
+ self.send_header("Content-Type", "application/json")
21
+ self.end_headers()
22
+ self.wfile.write(json.dumps({"data": [{"id": "fixture", "context_length": 131072}]}).encode())
23
+
24
+ def do_POST(self):
25
+ body = json.loads(self.rfile.read(int(self.headers["Content-Length"])))
26
+ captures.append({"path": self.path, "body": body})
27
+ if "model" not in body:
28
+ reply = {}
29
+ elif self.path.endswith("messages"):
30
+ reply = {"id": "fixture", "type": "message", "role": "assistant", "model": body["model"], "content": [{"type": "text", "text": "LOCAL_CAPTURE_ONLY"}], "stop_reason": "end_turn", "usage": {"input_tokens": 1, "output_tokens": 1}}
31
+ else:
32
+ reply = {"id": "fixture", "object": "chat.completion", "created": 0, "model": body["model"], "choices": [{"index": 0, "message": {"role": "assistant", "content": "LOCAL_CAPTURE_ONLY"}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}}
33
+ self.send_response(200)
34
+ if body.get("stream"):
35
+ self.send_header("Content-Type", "text/event-stream")
36
+ self.end_headers()
37
+ chunk = {"id": "fixture", "object": "chat.completion.chunk", "created": 0, "model": body["model"], "choices": [{"index": 0, "delta": {"content": "LOCAL_CAPTURE_ONLY"}, "finish_reason": "stop"}], "usage": {"prompt_tokens": 1, "completion_tokens": 1, "total_tokens": 2}}
38
+ self.wfile.write(("data: " + json.dumps(chunk) + "\n\ndata: [DONE]\n\n").encode())
39
+ else:
40
+ self.send_header("Content-Type", "application/json")
41
+ self.end_headers()
42
+ self.wfile.write(json.dumps(reply).encode())
43
+
44
+ def log_message(self, format, *args):
45
+ pass
46
+
47
+
48
+ server = ThreadingHTTPServer(("127.0.0.1", 0), Capture)
49
+ thread = threading.Thread(target=server.serve_forever, daemon=True)
50
+ thread.start()
51
+ url = f"http://127.0.0.1:{server.server_port}"
52
+ home = Path(os.environ["HERMES_HOME"])
53
+ home.mkdir(parents=True, exist_ok=True)
54
+ config = {"model": {"default": "fixture", "provider": "fixture-local", "max_tokens": 17}, "providers": {"fixture-local": {"api": url + "/v1", "api_key": "fixture", "max_output_tokens": 19}}}
55
+ (home / "config.yaml").write_text(json.dumps(config))
56
+ os.environ["HERMES_MAX_TOKENS"] = "13"
57
+ from gateway.run import _resolve_runtime_agent_kwargs
58
+ from gateway.platforms.api_server import _resolve_request_runtime_agent_kwargs
59
+ from hermes_cli.runtime_provider import resolve_runtime_provider
60
+ from hermes_cli.moa_config import _normalize_preset
61
+ from agent.transports.chat_completions import ChatCompletionsTransport
62
+ from agent.transports.anthropic import AnthropicTransport
63
+ from agent.transports.bedrock import BedrockTransport
64
+
65
+ messages = [{"role": "user", "content": "fixture"}]
66
+ client = OpenAI(api_key="fixture", base_url=url + "/v1", max_retries=0)
67
+ results = {}
68
+ for label, runtime in [("gateway", _resolve_runtime_agent_kwargs()), ("api-server", _resolve_request_runtime_agent_kwargs("fixture-local", "fixture")), ("provider", resolve_runtime_provider(requested="fixture-local", target_model="fixture"))]:
69
+ cap = runtime.get("max_tokens", runtime.get("max_output_tokens"))
70
+ kwargs = ChatCompletionsTransport().build_kwargs("fixture", messages, max_tokens=cap, max_tokens_param_fn=lambda value: {"max_tokens": value})
71
+ client.chat.completions.create(**kwargs)
72
+ results[label] = captures[-1]
73
+ for label, params in [("compatible-claude", {"anthropic_max_output": 65536}), ("internal-budget", {"max_tokens": 43})]:
74
+ kwargs = ChatCompletionsTransport().build_kwargs("claude-fixture", messages, max_tokens_param_fn=lambda value: {"max_tokens": value}, **params)
75
+ client.chat.completions.create(**kwargs)
76
+ results[label] = captures[-1]
77
+ from providers import get_provider_profile
78
+ from run_agent import AIAgent
79
+ agent = AIAgent(model="fixture", provider="custom", base_url=url + "/v1", api_key="fixture", quiet_mode=True, skip_memory=True, skip_context_files=True, enabled_toolsets=[])
80
+ actual_kwargs = agent._build_api_kwargs(messages, tools_for_api=[])
81
+ client.chat.completions.create(**actual_kwargs)
82
+ results["agent-main-custom"] = captures[-1]
83
+ kwargs = ChatCompletionsTransport().build_kwargs("fixture", messages, provider_profile=get_provider_profile("custom"), max_tokens_param_fn=lambda value: {"max_tokens": value})
84
+ client.chat.completions.create(**kwargs)
85
+ results["registered-custom-profile"] = captures[-1]
86
+ from agent.auxiliary_client import _compression_fast_lane_controls
87
+ from tools.delegate_tool_config import _resolve_delegation_credentials
88
+ route = {"provider": "custom", "model": "fixture", "reasoning_effort": "none", "max_output_tokens": 47}
89
+ compression_cap, _ = _compression_fast_lane_controls(
90
+ "compression", actual_provider="custom", actual_model="fixture", requested_provider="custom",
91
+ requested_model="fixture", route_config=route, leak_guard_config=route, max_tokens=None, extra_body={},
92
+ )
93
+ child_credentials = _resolve_delegation_credentials({"provider": "fixture-local", "model": "fixture"}, agent)
94
+ for label, cap in [("compression-config-helper", compression_cap), ("delegation-config-helper", child_credentials.get("max_output_tokens"))]:
95
+ kwargs = ChatCompletionsTransport().build_kwargs("fixture", messages, max_tokens=cap, max_tokens_param_fn=lambda value: {"max_tokens": value})
96
+ client.chat.completions.create(**kwargs)
97
+ results[label] = captures[-1]
98
+ kwargs = AnthropicTransport().build_kwargs("claude-sonnet-4-5", messages)
99
+ kwargs.pop("__anthropic__", None)
100
+ Anthropic(api_key="fixture", base_url=url, max_retries=0).messages.create(**kwargs)
101
+ results["native-anthropic"] = captures[-1]
102
+ results["bedrock-converse-built-not-sent"] = BedrockTransport().build_kwargs("amazon.nova-pro-v1:0", messages)
103
+ results["moa-normalized"] = _normalize_preset({"max_tokens": 23, "reference_max_tokens": 29})
104
+ if os.environ.get("FULL_OUTPUT_CAP_SURFACES"):
105
+ from output_caps_surfaces import exercise_surfaces
106
+ results.update(exercise_surfaces(agent, captures, url, home, config))
107
+ print(json.dumps(results, indent=2, default=str))
108
+ server.shutdown()
109
+ server.server_close()
110
+ thread.join()
111
+ if os.environ.get("VERIFY_OUTPUT_CAP_REMOVAL"):
112
+ for label in ("gateway", "api-server", "provider", "compatible-claude", "agent-main-custom", "registered-custom-profile", "compression-config-helper", "delegation-config-helper"):
113
+ assert "max_tokens" not in results[label]["body"], label
114
+ assert results["internal-budget"]["body"]["max_tokens"] == 43
115
+ assert results["native-anthropic"]["body"]["max_tokens"] > 0
116
+ assert "maxTokens" not in results["bedrock-converse-built-not-sent"].get("inferenceConfig", {})