@tunnelbox/hermes 0.1.1 → 0.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +99 -53
  2. package/README.zh-CN.md +128 -0
  3. package/dist/index.mjs +1485 -52
  4. package/package.json +41 -36
package/README.md CHANGED
@@ -1,82 +1,128 @@
1
1
  # @tunnelbox/hermes
2
2
 
3
- tunnelbox 的 **Hermes Agent 适配器**（B 类，独立进程，Python 框架/CLI 桥接）：手机远程驱动电脑上的 Hermes Agent（会话/流式/中止/删除），复用 `@tunnelbox/core`（RelayClient/状态/二维码）。
3
+ [English](README.md) · [简体中文](README.zh-CN.md)
4
+
5
+ **Official website:** [www.tunnelbox.top](https://www.tunnelbox.top)
6
+
7
+ **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).
4
8
 
5
9
  ```
6
- 手机 PWA ──WSS──► relay ──WSS──► 本适配器（电脑上常驻 Node 进程）
7
- └─ hermes chat -q "<text>"（每消息一次子进程）
10
+ Phone app ──WSS──► relay ──WSS──► tunnelbox-hermes (this adapter)
11
+ └─ hermes chat -q "<text>" (spawns a hermes subprocess per message)
8
12
  ```
9
13
 
10
- ## 前置条件
14
+ ## Quick start (install → run → pair → use)
15
+
16
+ Follow these steps once on a computer that has Hermes installed and configured.
17
+
18
+ ### Step 0 — Prepare your phone
11
19
 
12
- - Node.js ≥ 22；
13
- - 本机已安装 **Hermes Agent**（NousResearch/hermes-agent）并完成登录/模型配置：
14
- `curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash`（或各平台安装方式），
15
- `hermes setup` / `hermes portal` 可用，`hermes chat -q "hi"` 能正常应答。
16
- - CLI 非交互单轮模式：`hermes chat -q "…"`（`--model/--provider/--toolsets/--query-file`）。
20
+ Install the tunnelbox App (Android & iOS) from the official website: **https://www.tunnelbox.top**
17
21
 
18
- ## 构建与运行
22
+ - Sign in / create an account when prompted.
23
+
24
+ ### Step 1 — Install the adapter on your computer
25
+
26
+ Prerequisites: Node.js ≥ 22, and **Hermes Agent** (NousResearch/hermes-agent) installed with login/model configured — `hermes chat -q "hi"` answers correctly.
19
27
 
20
28
  ```bash
21
- cd plugin && npm install # workspaces 根（含 hermes）
22
- cd hermes && npm run build
23
- node dist/index.mjs # 或 npm start
29
+ npm install -g @tunnelbox/hermes
24
30
  ```
25
31
 
26
- ## 配置
32
+ ### Step 2 — Run it
33
+
34
+ ```bash
35
+ tunnelbox-hermes
36
+ ```
37
+
38
+ On first start the adapter connects to the relay and prints a **pairing QR code + pairing code** in the terminal.
39
+
40
+ ### Step 3 — Pair with your phone
41
+
42
+ In the phone app tap **Scan to pair** and scan the terminal QR code (or type the pairing code manually). The code is single-use and valid for about 10 minutes.
43
+
44
+ - Once bound, the adapter prints "connected account — open the app and pick this computer" on later starts and does not refresh the code.
45
+ - Want a fresh code any time? Run `tunnelbox-hermes --pair`.
46
+
47
+ ### Step 4 — Use it from your phone
48
+
49
+ 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.
27
50
 
28
- | 环境变量 | 默认 | 说明 |
51
+ ## Configuration
52
+
53
+ | Env var | Default | Description |
29
54
  |---|---|---|
30
- | `TUNNELBOX_RELAY_URL` | state 保存地址 | 中继地址 |
31
- | `TUNNELBOX_CWD` | `process.cwd()` | 默认工作区 |
32
- | `TUNNELBOX_HERMES_MODEL` | hermes 默认 | `--model` |
33
- | `TUNNELBOX_HERMES_PROVIDER` | hermes 默认 | `--provider`（如 nous/openrouter） |
34
- | `TUNNELBOX_HERMES_TOOLSETS` | hermes 默认 | `--toolsets`（逗号分隔） |
35
- | `TUNNELBOX_HERMES_VERBOSE` | 关 | `--verbose` |
36
- | `TUNNELBOX_HERMES_BIN` | `hermes` | hermes 可执行名/绝对路径 |
55
+ | `TUNNELBOX_RELAY_URL` | saved relay URL | Relay address |
56
+ | `TUNNELBOX_CWD` | `process.cwd()` | Default workspace |
57
+ | `TUNNELBOX_HERMES_MODEL` | hermes default | `--model` |
58
+ | `TUNNELBOX_HERMES_PROVIDER` | hermes default | `--provider` (e.g. nous/openrouter) |
59
+ | `TUNNELBOX_HERMES_TOOLSETS` | hermes default | `--toolsets` (comma-separated) |
60
+ | `TUNNELBOX_HERMES_VERBOSE` | off | `--verbose` |
61
+ | `TUNNELBOX_HERMES_BIN` | `hermes` | Hermes executable name / absolute path |
62
+ | `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**) |
63
+ | `TUNNELBOX_HERMES_HOOK_PORT` | `18791` | Local approval HTTP port (hook subprocess ↔ adapter) |
37
64
 
38
65
  ```bash
39
- TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" node dist/index.mjs
66
+ TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" tunnelbox-hermes
40
67
  ```
41
68
 
42
- ## 能力位
69
+ ## Capabilities
43
70
 
44
- | 能力 | 值 | 说明 |
71
+ | Capability | Value | Notes |
45
72
  |---|---|---|
46
- | streaming | true | `hermes chat -q` stdout 增量剥离 ANSI 后按到达转发 delta |
47
- | thinking | false | `-q` 无结构化推理部件 |
48
- | permission | **false** | 无审批回调；工具集/授权由 hermes 自身安全策略决定 |
49
- | commands | true | `/new` `/help` |
50
- | abort | true | kill 子进程（SIGTERM → SIGKILL） |
73
+ | streaming | ✅ | `hermes chat -q` stdout deltas (ANSI stripped) |
74
+ | thinking | ❌ | `-q` exposes no structured reasoning parts |
75
+ | permission | ✅ default | `pre_tool_call` hook → phone approval card (**experimental**) |
76
+ | commands | ✅ | `/new`, `/help` |
77
+ | abort | ✅ | kill subprocess (SIGTERM → SIGKILL) |
51
78
 
52
- ## 会话模型
79
+ ## Phone approval (experimental)
53
80
 
54
- - 会话 = 本地镜像（`~/.config/opencode/hermes-sessions/<uuid>/`）：每个流式部件/用户消息即时落一行，供列表/历史/删除。
55
- - 续聊：尽力从输出解析 hermes session id（形如 `20260225_143052_a1b2c3`，`meta.resumeId`）→ 后续消息用 `--resume <id>`；解析不到则该会话每次为独立问答（连续上下文受限）。
56
- - 状态文件：`~/.config/opencode/remote-state.hermes.json`。
81
+ 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).
57
82
 
58
- ## 官方 Hermes 插件（native-plugin）
83
+ **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**.
59
84
 
60
- 本包同时提供符合 Hermes 官方插件体系的 **Native 插件**（`native-plugin/`，Python，`plugin.yaml` + `register(ctx)`），
61
- 在本机 Hermes 会话内使用（工具 `tunnelbox_pair`/`tunnelbox_status`、`/tunnelbox` 命令、打包技能 + 实验性回合级手机桥）——
62
- 功能主体仍由本 headless 桥承担。安装/配置/局限见 [`native-plugin/README.md`](./native-plugin/README.md)。
85
+ > ⚠️ 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).
63
86
 
64
- ## 目录结构
87
+ ## Sessions
65
88
 
89
+ - Sessions are local mirrors (`~/.tunnelbox/hermes-sessions/<uuid>/`): each streamed part/user message is written immediately for list/history/delete.
90
+ - 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.
91
+ - State file: `~/.tunnelbox/remote-state.hermes.json`.
92
+
93
+ ## Security notes
94
+
95
+ - Tool execution / command authorization is governed by Hermes' own policy; the adapter never auto-approves. `TUNNELBOX_HERMES_APPROVAL=off` disables the phone approval card.
96
+ - Don't run unrestricted toolsets in untrusted directories, and don't expose sensitive projects to an untrusted phone.
97
+
98
+ ## Multilingual
99
+
100
+ User-visible output supports 8 languages (`zh-CN` / `zh-TW` / `en-US` / `ja-JP` / `ko-KR` / `fr-FR` / `de-DE` / `es-ES`). Resolution order: `TUNNELBOX_LANG` > saved `remote-state.hermes.json.lang` > system locale > `en-US`.
101
+
102
+ ## Troubleshooting
103
+
104
+ | Problem | Fix |
105
+ |---|---|
106
+ | No QR / pairing code on screen | Run `tunnelbox-hermes --pair` to print a fresh one |
107
+ | Need to pair a different phone | Unbind in the app settings, then run with `--pair` again |
108
+ | Already bound but phone doesn't connect | Confirm both use the same relay; check `~/.tunnelbox/tunnelbox.log` |
109
+ | Use your own relay | Start with `TUNNELBOX_RELAY_URL=wss://<your-relay>` |
110
+
111
+ ## State files
112
+
113
+ - `~/.tunnelbox/remote-state.hermes.json` — agentID / relay / bound state / language
114
+ - `~/.tunnelbox/hermes-sessions/` — local session mirrors
115
+ - `~/.tunnelbox/remote-pairing.hermes.txt` + `remote-pairing.json` — latest pairing info
116
+ - `~/.tunnelbox/tunnelbox.log` — adapter log
117
+
118
+ ## Uninstall
119
+
120
+ ```bash
121
+ npm uninstall -g @tunnelbox/hermes
66
122
  ```
67
- plugin/hermes/
68
- ├── package.json / tsconfig.json
69
- ├── scripts/build.mjs / smoke.mjs
70
- ├── native-plugin/ # ★ Hermes 官方 Native 插件（Python，本机会话内配对/状态 + 回合级桥实验）
71
- └── src/
72
- ├── index.ts # env 解析 + 连接中继
73
- ├── bridge.ts # relay/配对/消息路由/回合/镜像写入
74
- ├── runner.ts # hermes chat -q 子进程（stdout 增量 + ANSI 剥离 + session id 采集 + kill）
75
- ├── mirror.ts # 会话镜像存储（列表/历史/删除/meta）
76
- └── globals.d.ts
77
- ```
78
123
 
79
- ## 备注
124
+ Remove `~/.tunnelbox` (all adapters' shared state) only if you no longer use any tunnelbox adapter.
125
+
126
+ ## Development
80
127
 
81
- - 未验证项（需装有 hermes 实测校正）：`hermes chat -q` 在 stdout 的确切输出（是否 ANSI/分批/进度行）、`chat -q` 下 `--resume` 参数位置与语义、session id 是否出现在 `-q` 输出中、`--toolsets/--provider` 参数名。解析集中在 `runner.ts`。
82
- - 安全：hermes 工具执行/命令授权由其自身策略（config/安全文档）管理，本适配器不自动放行；请勿在不受信目录运行时不受限工具集。
128
+ 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 ADDED
@@ -0,0 +1,128 @@
1
+ # @tunnelbox/hermes
2
+
3
+ [English](README.md) · [简体中文](README.zh-CN.md)
4
+
5
+ **官网：** [www.tunnelbox.top](https://www.tunnelbox.top)
6
+
7
+ **tunnelbox Hermes 适配器（独立进程）**：用手机远程驱动电脑上的 Hermes Agent——会话 / 流式 / 中止 / 删除。它驱动 Hermes CLI，只向中继发出站连接（无需公网 IP / 端口映射）。
8
+
9
+ ```
10
+ 手机 App ──WSS──► relay ──WSS──► tunnelbox-hermes（本适配器）
11
+ └─ hermes chat -q "<text>"（每条消息拉起一个 hermes 子进程）
12
+ ```
13
+
14
+ ## 快速上手（安装 → 运行 → 配对 → 使用）
15
+
16
+ 在装有 Hermes 并完成配置的电脑上，按以下步骤操作一次即可。
17
+
18
+ ### 第 0 步 — 准备手机
19
+
20
+ 在官网下载并安装 tunnelbox App（Android / iOS 均已上架）：**https://www.tunnelbox.top**
21
+
22
+ - 按提示登录/注册账号。
23
+
24
+ ### 第 1 步 — 电脑上安装适配器
25
+
26
+ 前置条件：Node.js ≥ 22，且本机已安装 **Hermes Agent**（NousResearch/hermes-agent）并完成登录/模型配置——`hermes chat -q "hi"` 能正常应答。
27
+
28
+ ```bash
29
+ npm install -g @tunnelbox/hermes
30
+ ```
31
+
32
+ ### 第 2 步 — 运行
33
+
34
+ ```bash
35
+ tunnelbox-hermes
36
+ ```
37
+
38
+ 首次启动会连接中继，并在终端打印**配对二维码 + 配对码**。
39
+
40
+ ### 第 3 步 — 与手机配对
41
+
42
+ 在手机 App 点「扫一扫配对」，扫描终端二维码（或手动输入配对码）。配对码一次性有效，约 10 分钟。
43
+
44
+ - 绑定后再次启动会打印「已绑定账号，从手机「我的电脑」直接连接」，不再刷新码；
45
+ - 随时需要新码：运行 `tunnelbox-hermes --pair`。
46
+
47
+ ### 第 4 步 — 在手机上使用
48
+
49
+ 在 App 里打开这台电脑，即可新建会话、发消息、看流式输出、审批危险工具调用、中止运行中的会话。
50
+
51
+ ## 配置
52
+
53
+ | 环境变量 | 默认 | 说明 |
54
+ |---|---|---|
55
+ | `TUNNELBOX_RELAY_URL` | state 保存的地址 | 中继地址 |
56
+ | `TUNNELBOX_CWD` | `process.cwd()` | 默认工作区 |
57
+ | `TUNNELBOX_HERMES_MODEL` | hermes 默认 | `--model` |
58
+ | `TUNNELBOX_HERMES_PROVIDER` | hermes 默认 | `--provider`（如 nous/openrouter） |
59
+ | `TUNNELBOX_HERMES_TOOLSETS` | hermes 默认 | `--toolsets`（逗号分隔） |
60
+ | `TUNNELBOX_HERMES_VERBOSE` | 关 | `--verbose` |
61
+ | `TUNNELBOX_HERMES_BIN` | `hermes` | hermes 可执行名/绝对路径 |
62
+ | `TUNNELBOX_HERMES_APPROVAL` | `on` | 手机审批开关 `on`/`off`。开启时经 Hermes `pre_tool_call` hook 把工具请求推到手机审批卡（**实验**） |
63
+ | `TUNNELBOX_HERMES_HOOK_PORT` | `18791` | 本地审批 HTTP 端口（hook 子进程与适配器通信用） |
64
+
65
+ ```bash
66
+ TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" tunnelbox-hermes
67
+ ```
68
+
69
+ ## 能力位
70
+
71
+ | 能力 | 值 | 说明 |
72
+ |---|---|---|
73
+ | streaming | ✅ | `hermes chat -q` stdout 增量（剥离 ANSI） |
74
+ | thinking | ❌ | `-q` 无结构化推理部件 |
75
+ | permission | ✅ 默认 | `pre_tool_call` hook → 手机审批卡（**实验**） |
76
+ | commands | ✅ | `/new`、`/help` |
77
+ | abort | ✅ | kill 子进程（SIGTERM → SIGKILL） |
78
+
79
+ ## 手机审批（实验）
80
+
81
+ 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 放行）。
82
+
83
+ **语义**：HTTP 服务不可达（适配器未运行 / `approval=off`）→ hook no-op 放行（等同无 hook，不误拦）；请求已被接受但手机离线 / 超时（120s）/ 异常 → **fail-closed 拒绝**。
84
+
85
+ > ⚠️ 实验性：Hermes 官方未明确 `hermes chat -q`（single-query）是否运行 config shell hooks。异常时可 `TUNNELBOX_HERMES_APPROVAL=off` 关闭（注入的 hook 因服务不可达自动放行，恢复无 hook 行为）。
86
+
87
+ ## 会话模型
88
+
89
+ - 会话 = 本地镜像（`~/.tunnelbox/hermes-sessions/<uuid>/`）：每个流式部件/用户消息即时落盘，供列表/历史/删除。
90
+ - 续聊：尽力从输出解析 hermes session id（如 `20260225_143052_a1b2c3`，`meta.resumeId`）→ 后续消息用 `--resume <id>`；解析不到则该会话为独立问答。
91
+ - 状态文件：`~/.tunnelbox/remote-state.hermes.json`。
92
+
93
+ ## 安全说明
94
+
95
+ - 工具执行/命令授权由 Hermes 自身策略管理，本适配器不自动放行；`TUNNELBOX_HERMES_APPROVAL=off` 关闭手机审批卡。
96
+ - 请勿在不受信目录运行不受限工具集，也别把敏感工程目录暴露给不受信手机。
97
+
98
+ ## 多语言
99
+
100
+ 用户可见输出支持 8 种语言（`zh-CN` / `zh-TW` / `en-US` / `ja-JP` / `ko-KR` / `fr-FR` / `de-DE` / `es-ES`）。解析顺序：`TUNNELBOX_LANG` > `remote-state.hermes.json` 的 `lang` > 系统 locale > 默认 `en-US`。
101
+
102
+ ## 故障排查
103
+
104
+ | 问题 | 解决 |
105
+ |---|---|
106
+ | 终端没有二维码/配对码 | 运行 `tunnelbox-hermes --pair` 打印新码 |
107
+ | 需要换手机配对 | 在 App 设置里解绑，再带 `--pair` 运行 |
108
+ | 已绑定但手机连不上 | 确认两端同一中继；查看 `~/.tunnelbox/tunnelbox.log` |
109
+ | 使用自建中继 | 启动时带 `TUNNELBOX_RELAY_URL=wss://<你的中继>` |
110
+
111
+ ## 状态文件
112
+
113
+ - `~/.tunnelbox/remote-state.hermes.json` — agentID / 中继地址 / 绑定状态 / 语言
114
+ - `~/.tunnelbox/hermes-sessions/` — 本地会话镜像
115
+ - `~/.tunnelbox/remote-pairing.hermes.txt` + `remote-pairing.json` — 最新配对信息
116
+ - `~/.tunnelbox/tunnelbox.log` — 适配器日志
117
+
118
+ ## 卸载
119
+
120
+ ```bash
121
+ npm uninstall -g @tunnelbox/hermes
122
+ ```
123
+
124
+ 仅当不再使用任何 tunnelbox 适配器时，才删除 `~/.tunnelbox`（各适配器共享状态）。
125
+
126
+ ## 开发
127
+
128
+ 实现细节（协议映射、源码结构、决策记录、待实测项）保存在源码仓库中本包旁的 `DEV.md` 与仓库 `docs/` 下。