comate-cli 0.12.4b2__tar.gz → 0.12.4b3__tar.gz

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/CHANGELOG.md

@@ -71,6 +71,10 @@
   标签不再展示 `uv tool install …` 长串（与 Windows 对齐），措辞改为「退出后运行」；
   更新失败的兜底文案仍保留完整 uv 修复命令。源码 editable 安装下自更新必然被拒，
   启动检测与第二次启动弹窗两个入口现在直接静音；PATH 缺 uv 不静音。
+- compact 期间底部 loading 文案由 `Compacting context...`（三个半角点）改为
+  `Compacting context…`（单个省略号字符）：与 `Running…` 等其它进行时状态词、
+  以及设计稿 docs/superpowers/specs/2026-05-18-auto-compact-awareness-design.md
+  已写的写法对齐，少占两列宽。
 
 ### Fixed
 

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: comate-cli
-Version: 0.12.4b2
+Version: 0.12.4b3
 Summary: Comate terminal CLI built on comate-agent-sdk
 Project-URL: Homepage, https://github.com/AndyLee1024/agent-sdk
 Project-URL: Repository, https://github.com/AndyLee1024/agent-sdk
@@ -16,7 +16,7 @@ Classifier: Programming Language :: Python :: 3.13
 Requires-Python: <3.14,>=3.11
 Requires-Dist: charset-normalizer==3.4.7
 Requires-Dist: comate-agent-sdk<0.13,>=0.12.10
-Requires-Dist: comate-rpc<0.2,>=0.1.2
+Requires-Dist: comate-rpc<0.2,>=0.1.3
 Requires-Dist: concurrent-log-handler>=0.9.25
 Requires-Dist: curl-cffi==0.13.0
 Requires-Dist: httpx<0.29.0,>=0.28.1

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/comate_cli/main.py

@@ -59,9 +59,9 @@ PRINT_OUTPUT_FORMAT_UNSUPPORTED = frozenset({"stream-json"})
 
 # (rpc_stdio, resume_session_id, resume_select, print_prompt, output_format, rpc_relay,
 #  add_dirs, rpc_ws_port, yolo)；rpc_ws_port 为 None 表示不是 --rpc-ws，0 表示由系统挑空闲端口；
-# rpc_relay 为 None 表示不是 --rpc-relay，否则是（中转地址, Agent 令牌）。
+# rpc_relay 为 None 表示不是 --rpc-relay，否则是（中转地址, Agent 令牌, 是否允许远程切到 bypassPermissions）。
 ParsedArgs = tuple[
-    bool, str | None, bool, str | None, str, tuple[str, str] | None, tuple[str, ...], int | None, bool
+    bool, str | None, bool, str | None, str, tuple[str, str, bool] | None, tuple[str, ...], int | None, bool
 ]
 # --rpc-relay 的 Agent 令牌优先从这里取（不进进程列表和 shell 历史）。
 AGENT_TOKEN_ENV = "COMATE_AGENT_TOKEN"
@@ -274,7 +274,7 @@ def _usage_text(command_name: str = "comate") -> str:
         f"  {command_name} [--rpc-stdio] [--add-dir <path>]...\n"
         f"  {command_name} --rpc-ws [--port <n>] [--add-dir <path>]...\n"
         f"  {command_name} --rpc-relay --relay-url <ws(s)://...> [--agent-token <token>]"
-        " [--add-dir <path>]...\n"
+        " [--allow-bypass] [--add-dir <path>]...\n"
         f"  {command_name} -p [--output-format text|json] <prompt>\n"
         f"  {command_name} resume [<session_id>]\n"
         f"  {command_name} mcp <subcommand> [options]\n"
@@ -301,6 +301,8 @@ def _usage_text(command_name: str = "comate") -> str:
         "  --relay-url <url>  (--rpc-relay) Relay address, ws:// or wss://\n"
         "  --agent-token <t>  (--rpc-relay) Agent token; the COMATE_AGENT_TOKEN environment\n"
         "                     variable takes precedence and is recommended\n"
+        "  --allow-bypass     (--rpc-relay) Let remote terminals switch sessions to\n"
+        "                     bypassPermissions; refused by default\n"
         "  --yolo             Start in bypassPermissions (YOLO) mode\n"
         "  --version, -V      Print version and exit\n"
         "  --pre              (update) Also consider pre-release versions"
@@ -347,6 +349,8 @@ def _parse_args(argv: list[str]) -> ParsedArgs:
     port_arg: str | None = None
     relay_url_arg: str | None = None
     agent_token_arg: str | None = None
+    # 故意没有对应的环境变量：放开远程免审批，必须在启动命令里明着写。
+    allow_bypass = False
     print_mode = False
     output_format = PRINT_OUTPUT_FORMAT_TEXT
     output_format_explicit = False
@@ -380,6 +384,10 @@ def _parse_args(argv: list[str]) -> ParsedArgs:
                 agent_token_arg = value
             index += 1
             continue
+        if arg == "--allow-bypass":
+            allow_bypass = True
+            index += 1
+            continue
         if arg == "--port" or arg.startswith("--port="):
             if arg == "--port":
                 index += 1
@@ -439,12 +447,18 @@ def _parse_args(argv: list[str]) -> ParsedArgs:
 
         raise _ArgumentError(i18n(message.rpc_mode_conflict))
     if not rpc_relay_flag:
-        for option, value in (("--relay-url", relay_url_arg), ("--agent-token", agent_token_arg)):
-            if value is not None:
+        for option, given in (
+            ("--relay-url", relay_url_arg is not None),
+            ("--agent-token", agent_token_arg is not None),
+            ("--allow-bypass", allow_bypass),
+        ):
+            if given:
                 from comate_cli.terminal_agent.i18n import i18n, message
 
                 raise _ArgumentError(i18n(message.rpc_relay_option_without_rpc_relay, option=option))
-    rpc_relay = _parse_rpc_relay(relay_url_arg, agent_token_arg) if rpc_relay_flag else None
+    rpc_relay = (
+        (*_parse_rpc_relay(relay_url_arg, agent_token_arg), allow_bypass) if rpc_relay_flag else None
+    )
     if port_arg is not None and not rpc_ws:
         from comate_cli.terminal_agent.i18n import i18n, message
 

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/comate_cli/terminal_agent/app.py

@@ -1176,7 +1176,7 @@ async def run(
     *,
     rpc_stdio: bool = False,
     rpc_ws_port: int | None = None,
-    rpc_relay: tuple[str, str] | None = None,
+    rpc_relay: tuple[str, str, bool] | None = None,
     resume_session_id: str | None = None,
     resume_select: bool = False,
     print_message: str | None = None,
@@ -1367,13 +1367,14 @@ async def run(
         from comate_cli.terminal_agent.backend.client import resolve_distribution_version
 
         RpcRelayServer = _import_rpc_relay_server()
-        relay_url, agent_token = rpc_relay
+        relay_url, agent_token, allow_bypass = rpc_relay
         await RpcRelayServer(
             agent=agent,
             default_cwd=project_root,
             relay_url=relay_url,
             token=agent_token,
             version=resolve_distribution_version(profile.package_name),
+            allow_bypass=allow_bypass,
         ).run()
         return
 

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/comate_cli/terminal_agent/rpc_relay.py

@@ -9,6 +9,7 @@
   - 令牌被拒（关闭码 1008，或握手阶段 HTTP 401 / 403）：从没来过终端 = 不可能有会话，
     往标准错误报一句、非零退出；来过终端 = 可能有会话在跑，打 ERROR、进程留着让它们跑完。
 - 上线、掉线、重拨只进日志；不打就绪行（没有宿主程序读它）。
+- 远程终端默认不能把会话切到 ``bypassPermissions``：主人启动时加 ``--allow-bypass`` 才放开。
 
 websockets 客户端只出现在这个文件里；不走 ``--rpc-relay`` 时整个文件都不 import。
 """
@@ -92,9 +93,20 @@ class RpcRelayServer:
         relay_url: str,
         token: str,
         version: str,
+        allow_bypass: bool = False,
         reconnect_backoff: Sequence[float] = DEFAULT_RECONNECT_BACKOFF_S,
     ) -> None:
-        self._host = SessionHost(agent=agent, default_cwd=default_cwd, commands=CliCommandCatalog())
+        self._host = SessionHost(
+            agent=agent,
+            default_cwd=default_cwd,
+            commands=CliCommandCatalog(),
+            allow_bypass=allow_bypass,
+        )
+        if allow_bypass:
+            logger.warning(
+                "rpc relay: --allow-bypass is set; remote terminals may switch sessions to "
+                "bypassPermissions (tools run without approval)"
+            )
         self._url = relay_url
         self._token = token
         self._meta = HelloMeta(version=version, hostname=socket.gethostname(), cwd=str(default_cwd))

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/comate_cli/terminal_agent/tui_parts/render_panels.py

@@ -1067,7 +1067,7 @@ class RenderPanelsMixin:
 
         if self._renderer.is_auto_compacting() or self._is_compacting:
             return self._append_loading_detail_fragment(
-                self._animated_loading_fragments("Compacting context...")
+                self._animated_loading_fragments("Compacting context…")
             )
 
         if self._animator.is_active:

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/docs/cli-rpc-stdio-guide.md

@@ -1,12 +1,13 @@
 # Comate CLI RPC 接入指南（协议 v4）
 
-`comate --rpc-stdio`、`comate --rpc-ws` 和 `comate --rpc-relay` 把 comate 变成一个可以被别的程序驱动的服务：
-IDE 插件、Tauri 桌面壳、本机网页、经中转的远程网页都能开会话、发消息、看流式输出、回答审批。
+> 本文件与 comate-guide 的 `comate_agent_sdk/bundled_skills/comate-guide/references/rpc.md` 正文逐字相同（两份都是完整版，那份随安装包分发），改一份必须同步另一份。
+> 协议实现在 `packages/comate_rpc`，术语见它的 `CONTEXT.md`；TS 客户端的生成类型、测试、demo 页面见 `packages/comate_rpc/ts/README.md`；中转服务的完整参数见 `packages/comate_relay/README.md`。
 
-- 三种模式都说**协议 v4**（JSON-RPC 2.0）。v3 已删除，v3 客户端会在握手时被拒绝（ADR-0024）。
+`comate --rpc-stdio`、`comate --rpc-ws`、`comate --rpc-relay` 把 comate 变成一个可以被别的程序驱动的服务：开会话、发消息、看流式输出、回答审批。
+
+- 三种模式都说**协议 v4**（JSON-RPC 2.0）。v3 已删除，v3 客户端握手即被拒。
 - 三种模式和终端 TUI 平级：共用同一套 settings / preflight / Agent 组装逻辑，工具集是 comate 全量。
-- 协议实现在 `packages/comate_rpc`，术语见它的 `CONTEXT.md`；TS 客户端库和 demo 页面见 `packages/comate_rpc/ts/README.md`。
-- 字段的精确定义以生成的清单为准：`packages/comate_rpc/ts/src/generated/schema.json`（所有方法、事件、数据结构）。
+- 字段的精确定义以仓库内生成的清单为准：`packages/comate_rpc/ts/src/generated/schema.json`。
 
 ## 启动
 
@@ -14,19 +15,18 @@ IDE 插件、Tauri 桌面壳、本机网页、经中转的远程网页都能开
 | --- | --- | --- |
 | `comate --rpc-stdio` | 标准输入输出 | 一行一条 JSON。只有一个客户端；连接断了进程就结束 |
 | `comate --rpc-ws [--port N]` | 本机 WebSocket | 一个文本帧一条 JSON。可同时连多个客户端；`--port` 不填或填 0 = 系统挑空闲端口 |
-| `comate --rpc-relay --relay-url URL` | 拨出到中转 | Agent 主动连中转，不开任何端口；终端都连中转。见下面「经中转远程接入」 |
+| `comate --rpc-relay --relay-url URL` | 拨出到中转 | Agent 主动连中转，不开任何端口；终端都连中转。见「经中转远程接入」 |
 
-`--rpc-ws` 就绪后往标准输出打**唯一一行** JSON，启动它的宿主程序读这一行拿连接方式：
+`--rpc-ws` 就绪后往标准输出打**唯一一行** JSON，宿主程序读这一行拿连接方式：
 
 ```json
 {"type": "ready", "url": "ws://127.0.0.1:<port>/", "token": "<令牌>"}
 ```
 
 - 只绑定 `127.0.0.1`，没有 `--host`：Agent 永远不监听外网，远程要走中转。
-- 令牌每次启动随机生成。浏览器建 WebSocket 不能加请求头，所以令牌放在**子协议**里：
-  `new WebSocket(url, ["comate-rpc", token])`。令牌不对，握手直接被拒（HTTP 403）。
+- 令牌每次启动随机生成，放在 WebSocket **子协议**里：`new WebSocket(url, ["comate-rpc", token])`。令牌不对，握手被拒（HTTP 403）。
 - 端口被占用：标准错误打一句说明，退出码非 0。
-- 日志写 `~/.comate/logs/agent.log`（和 TUI 同一个文件，级别看 `COMATE_LOG_LEVEL`），不写标准输出，也不写标准错误；标准错误只留给启动失败时那一句报错。三种模式都一样。
+- 日志写 `~/.comate/logs/agent.log`（和 TUI 同一个文件，级别看 `COMATE_LOG_LEVEL`），不写标准输出和标准错误；标准错误只留给启动失败时那一句报错。三种模式都一样。
 
 不支持的启动组合（参数解析阶段直接报错）：
 
@@ -34,48 +34,74 @@ IDE 插件、Tauri 桌面壳、本机网页、经中转的远程网页都能开
 | --- | --- |
 | `--rpc-stdio`、`--rpc-ws`、`--rpc-relay` 给了不止一个 | 只能选一种通道 |
 | `--port` 不配 `--rpc-ws` | 端口只对 WebSocket 有意义 |
-| `--relay-url` / `--agent-token` 不配 `--rpc-relay` | 只对中转有意义 |
+| `--relay-url` / `--agent-token` / `--allow-bypass` 不配 `--rpc-relay` | 只对中转有意义 |
 | `--rpc-relay` 没给 `--relay-url`，或地址不是 `ws://` / `wss://` 开头 | 不知道往哪拨 |
 | `--rpc-relay` 既没有 `COMATE_AGENT_TOKEN` 也没有 `--agent-token` | 没令牌拨出去也会被拒 |
 | `comate resume ... --rpc-*` | 恢复会话走 `session.open` 的 `session_id` |
 | `--rpc-* --yolo` | 权限模式由每个 `session.open` 的 `permission_mode` 决定 |
 | `-p ... --rpc-*` | print 模式是另一条一次性输出路径 |
 
-preflight 照常执行，但不交互。宿主要提前配好 provider / settings；preflight 不通过时进程在进入 RPC 服务前退出。
+preflight 照常执行但不交互：宿主要提前配好 provider / settings，preflight 不通过时进程在进入 RPC 服务前退出。
 
 ## 经中转远程接入（`--rpc-relay`）
 
-适用场景：Agent 跑在 sandbox（容器、远程机器）里，那里**只许出、不许进**；桌面和手机都在别处。
-Agent 主动拨出到中转服务 `comate_relay`，终端也连中转，中转按「哪个 Agent、哪条连接」原样转发（ADR-0026）。
+适用场景：Agent 跑在 sandbox（容器、远程机器）里，那里**只许出、不许进**；桌面和手机在别处。Agent 主动拨出到中转服务 `comate-relay`，终端也连中转，中转按「哪个 Agent、哪条连接」原样转发。
 
 ```bash
 COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.example.com/ws/agent-link
 ```
 
-- **令牌**：由中转管理员用 `comate-relay agent add` 创建，只在创建时显示一次。
+- **令牌**：中转管理员用 `comate-relay agent add` 创建，只在创建时显示一次。
   - 推荐用环境变量 `COMATE_AGENT_TOKEN` 传：不会出现在进程列表和 shell 历史里。
   - 也可以用 `--agent-token <令牌>`。两者都给时**以环境变量为准**。
-  - 拨出时令牌放在子协议里（`["comate-rpc", 令牌]`），和本机 WebSocket 同一个办法。
 - **上线**：连上后第一帧自报 `hello`（comate 版本、主机名、工作目录），只用于在中转上显示，不参与鉴权。
 - **Agent 端不开端口、不碰证书**。`wss://` 的证书由中转那边负责。
-- **不打就绪行**：标准输出上什么都没有。上线、掉线、重连都记在日志文件 `~/.comate/logs/agent.log` 里。
-- **终端看到的协议和本机完全一样**：握手、开会话、订阅、审批、断线续传都照旧，只是连接地址换成中转的。
+- **不打就绪行**：标准输出什么都没有。上线、掉线、重连都只进日志。
+- **终端看到的协议和本机完全一样**，唯一区别是下面的免审批限制。
+
+**远程默认不能免审批**：`bypassPermissions`（工具不经审批直接执行）默认不许远程终端打开。
+
+- 被拒的调用：`session.open` 带 `permission_mode: "bypassPermissions"`（开新会话或恢复旧会话），以及 `session.setPermissionMode` 切到 `bypassPermissions`。
+- 被拒时回 -32602，`error.data.kind = "permission_mode_not_allowed"`，会话的权限模式不变。
+- 用 `session_id` 接入已经活着的会话不检查：接入时 `permission_mode` 本来就不生效。
+- Agent 主人启动时加 `--allow-bypass` 才放开，同时日志记一条 WARNING。这个开关**故意没有环境变量**，必须在启动命令里明着写。
+- `--rpc-stdio` / `--rpc-ws` 只有本机能连，不受这条限制。
 
 断线与重连：
 
 | 情况 | Agent 怎么做 |
 | --- | --- |
 | 网络断了、中转重启、中转暂时连不上 | 等 1、2、5、10、30 秒依次重拨，之后每 30 秒一次。**重拨期间会话照跑**，终端重新接入后带（纪元号, 序号）续传 |
-| 被同一令牌的新 Agent 顶替（关闭码 4009） | 不再重拨，只打日志。进程不退出，会话照跑，否则两个实例会互踢个没完 |
-| 令牌被拒（关闭码 1008，或握手被拒 HTTP 401 / 403），且**从没有终端连进来过** | 标准错误打一句说明，退出码 1。这时不可能有会话，留着没有意义 |
+| 被同一令牌的新 Agent 顶替（关闭码 4009） | 不再重拨，只打日志。进程不退出、会话照跑，否则两个实例会互踢个没完 |
+| 令牌被拒（关闭码 1008，或握手 HTTP 401 / 403），且**从没有终端连进来过** | 标准错误打一句说明，退出码 1 |
 | 令牌被拒，但之前**有终端连进来过** | 不再重拨，打 ERROR 日志。进程不退出，让可能还在跑的会话跑完；Ctrl+C 结束 |
 
-- 中转掉线期间空闲计时**照常**：没有终端连着、又不在跑回合的会话，30 分钟后照样关掉（历史在磁盘上，重开即可）。
+中转掉线期间空闲计时照常：没有终端连着、又不在跑回合的会话，30 分钟后照样关掉（历史在磁盘上，重开即可）。
+
+### 部署中转服务 `comate-relay`
+
+```bash
+comate-relay user add alice                     # 建账号，交互式输两次密码；脚本里用 --password-stdin
+comate-relay agent add --user alice --name box  # 打印 agent_id 和 Agent 令牌，令牌只显示这一次
+comate-relay serve                              # 默认只听 127.0.0.1:8765；浏览器打开就是 demo 页
+```
+
+- 其他子命令：`user remove` / `user list` / `user revoke`（撤销该账号全部登录令牌）、`agent remove` / `agent list`（永不显示令牌）。
+- 监听非本机地址必须给 `--certfile` / `--keyfile`（跑 HTTPS / WSS），或显式加 `--allow-insecure-http`（仅限可信局域网），否则拒绝启动。
+- Agent 拨入地址是 `/ws/agent-link`；终端的控制连接 `/ws/control`、连某个 Agent 用 `/ws/agents/{agent_id}`；登录 `POST /api/auth/login`。令牌一律放子协议 `["comate-rpc", 令牌]`。
+
+中转发给终端和 Agent 的关闭码：
+
+| 关闭码 | 含义 | 该怎么做 |
+| --- | --- | --- |
+| 1008 | 令牌错误 / 过期 / 被撤销 | 终端回登录页；Agent 停止重拨 |
+| 4003 | 这个 Agent 不属于你 | 终端不重连 |
+| 4004 | Agent 离线 | 终端退避重连，Agent 回来后自动接上 |
+| 4009 | 被同令牌的新连接顶替（发给旧 Agent） | Agent 停止重拨 |
 
 ## 协议骨架
 
-**只有客户端发请求，服务端只发通知。** 服务端不会反过来向客户端发请求——
-审批和提问是会话状态，客户端用普通方法回答（见「审批和提问」）。
+**只有客户端发请求，服务端只发通知。** 服务端不会反过来向客户端发请求；审批和提问是会话状态，客户端用普通方法回答。
 
 | 方法 | 方向 | 作用 |
 | --- | --- | --- |
@@ -87,8 +113,6 @@ COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.exa
 | `$/event` | 服务端 → 客户端（通知） | `{"subscription", "epoch", "seq", "event"}`，`event.type` 区分事件种类 |
 
 - 方法名是 `服务名.方法名`，参数和返回值字段都是 snake_case。
-- 协议版本不是 4：握手失败，`error.data = {"kind": "unsupported_protocol_version", "supported": [4]}`。
-- 握手前调别的方法：-32000，`data.kind = "not_initialized"`。
 
 最小对话（stdio，每行一条）：
 
@@ -114,7 +138,7 @@ COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.exa
 | `session.open` | `cwd?`、`session_id?`、`permission_mode?`（默认 `default`）、`include_partial_messages?` | 开会话。`session_id` 指向进程里**已经活着**的会话时接入它，返回同一个句柄（`attached: true`），其余参数不生效；指向落盘的旧会话时恢复它 |
 | `session.query` | `session_handle`、`prompt` | 发一条消息。自定义斜杠命令（`/名字 参数`）先展开再发；内置命令不能用文本发，要用对应的 `session.*` 方法 |
 | `session.interrupt` | `session_handle` | 中断当前回合。`interrupted` 表示调用时是否真有回合在跑 |
-| `session.setPermissionMode` | `session_handle`、`mode` | `default` / `acceptEdits` / `bypassPermissions` |
+| `session.setPermissionMode` | `session_handle`、`mode` | `default` / `acceptEdits` / `bypassPermissions`。经中转时 `bypassPermissions` 默认被拒 |
 | `session.setModelLevel` | `session_handle`、`level` | `LOW` / `MID` / `HIGH`，只换本会话，不写成用户默认值 |
 | `session.status` | `session_handle` | 会话状态 + 回合状态 + 用量 + 上下文信息 |
 | `session.compact` | `session_handle` | 手动压缩上下文 |
@@ -129,8 +153,7 @@ COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.exa
 
 ## 事件
 
-订阅 `session.events` 后，每条 `$/event` 的 `event.type` 是下面之一。
-这些名字是协议的一部分，和 Python 类名无关。**不认识的 `type` 直接跳过**，以后会加新事件。
+订阅 `session.events` 后，每条 `$/event` 的 `event.type` 是下面之一。这些名字是协议的一部分，和 Python 类名无关。**不认识的 `type` 直接跳过**，以后会加新事件。
 
 | 类别 | `type` |
 | --- | --- |
@@ -138,7 +161,8 @@ COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.exa
 | 回合 | `turn.started`、`turn.stopped`（`reason`：`completed` / `max_iterations` / `waiting_for_input` / `interrupted`） |
 | 输出 | `text`、`thinking`；开了 `include_partial_messages` 才有的增量：`text.delta`、`thinking.delta`、`stream.reset` |
 | 工具 | `tool.call`、`tool.result`；开了 `include_partial_messages` 才有：`tool.started`（模型刚开始写工具调用） |
-| 其他 | `llm.retry`、`usage.delta`、`subagent.*`、`job.*`、`tasks.updated`、`compaction.*`、`queue.changed`、`permissionMode.changed`、`modelLevel.changed` |
+| 子 agent / 后台任务 | `subagent.started`、`subagent.progress`、`subagent.stopped`；`job.started`、`job.progress`、`job.completed` |
+| 其他 | `llm.retry`、`usage.delta`、`tasks.updated`、`compaction.started`、`compaction.finished`、`queue.changed`、`permissionMode.changed`、`modelLevel.changed` |
 | 待处理项 | `interaction.pending`、`interaction.resolved`、`interaction.cancelled` |
 
 ### 断线续传和快照
@@ -148,8 +172,7 @@ COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.exa
 - 重新订阅时带上最后收到的 `epoch` 和 `seq`：
   - 纪元号对得上、缺的事件还在缓冲里 → 从下一条开始补发，不重复不缺。
   - 缺的事件已被挤出缓冲、或纪元号对不上（进程重启过）→ 先发一份 `snapshot`。
-- `snapshot` 包含：会话状态、回合状态（`idle` / `running` / `waiting_for_input`）、**还在等的待处理项**、队列、当前纪元号和序号。
-  重连后凭快照就能恢复界面，包括还没回答的审批。
+- `snapshot` 包含：会话状态、回合状态（`idle` / `running` / `waiting_for_input`）、**还在等的待处理项**、队列、当前纪元号和序号。重连后凭快照就能恢复界面，包括还没回答的审批。
 - 进程重启过的话，旧的 `session_handle` 已经失效：用 `session_id` 重新 `session.open`。
 
 ## 审批和提问
@@ -167,16 +190,12 @@ COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.exa
    | `question` | `{"decision": "answer", "answers": [{"selected_options": [...], "custom_text"?: "..."}]}` 或 `{"decision": "reject"}` |
 
    `deny` 带 `interrupt: true` = 拒绝并结束本回合；不带 = 只拒绝这一个工具。
-3. **第一个有效回答生效**，广播 `interaction.resolved`（带 `resolved_by`：是哪个客户端答的）。
-   之后再答同一项收到 -32002，客户端据此收起弹框。
-4. 回答格式不对（包括拼错或多出字段）→「参数无效」，**不算回答**，这一项继续等。
-   提问的 `answers` 必须和 `content.questions` **一一对应、条数相同**，条数不对同样是「参数无效」
-   （`data.kind: "wrong_answer_count"`）。
+3. **第一个有效回答生效**，广播 `interaction.resolved`（带 `resolved_by`：是哪个客户端答的）。之后再答同一项收到 -32002，客户端据此收起弹框。
+4. 回答格式不对（包括拼错或多出字段）→「参数无效」，**不算回答**，这一项继续等。提问的 `answers` 必须和 `content.questions` **一一对应、条数相同**，否则同样是「参数无效」（`data.kind: "wrong_answer_count"`）。
 
 - 不设超时：一直等到有人答、会话被中断、或会话关闭。
 - 会话被中断：广播 `interaction.cancelled`（`reason: "interrupted"`）。
-- 会话关闭（含空闲关闭、进程退出）：还在等的审批一律**按拒绝处理**，提问按拒绝处理，
-  广播 `interaction.cancelled`（`reason: "session_closed"`）。权限永远不会默认放行。
+- 会话关闭（含空闲关闭、进程退出）：还在等的审批和提问一律**按拒绝处理**，广播 `interaction.cancelled`（`reason: "session_closed"`）。权限永远不会默认放行。
 - 客户端不需要事先声明「能不能弹审批框」。答不了就不答，别的客户端也能答。
 
 ## 错误码
@@ -189,18 +208,32 @@ COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.exa
 | -32002 | 待处理项不存在或已被别人回答 |
 | -32800 | 请求已被 `$/cancelRequest` 取消 |
 
-额外信息统一放在 `error.data`，用 `kind` 区分具体原因，例如 `session_not_found`、`interaction_not_found`、`wrong_response_kind`（回答种类和待处理项对不上）、`not_initialized`。
+额外信息放在 `error.data`，用 `kind` 区分具体原因。客户端按 `kind` 分支，不要按 `message` 文本分支：
+
+| `kind` | 错误码 | 什么时候出现 | `data` 里的其他字段 |
+| --- | --- | --- | --- |
+| `unsupported_protocol_version` | -32602 | 握手时协议版本不是 4 | `supported` |
+| `not_initialized` | -32000 | 握手前调了别的方法 | — |
+| `session_state` | -32000 | 会话当前状态不允许这个操作（例如已关闭、正在清空历史） | — |
+| `session_not_found` | -32001 | `session_handle` 不存在（包括进程重启后的旧句柄） | — |
+| `interaction_not_found` | -32002 | 待处理项不存在，或已被别人先答了 | `request_id` |
+| `wrong_response_kind` | -32602 | 回答的种类和待处理项对不上（例如拿提问的回答去答审批） | `expected` |
+| `wrong_answer_count` | -32602 | 提问的 `answers` 条数和 `questions` 不一样 | `expected`、`actual` |
+| `command` | -32602 | `session.query` 里的斜杠命令展开失败 | — |
+| `permission_mode_not_allowed` | -32602 | 经中转时要切到 `bypassPermissions`，但 Agent 没加 `--allow-bypass` | — |
+| `unknown_subscription` | -32602 | `$/unsubscribe` 的订阅号不存在 | — |
+
+参数格式本身不对（缺字段、类型错等）也是 -32602，这时 `data` 里没有 `kind`，只有 `errors`：逐条列出哪个字段、错在哪。
 
 ## 会话生命周期（`--rpc-ws` / `--rpc-relay`）
 
 - 所有客户端都断开后，会话**继续跑**。
-- 同时满足「没有客户端订阅着」和「不在跑回合」才开始计时，持续 30 分钟就关闭（`session.closed`，`reason: "idle"`）。
-  等审批 / 等提问算「不在跑」。
+- 同时满足「没有客户端订阅着」和「不在跑回合」才开始计时，持续 30 分钟就关闭（`session.closed`，`reason: "idle"`）。等审批 / 等提问算「不在跑」。
 - 两个客户端可以同时看、同时操作同一个会话：一方用 `session_id` 调 `session.open` 接入即可。
 - 一个客户端读得太慢（发送队列超过 500 条）会被断开，让它走续传；不影响会话和其他客户端。
 - 进程退出（Ctrl+C）：关掉全部会话，还在等的审批按拒绝处理，正在跑的工具随会话中断。
 
-`--rpc-stdio` 只有一个连接：标准输入读到头、或写标准输出超时（对方不读），都等于连接断开 → 进程结束 → 全部会话关闭。
+`--rpc-stdio` 只有一个连接：标准输入读到头、或写标准输出超时（对方 10 秒不读），都等于连接断开 → 进程结束 → 全部会话关闭。
 
 ## 默认值
 
@@ -208,5 +241,48 @@ COMATE_AGENT_TOKEN=<Agent 令牌> comate --rpc-relay --relay-url wss://relay.exa
 | --- | --- |
 | 会话空闲时限 | 30 分钟 |
 | 每会话事件缓冲 | 2000 条或 8 MiB，先到为准 |
-| 每连接发送队列 | 500 条 |
+| 每连接发送队列 | 500 条（中转那条物理连接上是 5000 条） |
 | 审批 / 提问等待超时 | 无 |
+
+## TS 客户端（`comate-rpc-client`）
+
+仓库内 `packages/comate_rpc/ts/`，不发布 npm，前端用本地路径引用（`"comate-rpc-client": "file:../packages/comate_rpc/ts"`），直接导出 TS 源码，用 Vite 等打包器即可。
+
+```ts
+import { openSession, RpcClient } from "comate-rpc-client";
+
+// url / token 来自 `comate --rpc-ws` 的就绪行。进程重启后令牌会变：传函数，每次（重新）连接时现取。
+const client = await RpcClient.connect({ url, token: () => currentToken, clientInfo: { name: "my-app" } });
+const session = await openSession(client, {
+  params: { include_partial_messages: true },
+  handlers: {
+    approval: async (interaction, { signal }) => ({ decision: "allow" }),
+    question: async (interaction, { signal }) => ({ decision: "answer", answers: [{ selected_options: ["Blue"] }] }),
+  },
+});
+await session.query("hello");
+for await (const event of session.events) {
+  if (event.type === "text.delta") render(event.delta);
+}
+```
+
+- **处理器**：别人先答了、或会话被中断时 `signal` 被中止，收起弹框即可。注册了处理器却漏了某一种时，那一种会打一次 `console.warn`（没人答，回合会卡住）。
+- **取消**：每个方法都能带 `{ signal }`，中止后客户端发 `$/cancelRequest`。
+- **错误**：服务端错误是 `RpcError`，带 `code` 和 `data`，按 `err.kind` 分支（取值见上面的表）。请求发出后连接断了是 `ConnectionLostError`（服务端可能执行了，也可能没有）。
+- **重连**：断线自动重连（指数退避），订阅带（纪元号, 序号）续传，不会重复。进程重启过时，会话层用 `session_id` 重新打开会话、换上新句柄并收到快照，所以调方法时每次现读 `session.handle`。
+
+经中转连远程 Agent，拿到的是同一个会话客户端：
+
+```ts
+import { loginToRelay, openSession, RelayClient } from "comate-rpc-client";
+
+const login = await loginToRelay({ url: "http://127.0.0.1:8765/", account, password }); // { token, expires_at, device }
+const relay = await RelayClient.connect({ url, token: login.token, clientInfo: { name: "my-app" } });
+const changes = await relay.watchAgents();   // 上下线事件：先订阅、再列，中间的变化不会漏
+const agents = await relay.agents.list();    // agent_id、名字、在线、最后上线时间、meta（版本、主机名、工作目录）
+const client = await relay.connectAgent(agents[0].agent_id);
+const session = await openSession(client, { handlers: { /* ... */ } });
+```
+
+- 关闭码 1008 → 抛 `ReloginRequiredError`，回登录；4003 → `AgentNotYoursError`；第一次连就遇到 4004 → `AgentOfflineError`，连上以后遇到 4004 则自动退避重连。
+- 登出：`logoutFromRelay({ url, token })`。

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "comate-cli"
-version = "0.12.4b2"
+version = "0.12.4b3"
 description = "Comate terminal CLI built on comate-agent-sdk"
 readme = "README.md"
 requires-python = ">=3.11,<3.14"
@@ -33,7 +33,7 @@ dependencies = [
     "concurrent-log-handler>=0.9.25",
     "httpx>=0.28.1,<0.29.0",
     "setproctitle>=1.3.7",
-    "comate-rpc>=0.1.2,<0.2",
+    "comate-rpc>=0.1.3,<0.2",
 ]
 
 [project.urls]

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/tests/test_main_args.py

@@ -140,7 +140,7 @@ class TestMainArgs(unittest.TestCase):
                 ["--rpc-relay", "--relay-url", "wss://relay.example/ws/agent-link", "--agent-token", "tok"]
             )
         self.assertEqual(
-            run.await_args.kwargs["rpc_relay"], ("wss://relay.example/ws/agent-link", "tok")
+            run.await_args.kwargs["rpc_relay"], ("wss://relay.example/ws/agent-link", "tok", False)
         )
         self.assertFalse(run.await_args.kwargs["rpc_stdio"])
         self.assertIsNone(run.await_args.kwargs["rpc_ws_port"])
@@ -769,7 +769,7 @@ def test_bad_rpc_ws_arguments_are_rejected_in_the_ui_language(language, argv, ke
 _RELAY_URL = "wss://relay.example/ws/agent-link"
 
 
-def _relay_target(argv: list[str]) -> tuple[str, str] | None:
+def _relay_target(argv: list[str]) -> tuple[str, str, bool] | None:
     return main_module._parse_args(argv)[5]
 
 
@@ -778,10 +778,12 @@ def test_rpc_relay_takes_the_url_and_the_token_argument(monkeypatch) -> None:
     assert _relay_target(["--rpc-relay", "--relay-url", _RELAY_URL, "--agent-token", "from-arg"]) == (
         _RELAY_URL,
         "from-arg",
+        False,
     )
     assert _relay_target(["--rpc-relay", f"--relay-url={_RELAY_URL}", "--agent-token=from-arg"]) == (
         _RELAY_URL,
         "from-arg",
+        False,
     )
 
 
@@ -791,8 +793,9 @@ def test_rpc_relay_prefers_the_environment_token_over_the_argument(monkeypatch)
     assert _relay_target(["--rpc-relay", "--relay-url", _RELAY_URL, "--agent-token", "from-arg"]) == (
         _RELAY_URL,
         "from-env",
+        False,
     )
-    assert _relay_target(["--rpc-relay", "--relay-url", _RELAY_URL]) == (_RELAY_URL, "from-env")
+    assert _relay_target(["--rpc-relay", "--relay-url", _RELAY_URL]) == (_RELAY_URL, "from-env", False)
 
 
 def test_an_empty_environment_token_counts_as_unset(monkeypatch) -> None:
@@ -800,6 +803,17 @@ def test_an_empty_environment_token_counts_as_unset(monkeypatch) -> None:
     assert _relay_target(["--rpc-relay", "--relay-url", _RELAY_URL, "--agent-token", "from-arg"]) == (
         _RELAY_URL,
         "from-arg",
+        False,
+    )
+
+
+# 远程切到「全部放行」要主人在启动命令里明着写；只有 --rpc-relay 是远程，别的模式用它是配错了。
+def test_allow_bypass_is_off_unless_given_with_rpc_relay(monkeypatch) -> None:
+    monkeypatch.setenv("COMATE_AGENT_TOKEN", "from-env")
+    assert _relay_target(["--rpc-relay", "--relay-url", _RELAY_URL, "--allow-bypass"]) == (
+        _RELAY_URL,
+        "from-env",
+        True,
     )
 
 
@@ -829,6 +843,8 @@ def test_without_rpc_relay_there_is_no_relay_target(monkeypatch) -> None:
         ),
         (["--relay-url", _RELAY_URL], message.rpc_relay_option_without_rpc_relay, {"option": "--relay-url"}),
         (["--agent-token", "t"], message.rpc_relay_option_without_rpc_relay, {"option": "--agent-token"}),
+        (["--allow-bypass"], message.rpc_relay_option_without_rpc_relay, {"option": "--allow-bypass"}),
+        (["--rpc-ws", "--allow-bypass"], message.rpc_relay_option_without_rpc_relay, {"option": "--allow-bypass"}),
         (
             ["--rpc-relay", "--rpc-ws", "--relay-url", _RELAY_URL, "--agent-token", "t"],
             message.rpc_mode_conflict,

{comate_cli-0.12.4b2 → comate_cli-0.12.4b3}/tests/test_rpc_mode_logging.py

@@ -61,7 +61,7 @@ asyncio.run(main())
     [
         {"rpc_stdio": True},
         {"rpc_ws_port": 0},
-        {"rpc_relay": ("ws://127.0.0.1:1/ws/agent-link", "token")},
+        {"rpc_relay": ("ws://127.0.0.1:1/ws/agent-link", "token", False)},
     ],
     ids=["rpc-stdio", "rpc-ws", "rpc-relay"],
 )