@tunnelbox/hermes 0.1.4 → 0.1.6

package/README.md

@@ -4,11 +4,11 @@
 
 **Official website:** [www.tunnelbox.top](https://www.tunnelbox.top)
 
-**tunnelbox Hermes adapter (standalone daemon):** drive the Hermes Agent on your computer from your phone — sessions, streaming, abort, delete. It drives the Hermes CLI and dials **out** to a relay only (no public IP, no port forwarding).
+**tunnelbox Hermes adapter (standalone daemon):** drive the Hermes Agent on your computer from your phone — sessions, streaming, abort, delete. It drives the Hermes CLI (headless oneshot) and dials **out** to a relay only (no public IP, no port forwarding).
 
 ```
 Phone app ──WSS──► relay ──WSS──► tunnelbox-hermes (this adapter)
-                                      └─ hermes chat -q "<text>" (spawns a hermes subprocess per message)
+                                      └─ hermes chat [--resume <id>] -Q -q "<text>" (spawns a hermes subprocess per message)
 ```
 
 ## Quick start (install → run → pair → use)
@@ -23,7 +23,7 @@ Install the tunnelbox App (Android & iOS) from the official website: **https://w
 
 ### Step 1 — Install the adapter on your computer
 
-Prerequisites: Node.js ≥ 22, and **Hermes Agent** (NousResearch/hermes-agent) installed with login/model configured — `hermes chat -q "hi"` answers correctly.
+Prerequisites: Node.js ≥ 22, and **Hermes Agent** (NousResearch/hermes-agent) installed with login/model configured — `hermes chat -Q -q "hi"` answers correctly.
 
 ```bash
 npm install -g @tunnelbox/hermes
@@ -46,7 +46,11 @@ In the phone app tap **Scan to pair** and scan the terminal QR code (or type the
 
 ### Step 4 — Use it from your phone
 
-In the app, open this computer and you can start new sessions, send messages, watch streaming output, approve risky tool calls, and abort a running session.
+In the app, open this computer and you can start new sessions, send messages, watch streaming output, and abort a running session.
+
+> This package's standalone daemon is the **whole-block fallback** path. For **real-time** remote control
+> (live token streaming, bidirectional messages, phone approval), install the official Hermes **native plugin**
+> (`native-plugin/`, in-process): it runs inside a running Hermes CLI/Gateway and connects to the phone in real time.
 
 ## Configuration
 
@@ -58,9 +62,7 @@ In the app, open this computer and you can start new sessions, send messages, wa
 | `TUNNELBOX_HERMES_PROVIDER` | hermes default | `--provider` (e.g. nous/openrouter) |
 | `TUNNELBOX_HERMES_TOOLSETS` | hermes default | `--toolsets` (comma-separated) |
 | `TUNNELBOX_HERMES_VERBOSE` | off | `--verbose` |
-| `TUNNELBOX_HERMES_BIN` | `hermes` | Hermes executable name / absolute path |
-| `TUNNELBOX_HERMES_APPROVAL` | `on` | Phone approval switch `on`/`off`. When on, tool requests are pushed to the phone via the Hermes `pre_tool_call` hook (**experimental**) |
-| `TUNNELBOX_HERMES_HOOK_PORT` | `18791` | Local approval HTTP port (hook subprocess ↔ adapter) |
+| `TUNNELBOX_HERMES_BIN` | `hermes` | Hermes executable name / absolute path (may include leading args, e.g. `node /path/fake`) |
 
 ```bash
 TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" tunnelbox-hermes
@@ -70,29 +72,21 @@ TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/cla
 
 | Capability | Value | Notes |
 |---|---|---|
-| streaming | ✅ | `hermes chat -q` stdout deltas (ANSI stripped) |
-| thinking | ❌ | `-q` exposes no structured reasoning parts |
-| permission | ✅ default | `pre_tool_call` hook → phone approval card (**experimental**) |
+| streaming | ✅ | `chat -Q -q` emits the whole answer in one block → reported as turn-level `text` + `complete` |
+| thinking | ❌ | oneshot exposes no structured reasoning parts |
+| permission | ❌ | headless has no official approval channel → Hermes' own policy/sandbox fail-closed (phone approval lives in `native-plugin/`) |
 | commands | ✅ | `/new`, `/help` |
 | abort | ✅ | kill subprocess (SIGTERM → SIGKILL) |
 
-## Phone approval (experimental)
-
-Hermes' `pre_tool_call` hook (shell) fires before tool execution. The adapter installs it idempotently into `~/.hermes/config.yaml` (`node <adapter> --hook-pre-tool-call`, with a backup). Each tool call → hook → local HTTP (`127.0.0.1:18791`) → relay → phone approval card; allow/deny is written back (deny blocks the tool, allow no-ops through).
-
-**Semantics:** if the HTTP service is unreachable (adapter not running / `approval=off`), the hook no-ops and lets the tool through (like having no hook, never mis-blocks). Once a request is accepted, offline / timeout (120s) / error → **fail-closed deny**.
-
-> ⚠️ Experimental: Hermes does not officially document whether `hermes chat -q` (single-query) runs config shell hooks. If anything misbehaves, disable with `TUNNELBOX_HERMES_APPROVAL=off` (the injected hook then auto-releases because the service is unreachable).
-
 ## Sessions
 
-- Sessions are local mirrors (`~/.tunnelbox/hermes-sessions/<uuid>/`): each streamed part/user message is written immediately for list/history/delete.
-- Continuation: the adapter tries to parse a Hermes session id (e.g. `20260225_143052_a1b2c3`, `meta.resumeId`) and resumes with `--resume <id>`; if it can't be parsed, each session is an independent Q&A.
+- Sessions are local mirrors (`~/.tunnelbox/hermes-sessions/<uuid>/`): each message is written immediately for list/history/delete.
+- Continuation: after the first turn the adapter discovers the real Hermes session id via `hermes sessions list --workspace <dir>`, stores it in the mirror, and every later turn uses `chat --resume <id> -Q -q` (Hermes persistence guarantees multi-turn context). Verified on Hermes v0.21.1 (note: `hermes -z` does not resume, and caller-minted ids are invalid).
 - State file: `~/.tunnelbox/remote-state.hermes.json`.
 
 ## Security notes
 
-- Tool execution / command authorization is governed by Hermes' own policy; the adapter never auto-approves. `TUNNELBOX_HERMES_APPROVAL=off` disables the phone approval card.
+- Tool execution / command authorization is governed by Hermes' own policy (dangerous commands fail closed); this adapter never auto-approves and never rewrites `~/.hermes/config.yaml`.
 - Don't run unrestricted toolsets in untrusted directories, and don't expose sensitive projects to an untrusted phone.
 
 ## Multilingual
@@ -107,6 +101,7 @@ User-visible output supports 8 languages (`zh-CN` / `zh-TW` / `en-US` / `ja-JP`
 | Need to pair a different phone | Unbind in the app settings, then run with `--pair` again |
 | Already bound but phone doesn't connect | Confirm both use the same relay; check `~/.tunnelbox/tunnelbox.log` |
 | Use your own relay | Start with `TUNNELBOX_RELAY_URL=wss://<your-relay>` |
+| Hermes misbehaves / unexpected output | On a machine with hermes, run `npm run probe` and send the structured diagnostics back to maintainers |
 
 ## State files
 
@@ -125,4 +120,4 @@ Remove `~/.tunnelbox` (all adapters' shared state) only if you no longer use any
 
 ## Development
 
-Implementation details (protocol mapping, source layout, design decisions, untested items) are kept in the source repository as `DEV.md` next to this package, plus the protocol spec under the repo's `docs/`.
+Implementation details (protocol mapping, source layout, design decisions, untested items) are kept in the source repository as `DEV.md` next to this package, plus the protocol spec under the repo's `docs/`.

package/README.zh-CN.md

@@ -4,11 +4,11 @@
 
 **官网：** [www.tunnelbox.top](https://www.tunnelbox.top)
 
-**tunnelbox Hermes 适配器（独立进程）**：用手机远程驱动电脑上的 Hermes Agent——会话 / 流式 / 中止 / 删除。它驱动 Hermes CLI，只向中继发出站连接（无需公网 IP / 端口映射）。
+**tunnelbox Hermes 适配器（独立进程）**：用手机远程驱动电脑上的 Hermes Agent——会话 / 流式 / 中止 / 删除。它驱动 Hermes CLI（headless oneshot），只向中继发出站连接（无需公网 IP / 端口映射）。
 
 ```
 手机 App ──WSS──► relay ──WSS──► tunnelbox-hermes（本适配器）
-                                      └─ hermes chat -q "<text>"（每条消息拉起一个 hermes 子进程）
+                                      └─ hermes chat [--resume <id>] -Q -q "<text>"（每条消息拉起一个 hermes 子进程）
 ```
 
 ## 快速上手（安装 → 运行 → 配对 → 使用）
@@ -23,7 +23,7 @@
 
 ### 第 1 步 — 电脑上安装适配器
 
-前置条件：Node.js ≥ 22，且本机已安装 **Hermes Agent**（NousResearch/hermes-agent）并完成登录/模型配置——`hermes chat -q "hi"` 能正常应答。
+前置条件：Node.js ≥ 22，且本机已安装 **Hermes Agent**（NousResearch/hermes-agent）并完成登录/模型配置——`hermes chat -Q -q "hi"` 能正常应答。
 
 ```bash
 npm install -g @tunnelbox/hermes
@@ -46,7 +46,9 @@ tunnelbox-hermes
 
 ### 第 4 步 — 在手机上使用
 
-在 App 里打开这台电脑，即可新建会话、发消息、看流式输出、审批危险工具调用、中止运行中的会话。
+在 App 里打开这台电脑，即可新建会话、发消息、看流式输出、中止运行中的会话。
+
+> 本包的 headless 桥（spawn-per-message）为**整段 fallback** 路径；需要**实时**远程控制（逐 token 流式 / 双向消息 / 手机审批 / 选择）请安装官方 **Native 插件**（`native-plugin/`，进程内，需本机运行 Hermes CLI/Gateway）。headless 本身不提供手机审批。
 
 ## 配置
 
@@ -58,9 +60,7 @@ tunnelbox-hermes
 | `TUNNELBOX_HERMES_PROVIDER` | hermes 默认 | `--provider`（如 nous/openrouter） |
 | `TUNNELBOX_HERMES_TOOLSETS` | hermes 默认 | `--toolsets`（逗号分隔） |
 | `TUNNELBOX_HERMES_VERBOSE` | 关 | `--verbose` |
-| `TUNNELBOX_HERMES_BIN` | `hermes` | hermes 可执行名/绝对路径 |
-| `TUNNELBOX_HERMES_APPROVAL` | `on` | 手机审批开关 `on`/`off`。开启时经 Hermes `pre_tool_call` hook 把工具请求推到手机审批卡（**实验**） |
-| `TUNNELBOX_HERMES_HOOK_PORT` | `18791` | 本地审批 HTTP 端口（hook 子进程与适配器通信用） |
+| `TUNNELBOX_HERMES_BIN` | `hermes` | hermes 可执行名/绝对路径（可带前置参数，如 `node /path/fake`） |
 
 ```bash
 TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" tunnelbox-hermes
@@ -70,29 +70,21 @@ TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/cla
 
 | 能力 | 值 | 说明 |
 |---|---|---|
-| streaming | ✅ | `hermes chat -q` stdout 增量（剥离 ANSI） |
-| thinking | ❌ | `-q` 无结构化推理部件 |
-| permission | ✅ 默认 | `pre_tool_call` hook → 手机审批卡（**实验**） |
+| streaming | ✅ | `chat -Q -q` 整段一次性输出 → 回合级 `text`+`complete` 回传 |
+| thinking | ❌ | oneshot 无结构化推理部件 |
+| permission | ❌ | headless 无官方审批通道 → Hermes 自身策略/沙箱 fail-closed 兜底（手机审批见 `native-plugin/`） |
 | commands | ✅ | `/new`、`/help` |
 | abort | ✅ | kill 子进程（SIGTERM → SIGKILL） |
 
-## 手机审批（实验）
-
-Hermes 的 `pre_tool_call` hook（shell）在工具执行前触发。适配器把它幂等注入 `~/.hermes/config.yaml`（`node <适配器> --hook-pre-tool-call`，写前备份）。每次工具调用 → hook → 本地 HTTP（`127.0.0.1:18791`）→ 中继 → 手机审批卡；allow/deny 回填（deny 阻止工具，allow no-op 放行）。
-
-**语义**：HTTP 服务不可达（适配器未运行 / `approval=off`）→ hook no-op 放行（等同无 hook，不误拦）；请求已被接受但手机离线 / 超时（120s）/ 异常 → **fail-closed 拒绝**。
-
-> ⚠️ 实验性：Hermes 官方未明确 `hermes chat -q`（single-query）是否运行 config shell hooks。异常时可 `TUNNELBOX_HERMES_APPROVAL=off` 关闭（注入的 hook 因服务不可达自动放行，恢复无 hook 行为）。
-
 ## 会话模型
 
-- 会话 = 本地镜像（`~/.tunnelbox/hermes-sessions/<uuid>/`）：每个流式部件/用户消息即时落盘，供列表/历史/删除。
-- 续聊：尽力从输出解析 hermes session id（如 `20260225_143052_a1b2c3`，`meta.resumeId`）→ 后续消息用 `--resume <id>`；解析不到则该会话为独立问答。
+- 会话 = 本地镜像（`~/.tunnelbox/hermes-sessions/<uuid>/`）：每条消息即时落盘，供列表/历史/删除。
+- 续聊：首轮后经 `hermes sessions list --workspace <目录>` 发现 Hermes 真实会话 id 存镜像，后续每轮 `chat --resume <id> -Q -q`（Hermes 官方持久化保证多轮上下文）。已在 Hermes v0.21.1 真机验证（`hermes -z` 不续聊、自定义 id 无效）。
 - 状态文件：`~/.tunnelbox/remote-state.hermes.json`。
 
 ## 安全说明
 
-- 工具执行/命令授权由 Hermes 自身策略管理，本适配器不自动放行；`TUNNELBOX_HERMES_APPROVAL=off` 关闭手机审批卡。
+- 工具执行/命令授权由 Hermes 自身策略管理（危险命令 fail-closed）；本适配器不自动放行，也不改写用户 `~/.hermes/config.yaml`。
 - 请勿在不受信目录运行不受限工具集，也别把敏感工程目录暴露给不受信手机。
 
 ## 多语言
@@ -107,6 +99,7 @@ Hermes 的 `pre_tool_call` hook（shell）在工具执行前触发。适配器
 | 需要换手机配对 | 在 App 设置里解绑，再带 `--pair` 运行 |
 | 已绑定但手机连不上 | 确认两端同一中继；查看 `~/.tunnelbox/tunnelbox.log` |
 | 使用自建中继 | 启动时带 `TUNNELBOX_RELAY_URL=wss://<你的中继>` |
+| Hermes 应答异常/行为不符 | 在装有 hermes 的机器运行 `npm run probe`，输出结构化诊断回传维护者 |
 
 ## 状态文件
 
@@ -125,4 +118,4 @@ npm uninstall -g @tunnelbox/hermes
 
 ## 开发
 
-实现细节（协议映射、源码结构、决策记录、待实测项）保存在源码仓库中本包旁的 `DEV.md` 与仓库 `docs/` 下。
+实现细节（协议映射、源码结构、决策记录、待实测项）保存在源码仓库中本包旁的 `DEV.md` 与仓库 `docs/` 下。