mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
* refactor(plugins): remove the Sep 2026 decomposition compat layer on schedule The PLUGIN-COMPAT layer (2776813df3+d63e380324+0a5164cebe) kept pre-#102117 import paths alive for external plugins until 2026-09-14. That window closed two weeks ago; since then the loader has already been skipping plugins that use the old paths. This removes the layer itself: - 328 appended `PLUGIN-COMPAT` blocks (lazy `__getattr__` pointer tables, re-exported third-party names, restored dead definitions) and the three re-export stub modules (gateway/startup_watchdog, hermes_cli/observability/relay_runtime, tools/environments/modal_utils) - COMPAT_MANIFEST.md, compat_manifest.json, scripts/check_compat_pointers.py and its lint step - the reporting surfaces: CLI banner notice, `hermes plugins compat`, the `hermes doctor` section, the post-update notice, the Desktop one-time dialog, the loader's pre-import skip and the `plugins.allow_deprecated_imports` escape hatch An external plugin that still imports an old path now fails to load with its ImportError as the reason in `hermes plugins list`, the same path as any broken plugin. hermes_cli/plugin_compat.py stays as three inert stubs (compat_report, removal_in_effect, summary_lines): an already-running pre-removal `hermes update` lazy-imports them after the checkout swap (tests/compat/old_updater_surface.json). In-tree fallout, both already dead: hermes_cli/setup.py::_check_espeak_ng (no callers; its `shutil` came from a compat block) and gateway/config.py::SessionResetPolicy ("retained solely for the scheduled plugin-compat window"). Two test_run_agent patches targeted the removed `run_agent.handle_function_call` pointer; they now patch `model_tools.handle_function_call`, the seam production reads, like every sibling test in that file. * chore: retrigger CI (zero-job startup_failure phantom) * test: drop resolution allowlist rows for the two deleted which() sites hermes_cli/setup.py::_check_espeak_ng (dead) and tools/skillevaluator_scan.py::scanner_available (a restored definition inside a PLUGIN-COMPAT block) no longer exist; the stale-row gate requires their allowlist entries go with them.
152 lines
10 KiB
Markdown
152 lines
10 KiB
Markdown
# tui_gateway/ + ui-tui/ — the TUI and its JSON-RPC backend
|
|
|
|
Applies on top of the root `AGENTS.md`. The TUI fully replaces the classic prompt_toolkit CLI;
|
|
activate with `hermes --tui` or `HERMES_TUI=1`. `tui_gateway` is ALSO the backend the Desktop app
|
|
and the dashboard `/chat` talk to — changes here have three consumers.
|
|
|
|
## Process model
|
|
|
|
```
|
|
hermes --tui
|
|
└─ Node (Ink) ──stdio JSON-RPC── Python (tui_gateway)
|
|
│ └─ AIAgent + tools + sessions
|
|
└─ renders transcript, composer, prompts, activity
|
|
```
|
|
|
|
TypeScript owns the screen. Python owns sessions, tools, model calls, and slash-command logic.
|
|
Never move agent behaviour into the renderer.
|
|
|
|
## Transport
|
|
|
|
Newline-delimited JSON-RPC over stdio, peer-to-peer: client→server method calls, server→client
|
|
**requests** (the agent asking the user something: `approval`, `clarify`, `sudo`, `secret`, `vault.*`,
|
|
`connection`, the desktop read/act bridges) and server→client `event` notifications. `tui_gateway/server.py`
|
|
is the facade with the method/event catalog; methods live in `methods_*.py` siblings (`methods_config`,
|
|
`methods_complete`, `methods_browser`, `methods_bot_relay`, ...), event publishing in
|
|
`event_publisher.py` / `event_replay.py`, server→client requests in `server_requests.py` (`send()` blocks
|
|
the agent thread until the response frame with the same `srq-<n>` id arrives; `cancel*` withdraws with a
|
|
`request.cancel` event; `open_requests(sid)` is what `session.resume` / `session.events.since` replay so a
|
|
reconnecting client re-renders the still-open questions). A client says once per connection that it
|
|
answers them (`client.capabilities {server_requests: true}`, sent by the shared channel on `gateway.ready`);
|
|
a WebSocket client that never did is an app build older than server→client requests, and `send()` fails
|
|
fast for it instead of stalling the agent for the deadline. Desktop reaches the same server over WebSocket
|
|
via `apps/shared` (`JsonRpcGatewayClient`, `onRequest`). New RPC = a new `methods_<topic>.py` or an entry
|
|
in an existing topical sibling, registered in the table — no `if method == ...` chain (root shape rules).
|
|
|
|
**The wire is declared in Python and generated for TypeScript** (`tui_gateway/contracts/`). Every method
|
|
has a `Params` + `Result` model, every server→client request a `Params` + `Result`, every event a
|
|
`Payload` — one Pydantic class each, `extra="forbid"` by default (`OpenModel` for producer-owned dicts).
|
|
`register_method` refuses an undeclared name at import; the dispatcher rejects unknown param keys
|
|
(`4000` + key path) and, under `HERMES_TEST_ISOLATION=1`, raises `ContractViolation` when a handler's
|
|
result or an emitted payload does not match its model (production only logs). `apps/shared/src/
|
|
gateway-contract.generated.ts` (`RpcMethods`, `ServerRequestMap`, `BackendGatewayEventMap` + every value
|
|
shape) and `gateway-contract.openrpc.json` are rendered by `scripts/gen_gateway_contracts.py`;
|
|
`tests/tui_gateway/contracts/test_generated.py` fails when they are stale, so the loop is: change the model →
|
|
regenerate → `tsc` shows every consumer the field moved. `apps/shared/src/gateway-events.ts` only adds
|
|
the client-local synthetic events and the `GatewayEvent` envelope on top.
|
|
New question for the user = `_ask("<method>", sid, params, timeout)` in the emitter, a handler in
|
|
`apps/desktop/.../gateway-event/server-requests.ts` and `ui-tui/src/app/createServerRequestHandler.ts`,
|
|
and a `server_request(...)` in `contracts/server_requests.py`.
|
|
New event = `event("<type>", Payload)` in `contracts/events.py`; the emitter is checked against it.
|
|
|
|
## Profile scope in RPC methods
|
|
|
|
One `serve` process may host sessions from several profile homes (Desktop pooled backends launch
|
|
under a profile; the dashboard serves several). The launch profile is a profile: "default" means
|
|
the launch home, never `~/.hermes`. The first non-launch home hosted flips
|
|
`launch_profile_policy.py` → `set_multiplex_active(True)`; without it every fail-closed guard is
|
|
silently off. Every method that reads or writes home-, config- or `.env`-derived state runs under
|
|
`server.py::@_profile_scoped` (resolved from the live session's `profile_home`, or the explicit
|
|
`profile` argument for sessionless calls) and, for tool/agent construction,
|
|
`methods_tools.py::_profile_scoped_rpc`; the tokens come from `model_switch.py::
|
|
_profile_runtime_scope_tokens(profile_home)` — home + secret scope + terminal scope together.
|
|
**A method that sets only `get_hermes_home_override()` is half-bound**: config paths resolve to the
|
|
right profile while credentials and `TERMINAL_*` policy still come from the launch profile.
|
|
Off-turn paths bind the same way: `session_lifecycle.py::_finalize_session` / `_teardown_session`
|
|
enter `_session_profile_runtime_scope(session)` around `on_session_end`, the memory commit and
|
|
`agent.close()` (their callers are unscoped reapers, Timers, atexit and pool threads); background
|
|
threads start via `agent.memory_provider.spawn_context_thread`, never bare `threading.Thread`;
|
|
children act for the served profile through `tools/environments/local.py::served_profile_child_env`
|
|
(`hermes -p X` workers, `key_cmd` helpers, browser drivers), never `dict(os.environ)`. Grep for
|
|
unscoped handlers before adding one: `rg -n "^(async )?def " tui_gateway/methods_*.py | rg -v
|
|
_profile_scoped`. Probe with two on-disk homes and a `.env` name present only in the secondary:
|
|
call the method for that session and assert the secondary's value resolves and the launch
|
|
profile's does not, and that `os.environ` is unchanged afterwards.
|
|
|
|
## Key surfaces
|
|
|
|
| Surface | Ink component | Gateway method / event |
|
|
|---|---|---|
|
|
| Chat streaming | `app.tsx` + `messageLine.tsx` | `prompt.submit` → `message.delta` / `message.complete` |
|
|
| Tool activity | `thinking.tsx` | `tool.start` / `tool.generating` / `tool.complete` |
|
|
| Approvals | `prompts.tsx` | server→client request `approval` → response `{choice}` |
|
|
| Clarify / sudo / secret | `prompts.tsx`, `maskedPrompt.tsx` | server→client requests `clarify` / `sudo` / `secret` (`server_requests.py`) |
|
|
| Session picker | `sessionPicker.tsx` | `session.list` / `session.resume` |
|
|
| Slash commands | local handler + fallthrough | `slash.exec` → `_SlashWorker`; `command.dispatch` |
|
|
| Completions | `useCompletion` hook | `complete.slash`, `complete.path` (under a non-local `terminal.backend`, `complete.path` lists the directory through the session's terminal backend — never the gateway host, whose same-named tree would look right and be wrong) |
|
|
| Theming | `theme.ts` + `branding.tsx` | `gateway.ready` carries skin data |
|
|
| Connection operations (desktop card) | desktop `store/connection-request.ts` | `connection.request` → `connection.update`* → `connection.respond {op_id}`; `connectors.operation.status`. The op lives in `tools/connectors/live.py`; the card never parks the tool thread (`methods_connectors.py`). |
|
|
|
|
## Shared subagent snapshots
|
|
|
|
`subagent.list({session_id})` returns `{subagents, delegations}` for the calling
|
|
transport's live session. The roster is read-only and follows the CONVERSATION: exact-owner
|
|
records plus children whose durable lineage (`owner_agent_session_id` → compression tip, the
|
|
same spine as in-process `delegate_task(action="list")`) is the session's agent, because a
|
|
Desktop reconnect / resume remints the UI session id and compression rotates the key while the
|
|
children keep running (#114909). Control (`steer` / `interrupt` / `tail`) stays pinned to the
|
|
exact session record and transport. Child authority is resolved at RPC time against the owning session's
|
|
LIVE transport slot, so every authenticated reattach path (prompt.submit, queued drain,
|
|
resume, activate, viewer failover) carries it with no registry bookkeeping — never add a
|
|
per-record transport sync at an attach site; foreign or retired generations remain uncontrollable. `last_tool` is the last started tool, not an in-flight
|
|
indicator. Async completion units are not agents and lack exact generation authority;
|
|
`delegations` remains an empty array for wire compatibility. No dispatch context,
|
|
results, callbacks, or routing keys are sent. Clients hydrate from this snapshot
|
|
on their existing poll and avoid updates when unchanged.
|
|
|
|
`subagent.tail({session_id, subagent_id})` returns
|
|
`{subagent_id, available, text, truncated}`: the last 16 KiB of the live child's
|
|
existing transcript. Poll only the selected detail. Missing/finished/foreign
|
|
children return an unavailable empty snapshot; no client-supplied path is opened.
|
|
This is live-only, not persisted completion history. Invalid session/transport
|
|
returns error 4001. `subagent.steer({session_id, subagent_id, text})` remains the
|
|
shared control: `status: queued` acknowledges acceptance, not delivery; final
|
|
boundary races are reported by the existing runtime as `missed_steer`.
|
|
`subagent.interrupt({session_id, subagent_id})` requires the same exact live
|
|
session/transport/generation ownership, including for subtree members. Missing
|
|
RPC session authority is rejected; direct in-process `interrupt_subagent(id)`
|
|
retains its legacy unscoped contract.
|
|
|
|
## Slash command flow
|
|
|
|
1. Built-in client commands (`/help`, `/quit`, `/clear`, `/resume`, `/copy`, `/paste`, ...) are
|
|
handled locally in `app.tsx`.
|
|
2. Everything else → `slash.exec`, which runs in the persistent `_SlashWorker` subprocess →
|
|
`command.dispatch` fallback, which the gateway resolves into a skill / alias / exec directive
|
|
(a skill command resolves to `{type: "skill", message}` and is submitted as a normal prompt).
|
|
|
|
`commands.catalog` (empty-query list) and `complete.slash` (typed-query completions) already include
|
|
built-ins, user `quick_commands`, AND skill-derived commands (`scan_skill_commands()` /
|
|
`get_skill_commands()`) — clients do not need a new RPC to see skills. The command definitions
|
|
themselves come from `hermes_cli/commands.py` (`hermes_cli/AGENTS.md`).
|
|
|
|
## Dev commands
|
|
|
|
```bash
|
|
cd ui-tui
|
|
npm install # first time
|
|
npm run dev # watch mode (rebuilds hermes-ink + tsx --watch)
|
|
npm start # production
|
|
npm run build # full build (hermes-ink + tsc)
|
|
npm run typecheck # tsc --noEmit
|
|
npm run lint # eslint
|
|
npm run fmt # prettier
|
|
npm test # vitest
|
|
```
|
|
|
|
Python tests: `tests/tui_gateway/` via `scripts/run_tests.sh`. TS tests: vitest in `ui-tui`. A
|
|
Python test that asserts about `package.json` / `.ts` sources will not run on a JS-only PR — keep
|
|
JS-side assertions in vitest (root testing rules). Root TypeScript style rules apply.
|
|
|
|
Related: `web/AGENTS.md` (dashboard embeds this TUI over a PTY), `apps/desktop/AGENTS.md` (own
|
|
renderer on the same backend).
|