Add files using upload-large-folder tool
Browse filesThis view is limited to 50 files because it contains too many changes. See raw diff
- .coderabbit.yaml +18 -0
- .dockerignore +114 -0
- .env.example +544 -0
- .gitattributes +34 -35
- .gitignore +280 -0
- .mailmap +109 -0
- .npmrc +63 -0
- .nvmrc +1 -0
- .prettierignore +4 -0
- .prettierrc +11 -0
- .python-version +1 -0
- AGENTS.md +432 -0
- COMPAT_MANIFEST.md +0 -0
- CONTRIBUTING.es.md +602 -0
- CONTRIBUTING.md +1002 -0
- README.md +276 -0
- README.zh-CN.md +208 -0
- SECURITY.es.md +326 -0
- SECURITY.md +335 -0
- SOUL.md +1 -0
- cli.py +0 -0
- compat_manifest.json +0 -0
- docker-compose.yml +76 -0
- eslint.config.shared.mjs +106 -0
- evals/__init__.py +0 -0
- evals/acp_empty_session_wire.py +153 -0
- evals/anthropic_proxy_thinking_replay.py +103 -0
- evals/api_delegation_http_probe.py +102 -0
- evals/api_delegation_sync_probe.py +66 -0
- evals/approval_deny_dispatch.py +80 -0
- evals/auth_pool_controls.py +153 -0
- evals/auxiliary_resource_exhausted.py +110 -0
- evals/cli_deferred_notice.py +129 -0
- evals/cli_fallback_add_picker_error.py +135 -0
- evals/codex_masked_replay_review.py +138 -0
- evals/completion_backlog_probe.py +195 -0
- evals/cron_error_diagnostics.py +85 -0
- evals/cron_timeout_fork_race.py +93 -0
- evals/delivery_flood_wire.py +201 -0
- evals/desktop-reap-clock-pressure.cjs +12 -0
- evals/fanout_resource_bench.py +232 -0
- evals/gemini_type_array_probe.py +120 -0
- evals/goal_command_parity.py +51 -0
- evals/heartbeat_idle_wire.py +151 -0
- evals/kanban_graph_identity.py +86 -0
- evals/kanban_pr_acceptance_live.py +67 -0
- evals/kanban_scope_probe.py +60 -0
- evals/key_cmd_picker_live.py +182 -0
- evals/mcp_device_flow.py +172 -0
- 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 |
-
|
| 2 |
-
|
| 3 |
-
|
| 4 |
-
|
| 5 |
-
|
| 6 |
-
|
| 7 |
-
*.
|
| 8 |
-
|
| 9 |
-
*.
|
| 10 |
-
|
| 11 |
-
|
| 12 |
-
|
| 13 |
-
|
| 14 |
-
|
| 15 |
-
|
| 16 |
-
|
| 17 |
-
|
| 18 |
-
|
| 19 |
-
*.
|
| 20 |
-
*.
|
| 21 |
-
*.
|
| 22 |
-
*.
|
| 23 |
-
*.
|
| 24 |
-
*.
|
| 25 |
-
*.
|
| 26 |
-
|
| 27 |
-
*.
|
| 28 |
-
*.
|
| 29 |
-
*.
|
| 30 |
-
*.
|
| 31 |
-
*.
|
| 32 |
-
*.
|
| 33 |
-
*.
|
| 34 |
-
*.
|
| 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", {})
|