agentus 0.3.3 → 0.3.5

package/docs/installation.zh-CN.md

@@ -28,6 +28,57 @@ nvm install 22 && nvm use 22      # 或者
 brew install node                 # 或者 https://nodejs.org/en/download
 ```
 
+### 该跑哪份 Hermes
+
+裸装的 Hermes 足够跑会话。但驾驶舱自己依赖的那几项能力**不在发布版里** —— 按会话切换的**思考深度**
+（ACP `reasoning_effort`）、**跨重启 / `session/load` 存活的权限模式**，以及可自由填写的**上下文预算**
+（带 256K/512K/768K/1M 预设）。它们在 fork
+[`LiangYang666/hermes-agent`](https://github.com/LiangYang666/hermes-agent) 的 ACP 分支上，
+按基座版本各有一个**集成构建的 tag**，自成命名空间：
+
+```
+agentus/<hermes 内部版本>/merge-<YYYYMMDD-HHMM>
+```
+
+用 tag 而不是分支是刻意的：同名分支（在 `yl-dev/` 下）是工作面、会被重建，而 tag 永不移动 —— 所以钉
+tag。`agentus/` 这个前缀也把它和上游自己的 tag（`v0.21.7`、`v0.21.7+canary.*`）分开；最后一段是时间戳，
+可排序，所以「最新」就是一次 `sort -V`。
+
+先正常装好 Hermes（它的安装器会带上 Python/Node 运行时，并把 `hermes` 放进 PATH），再把那份构建
+套在那个运行时上跑：
+
+```bash
+# 1. Hermes 本体：槽位要用的运行时
+curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
+
+# 2. 最新的集成构建，按 tag 取（写全 refs/tags/：永不歧义）
+TAG=$(git ls-remote --tags --refs https://github.com/LiangYang666/hermes-agent.git \
+      'refs/tags/agentus/*' | awk '{print $2}' | sed 's#refs/tags/##' | sort -V | tail -1)
+git clone --depth=1 --branch "$TAG" https://github.com/LiangYang666/hermes-agent.git ~/Project/hermes-agent
+
+# 3. 包一层，让驾驶舱指向这个 wrapper
+mkdir -p ~/.local/bin
+cat > ~/.local/bin/hermes-acp-src <<'WRAP'
+#!/bin/sh
+exec env PYTHONPATH="$HOME/Project/hermes-agent" hermes "$@"
+WRAP
+chmod +x ~/.local/bin/hermes-acp-src
+AGENTUS_HERMES_CMD=~/.local/bin/hermes-acp-src npm start
+```
+
+`PYTHONPATH` 的作用是让这份 checkout **盖在**已安装的包前面，而解释器和依赖仍由装好的运行时提供 ——
+所以第 1 步不能省。验证槽位实际会跑什么（就是 Agentus 缺后端时提示的那条自检）：
+
+```bash
+PYTHONPATH=~/Project/hermes-agent hermes acp --check     # → Hermes ACP check OK
+```
+
+装成服务时，把 `AGENTUS_HERMES_CMD` 放进你交给服务端的环境里 —— 见「作为服务常驻」。保持默认
+（`hermes`）就是一份纯安装，所以 fork 是升级项、不是必须项。
+
+换到更新的构建只是在那棵树里 fetch + checkout（`git fetch --depth=1 origin tag <tag> && git checkout <tag>`），
+不用重装；正在跑的槽位会在下次重启时用上。
+
 ## 安装
 
 ### 一条命令 —— 用 npm 上发布的包（对外）
@@ -89,7 +140,7 @@ npm run agentus                     # 与 `npx agentus` 同一个 CLI，直接
 agentus [options]
 
   -p, --port <n>     监听端口                        (AGENTUS_PORT，默认 8788)
-  -d, --data <dir>   状态目录（sqlite、登录、TLS 材料、设置）
+  -d, --data <dir>   状态目录（sqlite、登录、设置）
                                                        (AGENTUS_DATA，默认 ~/.agentus)
   -o, --open         就绪后自动在浏览器打开驾驶舱
       --where        打印解析出的路径后退出（不启动任何东西）
@@ -97,8 +148,8 @@ agentus [options]
   -v, --version      打印版本
 ```
 
-`--where` 值得记住：它会打印服务端**实际**解析出的路径 —— 数据目录、前端产物、随附 APK、TLS
-监听、Node 版本 —— 然后退出，什么都不启动。它是「我的数据去哪了」的唯一权威答案（见下文）。
+`--where` 值得记住：它会打印服务端**实际**解析出的路径 —— 数据目录、前端产物、随附 APK、
+Node 版本 —— 然后退出，什么都不启动。它是「我的数据去哪了」的唯一权威答案（见下文）。
 
 ## 首次运行
 
@@ -132,9 +183,6 @@ agentus [options]
 | `AGENTUS_HERMES_HOME` | `~/.hermes` | 未在行里指定 home 时的默认 `HERMES_HOME` |
 | `AGENTUS_PERM_TIMEOUT_MS` | `300000`（5 分钟） | 权限提示自动取消前的等待时间 |
 | `AGENTUS_HISTORY_PAGE` | `500` | 对话记录分页大小 |
-| `AGENTUS_TLS_PORT` | 有证书时 `8443`，否则关闭 | TLS 监听端口（`0` = 关闭） |
-| `AGENTUS_TLS_CERT` / `AGENTUS_TLS_KEY` | `<DATA_DIR>/tls/{cert,key}.pem` | 该监听用的证书材料 |
-| `AGENTUS_TLS_CA` | `<DATA_DIR>/tls/ca.pem` | 设备只需装一次的根证书 |
 | `AGENTUS_TTS_BASE_URL` | 未设置 | 服务端语音合成的 OpenAI 兼容 base（`…/v1`）；不设 = 只用浏览器语音 |
 | `AGENTUS_TTS_API_KEY` / `AGENTUS_TTS_MODEL` / `AGENTUS_TTS_VOICE` | – / `tts-1` / `alloy` | 同上 |
 | `AGENTUS_STT_BASE_URL` | 未设置 | 服务端语音识别的 OpenAI 兼容 base；不设 = 只用浏览器识别 |
@@ -161,7 +209,7 @@ agentus [options]
 ### 数据目录
 
 默认 `~/.agentus`。里面有 `agentus.sqlite`（会话 + 记录）、`credentials.json`、`auth.token`、
-`auth.secret`、`tls/`、`settings.json`。首次启动时以 `0700` 创建，启动日志会打印它**以及为什么是
+`auth.secret`、`settings.json`。首次启动时以 `0700` 创建，启动日志会打印它**以及为什么是
 这个目录胜出**：
 
 | 顺序 | 规则 |
@@ -175,14 +223,13 @@ agentus [options]
 会打印服务端解析的结果，不用靠猜。
 
 任何东西都不会写进 `node_modules`：对已安装的包来说，`<pkg>/packages/server/.data` 会被下一次
-`npm i -g agentus` 删掉，连带记录、登录和 TLS 密钥一起没了。
+`npm i -g agentus` 删掉，连带记录和登录一起没了。
 
 ### 端口
 
 | 端口 | 协议 | 用途 |
 |---|---|---|
-| `AGENTUS_PORT`（8788） | 纯 HTTP | 局域网、本机回环、`curl`、脚本 —— 无证书警告，CI 不变 |
-| `AGENTUS_TLS_PORT`（8443） | HTTPS（自签） | **隧道** —— 加密公网那一跳 |
+| `AGENTUS_PORT`（8788） | 纯 HTTP | 局域网、本机回环、`curl`、脚本 —— 无证书警告，CI 不变；**唯一的监听** |
 | 5173 | Vite 开发服务器 | 前端热更新，仅在 `npm run dev` 期间 |
 
 两个监听的 handler、路由、鉴权完全相同，只有 socket 不同。
@@ -202,24 +249,15 @@ agentus [options]
 
 ### TLS
 
-纯 TCP 隧道（SakuraFrp、`ssh -L`、多数 frp 配置）只是转发字节 —— 它**不会**替你终结 TLS。所以
-服务端自己会讲 TLS，落在**第二个**监听上：
-
-```bash
-scripts/make-cert.sh                    # 自签根证书 + 短期叶证书，SAN = 你实际输入的名字
-# -> $AGENTUS_DATA/tls/{ca.pem,cert.pem,key.pem}   （key 0600，已被 git 忽略）
-# 启动日志会写：https://0.0.0.0:8443 (self-signed …) ; 把隧道指向这个端口
-```
+纯 TCP 隧道（SakuraFrp、`ssh -L`、多数 frp 配置）只是转发字节 —— 它**不会**替你终结 TLS。所以要
+在服务端**前面**终结 TLS：放一层反代（Caddy / nginx），或者用自带 `public_tls` 的隧道。
 
-该监听还会在 `/cert.crt` 上提供自己的签发证书，设备只需装一次根证书：
-`https://<你的名字>:<tls-port>/cert.crt`。iOS 会直接打开描述文件安装器；Android 会下载它
-（设置 → 安全 → CA 证书）；iOS 还需要再到 *关于本机 → 证书信任设置 → 启用*。这是公开材料 ——
-私钥永远不会离开 `<DATA_DIR>/tls/`。
+本进程自己只讲纯 HTTP，刻意如此：LAN 这条路不需要证书，`curl`/脚本保持不变；证书的生命周期（签发、
+轮换、SAN）留在前置层里，而不是塞进应用。
 
-`make-cert.sh` 有意签**两**张证书：一张 10 年的根（`ca.pem`，设备装它）和一张 390 天的叶
-（`cert.pem`，监听提供它）。Apple 把服务器证书有效期卡在 398 天，所以一张 10 年的叶证书正是
-iOS 在用户走完安装流程**之后**才拒绝的东西。叶证书可以随意轮换（`--leaf-only`），已装根证书的
-设备不受影响。
+走 TLS 到达的请求，session cookie 照样是 `Secure`：handler 读 `X-Forwarded-Proto`
+（`packages/server/src/auth.ts`），凡设置了这个头的前置层（Caddy 和 nginx 默认都设）都会拿到
+`Secure` cookie，本地无需任何配置。
 
 ### 后端
 
@@ -314,7 +352,7 @@ npm i -g agentus@latest            # 或者：npx agentus@latest … 跑一次
 
 ```bash
 npm rm -g agentus                  # 删程序（状态保留）
-rm -rf ~/.agentus                  # 删状态 —— SQLite、登录、TLS 密钥、设置
+rm -rf ~/.agentus                  # 删状态 —— SQLite、登录、设置
 ```
 
 装到用户级前缀的话用 `npm rm -g --prefix ~/.local agentus`。卸载**不会**碰 `~/.hermes`（你 agent
@@ -346,5 +384,6 @@ rm -rf ~/.agentus                  # 删状态 —— SQLite、登录、TLS 密
 **页面能打开但一直显示「reconnecting」。** 某条隧道丢掉了 WebSocket 的 `Upgrade`。实时流走
 `/ws`；请换成能透传 WebSocket 的隧道（SakuraFrp 的 TCP+auto-HTTPS 隧道已验证可用）。
 
-**局域网里出现证书警告。** 那是 TLS 监听的自签证书（裸局域网 IP 无法承载可信证书）。要么在
-局域网里用纯 HTTP 的 `:8788` 端口，要么从 `/cert.crt` 装一次签发证书（见 [TLS](#tls)）。
+**局域网里出现证书警告。** 服务端自己只讲纯 HTTP（`:8788`），所以出现警告说明你是用 IP 直接
+访问了终结 TLS 的那层前置（它的证书签的是域名，不是 IP）。要么用纯 HTTP 的 `:8788`，要么用证书
+签发的那个名字去访问前置层。

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "agentus",
- "version": "0.3.3",
+ "version": "0.3.5",
  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
  "license": "Apache-2.0",
  "repository": {
@@ -23,7 +23,6 @@
   "packages/shared/src/",
   "packages/shared/package.json",
   "packages/web/dist/",
-  "scripts/make-cert.sh",
   "docs/",
   "NOTICE"
  ],
@@ -53,18 +52,24 @@
   "workspace-smoke": "node scripts/workspace-smoke.mjs",
   "voice-smoke": "node scripts/voice-smoke.mjs",
   "sentence-units": "tsx scripts/qa/sentence-units.mts",
+  "token-format": "tsx scripts/qa/token-format.mts",
+  "terminal-palette": "tsx scripts/qa/terminal-palette.mts",
+  "android-trust-merge": "node scripts/qa/android-trust-merge.mjs",
+  "plan-hint-sweep": "node scripts/qa/plan-hint-sweep.mjs",
   "plan-service-sweep": "node scripts/qa/plan-service-sweep.mjs",
   "plan-mcp-sweep": "node scripts/qa/plan-mcp-sweep.mjs",
   "plan-v2-sweep": "tsx scripts/qa/plan-v2-sweep.mts",
-  "tls-smoke": "node scripts/tls-smoke.mjs",
   "notify-testbed": "tsx scripts/notify-testbed.mts",
   "notify-smoke": "tsx scripts/notify-smoke.mts",
+  "web-notify-rules": "tsx scripts/qa/web-notify-rules.mts",
+  "web-notify-sweep": "node scripts/qa/web-notify-sweep.mjs",
   "apk": "bash scripts/build-apk.sh",
   "transcript-fold": "tsx scripts/qa/transcript-fold.mts",
   "store-fold": "tsx scripts/qa/store-fold.mts",
   "live-stream": "tsx scripts/qa/live-stream.mts",
   "open-target": "tsx scripts/qa/open-target.mts",
   "rail-recent": "tsx scripts/qa/rail-recent.mts",
+  "permission-echo": "node scripts/qa/permission-echo.mjs",
   "turn-pulse": "tsx scripts/qa/turn-pulse.mts",
   "resume-tail": "tsx scripts/qa/resume-tail.mts",
   "render-lag-sweep": "node scripts/qa/render-lag-sweep.mjs",

package/packages/server/mock/agent.mjs

@@ -5,6 +5,8 @@
 //
 // Env switches to simulate edge cases (append `=N` to env vars when spawning):
 //   MOCK_TOOL=1        -> prompt triggers a tool_call + requestPermission
+//   MOCK_TOOL2=1       -> TWO tool_calls + requestPermissions in one turn (a session holding more
+//                         than one pending request; `[tool2]` in the prompt does the same)
 //   MOCK_THINK=1       -> emits agent_thought_chunk before the answer
 //   MOCK_SLOW_MS=n     -> delay between chunks (default 60)
 //   MOCK_SPAWN_MS=n    -> boot latency before the handshake answers (default 0). A real agent takes
@@ -506,6 +508,42 @@ const agent = () => ({
       }
     }
 
+    // `[tool2]` — TWO approvals from one turn, raised together (the shape an agent produces when it
+    // edits two files in parallel), with no diff payload so the two cards differ only by file name.
+    // This is the fixture for the state that has no other name: a session can hold more than one
+    // pending request, while the dialog draws only `perms[0]` — so answering the first swaps in the
+    // second, drawn identically, and the operator reads 「我点了允许，它还在那儿」 (measured
+    // 2026-10-11). QA only: scripts/qa/permission-echo.mjs.
+    if (process.env.MOCK_TOOL2 === "1" || /\btool2\b/.test(text)) {
+      const mode2 = s.currentModeId || "default";
+      if (mode2 !== "dont_ask" && mode2 !== "accept_edits") {
+        await Promise.all(["./two-a.txt", "./two-b.txt"].map(async (name, i) => {
+          const toolCallId = `tc-${sessionId}-pair-${i}`;
+          await send(agent._conn, sessionId, {
+            sessionUpdate: "tool_call", toolCallId,
+            title: `Write file: ${name}`, kind: "edit", status: "pending",
+            rawInput: { path: name, content: `hello from the mock agent (${i + 1})` },
+          });
+          const resp = await agent._conn.requestPermission({
+            sessionId,
+            toolCall: { toolCallId, title: `Write file: ${name}`, kind: "edit" },
+            options: [
+              { optionId: "allow", name: "Allow", kind: "allow_once" },
+              { optionId: "reject", name: "Reject", kind: "reject_once" },
+            ],
+          });
+          const pick = resp?.outcome?.optionId;
+          await send(agent._conn, sessionId, {
+            sessionUpdate: "tool_call_update", toolCallId,
+            status: pick === "reject" ? "failed" : "completed",
+            rawOutput: pick === "reject"
+              ? `rejected by the operator — nothing written (chosen option: ${pick})`
+              : `wrote ${name} (chosen option: ${pick})`,
+          });
+        }));
+      }
+    }
+
     if (wantTool) {
       const toolCallId = `tc-${sessionId}-${Date.now()}`;
       const edit = wantHermes ? MOCK_HERMES_EDIT : MOCK_EDIT;

package/packages/server/src/acp/registry.ts

@@ -204,7 +204,17 @@ export interface BackendHandshake {
   /** agentCapabilities.sessionCapabilities.fork */
   fork: boolean | null;
   modes: { currentModeId: string | null; available: string[]; names?: Record<string, string> } | null;
-  configOptions: { id: string; name: string | null; currentValue: string | null }[];
+  /** The ACP `select`s, kept WHOLE rather than reduced to id/name/currentValue: the new-session
+   *  start page has no session to read configOptions from, so the controls it draws come from
+   *  here — and a control without its `options` is a button that cannot be turned. */
+  configOptions: {
+    id: string;
+    name: string | null;
+    currentValue: string | null;
+    type?: string | null;
+    category?: string | null;
+    options?: { value: string; name: string | null; description?: string | null }[] | null;
+  }[];
   models: { currentModelId: string | null; available: string[] } | null;
   /** slash commands the agent announced (session/update or newSession) */
   commands: string[];
@@ -621,6 +631,23 @@ export function handshakeFrom(
       id: o.id,
       name: o.name ?? null,
       currentValue: o.currentValue === undefined || o.currentValue === null ? null : String(o.currentValue),
+      // Passed through defensively like everything else here: the SDK types cover only part of what
+      // the wire carries, and a session's real control set differs per agent.
+      type: typeof (o as { type?: unknown }).type === "string" ? String((o as { type?: string }).type) : null,
+      category:
+        typeof (o as { category?: unknown }).category === "string"
+          ? String((o as { category?: string }).category)
+          : null,
+      options: Array.isArray((o as { options?: unknown }).options)
+        ? ((o as unknown as { options: { value?: unknown; name?: unknown; description?: unknown }[] }).options ?? []).map(
+            (opt) => ({
+              value: String(opt.value ?? ""),
+              name: opt.name === undefined || opt.name === null ? null : String(opt.name),
+              description:
+                opt.description === undefined || opt.description === null ? null : String(opt.description),
+            }),
+          )
+        : null,
     })),
     models,
     commands: (s.availableCommands ?? []).map((c) => c.name),