Update CLI chat session bridge (#697)

* feat: add CLI chat sessions with Python agent bridge Introduce a new CLI chat mode that connects Web UI directly to Hermes Agent's AIAgent via a Python bridge subprocess and Socket.IO, bypassing the API Server /v1/responses path. Supports streaming, slash commands (/new, /undo, /retry, /branch, /compress, /save, /title), interrupt, and steer. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com> * feat: update CLI chat session bridge * fix: extend agent bridge startup timeouts * docs: update bridge chat session design * feat: align bridge compression and provider registry * chore: bump version to 0.5.20 --------- Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-14 09:03:57 +08:00
parent e0fcc0040b
commit eae7195ba8
31 changed files with 3906 additions and 1040 deletions
@@ -0,0 +1,85 @@
+# Agent Bridge
+
+Optional backend-side bridge for talking to `~/.hermes/hermes-agent` by
+instantiating `run_agent.AIAgent` directly in a Python process.
+
+This is intentionally separate from the current Web UI chat path.
+
+## Python Service
+
+```bash
+python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py
+```
+
+Default endpoint:
+
+```text
+ipc:///tmp/hermes-agent-bridge.sock
+```
+
+On Windows, the default endpoint is TCP because Python may not support Unix
+domain sockets there:
+
+```text
+tcp://127.0.0.1:18765
+```
+
+Override with:
+
+```bash
+HERMES_AGENT_BRIDGE_ENDPOINT=tcp://127.0.0.1:8765 python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py
+```
+
+The service discovers Hermes Agent in this order:
+
+1. `--agent-root`
+2. `HERMES_AGENT_ROOT`
+3. the installed `hermes` command path
+4. current working directory and parent directories
+5. common locations such as `~/.hermes/hermes-agent`, `~/hermes-agent`, and `/opt/hermes-agent`
+
+Hermes home is resolved from `--hermes-home`, `HERMES_HOME`, then `~/.hermes`.
+
+Default agent root:
+
+```text
+~/.hermes/hermes-agent
+```
+
+You can pass both paths explicitly:
+
+```bash
+python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py \
+  --agent-root ~/.hermes/hermes-agent \
+  --hermes-home ~/.hermes
+```
+
+The socket transport uses Python and Node standard libraries. No ZMQ dependency
+is required.
+
+## Backend Usage
+
+```ts
+import { AgentBridgeClient } from './services/hermes/agent-bridge'
+
+const bridge = new AgentBridgeClient()
+const run = await bridge.chat(sessionId, message)
+
+for await (const chunk of bridge.streamOutput(run.run_id)) {
+  if (chunk.delta) {
+    // forward chunk.delta to Socket.IO/SSE/etc.
+  }
+}
+```
+
+The external chat call only sends `session_id` and `message`. Provider, model,
+keys, tools, reasoning, and session DB are resolved by hermes-agent from the
+normal Hermes config and environment.
+
+The bridge instantiates `AIAgent` with `platform="cli"` by default so behavior
+matches CLI chat. Override it only if a caller intentionally needs a distinct
+platform identity:
+
+```bash
+HERMES_AGENT_BRIDGE_PLATFORM=agent-bridge python packages/server/src/services/hermes/agent-bridge/hermes_bridge.py
+```