Import docs/protocol.md
This commit is contained in:
parent
d7300754b0
commit
adf456f1c0
419
docs/protocol.md
419
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.<backend>.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<MuxFrame | HostFrame> }`。该 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:<nativeId>` or `acp:<nativeId>`). The fixed unary endpoints are
|
||||
(the matching backend prefix, such as `cursor:<nativeId>`, `acp:<nativeId>`, `claude:<nativeId>` or `hermes:<nativeId>`). 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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue