diff --git a/docs/protocol.md b/docs/protocol.md index aac540b..cfc8279 100644 --- a/docs/protocol.md +++ b/docs/protocol.md @@ -1,12 +1,11 @@ # DSH Remote Protocol v1 -2026-10-25 实现边界:Host 插件、随包 Remote 客户端和 Android 已移除 Harness `0.1.1-rc.2` ApiProxy 兼容。请使用提供官方 Typert Remote carrier 的 Host;仅提供 ApiProxy 或不支持能力发现的旧 Host 会被拒绝,不再降级。CodeX/ACP 保留独立数据面,Desktop 内存投影统一使用 Typert。本轮不改独立 VS Code Client 或独立 Remote Web 仓库。 +当前 carrier 边界:Host 插件、随包 Remote 客户端和 Android 已移除 Harness `0.1.1-rc.2` ApiProxy 兼容。请使用提供官方 Typert Remote carrier 的 Host;仅提供 ApiProxy 或不支持能力发现的旧 Host 会被拒绝,不再降级。CodeX/ACP 保留独立数据面,Desktop 内存投影统一使用 Typert。独立 VS Code Client 与 Remote Web 按各自的实现范围维护。 `harness.api.*` 方法/事件/capability 的以下定义仅保留为历史线协议与旧 Client 类型契约;当前 Host 不注册这些方法,调用返回 `METHOD_NOT_FOUND`。 -状态:Draft v0.2(首版发布前,不保留旧业务 RPC 兼容) -日期:2026-09-10 +状态:维护中的 v1 线协议;实现支持通过 capability 协商,不以文档示例或软件版本推断 协议版本:`1` -实现状态:**当前仓库实现 Client/Plugin 侧协议与最小单账号 Relay Server;完整 Server 由独立项目实现** +实现状态:**当前仓库实现 Client/Plugin 侧协议与最小单账号 Server(可配置 WebRTC / TURN 和加密 Relay);完整 Server 由独立项目实现** ### Claude ACP Host 实验性接入(Issue #125) @@ -19,13 +18,12 @@ 当前仓库负责: - `packages/protocol` 的类型、schema、编解码和版本校验 -- Plugin 的v0.1.2 alpha.1–rc.1 与 v0.1.5 rc.1 Session V3 Typert Remote tunnel、加密、重连和 capability 行为 +- Plugin 的官方 Typert / Session V3 tunnel、加密、重连和 capability 行为 - Mock Host/Client 与协议 conformance fixtures `apps/server` 实现本文的单账号注册/刷新、设备发现、Control、WebRTC signaling/TURN credential 与 Relay 子集;范围见 [最小 Server](../apps/server/README.md)。其余多账号、主机匹配码、Browser 授权、独立 Relay attach/resume 与 Admin 能力仍属于独立 Server,不得把未实现的能力声明为可用。 -任何与本文不一致的示例代码都视为未完成实现,不能反向修改协议语义。当前尚未发布, -旧 Android 业务 RPC 明确不兼容;首版发布后破坏兼容性的变更必须提升协议版本。 +任何与本文不一致的示例代码都视为未完成实现,不能反向修改协议语义。退役的 Android 自定义业务 RPC 不兼容;破坏现有线协议兼容性的变更必须提升协议版本。 ## 1. 范围 @@ -50,7 +48,7 @@ Admin API 不属于 E2EE Remote Protocol。它是同站点的独立 HTTPS API, 本文的“必须”“禁止”“应该”“可以”是规范性要求。 -- **Host**:运行 DeepSeek Harness 与 `@dsh-remote/plugin` 的设备。 +- **Host**:运行 DeepSeek Harness 与 `ds-harness-remote`(或同版本 TUI 组合包)的设备。 - **Client**:通过 Remote transport 控制 Host 的 Desktop Harness、VS Code、Android 或 Remote Web; Browser Launcher 只注册 `role=client` device 以发现 Host,本身不是 Remote Client runtime。 - **Server**:负责账号授权、presence、signaling 和 opaque Relay 的协调服务。 @@ -348,7 +346,7 @@ Content-Type: application/json 规范要求: - Host 与 Client 的 `owner_account` 必须非空且完全一致。 -- 不允许匿名 Client 注册,也没有设备码创建、领取、确认或轮询接口。 +- 普通账号注册不接受匿名 Client。独立扫码设备配对使用另一组受密钥证明保护的接口及显式关系,见[配对协议](device-pairing-v1.md),不绕过本节连接授权。 - `GET /api/v1/devices` 只返回当前 Client 通过同账号授权边可访问的 Host。 新客户端使用 `?limit=50` 启用分页(1–100),后续传回不透明的 `cursor`, 直到 `nextCursor=null`。只传 cursor 时 limit 默认 50。分页按不可变 deviceId @@ -769,11 +767,10 @@ Plugin Host 的 Harness 业务路由只接受 capability 对应的官方 Typert "type": "rpc.request", "timestamp": 1786000000000, "payload": { - "method": "harness.api.call", + "method": "harness.remote.call", "params": { - "method": "session.list", - "rpcId": "native-rpc-id", - "payload": {} + "endpoint": "session/list", + "payload": { "args": {} } } } } @@ -827,13 +824,18 @@ Harness RPC 路径、路径规范化变体及 query 均以 `INVALID_MESSAGE` 拒 Connection handler。不得通过该入口绕过 Harness Remote allowlist、Remote 设置限制或 终端归属与输入权校验。`body` 只允许 `{ endpoint, payload? }`,`payload` 为普通 JSON 对象或 `null`(数组与原始值拒绝);额外顶层字段拒绝。Host 在进入任何本机 carrier 前 -按 `endpoint` 执行以下编译期固定操作白名单,新增上游操作默认拒绝: +按 `endpoint` 执行编译期固定操作白名单,新增上游操作默认拒绝。 -- 查询:`state`、`models`、`efforts`、`exchange`、`exchange-text`、`file-text`、`earlier`、`chat`、`run-stats`、`thinking`、`usage`、`room-progress`、`group-rows`、`schedules`。 -- Bot 管理:`create-bot`、`duplicate-bot`、`update-bot`、`delete-bot`、`set-main`、`set-flags`、`resume`、`bot-new-part`、`bot-open-part`。 -- 群聊管理:`create-room`、`update-room`、`delete-room`、`stop-room-work`、`goal-draft`、`goal-control`、`room-continue`。 -- Agent 会话管理:`add-agent`、`agent-session`、`agent-adopt`、`agent-archive`、`agent-rename`、`remove-agent`。 -- 会话交互:`send`、`btw`、`btw-cancel`、`btw-delete`、`side-new`、`side-ask`、`side-cancel`、`side-close`、`answer-question`、`dismiss-question`、`dismiss-view`、`view-reply`、`approval-answer`、`stop-member-work`。 +2026-11-13 对齐 [DS-Bot v0.3.6](https://github.com/Fei2411/DS-Bot/tree/v0.3.6): +完整暴露其 `channel.js` 的命名 endpoint 与 `computer/index.js` 的 `computer-*` endpoint, +包括模型供应商、密钥、连接器、IM、手机配对、电脑控制、更新、诊断、头像、分组、记忆编辑与 Side Chat。 +精确清单见 `packages/plugin/src/plugin-route-bridge.ts` 的 `BOT_REMOTE_OPERATIONS`; +独立上游快照见 `packages/plugin/tests/fixtures/ds-bot-v0.3.6-endpoints.json`。 +旧 Host 的 `btw`、`btw-cancel`、`room-continue` 仍放行。 +`approval-answer` 的 choice 不再限制为单次允许/拒绝,交由 DS-Bot 自身校验。 +这些管理操作仅能通过既有认证 Remote 通道调用;不新增 HTTP 路径或通用 endpoint 通配符。 +原有消息/响应大小与 30 秒调用预算保持不变,超大图片或长操作仍受此边界限制。 +这表示 Host 接口透传覆盖,不表示 Android 原生界面已支持所有功能。 `group-rows { roomId, from, to?, anchor? }` 读取群聊账簿中某轮的行,`open` 表示该轮仍在增长; 它也是轮次结束后仍能显示成员回复正文的唯一读取入口。该 operation 于 0.6.4 加入白名单: @@ -859,14 +861,12 @@ DS Bot 0.2.1 旁问:`btw { sessionId, text }` 返回卡片 ID,`btw-cancel { Android 卡片使用固定 0.2.1 schema 和受限表达式解释器,支持本地计算与 SVG 图表; HTML 仅展示摘要和主机打开提示,不执行 HTML/脚本,不增加网络访问或通用 RPC。 -`approval-answer` 只接受 DS Bot 的 `allow`(单次)或 `reject`,不开放 session-wide 审批(0.3.0 起同时覆盖群聊与 Bot 自有会话审批)。 -安装/升级、日程增删、凭据和 connector/mail 管理、IM 外部账号配对与登录、本机 CLI Agent 注册(`local-agent-*`)、电脑操控与截屏(`computer-*`)、能力脚本、memory 写入、浏览器控制、诊断 -文件及本机偏好设置等操作均不开放;不允许通过 `api/bot` 间接扩大 Harness Remote 权限。 -被拒绝的操作返回 `INVALID_MESSAGE`,浏览器兼容入口显示安全的 -`remote-plugin/operation-not-allowed` 原生错误封装。 +未知 endpoint 返回 `INVALID_MESSAGE`,浏览器兼容入口显示 +`remote-plugin/operation-not-allowed` 原生错误封装。DS-Bot v0.3.6 的管理接口 +已按上述完整白名单开放,旧版本文档中的“仅单次审批/本地管理”限制不再适用。 ```json -"params": { "route": "api/bot", "body": { "endpoint": "state", "payload": null } } +{ "params": { "route": "api/bot", "body": { "endpoint": "state", "payload": null } } } ``` Result 为 `{ "status": number, "json": unknown }`,即本机路由的 HTTP 状态码与解析后的 JSON @@ -909,6 +909,7 @@ Host handshake 的 capability 例子: "harness.remote.v1", "harness.remote.transfer.v1", "harness.remote.stream.transfer.v1", + "remote.compaction.async.v1", "fileviewer.read.v1", "workspace.upload.v1", "codex.appserver.v1", @@ -956,8 +957,12 @@ Host 已启用且实现该后端协议,不代表 CLI 已初始化完成。ACP `workspace.upload.open|chunk|commit|abort`。Client 必须以加密通道内的 `harness.transport.describe` 结果确认该能力;它不表示任意目录可写,也不扩展原生 附件、图片 transfer 或只读预览 allowlist。协议详见 [Workspace upload](#workspace-upload)。 +其可选扩展 `workspace.upload.binary.v1` 只在上传服务实际可用且声明基础能力时, +通过认证后的 describe 返回;初始协调握手和旧版 JSON 上传不变。 未声明该能力时不调用上传 RPC;旧 Host 的入口保持禁用。 +`remote.session.events.v1` 声明 Host 的 `$events` 流具备真实转发能力(而非缺少 `@deepseek-ai/dsh-api-remotes` 时的空转兜底),会持续推送 `api-session/added|removed|status|activity|error` 事件,且 `session/control` 与 `workspace/list` 语义就绪;Client 据此可停止周期性全量 `session/list` 轮询,改为增量更新并在新建/移除未知根会话时按需同步工作区目录。 + ### 17.1 工作区类型能力声明(workspaceTypes) 为支持 Web 等客户端动态渲染工作区类型选择器并避免在前端硬编码判断,Host 在 `harness.transport.describe` @@ -967,8 +972,8 @@ Host 已启用且实现该后端协议,不代表 CLI 已初始化完成。ACP { "capabilities": [ "transport.relay", - "harness.api.v1", - "harness.api.transfer.v1", + "harness.remote.v3", + "harness.remote.transfer.v1", "codex.appserver.v1", "codex.appserver.transfer.v1" ], @@ -1026,17 +1031,7 @@ rc.2 ApiProxy 已明确移除。当前实现不翻译 rc.2 与 Typert 的完整 carrier 或 Session 代际不一致时,Desktop Client 必须在选择目标、创建 Workspace 或其它 mutation 前 返回 `HARNESS_VERSION_INCOMPATIBLE`。 -当前 Plugin Client / Android Harness 兼容矩阵: - -| Host Plugin / Harness | 业务 carrier | Remote Workspace / Session | File Viewer | 图片分块 | -| --- | --- | --- | --- | --- | -| `0.3.15–0.3.23` / rc.2 | `harness.api.v1`(历史 capability) | 不支持(已移除) | `0.3.17+` 且 provider 存在时支持 | 不支持 | -| `0.3.24–0.3.36` / rc.2 | `harness.api.v1` | 不支持(已移除) | provider 存在时支持 | `harness.api.transfer.v1` | -| `0.4.x` / rc.2 | capability 探测返回 `harness.api.v1` | 不支持(已移除) | provider 存在时支持 | `harness.api.transfer.v1` | -| `0.4.x` / v0.1.2 alpha.1–rc.1 | capability 探测返回 `harness.remote.v1` | 支持 | provider 存在时支持 | `harness.remote.transfer.v1` | -| `0.4.12+` / v0.1.5 rc.1 与 v0.1.6 alpha.1 | capability 探测返回 `harness.remote.v3` | 支持 | provider 存在时支持 | `harness.remote.transfer.v1` | - -当前 Plugin Client 与 Android 必须使用加密通道上的 capability 探测,不从 `clientVersion` 推测或降级到旧 ApiProxy。 +当前兼容范围见[版本兼容](compatibility.zh.md)。Plugin Client 与 Android 必须在加密通道中探测 capability,不能从 clientVersion 推测或降级到已退役 ApiProxy。 ## 18. 历史数据结构(已废弃) @@ -1053,85 +1048,11 @@ Message(含 role/content 数组)、ToolCall(含 callId/input/output)和 `session.send`、`session.stop`、`permissions.respond`、`connection.ping`、`sync.from`) 均已退出 Plugin 协议,Host 必须拒绝。 -### Historical Native Harness API bridge(已移除) +### 已退役 ApiProxy carrier -`harness.api.v1` 用于让安装了 Plugin Client face 的本地 Harness 继续使用官方 UI 操作远端 Host。它不是通用反射 RPC;Host 必须以代码内固定 allowlist 校验每个 `method`,未知或禁止方法返回 `METHOD_NOT_ALLOWED`。 +`harness.api.*` RPC、`harness.api.v1` / `harness.api.transfer.v1` capability 和相应事件仅保留于部分旧 Client 类型中。当前 Host 不注册这些路由,不能将它们作为安装或调用示例。旧定义可从版本历史追溯;当前业务使用下述 Typert carrier。 -#### `harness.api.call` - -Params: - -```json -{ - "method": "session.list", - "rpcId": "native-harness-rpc-id", - "payload": {} -} -``` - -Result 是 Harness `ApiProxy` 的原生 `RpcResponse`,必须回显内层 `rpcId`。v1 allowlist 仅包括: - -- session list/search/create/history/models/selectModel/rename/fork/prompt/attachment/updateQueue/cancel -- subagent list/history/prompt/interrupt -- `host.describe`、`host.listDirectory`(只读目录元数据,用于远程 Workspace 选择器) -- workspace list/create/rename/delete/reorder/attach/archive -- skill list、agent preset list/select/read -- goal create/edit/pause/resume/complete/clear -- `commands.list`、`commands.execute`(经官方 Typert gateway 分发,使用 Host 对当前 Agent 的有效注册命令) -- LLM provider/model list -- Host 设置与模型发现平面:`settings.describe/update/replace/mutate`、`credentials.describe/set/unset`、`llm.discoverModels` - -`session.attachment` 只转发 Harness 原生的只读查询;Host ApiProxy 必须验证 attachment 已被指定 session 的持久化日志引用后才返回内容。它不能创建、上传、修改或枚举附件。明确禁止 native path open/picker、`settings.openDocument`、目录创建、绕过 File Viewer provider 的文件读取、attachment upload、download 以及任何未列出方法。`host.listDirectory` 只返回单层目录元数据。Host 应优先调用官方 ApiProxy browse capability;当桌面 Harness 只组合 `native` picker 时,Plugin 可在已认证的 Host bridge 内提供等价的只读元数据实现。该兜底必须限制结果数量,只返回目录名、绝对路径、面包屑、Home 路径和 hidden 标志,不得读取文件内容、写入文件系统或扩展为通用文件系统 RPC。若该只读列表能力可用,Bridge 可在 `host.describe` 响应中补充 `canOpenPath: true`,仅用于让 Remote Web 显示目录浏览入口,不代表允许 native picker 或打开路径。`commands.list` 与 `commands.execute` 不是通用方法调用入口:Bridge 必须要求 payload 仅含 `agentId`(`execute` 另含长度受限的 `line` 和空附件数组;当前字段名为 `submittedAttachments: []`,旧 Client 使用 `images: []` 时 Host bridge 会按 Typert descriptor 自动兼容,省略两者时注入空数组),并经官方 Typert gateway 使用 Host 对当前 Agent 解析出的有效命令目录和 handler。命令语法、名称解析、Agent scoped shadowing、参数校验和执行语义均由 Host 命令注册表负责,与本地 Harness UI 一致;未注册命令不会进入 handler。额外字段、非空附件数组、缺失必需参数和超长输入在 Bridge 边界 fail closed。外层 Remote request id 负责安全通道去重,内层 `rpcId` 保持 Harness UI 的原生关联语义。 - -命令附件字段按 Host 版本选择:v0.1.5 及以上使用 `submittedAttachments`,更早版本使用 `images`;未知版本按旧字段处理。 - -Host 设置平面允许已认证且通过本地 identity 固定的 Remote peer 配置 Host 当前注册的设置分区,必须满足以下作用域约束,否则在 Bridge 边界 fail closed: - -- `settings.update/replace/mutate` 的目标命名空间必须存在于 Host 原生 `settings.describe` 实时返回的目录中(未注册或目录不可用即拒绝);`patch`/`section`/`ops` 序列化后不得超过 64 KiB,`ops` 最多 64 条,`path` 最多 8 段且每段不超过 64 字节,`ns` 不超过 128 字节。 -- `settings.describe` 返回原生 seam 当前注册的全部命名空间及其已经过原生 secret redaction 的值;Bridge 必须强制把 `hasDocument` 设为 `false`。写入仍可携带 `expectedRevision`,冲突语义由原生 seam 决定。 -- `credentials.describe/set/unset` 沿用 Harness 官方的全局 credential-reference 语义。引用名称必须是 POSIX 环境变量形态(`^[A-Za-z_][A-Za-z0-9_]*$`,最长 128 字节),`set` 的 value 最长 8 KiB。credential 值只允许在 `credentials.set` 入站方向出现,不得写入日志、不得出现在任何响应里。 -- `llm.discoverModels` 只允许探测 HTTPS 端点(localhost 允许 HTTP),禁止 URL 内嵌凭据和 fragment;`baseURL` 最长 2048 字节,`apiKey` 最长 8 KiB,且仅作草稿探测,Host 不存储、不返回该 key。Bridge 必须把所有探测失败折叠为固定的 `model-discovery-failed` 文案和不含 endpoint/key 的安全 details,不得透传 adapter 错误消息。 -- `settings.openDocument`、native path open/picker、目录创建、任意文件访问仍然禁止。设置写入不允许命中实时注册目录以外的命名空间;credential 引用、设置 payload 和模型发现端点必须继续满足上述边界。 - -#### `harness.api.transfer.*` - -`harness.api.transfer.v1` 是 `harness.api.call` 的有界分块封装,用于 rc.2 图片 prompt 和 -`session.attachment` 响应超过单条 4 MiB secure message 的情况。分块重组后的内容仍必须是 -完全相同的 `{ method, rpcId, payload }` 原生 envelope,并再次经过固定 allowlist;它不是新的 -Harness 业务协议,也不能绕过 ApiProxy。Client 不直接调用 DeepSeek Files API,API key、图片 -预处理、上传与 file id 缓存仍只存在于 Host 的官方 adapter。 - -- `open`: `{ transferId, totalBytes, totalChunks }`,每个 authenticated connection 最多两个活动输入 transfer。 -- `chunk`: `{ transferId, index, data }`,`data` 为 canonical base64,解码后每块最多 512 KiB,必须从 0 开始严格有序且恰好一次。 -- `commit`: `{ transferId }`,完整重组并调用原生 ApiProxy;小响应内联返回,大响应返回 `{ kind: "chunked", transferId, totalBytes, totalChunks }`。 -- `read`: `{ transferId, index }`,严格顺序读取响应分块。 -- `close`: `{ transferId }`,成功、取消或失败后释放输入/输出状态;连接断开时 Host 必须清除该连接的全部 transfer。 - -单个 transfer 上限 288 MiB(容纳上游默认 200 MiB source image aggregate 的 base64 -envelope),空闲 2 分钟过期。任何重复 id、乱序、重放、非 canonical base64、声明长度不符、 -超限或跨 connection transfer id 都必须 fail closed。每个 chunk 仍作为独立 Remote RPC 经过 -Noise 加密、计数器防重放和 membership/trusted-peer 校验。 - -#### `harness.api.respond` - -Params:`{ "message": ClientResponse }`。只用于回答由 Harness 原生事件流发出的 approval/question ServerRequest;`rpcId` 必须由同一 `connectionId` 的 mux stream 实际发出,Client 不能自行创造可回答的 Host request,也不能回答只发送给其他 connection 的请求。 - -#### `harness.api.stream.open` / `harness.api.stream.close` - -Open Params: - -```json -{ - "streamId": "client-stream-id", - "stream": "mux", - "rpcId": "native-open-rpc-id", - "payload": {} -} -``` - -`stream` 仅允许 `mux | host`,每条 peer connection 最多同时打开三个原生流:常驻的 host/mux 各一条,加一条 mux 切换缓冲。mux 流的 `payload` 可携带可选 `sessionId`(focus):提供后 Host 只转发该 session 的 mux 帧(`session/event`、approval、question 等),其余 session 的流量不进入 tunnel;省略时转发全部。Remote Web 每次只关注一个 session,用 focus 避免把其他活跃 session 的大事件流(可能达数 MB)推过 WebRTC/relay 数据面。切换 session 时 Client 先打开新 mux,成功后立即关闭旧 mux;新流失败时保留旧流。Close Params:`{ "streamId": "client-stream-id" }`。`streamId` namespace、三条流上限和生命周期都属于发起它的 `connectionId`;不同 Client 可使用相同 `streamId`,不得互相关闭或接收对方的 tunnel event。连接替换、撤销或断开时 Host 只取消该 connection 的全部流。 - -### Harness Typert Remote bridge(当前基线 0.2.1,兼容 0.2.0 RC) +### Harness Typert Remote bridge(当前基线 0.2.2-rc.1) `harness.remote.v1` 只承载 `dsh-v0.1.2-alpha.1`–`rc.1` 官方 `TypertGateway` 已编码的 carrier envelope;`harness.remote.v3` 承载 `dsh-v0.1.5-rc.1` 的相同官方 carrier 与 Session V3 @@ -1196,6 +1117,16 @@ Harness `0.2.1` 增加固定官方端点 `userQuestions/answer`(call)、`use 当前兼容维护目标为 Typert Session V3 `0.2.x`;前述 ApiProxy 章节仅保留历史线协议,当前 Host 不再实现其路由,Plugin Client 与 Android 不再连接该 carrier。 +#### Host 设置与 credential 边界 + +Host 设置平面允许已认证且通过本地 identity 固定的 Remote peer 配置 Host 当前注册的设置分区,必须满足以下作用域约束,否则在 Bridge 边界 fail closed: + +- `settings/update/replace/mutate` 的目标命名空间必须存在于 Host 原生 `settings/describe` 实时返回的目录中(未注册或目录不可用即拒绝);`patch`/`section`/`ops` 序列化后不得超过 64 KiB,`ops` 最多 64 条,`path` 最多 8 段且每段不超过 64 字节,`ns` 不超过 128 字节。 +- `settings/describe` 返回原生 seam 当前注册的全部命名空间及其已经过原生 secret redaction 的值;Bridge 必须强制把 `hasDocument` 设为 `false`。写入仍可携带 `expectedRevision`,冲突语义由原生 seam 决定。 +- `credentials/describe/set/unset` 沿用 Harness 官方的全局 credential-reference 语义。引用名称必须是 POSIX 环境变量形态(`^[A-Za-z_][A-Za-z0-9_]*$`,最长 128 字节),`set` 的 value 最长 8 KiB。credential 值只允许在 `credentials/set` 入站方向出现,不得写入日志、不得出现在任何响应里。 +- `llm/discoverModels` 只允许探测 HTTPS 端点(localhost 允许 HTTP),禁止 URL 内嵌凭据和 fragment;`baseURL` 最长 2048 字节,`apiKey` 最长 8 KiB,且仅作草稿探测,Host 不存储、不返回该 key。Bridge 必须把所有探测失败折叠为固定的 `model-discovery-failed` 文案和不含 endpoint/key 的安全 details,不得透传 adapter 错误消息。 +- `settings/openDocument`、native path open/picker 和任意文件访问仍然禁止;工作区创建仅按上述固定 workspace/create 边界执行。设置写入不允许命中实时注册目录以外的命名空间;credential 引用、设置 payload 和模型发现端点必须继续满足上述边界。 + #### `harness.remote.stream.open` / `harness.remote.stream.close` Open Params:`{ "streamId", "endpoint", "payload" }`;Close Params:`{ "streamId" }`。 @@ -1246,15 +1177,54 @@ Client 的 256 项/4 MiB 等待队列只存小描述,同一 stream 同时只 事件的结果必须经 allowlisted `$events/result` unary endpoint 返回原 Host;Plugin 不创造 permission id、decision enum 或额外响应状态机。 +#### `harness.remote.compaction.*`(异步压缩) + +`remote.compaction.async.v1` 是 Remote 自有契约,不改变 Harness `commands/execute` 的语义: +官方 `/compact` handler 会等待 `compactNow()` 完成,本地慢后端(例如 prefill 约 1k tok/s、 +上下文 500K)单次压缩需要数分钟,任何单条 RPC deadline 都不应成为压缩的实际期限。 + +- `harness.remote.compaction.submit`,Params `{ sessionId, requestId, budgetMs? }`,Result + `{ operationId, state }`。Host 登记后立即返回 `accepted`;相同 `requestId` 在 + `(deviceId, sessionId)` 范围内幂等去重,响应丢失后重试不会重复执行。Host 后台继续调用 + 固定命令 `/compact`。 +- `harness.remote.compaction.status`,Params `{ sessionId, operationId }`,Result + `{ operationId, sessionId, state, acceptedAt?, startedAt?, finishedAt?, message? }`, + `state` 为 `accepted|running|cancelling|succeeded|failed|cancelled|interrupted|unconfirmed`。 +- `harness.remote.compaction.cancel`,Params 与 status 相同。Harness 的 + `commands/execute` 经 `withAbort()` 在 signal 中止后立即停止等待 handler,而 handler + 可能仍在压缩、持锁并持久化;因此“命令调用已返回”不等于“压缩已收尾”。Host 在取消后 + 先返回 `cancelling`,再结合 Session 日志中的 `command/run` 与 + `compaction/end`(同一 `sourceCommandId`)确认收尾:确认失败则返回 `cancelled`; + 确认成功提交(`compaction/end` 无 error)但取消期间已无法观察持久化结果时返回 + `unconfirmed`,不得仅凭取消标记覆盖成功;始终无法确认时保持 `cancelling`, + Client 继续轮询。预算超时遵循同一规则(确认失败为 `failed`,已提交但不可确认时为 + `unconfirmed`,未确认时保持 `cancelling`)。 +- 执行归属 Host runtime,不随提交连接关闭而中止;断线只停止观察,重连后可用同一 + `operationId` 继续查询。Host 重启后未知 id 返回 `interrupted`,不自动重放,也不伪造成功。 +- `budgetMs` 是压缩任务自身预算(默认 30 分钟,钳制到 1–120 分钟),与提交/查询 RPC 的 + 超时分离。终态以 Host 后台 `commands/execute` 的结算为准;仅看到 `compaction/end` + 不能判定成功,后续保存失败必须报告为 `failed`。 +- 本契约只覆盖 `/compact`。其他命令、插件清单校验、提醒创建等继续使用现有 RPC 超时策略; + Host 不开放任意后台命令。未声明该能力的旧 Host 保持原 `commands/execute` 行为。 +- 同一 Session 同时只接纳一个未结束的压缩操作(新的 `requestId` 在旧操作结束前返回 + `AGENT_BUSY`);Host 最多跟踪 32 个操作,超出返回可重试的 `RATE_LIMITED`。终态在内存 + 保留 10 分钟用于查询与去重;过期后的未知 `operationId` 不证明原压缩失败,也不会被自动重放。 +- 产品客户端(Android)在提交前持久化 `requestId`、收到响应后持久化 `operationId`,按 + Host 设备与会话隔离;提交响应丢失时用同一 `requestId` 重试,重连后只查询原操作。 + 观察失败返回“暂时无法确认状态”,不得当作压缩失败或再次提交。 + #### `harness.remote.transfer.*` -`harness.remote.transfer.v1` 是 `harness.remote.call` 的有界分块封装。操作、512 KiB chunk、 +`harness.remote.transfer.v1` 是 `harness.remote.call` 的有界分块封装。操作为 open / chunk / commit / read / close,使用 512 KiB chunk、 288 MiB 总大小、严格有序/恰好一次、canonical base64、每连接输入/输出各两个 transfer 和 -2 分钟 idle 规则与 `harness.api.transfer.v1` 相同。重组后的 JSON 必须仍是 +2 分钟 idle 清理。重组后的 JSON 必须仍是 `{ endpoint, payload }`,并再次经过同一固定 endpoint allowlist;它不能绕过 Gateway 或 扩展可调用业务面。直接调用若收到 `RESPONSE_TOO_LARGE`,Client 必须以相同请求自动重试一次 该分块路径;其他错误不得触发隐式重试。 +输入 open 为 `{transferId,totalBytes,totalChunks}`,chunk 为 `{transferId,index,data}`,commit 为 `{transferId}`;大响应返回 `{kind:"chunked",transferId,totalBytes,totalChunks}`,由 `{transferId,index}` 按序 read,最后 close。chunk 解码后最多 512 KiB;重复 ID、乱序、非规范编码、长度不符或跨连接句柄均拒绝,断线清理该连接全部 transfer。 + + 新版 DSH 0.1.6 的 `permissions` Session 投影仅保留 `currentValue`;选项通过官方 `permissionPresets/catalog`(`{ args: {} }`)读取,返回 `{ options: [{ value, name, description? }] }`。 Host 固定 allowlist 仅增加该只读 endpoint;预设切换继续使用官方 `commands/execute`。 @@ -1263,7 +1233,7 @@ Host 固定 allowlist 仅增加该只读 endpoint;预设切换继续使用官 ### Native sidebar: read-only files and Host-configurable terminal Harness `0.1.6-alpha.2` 原生侧栏通过现有 `harness.remote.*` carrier 传输;不新增 Harness wire format。 -Android 用户可显式下载工作区原文件到系统目录选择器授权的手机目录(每文件最多 100 MiB,包含恰好 100 MiB;独立于移动端预览上限:PDF 16 MiB、图片 8 MiB)。复用下述 `stat` / `readBytes` 分块读取及路径、版本、大小和取消校验,不新增 download RPC,不写 Host 文件;Office 下载保存原文件,转换后的 PDF 仅用于预览。 +Android 用户可显式下载工作区原文件到手机(Android 10+ 使用 MediaStore Downloads,Android 8–9 使用系统目录选择器)(每文件最多 100 MiB,包含恰好 100 MiB;独立于移动端预览上限:PDF 16 MiB、图片 8 MiB)。复用下述 `stat` / `readBytes` 分块读取及路径、版本、大小和取消校验,不新增 download RPC,不写 Host 文件;Office 下载保存原文件,转换后的 PDF 仅用于预览。 固定只读 allowlist:`workspaceFiles/list|stat|read|readBytes|readAll|readRelated|changes`,以及 `officeToPdf/generation|render`。Host 官方 Session lookup、组合文件系统、分页与大小限制继续生效。 @@ -1372,7 +1342,7 @@ Host 必须调用 `fileViewerHost` 服务,让被选中的 File Viewer provider Agent ACP 是现有 Remote Plugin 内部的通用业务面(见 #65),不是第二个 Plugin,也不是 Codex 专用 API。Host 通过 `acp.enabled` 和 `acp.backends` 独立配置 Cursor / Antigravity / Pi -adapter 的启用、command、args 与 cwd;旧 `cursor.enabled` / `cursor.binary` 仅兼容 Cursor。 +以及 OpenCode / Claude / Hermes adapter 的启用、command、args 与 cwd;旧 `cursor.enabled` / `cursor.binary` 仅兼容 Cursor。 `agent.acp.v1`、`agent.acp.transfer.v1` 与 `agent.acp..v1` 表示启用且已实现的协议; 实际就绪状态见 `workspaceTypes.available`,后台初始化不得阻塞 Harness Remote。 现有 `harness.api.*` / `harness.remote.*` 和 `codex.app.*` 的线协议、路由与能力不受影响。 @@ -1407,7 +1377,7 @@ Host 以可信 catalog / realpath 和原生返回的 ID/目录确认会话归属 受信任同账号连接归档。原生失败或响应未确认返回 `OPENCODE_ARCHIVE_UNAVAILABLE`,后端 关闭或替换不能返回迟到成功。Desktop/Android 在成功确认后更新内存,失败保留原状态。 其他 ACP 后端无此能力,禁止仅移除本地投影并返回归档成功。具体进程隔离与验证边界见 -[OpenCode 原生归档设计](design/acp-session-archive.md)。 +[OpenCode 原生归档设计](acp-remote.md#opencode-与原生归档)。 Client 侧 `initialize` 由 Gateway 返回 backend-neutral 能力描述,不把 Cursor 私有 method 名暴露为公共面。AGY 的 `dsh/sessionList` 在指定有效工作目录时可异步预热该目录的一个空闲进程,不等待初始化、 @@ -1613,7 +1583,7 @@ ACP 同时要求调用连接的 peer 仍有效、backend 可用、session owner - `open`:`totalBytes` 是非负整数:Host 验证当前连接为 LAN 或直接 P2P 时最大 1 GiB(1,073,741,824 bytes);TURN、Relay、未知路径最大 20 MiB。Host 在 open、chunk 和 commit 重新检查实际路径;大文件传输回退至中继时拒绝并清理未提交数据。旧 Host 可保留 20 MiB 限额,Client 不得自动重传。`name` 是单个文件名,UTF-8 编码最多 220 bytes;禁止 `/`、`\`、ASCII 控制字符、DEL、`<>:"|?*`、`.`、`..`、尾部点/空格、 Windows 保留名,以及 Host 临时文件前缀 `.dsh-upload-`。不能传 `cwd`、目标目录或目标路径。 - Host 当前返回 `chunkBytes: 65536`,表示后续每块**解码后**最多 64 KiB。 + 未协商二进制扩展时,Host 返回 `chunkBytes: 65536`,表示后续每块**解码后**最多 64 KiB。 - `chunk`:`offset` 是从 0 开始的非负整数字节偏移,必须等于上一块确认后的 `receivedBytes`。`data` 使用标准、规范的 Base64(含所需 padding),不使用 Base64URL; 解码结果不得为空、不得超过 `chunkBytes`,累计不得超过 `totalBytes`。Host 顺序写入, @@ -1626,6 +1596,26 @@ ACP 同时要求调用连接的 peer 仍有效、backend 可用、session owner - `abort`:移除同一会话下尚未提交的上传;不存在或已提交时幂等返回 `{aborted:true}`, 不删除已经发布的文件。活动句柄属于其他会话时返回 `UPLOAD_NOT_FOUND`,不影响原上传。 +#### 可选二进制上传扩展 + +`workspace.upload.binary.v1` 是 `workspace.upload.v1` 的附加能力,仅在认证后的 +`harness.transport.describe` 同时声明两者时启用。旧 Host 未声明时,Client 保持原有 +open 参数和 64 KiB Base64 chunk;新 Host 对旧 Client 的参数及响应也完全保持原样。 +不得通过发送 mutation 探测支持情况,或在传输失败后换格式重放数据。 + +Client 在 open 增加 `encoding: "binary-v1"`,Host 回显该字段并返回 +`chunkBytes: 262144`。只有该上传句柄可以调用 `workspace.upload.chunk.binary`,其参数 +仍为 `{sessionId, uploadId, offset, data}`,但 data 是原始 Uint8Array;响应仍为普通 +JSON RPC 的 `{uploadId, receivedBytes}`。同一上传不能混用两种 chunk。Client 校验 +句柄、累计确认偏移与 commit 的完整字节数;最多四块在途,确认后报告进度。 + +二进制 RPC 位于现有 Noise 加密层内,使用固定 12-byte 前缀: +`44 53 48 55 50 01 00 00`,随后四字节大端无符号 JSON header 长度。Header 是正常的 +`rpc.request` envelope,但 params 不含 data;紧随其后的是原始 chunk 字节。仅允许 +`workspace.upload.chunk.binary` 使用此格式,header 最多 4096 bytes,正文 1–262144 +bytes;解码后仍通过现有 envelope 校验与 Host 上传授权。普通消息的 JSON 格式、Noise +suite、nonce 归属、分片、上传总额限制、目录归属检查及原子提交均不变。 + 例如上传原名 `report.txt` 的三个字节 `abc`,且目录中已有同名文件: ```text @@ -1643,6 +1633,50 @@ workspace.upload.commit 以上 Params/Result 仍使用 §16 的 `rpc.request` / `rpc.response` / `rpc.error` envelope, 每次调用各有独立 request ID;上传顺序由 `uploadId`、`offset` 和 Host 状态共同约束。 +#### 可选 LAN TCP 上传扩展 + +`workspace.upload.lan.v1` 依赖基础与二进制上传能力,只能通过已认证的 +`harness.transport.describe` 获知。首个客户端为 Android:仅对至少 1 MiB 的二进制上传、 +当前真实路径为 LAN、原生二进制 WebSocket sender 可用时尝试。聊天和控制流不迁移。 +IPv6、P2P、TURN、Relay、旧 Host 和缺少原生模块的客户端沿用现有上传路径。 + +Client 从当前 WebRTC 选中路径读取 Host 的实际 IPv4 地址,再在**原认证通道**调用: + +| RPC | Params | Result | +| --- | --- | --- | +| `workspace.upload.lan.open` | `{sessionId, uploadId, address}` | `{sessionId, uploadId, connectionId, url, expiresInMs}` | + +此 RPC 只分配临时入口,不创建文件。Host 从认证连接取得设备静态公钥与 connectionId, +不接受 Client 自报身份;只接受本机网卡实际拥有的 RFC1918 IPv4 字面地址,并且当前 +Host 观测路径必须为 LAN。每个认证连接最多两个入口,分别绑定一个 sessionId/uploadId。 +入口为该地址上的随机 TCP 端口,固定路径 +`/ds-harness-remote/upload/<32-byte base64url ticket>`;票据未使用时 10 秒过期, +一次 WebSocket upgrade 即消耗,错误路径不消耗。普通 HTTP 请求一律 404。 + +Client 必须验证返回的 sessionId/uploadId/connectionId 与当前操作完全一致;URL 必须为 +`ws:`,主机字面地址与实际选中的 Host 地址一致,不能含用户信息、query、fragment、 +任意路径或 DNS 名称。新 socket 使用独立的 Noise IK,会话双方仍校验原连接固定的静态 +身份密钥。Prologue 是 UTF-8 编码的 JSON 数组: +`["ds-harness-remote/lan-upload/v1", connectionId, sessionId, uploadId, ticket]`。 +Host 握手预算 5 秒,Android 从连接开始的总预算 3 秒;握手未成功不能发送上传 RPC。 + +握手后,每个二进制 WebSocket message 是一个 Noise ciphertext(最多 65,535 bytes)。 +内部继续使用原 `SecureMessageCodec` 和二进制 RPC 格式,不再附加 RTC 的 8 KiB 分片。 +只允许绑定 scope 的 `workspace.upload.open`(encoding 必须是 binary-v1)、 +`workspace.upload.chunk.binary`、`workspace.upload.commit`、`workspace.upload.abort`。 +不转发 Harness、插件路由、终端或其他业务。复用同一个连接所有者的 WorkspaceUploadHost, +保持真实会话工作区授权、目录身份检查、偏移与完整长度校验、限制、不覆盖原子发布和 fsync。 +Android 仍最多四个 256 KiB chunk 在途,原生 sender 只传递 ciphertext 字节,不拥有密钥、 +nonce、重连或重试逻辑。Host 最多接受 2 MiB / 8 条排队 RPC;空闲 120 秒清理。 + +入口与 socket 都属于原认证连接;断开、替换或撤销时销毁票据、监听器与 Noise session, +清理尚未提交的临时文件。切出 LAN 后拒绝后续数据请求。提交已完成时,即使响应丢失也不能 +删除已发布文件;Client 必须把这种结果视为投递不确定,不能换通道重发。 + +未声明能力时不探测。协商返回不支持或入口不可达、且**尚未发送文件 open RPC**时,可以在 +原通道执行一次正常上传。认证/帧校验失败、取消、连接替换不触发降级;文件 open、chunk、 +commit 任意一次发送后失败,都不能回退重放。abort 是清理请求,可以通过原通道发送。 + #### 生命周期、重试与落盘边界 每连接最多 2 个活动上传。Host 在工作区根目录排他创建随机 `.dsh-upload-*.part` @@ -1703,9 +1737,7 @@ Web 在选择、拖拽或粘贴文件后开始上传,每个输入栏最多保 ## 20. Events -Plugin 按 Harness 代际发送 `harness.api.frame` / `harness.api.stream.closed`,或 -`harness.remote.frame` / `harness.remote.stream.closed`。可选 Codex 领域发送 -`codex.app.frame` / `codex.app.stream.closed`。 +当前 Host 发送 `harness.remote.frame` / `harness.remote.stream.closed`;CodeX 使用 `codex.app.*`,ACP 使用 `agent.acp.*` 事件。历史 `harness.api.*` 事件不由当前 Host 发送。 冻结 Android 原型事件(`session.created`、`session.updated`、`message.created`、 `message.delta`、`tool.started`、`tool.updated`、`tool.finished`、 @@ -1722,7 +1754,7 @@ Event envelope: "timestamp": 1786000000000, "payload": { "seq": 8272, - "event": "harness.api.frame", + "event": "harness.remote.frame", "data": {} } } @@ -1730,14 +1762,6 @@ Event envelope: `seq` 在同一 Host identity 上严格递增。重放必须保留原始 seq/id/timestamp。 -### `harness.api.frame` - -data:`{ "streamId": "...", "frame": RpcRequest }`。该 event 不进入 Host 的通用 seq replay buffer;Harness Client Runtime 负责按原生流语义重连并重新取得 history baseline。 - -### `harness.api.stream.closed` - -data:`{ "streamId": "...", "reason": "cancelled|completed|failed|peer-disconnected" }`。Client 收到后必须结束对应 iterator;transport 意外关闭时本地模式切换器必须 fail closed,不得继续向旧 Host 提交请求。 - ### `harness.remote.frame` data:`{ "streamId": "...", "hasValue": true, "value"?: unknown }`。`hasValue` 区分显式 @@ -1750,45 +1774,11 @@ Client 收到后结束对应 iterator;`failed` 必须以 Gateway 归一化 fai ## 21. Event Replay 与重连 -本节旧 `sync.from` 机制已退出 Plugin。Desktop Client 重连后重新打开官方 mux/host -stream,并由 Harness UI 重新读取原生 history baseline;Plugin 不维护第二套 replay buffer。 +`sync.from`、`sessions.get` 和旧通用 replay buffer 已退出 Plugin。Client 不得通过这些方法恢复会话,也不应持久化一个通用 lastSeq 并据此推断跨流完整性。 -Client 为每台 Host 持久化 `lastSeq`,但不必持久化解密后的 conversation。 +业务连接断开后,清理连接所属 RPC、stream、transfer 和待答句柄;新连接重新完成 membership、pinned identity 与 Noise 认证,重新打开官方 stream,由 Harness UI 或对应 CodeX/ACP Client 读取历史 baseline。各流的 seq/cursor 依其所属官方契约处理,不建立第二份持久化会话或重放结果未知的 mutation。 -Secure channel 恢复后调用扩展 RPC: - -```text -sync.from -``` - -Params: - -```json -{ "afterSeq": 8271 } -``` - -Result: - -```json -{ - "events": [], - "lastSeq": 8290, - "hasMore": false -} -``` - -如果 Host replay buffer 不再包含所需 seq,返回: - -```json -{ - "code": "FULL_RESYNC_REQUIRED", - "details": { "currentSeq": 9000 } -} -``` - -Client 随后调用 `sessions.get` 获取当前会话 snapshot。恢复期间 Send/permission 按钮必须禁用,避免在未知状态上产生副作用。 - -Event 去重 key 为 `(hostDeviceId, seq)`。收到 `seq <= lastSeq` 的重放事件忽略;收到 `seq > lastSeq + 1` 立即暂停 reducer 并同步。 +已协商控制租约且数据面健康时,控制面恢复不等于业务连接断开;按下述可选恢复契约保留原有流与计数器,不能先清理再伪造“无损恢复”。 ## 22. Ping/Pong @@ -1929,10 +1919,10 @@ pong 回显 nonce。Heartbeat 不能携带业务数据。 | ICE candidates / connection | 256 | | Heartbeat interval | 25 s | | Heartbeat disconnect | 75 s | -| Event replay window | 至少 10,000 events 或 15 min,取先达到者 | +| 通用 Event replay buffer | 不提供;恢复读取所属领域的历史 baseline | 工作区上传采用上述固定限额,`chunkBytes` 由 open 返回,不新增 hello/system.info 字段。 -其他限制如由 Server/Host 协商缩小,必须在 hello/system.info 中公布。超限必须返回稳定错误或关闭违规连接,不能无限缓存。 +其他可协商限制通过 hello.ack 或对应 capability/操作响应公布;system.info 已退役。超限必须返回稳定错误或关闭违规连接,不能无限缓存。 ## 25. 安全不变量 @@ -1966,7 +1956,7 @@ pong 回显 nonce。Heartbeat 不能携带业务数据。 - Workspace upload 连接/会话/后端 authority 隔离、路径穿越与根目录/临时条目替换拒绝 - Workspace upload 取消/空闲/断线清理、迟到目录解析取消与提交点后文件保留 - Workspace upload 提交缓存幂等、缓存失效后的结果未知与旧 Host capability 降级 -- event seq、duplicate、gap、replay 和 full resync +- 原生流顺序、历史 baseline 恢复、重复/迟到帧隔离与不重放 mutation - Host/Client account authorization、owner mismatch 与跨账号访问拒绝 - Host registration code expire/single-use - Noise IK handshake、peer mismatch、tamper、replay 和 rekey @@ -1979,7 +1969,7 @@ UI 排版、静态说明和 Admin 普通筛选不属于协议 conformance。 ## 27. 实现差距管理 -当前 `packages/protocol`、`packages/crypto`、`packages/webrtc` 和 Server scaffold 是早期代码,不得仅因类型存在就声明符合本规范。 +共享类型、runtime schema、Host/Client 接入和 Server 支持范围需要一致;类型存在不能单独证明符合本规范。未完成工作见 [TODO](TODO.md)。 实现阶段应维护 checklist: @@ -2066,15 +2056,14 @@ allowlist,也不提供文件写入能力。 ### ACP shared workspace tools and live AGY models `agent.acp.workspace-files.v1` enables readonly workspace files. `agent.acp.terminal.v1` -is advertised only while the Host Remote terminal setting is enabled. Both work for -Cursor and Antigravity; session scope is supplied by the backend, never a client cwd. +is advertised only while the Host Remote terminal setting is enabled. These shared workspace tools cover the implemented ACP backends, including Cursor, Antigravity, Pi, OpenCode, Claude and Hermes; session scope is supplied by the backend, never a client cwd. `agent.acp.antigravity.models.v1` enables the live installed AGY model catalog and confirmed per-conversation model/effort selection. Remote versions below `0.5.0` continue to ignore `workspaceTypes`; newer clients require these optional capabilities. - `agent.acp.call` method `dsh/toolCall` takes `{sessionId,backend,endpoint,args}`. `sessionId` is the native ID; every scope in `args` must equal its UI ID - (`cursor:` or `acp:`). The fixed unary endpoints are + (the matching backend prefix, such as `cursor:`, `acp:`, `claude:` or `hermes:`). The fixed unary endpoints are `workspaceFiles/list|stat|read|readBytes|readAll` and `terminal/environment|shells|list|create|write|resize|rename|close`. - `agent.acp.stream.open` accepts an optional `tool:{backend,endpoint,args}` with @@ -2110,7 +2099,7 @@ continue to ignore `workspaceTypes`; newer clients require these optional capabi earlier replies after a model change. AGY transcripts without model metadata must not be assigned a fabricated historical model. -ACP model selection also accepts `backend:"cursor"|"claude"|"pi"|"opencode"` through the same +ACP model selection also accepts `backend:"cursor"|"claude"|"pi"|"opencode"|"hermes"` through the same `dsh/sessionModels` / `dsh/selectModel` envelope. Pi uses its wrapper's reported model/thinking options. Cursor, Claude and OpenCode use the session's `configOptions` (including grouped model choices), or legacy `models.availableModels`; no static catalog @@ -2136,25 +2125,83 @@ configuration RPC or fabricated choices. The display name is `Claude`, backend I ### Official plugin management (2026-10-22) -The authenticated Typert channel allows only `pluginManager/listBundles`, -`pluginManager/listPlugins`, `pluginManager/setBundleEnabled` and -`pluginManager/setPluginEnabled` for the official plugin page. Enablement keeps +The authenticated Typert channel allows fixed official plugin-page endpoints, including `pluginManager/listBundles`, `pluginManager/listPlugins`, `pluginManager/listVersions`, `pluginManager/readBundleDetail`, `pluginManager/setBundleEnabled`, `pluginManager/setPluginEnabled` and `pluginManager/updateBundle`. Enablement keeps the official `{ args: { name, enabled } }` / `{ args: { id, enabled } }` envelope and native saved/runtime/restart outcomes. The Host checks the current official inventory before mutation; unknown/read-only entries, Remote itself and bundles containing Remote are rejected. These endpoints cannot be opened as streams. Plugin configuration continues through the existing official `settings` endpoints; -Remote access namespaces remain local-only. Installation, removal, arbitrary -plugin-manager methods and legacy ApiProxy plugin management remain disallowed. +Remote access namespaces remain local-only. Third-party bundle updates use the official manager; Remote itself and any bundle containing it remain protected. Arbitrary install/remove and unlisted plugin-manager methods remain disallowed; local self-update has a separate control path. This adds no new wire format or capability and requires an updated Host plugin. -## Optional WebRTC control recovery (implementation in progress) +## Optional WebRTC control recovery The additive `transport.webrtc.resume.v1` contract is specified in -[WebRTC control recovery](design/webrtc-control-recovery.md). Protocol v1 and +[WebRTC control recovery](design/control-recovery.md). Protocol v1 and legacy control lifetimes remain unchanged unless all three parties negotiate it. ## Device pairing v1 -The full Server and Remote plugin implement phone confirmation followed by one local Host code submission. New Hosts accept incoming connections only. See [the protocol](device-pairing-v1.md) and [DSH-Go integration](dsh-go-pairing-integration.md). This capability is not available in the bundled minimal `apps/server`; unsupported Servers fail closed. +The full Server and Remote plugin implement phone confirmation followed by one local Host code submission. New Hosts accept incoming connections only. See the [pairing contract and mobile integration](device-pairing-v1.md). This capability is not available in the bundled minimal `apps/server`; unsupported Servers fail closed. + +### Remote official attachment uploads + +The Remote browser client installs the official `__DSH_FILE_UPLOAD__.fetch` hook +and also replaces the live `fileUpload.post` carrier when the shell has already +constructed it. This covers the shared Harness Web/Desktop/IDE upload service. +In local mode the request retains its original destination. In Remote mode, +`api/session/uploadFileBinary` attachments enter the Client-local control operation `plugin.route.call` +with body `{ endpoint: "image", payload: { sessionId, mediaType, name?, data } }` +for images, or `{ endpoint: "file", payload: { sessionId, name?, data } }` for +ordinary files, including empty files. +`data` is base64; PNG/JPEG/WebP/GIF are accepted. This local control operation does not expose the upload path through the encrypted Bot route allowlist. The Client runtime routes +attachments through the dedicated `remoteUploads/upload` Harness Remote endpoint +(`remoteImages/upload` remains an alias), +using the existing ordered `harness.remote.transfer.*` protocol for oversized +requests. Individual encrypted frames remain below 4 MiB. Image acceptance is +controlled by the official Host service's `imageLimits` (`maxImageBytes`, +`maxMessageImageBytes`, dimensions, pixel count and media types), rather than a +2 MiB Remote image limit. A 192 MiB raw-image transport safety ceiling keeps +base64 requests within the existing 288 MiB aggregate transfer budget. +The native `fileUploads/upload` RPC is also forwarded for IDE clients submitting +encoded bytes. Ordinary files use the official file storage service; Remote +never accepts a destination path. The Host sanitizes the display filename and +stages the upload under the receiving Session. Prompt file blocks carry only +`{ type: "file", receiptId }`. Current Hosts also accept those file receipts in +`commands/execute.submittedAttachments`; older Hosts reject them rather than +dropping the attachment. +The Host reconstructs the raw-byte request to the fixed official upload route, +using its authenticated local Connection carrier. Official Session staging and +attachment receipts are preserved; no client-local attachment reference is +substituted. Disconnection, unsupported Host versions and non-Harness backends +fail closed. Upload mutations are never automatically retried. Older Hosts +reject the new endpoint and must be upgraded on both ends. The standalone +VS Code extension accepts one file or image per message: images use inline +image content, while other files are staged through `fileUploads/upload` and +submitted by receipt. Both use the existing chunked Remote transport. + +### Client-local `@file` mentions in Remote prompts + +When a Desktop client selects a Remote Harness workspace, its local +Remote plugin intercepts `session/prompt` before forwarding. Standalone native absolute `@file` mentions in user text (for example +`@C:\\...` on Windows or `@/Users/...` on macOS, with quoted paths for spaces) are +checked against the selected remote workspace's `fileReferences/list` first. +An exact remote file candidate remains a text mention for the remote Host. +Otherwise, an existing client-local file is read by the client machine's Host process, uploaded with the existing +`fileUploads/upload` call into the selected remote Session, and replaced by +`{type:"file",receiptId}` content blocks. The client forwards the prompt only +after each upload returns a valid receipt. Missing, non-regular, symbolic-link, +or oversized client-local files fail the prompt. Paths absent on the client remain +text mentions for remote Host resolution. +At most four files and 192 MiB total are accepted per prompt. Non-absolute and non-native `@` references keep their existing behavior. The remote Host's +attachment service still controls file acceptance and storage. + +### Optional in-band live transport upgrade (`remote.transport.upgrade.v1`) + +When the Host advertises `remote.transport.upgrade.v1` in `harness.transport.describe`, a Client that completed its authenticated Noise IK session immediately over Relay may negotiate higher-tier WebRTC DataChannels (`TURN -> P2P -> LAN`) in-band without rotating Noise keys, resetting stream subscriptions, or altering the Relay Server: + +- **Handshake vs initial history separation**: Relay completes Noise authentication in parallel with WebRTC hole punching; Clients wait a short bounded direct window (default 450 ms on Wi-Fi/LAN-capable routes, 250 ms on cellular) before sending large initial history/catalog reads so fast LAN/P2P paths avoid Relay history load while high-latency cellular networks still fall back to Relay promptly. +- **RPCs & events**: `remote.transport.upgrade.offer` (`{ attemptId, sdp } -> { attemptId, sdp }`), `remote.transport.upgrade.ice` (`{ attemptId, candidate } -> { ok: true }`, with responder trickle ICE emitted as `remote.transport.upgrade.ice` event), `remote.transport.upgrade.activate` (`{ attemptId, transport? } -> { activated, mode, previousLegEndCounter? }`), `remote.transport.upgrade.drain` (`{ attemptId, previousLegEndCounter } -> { ok: true }`), and `remote.transport.upgrade.abort` (`{ attemptId? } -> { ok: true }`). +- **Authoritative Host path verification**: Tier promotion (`Relay < TURN < P2P < LAN`) strictly trusts the Host's own verified ICE candidate-pair telemetry (`connectionDetails().mode`); client hints never elevate a lower-tier path into `LAN` or `P2P`. +- **Sequenced framing, watermark draining & bounded reorder**: Upgraded DataChannel frames prepend a 12-byte big-endian sequence header (`'DSHU' || uint64 noiseCounter`) before RTCH chunking. Both endpoints buffer out-of-order frames in `SequencedCiphertextReorderBuffer` (bounded by 256 frames, 4 MiB total bytes, and a 5 s gap timeout) and drain superseded WebRTC legs until `receivingCounter >= previousLegEndCounter` (bounded by a 3 s fallback deadline). Upgrade failure before activation keeps the current carrier intact; DataChannel loss after activation closes the tunnel so normal reconnect recovery runs.