hermes-agent/website/docs/reference/tools-reference.md

377 lines
40 KiB
Markdown
Raw Permalink Normal View History

---
sidebar_position: 3
title: "Built-in Tools Reference"
description: "Authoritative reference for Hermes built-in tools, grouped by toolset"
---
# Built-in Tools Reference
docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784) * docs: deep audit — fix stale config keys, missing commands, and registry drift Cross-checked ~80 high-impact docs pages (getting-started, reference, top-level user-guide, user-guide/features) against the live registries: hermes_cli/commands.py COMMAND_REGISTRY (slash commands) hermes_cli/auth.py PROVIDER_REGISTRY (providers) hermes_cli/config.py DEFAULT_CONFIG (config keys) toolsets.py TOOLSETS (toolsets) tools/registry.py get_all_tool_names() (tools) python -m hermes_cli.main <subcmd> --help (CLI args) reference/ - cli-commands.md: drop duplicate hermes fallback row + duplicate section, add stepfun/lmstudio to --provider enum, expand auth/mcp/curator subcommand lists to match --help output (status/logout/spotify, login, archive/prune/ list-archived). - slash-commands.md: add missing /sessions and /reload-skills entries + correct the cross-platform Notes line. - tools-reference.md: drop bogus '68 tools' headline, drop fictional 'browser-cdp toolset' (these tools live in 'browser' and are runtime-gated), add missing 'kanban' and 'video' toolset sections, fix MCP example to use the real mcp_<server>_<tool> prefix. - toolsets-reference.md: list browser_cdp/browser_dialog inside the 'browser' row, add missing 'kanban' and 'video' toolset rows, drop the stale '38 tools' count for hermes-cli. - profile-commands.md: add missing install/update/info subcommands, document fish completion. - environment-variables.md: dedupe GMI_API_KEY/GMI_BASE_URL rows (kept the one with the correct gmi-serving.com default). - faq.md: Anthropic/Google/OpenAI examples — direct providers exist (not just via OpenRouter), refresh the OpenAI model list. getting-started/ - installation.md: PortableGit (not MinGit) is what the Windows installer fetches; document the 32-bit MinGit fallback. - installation.md / termux.md: installer prefers .[termux-all] then falls back to .[termux]. - nix-setup.md: Python 3.12 (not 3.11), Node.js 22 (not 20); fix invalid 'nix flake update --flake' invocation. - updating.md: 'hermes backup restore --state pre-update' doesn't exist — point at the snapshot/quick-snapshot flow; correct config key 'updates.pre_update_backup' (was 'update.backup'). user-guide/ - configuration.md: api_max_retries default 3 (not 2); display.runtime_footer is the real key (not display.runtime_metadata_footer); checkpoints defaults enabled=false / max_snapshots=20 (not true / 50). - configuring-models.md: 'hermes model list' / 'hermes model set ...' don't exist — hermes model is interactive only. - tui.md: busy_indicator -> tui_status_indicator with values kaomoji|emoji|unicode|ascii (not kawaii|minimal|dots|wings|none). - security.md: SSH backend keys (TERMINAL_SSH_HOST/USER/KEY) live in .env, not config.yaml. - windows-wsl-quickstart.md: there is no 'hermes api' subcommand — the OpenAI-compatible API server runs inside hermes gateway. user-guide/features/ - computer-use.md: approvals.mode (not security.approval_level); fix broken ./browser-use.md link to ./browser.md. - fallback-providers.md: top-level fallback_providers (not model.fallback_providers); the picker is subcommand-based, not modal. - api-server.md: API_SERVER_* are env vars — write to per-profile .env, not 'hermes config set' which targets YAML. - web-search.md: drop web_crawl as a registered tool (it isn't); deep-crawl modes are exposed through web_extract. - kanban.md: failure_limit default is 2, not '~5'. - plugins.md: drop hard-coded '33 providers' count. - honcho.md: fix unclosed quote in echo HONCHO_API_KEY snippet; document that 'hermes honcho' subcommand is gated on memory.provider=honcho; reconcile subcommand list with actual --help output. - memory-providers.md: legacy 'hermes honcho setup' redirect documented. Verified via 'npm run build' — site builds cleanly; broken-link count went from 149 to 146 (no regressions, fixed a few in passing). * docs: round 2 audit fixes + regenerate skill catalogs Follow-up to the previous commit on this branch: Round 2 manual fixes: - quickstart.md: KIMI_CODING_API_KEY mentioned alongside KIMI_API_KEY; voice-mode and ACP install commands rewritten — bare 'pip install ...' doesn't work for curl-installed setups (no pip on PATH, not in repo dir); replaced with 'cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"'. ACP already ships in [all] so the curl install includes it. - cli.md / configuration.md: 'auxiliary.compression.model' shown as 'google/gemini-3-flash-preview' (the doc's own claimed default); actual default is empty (= use main model). Reworded as 'leave empty (default) or pin a cheap model'. - built-in-plugins.md: added the bundled 'kanban/dashboard' plugin row that was missing from the table. Regenerated skill catalogs: - ran website/scripts/generate-skill-docs.py to refresh all 163 per-skill pages and both reference catalogs (skills-catalog.md, optional-skills-catalog.md). This adds the entries that were genuinely missing — productivity/teams-meeting-pipeline (bundled), optional/finance/* (entire category — 7 skills: 3-statement-model, comps-analysis, dcf-model, excel-author, lbo-model, merger-model, pptx-author), creative/hyperframes, creative/kanban-video-orchestrator, devops/watchers, productivity/shop-app, research/searxng-search, apple/macos-computer-use — and rewrites every other per-skill page from the current SKILL.md. Most diffs are tiny (one line of refreshed metadata). Validation: - 'npm run build' succeeded. - Broken-link count moved 146 -> 155 — the +9 are zh-Hans translation shells that lag every newly-added skill page (pre-existing pattern). No regressions on any en/ page.
2026-05-09 13:19:51 -07:00
This page documents Hermes' built-in tools, grouped by toolset. Availability varies by platform, credentials, and enabled toolsets.
docs: comprehensive documentation audit — fix stale info, expand thin pages, add depth (#5393) Major changes across 20 documentation pages: Staleness fixes: - Fix FAQ: wrong import path (hermes.agent → run_agent) - Fix FAQ: stale Gemini 2.0 model → Gemini 3 Flash - Fix integrations/index: missing MiniMax TTS provider - Fix integrations/index: web_crawl is not a registered tool - Fix sessions: add all 19 session sources (was only 5) - Fix cron: add all 18 delivery targets (was only telegram/discord) - Fix webhooks: add all delivery targets - Fix overview: add missing MCP, memory providers, credential pools - Fix all line-number references → use function name searches instead - Update file size estimates (run_agent ~9200, gateway ~7200, cli ~8500) Expanded thin pages (< 150 lines → substantial depth): - honcho.md: 43 → 108 lines — added feature comparison, tools, config, CLI - overview.md: 49 → 55 lines — added MCP, memory providers, credential pools - toolsets-reference.md: 57 → 175 lines — added explanations, config examples, custom toolsets, wildcards, platform differences table - optional-skills-catalog.md: 74 → 153 lines — added 25+ missing skills across communication, devops, mlops (18!), productivity, research categories - integrations/index.md: 82 → 115 lines — added messaging, HA, plugins sections - cron-internals.md: 90 → 195 lines — added job JSON example, lifecycle states, tick cycle, delivery targets, script-backed jobs, CLI interface - gateway-internals.md: 111 → 250 lines — added architecture diagram, message flow, two-level guard, platform adapters, token locks, process management - agent-loop.md: 112 → 235 lines — added entry points, API mode resolution, turn lifecycle detail, message alternation rules, tool execution flow, callback table, budget tracking, compression details - architecture.md: 152 → 295 lines — added system overview diagram, data flow diagrams, design principles table, dependency chain Other depth additions: - context-references.md: added platform availability, compression interaction, common patterns sections - slash-commands.md: added quick commands config example, alias resolution - image-generation.md: added platform delivery table - tools-reference.md: added tool counts, MCP tools note - index.md: updated platform count (5 → 14+), tool count (40+ → 47)
2026-04-05 19:45:50 -07:00
**Quick counts (current registry):** ~85 tools — 4 browser tools (`browser_exec`, `browser_cdp`, `browser_dialog`, `browser_vault`), 4 file tools, 2 terminal tools (`terminal`, `process_manage`), 11 desktop-GUI tools (`read_terminal`, `close_terminal`, `desktop_preview`, `drive_preview`, `annotate_preview`, `read_window_below`, `focus_pane`, `react_to_message`, `gui_tour`, `show_tip`, `set_theme` — desktop-app sessions only), 2 web tools, 5 Feishu tools, 5 Yuanbao tools, 14 kanban tools (registered when the kanban dispatcher spawns the agent), 1 project tool (`desktop_project`; desktop/GUI sessions), 2 Discord tools, 3 video tools (`video_generate`, `xai_video_edit`, `xai_video_extend`), and a handful of standalone tools (`memory`, `clarify`, `delegate_task`, `execute_code`, `cronjob_manage`, `session_search`, `skill_view`/`skill_manage`/`skills_list`, `text_to_speech`, `image_generate`, `vision_analyze`, `video_analyze`, `todo_list`, `computer_use`, `x_search`).
docs: comprehensive documentation audit — fix stale info, expand thin pages, add depth (#5393) Major changes across 20 documentation pages: Staleness fixes: - Fix FAQ: wrong import path (hermes.agent → run_agent) - Fix FAQ: stale Gemini 2.0 model → Gemini 3 Flash - Fix integrations/index: missing MiniMax TTS provider - Fix integrations/index: web_crawl is not a registered tool - Fix sessions: add all 19 session sources (was only 5) - Fix cron: add all 18 delivery targets (was only telegram/discord) - Fix webhooks: add all delivery targets - Fix overview: add missing MCP, memory providers, credential pools - Fix all line-number references → use function name searches instead - Update file size estimates (run_agent ~9200, gateway ~7200, cli ~8500) Expanded thin pages (< 150 lines → substantial depth): - honcho.md: 43 → 108 lines — added feature comparison, tools, config, CLI - overview.md: 49 → 55 lines — added MCP, memory providers, credential pools - toolsets-reference.md: 57 → 175 lines — added explanations, config examples, custom toolsets, wildcards, platform differences table - optional-skills-catalog.md: 74 → 153 lines — added 25+ missing skills across communication, devops, mlops (18!), productivity, research categories - integrations/index.md: 82 → 115 lines — added messaging, HA, plugins sections - cron-internals.md: 90 → 195 lines — added job JSON example, lifecycle states, tick cycle, delivery targets, script-backed jobs, CLI interface - gateway-internals.md: 111 → 250 lines — added architecture diagram, message flow, two-level guard, platform adapters, token locks, process management - agent-loop.md: 112 → 235 lines — added entry points, API mode resolution, turn lifecycle detail, message alternation rules, tool execution flow, callback table, budget tracking, compression details - architecture.md: 152 → 295 lines — added system overview diagram, data flow diagrams, design principles table, dependency chain Other depth additions: - context-references.md: added platform availability, compression interaction, common patterns sections - slash-commands.md: added quick commands config example, alias resolution - image-generation.md: added platform delivery table - tools-reference.md: added tool counts, MCP tools note - index.md: updated platform count (5 → 14+), tool count (40+ → 47)
2026-04-05 19:45:50 -07:00
:::tip MCP Tools
In addition to built-in tools, Hermes can load tools dynamically from MCP servers. MCP tools appear with the prefix `mcp__<server>__` (e.g., `mcp__github__create_issue` for the `github` MCP server). See [MCP Integration](../user-guide/features/mcp.md) for configuration.
docs: comprehensive documentation audit — fix stale info, expand thin pages, add depth (#5393) Major changes across 20 documentation pages: Staleness fixes: - Fix FAQ: wrong import path (hermes.agent → run_agent) - Fix FAQ: stale Gemini 2.0 model → Gemini 3 Flash - Fix integrations/index: missing MiniMax TTS provider - Fix integrations/index: web_crawl is not a registered tool - Fix sessions: add all 19 session sources (was only 5) - Fix cron: add all 18 delivery targets (was only telegram/discord) - Fix webhooks: add all delivery targets - Fix overview: add missing MCP, memory providers, credential pools - Fix all line-number references → use function name searches instead - Update file size estimates (run_agent ~9200, gateway ~7200, cli ~8500) Expanded thin pages (< 150 lines → substantial depth): - honcho.md: 43 → 108 lines — added feature comparison, tools, config, CLI - overview.md: 49 → 55 lines — added MCP, memory providers, credential pools - toolsets-reference.md: 57 → 175 lines — added explanations, config examples, custom toolsets, wildcards, platform differences table - optional-skills-catalog.md: 74 → 153 lines — added 25+ missing skills across communication, devops, mlops (18!), productivity, research categories - integrations/index.md: 82 → 115 lines — added messaging, HA, plugins sections - cron-internals.md: 90 → 195 lines — added job JSON example, lifecycle states, tick cycle, delivery targets, script-backed jobs, CLI interface - gateway-internals.md: 111 → 250 lines — added architecture diagram, message flow, two-level guard, platform adapters, token locks, process management - agent-loop.md: 112 → 235 lines — added entry points, API mode resolution, turn lifecycle detail, message alternation rules, tool execution flow, callback table, budget tracking, compression details - architecture.md: 152 → 295 lines — added system overview diagram, data flow diagrams, design principles table, dependency chain Other depth additions: - context-references.md: added platform availability, compression interaction, common patterns sections - slash-commands.md: added quick commands config example, alias resolution - image-generation.md: added platform delivery table - tools-reference.md: added tool counts, MCP tools note - index.md: updated platform count (5 → 14+), tool count (40+ → 47)
2026-04-05 19:45:50 -07:00
:::
## `browser` toolset
`browser_exec` and `browser_vault` drive the browser session — the Chromium Hermes launches, a cloud browser, or the browser attached with `/browser connect`. `browser_cdp` and `browser_dialog` are offered only while a CDP endpoint is configured (`/browser connect`, `BROWSER_CDP_URL` or `browser.cdp_url`) and act on that browser; they are absent for launched and cloud sessions. See [Browser Automation](../user-guide/features/browser.md).
docs: resync reference, user-guide, developer-guide, and messaging pages against code (#17738) Broad drift audit against origin/main (b52b63396). Reference pages (most user-visible drift): - slash-commands: add /busy, /curator, /footer, /indicator, /redraw, /steer that were missing; drop non-existent /terminal-setup; fix /q footnote (resolves to /queue, not /quit); extend CLI-only list with all 24 CLI-only commands in the registry - cli-commands: add dedicated sections for hermes curator / fallback / hooks (new subcommands not previously documented); remove stale hermes honcho standalone section (the plugin registers dynamically via hermes memory); list curator/fallback/hooks in top-level table; fix completion to include fish - toolsets-reference: document the real 52-toolset count; split browser vs browser-cdp; add discord / discord_admin / spotify / yuanbao; correct hermes-cli tool count from 36 to 38; fix misleading claim that hermes-homeassistant adds tools (it's identical to hermes-cli) - tools-reference: bump tool count 55 -> 68; add 7 Spotify, 5 Yuanbao, 2 Discord toolsets; move browser_cdp/browser_dialog to their own browser-cdp toolset section - environment-variables: add 40+ user-facing HERMES_* vars that were undocumented (--yolo, --accept-hooks, --ignore-*, inference model override, agent/stream/checkpoint timeouts, OAuth trace, per-platform batch tuning for Telegram/Discord/Matrix/Feishu/WeCom, cron knobs, gateway restart/connect timeouts); dedupe the Cron Scheduler section; replace stale QQ_SANDBOX with QQ_PORTAL_HOST User-guide (top level): - cli.md: compression preserves last 20 turns, not 4 (protect_last_n: 20) - configuration.md: display.platforms is the canonical per-platform override key; tool_progress_overrides is deprecated and auto-migrated - profiles.md: model.default is the config key, not model.model - sessions.md: CLI/TUI session IDs use 6-char hex, gateway uses 8 - checkpoints-and-rollback.md: destructive-command list now matches _DESTRUCTIVE_PATTERNS (adds rmdir, cp, install, dd) - docker.md: the container runs as non-root hermes (UID 10000) via gosu; fix install command (uv pip); add missing --insecure on the dashboard compose example (required for non-loopback bind) - security.md: systemctl danger pattern also matches 'restart' - index.md: built-in tool count 47 -> 68 - integrations/index.md: 6 STT providers, 8 memory providers - integrations/providers.md: drop fictional dashscope/qwen aliases Features: - overview.md: 9 image models (not 8), 9 TTS providers (not 5), 8 memory providers (Supermemory was missing) - tool-gateway.md: 9 image models - tools.md: extend common-toolsets list with search / messaging / spotify / discord / debugging / safe - fallback-providers.md: add 6 real providers from PROVIDER_REGISTRY (lmstudio, kimi-coding-cn, stepfun, alibaba-coding-plan, tencent-tokenhub, azure-foundry) - plugins.md: Available Hooks table now includes on_session_finalize, on_session_reset, subagent_stop - built-in-plugins.md: add the 7 bundled plugins the page didn't mention (spotify, google_meet, three image_gen providers, two dashboard examples) - web-dashboard.md: add --insecure and --tui flags - cron.md: hermes cron create takes positional schedule/prompt, not flags Messaging: - telegram.md: TELEGRAM_WEBHOOK_SECRET is now REQUIRED when TELEGRAM_WEBHOOK_URL is set (gateway refuses to start without it per GHSA-3vpc-7q5r-276h). Biggest user-visible drift in the batch. - discord.md: HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS default is 2.0, not 0.1 - dingtalk.md: document DINGTALK_REQUIRE_MENTION / FREE_RESPONSE_CHATS / MENTION_PATTERNS / HOME_CHANNEL / ALLOW_ALL_USERS that the adapter supports - bluebubbles.md: drop fictional BLUEBUBBLES_SEND_READ_RECEIPTS env var; the setting lives in platforms.bluebubbles.extra only - qqbot.md: drop dead QQ_SANDBOX; add real QQ_PORTAL_HOST and QQ_GROUP_ALLOWED_USERS - wecom-callback.md: replace 'hermes gateway start' (service-only) with 'hermes gateway' for first-time setup Developer-guide: - architecture.md: refresh tool/toolset counts (61/52), terminal backend count (7), line counts for run_agent.py (~13.7k), cli.py (~11.5k), main.py (~10.4k), setup.py (~3.5k), gateway/run.py (~12.2k), mcp_tool.py (~3.1k); add yuanbao adapter, bump platform adapter count 18 -> 20 - agent-loop.md: run_agent.py line count 10.7k -> 13.7k - tools-runtime.md: add vercel_sandbox backend - adding-tools.md: remove stale 'Discovery import added to model_tools.py' checklist item (registry auto-discovery) - adding-platform-adapters.md: mark send_typing / get_chat_info as concrete base methods; only connect/disconnect/send are abstract - acp-internals.md: ACP sessions now persist to SessionDB (~/.hermes/state.db); acp.run_agent call uses use_unstable_protocol=True - cron-internals.md: gateway runs scheduler in a dedicated background thread via _start_cron_ticker, not on a maintenance cycle; locking is cross-process via fcntl.flock (Unix) / msvcrt.locking (Windows) - gateway-internals.md: gateway/run.py ~12k lines - provider-runtime.md: cron DOES support fallback (run_job reads fallback_providers from config) - session-storage.md: SCHEMA_VERSION = 11 (not 9); add migrations 10 and 11 (trigram FTS, inline-mode FTS5 re-index); add api_call_count column to Sessions DDL; document messages_fts_trigram and state_meta in the architecture tree - context-compression-and-caching.md: remove the obsolete 'context pressure warnings' section (warnings were removed for causing models to give up early) - context-engine-plugin.md: compress() signature now includes focus_topic param - extending-the-cli.md: _build_tui_layout_children signature now includes model_picker_widget; add to default layout Also fixed three pre-existing broken links/anchors the build warned about (docker.md -> api-server.md, yuanbao.md -> cron-jobs.md and tips#background-tasks, nix-setup.md -> #container-aware-cli). Regenerated per-skill pages via website/scripts/generate-skill-docs.py so catalog tables and sidebar are consistent with current SKILL.md frontmatter. docusaurus build: clean, no broken links or anchors.
2026-04-29 20:55:59 -07:00
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `browser_exec` | Drive a real web browser by running Python with pre-imported helpers (`new_tab`, `goto_url`, `wait_for_load`, `page_info`, `js`, `fill_input`, `click_at_xy`, `capture_screenshot`, `cdp`, `ensure_real_tab`). Browser state persists across calls; Python variables do not. `session` isolates concurrent work; `timeout_s` defaults to 300 (max 1800). | `terminal` toolset |
| `browser_cdp` | Send a raw Chrome DevTools Protocol command. Escape hatch for browser operations the `browser_exec` helpers don't cover. See https://chromedevtools.github.io/devtools-protocol/ | CDP endpoint |
| `browser_dialog` | Respond to a native JavaScript dialog (alert / confirm / prompt / beforeunload) blocking the page: `browser_dialog(action='accept'\|'dismiss')`, with `prompt_text` for `prompt()` and `dialog_id` when several are queued. | CDP endpoint |
| `browser_vault` | Use saved logins, passwords, cards, addresses and one-time codes on the current page without secrets entering the conversation. Actions: `list`, `fill`, `save_login`, `enter_code`, `unlock`. | — |
docs: resync reference, user-guide, developer-guide, and messaging pages against code (#17738) Broad drift audit against origin/main (b52b63396). Reference pages (most user-visible drift): - slash-commands: add /busy, /curator, /footer, /indicator, /redraw, /steer that were missing; drop non-existent /terminal-setup; fix /q footnote (resolves to /queue, not /quit); extend CLI-only list with all 24 CLI-only commands in the registry - cli-commands: add dedicated sections for hermes curator / fallback / hooks (new subcommands not previously documented); remove stale hermes honcho standalone section (the plugin registers dynamically via hermes memory); list curator/fallback/hooks in top-level table; fix completion to include fish - toolsets-reference: document the real 52-toolset count; split browser vs browser-cdp; add discord / discord_admin / spotify / yuanbao; correct hermes-cli tool count from 36 to 38; fix misleading claim that hermes-homeassistant adds tools (it's identical to hermes-cli) - tools-reference: bump tool count 55 -> 68; add 7 Spotify, 5 Yuanbao, 2 Discord toolsets; move browser_cdp/browser_dialog to their own browser-cdp toolset section - environment-variables: add 40+ user-facing HERMES_* vars that were undocumented (--yolo, --accept-hooks, --ignore-*, inference model override, agent/stream/checkpoint timeouts, OAuth trace, per-platform batch tuning for Telegram/Discord/Matrix/Feishu/WeCom, cron knobs, gateway restart/connect timeouts); dedupe the Cron Scheduler section; replace stale QQ_SANDBOX with QQ_PORTAL_HOST User-guide (top level): - cli.md: compression preserves last 20 turns, not 4 (protect_last_n: 20) - configuration.md: display.platforms is the canonical per-platform override key; tool_progress_overrides is deprecated and auto-migrated - profiles.md: model.default is the config key, not model.model - sessions.md: CLI/TUI session IDs use 6-char hex, gateway uses 8 - checkpoints-and-rollback.md: destructive-command list now matches _DESTRUCTIVE_PATTERNS (adds rmdir, cp, install, dd) - docker.md: the container runs as non-root hermes (UID 10000) via gosu; fix install command (uv pip); add missing --insecure on the dashboard compose example (required for non-loopback bind) - security.md: systemctl danger pattern also matches 'restart' - index.md: built-in tool count 47 -> 68 - integrations/index.md: 6 STT providers, 8 memory providers - integrations/providers.md: drop fictional dashscope/qwen aliases Features: - overview.md: 9 image models (not 8), 9 TTS providers (not 5), 8 memory providers (Supermemory was missing) - tool-gateway.md: 9 image models - tools.md: extend common-toolsets list with search / messaging / spotify / discord / debugging / safe - fallback-providers.md: add 6 real providers from PROVIDER_REGISTRY (lmstudio, kimi-coding-cn, stepfun, alibaba-coding-plan, tencent-tokenhub, azure-foundry) - plugins.md: Available Hooks table now includes on_session_finalize, on_session_reset, subagent_stop - built-in-plugins.md: add the 7 bundled plugins the page didn't mention (spotify, google_meet, three image_gen providers, two dashboard examples) - web-dashboard.md: add --insecure and --tui flags - cron.md: hermes cron create takes positional schedule/prompt, not flags Messaging: - telegram.md: TELEGRAM_WEBHOOK_SECRET is now REQUIRED when TELEGRAM_WEBHOOK_URL is set (gateway refuses to start without it per GHSA-3vpc-7q5r-276h). Biggest user-visible drift in the batch. - discord.md: HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS default is 2.0, not 0.1 - dingtalk.md: document DINGTALK_REQUIRE_MENTION / FREE_RESPONSE_CHATS / MENTION_PATTERNS / HOME_CHANNEL / ALLOW_ALL_USERS that the adapter supports - bluebubbles.md: drop fictional BLUEBUBBLES_SEND_READ_RECEIPTS env var; the setting lives in platforms.bluebubbles.extra only - qqbot.md: drop dead QQ_SANDBOX; add real QQ_PORTAL_HOST and QQ_GROUP_ALLOWED_USERS - wecom-callback.md: replace 'hermes gateway start' (service-only) with 'hermes gateway' for first-time setup Developer-guide: - architecture.md: refresh tool/toolset counts (61/52), terminal backend count (7), line counts for run_agent.py (~13.7k), cli.py (~11.5k), main.py (~10.4k), setup.py (~3.5k), gateway/run.py (~12.2k), mcp_tool.py (~3.1k); add yuanbao adapter, bump platform adapter count 18 -> 20 - agent-loop.md: run_agent.py line count 10.7k -> 13.7k - tools-runtime.md: add vercel_sandbox backend - adding-tools.md: remove stale 'Discovery import added to model_tools.py' checklist item (registry auto-discovery) - adding-platform-adapters.md: mark send_typing / get_chat_info as concrete base methods; only connect/disconnect/send are abstract - acp-internals.md: ACP sessions now persist to SessionDB (~/.hermes/state.db); acp.run_agent call uses use_unstable_protocol=True - cron-internals.md: gateway runs scheduler in a dedicated background thread via _start_cron_ticker, not on a maintenance cycle; locking is cross-process via fcntl.flock (Unix) / msvcrt.locking (Windows) - gateway-internals.md: gateway/run.py ~12k lines - provider-runtime.md: cron DOES support fallback (run_job reads fallback_providers from config) - session-storage.md: SCHEMA_VERSION = 11 (not 9); add migrations 10 and 11 (trigram FTS, inline-mode FTS5 re-index); add api_call_count column to Sessions DDL; document messages_fts_trigram and state_meta in the architecture tree - context-compression-and-caching.md: remove the obsolete 'context pressure warnings' section (warnings were removed for causing models to give up early) - context-engine-plugin.md: compress() signature now includes focus_topic param - extending-the-cli.md: _build_tui_layout_children signature now includes model_picker_widget; add to default layout Also fixed three pre-existing broken links/anchors the build warned about (docker.md -> api-server.md, yuanbao.md -> cron-jobs.md and tips#background-tasks, nix-setup.md -> #container-aware-cli). Regenerated per-skill pages via website/scripts/generate-skill-docs.py so catalog tables and sidebar are consistent with current SKILL.md frontmatter. docusaurus build: clean, no broken links or anchors.
2026-04-29 20:55:59 -07:00
## `clarify` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
Clarify: one question shape and one result shape on every surface (skip, cancel, timeout and undelivered are told apart) (#127760) * refactor(desktop): split clarify-tool.tsx into a clarify/ folder Pure moves, no behaviour change. Parsing, the question-card core (shell, choice rows, question block), the delivery watchdog, and each pending/settled card get their own file so the core can be reused. * feat(clarify): one questions[] shape with per-question status and one outcome The clarify tool now takes only questions=[{question, choices?, multi_select?}]. A wrong shape is a tool error that names the right one, so a model that sends the old top-level question/choices corrects itself on the next call. Every result has the same shape on every surface: each response carries status (answered, skipped, unanswered) with user_response null unless answered, and the result carries one outcome (submitted, cancelled, timed_out, undelivered) plus an optional surface-written notice. The timeout and cancel sentences that used to pose as the user's answer are gone, and the compressor reads status instead of matching their prefixes. The callback contract is callback(questions) -> {answers, outcome, notice?} (None = skipped, missing qid = unanswered). tui_gateway settles a batch the same way for the last lock, a cancel, an interrupt and the deadline, and clarify.lock keeps a null answer as a skip. A multi-select answer that is not a JSON array counts as one typed ("Other") answer. The tool-row preview reads the first question. * feat(clarify): every surface asks through the one question card CLI: the batch panel is the only panel; Enter on an empty field skips a question, Ctrl+C cancels and keeps the locked answers, the deadline returns timed_out. -q and -z return undelivered with a no-user notice. Ink TUI: the single-question prompt is gone; the card supports multi-select (Space or a digit toggles, Enter locks, typed Other text joins the picks), an empty submit skips, Esc cancels, and "Batch" names are dropped. Desktop: the single-question card is deleted and its keyboard handling moved into the one card (arrows, letters and digits, auto-advance, Enter picks then confirms). Confirm enables at one answer; blank questions lock null; Skip and a composer message cancel; the settled card shows No answer for unanswered questions. The bots room card follows the same contract. Messaging: one card per question with a "Reply skip to skip" line in every locale; timeouts and delivery failures map to timed_out and undelivered. * fix(clarify): cancelled for a released messaging card, labels win over the skip word A prose reply to a messaging choice card, /new and session end released the wait with "", which read as timed_out. They now resolve with a CANCELLED marker and the tool gets outcome cancelled. A typed reply that matches a choice label ("Skip") now resolves to that choice; the skip word applies only when no choice matches. The bots room card sends the picked labels as they are; the tool already strips the recommendation label. Unused OUTCOMES and a new docstring and comment are removed. * fix(tui): re-editing a multi-select answer keeps its picks The Ink card stored a multi-select answer as display text ("A, B"), so revisiting the question put the whole string into Other and re-locked it as one item. The answers map now keeps the raw JSON array, the card restores the picks on revisit, and only the display lines format it. Comments that earlier edits reworded are restored to their original words, minus the phrases the change made wrong. The compute-host clarify lock accepts None for a skipped question. * test(clarify): align three checks with the one-answer confirm and the regenerated keys The desktop Cmd+Enter test now expects a send with one answer (the blank question locks null), the compressor test expects the single-answer summary the code gives, and locales/_keys.desktop.json is regenerated for the removed and added clarify strings. * test(tui): the one-question card header is singular
2026-09-29 18:33:44 +05:30
| `clarify` | Ask the user one or more questions when you need clarification, feedback, or a decision before proceeding. Every call passes `questions`, an array of 1–5 entries (a single question is a one-entry array). Each question supports three modes: 1. **Single-select multiple choice** — up to 4 choices; the user picks one or types their own answer via a 5th 'Other' option. 2. **Multi-select multiple choice** — `multi_select=true` renders checkboxes and returns a list of selected choices. 3. **Open-ended** — no choices; the user types a free-form response. Choices are ordered best-first, so the first one is labelled `(Recommended)` on every surface and is the default highlight; the label is presentation only and is stripped from the answer the agent reads. On the classic CLI multi-select uses Space-to-toggle checkboxes; on messaging platforms without native checkbox UIs the user replies with comma/space-separated numbers (e.g. "1, 3") or the option text. | — |
### Asking multiple questions at once
Clarify: one question shape and one result shape on every surface (skip, cancel, timeout and undelivered are told apart) (#127760) * refactor(desktop): split clarify-tool.tsx into a clarify/ folder Pure moves, no behaviour change. Parsing, the question-card core (shell, choice rows, question block), the delivery watchdog, and each pending/settled card get their own file so the core can be reused. * feat(clarify): one questions[] shape with per-question status and one outcome The clarify tool now takes only questions=[{question, choices?, multi_select?}]. A wrong shape is a tool error that names the right one, so a model that sends the old top-level question/choices corrects itself on the next call. Every result has the same shape on every surface: each response carries status (answered, skipped, unanswered) with user_response null unless answered, and the result carries one outcome (submitted, cancelled, timed_out, undelivered) plus an optional surface-written notice. The timeout and cancel sentences that used to pose as the user's answer are gone, and the compressor reads status instead of matching their prefixes. The callback contract is callback(questions) -> {answers, outcome, notice?} (None = skipped, missing qid = unanswered). tui_gateway settles a batch the same way for the last lock, a cancel, an interrupt and the deadline, and clarify.lock keeps a null answer as a skip. A multi-select answer that is not a JSON array counts as one typed ("Other") answer. The tool-row preview reads the first question. * feat(clarify): every surface asks through the one question card CLI: the batch panel is the only panel; Enter on an empty field skips a question, Ctrl+C cancels and keeps the locked answers, the deadline returns timed_out. -q and -z return undelivered with a no-user notice. Ink TUI: the single-question prompt is gone; the card supports multi-select (Space or a digit toggles, Enter locks, typed Other text joins the picks), an empty submit skips, Esc cancels, and "Batch" names are dropped. Desktop: the single-question card is deleted and its keyboard handling moved into the one card (arrows, letters and digits, auto-advance, Enter picks then confirms). Confirm enables at one answer; blank questions lock null; Skip and a composer message cancel; the settled card shows No answer for unanswered questions. The bots room card follows the same contract. Messaging: one card per question with a "Reply skip to skip" line in every locale; timeouts and delivery failures map to timed_out and undelivered. * fix(clarify): cancelled for a released messaging card, labels win over the skip word A prose reply to a messaging choice card, /new and session end released the wait with "", which read as timed_out. They now resolve with a CANCELLED marker and the tool gets outcome cancelled. A typed reply that matches a choice label ("Skip") now resolves to that choice; the skip word applies only when no choice matches. The bots room card sends the picked labels as they are; the tool already strips the recommendation label. Unused OUTCOMES and a new docstring and comment are removed. * fix(tui): re-editing a multi-select answer keeps its picks The Ink card stored a multi-select answer as display text ("A, B"), so revisiting the question put the whole string into Other and re-locked it as one item. The answers map now keeps the raw JSON array, the card restores the picks on revisit, and only the display lines format it. Comments that earlier edits reworded are restored to their original words, minus the phrases the change made wrong. The compute-host clarify lock accepts None for a skipped question. * test(clarify): align three checks with the one-answer confirm and the regenerated keys The desktop Cmd+Enter test now expects a send with one answer (the blank question locks null), the compressor test expects the single-answer summary the code gives, and locales/_keys.desktop.json is regenerated for the removed and added clarify strings. * test(tui): the one-question card header is singular
2026-09-29 18:33:44 +05:30
The `clarify` tool takes a `questions` array (1–5 independent questions, each with its own `choices` and `multi_select`) so the agent can batch several clarification needs into a single prompt instead of asking sequentially. The result is `{responses, outcome}`: a `responses` array in the same order, each entry with the question text, `choices_offered`, a `status` (`answered`, `skipped` or `unanswered`) and `user_response` (null unless answered). `outcome` is `submitted`, `cancelled`, `timed_out` or `undelivered`.
Per-surface behavior:
Clarify: one question shape and one result shape on every surface (skip, cancel, timeout and undelivered are told apart) (#127760) * refactor(desktop): split clarify-tool.tsx into a clarify/ folder Pure moves, no behaviour change. Parsing, the question-card core (shell, choice rows, question block), the delivery watchdog, and each pending/settled card get their own file so the core can be reused. * feat(clarify): one questions[] shape with per-question status and one outcome The clarify tool now takes only questions=[{question, choices?, multi_select?}]. A wrong shape is a tool error that names the right one, so a model that sends the old top-level question/choices corrects itself on the next call. Every result has the same shape on every surface: each response carries status (answered, skipped, unanswered) with user_response null unless answered, and the result carries one outcome (submitted, cancelled, timed_out, undelivered) plus an optional surface-written notice. The timeout and cancel sentences that used to pose as the user's answer are gone, and the compressor reads status instead of matching their prefixes. The callback contract is callback(questions) -> {answers, outcome, notice?} (None = skipped, missing qid = unanswered). tui_gateway settles a batch the same way for the last lock, a cancel, an interrupt and the deadline, and clarify.lock keeps a null answer as a skip. A multi-select answer that is not a JSON array counts as one typed ("Other") answer. The tool-row preview reads the first question. * feat(clarify): every surface asks through the one question card CLI: the batch panel is the only panel; Enter on an empty field skips a question, Ctrl+C cancels and keeps the locked answers, the deadline returns timed_out. -q and -z return undelivered with a no-user notice. Ink TUI: the single-question prompt is gone; the card supports multi-select (Space or a digit toggles, Enter locks, typed Other text joins the picks), an empty submit skips, Esc cancels, and "Batch" names are dropped. Desktop: the single-question card is deleted and its keyboard handling moved into the one card (arrows, letters and digits, auto-advance, Enter picks then confirms). Confirm enables at one answer; blank questions lock null; Skip and a composer message cancel; the settled card shows No answer for unanswered questions. The bots room card follows the same contract. Messaging: one card per question with a "Reply skip to skip" line in every locale; timeouts and delivery failures map to timed_out and undelivered. * fix(clarify): cancelled for a released messaging card, labels win over the skip word A prose reply to a messaging choice card, /new and session end released the wait with "", which read as timed_out. They now resolve with a CANCELLED marker and the tool gets outcome cancelled. A typed reply that matches a choice label ("Skip") now resolves to that choice; the skip word applies only when no choice matches. The bots room card sends the picked labels as they are; the tool already strips the recommendation label. Unused OUTCOMES and a new docstring and comment are removed. * fix(tui): re-editing a multi-select answer keeps its picks The Ink card stored a multi-select answer as display text ("A, B"), so revisiting the question put the whole string into Other and re-locked it as one item. The answers map now keeps the raw JSON array, the card restores the picks on revisit, and only the display lines format it. Comments that earlier edits reworded are restored to their original words, minus the phrases the change made wrong. The compute-host clarify lock accepts None for a skipped question. * test(clarify): align three checks with the one-answer confirm and the regenerated keys The desktop Cmd+Enter test now expects a send with one answer (the blank question locks null), the compressor test expects the single-answer summary the code gives, and locales/_keys.desktop.json is regenerated for the removed and added clarify strings. * test(tui): the one-question card header is singular
2026-09-29 18:33:44 +05:30
- **Desktop** shows every question on one card. Picks and typed answers stage locally, and one **Confirm and continue** button (enabled once at least one question has an answer) submits the whole batch; blank questions are skipped. Staged answers stay editable until that confirm. Skip cancels the whole batch.
- **TUI and CLI** show a compact status list (`✓` answered / `▸` active / `·` pending) with only the active question's choices expanded. Enter locks the active answer and jumps to the next unanswered question; Tab moves between questions to answer in any order; an empty submit skips that question; Esc cancels the batch.
- **Messaging platforms** (Telegram, Discord, …) ask the questions one at a time, one card per question. Reply `skip` to skip one question. If the user stops responding, the remaining questions are not sent.
Clarify: one question shape and one result shape on every surface (skip, cancel, timeout and undelivered are told apart) (#127760) * refactor(desktop): split clarify-tool.tsx into a clarify/ folder Pure moves, no behaviour change. Parsing, the question-card core (shell, choice rows, question block), the delivery watchdog, and each pending/settled card get their own file so the core can be reused. * feat(clarify): one questions[] shape with per-question status and one outcome The clarify tool now takes only questions=[{question, choices?, multi_select?}]. A wrong shape is a tool error that names the right one, so a model that sends the old top-level question/choices corrects itself on the next call. Every result has the same shape on every surface: each response carries status (answered, skipped, unanswered) with user_response null unless answered, and the result carries one outcome (submitted, cancelled, timed_out, undelivered) plus an optional surface-written notice. The timeout and cancel sentences that used to pose as the user's answer are gone, and the compressor reads status instead of matching their prefixes. The callback contract is callback(questions) -> {answers, outcome, notice?} (None = skipped, missing qid = unanswered). tui_gateway settles a batch the same way for the last lock, a cancel, an interrupt and the deadline, and clarify.lock keeps a null answer as a skip. A multi-select answer that is not a JSON array counts as one typed ("Other") answer. The tool-row preview reads the first question. * feat(clarify): every surface asks through the one question card CLI: the batch panel is the only panel; Enter on an empty field skips a question, Ctrl+C cancels and keeps the locked answers, the deadline returns timed_out. -q and -z return undelivered with a no-user notice. Ink TUI: the single-question prompt is gone; the card supports multi-select (Space or a digit toggles, Enter locks, typed Other text joins the picks), an empty submit skips, Esc cancels, and "Batch" names are dropped. Desktop: the single-question card is deleted and its keyboard handling moved into the one card (arrows, letters and digits, auto-advance, Enter picks then confirms). Confirm enables at one answer; blank questions lock null; Skip and a composer message cancel; the settled card shows No answer for unanswered questions. The bots room card follows the same contract. Messaging: one card per question with a "Reply skip to skip" line in every locale; timeouts and delivery failures map to timed_out and undelivered. * fix(clarify): cancelled for a released messaging card, labels win over the skip word A prose reply to a messaging choice card, /new and session end released the wait with "", which read as timed_out. They now resolve with a CANCELLED marker and the tool gets outcome cancelled. A typed reply that matches a choice label ("Skip") now resolves to that choice; the skip word applies only when no choice matches. The bots room card sends the picked labels as they are; the tool already strips the recommendation label. Unused OUTCOMES and a new docstring and comment are removed. * fix(tui): re-editing a multi-select answer keeps its picks The Ink card stored a multi-select answer as display text ("A, B"), so revisiting the question put the whole string into Other and re-locked it as one item. The answers map now keeps the raw JSON array, the card restores the picks on revisit, and only the display lines format it. Comments that earlier edits reworded are restored to their original words, minus the phrases the change made wrong. The compute-host clarify lock accepts None for a skipped question. * test(clarify): align three checks with the one-answer confirm and the regenerated keys The desktop Cmd+Enter test now expects a send with one answer (the blank question locks null), the compressor test expects the single-answer summary the code gives, and locales/_keys.desktop.json is regenerated for the removed and added clarify strings. * test(tui): the one-question card header is singular
2026-09-29 18:33:44 +05:30
If the prompt times out part-way, answers the user already locked are kept: the tool result carries them with `"outcome": "timed_out"` and marks the rest `"status": "unanswered"`, so the agent can distinguish a deliberate skip from an absent user. On messaging platforms the result also carries a `"notice"` saying why the wait ended (`[user did not respond within Nm]`, or `[clarify prompt could not be delivered]` when the platform rejected the card — Hermes first retries the question as a plain numbered-list message, and only reports this when that fails too; `[clarify prompt could not be delivered: no chat surface]` when the run has no chat to prompt in), so an undelivered prompt is never reported as user inactivity.
manage_connections covers local MCP servers; setup_mcp leaves the schema (NS-867, PR1) (#109517) * feat(connections): manage_connections covers local MCP servers; setup_mcp leaves the schema One model tool now connects the user to apps of both kinds. A target `{"name": "linear", "mcp": true}` is a locally configured MCP server; `install` / `enable` / `authorize` are its verbs. Bare strings and `{"name": ...}` stay managed connectors and that leg is unchanged. MCP targets run through one backend-owned connection operation (tools/connections_tool_operation.py): created with a server-side deadline from the new config key `connections.wait_timeout_seconds` (default 120, floor 5, no ceiling), per-target state, and exactly-once settlement (all resolved / Continue / deadline / interrupt). Unresolved targets freeze as `not_connected` with the settle reason. Why the fold works now: the approval card is reached through `agent.connection_callback` via the agent-level inline executor table, which is the only path that carries a GUI callback. Registry dispatch (every non-GUI surface) settles MCP targets as `unavailable` with the `hermes mcp install / login` hint; managed targets in the same call are unaffected. `setup_mcp` is removed from every advertised toolset and from the deferral list; an inline-table shim keeps calls from conversations opened before this change dispatching (prompt-cache protection). `_LEGACY_TOOL_ALIASES` is not the mechanism: inline tools bypass it. Gateway: `mcp.setup.request/respond` are replaced by `connection.request/respond/expire` (no wire compat; desktop ships with this). The bridge waits exactly the operation's deadline. The `session.resume` snapshot gains `pending_connection` so a reopened window restores the card with the original deadline. `manage_connections` joins `_SEQUENTIAL_DEADLINE_EXEMPT_TOOLS`: the operation owns its wait; the 420s guard must not report `tool_timeout` while the card is live. The portal `check_fn` on the tool is dropped in favour of a handler-level gate on the managed leg, so signed-out sessions can still approve local MCPs. * wip(desktop): connection.request store, resume restore, card routing for MCP targets Renderer half of the setup_mcp fold, first slice: connection-request store (mirrors clarify), connection.request/expire handling, pending_connection resume restore, mcpTargets() + isCardTool(name, args) so MCP-target manage_connections calls classify as cards. Not yet: the card component rewrite (mcp-setup-tool.tsx), mcp-directory.ts removal, vitest, docs. Does not typecheck until the card rewrite lands. * fix(config): hermes update turns on the connections toolset for saved toolset lists `hermes tools` writes an explicit `platform_toolsets.<platform>` list, and the resolver reads absence from that list as "unchecked". The `connections` toolset (#106842) shipped after most users last saved, so `manage_connections` is stripped from the schema on every install that ever opened the picker. The Nous entitlement gate never runs; the agent reports the tool as missing. Migration 44 -> 45 (renumbered when folded into #109517; main was already at 44) appends `connections` to each explicit per-platform list that lacks it and records the offer in `known_builtin_toolsets` where that record exists, so a later uncheck reads as a decline. It skips: platforms whose record already holds `connections` (the user saw the checkbox and left it off), bare composite lists ([hermes-cli]) that already inherit it, platforms where the toolset is not allowed, and any config whose `agent.disabled_toolsets` names `connections` (Blank Slate, `hermes tools --disable`), because the resolver subtracts that list last and the enable would never take effect. The explicit-list test is the resolver's own: any configurable or plugin key. `hermes update` runs migrations post-pull for the active profile and every sibling, so one update is enough. Fresh installs and composite users were never affected. * refactor: anti-slop pass on the desktop slice; shorten added comments Parse connection.request at the boundary with a typed wire interface instead of unknown + typeof; mcpTargets reuses connectorText; comments cut to one or two lines. slop-ratchet: no net-new findings in 13 touched files. * feat(desktop): the MCP approval card answers manage_connections; MCP Directory removed The existing card (mcp-setup-tool.tsx) now reads the connection-request store, renders for manage_connections calls with mcp:true targets, answers through connection.respond with a per-target outcome, and no longer calls reload.mcp after Install; the new server's tools arrive on the between-turns refresh. A settled operation renders the first target's frozen state. session.resume restores a pending card with its original deadline on both the activate and cold-resume paths. lib/mcp-directory.ts is deleted along with its two fallback branches (suggestion provider, card install). The catalog was already primary in both; a catalog miss now yields no suggestion / a notInCatalog error. The GitHub never-suggest test is rewritten on catalog-shaped data. vitest: connection-request store (6), suggestion provider, clarify restore. slop-ratchet: no net-new findings in 19 touched files. * chore: drop __pycache__ files swept in by an over-broad git add * fix(desktop): correlate the connection.request row with the model's tool call by reason The synthetic row from connection.request and the tool.start row carried different ids and no shared match value (op_id is not in the model's args), so the card mounted twice. reason is the arg both sides carry. * docs: manage_connections covers local MCP servers; connections.wait_timeout_seconds * fix(connections): settle reason derives from target state, never from the renderer A card that answers one of two targets and claims all_resolved must settle as continue with the other target not_connected; found live with a two-target call. * fix(desktop): a pending connection card re-arms on resume and activate The store entry was restored but the transcript row was not, so navigating away and back (or reloading) lost the card while the backend kept waiting. restorePendingClarifyToolCall's core is generalized to any blocking tool name and both resume paths project the connection row through it. Verified live: card restored after navigate-away and after a full renderer reload, deadline_at unchanged, approve settles connected. * style: literal wording in added comments, docstrings and docs * fix: shared gateway-event contract and config-schema category for the connection events connection.request/expire replace mcp.setup.* in apps/shared gateway-events (json list, BACKEND_EVENT_NAMES, GatewayEventMap) so the renderer's event union includes them and the tui_gateway contract test passes. The new `connections` config section folds into the agent tab like the other single-field sections. * style: import order (perfectionist) in the desktop and shared files this PR touches * chore: retrigger CI (zero-job dispatch failure, auto-heal)
2026-09-15 00:41:13 +05:30
## `connections` toolset
One tool for both kinds of external app. A target is a managed connector (`"gmail"` or
`{"name": "gmail"}`, authorized through the Nous gateway) or a local MCP server
(`{"name": "linear", "mcp": true}`, an entry in `mcp_servers`).
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `manage_connections` | Managed actions: `display` (desktop app only: a card of every hosted connector, most used apps first, where clicking an app starts its sign-in; any `connectors` slugs are pinned at the top as Suggested; it waits until the user presses Continue or 300 seconds pass and returns `connected`, `newly_connected` and `suggested` slugs, and adds `timed_out: true` when the deadline ended it; on other surfaces it returns the `status` list and tells the user to connect from the desktop app or the portal), `status` (each connector lists its `accounts`: alias, label, status, active), `connect`, `reconnect` (repairs only what is not connected; `force: true` restarts a working one), `rename`. A connect or reconnect target may carry an account name (`{"name": "gmail", "alias": "work"}`): connect with a new name adds another account, and reconnect with a name repairs only that account and deletes nothing. `rename` takes one target, `{"name": "gmail", "alias": "work", "to": "office"}`; `alias` may be the app label of an unnamed account. MCP actions, for `mcp: true` targets only: `install` a catalog entry, `enable` a disabled configured server, `authorize` (OAuth). In the desktop app, the terminal UI and the classic CLI every action shows a card and blocks until each target is connected, skipped, or the 300-second deadline passes; the result lists targets as `connected`, `skipped` or `not_connected` and carries no link. An MCP `install` collects the entry's setup values in the card, runs the entry's OAuth from the card when it has one (the user opens the link; nothing opens by itself), and saves configuration, tokens and values together when the server accepts the token. A connected MCP target carries `tools` (the registered names) and `tools_listing`, and those tools are callable through `tool_describe`/`tool_call` in the same turn. A target with `discovery_error` is authorized but its tools could not be listed; call `install` or `authorize` for it again to retry discovery without new consent. On surfaces with no card (messaging, scripted dispatch) managed targets return a `connect_url` per app for the user to open, and an MCP target runs at once: `authorize` and an OAuth `install` return the authorization URL, other installs and `enable` report the outcome, and a missing credential comes back as `failed` naming the variable to set. Cannot disconnect, remove or revoke an account; the user does that. | — |
manage_connections covers local MCP servers; setup_mcp leaves the schema (NS-867, PR1) (#109517) * feat(connections): manage_connections covers local MCP servers; setup_mcp leaves the schema One model tool now connects the user to apps of both kinds. A target `{"name": "linear", "mcp": true}` is a locally configured MCP server; `install` / `enable` / `authorize` are its verbs. Bare strings and `{"name": ...}` stay managed connectors and that leg is unchanged. MCP targets run through one backend-owned connection operation (tools/connections_tool_operation.py): created with a server-side deadline from the new config key `connections.wait_timeout_seconds` (default 120, floor 5, no ceiling), per-target state, and exactly-once settlement (all resolved / Continue / deadline / interrupt). Unresolved targets freeze as `not_connected` with the settle reason. Why the fold works now: the approval card is reached through `agent.connection_callback` via the agent-level inline executor table, which is the only path that carries a GUI callback. Registry dispatch (every non-GUI surface) settles MCP targets as `unavailable` with the `hermes mcp install / login` hint; managed targets in the same call are unaffected. `setup_mcp` is removed from every advertised toolset and from the deferral list; an inline-table shim keeps calls from conversations opened before this change dispatching (prompt-cache protection). `_LEGACY_TOOL_ALIASES` is not the mechanism: inline tools bypass it. Gateway: `mcp.setup.request/respond` are replaced by `connection.request/respond/expire` (no wire compat; desktop ships with this). The bridge waits exactly the operation's deadline. The `session.resume` snapshot gains `pending_connection` so a reopened window restores the card with the original deadline. `manage_connections` joins `_SEQUENTIAL_DEADLINE_EXEMPT_TOOLS`: the operation owns its wait; the 420s guard must not report `tool_timeout` while the card is live. The portal `check_fn` on the tool is dropped in favour of a handler-level gate on the managed leg, so signed-out sessions can still approve local MCPs. * wip(desktop): connection.request store, resume restore, card routing for MCP targets Renderer half of the setup_mcp fold, first slice: connection-request store (mirrors clarify), connection.request/expire handling, pending_connection resume restore, mcpTargets() + isCardTool(name, args) so MCP-target manage_connections calls classify as cards. Not yet: the card component rewrite (mcp-setup-tool.tsx), mcp-directory.ts removal, vitest, docs. Does not typecheck until the card rewrite lands. * fix(config): hermes update turns on the connections toolset for saved toolset lists `hermes tools` writes an explicit `platform_toolsets.<platform>` list, and the resolver reads absence from that list as "unchecked". The `connections` toolset (#106842) shipped after most users last saved, so `manage_connections` is stripped from the schema on every install that ever opened the picker. The Nous entitlement gate never runs; the agent reports the tool as missing. Migration 44 -> 45 (renumbered when folded into #109517; main was already at 44) appends `connections` to each explicit per-platform list that lacks it and records the offer in `known_builtin_toolsets` where that record exists, so a later uncheck reads as a decline. It skips: platforms whose record already holds `connections` (the user saw the checkbox and left it off), bare composite lists ([hermes-cli]) that already inherit it, platforms where the toolset is not allowed, and any config whose `agent.disabled_toolsets` names `connections` (Blank Slate, `hermes tools --disable`), because the resolver subtracts that list last and the enable would never take effect. The explicit-list test is the resolver's own: any configurable or plugin key. `hermes update` runs migrations post-pull for the active profile and every sibling, so one update is enough. Fresh installs and composite users were never affected. * refactor: anti-slop pass on the desktop slice; shorten added comments Parse connection.request at the boundary with a typed wire interface instead of unknown + typeof; mcpTargets reuses connectorText; comments cut to one or two lines. slop-ratchet: no net-new findings in 13 touched files. * feat(desktop): the MCP approval card answers manage_connections; MCP Directory removed The existing card (mcp-setup-tool.tsx) now reads the connection-request store, renders for manage_connections calls with mcp:true targets, answers through connection.respond with a per-target outcome, and no longer calls reload.mcp after Install; the new server's tools arrive on the between-turns refresh. A settled operation renders the first target's frozen state. session.resume restores a pending card with its original deadline on both the activate and cold-resume paths. lib/mcp-directory.ts is deleted along with its two fallback branches (suggestion provider, card install). The catalog was already primary in both; a catalog miss now yields no suggestion / a notInCatalog error. The GitHub never-suggest test is rewritten on catalog-shaped data. vitest: connection-request store (6), suggestion provider, clarify restore. slop-ratchet: no net-new findings in 19 touched files. * chore: drop __pycache__ files swept in by an over-broad git add * fix(desktop): correlate the connection.request row with the model's tool call by reason The synthetic row from connection.request and the tool.start row carried different ids and no shared match value (op_id is not in the model's args), so the card mounted twice. reason is the arg both sides carry. * docs: manage_connections covers local MCP servers; connections.wait_timeout_seconds * fix(connections): settle reason derives from target state, never from the renderer A card that answers one of two targets and claims all_resolved must settle as continue with the other target not_connected; found live with a two-target call. * fix(desktop): a pending connection card re-arms on resume and activate The store entry was restored but the transcript row was not, so navigating away and back (or reloading) lost the card while the backend kept waiting. restorePendingClarifyToolCall's core is generalized to any blocking tool name and both resume paths project the connection row through it. Verified live: card restored after navigate-away and after a full renderer reload, deadline_at unchanged, approve settles connected. * style: literal wording in added comments, docstrings and docs * fix: shared gateway-event contract and config-schema category for the connection events connection.request/expire replace mcp.setup.* in apps/shared gateway-events (json list, BACKEND_EVENT_NAMES, GatewayEventMap) so the renderer's event union includes them and the tui_gateway contract test passes. The new `connections` config section folds into the agent tab like the other single-field sections. * style: import order (perfectionist) in the desktop and shared files this PR touches * chore: retrigger CI (zero-job dispatch failure, auto-heal)
2026-09-15 00:41:13 +05:30
Desktop connect runs on the connection operation: one card, no link to the model, no renderer polling (NS-868) (#110574) * refactor(connectors): cut comments that restate the code Connector modules (tools/connectors, tui_gateway connector RPCs, desktop connector card/store) keep only comments that carry a non-derivable why or a cross-module contract. No behaviour change. * feat(connectors): managed connect runs on the connection operation Managed `connect` / `reconnect` mint one ConnectionOperation for every target and, on a desktop session, block the tool turn until the operation settles; the result is per-target outcomes and never carries a connect link. Off the desktop the result carries the links and returns at once (PR3 delivers them as their own message). Why: the previous leg handed the model a URL and a `wait` verb, and the renderer ran its own 2s poller on top of the backend's 5s one; both walked the whole gateway catalog at two vendor calls per page to read one row (~3 Composio calls/s per pending target). A hidden composer message started the model's `wait` on the user's behalf. None of it was observable from the operation the MCP leg already used. What the operation looks like now: - `contract.py`: TargetState / Actor / SettleReason enums and the `(kind, from) -> {to: actor}` transition table. `operation.transition()` enforces it; a card cannot claim a managed target `connected`, only the backend watcher can. - `live.py`: one open operation per session, found by `op_id`. `connectors.operation.status` reads it, `connection.respond` drives it, `pending_connection` on resume replays it. - `run.py`: the one lifecycle for both target kinds (prepare -> card -> wake/observe loop -> settle -> result). The managed `observe` hook polls the gateway list once per tick for the whole operation; the exact-status route replaces that call when the gateway ships it. - `connection.update` is emitted on every transition and on settlement; registered in the shared event contract with the operation vocabulary typed on the TS side. - `wait`, `_rendered_links`, `_seen_instructions`, the just-minted bounce and `_clamp_timeout` are deleted. `force` on `reconnect` always reinitiates; plain `reconnect` repairs only what the gateway reports disconnected. - `connections.wait_timeout_seconds` is removed from config defaults, the example and the docs. The deadline is `OPERATION_DEADLINE_SECONDS = 300` in `operation.py`; the key was added on this unmerged train so no migration is needed. - Wire model: `statusReason` parsed on connection results; the seven-state `connectionStatus` is typed on list items and an unknown value fails validation; `CONNECTION_REQUIRED` carries `connect_card_available` instead of the link when the session platform is `desktop`. Session platform, not callback presence, decides whether a card exists: the GUI bridge attaches callbacks to every backend session, terminal TUI included. * feat(desktop): connector card subscribes to the connection operation The card renders from the backend's operation instead of driving its own: `connector-flow.ts` (the renderer's 2s `connectors.list` poller, its 120s client deadline and `keepWaiting`) is deleted, and both hidden composer submits in `connector-tool.tsx` go with it. The model is never nudged into a `wait`; the tool call is blocked on the backend until the operation settles. - `connection-request.ts` is the operation store: keyed by `op_id`, one entry per session, `applyOperationStatus` / `applyConnectionUpdate` as pure reducers, `respond` leaves the entry in place (the backend answers with `connection.update`), `ConnectionTargetOutcome` is a discriminated union the backend's transition table accepts. - `input-requests.ts` applies `connection.update`; `connection.expire` and the resume snapshot correlate by `op_id` (a snapshot has no `request_id`). - `ConnectorOffer` renders one `ConnectorCard` per target from a single `Record<ConnectionTargetState, phase>` table; Connect opens the stored link, Try again on failed / expired reissues through `connectors.connect` on the open operation, Not now is a per-target `skipped`, Continue settles. A settled operation renders `ConnectorSummary` rows with no live control. - `tool-render-class.ts`: `manage_connections` renders the card regardless of `HERMES_GUEST_ONBOARDING`; the flag still gates the onboarding flow, not the card. The backend gate already decided admission; a card only exists because the tool was admitted. - `mcp-setup-tool.tsx` speaks the same outcome vocabulary (connected / skipped / failed). - `ConnectorRow.connectionStatus` is the seven-state literal union, not `string | null`. - The guided-onboarding poller (`first-build-connectors.ts`) keeps its own row/phase types and compiles unchanged; PR3 moves it onto the operation. anti-slop: no net-new findings (17 touched files vs 11d1a12472). * fix(connectors): the card never parks the tool thread; every update carries the snapshot Found by the pre-PR adversarial review and a real-path E2E test (both left in the tree). - The desktop `connection_callback` was still `_block("connection.request", ...)`, which parked the tool thread on a private request-id Event until a `_respond` that no longer exists for this event. `connection.respond` settled the operation but the tool waited its full deadline before the watcher loop even started. The callback now only emits the card; the operation's own wake loop is the wait. The MCP leg's blocking bridge goes with it: the card answers through `connection.respond` like every other card. - `connection.request` and every `connection.update` frame carry the full target snapshot (state, link, detail). The initial mint happened before the card existed, so the renderer never saw the links and Connect stayed disabled; a Continue settlement stamped `not_connected` on the backend while the card still showed `initiated`. The store now overlays the snapshot; no state is reconstructed from deltas. - The `connection.update` emitter is a class-level `on_change` slot on the operation, set once by `register()` (a second `register()` no longer stacks wrappers); session lookup takes `_sessions_lock`; a re-minted link on an `initiated` target goes through `refresh_link()` and emits, instead of a bare attribute write. - `session.interrupt` is checked before the first observe, so an interrupted call settles `interrupt`, not `all_resolved`. - A gateway list reporting `expired` for an initiated target is recorded with actor `clock` (the contract's owner of that edge); it raised `IllegalTransition` before. - Dead `keepWaiting` i18n keys from the deleted renderer poller removed. tests/tui_gateway/test_connector_operation_e2e.py runs the desktop lifecycle through the real tool, registry, gateway RPC handlers and callback bridge with only the HTTP client faked. * docs(connectors): prompts and docs describe the operation, not the deleted wait verb The onboarding prompts told the model to call action="wait" with timeout_seconds and to expect a hidden [setup]/[connectors] note; both are gone. tool-search.md and toolsets-reference.md said the model gets a connect link on the desktop. tui_gateway/AGENTS.md gains the connection-operation row of the surface table. * fix(connectors): the panel re-mints only a dead link Try again on a failed or expired target mints a fresh link on the open operation. A waiting target keeps the link it was minted with; the card reopens it and connectors.connect refuses to spend a second mint (LINK_STILL_VALID). The unused refresh_link() goes. The package docstring names the new siblings; the nine-name public surface is unchanged. * test(connectors): the local-batch test answers the operation the way the card does The callback stopped returning an answer in f782b26d98 (the card answers through connection.respond); this test still returned one and waited out the 300s deadline in CI. * ci: retrigger * fix(connectors): the desktop card appears outside guided onboarding Live on a signed-in macOS desktop, the two-app connect never showed a card. Three defects, each hidden by a test that bound state the running app never binds. The backend read the surface from HERMES_SESSION_PLATFORM only. The desktop and TUI gateway bind it as HERMES_SESSION_SOURCE (_set_session_context), so session_platform() was "" and managed connects took the off-desktop branch: links in the model's message, no operation. session_platform() now reads platform, then source. The E2E test binds through server._set_session_context instead of set_session_vars(platform="desktop"). The renderer routed manage_connections to the card only under isOnboardingEnabled(), the HERMES_GUEST_ONBOARDING launch flag, in message-parts.tsx and the run splitter in fallback.tsx. tool-render-class.ts had already dropped that gate in this PR; the two routers had not. Both now route on the tool name alone. ConnectorTool resolved the session owner by the runtime id. Owner routes, hints and session rows are keyed by the stored id, so in registry topology the owner never resolved and the card rendered null while the tool blocked. It now resolves by the stored id, matching the PR1.5 card and every other owner lookup. message-parts-connectors.test.tsx mounts the real Fallback router with the onboarding flag off and distinct runtime/stored ids; red before each renderer fix, green after. * style(connectors): shorter comments, no module mock in the card router test The router test mocked isOnboardingEnabled to false; jsdom has no preload bridge, so the real function already returns false. Comments that restated the code are cut to one line. anti-slop: no net-new findings (25 touched files) * fix(connectors): Connect on a waiting row opens the stored link ConnectorCard derived the button's loading state from the phase label, so a managed row that read "Finish connecting in your browser" (every row, since links are minted up front) had a disabled Connect button. Nothing on the desktop could open the sign-in link; every managed connect ended skipped, not_connected, or at the deadline. The card now takes `busy` for "the action itself is running" and keeps `phase` as a label. The MCP card passes its in-flight flag; the connector card passes the re-mint wait. Red before: the Connect button on an initiated row rendered disabled and a click opened nothing. * fix(connectors): a settled card stays dead; the card binds to its tool call only A second connect for the same apps revived the finished card on the old tool row. The connection.request payload carried no id, so the renderer fell back to matching rows by connector names, and any row with those names qualified, settled or not. The operation now records the model's tool_call_id and sends it in connection.request and in the resume snapshot. The card binds to the tool row with that id and to nothing else; the name-match fallback is deleted. A payload without the id is rejected by the store. `reason` is removed from the tool: it was the only text the card ever showed from the model and its absence forked a second tool part, since `reason` doubled as the row-correlation key in tool-parts.ts. The card never needed it. `connection.expire` is deleted from the contract and from _EXPIRING_REQUESTS: the card is raised with _emit, not _block, so nothing has emitted it since the operation lifecycle landed. Sid's rule of record: a resolved card is fully dead; no path brings it back. * fix(connectors): the watch loop settles once, on time, and never raises into the result Three findings from the live review, one loop. Continue racing a finished sign-in: the loop ran the gateway read, then settled. A read that returned `connected` for an already-settled or failed target raised IllegalTransition out of the tool and the model got a generic error instead of the per-app outcomes. The read now skips targets that are not live (pending, initiated) and skips a settled operation; the loop checks `settled` after every read. Settle reason as row text: `settle()` wrote `continue`/`deadline` into each unresolved target's `detail`, and the card printed it in red. The reason stays on the operation only. Stop and the deadline waited for the next tick: `/stop` sets a per-thread flag with no wake hook, so the sleep is sliced at 250 ms and the flag and clock are read each slice. The clock is also checked before each read, not only after. Tests: a failed mint that later reads connected settles cleanly; Continue during a read keeps the settled result; no reason in detail; an interrupt settles within the same second. * fix(connectors): MCP setup off the desktop returns unavailable instead of blocking run_mcp_operation treated a non-None connection_callback as "a card exists". Every tui_gateway session has that callback, the Ink TUI included, so an MCP install from the terminal UI blocked until the 300 s deadline while the docs promised `unavailable` with the terminal commands. The MCP path now reads the session surface the same way the managed path does; the callback is never the predicate. Test binds the surface to `tui` with the callback attached. * fix(connectors): a failed Try again shows the failure, not the old dead link The panel's re-mint ignored the gateway's per-app status and moved the row to `initiated` with whatever link came back, `None` included, so a mint that failed again rendered as waiting on the link that had already died. One reader of a mint response now serves both the first mint and Try again (`managed.mint`, with the actor as a parameter). A repeated failure keeps the row `failed`, drops the link, and carries the vendor's new text through `operation.refresh`, which emits a frame without a state change so the card redraws. * fix(connectors): a forced reconnect waits for the new sign-in before it reports connected `reconnect` with `force: true` is the account switch. The vendor keeps the old account active while the new link waits, so the first list read after the mint said `connected` and the operation settled at once: the new link was dropped and the model was told the switch was done. A forced target is marked awaiting_new_attempt after the mint. The watcher ignores its row until the list shows the new attempt (`connectionStatus: initiated`) once, then trusts `connected`. * fix(connectors): the operation registers under the gateway session key The tool registered the operation under the agent's session_id; every RPC (connection.respond, connectors.operation.status, the panel's connectors.connect) and the update emitter looked it up by the gateway's session key. Those agree until compaction rotates the agent id mid-turn; then the card's clicks find nothing, no update reaches it, and the tool waits out the deadline. The registration key is now the bound HERMES_SESSION_KEY, with the agent id as the fallback for callers with no gateway (unit tests, a bare CLI). The E2E passes a rotated agent id and drives the card by the gateway key. * fix(connectors): the forced-reconnect gate reads any non-active row; a failed re-mint of an expired row is failed Three follow-ups from the verification of the fix pass. The awaiting_new_attempt gate cleared only on the literal `connectionStatus: initiated`. The field is optional on the wire and `initializing`, `failed`, `expired` are valid values, so a forced reconnect could wait the full 300 s and swallow a failed new attempt. The gate now holds only while the row still reads as the old account (`connected` or `active`) and releases on anything else. Try again on an `expired` row whose re-mint fails raised IllegalTransition (no expired → failed edge). The re-mint steps through `initiated` as the user's attempt, then `failed`, then drops the dead link. `detail` never carries a state name any more: `failed` as detail rendered as the row label and made agent/display.py tag the settled result as a tool error. Only vendor text goes there. `connection.expire` removed from the renderer's unscoped-stream set; nothing emits it.
2026-09-15 00:41:14 +05:30
The deadline for one call is five minutes, fixed by the backend when the call starts;
reopening the chat or restarting the desktop never extends it. The tool is present only when the
Nous Portal has enabled connectors for the signed-in account (the `managed_tools` claim on its
token). Other sessions do not see it.
manage_connections covers local MCP servers; setup_mcp leaves the schema (NS-867, PR1) (#109517) * feat(connections): manage_connections covers local MCP servers; setup_mcp leaves the schema One model tool now connects the user to apps of both kinds. A target `{"name": "linear", "mcp": true}` is a locally configured MCP server; `install` / `enable` / `authorize` are its verbs. Bare strings and `{"name": ...}` stay managed connectors and that leg is unchanged. MCP targets run through one backend-owned connection operation (tools/connections_tool_operation.py): created with a server-side deadline from the new config key `connections.wait_timeout_seconds` (default 120, floor 5, no ceiling), per-target state, and exactly-once settlement (all resolved / Continue / deadline / interrupt). Unresolved targets freeze as `not_connected` with the settle reason. Why the fold works now: the approval card is reached through `agent.connection_callback` via the agent-level inline executor table, which is the only path that carries a GUI callback. Registry dispatch (every non-GUI surface) settles MCP targets as `unavailable` with the `hermes mcp install / login` hint; managed targets in the same call are unaffected. `setup_mcp` is removed from every advertised toolset and from the deferral list; an inline-table shim keeps calls from conversations opened before this change dispatching (prompt-cache protection). `_LEGACY_TOOL_ALIASES` is not the mechanism: inline tools bypass it. Gateway: `mcp.setup.request/respond` are replaced by `connection.request/respond/expire` (no wire compat; desktop ships with this). The bridge waits exactly the operation's deadline. The `session.resume` snapshot gains `pending_connection` so a reopened window restores the card with the original deadline. `manage_connections` joins `_SEQUENTIAL_DEADLINE_EXEMPT_TOOLS`: the operation owns its wait; the 420s guard must not report `tool_timeout` while the card is live. The portal `check_fn` on the tool is dropped in favour of a handler-level gate on the managed leg, so signed-out sessions can still approve local MCPs. * wip(desktop): connection.request store, resume restore, card routing for MCP targets Renderer half of the setup_mcp fold, first slice: connection-request store (mirrors clarify), connection.request/expire handling, pending_connection resume restore, mcpTargets() + isCardTool(name, args) so MCP-target manage_connections calls classify as cards. Not yet: the card component rewrite (mcp-setup-tool.tsx), mcp-directory.ts removal, vitest, docs. Does not typecheck until the card rewrite lands. * fix(config): hermes update turns on the connections toolset for saved toolset lists `hermes tools` writes an explicit `platform_toolsets.<platform>` list, and the resolver reads absence from that list as "unchecked". The `connections` toolset (#106842) shipped after most users last saved, so `manage_connections` is stripped from the schema on every install that ever opened the picker. The Nous entitlement gate never runs; the agent reports the tool as missing. Migration 44 -> 45 (renumbered when folded into #109517; main was already at 44) appends `connections` to each explicit per-platform list that lacks it and records the offer in `known_builtin_toolsets` where that record exists, so a later uncheck reads as a decline. It skips: platforms whose record already holds `connections` (the user saw the checkbox and left it off), bare composite lists ([hermes-cli]) that already inherit it, platforms where the toolset is not allowed, and any config whose `agent.disabled_toolsets` names `connections` (Blank Slate, `hermes tools --disable`), because the resolver subtracts that list last and the enable would never take effect. The explicit-list test is the resolver's own: any configurable or plugin key. `hermes update` runs migrations post-pull for the active profile and every sibling, so one update is enough. Fresh installs and composite users were never affected. * refactor: anti-slop pass on the desktop slice; shorten added comments Parse connection.request at the boundary with a typed wire interface instead of unknown + typeof; mcpTargets reuses connectorText; comments cut to one or two lines. slop-ratchet: no net-new findings in 13 touched files. * feat(desktop): the MCP approval card answers manage_connections; MCP Directory removed The existing card (mcp-setup-tool.tsx) now reads the connection-request store, renders for manage_connections calls with mcp:true targets, answers through connection.respond with a per-target outcome, and no longer calls reload.mcp after Install; the new server's tools arrive on the between-turns refresh. A settled operation renders the first target's frozen state. session.resume restores a pending card with its original deadline on both the activate and cold-resume paths. lib/mcp-directory.ts is deleted along with its two fallback branches (suggestion provider, card install). The catalog was already primary in both; a catalog miss now yields no suggestion / a notInCatalog error. The GitHub never-suggest test is rewritten on catalog-shaped data. vitest: connection-request store (6), suggestion provider, clarify restore. slop-ratchet: no net-new findings in 19 touched files. * chore: drop __pycache__ files swept in by an over-broad git add * fix(desktop): correlate the connection.request row with the model's tool call by reason The synthetic row from connection.request and the tool.start row carried different ids and no shared match value (op_id is not in the model's args), so the card mounted twice. reason is the arg both sides carry. * docs: manage_connections covers local MCP servers; connections.wait_timeout_seconds * fix(connections): settle reason derives from target state, never from the renderer A card that answers one of two targets and claims all_resolved must settle as continue with the other target not_connected; found live with a two-target call. * fix(desktop): a pending connection card re-arms on resume and activate The store entry was restored but the transcript row was not, so navigating away and back (or reloading) lost the card while the backend kept waiting. restorePendingClarifyToolCall's core is generalized to any blocking tool name and both resume paths project the connection row through it. Verified live: card restored after navigate-away and after a full renderer reload, deadline_at unchanged, approve settles connected. * style: literal wording in added comments, docstrings and docs * fix: shared gateway-event contract and config-schema category for the connection events connection.request/expire replace mcp.setup.* in apps/shared gateway-events (json list, BACKEND_EVENT_NAMES, GatewayEventMap) so the renderer's event union includes them and the tui_gateway contract test passes. The new `connections` config section folds into the agent tab like the other single-field sections. * style: import order (perfectionist) in the desktop and shared files this PR touches * chore: retrigger CI (zero-job dispatch failure, auto-heal)
2026-09-15 00:41:13 +05:30
## `code_execution` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `execute_code` | Run a Python script that can call Hermes tools programmatically. Use this when you need 3+ tool calls with processing logic between them, need to filter/reduce large tool outputs before they enter your context, need conditional branching (… | — |
## `cronjob` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `cronjob_manage` | Unified scheduled-task manager. Use `action="create"`, `"list"`, `"update"`, `"pause"`, `"resume"`, `"run"`, or `"remove"` to manage jobs. Supports skill-backed jobs with one or more attached skills, and `skills=[]` on update clears attached skills. Cron runs happen in fresh sessions with no current-chat context. | — |
## `delegation` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
2026-08-02 22:14:58 -07:00
| `delegate_task` | Spawn subagents in isolated contexts; each gets its own conversation, terminal session, and toolset, and only its final summary returns to you. Provide 'goal' for a single task or 'tasks' for a parallel batch (limits and nesting rules… | — |
docs: correctness audit — fix wrong values, add missing coverage (#11972) Comprehensive audit of every reference/messaging/feature doc page against the live code registries (PROVIDER_REGISTRY, OPTIONAL_ENV_VARS, COMMAND_REGISTRY, TOOLSETS, tool registry, on-disk skills). Every fix was verified against code before writing. ### Wrong values fixed (users would paste-and-fail) - reference/environment-variables.md: - DASHSCOPE_BASE_URL default was `coding-intl.dashscope.aliyuncs.com/v1` \u2192 actual `dashscope-intl.aliyuncs.com/compatible-mode/v1`. - MINIMAX_BASE_URL and MINIMAX_CN_BASE_URL defaults were `/v1` \u2192 actual `/anthropic` (Hermes calls MiniMax via its Anthropic Messages endpoint). - reference/toolsets-reference.md MCP example used the non-existent nested `mcp: servers:` key \u2192 real key is the flat `mcp_servers:`. - reference/skills-catalog.md listed ~20 bundled skills that no longer exist on disk (all moved to `optional-skills/`). Regenerated the whole bundled section from `skills/**/SKILL.md` \u2014 79 skills, accurate paths and names. - messaging/slack.md ":::info" callout claimed Slack has no `free_response_channels` equivalent; both the env var and the yaml key are in fact read. - messaging/qqbot.md documented `QQ_MARKDOWN_SUPPORT` as an env var, but the adapter only reads `extra.markdown_support` from config.yaml. Removed the env var row and noted config-only nature. - messaging/qqbot.md `hermes setup gateway` \u2192 `hermes gateway setup`. ### Missing coverage added - Providers: AWS Bedrock and Qwen Portal (qwen-oauth) \u2014 both in PROVIDER_REGISTRY but undocumented everywhere. Added sections to integrations/providers.md, rows to quickstart.md and fallback-providers.md. - integrations/providers.md "Fallback Model" provider list now includes gemini, google-gemini-cli, qwen-oauth, xai, nvidia, ollama-cloud, bedrock. - reference/cli-commands.md `--provider` enum and HERMES_INFERENCE_PROVIDER enum in env-vars now include the same set. - reference/slash-commands.md: added `/agents` (alias `/tasks`) and `/copy`. Removed duplicate rows for `/snapshot`, `/fast` (\u00d72), `/debug`. - reference/tools-reference.md: fixed "47 built-in tools" \u2192 52. Added `feishu_doc` and `feishu_drive` toolset sections. - reference/toolsets-reference.md: added `feishu_doc` / `feishu_drive` core rows + all missing `hermes-<platform>` toolsets in the platform table (bluebubbles, dingtalk, feishu, qqbot, wecom, wecom-callback, weixin, homeassistant, webhook, gateway). Fixed the `debugging` composite to describe the actual `includes=[...]` mechanism. - reference/optional-skills-catalog.md: added `fitness-nutrition`. - reference/environment-variables.md: added NOUS_BASE_URL, NOUS_INFERENCE_BASE_URL, NVIDIA_API_KEY/BASE_URL, OLLAMA_API_KEY/BASE_URL, XAI_API_KEY/BASE_URL, MISTRAL_API_KEY, AWS_REGION/AWS_PROFILE, BEDROCK_BASE_URL, HERMES_QWEN_BASE_URL, DISCORD_ALLOWED_CHANNELS, DISCORD_PROXY, TELEGRAM_REPLY_TO_MODE, MATRIX_DEVICE_ID, MATRIX_REACTIONS, QQBOT_HOME_CHANNEL_NAME, QQ_SANDBOX. - messaging/discord.md: documented DISCORD_ALLOWED_CHANNELS, DISCORD_PROXY, HERMES_DISCORD_TEXT_BATCH_DELAY_SECONDS and HERMES_DISCORD_TEXT_BATCH_SPLIT _DELAY_SECONDS (all actively read by the adapter). - messaging/matrix.md: documented MATRIX_REACTIONS (default true). - messaging/telegram.md: removed the redundant second Webhook Mode section that invented a `telegram.webhook_mode: true` yaml key the adapter does not read. - user-guide/features/hooks.md: added `on_session_finalize` and `on_session_reset` (both emitted via invoke_hook but undocumented). - user-guide/features/api-server.md: documented GET /health/detailed, the `/api/jobs/*` CRUD surface, POST /v1/runs, and GET /v1/runs/{id}/events (10 routes that were live but undocumented). - user-guide/features/fallback-providers.md: added `approval` and `title_generation` auxiliary-task rows; added gemini, bedrock, qwen-oauth to the supported-providers table. - user-guide/features/tts.md: "seven providers" \u2192 "eight" (post-xAI add oversight in #11942). - user-guide/configuration.md: TTS provider enum gains `xai` and `gemini`; yaml example block gains `mistral:`, `gemini:`, `xai:` subsections. Auxiliary-provider enum now enumerates all real registry entries. - reference/faq.md: stale AIAgent/config examples bumped from `nous/hermes-3-llama-3.1-70b` and `claude-sonnet-4.6` to `claude-opus-4.7`. ### Docs-site integrity - guides/build-a-hermes-plugin.md referenced two nonexistent hooks (`pre_api_request`, `post_api_request`). Replaced with the real `on_session_finalize` / `on_session_reset` entries. - messaging/open-webui.md and features/api-server.md had pre-existing broken links to `/docs/user-guide/features/profiles` (actual path is `/docs/user-guide/profiles`). Fixed. - reference/skills-catalog.md had one `<1%` literal that MDX parsed as a JSX tag. Escaped to `&lt;1%`. ### False positives filtered out (not changed, verified correct) - `/set-home` is a registered alias of `/sethome` \u2014 docs were fine. - `hermes setup gateway` is valid syntax (`hermes setup \<section\>`); changed in qqbot.md for cross-doc consistency, not as a bug fix. - Telegram reactions "disabled by default" matches code (default `"false"`). - Matrix encryption "opt-in" matches code (empty env default \u2192 disabled). - `pre_api_request` / `post_api_request` hooks do NOT exist in current code; documented instead the real `on_session_finalize` / `on_session_reset`. - SIGNAL_IGNORE_STORIES is already in env-vars.md (subagent missed it). Validation: - `docusaurus build` \u2014 passes (only pre-existing nix-setup anchor warning). - `ascii-guard lint docs` \u2014 124 files, 0 errors. - 22 files changed, +317 / \u2212158.
2026-04-18 01:45:48 -07:00
## `feishu_doc` toolset
Scoped to the Feishu document-comment intelligent-reply handler (`gateway/platforms/feishu_comment.py`). Not exposed on `hermes-cli` or the regular Feishu chat adapter.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `feishu_doc_read` | Read the full text content of a Feishu/Lark document (Docx, Doc, or Sheet) given its file_type and token. | Feishu app credentials |
## `feishu_drive` toolset
Scoped to the Feishu document-comment handler. Drives comment read/write operations on drive files.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `feishu_drive_add_comment` | Add a top-level comment on a Feishu/Lark document or file. | Feishu app credentials |
| `feishu_drive_list_comments` | List whole-document comments on a Feishu/Lark file, most recent first. | Feishu app credentials |
| `feishu_drive_list_comment_replies` | List replies on a specific Feishu comment thread (whole-doc or local-selection). | Feishu app credentials |
| `feishu_drive_reply_comment` | Post a reply on a Feishu comment thread, with optional `@`-mention. | Feishu app credentials |
## `file` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `patch` | Targeted find-and-replace edits in files. Use this instead of sed/awk in terminal. Uses fuzzy matching (9 strategies) so minor whitespace/indentation differences won't break it. Returns a unified diff. Auto-runs syntax checks after editing… | — |
docs: accuracy sweep + coverage for 2 months of shipped features Accuracy pass (all 373 pages audited against code, 13 parallel audits): - configuration.md: 12 stale defaults/keys (file-sync rewrite, clarify timeout, streaming knobs, iteration budget, TTS/STT enums) - reference/: commands/env-vars/toolsets/tools synced with COMMAND_REGISTRY, argparse tree, OPTIONAL_ENV_VARS, TOOLSETS (28 env vars added, 3 phantom removed, mcp__ naming, webhook platform restricted toolset) - features/, messaging/, developer-guide/, guides/: ~60 factual fixes (web_extract truncation, dashboard auth fail-closed, delegation blocked tools, adapter signatures, session schema v23, phantom Matrix env vars, hermes setup tts, auth spotify, webhook --skills) - zh-Hans: explicit heading IDs fix 2 broken WSL2 anchors New coverage for features shipped in the last 2 months (verified against code before writing): - compression.in_place, verify-on-stop (+v31/v32 migration reality), ${env:VAR} SecretRef, display.timestamp_format, session:compress hook + thread_id/chat_type fields - /journey learning timeline, per-channel model/system-prompt overrides, /sessions search, clarify multi-select, -z --usage-file, uninstall --dry-run, config get/unset - MCP elicitation, extra_headers, discover_models, api-server run cap, Bedrock cachePoint, Discord reasoning_style, Google Chat clarify cards, vibe reactions, resume cwd restore, Yuanbao forwarded messages, api_content sidecar, roaming pet, tool_progress log mode, WhatsApp polls/locations, kanban per-task model + lifecycle hooks
2026-07-29 00:55:15 -07:00
| `read_file` | Read a text file with line numbers and pagination. Use this instead of cat/head/tail in terminal. Output format: 'LINE_NUM\|CONTENT'. Suggests similar filenames if not found. Use offset and limit for large files. Reads exceeding ~100K characters are truncated on a line boundary and return a next_offset. Jupyter notebooks (.ipynb), Word documents (.docx), and Excel workbooks (.xlsx) a… | — |
| `search_files` | Search file contents or find files by name. Use this instead of grep/rg/find/ls in terminal. Ripgrep-backed, faster than shell equivalents. Content search (target='content'): Regex search inside files. Output modes: full matches with line… | — |
| `write_file` | Write content to a file, completely replacing existing content. Use this instead of echo/cat heredoc in terminal. Creates parent directories automatically. OVERWRITES the entire file — use 'patch' for targeted edits. For an existing file, call read_file first: write_file refuses (file untouched) when the task has no current full read/write of the file or the file changed on disk since — on refusal, read_file, merge, retry. Auto-runs syntax checks on .py/.json/.yaml/.toml and other linted languages; only NEW errors introduced by the write are surfaced. | — |
fix(tools): a task's own patch keeps its full-file write baseline A deployment reported that write_file -> read_file (full) -> patch -> write_file refuses the last write with stale_write_blocked and "exists but this task has not seen its full current content", in 50 of 50 trials. No other writer took part. When the model does not reread before the turn ends, the refusal surfaces as the "File-mutation verifier: N file edit(s) FAILED" footer. Mechanism. The write_file baseline is an exact file version: (st_dev, st_ino, st_size, st_mtime_ns, st_ctime_ns, sha256) (tools/file_tools_read_tracking.py _file_version, _mark_full_write_baseline, _has_full_write_baseline). write_file_tool marks a fresh baseline from the bytes it wrote. patch_tool only ran _note_edited and _reset_patch_failures, so the task's own patch changed the version and left the baseline it held stale. _stale_overwrite_blocker then treated the task like an external writer. Invariant: after a task's own successful patch, the task may replace the file whole exactly when it held a current full baseline for the bytes the patch read and the bytes the patch wrote are what is on disk. Lineage. a8af57fcd2 added the guard. dddefaefae counted paged, extracted and post-compaction reads. e636aedebf kept a baseline across narrower rereads of unchanged bytes and bound it to the sha256. That is the change that made this sequence refuse (its parent lets the write through). Own patches are the missing case of e636aedebf's principle that unchanged knowledge survives. Shape: - Under the per-path locks, before the patch reads, patch_tool records the sha256 of each path whose baseline still matches disk (_known_full_content_sha256). - read_file_raw and patch_replace report the sha256 of the exact bytes they read, BOM included. Each file write records (path, read sha256, written sha256) in PatchResult._writes for replace, V4A Update and V4A Add. - _carry_full_write_baselines marks the baseline only when the read sha256 equals the known one (or the patch created the file). The mark goes through _mark_full_write_baseline with the written sha256 as expected_sha256. A writer that lands before the patch reads leaves a read sha256 the task never knew. One that lands after the patch writes fails the expected-sha check. Neither case gets a baseline. Several operations on one file in one V4A patch chain in order. - A blind patch (no baseline, or a partial view) is noted per task in blind_patches. While disk still holds exactly those bytes, the refusal says "Your patch changed this file after a partial view. Read the current file in full before a whole-file overwrite, or continue with targeted patches." Sibling, external and never-read refusals keep their wording. Remote backends: the baseline logic already stats the host path. On a sandbox backend (non-LocalEnvironment env, verified with the remote-binary-guard transport double), read_file records no baseline, and _stale_overwrite_blocker lets the write through because the host path does not exist. The carry hashes the same host path, so it records nothing there. Paths the backend rewrites (translated mounts) do not match the resolved host path and are skipped. Behaviour on those backends is byte-identical to before. Hint contradiction: after three failed replace patches, option (3) said "use write_file to replace the entire file", which is the call the guard refuses after a patch. It now says "re-read the file in full, then use write_file to replace it". Out of scope: enforcing recovery from a stale_write_blocked refusal before a turn ends. The stale_write_blocked receipt and the file-mutation footer are unchanged.
2026-10-06 14:28:01 +00:00
For local files, a full unredacted read (including all pages of the same file version), a successful `write_file`, or your own `patch` of a file you had read in full supplies a whole-file baseline. Reading a smaller region afterward does not discard that baseline while the bytes remain unchanged. A file changed by another writer, an unread file, a file patched without a full read, or a view with hidden/redacted or clamped content still needs a full current read before replacement; `patch` remains available for targeted edits. Writes made through terminal commands or `execute_code` do not establish a `write_file` baseline.
feat(computer-use): cua-driver backend, universal any-model schema Background macOS desktop control via cua-driver MCP — does NOT steal the user's cursor or keyboard focus, works with any tool-capable model. Replaces the Anthropic-native `computer_20251124` approach from the abandoned #4562 with a generic OpenAI function-calling schema plus SOM (set-of-mark) captures so Claude, GPT, Gemini, and open models can all drive the desktop via numbered element indices. - `tools/computer_use/` package — swappable ComputerUseBackend ABC + CuaDriverBackend (stdio MCP client to trycua/cua's cua-driver binary). - Universal `computer_use` tool with one schema for all providers. Actions: capture (som/vision/ax), click, double_click, right_click, middle_click, drag, scroll, type, key, wait, list_apps, focus_app. - Multimodal tool-result envelope (`_multimodal=True`, OpenAI-style `content: [text, image_url]` parts) that flows through handle_function_call into the tool message. Anthropic adapter converts into native `tool_result` image blocks; OpenAI-compatible providers get the parts list directly. - Image eviction in convert_messages_to_anthropic: only the 3 most recent screenshots carry real image data; older ones become text placeholders to cap per-turn token cost. - Context compressor image pruning: old multimodal tool results have their image parts stripped instead of being skipped. - Image-aware token estimation: each image counts as a flat 1500 tokens instead of its base64 char length (~1MB would have registered as ~250K tokens before). - COMPUTER_USE_GUIDANCE system-prompt block — injected when the toolset is active. - Session DB persistence strips base64 from multimodal tool messages. - Trajectory saver normalises multimodal messages to text-only. - `hermes tools` post-setup installs cua-driver via the upstream script and prints permission-grant instructions. - CLI approval callback wired so destructive computer_use actions go through the same prompt_toolkit approval dialog as terminal commands. - Hard safety guards at the tool level: blocked type patterns (curl|bash, sudo rm -rf, fork bomb), blocked key combos (empty trash, force delete, lock screen, log out). - Skill `apple/macos-computer-use/SKILL.md` — universal (model-agnostic) workflow guide. - Docs: `user-guide/features/computer-use.md` plus reference catalog entries. 44 new tests in tests/tools/test_computer_use.py covering schema shape (universal, not Anthropic-native), dispatch routing, safety guards, multimodal envelope, Anthropic adapter conversion, screenshot eviction, context compressor pruning, image-aware token estimation, run_agent helpers, and universality guarantees. 469/469 pass across tests/tools/test_computer_use.py + the affected agent/ test suites. - `model_tools.py` provider-gating: the tool is available to every provider. Providers without multi-part tool message support will see text-only tool results (graceful degradation via `text_summary`). - Anthropic server-side `clear_tool_uses_20250919` — deferred; client-side eviction + compressor pruning cover the same cost ceiling without a beta header. - macOS only. cua-driver uses private SkyLight SPIs (SLEventPostToPid, SLPSPostEventRecordTo, _AXObserverAddNotificationAndCheckRemote) that can break on any macOS update. Pin with HERMES_CUA_DRIVER_VERSION. - Requires Accessibility + Screen Recording permissions — the post-setup prints the Settings path. Supersedes PR #4562 (pyautogui/Quartz foreground backend, Anthropic- native schema). Credit @0xbyt4 for the original #3816 groundwork whose context/eviction/token design is preserved here in generic form.
2026-04-23 16:44:24 -07:00
## `computer_use` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
2026-06-26 14:05:15 -04:00
| `computer_use` | Background desktop control via cua-driver — screenshots (SOM / vision / AX), click / drag / scroll / type / key / wait, list_apps, focus_app. Does NOT steal the user's cursor or keyboard focus. Works with any tool-capable model. macOS, Windows, and Linux. | `cua-driver` on `$PATH` (install via `hermes tools`). |
feat(computer-use): cua-driver backend, universal any-model schema Background macOS desktop control via cua-driver MCP — does NOT steal the user's cursor or keyboard focus, works with any tool-capable model. Replaces the Anthropic-native `computer_20251124` approach from the abandoned #4562 with a generic OpenAI function-calling schema plus SOM (set-of-mark) captures so Claude, GPT, Gemini, and open models can all drive the desktop via numbered element indices. - `tools/computer_use/` package — swappable ComputerUseBackend ABC + CuaDriverBackend (stdio MCP client to trycua/cua's cua-driver binary). - Universal `computer_use` tool with one schema for all providers. Actions: capture (som/vision/ax), click, double_click, right_click, middle_click, drag, scroll, type, key, wait, list_apps, focus_app. - Multimodal tool-result envelope (`_multimodal=True`, OpenAI-style `content: [text, image_url]` parts) that flows through handle_function_call into the tool message. Anthropic adapter converts into native `tool_result` image blocks; OpenAI-compatible providers get the parts list directly. - Image eviction in convert_messages_to_anthropic: only the 3 most recent screenshots carry real image data; older ones become text placeholders to cap per-turn token cost. - Context compressor image pruning: old multimodal tool results have their image parts stripped instead of being skipped. - Image-aware token estimation: each image counts as a flat 1500 tokens instead of its base64 char length (~1MB would have registered as ~250K tokens before). - COMPUTER_USE_GUIDANCE system-prompt block — injected when the toolset is active. - Session DB persistence strips base64 from multimodal tool messages. - Trajectory saver normalises multimodal messages to text-only. - `hermes tools` post-setup installs cua-driver via the upstream script and prints permission-grant instructions. - CLI approval callback wired so destructive computer_use actions go through the same prompt_toolkit approval dialog as terminal commands. - Hard safety guards at the tool level: blocked type patterns (curl|bash, sudo rm -rf, fork bomb), blocked key combos (empty trash, force delete, lock screen, log out). - Skill `apple/macos-computer-use/SKILL.md` — universal (model-agnostic) workflow guide. - Docs: `user-guide/features/computer-use.md` plus reference catalog entries. 44 new tests in tests/tools/test_computer_use.py covering schema shape (universal, not Anthropic-native), dispatch routing, safety guards, multimodal envelope, Anthropic adapter conversion, screenshot eviction, context compressor pruning, image-aware token estimation, run_agent helpers, and universality guarantees. 469/469 pass across tests/tools/test_computer_use.py + the affected agent/ test suites. - `model_tools.py` provider-gating: the tool is available to every provider. Providers without multi-part tool message support will see text-only tool results (graceful degradation via `text_summary`). - Anthropic server-side `clear_tool_uses_20250919` — deferred; client-side eviction + compressor pruning cover the same cost ceiling without a beta header. - macOS only. cua-driver uses private SkyLight SPIs (SLEventPostToPid, SLPSPostEventRecordTo, _AXObserverAddNotificationAndCheckRemote) that can break on any macOS update. Pin with HERMES_CUA_DRIVER_VERSION. - Requires Accessibility + Screen Recording permissions — the post-setup prints the Settings path. Supersedes PR #4562 (pyautogui/Quartz foreground backend, Anthropic- native schema). Credit @0xbyt4 for the original #3816 groundwork whose context/eviction/token design is preserved here in generic form.
2026-04-23 16:44:24 -07:00
:::note
**Honcho tools** (`honcho_profile`, `honcho_search`, `honcho_context`, `honcho_reasoning`, `honcho_conclude`) are no longer built-in. They are available via the Honcho memory provider plugin from the plugin catalog (`hermes plugins install honcho`). See [Memory Providers](../user-guide/features/memory-providers.md) for installation and usage.
**Home Assistant tools** (`ha_list_entities`, `ha_get_state`, `ha_list_services`, `ha_call_service`, toolset `homeassistant`) are no longer built-in. They come from the `homeassistant` catalog plugin (`hermes plugins install homeassistant`). See [Home Assistant](../user-guide/messaging/homeassistant.md).
**Spotify tools** (`spotify_playback`, `spotify_devices`, `spotify_queue`, `spotify_search`, `spotify_playlists`, `spotify_albums`, `spotify_library`, toolset `spotify`) are no longer built-in. They come from the `spotify` catalog plugin (`hermes plugins install spotify`, then `hermes spotify login`). See [Spotify](../user-guide/features/spotify.md).
:::
## `image_gen` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `image_generate` | Generate images from text prompts (text-to-image) or edit/transform an existing image (image-to-image) via the user-configured backend (FAL.ai, OpenAI, OpenAI Codex auth, xAI, Krea). Pass `image_url` to edit an image and `reference_image_urls` for style references; omit both for text-to-image. The model is user-configured and not selectable by the agent. Returns a single image URL or local path. | FAL_KEY / OPENAI_API_KEY / Codex OAuth / xAI OAuth / KREA_API_KEY |
docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784) * docs: deep audit — fix stale config keys, missing commands, and registry drift Cross-checked ~80 high-impact docs pages (getting-started, reference, top-level user-guide, user-guide/features) against the live registries: hermes_cli/commands.py COMMAND_REGISTRY (slash commands) hermes_cli/auth.py PROVIDER_REGISTRY (providers) hermes_cli/config.py DEFAULT_CONFIG (config keys) toolsets.py TOOLSETS (toolsets) tools/registry.py get_all_tool_names() (tools) python -m hermes_cli.main <subcmd> --help (CLI args) reference/ - cli-commands.md: drop duplicate hermes fallback row + duplicate section, add stepfun/lmstudio to --provider enum, expand auth/mcp/curator subcommand lists to match --help output (status/logout/spotify, login, archive/prune/ list-archived). - slash-commands.md: add missing /sessions and /reload-skills entries + correct the cross-platform Notes line. - tools-reference.md: drop bogus '68 tools' headline, drop fictional 'browser-cdp toolset' (these tools live in 'browser' and are runtime-gated), add missing 'kanban' and 'video' toolset sections, fix MCP example to use the real mcp_<server>_<tool> prefix. - toolsets-reference.md: list browser_cdp/browser_dialog inside the 'browser' row, add missing 'kanban' and 'video' toolset rows, drop the stale '38 tools' count for hermes-cli. - profile-commands.md: add missing install/update/info subcommands, document fish completion. - environment-variables.md: dedupe GMI_API_KEY/GMI_BASE_URL rows (kept the one with the correct gmi-serving.com default). - faq.md: Anthropic/Google/OpenAI examples — direct providers exist (not just via OpenRouter), refresh the OpenAI model list. getting-started/ - installation.md: PortableGit (not MinGit) is what the Windows installer fetches; document the 32-bit MinGit fallback. - installation.md / termux.md: installer prefers .[termux-all] then falls back to .[termux]. - nix-setup.md: Python 3.12 (not 3.11), Node.js 22 (not 20); fix invalid 'nix flake update --flake' invocation. - updating.md: 'hermes backup restore --state pre-update' doesn't exist — point at the snapshot/quick-snapshot flow; correct config key 'updates.pre_update_backup' (was 'update.backup'). user-guide/ - configuration.md: api_max_retries default 3 (not 2); display.runtime_footer is the real key (not display.runtime_metadata_footer); checkpoints defaults enabled=false / max_snapshots=20 (not true / 50). - configuring-models.md: 'hermes model list' / 'hermes model set ...' don't exist — hermes model is interactive only. - tui.md: busy_indicator -> tui_status_indicator with values kaomoji|emoji|unicode|ascii (not kawaii|minimal|dots|wings|none). - security.md: SSH backend keys (TERMINAL_SSH_HOST/USER/KEY) live in .env, not config.yaml. - windows-wsl-quickstart.md: there is no 'hermes api' subcommand — the OpenAI-compatible API server runs inside hermes gateway. user-guide/features/ - computer-use.md: approvals.mode (not security.approval_level); fix broken ./browser-use.md link to ./browser.md. - fallback-providers.md: top-level fallback_providers (not model.fallback_providers); the picker is subcommand-based, not modal. - api-server.md: API_SERVER_* are env vars — write to per-profile .env, not 'hermes config set' which targets YAML. - web-search.md: drop web_crawl as a registered tool (it isn't); deep-crawl modes are exposed through web_extract. - kanban.md: failure_limit default is 2, not '~5'. - plugins.md: drop hard-coded '33 providers' count. - honcho.md: fix unclosed quote in echo HONCHO_API_KEY snippet; document that 'hermes honcho' subcommand is gated on memory.provider=honcho; reconcile subcommand list with actual --help output. - memory-providers.md: legacy 'hermes honcho setup' redirect documented. Verified via 'npm run build' — site builds cleanly; broken-link count went from 149 to 146 (no regressions, fixed a few in passing). * docs: round 2 audit fixes + regenerate skill catalogs Follow-up to the previous commit on this branch: Round 2 manual fixes: - quickstart.md: KIMI_CODING_API_KEY mentioned alongside KIMI_API_KEY; voice-mode and ACP install commands rewritten — bare 'pip install ...' doesn't work for curl-installed setups (no pip on PATH, not in repo dir); replaced with 'cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"'. ACP already ships in [all] so the curl install includes it. - cli.md / configuration.md: 'auxiliary.compression.model' shown as 'google/gemini-3-flash-preview' (the doc's own claimed default); actual default is empty (= use main model). Reworded as 'leave empty (default) or pin a cheap model'. - built-in-plugins.md: added the bundled 'kanban/dashboard' plugin row that was missing from the table. Regenerated skill catalogs: - ran website/scripts/generate-skill-docs.py to refresh all 163 per-skill pages and both reference catalogs (skills-catalog.md, optional-skills-catalog.md). This adds the entries that were genuinely missing — productivity/teams-meeting-pipeline (bundled), optional/finance/* (entire category — 7 skills: 3-statement-model, comps-analysis, dcf-model, excel-author, lbo-model, merger-model, pptx-author), creative/hyperframes, creative/kanban-video-orchestrator, devops/watchers, productivity/shop-app, research/searxng-search, apple/macos-computer-use — and rewrites every other per-skill page from the current SKILL.md. Most diffs are tiny (one line of refreshed metadata). Validation: - 'npm run build' succeeded. - Broken-link count moved 146 -> 155 — the +9 are zh-Hans translation shells that lag every newly-added skill page (pre-existing pattern). No regressions on any en/ page.
2026-05-09 13:19:51 -07:00
## `kanban` toolset
Registered when the agent is either (a) spawned by the kanban dispatcher (`HERMES_KANBAN_TASK` env set) or (b) running in a profile that explicitly enables the `kanban` toolset. Task-scoped workers use lifecycle tools for their assigned task; orchestrator profiles additionally get board-routing tools like `kanban_list` and `kanban_unblock`. See [Kanban Multi-Agent](../user-guide/features/kanban.md) for the full workflow.
docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784) * docs: deep audit — fix stale config keys, missing commands, and registry drift Cross-checked ~80 high-impact docs pages (getting-started, reference, top-level user-guide, user-guide/features) against the live registries: hermes_cli/commands.py COMMAND_REGISTRY (slash commands) hermes_cli/auth.py PROVIDER_REGISTRY (providers) hermes_cli/config.py DEFAULT_CONFIG (config keys) toolsets.py TOOLSETS (toolsets) tools/registry.py get_all_tool_names() (tools) python -m hermes_cli.main <subcmd> --help (CLI args) reference/ - cli-commands.md: drop duplicate hermes fallback row + duplicate section, add stepfun/lmstudio to --provider enum, expand auth/mcp/curator subcommand lists to match --help output (status/logout/spotify, login, archive/prune/ list-archived). - slash-commands.md: add missing /sessions and /reload-skills entries + correct the cross-platform Notes line. - tools-reference.md: drop bogus '68 tools' headline, drop fictional 'browser-cdp toolset' (these tools live in 'browser' and are runtime-gated), add missing 'kanban' and 'video' toolset sections, fix MCP example to use the real mcp_<server>_<tool> prefix. - toolsets-reference.md: list browser_cdp/browser_dialog inside the 'browser' row, add missing 'kanban' and 'video' toolset rows, drop the stale '38 tools' count for hermes-cli. - profile-commands.md: add missing install/update/info subcommands, document fish completion. - environment-variables.md: dedupe GMI_API_KEY/GMI_BASE_URL rows (kept the one with the correct gmi-serving.com default). - faq.md: Anthropic/Google/OpenAI examples — direct providers exist (not just via OpenRouter), refresh the OpenAI model list. getting-started/ - installation.md: PortableGit (not MinGit) is what the Windows installer fetches; document the 32-bit MinGit fallback. - installation.md / termux.md: installer prefers .[termux-all] then falls back to .[termux]. - nix-setup.md: Python 3.12 (not 3.11), Node.js 22 (not 20); fix invalid 'nix flake update --flake' invocation. - updating.md: 'hermes backup restore --state pre-update' doesn't exist — point at the snapshot/quick-snapshot flow; correct config key 'updates.pre_update_backup' (was 'update.backup'). user-guide/ - configuration.md: api_max_retries default 3 (not 2); display.runtime_footer is the real key (not display.runtime_metadata_footer); checkpoints defaults enabled=false / max_snapshots=20 (not true / 50). - configuring-models.md: 'hermes model list' / 'hermes model set ...' don't exist — hermes model is interactive only. - tui.md: busy_indicator -> tui_status_indicator with values kaomoji|emoji|unicode|ascii (not kawaii|minimal|dots|wings|none). - security.md: SSH backend keys (TERMINAL_SSH_HOST/USER/KEY) live in .env, not config.yaml. - windows-wsl-quickstart.md: there is no 'hermes api' subcommand — the OpenAI-compatible API server runs inside hermes gateway. user-guide/features/ - computer-use.md: approvals.mode (not security.approval_level); fix broken ./browser-use.md link to ./browser.md. - fallback-providers.md: top-level fallback_providers (not model.fallback_providers); the picker is subcommand-based, not modal. - api-server.md: API_SERVER_* are env vars — write to per-profile .env, not 'hermes config set' which targets YAML. - web-search.md: drop web_crawl as a registered tool (it isn't); deep-crawl modes are exposed through web_extract. - kanban.md: failure_limit default is 2, not '~5'. - plugins.md: drop hard-coded '33 providers' count. - honcho.md: fix unclosed quote in echo HONCHO_API_KEY snippet; document that 'hermes honcho' subcommand is gated on memory.provider=honcho; reconcile subcommand list with actual --help output. - memory-providers.md: legacy 'hermes honcho setup' redirect documented. Verified via 'npm run build' — site builds cleanly; broken-link count went from 149 to 146 (no regressions, fixed a few in passing). * docs: round 2 audit fixes + regenerate skill catalogs Follow-up to the previous commit on this branch: Round 2 manual fixes: - quickstart.md: KIMI_CODING_API_KEY mentioned alongside KIMI_API_KEY; voice-mode and ACP install commands rewritten — bare 'pip install ...' doesn't work for curl-installed setups (no pip on PATH, not in repo dir); replaced with 'cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"'. ACP already ships in [all] so the curl install includes it. - cli.md / configuration.md: 'auxiliary.compression.model' shown as 'google/gemini-3-flash-preview' (the doc's own claimed default); actual default is empty (= use main model). Reworded as 'leave empty (default) or pin a cheap model'. - built-in-plugins.md: added the bundled 'kanban/dashboard' plugin row that was missing from the table. Regenerated skill catalogs: - ran website/scripts/generate-skill-docs.py to refresh all 163 per-skill pages and both reference catalogs (skills-catalog.md, optional-skills-catalog.md). This adds the entries that were genuinely missing — productivity/teams-meeting-pipeline (bundled), optional/finance/* (entire category — 7 skills: 3-statement-model, comps-analysis, dcf-model, excel-author, lbo-model, merger-model, pptx-author), creative/hyperframes, creative/kanban-video-orchestrator, devops/watchers, productivity/shop-app, research/searxng-search, apple/macos-computer-use — and rewrites every other per-skill page from the current SKILL.md. Most diffs are tiny (one line of refreshed metadata). Validation: - 'npm run build' succeeded. - Broken-link count moved 146 -> 155 — the +9 are zh-Hans translation shells that lag every newly-added skill page (pre-existing pattern). No regressions on any en/ page.
2026-05-09 13:19:51 -07:00
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `kanban_show` | Show the active kanban task assigned to this worker (title, description, comments, dependencies). | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_list` | List board tasks with filters. Orchestrator-only; hidden from dispatcher-spawned task workers. | profile with `kanban` toolset |
| `kanban_complete` | Mark the current task done with a structured handoff payload (results, artifacts, follow-ups). | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_block` | Block the current task on a question for the user — the dispatcher pauses, surfaces the question, and resumes once a human replies. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_request_review` | Hand the implementation to a reviewer with `summary`, optional structured `metadata`, and an optional reviewer profile. Moves the same task to `review`; it is not a block and does not affect block-loop accounting. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_request_changes` | Reviewer verdict for an actively claimed review run. Closes the review run, reapplies parent gating, and routes the task back to the original implementer without using a block. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_heartbeat` | Send a progress heartbeat during a long-running operation so the dispatcher knows the worker is still alive. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_comment` | Add a comment to the task thread without changing its state — useful for surfacing intermediate findings. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_create` | Fan out child tasks from the current task. Used by orchestrators and follow-up-spawning workers. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_link` | Link tasks with a parent → child dependency edge. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_unblock` | Move a blocked task to `ready` when all parents are done, or `todo` while any parent remains open. Orchestrator-only; hidden from dispatcher-spawned task workers. | profile with `kanban` toolset |
docs: accuracy sweep + coverage for 2 months of shipped features Accuracy pass (all 373 pages audited against code, 13 parallel audits): - configuration.md: 12 stale defaults/keys (file-sync rewrite, clarify timeout, streaming knobs, iteration budget, TTS/STT enums) - reference/: commands/env-vars/toolsets/tools synced with COMMAND_REGISTRY, argparse tree, OPTIONAL_ENV_VARS, TOOLSETS (28 env vars added, 3 phantom removed, mcp__ naming, webhook platform restricted toolset) - features/, messaging/, developer-guide/, guides/: ~60 factual fixes (web_extract truncation, dashboard auth fail-closed, delegation blocked tools, adapter signatures, session schema v23, phantom Matrix env vars, hermes setup tts, auth spotify, webhook --skills) - zh-Hans: explicit heading IDs fix 2 broken WSL2 anchors New coverage for features shipped in the last 2 months (verified against code before writing): - compression.in_place, verify-on-stop (+v31/v32 migration reality), ${env:VAR} SecretRef, display.timestamp_format, session:compress hook + thread_id/chat_type fields - /journey learning timeline, per-channel model/system-prompt overrides, /sessions search, clarify multi-select, -z --usage-file, uninstall --dry-run, config get/unset - MCP elicitation, extra_headers, discover_models, api-server run cap, Bedrock cachePoint, Discord reasoning_style, Google Chat clarify cards, vibe reactions, resume cwd restore, Yuanbao forwarded messages, api_content sidecar, roaming pet, tool_progress log mode, WhatsApp polls/locations, kanban per-task model + lifecycle hooks
2026-07-29 00:55:15 -07:00
| `kanban_attach` | Attach a file to a task by passing its bytes inline (base64). Stored as a real attachment under the task's attachments dir, capped at 25 MB. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_attach_url` | Attach a file to a task by URL — Hermes downloads it server-side and stores it as a real attachment (capped at 25 MB). Only http/https URLs. | `HERMES_KANBAN_TASK` or `kanban` toolset |
| `kanban_attachments` | List the files attached to a task: id, filename, content_type, size, uploader, and the absolute on-disk path. | `HERMES_KANBAN_TASK` or `kanban` toolset |
docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784) * docs: deep audit — fix stale config keys, missing commands, and registry drift Cross-checked ~80 high-impact docs pages (getting-started, reference, top-level user-guide, user-guide/features) against the live registries: hermes_cli/commands.py COMMAND_REGISTRY (slash commands) hermes_cli/auth.py PROVIDER_REGISTRY (providers) hermes_cli/config.py DEFAULT_CONFIG (config keys) toolsets.py TOOLSETS (toolsets) tools/registry.py get_all_tool_names() (tools) python -m hermes_cli.main <subcmd> --help (CLI args) reference/ - cli-commands.md: drop duplicate hermes fallback row + duplicate section, add stepfun/lmstudio to --provider enum, expand auth/mcp/curator subcommand lists to match --help output (status/logout/spotify, login, archive/prune/ list-archived). - slash-commands.md: add missing /sessions and /reload-skills entries + correct the cross-platform Notes line. - tools-reference.md: drop bogus '68 tools' headline, drop fictional 'browser-cdp toolset' (these tools live in 'browser' and are runtime-gated), add missing 'kanban' and 'video' toolset sections, fix MCP example to use the real mcp_<server>_<tool> prefix. - toolsets-reference.md: list browser_cdp/browser_dialog inside the 'browser' row, add missing 'kanban' and 'video' toolset rows, drop the stale '38 tools' count for hermes-cli. - profile-commands.md: add missing install/update/info subcommands, document fish completion. - environment-variables.md: dedupe GMI_API_KEY/GMI_BASE_URL rows (kept the one with the correct gmi-serving.com default). - faq.md: Anthropic/Google/OpenAI examples — direct providers exist (not just via OpenRouter), refresh the OpenAI model list. getting-started/ - installation.md: PortableGit (not MinGit) is what the Windows installer fetches; document the 32-bit MinGit fallback. - installation.md / termux.md: installer prefers .[termux-all] then falls back to .[termux]. - nix-setup.md: Python 3.12 (not 3.11), Node.js 22 (not 20); fix invalid 'nix flake update --flake' invocation. - updating.md: 'hermes backup restore --state pre-update' doesn't exist — point at the snapshot/quick-snapshot flow; correct config key 'updates.pre_update_backup' (was 'update.backup'). user-guide/ - configuration.md: api_max_retries default 3 (not 2); display.runtime_footer is the real key (not display.runtime_metadata_footer); checkpoints defaults enabled=false / max_snapshots=20 (not true / 50). - configuring-models.md: 'hermes model list' / 'hermes model set ...' don't exist — hermes model is interactive only. - tui.md: busy_indicator -> tui_status_indicator with values kaomoji|emoji|unicode|ascii (not kawaii|minimal|dots|wings|none). - security.md: SSH backend keys (TERMINAL_SSH_HOST/USER/KEY) live in .env, not config.yaml. - windows-wsl-quickstart.md: there is no 'hermes api' subcommand — the OpenAI-compatible API server runs inside hermes gateway. user-guide/features/ - computer-use.md: approvals.mode (not security.approval_level); fix broken ./browser-use.md link to ./browser.md. - fallback-providers.md: top-level fallback_providers (not model.fallback_providers); the picker is subcommand-based, not modal. - api-server.md: API_SERVER_* are env vars — write to per-profile .env, not 'hermes config set' which targets YAML. - web-search.md: drop web_crawl as a registered tool (it isn't); deep-crawl modes are exposed through web_extract. - kanban.md: failure_limit default is 2, not '~5'. - plugins.md: drop hard-coded '33 providers' count. - honcho.md: fix unclosed quote in echo HONCHO_API_KEY snippet; document that 'hermes honcho' subcommand is gated on memory.provider=honcho; reconcile subcommand list with actual --help output. - memory-providers.md: legacy 'hermes honcho setup' redirect documented. Verified via 'npm run build' — site builds cleanly; broken-link count went from 149 to 146 (no regressions, fixed a few in passing). * docs: round 2 audit fixes + regenerate skill catalogs Follow-up to the previous commit on this branch: Round 2 manual fixes: - quickstart.md: KIMI_CODING_API_KEY mentioned alongside KIMI_API_KEY; voice-mode and ACP install commands rewritten — bare 'pip install ...' doesn't work for curl-installed setups (no pip on PATH, not in repo dir); replaced with 'cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"'. ACP already ships in [all] so the curl install includes it. - cli.md / configuration.md: 'auxiliary.compression.model' shown as 'google/gemini-3-flash-preview' (the doc's own claimed default); actual default is empty (= use main model). Reworded as 'leave empty (default) or pin a cheap model'. - built-in-plugins.md: added the bundled 'kanban/dashboard' plugin row that was missing from the table. Regenerated skill catalogs: - ran website/scripts/generate-skill-docs.py to refresh all 163 per-skill pages and both reference catalogs (skills-catalog.md, optional-skills-catalog.md). This adds the entries that were genuinely missing — productivity/teams-meeting-pipeline (bundled), optional/finance/* (entire category — 7 skills: 3-statement-model, comps-analysis, dcf-model, excel-author, lbo-model, merger-model, pptx-author), creative/hyperframes, creative/kanban-video-orchestrator, devops/watchers, productivity/shop-app, research/searxng-search, apple/macos-computer-use — and rewrites every other per-skill page from the current SKILL.md. Most diffs are tiny (one line of refreshed metadata). Validation: - 'npm run build' succeeded. - Broken-link count moved 146 -> 155 — the +9 are zh-Hans translation shells that lag every newly-added skill page (pre-existing pattern). No regressions on any en/ page.
2026-05-09 13:19:51 -07:00
2026-06-28 12:47:50 -07:00
## `project` toolset
Tools for driving desktop [Projects](../user-guide/cli.md) — named, multi-folder workspaces. Registered when the `project` toolset is enabled (primarily the desktop app / dashboard surfaces).
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `desktop_project` | One action enum for the three Project verbs: `create` makes a desktop Project (a named workspace) and switches this chat into it — pass `path` to anchor it to a repo/folder; `list` shows the desktop Projects and which one is active; `switch` moves this chat into an existing Project (by name, slug, or id), moving the session workspace to the project's primary folder. | — |
2026-06-28 12:47:50 -07:00
## `memory` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
2026-06-28 12:47:50 -07:00
| `memory` | Save important information to persistent memory that survives across sessions. Your memory appears in your system prompt at session start -- it's how you remember things about the user and your environment between conversations. WHEN TO SA… | — |
## `catalog` toolset
feat(desktop): every desktop chat can install catalog plugins; tools gated by session platform Toolsets that exist only for one kind of session now say so on their spec: `platforms=frozenset({"desktop"})`. `TOOLSET_SESSION_PLATFORMS` is derived from the specs that carry the key, `all` / `*` / no selection skip those toolsets, and `toolsets.agent_tool_drops(agent)` removes their tools from any agent whose own session platform is not listed. `agent_init._load_tools` and `tools/mcp_tool_agent.py` (MCP refresh and prefix restore) call that one helper. `tool_search._DIRECT_SURFACE_TOOLSETS` is derived from `CLIENT_SURFACE_TOOLSETS` and `TOOLSET_SESSION_PLATFORMS`. This replaces the profile-role gate: `profile_role_toolsets`, the role code in `_with_session_toolsets` and the explicit-pin branch, the strip step in `_select_tool_names`, and main's `setup` toolset (whose only tool moves out) are deleted. `manage_catalog` moves into a new `catalog` toolset, which the desktop client folds into every desktop chat like `project` and `desktop_ui`. It is deferred behind tool_search by default (`config_defaults` defer list). The shared-metrics schemas' toolset enum follows (`setup` out, `catalog` in). The install card works outside the setup chat (#129650, with review fixes): - Parallel installs: `_set_plugin_enabled` holds a per-home lock around the read-then-admit section, so rows enabled at once no longer refuse each other. - A catalog plugin already on disk and not enabled is enabled in place, so Try again after a refused enable can finish. - A failed catalog row counts as resolved (`contract.resolves`), so it no longer holds the turn to the 300 s deadline. The snapshot carries `resolved`, and the card reads it instead of a hand copy of the backend's rule. - Each card draws its own operation by op id, because models reuse call ids. - The row carries the approved non-secret choices (`approved`: force, enable, ref) and the chosen profile, so Try again after the card settled repeats them. - Install phases are ids (`InstallPhase`, wire `CatalogInstallPhase`) and the installed-row notes are fields (`enabled`, `missing_env`, `server_errors`, `already_installed`, `requires_hermes`); the card words them in English strings (translations follow later). Failure reasons stay raw text, and `detail` keeps the English notes for the model. - Installs and search target the calling chat's own home, carried as a path; the row's profile name is only a label, with no `'default'` fallback in Python or TypeScript. - `dashboard_install_plugin` is split into `_resolve_source`, `_place_tree` and `_enable_placed`. Desktop English strings for the card move to `en_catalog_install.ts` / `types_catalog_install.ts`, which offsets the growth of `en.ts` and `types.ts`.
2026-10-06 22:07:04 +05:30
Enabled for sessions whose source is the desktop app, whichever backend it's connected to. CLI, TUI, `hermes -z`, cron, kanban and messaging sessions never get it, even when a config list names it. `all` does not include it. Remove it with `agent.disabled_toolsets: [catalog]`.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
feat(desktop): every desktop chat can install catalog plugins; tools gated by session platform Toolsets that exist only for one kind of session now say so on their spec: `platforms=frozenset({"desktop"})`. `TOOLSET_SESSION_PLATFORMS` is derived from the specs that carry the key, `all` / `*` / no selection skip those toolsets, and `toolsets.agent_tool_drops(agent)` removes their tools from any agent whose own session platform is not listed. `agent_init._load_tools` and `tools/mcp_tool_agent.py` (MCP refresh and prefix restore) call that one helper. `tool_search._DIRECT_SURFACE_TOOLSETS` is derived from `CLIENT_SURFACE_TOOLSETS` and `TOOLSET_SESSION_PLATFORMS`. This replaces the profile-role gate: `profile_role_toolsets`, the role code in `_with_session_toolsets` and the explicit-pin branch, the strip step in `_select_tool_names`, and main's `setup` toolset (whose only tool moves out) are deleted. `manage_catalog` moves into a new `catalog` toolset, which the desktop client folds into every desktop chat like `project` and `desktop_ui`. It is deferred behind tool_search by default (`config_defaults` defer list). The shared-metrics schemas' toolset enum follows (`setup` out, `catalog` in). The install card works outside the setup chat (#129650, with review fixes): - Parallel installs: `_set_plugin_enabled` holds a per-home lock around the read-then-admit section, so rows enabled at once no longer refuse each other. - A catalog plugin already on disk and not enabled is enabled in place, so Try again after a refused enable can finish. - A failed catalog row counts as resolved (`contract.resolves`), so it no longer holds the turn to the 300 s deadline. The snapshot carries `resolved`, and the card reads it instead of a hand copy of the backend's rule. - Each card draws its own operation by op id, because models reuse call ids. - The row carries the approved non-secret choices (`approved`: force, enable, ref) and the chosen profile, so Try again after the card settled repeats them. - Install phases are ids (`InstallPhase`, wire `CatalogInstallPhase`) and the installed-row notes are fields (`enabled`, `missing_env`, `server_errors`, `already_installed`, `requires_hermes`); the card words them in English strings (translations follow later). Failure reasons stay raw text, and `detail` keeps the English notes for the model. - Installs and search target the calling chat's own home, carried as a path; the row's profile name is only a label, with no `'default'` fallback in Python or TypeScript. - `dashboard_install_plugin` is split into `_resolve_source`, `_place_tree` and `_enable_placed`. Desktop English strings for the card move to `en_catalog_install.ts` / `types_catalog_install.ts`, which offsets the growth of `en.ts` and `types.ts`.
2026-10-06 22:07:04 +05:30
| `manage_catalog` | Desktop sessions only, deferred behind `tool_search` by default. `search` lists catalog plugins and hub skills matching `query` (optionally one `kind`) with `id`, `kind`, `display`, `tier`, `platforms` and `installed` (present in this chat's profile); it changes nothing. `install` takes `items: [{kind, id}]` and shows one approval card with a row per item (Install, Advanced, Skip); an id the catalog does not know, or a plugin this OS cannot run, is drawn failed with the reason. An approved row installs into this chat's profile (or the profile chosen under Advanced) at the catalog's reviewed commit, with the same kill list, security scan and live activation as the Plugins tab, so the plugin's MCP tools and skills are usable in that profile's open chats at once. The result lists each row as `connected` (with `tools` and `skill`), `skipped`, `failed` (with `detail`) or `not_connected`; a failed row ends the wait like an installed or skipped one, and an install turns on a catalog plugin that is on disk but not enabled. The model cannot pass a source, commit, profile or setting. Anywhere else the call returns the `hermes plugins install` / `hermes skills install` command to run instead. | — |
## `session_search` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `session_search` | Search past sessions stored in the local session DB, or scroll inside one. FTS5-backed retrieval; returns actual messages from the DB (no LLM calls). Four shapes: discovery (pass `query`), scroll (pass `session_id` + `around_message_id`), read (pass `session_id` only), browse (no args). Discovery supports time bounds (`after`/`before` — ISO dates or relative durations like `7d`, `24h`, `2w`) and `exclude_session_ids` for iterative re-finding. | — |
## `skills` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `skill_manage` | Manage skills (create, update, delete). Skills are your procedural memory — reusable approaches for recurring task types. New skills go to ~/.hermes/skills/; existing skills can be modified wherever they live. Actions: create (full SKILL.m… | — |
| `skill_view` | Skills allow for loading information about specific tasks and workflows, as well as scripts and templates. Load a skill's full content or access its linked files (references, templates, scripts). First call returns SKILL.md content plus a… | — |
| `skills_list` | List available skills (name + description). Use skill_view(name) to load full content. | — |
## `terminal` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `process_manage` | Manage background processes started with terminal(background=true). Actions: 'list' (show all), 'poll' (check status + new output), 'log' (full output with pagination), 'wait' (block until done or timeout), 'kill' (terminate), 'write' (sen… | — |
fix(process): heartbeats wake the agent only on new output, and never as a user bubble A `terminal(background=true, heartbeat=N)` tick queued a notification every N seconds whether or not the process had printed anything, and every queued event costs the owning session a full model turn. On Desktop and the TUI that turn painted the wake as a user bubble ("[Background process ... heartbeat #9 ... (no new output since the last heartbeat)]") followed by the model's "Still running normally." — over and over, for a process whose row on the status stack already said it was running — and while the wake held the session's turn, the user's own prompt sat queued behind it. - `ProcessRegistry._emit_heartbeat` skips a tick with no new output. The sequence counts delivered beats only; the "(no new output)" placeholder in the formatter is gone. - TUI/Desktop type heartbeat rows `display_kind: hidden` (the kind both clients and the transcript preview already honour); the CLI paints a one-line receipt and persists the row hidden, so reopening the session in Desktop shows only the agent's reply. - Desktop hydration drops heartbeat rows persisted by older backends the same way. - `display.background_process_notifications: off` is honored by the TUI/Desktop poller and the CLI drain, not just the messaging gateway. `off` mutes process-driven wakes only: a finished `delegate_task(background=true)` still lands. Supersedes #123123 (cherry-picked; scoped so `off` keeps subagent results) and #119202 (cherry-picked; `heartbeat: 0` is schema-valid so models that materialize every field stop tripping the foreground guard).
2026-09-25 18:13:06 -05:00
| `terminal` | Execute shell commands on a Linux environment. Filesystem persists between calls. Set `background=true` for long-running servers. Set `notify_on_complete=true` (with `background=true`) to get an automatic notification when the process finishes — no polling needed. Add `heartbeat=N` (seconds, min 60) to also receive a periodic notification carrying the output produced since the previous one — for long bounded jobs such as a merge train or a full test suite, so a failure is seen within N seconds instead of at exit; a tick with no new output is skipped, and the wake is hidden from the transcript on Desktop/TUI (only the agent's reply shows). Do NOT use cat/head/tail — use read_file. Do NOT use grep/rg/find — use search_files. | — |
## `desktop_ui` toolset
Enabled for sessions whose source is the Hermes desktop app, on any backend it
is connected to (local, SSH, URL, or Hermes Cloud). Absent from CLI, TUI,
messaging, and cron sessions.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `read_terminal` | Read what's currently shown in the in-app terminal pane of the Hermes desktop GUI (the embedded shell beside this chat). | — |
| `close_terminal` | Close the read-only terminal tab for a background process in the Hermes desktop GUI. Does NOT kill the process — only drops the tab/view; use process_manage(action='kill') to stop it. | — |
| `desktop_preview` | Drive the preview pane beside the chat in the Hermes desktop app: `open` a web URL, localhost dev-server URL, or file path (HTML renders live); `close` the whole pane (omit `url`) or one tab inside it (pass the URL or file path); `read` what the pane currently shows — the in-app Browser's page text (URL + title + rendered text, pageable with `start`/`count`) or a file/artifact tab's identity. | — |
feat(desktop): durable element handles, and a delta instead of the whole page Every drive_preview action answered with the entire inventory — around 120 elements of ref, role, label, and an up-to-eight-rung `:nth-child` selector chain. On a real app shell that was ~24.5k characters, re-sent after every click, so a ten-step task paid for ten copies of a page that had barely moved. Handles are now durable and legible. An element is named after what it is and what it says — `btn-sign-in`, `inp-email`, `srch-search-projects` — minted once per page and never reused, with duplicates disambiguated as `btn-edit`, `btn-edit-1`. Each one remembers a stable attribute, its role, its accessible name, and the nearest landmark it sits in, so when a framework destroys the node and builds a new one the handle moves across and the agent is told `rebound` rather than being handed a removal it has to react to and an addition it has to re-read. The re-bind ladder is anchortree's (Apache-2.0), minus its geometry rung, which can never clear the threshold on its own. Because the handles hold, the first look at a page returns the inventory and every look after it returns only what moved. `changed` carries the ref and whichever of label/value/disabled actually shifted — role and selector are absent by construction, since a change in either would mean the re-bind ladder was looking at a different element. A delta gives way to a full re-read when half the page is new, where there is nothing left to reuse. The selector column is gone with it. It was 74% of the inventory on an 85-element page, nothing downstream ever read it, and a positional chain is wrong the moment a sibling appears. An `#id` or `[data-testid]` survives when the page offers one; everything else is addressed by handle. Legibility is what makes the delta work rather than a nicety. `+ btn-sign-in` on turn nine reads on its own, where `+ @e42` sends the model back to an inventory twenty thousand tokens ago. Measured on an 85-element app shell: 18,693 -> 4,930 characters for a baseline, and a steady turn that moved two things costs ~200.
2026-08-20 04:36:51 -05:00
| `drive_preview` | Interact with the page open in the in-app browser: `elements` inventories what's clickable and typable (each with a ref that names it, like `btn-sign-in` or `inp-email`, plus role, label, and value), then `click`, `hover`, `type`, `scroll`, and `press` act on a ref, and `back`/`forward`/`reload` drive the pane's history. The pointer and keyboard are real input, so hover menus open. A ref lasts until the page navigates, including across a re-render that rebuilds the element, so after the first inventory every action answers with just a delta — what was added, removed, changed, or rebound — instead of the whole page again. | — |
feat(tools): drive_preview and annotate_preview — the agent can use the page it opened The in-app browser was a one-way mirror. open_preview put a page in the pane and read_preview read its text back, but nothing could touch it. A click meant falling back to the browser_* tools, which drive a separate Chromium the user cannot see — so "log into this and pull my invoices" happened in a different browser from the one on screen, with none of the sessions the user is already signed into. Four pieces, and they only make sense together: · an in-page engine that inventories what is interactable and performs the verb, injected as source because it has to run inside the guest page; · the preview.act.request bridge from the gateway into the pane; · drive_preview, for acting: elements, click, type, scroll, press, and the pane's own back/forward/reload; · annotate_preview, for marking without acting. Those last two started as one tool doing two unrelated jobs. Leaving a mark is not an action — it outlives the turn that drew it — so it gets its own verb, and the interaction verb gets a name that says what it does. Gating is the existing surface rule: desktop_ui folds in on session source: 'desktop', and the bridge refuses to act for a background session, so a turn running behind the user's back cannot reach into the page they are working in. Two details worth a reviewer's attention. Typing assigns through the prototype's value setter, because React shadows value with its own accessor and ignores an input event whose value it believes it already wrote — a plain el.value = … types into a field that snaps back on the next render. And clicking replays the pointer/mouse pair before activation, because frameworks bind to mousedown as often as to click.
2026-08-19 13:30:39 -05:00
| `annotate_preview` | Outline an element in the in-app browser and leave the mark up until it's removed — the deliberate counterpart to the transient cues `drive_preview` draws as it works. `add` marks a ref with an optional short label, `remove` takes one down, `clear` takes them all. Marks follow their element and vanish with it, so a navigation clears them. | — |
| `read_window_below` | Identify the OS window directly underneath the Hermes desktop window — app name, title, bounds (metadata only, never pixels). On macOS, other apps' titles appear only when Screen Recording is already granted; the tool never prompts for it. | — |
| `focus_pane` | Reveal and focus a pane in the Hermes desktop app (chat, files, terminal, review, sessions). | — |
| `react_to_message` | React to a message with a single emoji, iMessage-tapback style. Opt-in via Settings → Appearance (`display.message_reactions`). | — |
| `gui_tour` | Give a live guided tour: dim the screen, highlight an element, and attach a narrated popover (driver.js). Works on the Hermes app's own UI and on any page open in the preview pane. `start` with no steps runs the app's built-in tour (`preset` `quick` or `full`, default `full`). For a custom tour, `targets` discovers what's on screen, `show` narrates step-by-step, and `start` with `steps` hands the user Next/Prev controls. | — |
| `show_tip` | Point at one element with a small accent bubble and an arrow — the quiet sibling of `gui_tour`, with no dimming, no spotlight, and no Next/Prev. Same `data-tour` handles and the same `tour(action='targets')` discovery call. | — |
| `set_theme` | Set the Hermes desktop app's accent colour (a swatch id, `theme`, or `#rrggbb`), light/dark/system mode, and layout preset (Simple: `sidebar-left`, `sidebar-right`; Advanced: `default`, `basic`, `focus`, `terminal-deck`, `quad`; or a saved layout's id). The result reports what was applied; an unknown value comes back with the available ids. `picker` (`accent` or `layout`) shows a picker card in the chat and waits up to 5 minutes for the pick. | — |
### Tours
For a general look around the app, `gui_tour(action='start')` with no steps runs the desktop app's built-in tour. `preset='quick'` shows four essentials (sessions, composer, new session, model); `preset='full'` (the default) adds the stops for the current interface mode. Stops whose element is not on screen are skipped. The built-in tour runs only on `surface='app'`, and `preset` cannot be combined with `steps`.
Setup scan stays off backend globals; audit lint and RPC fixes (#129341) * fix: userscan tmux and zellij socket probes pass the /tmp literal check The four lines read where tmux and zellij put their sockets (and, on macOS, measure the user's own temp dir). The POSIX fallback for those directories is /tmp, so the literal is the fact being probed, not a scratch path. Mark each line so the blocking lint step in lint.yml passes. * fix: setup-profile and start_chat RPCs no longer block the RPC reader onboarding.ensure_setup_profile / ensure_setup_session / reset_setup_profile can run create_profile (a skill-tree copy), state.db writes and the first import of the setup scanner. session.start_chat creates a session and runs prompt.submit. Inline on the reader thread they left session.interrupt and approval.respond unread in the pipe, the failure the _LONG_HANDLERS comment names. profiles.create was already on the list for the same reason. * fix: userscan children run with stdin closed and the served profile's env The /initiate-setup builder runs the user scan on a backend thread, so every child the scan spawned inherited the JSON-RPC stdin pipe (#14036) and the launch profile's os.environ. HostAccess.run, copy_locked and the PowerShell batch now pass stdin=subprocess.DEVNULL, and every spawn takes its env from HostAccess.child_env(). host_facts passes served_profile_child_env() into the run; the standalone run.py keeps the process env. check_subprocess_stdin.py now scans optional-skills/: the backend loads initiate-setup's scripts in-process. The nested-dir skip matches paths relative to the context dir, so a skill's own scripts/ folder is in scope. Three model-run optional-skill scripts it flagged get stdin closed. * refactor: split the userscan spec modules over 2,000 lines by topic Six spec modules under initiate-setup's userscan passed the 2,000-line gate. Each keeps its shared helpers and first families; the rest move verbatim into <stem>_<topic>.py siblings that import the helpers they use from the base module: apps_dev -> apps_dev_agents, apps_dev_devenv browser_files -> browser_files_comms, browser_files_content usage_gaming -> usage_gaming_games, usage_gaming_hardware linux_system -> linux_system_security, linux_system_hardware linux_apps -> linux_apps_dev, linux_apps_browser, linux_apps_files darwin_apps -> darwin_apps_dev, darwin_apps_browser, darwin_apps_files linux_system keeps health and usage: install_age reads usage's _wtmp and usage reads health's _kdump_dirs. References through the ad./bf./ug. aliases point at the module that now defines the name. specs/__init__ imports each sibling right after its base, so per-OS registration order and the registry keys stay the same. No behaviour change: `run.py --list` is byte-identical before and after, and a temp-home scan under --os darwin/linux/windows gives the same fact statuses, errors and insights. * fix: the setup scan never patches process globals or sys.path in the backend The /initiate-setup builder runs the user scan on a backend thread. It put the scanner dir at sys.path[0] of the backend (so a top-level `run` or `userscan` import anywhere resolved to the scanner), and it loaded host.py's deny_reads_under (swaps builtins.open, io.open, sqlite3.connect and subprocess.Popen) and override_env (rewrites os.environ HOME and HERMES_HOME) into the backend's import graph. - userscan/cli.py now holds override_env, the read guard, the aggregate HostAccess and scan_accounts. Only run.py imports it; runner.run() no longer retargets os.environ (overrides stay l0 data), and run.py applies override_env around run() for --home and friends. - The package uses relative imports, and host_facts loads it once per process as initiate_setup_userscan, without touching sys.path. Live: after an in-process scan sys.path, os.environ and the four patched callables are unchanged and no top-level userscan module exists (before: sys.path[0] was the scanner dir and userscan.host was importable). `run.py --list` is unchanged; --all-users and --home give the same output. * refactor: userscan runner runs each layer as a named phase runner._run was one closure-heavy function at cyclomatic complexity 66. Its state moves onto a small _Pass object whose run_l1 / run_l2 (with _run_python_l2) / run_l3 methods each hold one layer, moved verbatim; _run composes them and builds the output. Highest CC in the file is now 21 (run_l3). No behaviour change: temp-home scans under --os darwin/linux/windows give the same fact ids, statuses, methods, tiers, coverage, insights and output keys as before. * chore: name the setup intro flag writer, document gui_tour presets, trim media.ts - hermes_cli/setup_profile.py::mark_seen becomes mark_intro_seen. It writes the setup profile's intro state; agent/onboarding.py::mark_seen flips a config.yaml hint flag, and tui_gateway uses both. The RPC name onboarding.mark_seen is unchanged. - tools-reference: gui_tour's `start` without `steps` runs the built-in tour (`preset` quick or full, default full). - apps/desktop/src/lib/media.ts: drop the blank line at EOF (git diff --check). * docs: describe the setup chat's automatic machine scan The scan runs without a consent step when the desktop app creates the setup profile (the owner kept it automatic). The desktop user guide now says where it runs (the backend's machine), what it reads (T1: counts and categories; finer values are dropped before storage), what reaches the model (the derived fact block in the first setup message, sent to the setup chat's inference provider) and where the cache lives (insights/profile.json in the setup profile's home, 0600, 24 h). The skill's own docs page is generated from SKILL.md, which is the model's prompt, so the user-facing text lives in the desktop guide. * fix: overlapping setup-profile RPCs no longer race on the RPC pool ensure_setup_profile, ensure_setup_session and reset_setup_profile moved off the reader thread, so two kickoffs could overlap: both saw no setup profile, and the losers failed on the half-made profile (5 of 6 barrier-started calls returned ENOENT), or both saw an empty setup chat and seeded it twice. One module lock restores the one-at-a-time order; the prescan stays outside it. * fix: the Linux locale probe reads date formats in a child, not via setlocale locale.user ran setlocale(LC_TIME) on the scan thread inside the backend. setlocale is process-wide and not thread-safe, so strftime in other session threads briefly used the user's LC_TIME. The probe now runs 'locale d_fmt t_fmt' under LC_ALL=<locale> through HostAccess.run (new env overlay on child_env), after checking 'locale -a', because locale prints C formats for a locale that is not installed. * docs: link the setup scan from the /initiate-setup and onboarding references The desktop guide's scan section now says which search-engine names are kept and that the scan runs in the CLI and the gateway too. The /initiate-setup row and the profile_build bullet link to it.
2026-09-30 19:45:19 +05:30
For a custom tour, the `gui_tour` tool discovers its own targets — call `action='targets'` and it returns every addressable element on screen with a selector, a label, and a `stable` flag. Stable selectors key off identity (`data-tour`, `id`, `data-testid`, `aria-label`) and survive a re-render; positional `nth-child` paths don't, so stable ones sort first and should be preferred.
To give an element a durable handle of your own, mark it up:
```html
<div data-tour="composer">…</div>
```
Handles are applied at the **primitive**, not the call site, so one edit names every instance. The ones that already exist:
| Handle | What it names |
|---|---|
| `overlay-nav` | the left nav of any route overlay (settings, cron, profiles, agents) |
| `nav-<id>` | one row in that nav — `nav-models`, `nav-appearance`, … |
| `field-<schemaKey>` | one settings row, by its config key — `field-model`, `field-provider`, … |
| `page-tabs` | the filter tabs on any `PageSearchShell` page (artifacts, skills, …) |
| `artifact-card` | an artifact card in the grid |
When adding a surface, tag its shared primitive the same way rather than tagging screens one by one — that keeps the tour vocabulary small and stops selectors from rotting.
The same engine backs curated (non-agent) tours in the desktop app, so a feature can ship its own walkthrough:
```ts
import { startTour, showTourStep, stopTour } from '@/lib/tour'
startTour([
{ selector: '[data-tour="composer"]', title: 'Composer', text: 'Type here.' },
{ selector: '[data-tour="files"]', title: 'Files', text: 'Browse your project.' }
])
```
A step can also move the app to where its target lives, and the tour puts things back when it ends:
```ts
startTour([
{ navigate: '/artifacts', selector: '[data-tour="page-tabs"]', title: 'Filters', text: '…' },
{ pane: 'sessions', selector: '[data-slot="sidebar"]', title: 'Sessions', text: '…' }
])
```
`navigate` takes a route path and `pane` a desktop pane name. Both run as the step is entered, targets that mount late are waited for, and closing the tour — by any route, including Esc — returns to wherever it started.
Pass `'preview'` as the second argument to run against the page in the preview pane instead of the app.
### Tips
A tip is a tour step without the production: one bubble, one arrow, no scrim and
nothing to page through. It's the right weight for a sentence that would be
clearer with a finger on the thing it's about — "the model name is a button" —
where dimming the whole app would not be.
The `show_tip` tool takes the same selectors `gui_tour(action='targets')` reports, so
discovery is one call for both, and the durable `data-tour` handles above name
targets for either. One tip is on screen at a time; a new one replaces the last.
The app can also show its own, walking a built-in catalog of app features in
order, paced like a game's loading-screen tips rather than a notification: a few
minutes into a launch at the earliest, then at most one every six hours, and
only at a genuinely idle moment. A tip from Hermes shares that cooldown, so it
also buys the user six hours of quiet from the rotation. The rotation is a single
lap: each catalog tip shows once, whether it timed out or was closed with the ✕,
and once every tip has had its turn the app goes quiet. The settings row starts
the lap over.
Both tips and tours are on by default and switched off in Settings → Appearance
(`display.in_app_tips`, `display.in_app_tours`). Off covers Hermes as well as
the app: the switch reaches the connected gateway's config and the tool leaves
the model's schema, so the agent is never told about a surface it isn't allowed
to use. Like every schema change, that lands on the next session — a running
conversation keeps the toolset it started with, and the app declines the call in
the meantime.
## `todo` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `todo_list` | Manage your task list for the current session. Use for complex tasks with 3+ steps or when the user provides multiple tasks. Call with no parameters to read the current list. Items may nest: an item's optional `parent` field points at another item's id, making it a subtask — surfaces render the tree indented. | — |
## `vision` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
docs: comprehensive 2-week sweep of feature/PR coverage gaps (#28497) Catch the website docs up to two weeks of merged work (May 4 – May 18, 2026, roughly 1,080 PRs). The audit found ~50 user-visible features that had landed in code with no docs footprint, plus a handful of stale pages. This PR closes every gap the scan turned up. New pages - user-guide/features/deliverable-mode.md — extension list, agent triggers, kanban_complete artifacts pattern, [[as_document]] override (PR #27813). - developer-guide/web-search-provider-plugin.md — authoring guide modeled on image-gen-provider-plugin, covering brave_free / ddgs / etc. (PR #25448). Providers / auth - Rename "Alibaba Cloud" → "Qwen Cloud (Alibaba DashScope)" everywhere the display label shows up; provider id stays `alibaba` (PR #24835). - Document OAuth refresh-token quarantine for xAI / MiniMax / Codex (PRs #28116 / #28118 / #28119). - Document Nous JWT minting from refresh token + invalid-refresh quarantine + cross-profile shared token store (PRs #27663 / #19712). - Add `## Microsoft Entra ID authentication (keyless)` section to azure-foundry guide — DefaultAzureCredential, RBAC, OpenAI + Anthropic routing details (PR #28101 / #9df9816da). - Custom providers `api_mode` is now prompted-and-persisted, not just URL autodetected (PR #25068). - Delegation honours `api_mode` + auto-detects anthropic_messages base URLs (PR #26824). - `x_search` auto-enables when xAI credentials are present (PR #27376). - Add `xAI Grok OAuth (SuperGrok)` row to providers headline table (PR #26534). - NVIDIA NIM billing-origin header is set automatically (PR #26585). Windows / installer - `install.ps1`: document `-Commit <sha>` and `-Tag <v>` pin params plus the BOM-strip / git-retry hardening (PR #28169). - Document Hermes Desktop thin installer + first-launch bootstrap (PR #27822). - Document `dep_ensure` Windows bootstrap (PR #27845). - Document install-method auto-detection (pip / git / homebrew / nixos) and the matching update command (PR #27843). Gateway / messaging - `/platform list|pause|resume` full description + circuit-breaker semantics (PR #26600). - Slack / Matrix / Mattermost get parallel `allowed_channels` / `allowed_rooms` allowlist sections matching Telegram/Discord/DingTalk (PR #21251). - Discord `allow_any_attachment` + `max_attachment_bytes` (config and env vars) (PR #27245). - Discord clarify-choice button rendering (PR #25485). - Telegram `guest_mode` @mention bypass for allowlisted groups (PR #22759). - Telegram `notifications` mode (`important` vs `all`) (PR #22793). - `[[as_document]]` skill / response directive for forcing document-style media delivery (PR #21210). CLI / TUI - `/new [name]` argument (PR #19637). - `/subgoal` user-supplied criteria appended to `/goal` (PR #25449). - `/exit --delete` flag confirmation prompts for destructive slash commands (PR #22687). - Status-bar additions: ▶ N background indicator (PR #27175), context compression count (PR #21218), YOLO mode banner+statusbar warning (PR #26238). - `display.timestamps` + `docker_extra_args` config keys (PR #23599). - TUI collapsible startup banner sections (PR #20625). - `HERMES_SESSION_ID` exported to tool subprocesses (PR #23847). i18n - Refresh display.language locale list from 8 → 16 (en, zh, zh-hant, ja, de, es, fr, tr, uk, af, ko, it, ga, pt, ru, hu) — matches `agent/i18n.py:SUPPORTED_LANGUAGES`. Tools / features - `vision_analyze` native-pixel passthrough for vision-capable callers, with auxiliary text-describer fallback (PR #22955). - `session_search` rewrite to the single-shape tool (discovery / scroll / browse modes) (PRs #27590 / #27840). - Clarify MCP transport scope: client supports stdio + SSE; embedded `hermes mcp serve` is stdio-only (PR #21227). - Web search backends table: add Brave Search (free tier) and DDGS rows (PR #21337). - ACP session-scoped edit auto-approval modes (PR #27862). - Curator rename map in the user-visible per-run summary (PR #22910). - Prompt caching feature page reference in features/overview.md — Claude cross-session 1-hour prefix cache on native Anthropic / OpenRouter / Nous Portal (PR #23828). - Cron per-job profile parameter (PR #28124). - `--no-skills` flag for `hermes profile create` (PR #20986). Build - Verified with `npm run build` in `website/`; both `en` and `zh-Hans` locales compile. Remaining broken-link/anchor warnings are pre-existing (`rl-training.md` from learning-path / overview; the zh-Hans translation lag the docs skill already calls out).
2026-05-18 23:55:25 -07:00
| `vision_analyze` | Analyze images using AI vision. On vision-capable main models, returns the raw image pixels as a multimodal tool result so the model sees them natively on its next turn. On text-only main models, falls back to an auxiliary vision model that describes the image and returns the description as text. Tool signature is identical either way. | — |
docs: deep audit — fix stale config keys, missing commands, and registry drift (#22784) * docs: deep audit — fix stale config keys, missing commands, and registry drift Cross-checked ~80 high-impact docs pages (getting-started, reference, top-level user-guide, user-guide/features) against the live registries: hermes_cli/commands.py COMMAND_REGISTRY (slash commands) hermes_cli/auth.py PROVIDER_REGISTRY (providers) hermes_cli/config.py DEFAULT_CONFIG (config keys) toolsets.py TOOLSETS (toolsets) tools/registry.py get_all_tool_names() (tools) python -m hermes_cli.main <subcmd> --help (CLI args) reference/ - cli-commands.md: drop duplicate hermes fallback row + duplicate section, add stepfun/lmstudio to --provider enum, expand auth/mcp/curator subcommand lists to match --help output (status/logout/spotify, login, archive/prune/ list-archived). - slash-commands.md: add missing /sessions and /reload-skills entries + correct the cross-platform Notes line. - tools-reference.md: drop bogus '68 tools' headline, drop fictional 'browser-cdp toolset' (these tools live in 'browser' and are runtime-gated), add missing 'kanban' and 'video' toolset sections, fix MCP example to use the real mcp_<server>_<tool> prefix. - toolsets-reference.md: list browser_cdp/browser_dialog inside the 'browser' row, add missing 'kanban' and 'video' toolset rows, drop the stale '38 tools' count for hermes-cli. - profile-commands.md: add missing install/update/info subcommands, document fish completion. - environment-variables.md: dedupe GMI_API_KEY/GMI_BASE_URL rows (kept the one with the correct gmi-serving.com default). - faq.md: Anthropic/Google/OpenAI examples — direct providers exist (not just via OpenRouter), refresh the OpenAI model list. getting-started/ - installation.md: PortableGit (not MinGit) is what the Windows installer fetches; document the 32-bit MinGit fallback. - installation.md / termux.md: installer prefers .[termux-all] then falls back to .[termux]. - nix-setup.md: Python 3.12 (not 3.11), Node.js 22 (not 20); fix invalid 'nix flake update --flake' invocation. - updating.md: 'hermes backup restore --state pre-update' doesn't exist — point at the snapshot/quick-snapshot flow; correct config key 'updates.pre_update_backup' (was 'update.backup'). user-guide/ - configuration.md: api_max_retries default 3 (not 2); display.runtime_footer is the real key (not display.runtime_metadata_footer); checkpoints defaults enabled=false / max_snapshots=20 (not true / 50). - configuring-models.md: 'hermes model list' / 'hermes model set ...' don't exist — hermes model is interactive only. - tui.md: busy_indicator -> tui_status_indicator with values kaomoji|emoji|unicode|ascii (not kawaii|minimal|dots|wings|none). - security.md: SSH backend keys (TERMINAL_SSH_HOST/USER/KEY) live in .env, not config.yaml. - windows-wsl-quickstart.md: there is no 'hermes api' subcommand — the OpenAI-compatible API server runs inside hermes gateway. user-guide/features/ - computer-use.md: approvals.mode (not security.approval_level); fix broken ./browser-use.md link to ./browser.md. - fallback-providers.md: top-level fallback_providers (not model.fallback_providers); the picker is subcommand-based, not modal. - api-server.md: API_SERVER_* are env vars — write to per-profile .env, not 'hermes config set' which targets YAML. - web-search.md: drop web_crawl as a registered tool (it isn't); deep-crawl modes are exposed through web_extract. - kanban.md: failure_limit default is 2, not '~5'. - plugins.md: drop hard-coded '33 providers' count. - honcho.md: fix unclosed quote in echo HONCHO_API_KEY snippet; document that 'hermes honcho' subcommand is gated on memory.provider=honcho; reconcile subcommand list with actual --help output. - memory-providers.md: legacy 'hermes honcho setup' redirect documented. Verified via 'npm run build' — site builds cleanly; broken-link count went from 149 to 146 (no regressions, fixed a few in passing). * docs: round 2 audit fixes + regenerate skill catalogs Follow-up to the previous commit on this branch: Round 2 manual fixes: - quickstart.md: KIMI_CODING_API_KEY mentioned alongside KIMI_API_KEY; voice-mode and ACP install commands rewritten — bare 'pip install ...' doesn't work for curl-installed setups (no pip on PATH, not in repo dir); replaced with 'cd ~/.hermes/hermes-agent && uv pip install -e ".[voice]"'. ACP already ships in [all] so the curl install includes it. - cli.md / configuration.md: 'auxiliary.compression.model' shown as 'google/gemini-3-flash-preview' (the doc's own claimed default); actual default is empty (= use main model). Reworded as 'leave empty (default) or pin a cheap model'. - built-in-plugins.md: added the bundled 'kanban/dashboard' plugin row that was missing from the table. Regenerated skill catalogs: - ran website/scripts/generate-skill-docs.py to refresh all 163 per-skill pages and both reference catalogs (skills-catalog.md, optional-skills-catalog.md). This adds the entries that were genuinely missing — productivity/teams-meeting-pipeline (bundled), optional/finance/* (entire category — 7 skills: 3-statement-model, comps-analysis, dcf-model, excel-author, lbo-model, merger-model, pptx-author), creative/hyperframes, creative/kanban-video-orchestrator, devops/watchers, productivity/shop-app, research/searxng-search, apple/macos-computer-use — and rewrites every other per-skill page from the current SKILL.md. Most diffs are tiny (one line of refreshed metadata). Validation: - 'npm run build' succeeded. - Broken-link count moved 146 -> 155 — the +9 are zh-Hans translation shells that lag every newly-added skill page (pre-existing pattern). No regressions on any en/ page.
2026-05-09 13:19:51 -07:00
## `video` toolset
Opt-in toolset (not loaded in the default `hermes-cli` set). Add via `--toolsets video` or include `video` in your `toolsets:` config.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `video_analyze` | Analyze video content from a URL or file path — captions, scene breakdowns, key timestamps, and visual descriptions. | — |
## `video_gen` toolset
Opt-in toolset (not loaded in the default `hermes-cli` set). Add via `--toolsets video_gen` or enable it in `hermes tools` → Video Generation, which also walks you through picking a backend.
Backends ship as plugins under `plugins/video_gen/<name>/`:
- **xAI Grok-Imagine** — text-to-video and image-to-video (SuperGrok OAuth or `XAI_API_KEY`).
- **FAL.ai** — Veo 3.1, Pixverse v6, Kling 3.0 / O3 (requires `FAL_KEY`).
- **OpenRouter** — every generative model on OpenRouter's video API (Veo 3.1, Sora 2 Pro, Kling 3, Seedance 2, Wan 3, Hailuo 3, Grok Imagine, FLUX 3 Video, …); text-to-video, image-to-video and reference-to-video; catalog and per-model limits fetched live (requires `OPENROUTER_API_KEY` or a credential added with `hermes auth add openrouter`, billed to your OpenRouter credit).
feat(video): OpenRouter backend covers every model on the live video catalog The salvaged #103267 plugin hardcoded a single model (minimax/hailuo-3-max) and rejected any other id. OpenRouter's public GET /api/v1/videos/models already publishes every generative model with its supported durations, resolutions, aspect ratios, frame-image support, audio and seed flags, and pricing SKUs, so the provider now reads that catalog (5-min TTL, offline snapshot fallback): - list_models(): all 25+ generative models (edit/upscale/avatar rows that take no duration are outside the unified video_generate surface and are dropped) with a per-second price label where the SKU is per-second - capabilities(): the CONFIGURED model's surface, so the dynamic schema only advertises audio/seed/resolutions the selected model honours - _build_payload(): clamps duration/resolution/aspect ratio to the model's live limits (nearest by value/height/ratio) and drops generate_audio/seed for models that lack them (the API 400s otherwise); reference images ride in input_references; local file inputs are refused (OpenRouter fetches URLs itself), data:image/ URLs from the sandbox chokepoint pass through - bearer key only ever goes to the configured origin (poll + /content), never to a provider-supplied unsigned_urls host (kept from #103267) Also drops the source-grep `_IGNORES_SEED` escape hatch #103267 added to the declaration⇄implementation sweep; the provider now implements seed for real. Docs list OpenRouter and DeepInfra as bundled video backends. Requested by Don Piedro Savastano (Discord): OpenRouter credit for video_generate.
2026-09-12 12:58:29 -07:00
- **DeepInfra** — live `video-gen` catalog over the OpenAI-compatible videos endpoint (requires `DEEPINFRA_API_KEY`).
The single `video_generate` tool covers both modalities — pass `image_url` to animate a still, omit it to generate from text alone. The active backend auto-routes to the right endpoint. As with `image_generate`, the model is user-configured (`video_gen.model`) and not selectable by the agent — none of the video tools take a `model` argument. The tool's description is rebuilt at session start to reflect the active backend's actual capabilities (modalities, aspect ratios, resolutions, duration range, max reference images, audio support). See [Video Generation Provider Plugins](../developer-guide/video-gen-provider-plugin.md) for backend authoring.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `video_generate` | Generate a video from a text prompt (text-to-video) or animate a still image (image-to-video) using the user's configured video generation backend. Pass `image_url` to animate that image; omit it to generate from text alone. The backend auto-routes to the right endpoint. Returns either an HTTP URL or an absolute file path in the `video` field. | Active `video_gen` plugin + its credential (e.g. `XAI_API_KEY`, `FAL_KEY`) |
docs: accuracy sweep + coverage for 2 months of shipped features Accuracy pass (all 373 pages audited against code, 13 parallel audits): - configuration.md: 12 stale defaults/keys (file-sync rewrite, clarify timeout, streaming knobs, iteration budget, TTS/STT enums) - reference/: commands/env-vars/toolsets/tools synced with COMMAND_REGISTRY, argparse tree, OPTIONAL_ENV_VARS, TOOLSETS (28 env vars added, 3 phantom removed, mcp__ naming, webhook platform restricted toolset) - features/, messaging/, developer-guide/, guides/: ~60 factual fixes (web_extract truncation, dashboard auth fail-closed, delegation blocked tools, adapter signatures, session schema v23, phantom Matrix env vars, hermes setup tts, auth spotify, webhook --skills) - zh-Hans: explicit heading IDs fix 2 broken WSL2 anchors New coverage for features shipped in the last 2 months (verified against code before writing): - compression.in_place, verify-on-stop (+v31/v32 migration reality), ${env:VAR} SecretRef, display.timestamp_format, session:compress hook + thread_id/chat_type fields - /journey learning timeline, per-channel model/system-prompt overrides, /sessions search, clarify multi-select, -z --usage-file, uninstall --dry-run, config get/unset - MCP elicitation, extra_headers, discover_models, api-server run cap, Bedrock cachePoint, Discord reasoning_style, Google Chat clarify cards, vibe reactions, resume cwd restore, Yuanbao forwarded messages, api_content sidecar, roaming pet, tool_progress log mode, WhatsApp polls/locations, kanban per-task model + lifecycle hooks
2026-07-29 00:55:15 -07:00
| `xai_video_edit` | Edit an existing video with xAI Imagine. Provider-specific (separate from `video_generate`). `video_url` must be the public HTTPS MP4 URL from a prior Imagine result. | xAI Imagine credentials (SuperGrok OAuth or `XAI_API_KEY`) |
| `xai_video_extend` | Extend an existing video with xAI Imagine. Provider-specific (separate from `video_generate`). `video_url` must be the public HTTPS MP4 URL from a prior Imagine result. | xAI Imagine credentials (SuperGrok OAuth or `XAI_API_KEY`) |
## `web` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `web_search` | Search the web for information. Returns up to 5 results by default with titles, URLs, and descriptions. Accepts an optional `limit` (1-100, default 5). The query is passed through to the configured backend, so operators such as `site:domain`, `filetype:pdf`, `intitle:word`, `-term`, and `"exact phrase"` may work when the backend supports them. | EXA_API_KEY or PARALLEL_API_KEY or FIRECRAWL_API_KEY or TAVILY_API_KEY or PERPLEXITY_API_KEY or KEENABLE_API_KEY |
| `web_extract` | Extract content from web page URLs. Returns clean page content in markdown/text (no LLM summarization — fast). Also works with PDF URLs (arxiv papers, documents) — pass the PDF link directly. Pages within the char budget (default 15000) return whole; larger pages return a head+tail window with a footer pointing at the full text saved on disk. Max 5 URLs per call. | EXA_API_KEY or PARALLEL_API_KEY or FIRECRAWL_API_KEY or TAVILY_API_KEY or PERPLEXITY_API_KEY or KEENABLE_API_KEY |
feat(x_search): gated X (Twitter) search tool with OAuth-or-API-key auth (#26763) * feat(x_search): gated X (Twitter) search tool with OAuth-or-API-key auth Salvages tools/x_search_tool.py from the closed PR #10786 (originally by @Jaaneek) and reworks its credential resolution so the tool registers when EITHER xAI credential path is available: * XAI_API_KEY (paid xAI API key) is set in ~/.hermes/.env or the env, OR * The user is signed in via xAI Grok OAuth — SuperGrok subscription — i.e. hermes auth add xai-oauth has been run Both paths route through xAI's built-in x_search Responses tool at https://api.x.ai/v1/responses. When both credentials exist OAuth wins, matching tools/xai_http.py's existing preference order (uses SuperGrok quota instead of paid API spend). The check_fn calls resolve_xai_http_credentials() which auto-refreshes the OAuth access token if it's within the refresh skew window, so a True return means the bearer is fetchable AND non-empty. Wiring - tools/x_search_tool.py — new tool, ~370 LOC. Schema gated by check_fn, bearer resolved per-call so revoked OAuth surfaces a clean tool_error rather than an HTTP 401. - toolsets.py — "x_search" toolset def. NOT added to _HERMES_CORE_TOOLS; users opt in via hermes tools. - hermes_cli/tools_config.py — CONFIGURABLE_TOOLSETS entry + TOOL_CATEGORIES block with two provider options (OAuth + API key) sharing the existing xai_grok post_setup hook for credential bootstrap. - hermes_cli/config.py — DEFAULT_CONFIG["x_search"] with model / timeout_seconds / retries. Additive nested key; no version bump. - tests/tools/test_x_search_tool.py — 13 tests covering HTTP shape, handle validation, citation extraction, 4xx/5xx/timeout handling, and the full credential-resolution matrix (OAuth-only, API-key-only, both-set, neither-set, resolver-raises, config overrides, registry registration). - website/docs/guides/xai-grok-oauth.md — adds X Search to the direct-to-xAI tools section with off-by-default note. - website/docs/user-guide/features/tools.md — new row in the tools table. Off by default — users enable via `hermes tools` → 🐦 X (Twitter) Search. Schema only appears to the model when xAI credentials are configured. Co-authored-by: Jaaneek <Jaaneek@users.noreply.github.com> * docs(x_search): add dedicated feature page + reference entries - website/docs/user-guide/features/x-search.md (new) — full feature walkthrough: authentication, enablement, configuration, parameters, returned fields, example, troubleshooting, see-also links. - website/docs/reference/tools-reference.md — new "x_search" toolset section with parameter docs and credential gating note. - website/docs/reference/toolsets-reference.md — new row in the toolset catalog table. - website/sidebars.ts — wires the new feature page under Media & Web, after web-search. --------- Co-authored-by: Jaaneek <Jaaneek@users.noreply.github.com>
2026-05-16 00:58:27 -07:00
## `x_search` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `x_search` | Search X (Twitter) posts, profiles, and threads using xAI's built-in `x_search` Responses tool. Read-only public X discovery for current discussion, reactions, or claims on public X (not general web pages). Does not post, reply, like, DM, upload media, delete, or inspect the authenticated X account — those need a separate authenticated X API surface (e.g. the `xurl` skill). Off by default — opt in via `hermes tools` → 🐦 X (Twitter) Search. Schema is only registered when xAI credentials are configured (check_fn-gated). | XAI_API_KEY **or** xAI Grok OAuth (SuperGrok / Premium+) login |
feat(x_search): gated X (Twitter) search tool with OAuth-or-API-key auth (#26763) * feat(x_search): gated X (Twitter) search tool with OAuth-or-API-key auth Salvages tools/x_search_tool.py from the closed PR #10786 (originally by @Jaaneek) and reworks its credential resolution so the tool registers when EITHER xAI credential path is available: * XAI_API_KEY (paid xAI API key) is set in ~/.hermes/.env or the env, OR * The user is signed in via xAI Grok OAuth — SuperGrok subscription — i.e. hermes auth add xai-oauth has been run Both paths route through xAI's built-in x_search Responses tool at https://api.x.ai/v1/responses. When both credentials exist OAuth wins, matching tools/xai_http.py's existing preference order (uses SuperGrok quota instead of paid API spend). The check_fn calls resolve_xai_http_credentials() which auto-refreshes the OAuth access token if it's within the refresh skew window, so a True return means the bearer is fetchable AND non-empty. Wiring - tools/x_search_tool.py — new tool, ~370 LOC. Schema gated by check_fn, bearer resolved per-call so revoked OAuth surfaces a clean tool_error rather than an HTTP 401. - toolsets.py — "x_search" toolset def. NOT added to _HERMES_CORE_TOOLS; users opt in via hermes tools. - hermes_cli/tools_config.py — CONFIGURABLE_TOOLSETS entry + TOOL_CATEGORIES block with two provider options (OAuth + API key) sharing the existing xai_grok post_setup hook for credential bootstrap. - hermes_cli/config.py — DEFAULT_CONFIG["x_search"] with model / timeout_seconds / retries. Additive nested key; no version bump. - tests/tools/test_x_search_tool.py — 13 tests covering HTTP shape, handle validation, citation extraction, 4xx/5xx/timeout handling, and the full credential-resolution matrix (OAuth-only, API-key-only, both-set, neither-set, resolver-raises, config overrides, registry registration). - website/docs/guides/xai-grok-oauth.md — adds X Search to the direct-to-xAI tools section with off-by-default note. - website/docs/user-guide/features/tools.md — new row in the tools table. Off by default — users enable via `hermes tools` → 🐦 X (Twitter) Search. Schema only appears to the model when xAI credentials are configured. Co-authored-by: Jaaneek <Jaaneek@users.noreply.github.com> * docs(x_search): add dedicated feature page + reference entries - website/docs/user-guide/features/x-search.md (new) — full feature walkthrough: authentication, enablement, configuration, parameters, returned fields, example, troubleshooting, see-also links. - website/docs/reference/tools-reference.md — new "x_search" toolset section with parameter docs and credential gating note. - website/docs/reference/toolsets-reference.md — new row in the toolset catalog table. - website/sidebars.ts — wires the new feature page under Media & Web, after web-search. --------- Co-authored-by: Jaaneek <Jaaneek@users.noreply.github.com>
2026-05-16 00:58:27 -07:00
## `tts` toolset
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `text_to_speech` | Convert text to speech audio. Returns a MEDIA: path that the platform delivers as a voice message. On Telegram it plays as a voice bubble, on Discord/WhatsApp as an audio attachment. In CLI mode, saves to ~/voice-memos/. Voice and provider… | — |
docs: resync reference, user-guide, developer-guide, and messaging pages against code (#17738) Broad drift audit against origin/main (b52b63396). Reference pages (most user-visible drift): - slash-commands: add /busy, /curator, /footer, /indicator, /redraw, /steer that were missing; drop non-existent /terminal-setup; fix /q footnote (resolves to /queue, not /quit); extend CLI-only list with all 24 CLI-only commands in the registry - cli-commands: add dedicated sections for hermes curator / fallback / hooks (new subcommands not previously documented); remove stale hermes honcho standalone section (the plugin registers dynamically via hermes memory); list curator/fallback/hooks in top-level table; fix completion to include fish - toolsets-reference: document the real 52-toolset count; split browser vs browser-cdp; add discord / discord_admin / spotify / yuanbao; correct hermes-cli tool count from 36 to 38; fix misleading claim that hermes-homeassistant adds tools (it's identical to hermes-cli) - tools-reference: bump tool count 55 -> 68; add 7 Spotify, 5 Yuanbao, 2 Discord toolsets; move browser_cdp/browser_dialog to their own browser-cdp toolset section - environment-variables: add 40+ user-facing HERMES_* vars that were undocumented (--yolo, --accept-hooks, --ignore-*, inference model override, agent/stream/checkpoint timeouts, OAuth trace, per-platform batch tuning for Telegram/Discord/Matrix/Feishu/WeCom, cron knobs, gateway restart/connect timeouts); dedupe the Cron Scheduler section; replace stale QQ_SANDBOX with QQ_PORTAL_HOST User-guide (top level): - cli.md: compression preserves last 20 turns, not 4 (protect_last_n: 20) - configuration.md: display.platforms is the canonical per-platform override key; tool_progress_overrides is deprecated and auto-migrated - profiles.md: model.default is the config key, not model.model - sessions.md: CLI/TUI session IDs use 6-char hex, gateway uses 8 - checkpoints-and-rollback.md: destructive-command list now matches _DESTRUCTIVE_PATTERNS (adds rmdir, cp, install, dd) - docker.md: the container runs as non-root hermes (UID 10000) via gosu; fix install command (uv pip); add missing --insecure on the dashboard compose example (required for non-loopback bind) - security.md: systemctl danger pattern also matches 'restart' - index.md: built-in tool count 47 -> 68 - integrations/index.md: 6 STT providers, 8 memory providers - integrations/providers.md: drop fictional dashscope/qwen aliases Features: - overview.md: 9 image models (not 8), 9 TTS providers (not 5), 8 memory providers (Supermemory was missing) - tool-gateway.md: 9 image models - tools.md: extend common-toolsets list with search / messaging / spotify / discord / debugging / safe - fallback-providers.md: add 6 real providers from PROVIDER_REGISTRY (lmstudio, kimi-coding-cn, stepfun, alibaba-coding-plan, tencent-tokenhub, azure-foundry) - plugins.md: Available Hooks table now includes on_session_finalize, on_session_reset, subagent_stop - built-in-plugins.md: add the 7 bundled plugins the page didn't mention (spotify, google_meet, three image_gen providers, two dashboard examples) - web-dashboard.md: add --insecure and --tui flags - cron.md: hermes cron create takes positional schedule/prompt, not flags Messaging: - telegram.md: TELEGRAM_WEBHOOK_SECRET is now REQUIRED when TELEGRAM_WEBHOOK_URL is set (gateway refuses to start without it per GHSA-3vpc-7q5r-276h). Biggest user-visible drift in the batch. - discord.md: HERMES_DISCORD_TEXT_BATCH_SPLIT_DELAY_SECONDS default is 2.0, not 0.1 - dingtalk.md: document DINGTALK_REQUIRE_MENTION / FREE_RESPONSE_CHATS / MENTION_PATTERNS / HOME_CHANNEL / ALLOW_ALL_USERS that the adapter supports - bluebubbles.md: drop fictional BLUEBUBBLES_SEND_READ_RECEIPTS env var; the setting lives in platforms.bluebubbles.extra only - qqbot.md: drop dead QQ_SANDBOX; add real QQ_PORTAL_HOST and QQ_GROUP_ALLOWED_USERS - wecom-callback.md: replace 'hermes gateway start' (service-only) with 'hermes gateway' for first-time setup Developer-guide: - architecture.md: refresh tool/toolset counts (61/52), terminal backend count (7), line counts for run_agent.py (~13.7k), cli.py (~11.5k), main.py (~10.4k), setup.py (~3.5k), gateway/run.py (~12.2k), mcp_tool.py (~3.1k); add yuanbao adapter, bump platform adapter count 18 -> 20 - agent-loop.md: run_agent.py line count 10.7k -> 13.7k - tools-runtime.md: add vercel_sandbox backend - adding-tools.md: remove stale 'Discovery import added to model_tools.py' checklist item (registry auto-discovery) - adding-platform-adapters.md: mark send_typing / get_chat_info as concrete base methods; only connect/disconnect/send are abstract - acp-internals.md: ACP sessions now persist to SessionDB (~/.hermes/state.db); acp.run_agent call uses use_unstable_protocol=True - cron-internals.md: gateway runs scheduler in a dedicated background thread via _start_cron_ticker, not on a maintenance cycle; locking is cross-process via fcntl.flock (Unix) / msvcrt.locking (Windows) - gateway-internals.md: gateway/run.py ~12k lines - provider-runtime.md: cron DOES support fallback (run_job reads fallback_providers from config) - session-storage.md: SCHEMA_VERSION = 11 (not 9); add migrations 10 and 11 (trigram FTS, inline-mode FTS5 re-index); add api_call_count column to Sessions DDL; document messages_fts_trigram and state_meta in the architecture tree - context-compression-and-caching.md: remove the obsolete 'context pressure warnings' section (warnings were removed for causing models to give up early) - context-engine-plugin.md: compress() signature now includes focus_topic param - extending-the-cli.md: _build_tui_layout_children signature now includes model_picker_widget; add to default layout Also fixed three pre-existing broken links/anchors the build warned about (docker.md -> api-server.md, yuanbao.md -> cron-jobs.md and tips#background-tasks, nix-setup.md -> #container-aware-cli). Regenerated per-skill pages via website/scripts/generate-skill-docs.py so catalog tables and sidebar are consistent with current SKILL.md frontmatter. docusaurus build: clean, no broken links or anchors.
2026-04-29 20:55:59 -07:00
## `discord` toolset
Registered on the `hermes-discord` platform toolset (gateway only). Uses the same bot token as the messaging adapter.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `discord` | Read and participate in a Discord server. Actions include `search_members`, `fetch_messages`, `send_message`, `react`, `fetch_channel`, `list_channels`, and more. | `DISCORD_BOT_TOKEN` |
## `discord_admin` toolset
Registered on the `hermes-discord` platform toolset. Moderation actions require the bot to hold the matching Discord permissions.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `discord_admin` | Manage a Discord server via the REST API: list guilds/channels/roles, create/edit/delete channels, manage role grants, timeouts, kicks, and bans. | `DISCORD_BOT_TOKEN` + bot permissions |
## `hermes-yuanbao` toolset
Registered only on the `hermes-yuanbao` platform toolset. Yuanbao is Tencent's chat app; these tools drive its DM/group/sticker APIs.
| Tool | Description | Requires environment |
|------|-------------|----------------------|
| `yb_query_group_info` | Query basic info about a group (called "派/Pai" in the app): name, owner, member count. | Yuanbao credentials |
| `yb_query_group_members` | Query members of a group (for `@`-mentions, finding a user by name, listing bots). | Yuanbao credentials |
| `yb_send_dm` | Send a private/direct message to a user in a group, with optional media files. | Yuanbao credentials |
| `yb_search_sticker` | Search the built-in Yuanbao sticker (TIM face) catalogue by keyword. | Yuanbao credentials |
| `yb_send_sticker` | Send a built-in sticker to the current Yuanbao chat. | Yuanbao credentials |