72691c6fd6
The mobile composer/footer slid over the message list when the user swiped with the keyboard up. Cause: --vv-height / --vv-offset-top were routed through React state via useMobileKeyboard, so on iOS — which fires visualViewport scroll/resize on the same frame as its keyboard animation — the .chat-thread translation lagged by one paint, visible as the composer momentarily floating over messages. Now those two vars are written imperatively in a useLayoutEffect directly to the .chat-thread DOM node on every visualViewport event, mirroring the working pattern at QuickChatFAB.tsx:1032-1052 (which already works correctly on mobile). Only --keyboard-overlap (a structural open/close signal, not per-frame) still flows through React state. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
101 lines
5.1 KiB
Markdown
101 lines
5.1 KiB
Markdown
# Hermes Runtime Plugin
|
|
|
|
Drives the local **`hermes` CLI** ([NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)) as a subprocess, so a Fusion agent backed by this runtime delegates each prompt to a real Hermes Agent process running on the same machine.
|
|
|
|
## What it does
|
|
|
|
For each `promptWithFallback(session, prompt)` call:
|
|
|
|
1. Spawns `hermes chat -q <prompt> -Q --source tool` (with `--resume <id>` on subsequent calls in the same session).
|
|
2. Captures the trailing `session_id: YYYYMMDD_HHMMSS_xxxxxx` line from stdout.
|
|
3. Strips ANSI + TUI chrome (`╭─ Hermes ─╮`, `↻ Resumed session …`, etc.) and forwards the cleaned response body to `session.callbacks.onText(...)`.
|
|
4. Persists the captured session id on the session object so the next call resumes the same Hermes session.
|
|
|
|
This is fundamentally different from the older "raw-model" approach that bypassed `hermes` entirely by calling `@mariozechner/pi-ai` directly. The CLI subprocess is now the source of truth — provider/model selection, auth, skills, and memory are all the responsibility of the user's local `hermes` install.
|
|
|
|
## Prerequisites
|
|
|
|
You need the `hermes` Python CLI on `PATH` (or set `binaryPath` / `HERMES_BIN`). Install instructions:
|
|
|
|
```bash
|
|
# Recommended: use the upstream installer
|
|
curl -LsSf https://hermes-agent.nousresearch.com/install.sh | sh
|
|
|
|
# Or via pipx (cross-platform)
|
|
pipx install hermes-agent
|
|
```
|
|
|
|
After install, run `hermes login` (or `hermes auth`) to configure a provider. The Fusion plugin does **not** manage Hermes auth — it inherits whatever the local install has.
|
|
|
|
Verify with `hermes --version`.
|
|
|
|
## Fusion skill auto-install
|
|
|
|
When the Hermes runtime plugin loads, it attempts to auto-install/mirror Fusion's bundled `fusion` skill into the active Hermes profile skill directory:
|
|
|
|
- default profile: `${HERMES_HOME:-~/.hermes}/skills/fusion`
|
|
- named profile: `${HERMES_HOME:-~/.hermes}/profiles/<profile>/skills/fusion`
|
|
|
|
The installer is idempotent and self-healing:
|
|
|
|
- leaves an already-correct install untouched
|
|
- replaces prior Fusion installs it can positively identify
|
|
- avoids replacing unrelated user-managed directories
|
|
|
|
If the bundled Fusion skill source is missing or filesystem writes fail, the plugin logs a warning and still starts the Hermes runtime.
|
|
|
|
## Limitations
|
|
|
|
Because we drive the CLI's `chat -q` mode:
|
|
|
|
- **No per-token streaming.** Hermes buffers output through prompt_toolkit; the full response arrives once the process exits. `onText` is called exactly once per turn.
|
|
- **No reasoning/thinking deltas.** `-Q` mode suppresses them. If you need streaming + reasoning, switch to Hermes's ACP mode (not yet implemented in this plugin).
|
|
- **No tool-call hooks.** Hermes runs tools internally; Fusion only sees the final assistant text. Use `yolo: true` to skip Hermes's interactive approval prompts in non-interactive sessions.
|
|
- **No JS tool callbacks.** `customTools` callback functions are still not executable through Hermes CLI mode; Hermes runs its own tool layer and Fusion receives final text.
|
|
- **Fusion context is prompt-mediated.** The engine forwards requested Fusion skill names into `skills`, and the adapter prepends Fusion system/runtime context on the first turn of each session so capability expectations (for example messaging/delegation flows) are not silently dropped on non-pi runtimes.
|
|
- `AgentRuntimeOptions.cwd` / `sessionManager` are still adapter-noops in CLI mode.
|
|
|
|
## Settings
|
|
|
|
| Key | Env var | Default | Notes |
|
|
|---|---|---|---|
|
|
| `binaryPath` | `HERMES_BIN` | `hermes` | Path to the `hermes` binary. Falls back to PATH lookup. |
|
|
| `model` | `HERMES_MODEL_ID` | (Hermes default) | `-m <model>` (e.g. `claude-sonnet-4-5`, `MiniMax-M2.7`). |
|
|
| `provider` | `HERMES_PROVIDER` | (Hermes default) | `--provider <provider>` — one of `auto`, `anthropic`, `openrouter`, `gemini`, `openai-codex`, `copilot`, `copilot-acp`, `huggingface`, `zai`, `kimi-coding`, `minimax`, `minimax-cn`, `kilocode`, `xiaomi`, `nous`. |
|
|
| `maxTurns` | `HERMES_MAX_TURNS` | `12` | `--max-turns N`. Hermes's own default is 90; we cap lower. |
|
|
| `yolo` | `HERMES_YOLO` | `false` | `--yolo` — skip interactive approval. Required for non-interactive sessions that use shell-style tools. |
|
|
| `cliTimeoutMs` | `HERMES_CLI_TIMEOUT_MS` | `300000` (5 min) | Hard kill on the Fusion side. |
|
|
|
|
Settings precedence: plugin settings → env var → default.
|
|
|
|
## Public API
|
|
|
|
```ts
|
|
import {
|
|
HermesRuntimeAdapter,
|
|
resolveCliSettings,
|
|
invokeHermesCli,
|
|
buildHermesArgs,
|
|
parseHermesOutput,
|
|
probeHermesBinary,
|
|
type HermesCliSettings,
|
|
type HermesCliResult,
|
|
type HermesBinaryStatus,
|
|
} from "@fusion-plugin-examples/hermes-runtime";
|
|
```
|
|
|
|
`probeHermesBinary({ binaryPath?, timeoutMs? })` runs `hermes --version` and returns `{ available, version, binaryPath, reason, probeDurationMs }`. Used by the dashboard's "Runtimes → Hermes" settings card to power the install-status badge.
|
|
|
|
## Metadata
|
|
|
|
- **Plugin ID:** `fusion-plugin-hermes-runtime`
|
|
- **Runtime ID:** `hermes`
|
|
- **Package:** `@fusion-plugin-examples/hermes-runtime`
|
|
|
|
## Development
|
|
|
|
```bash
|
|
pnpm --filter @fusion-plugin-examples/hermes-runtime test # 41 tests
|
|
pnpm --filter @fusion-plugin-examples/hermes-runtime build
|
|
```
|