@tunnelbox/hermes 0.1.3 → 0.1.5
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.
- package/README.md +123 -97
- package/README.zh-CN.md +121 -0
- package/dist/index.mjs +613 -554
- package/package.json +9 -6
package/README.md
CHANGED
|
@@ -1,97 +1,123 @@
|
|
|
1
|
-
# @tunnelbox/hermes
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
##
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
1
|
+
# @tunnelbox/hermes
|
|
2
|
+
|
|
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 (headless oneshot) and dials **out** to a relay only (no public IP, no port forwarding).
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
Phone app ──WSS──► relay ──WSS──► tunnelbox-hermes (this adapter)
|
|
11
|
+
└─ hermes chat [--resume <id>] -Q -q "<text>" (spawns a hermes subprocess per message)
|
|
12
|
+
```
|
|
13
|
+
|
|
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
|
|
19
|
+
|
|
20
|
+
Install the tunnelbox App (Android & iOS) from the official website: **https://www.tunnelbox.top**
|
|
21
|
+
|
|
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 -q "hi"` answers correctly.
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npm install -g @tunnelbox/hermes
|
|
30
|
+
```
|
|
31
|
+
|
|
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, and abort a running session.
|
|
50
|
+
|
|
51
|
+
> This package's standalone daemon is the **whole-block fallback** path. For **real-time** remote control
|
|
52
|
+
> (live token streaming, bidirectional messages, phone approval), install the official Hermes **native plugin**
|
|
53
|
+
> (`native-plugin/`, in-process): it runs inside a running Hermes CLI/Gateway and connects to the phone in real time.
|
|
54
|
+
|
|
55
|
+
## Configuration
|
|
56
|
+
|
|
57
|
+
| Env var | Default | Description |
|
|
58
|
+
|---|---|---|
|
|
59
|
+
| `TUNNELBOX_RELAY_URL` | saved relay URL | Relay address |
|
|
60
|
+
| `TUNNELBOX_CWD` | `process.cwd()` | Default workspace |
|
|
61
|
+
| `TUNNELBOX_HERMES_MODEL` | hermes default | `--model` |
|
|
62
|
+
| `TUNNELBOX_HERMES_PROVIDER` | hermes default | `--provider` (e.g. nous/openrouter) |
|
|
63
|
+
| `TUNNELBOX_HERMES_TOOLSETS` | hermes default | `--toolsets` (comma-separated) |
|
|
64
|
+
| `TUNNELBOX_HERMES_VERBOSE` | off | `--verbose` |
|
|
65
|
+
| `TUNNELBOX_HERMES_BIN` | `hermes` | Hermes executable name / absolute path (may include leading args, e.g. `node /path/fake`) |
|
|
66
|
+
|
|
67
|
+
```bash
|
|
68
|
+
TUNNELBOX_RELAY_URL=wss://chat.example.com TUNNELBOX_HERMES_MODEL="anthropic/claude-sonnet-4" tunnelbox-hermes
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Capabilities
|
|
72
|
+
|
|
73
|
+
| Capability | Value | Notes |
|
|
74
|
+
|---|---|---|
|
|
75
|
+
| streaming | ✅ | `chat -Q -q` emits the whole answer in one block → reported as turn-level `text` + `complete` |
|
|
76
|
+
| thinking | ❌ | oneshot exposes no structured reasoning parts |
|
|
77
|
+
| permission | ❌ | headless has no official approval channel → Hermes' own policy/sandbox fail-closed (phone approval lives in `native-plugin/`) |
|
|
78
|
+
| commands | ✅ | `/new`, `/help` |
|
|
79
|
+
| abort | ✅ | kill subprocess (SIGTERM → SIGKILL) |
|
|
80
|
+
|
|
81
|
+
## Sessions
|
|
82
|
+
|
|
83
|
+
- Sessions are local mirrors (`~/.tunnelbox/hermes-sessions/<uuid>/`): each message is written immediately for list/history/delete.
|
|
84
|
+
- 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).
|
|
85
|
+
- State file: `~/.tunnelbox/remote-state.hermes.json`.
|
|
86
|
+
|
|
87
|
+
## Security notes
|
|
88
|
+
|
|
89
|
+
- 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`.
|
|
90
|
+
- Don't run unrestricted toolsets in untrusted directories, and don't expose sensitive projects to an untrusted phone.
|
|
91
|
+
|
|
92
|
+
## Multilingual
|
|
93
|
+
|
|
94
|
+
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`.
|
|
95
|
+
|
|
96
|
+
## Troubleshooting
|
|
97
|
+
|
|
98
|
+
| Problem | Fix |
|
|
99
|
+
|---|---|
|
|
100
|
+
| No QR / pairing code on screen | Run `tunnelbox-hermes --pair` to print a fresh one |
|
|
101
|
+
| Need to pair a different phone | Unbind in the app settings, then run with `--pair` again |
|
|
102
|
+
| Already bound but phone doesn't connect | Confirm both use the same relay; check `~/.tunnelbox/tunnelbox.log` |
|
|
103
|
+
| Use your own relay | Start with `TUNNELBOX_RELAY_URL=wss://<your-relay>` |
|
|
104
|
+
| Hermes misbehaves / unexpected output | On a machine with hermes, run `npm run probe` and send the structured diagnostics back to maintainers |
|
|
105
|
+
|
|
106
|
+
## State files
|
|
107
|
+
|
|
108
|
+
- `~/.tunnelbox/remote-state.hermes.json` — agentID / relay / bound state / language
|
|
109
|
+
- `~/.tunnelbox/hermes-sessions/` — local session mirrors
|
|
110
|
+
- `~/.tunnelbox/remote-pairing.hermes.txt` + `remote-pairing.json` — latest pairing info
|
|
111
|
+
- `~/.tunnelbox/tunnelbox.log` — adapter log
|
|
112
|
+
|
|
113
|
+
## Uninstall
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
npm uninstall -g @tunnelbox/hermes
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Remove `~/.tunnelbox` (all adapters' shared state) only if you no longer use any tunnelbox adapter.
|
|
120
|
+
|
|
121
|
+
## Development
|
|
122
|
+
|
|
123
|
+
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,121 @@
|
|
|
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（headless oneshot），只向中继发出站连接（无需公网 IP / 端口映射）。
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
手机 App ──WSS──► relay ──WSS──► tunnelbox-hermes（本适配器）
|
|
11
|
+
└─ hermes chat [--resume <id>] -Q -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 -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
|
+
> 本包的 headless 桥（spawn-per-message）为**整段 fallback** 路径；需要**实时**远程控制（逐 token 流式 / 双向消息 / 手机审批 / 选择）请安装官方 **Native 插件**（`native-plugin/`，进程内，需本机运行 Hermes CLI/Gateway）。headless 本身不提供手机审批。
|
|
52
|
+
|
|
53
|
+
## 配置
|
|
54
|
+
|
|
55
|
+
| 环境变量 | 默认 | 说明 |
|
|
56
|
+
|---|---|---|
|
|
57
|
+
| `TUNNELBOX_RELAY_URL` | state 保存的地址 | 中继地址 |
|
|
58
|
+
| `TUNNELBOX_CWD` | `process.cwd()` | 默认工作区 |
|
|
59
|
+
| `TUNNELBOX_HERMES_MODEL` | hermes 默认 | `--model` |
|
|
60
|
+
| `TUNNELBOX_HERMES_PROVIDER` | hermes 默认 | `--provider`（如 nous/openrouter） |
|
|
61
|
+
| `TUNNELBOX_HERMES_TOOLSETS` | hermes 默认 | `--toolsets`（逗号分隔） |
|
|
62
|
+
| `TUNNELBOX_HERMES_VERBOSE` | 关 | `--verbose` |
|
|
63
|
+
| `TUNNELBOX_HERMES_BIN` | `hermes` | hermes 可执行名/绝对路径（可带前置参数，如 `node /path/fake`） |
|
|
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 | ✅ | `chat -Q -q` 整段一次性输出 → 回合级 `text`+`complete` 回传 |
|
|
74
|
+
| thinking | ❌ | oneshot 无结构化推理部件 |
|
|
75
|
+
| permission | ❌ | headless 无官方审批通道 → Hermes 自身策略/沙箱 fail-closed 兜底（手机审批见 `native-plugin/`） |
|
|
76
|
+
| commands | ✅ | `/new`、`/help` |
|
|
77
|
+
| abort | ✅ | kill 子进程（SIGTERM → SIGKILL） |
|
|
78
|
+
|
|
79
|
+
## 会话模型
|
|
80
|
+
|
|
81
|
+
- 会话 = 本地镜像（`~/.tunnelbox/hermes-sessions/<uuid>/`）：每条消息即时落盘，供列表/历史/删除。
|
|
82
|
+
- 续聊：首轮后经 `hermes sessions list --workspace <目录>` 发现 Hermes 真实会话 id 存镜像，后续每轮 `chat --resume <id> -Q -q`（Hermes 官方持久化保证多轮上下文）。已在 Hermes v0.21.1 真机验证（`hermes -z` 不续聊、自定义 id 无效）。
|
|
83
|
+
- 状态文件：`~/.tunnelbox/remote-state.hermes.json`。
|
|
84
|
+
|
|
85
|
+
## 安全说明
|
|
86
|
+
|
|
87
|
+
- 工具执行/命令授权由 Hermes 自身策略管理（危险命令 fail-closed）；本适配器不自动放行，也不改写用户 `~/.hermes/config.yaml`。
|
|
88
|
+
- 请勿在不受信目录运行不受限工具集，也别把敏感工程目录暴露给不受信手机。
|
|
89
|
+
|
|
90
|
+
## 多语言
|
|
91
|
+
|
|
92
|
+
用户可见输出支持 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`。
|
|
93
|
+
|
|
94
|
+
## 故障排查
|
|
95
|
+
|
|
96
|
+
| 问题 | 解决 |
|
|
97
|
+
|---|---|
|
|
98
|
+
| 终端没有二维码/配对码 | 运行 `tunnelbox-hermes --pair` 打印新码 |
|
|
99
|
+
| 需要换手机配对 | 在 App 设置里解绑，再带 `--pair` 运行 |
|
|
100
|
+
| 已绑定但手机连不上 | 确认两端同一中继；查看 `~/.tunnelbox/tunnelbox.log` |
|
|
101
|
+
| 使用自建中继 | 启动时带 `TUNNELBOX_RELAY_URL=wss://<你的中继>` |
|
|
102
|
+
| Hermes 应答异常/行为不符 | 在装有 hermes 的机器运行 `npm run probe`，输出结构化诊断回传维护者 |
|
|
103
|
+
|
|
104
|
+
## 状态文件
|
|
105
|
+
|
|
106
|
+
- `~/.tunnelbox/remote-state.hermes.json` — agentID / 中继地址 / 绑定状态 / 语言
|
|
107
|
+
- `~/.tunnelbox/hermes-sessions/` — 本地会话镜像
|
|
108
|
+
- `~/.tunnelbox/remote-pairing.hermes.txt` + `remote-pairing.json` — 最新配对信息
|
|
109
|
+
- `~/.tunnelbox/tunnelbox.log` — 适配器日志
|
|
110
|
+
|
|
111
|
+
## 卸载
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
npm uninstall -g @tunnelbox/hermes
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
仅当不再使用任何 tunnelbox 适配器时，才删除 `~/.tunnelbox`（各适配器共享状态）。
|
|
118
|
+
|
|
119
|
+
## 开发
|
|
120
|
+
|
|
121
|
+
实现细节（协议映射、源码结构、决策记录、待实测项）保存在源码仓库中本包旁的 `DEV.md` 与仓库 `docs/` 下。
|