dsh-device-fleet 0.0.0-stage → 0.1.0-dev.10

package/docs/notes/network-v1-v2-implementation.md

@@ -0,0 +1,71 @@
+# 网络层 v1/v2 实现说明
+
+状态：**已实现并通过本机双端测试**（2026-11-09）。对应 ADR：[0017 网络层分阶段](../adr/0017-network-phases-direct-and-relay.md)。
+
+## 文件
+
+| 文件 | 作用 |
+|---|---|
+| `src/net/identity.js` | 设备身份（Ed25519 签名 + X25519 协商）、`fleetKey` 邀请编解码、成员证明 HMAC、账号指纹、Relay 注册 token |
+| `src/net/secure-channel.js` | 端到端安全通道：HELLO/HELLO_ACK 握手、签名与成员证明校验、X25519+HKDF 派生、AES-256-GCM 帧、计数防重放 |
+| `src/net/protocol.js` | 版本号、帧类型（rpc.req/res/err、event、ping/pong、ready）、稳定 JSON、错误序列化 |
+| `src/net/direct.js` | v1 直连：TCP 监听器 + 出站拨号（带超时） |
+| `src/net/discovery.js` | v1 局域网发现：UDP 组播公告（fleetHash + deviceId + 直连端口） |
+| `src/net/relay-server.js` | v2 Relay：控制面（注册/连接/接受/拒绝）+ 数据面（两条 TCP 拼接，只搬密文） |
+| `src/net/relay-client.js` | v2 客户端：控制连接、自动重连、请求/接受连接、数据 socket |
+| `src/net/fleet-node.js` | 设备门面：roster/TOFU、直连/发现/Relay 选择、RPC、事件、关闭 |
+| `test/net.test.mjs` | 7 个测试（见下） |
+
+## 线格式
+
+### 安全通道握手（换行分隔 JSON）
+
+1. 发起方 → 响应方 `hello`：`{t:'hello', v:1, fleetId, deviceId, name, edPublic, xPublic, ephX, nonce, ts, accountFingerprint, proof, sig}`
+   - `proof = HMAC(fleetKey, "member|fleetId|deviceId|edPublic|xPublic|accountFingerprint")`
+   - `sig = Ed25519(稳定 JSON(除 sig 外的全部字段))`
+2. 响应方校验 fleet/时间戳/签名/成员证明/账号指纹/已固定公钥，回复 `hello.ack`（同构）。
+3. 双方以 `X25519(ephX_i, ephX_r)` 为 IKM、`sha256(稳定 JSON(hello,ack))` 为 salt，HKDF 派生：
+   - 发起→响应 32B key + 4B nonce 前缀；响应→发起 32B key + 4B nonce 前缀。
+4. 双方各发一条加密 `ready` 帧；收到对方 `ready` 后通道可用（`ready` 事件）。
+
+### 加密帧
+
+```
+| u32be length | AES-256-GCM ciphertext | 16B tag |
+nonce = 4B 方向前缀 || u64be 计数器；AAD = "dsh-device-fleet/frame/v1"
+```
+
+计数器严格递增、按 TCP 顺序校验，重放/乱序/篡改都会使 `openFrame` 失败并断链。
+
+## Relay 协议（v2）
+
+控制面（TCP，换行分隔 JSON）：
+- `register {fleetId, deviceId, ts, token}` → `register.ok`；`token = HMAC(fleetKey, "relay-register|fleetId|deviceId|ts")`；Relay 用配置的 fleetKey 校验，时间戳 ±120s。
+- `connect {reqId, targetDeviceId}` → 请求方收 `connect.pending`，目标方收 `incoming {reqId, fromDeviceId}`。
+- 目标方 `accept {reqId}` → 双方收 `connect.ready {reqId, dataPort, token}`；`reject` → 请求方收 `connect.fail`。
+- 心跳 `ping`/`pong`。
+
+数据面（第二个 TCP 端口）：双方分别连接并发送一行头
+`{fleetId, deviceId, reqId, token}\n`，Relay 校验后把两条 socket 的原始字节互相 pipe。**Relay 不解析、不终止加密**，与 secure-channel 的密文完全兼容。
+
+## 已验证（`node test/net.test.mjs`，7/7 通过）
+
+1. 邀请编解码携带 fleet/账号指纹/Relay 地址；
+2. v1 直连：认证握手 + RPC echo + 双向 roster TOFU 固定；
+3. 不同 fleet 或不同账号指纹的握手被拒；
+4. roster 中固定公钥与对端不一致时被拒；
+5. v2 Relay：两设备经中继完成加密 RPC，Relay 记录到 splice；
+6. Relay 拒绝不知道 fleetKey 的客户端；
+7. LAN 组播发现发现对端并通过发现地址直连（组播不可用时测试自动跳过）。
+
+运行：`node test/net.test.mjs`（受限沙箱里 `node --test test/` 需要 spawn 子进程，可能被拒；直接跑测试文件即可）。
+
+## 当前限制 / 后续
+
+- **无 NAT 打洞**：跨网一律走 Relay（v3 再做打洞）。
+- **Relay 控制面为明文 TCP**：部署时应在 TLS/反代之后，或后续加 TLS。
+- **TOFU 无密钥轮换/吊销**：Roster 只固定公钥，设备重装会变新身份；后续加签名 roster 与吊销。
+- **无二进制流式分块**：RPC 参数/结果为 JSON（大文件需后续加 chunk 帧）。
+- **无重放窗口**：严格顺序计数已防重放；断线重连即新会话，不做跨会话恢复。
+- **无速率限制/审计**：Relay 与节点都未做限流；上线前补。
+- **账号指纹需上层注入**：网络层只接收 `accountFingerprint` 字符串，由 Host 插件从 `deepseekAccount.getDeviceIdentity()` 派生。

package/docs/notes/pairing-session-2026-11-09.md

@@ -0,0 +1,30 @@
+# 首次配对实录（2026-11-09）
+
+## 环境
+
+- 设备 A：本机（Windows，DSH desktop profile，`device-fleet` 0.1.0-dev.3）
+  - deviceId：`50fdaf90-f0aa-440e-9fa6-c60ba5051001`，deviceName：`desktop`
+  - 直连：`0.0.0.0:60506`（热点网段 `192.168.137.1:60506`）
+  - allowedRoots：`E:/Dsh_test`
+- 设备 B：另一台设备（同一热点 `192.168.137.0/24`，plugin 0.1.0-dev.3）
+  - deviceId：`c2d42572-e5f0-4d7e-9fff-c28d9a668439`
+- 热点网段内网段：A `192.168.137.1/24`，B 为客户端之一。
+
+## 过程
+
+1. dev.3 邀请携带 `endpoints`（A 的 `210.73.18.88:60506` 与 `192.168.137.1:60506`）。
+2. B 安装 dev.3 → `fleet_join` 新邀请 → 重启；插件读取 enrollment endpoints，自动回连 A。
+3. 结果：双方握手成功，roster 互固定公钥；A 侧 `fleet_list` 显示 B `online`，`fleet_status.connected` 含 B。
+4. `fleet_tools(device=B)` 成功（说明 RPC/加密通道正常）。
+5. `fleet_read(device=B, path=E:/Dsh_test/hello-from-A.txt)` 返回 `denied: no allowed roots configured on this device` —— 策略按设计拦截，B 侧尚未配置 allowedRoots。
+
+## 结论
+
+- **网络层 v1 直连 + 配对流程打通**（组播发现在该热点下不可用，邀请 endpoints 自动回连解决了问题）。
+- **Tool Policy 生效**：目标设备未配置允许根时直调被拒。
+- 待配置 B 的 `policy.allowedRoots` / `execution.cwd` 后可双向直调；`fleet_run` 待审批收件箱 UI。
+
+## 复现要点
+
+- 邀请里的 endpoints 由 `networkInterfaces()` 的非回环 IPv4 + 当前 direct port 组成；direct 端口每次插件重载会变，重载后需重新生成邀请或手动 `fleet_connect`。
+- 同一账号指纹：邀请携带 `accountFingerprint`；B 登录不同账号会在加载时被标记 mismatch 并拒绝连接。

package/docs/notes/remote-tests-2026-11-09.md

@@ -0,0 +1,33 @@
+# 跨设备调用实测（2026-11-09，dev.6）
+
+环境：A `desktop` / `50fdaf90-…`（端口固定 60580）；B `laptop` / `c2d42572-…`（dev.6，同一热点）。
+测试文件：A `E:\Dsh_test\hello-from-A.txt`；B `E:\Dsh_test\hello-from-B.txt`。
+
+## 结果
+
+| # | 调用 | 结果 | 耗时 |
+|---|---|---|---|
+| 1 | `fleet_read(B, E:/Dsh_test/hello-from-B.txt)` | ✅ 返回 `hello from device B` | 48ms |
+| 2 | `fleet_call(B, tool="read", {file_path:…hello-from-B.txt})` | ✅ 返回同一内容（原始工具直调） | 4ms |
+| 3 | `fleet_fetch(B, hello-from-B.txt)` | ✅ 返回文本 | 1ms |
+| 4 | `fleet_run(B, "echo hello-from-B")` | ⚠️ `approval_denied`（B 策略 run=ask，审批 UI 未实现，fail-closed 正确） | 即时 |
+| 5 | `fleet_delegate(B, "读取 hello-from-B.txt 并原样返回")` | ✅ B 的 agent（spawn 子会话 `1a768f89…`）读文件并回传最终文本 | 2.7s |
+| 6 | `fleet_delegate(B, "用 fleet_read 读 A 的 hello-from-A.txt 并原样返回")` | ✅ B 的 agent 反向调用 A 的 `read`，回传 `hello from device A (fleet test)`（子会话 `515f8c1b…`） | 2.5s |
+
+## 结论
+
+- v1 直连 + 端到端加密 + 配对/roster 固定公钥：**通过**；
+- 直调（typed 快捷工具 / `fleet_call` 原始工具 / fetch）：**通过**；
+- Tool Policy 与 fail-closed 审批：**按设计生效**；
+- 跨设备委派（B 的 agent 在本机执行并回传；B 的 agent 反向调 A 工具）：**通过**；
+- 遗留：审批收件箱 UI（`run`/`delegate` 的 `ask` 档目前只能拒绝或配置 auto）；Room/Room Board/设备页 UI 未开始；委派返回文本里 `[reasoning]` 是结果里的 reasoning block 展示，可后续过滤。
+
+## 复现命令（A 侧）
+
+```
+fleet_list()
+fleet_read(device="c2d42572-…", path="E:/Dsh_test/hello-from-B.txt")
+fleet_call(device="c2d42572-…", tool="read", parameters={file_path:"E:/Dsh_test/hello-from-B.txt"})
+fleet_delegate(device="c2d42572-…", task="读取 E:/Dsh_test/hello-from-B.txt 并原样返回")
+fleet_delegate(device="c2d42572-…", task="用 fleet_read 读设备 50fdaf90-… 的 E:/Dsh_test/hello-from-A.txt 并原样返回")
+```

package/docs/notes/room-logic-phase.md

@@ -0,0 +1,31 @@
+# Room 逻辑层实测（2026-11-09，dev.8，单机模拟参与者）
+
+在当前这台 DSH 内，用两个**真实本地 session/agent** 充当 Room 参与者，验证寻址唤醒与看板串行交接，不依赖第二台设备。
+
+## 流程与结果
+
+1. `room_create` → roomId = 当前会话 `session-269260c9-…`，host 成员 `host:session-269260c9-…`。
+2. `room_add_local(name="worker-a", cwd=E:/Dsh_test)` → 真实 session `session-d063026e-…`。
+3. `room_send(to=[worker-a], text="读取 hello-from-A.txt 并用 room_send 回复 host")` → `woke worker-a`；
+   - worker-a 的 agent 真实跑了一轮模型 + 本机 `read`，并在 3.4s 内调用 `room_send` 回传 `hello from device A (fleet test)`；
+   - transcript 两条消息，完整可见。
+4. `room_add_local(name="worker-b")`；看板：
+   - taskA `读取 hello-from-A.txt` owner=worker-a；
+   - taskB `汇总读取结果` owner=worker-b，`dependsOn=[taskA]`；
+   - taskC `并行：独立检查` owner=worker-a，无依赖。
+5. `room_task_update(taskA, done)` → 返回 `handed off to worker-b`；worker-b 被点名唤醒，30s 内完成汇总并 `room_send` 给 host（内容含前序结果、交叉校验、并行任务仍 pending 的说明），同时把自己 taskB 置为 running。
+6. `room_task_list`：taskA done、taskB running、taskC pending（并行任务未被串行交接影响）。
+7. `room_close`。
+
+## 结论
+
+- Room 生命周期、成员管理、寻址消息、未点名不唤醒、host 权威日志：单机逻辑通过；
+- Room Board `dependsOn` 串行交接 / 并行任务不阻塞：真实 agent 验证通过；
+- 参与者使用的都是真实 DSH agent（各自 session），不是 mock。
+
+## 限制（下一步）
+
+- 远程参与者传输（把 local participant 换成远端设备成员）尚未接入；
+- Client 面板/房间视图未做（用户无法在 GUI 直接看 room 时间线/看板）；
+- 房间状态在插件内存 + host session 事件里，插件重载后需要 rehydrate（未实现）；
+- 房间策略仅存储，尚未强制（invite/join/maxMembers 中 maxMembers 已生效）。

package/docs/notes/step1-host-plugin-and-direct-call.md

@@ -0,0 +1,57 @@
+# Step 1：Host 插件接入 + 直调 MVP（实现说明）
+
+状态：**代码完成、单元测试通过（net 8/8 + host 6/6），尚未在真实 DSH 进程内安装联调**。
+
+## 本轮落地
+
+| 文件 | 内容 |
+|---|---|
+| `src/plugin/index.js` | Cordis Host 插件入口：`name`/`inject`/`Config`/`apply`；加载持久状态、启动 FleetNode、注册 6 个 `fleet_*` 工具、常驻提示 section、首次使用手册、编排钩子一行提示、账号指纹绑定、退出清理 |
+| `src/host/store.js` | `$DSH_HOME/device-fleet/` 下的身份/Fleet/roster/config/enrollment 持久化（原子写）；邀请创建与接受；账号指纹比对 |
+| `src/host/tool-policy.js` | 设备本地 Tool Policy：allowedRoots、read/list/grep/fetch/run/tool 六种能力的 auto/ask/deny、原始工具 allowlist、一次性/TTL 授权 |
+| `src/host/execution-slot.js` | Execution Slot：懒创建隐藏 DSH 会话（`sessionController.create` → `resolveAgent`），用 `ctx.tools.execute` 在该 agent 上下文里执行工具，不跑模型 |
+| `src/host/direct-call.js` | `DirectCallHost`（B 侧：`fleet.ping/info/tools/call`，策略→审批→执行）、`DirectCallClient`（A 侧 RPC 封装与结果渲染） |
+| `src/host/tools.js` | 6 个工具定义：`fleet_list` / `fleet_tools` / `fleet_call` + `fleet_read` / `fleet_fetch` / `fleet_run`（typed 快捷工具走同一 `fleet.call` 路径） |
+| `cordis.patch.yml` | 插件挂载行与安全默认配置 |
+| 网络层 | 握手新增 `pluginVersion` / `dshVersion` / `capabilities` 严格校验（ADR-0024）；新增版本不匹配测试 |
+
+## 配置示例（profile patch / 插件设置页）
+
+```yaml
+- id: device-fleet
+  config:
+    deviceName: desktop
+    discovery: true
+    relay: { host: relay.local, port: 47800, dataPort: 47801 }
+    execution:
+      cwd: D:/work            # Execution Slot 的工作目录
+      agentPreset: standard   # 必须是本机存在的 preset
+      shellTool: pwsh
+    policy:
+      allowedRoots: [D:/work] # 直调只能访问这些根
+      capabilities: { read: auto, list: auto, grep: auto, fetch: auto, run: ask, tool: deny }
+      allowedTools: []
+      approvalTtlMs: 900000
+```
+
+## 已测试
+
+- 网络层 8 个测试：直连 RPC、组播发现、Relay 加密中继、跨 fleet/跨账号/固定公钥/版本不匹配拒绝、Relay 鉴权失败；
+- Host 层 6 个测试：状态持久化与邀请入网、Tool Policy（根目录/能力档位/allowlist/TTL）、Execution Slot 懒创建与结果归一、DirectCallHost 的策略/审批/执行、工具 handler 的列表与快捷路由、客户端渲染；
+- 全部 `src/**/*.js` 通过 `node --check`。
+
+## 未验证 / 已知缺口
+
+1. **未在真实 DSH 进程里加载**：`@deepseek-ai/dsh-tools`/`schemastery`/`dsh-llm` 的 peer 解析、Config schema 校验、`ctx.*` API 细节需要在安装后确认（sandbox 里无法 import profile 依赖）。
+2. **审批收件箱 UI 未实现**：`ask` 档当前 fail-closed（`autoApproveAsk: true` 仅供开发）；收件箱、TTL 授权、通知属于下一步。
+3. **`fleet_run` 参数尚简单**：目前只传 `command`；cwd/超时/环境变量待补。
+4. **`fleet_fetch` 只返回文本**（≤ 限制内），大文件/二进制与写入 A 侧工作区待做。
+5. **Room / Board / 委派 / UI 未开始**；插件尚未安装到 profile（需要一次 danger-full-access 审批）。
+6. 账号服务不可用时 `accountFingerprint = null`，握手不做账号比对；需要在真实登录态下验证。
+
+## 下一步
+
+1. 安装 bundle 到 `desktop` profile（`plugin_manager install_bundle`，需批准）；
+2. 在真实 DSH 里验证：插件加载、6 个工具出现在模型工具表、`fleet_list` 正常；
+3. 用第二台设备（或第二个 DSH_HOME/实例）完成一次"fleet_read 读对端文件 + fleet_run 跑命令（带 B 侧审批）"的端到端联调；
+4. 再进入 Room / Board / 委派与审批 UI。

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "dsh-device-fleet",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0-dev.10",
+  "description": "DeepSeek Harness device fleet: enroll devices, direct-call remote tools, shared Rooms with lazy-woken agents, and delegated subagents across devices.",
+  "type": "module",
+  "main": "src/plugin/index.js",
+  "exports": {
+    ".": "./src/plugin/index.js",
+    "./client": "./client.js",
+    "./net": "./src/net/index.js",
+    "./host": "./src/host/index.js",
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "~4.1.0",
+    "@deepseek-ai/dsh-tools": "^0.2.2-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.2.2-rc.1",
+    "@deepseek-ai/schemastery": "~3.19.0"
+  },
+  "scripts": {
+    "test": "node test/net.test.mjs && node test/host.test.mjs",
+    "test:net": "node test/net.test.mjs",
+    "test:host": "node test/host.test.mjs"
+  },
+  "files": [
+    "src",
+    "client.js",
+    "cordis.patch.yml",
+    "README.md",
+    "CONTEXT.md",
+    "docs",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "dev"
+  },
+  "license": "MIT"
 }

package/src/host/approval-inbox.js

@@ -0,0 +1,135 @@
+// Local approval inbox (ADR-0020): a target device asks its own user before a
+// remote call/delegation with the `ask` policy can run. v1 has no client UI yet;
+// the inbox is exposed through `fleet_approvals` / `fleet_approve` /
+// `fleet_deny` and can be exercised with `fleet_simulate_request` while the
+// client panel is still missing.
+import { EventEmitter } from 'node:events'
+import { randomUUID } from 'node:crypto'
+
+export const APPROVAL_SCOPES = ['once', 'ttl']
+
+const SUMMARY_ARG_LENGTH = 160
+
+function summarizeArgs(args) {
+  try {
+    const text = JSON.stringify(args ?? {})
+    return text.length > SUMMARY_ARG_LENGTH ? `${text.slice(0, SUMMARY_ARG_LENGTH)}…` : text
+  } catch {
+    return '[unserializable arguments]'
+  }
+}
+
+export class ApprovalInbox extends EventEmitter {
+  constructor({ ttlMs = 60_000, maxPending = 50, now = Date.now } = {}) {
+    super()
+    this.ttlMs = ttlMs
+    this.maxPending = maxPending
+    this.now = now
+    this.closed = false
+    /** @type {Map<string, any>} */
+    this.pending = new Map()
+  }
+
+  /**
+   * Ask the local user. Resolves `{ approved, scope?, reason? }` when approved,
+   * denied, expired or closed.
+   */
+  request(request) {
+    if (this.closed) return Promise.resolve({ approved: false, reason: 'inbox-closed' })
+    if (this.pending.size >= this.maxPending) {
+      return Promise.resolve({ approved: false, reason: 'inbox-full' })
+    }
+    const id = randomUUID()
+    const createdAt = this.now()
+    const entry = {
+      id,
+      fromDeviceId: request.fromDeviceId ?? 'unknown',
+      capability: request.capability ?? 'tool',
+      tool: request.tool ?? null,
+      reason: request.reason ?? '',
+      argsSummary: summarizeArgs(request.args),
+      createdAt,
+      expiresAt: createdAt + this.ttlMs,
+      status: 'pending',
+    }
+    entry.promise = new Promise((resolve) => {
+      entry.resolve = resolve
+    })
+    entry.timer = setTimeout(() => this.expire(id), this.ttlMs)
+    entry.timer.unref?.()
+    this.pending.set(id, entry)
+    this.emit('request', this.summary(entry))
+    return entry.promise
+  }
+
+  summary(entry) {
+    return {
+      id: entry.id,
+      fromDeviceId: entry.fromDeviceId,
+      capability: entry.capability,
+      tool: entry.tool,
+      reason: entry.reason,
+      argsSummary: entry.argsSummary,
+      createdAt: entry.createdAt,
+      expiresAt: entry.expiresAt,
+      expiresInMs: Math.max(0, entry.expiresAt - this.now()),
+      status: entry.status,
+    }
+  }
+
+  list() {
+    return [...this.pending.values()]
+      .filter((entry) => entry.status === 'pending')
+      .sort((a, b) => a.createdAt - b.createdAt)
+      .map((entry) => this.summary(entry))
+  }
+
+  approve(id, { scope = 'once' } = {}) {
+    const entry = this.settle(id, 'approved')
+    if (!entry) throw Object.assign(new Error(`unknown approval request: ${String(id)}`), { code: 'unknown-request' })
+    const chosen = APPROVAL_SCOPES.includes(scope) ? scope : 'once'
+    entry.resolve({ approved: true, scope: chosen })
+    this.emit('approved', { ...this.summary(entry), scope: chosen })
+    return { ...this.summary(entry), scope: chosen }
+  }
+
+  deny(id, reason = 'denied by local user') {
+    const entry = this.settle(id, 'denied')
+    if (!entry) throw Object.assign(new Error(`unknown approval request: ${String(id)}`), { code: 'unknown-request' })
+    entry.resolve({ approved: false, reason })
+    this.emit('denied', { ...this.summary(entry), reason })
+    return { ...this.summary(entry), reason }
+  }
+
+  expire(id) {
+    const entry = this.pending.get(id)
+    if (!entry || entry.status !== 'pending') return
+    entry.status = 'expired'
+    this.pending.delete(id)
+    clearTimeout(entry.timer)
+    entry.resolve({ approved: false, reason: 'approval-timeout' })
+    this.emit('expired', this.summary(entry))
+  }
+
+  settle(id, status) {
+    const entry = this.pending.get(id)
+    if (!entry || entry.status !== 'pending') return undefined
+    entry.status = status
+    this.pending.delete(id)
+    clearTimeout(entry.timer)
+    return entry
+  }
+
+  /** Close the inbox: every pending request fails closed. */
+  close() {
+    if (this.closed) return
+    this.closed = true
+    for (const entry of this.pending.values()) {
+      clearTimeout(entry.timer)
+      entry.status = 'closed'
+      entry.resolve({ approved: false, reason: 'inbox-closed' })
+    }
+    this.pending.clear()
+    this.emit('closed')
+  }
+}

package/src/host/approval-web.js

@@ -0,0 +1,95 @@
+// Local approval HTTP surface for the approval panel (dev.9). The page is
+// served by the DSH web carrier, so browser fetch carries the session cookie.
+// All decisions go through ApprovalInbox; nothing here bypasses Tool Policy.
+const MAX_BODY_BYTES = 64 * 1024
+
+function json(res, status, value) {
+  const text = JSON.stringify(value)
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(text)
+}
+
+async function readJsonBody(req) {
+  const chunks = []
+  let size = 0
+  for await (const chunk of req) {
+    size += chunk.length
+    if (size > MAX_BODY_BYTES) throw Object.assign(new Error('request body is too large'), { code: 'body-too-large' })
+    chunks.push(chunk)
+  }
+  if (chunks.length === 0) return {}
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString('utf8'))
+  } catch {
+    throw Object.assign(new Error('request body must be JSON'), { code: 'bad-json' })
+  }
+}
+
+/** HTTP-free decision helper shared by the routes and unit tests. */
+export function createApprovalApi({ inbox }) {
+  return {
+    list() {
+      return { approvals: inbox.list() }
+    },
+    decide(body = {}) {
+      const { id, action } = body
+      if (typeof id !== 'string' || id === '') {
+        throw Object.assign(new Error('id is required'), { code: 'bad-request' })
+      }
+      if (action === 'approve') {
+        const scope = body.scope === 'ttl' ? 'ttl' : 'once'
+        return { ok: true, result: inbox.approve(id, { scope }) }
+      }
+      if (action === 'deny') {
+        return { ok: true, result: inbox.deny(id, typeof body.reason === 'string' ? body.reason : 'denied by local user') }
+      }
+      throw Object.assign(new Error('action must be approve or deny'), { code: 'bad-request' })
+    },
+  }
+}
+
+/**
+ * Register the approval routes on the DSH web carrier.
+ * @returns {() => void} disposer
+ */
+export function registerApprovalRoutes({ webServer, inbox, logger = null }) {
+  if (!webServer?.register || !inbox) return () => {}
+  const api = createApprovalApi({ inbox })
+  const disposers = []
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/device-fleet/approvals',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return json(res, 405, { error: 'method not allowed' })
+        try {
+          json(res, 200, api.list())
+        } catch (error) {
+          logger?.warn?.(`[device-fleet] approval list failed: ${String(error?.message ?? error)}`)
+          json(res, 500, { error: 'internal error' })
+        }
+      },
+    }),
+  )
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/device-fleet/approvals/decide',
+      handler: async (req, res) => {
+        if (req.method !== 'POST') return json(res, 405, { error: 'method not allowed' })
+        try {
+          const body = await readJsonBody(req)
+          json(res, 200, api.decide(body))
+        } catch (error) {
+          const status = ['bad-request', 'bad-json', 'body-too-large', 'unknown-request'].includes(error?.code) ? 400 : 500
+          json(res, status, { error: String(error?.message ?? error), code: error?.code ?? 'error' })
+        }
+      },
+    }),
+  )
+  return () => {
+    for (const dispose of disposers) dispose()
+  }
+}

package/src/host/delegation.js

@@ -0,0 +1,127 @@
+// Cross-device delegation (ADR-0015): the caller asks the target device's
+// agent to do a one-shot task and gets the final assistant output back.
+//
+// On the target device this runs through the official SubagentProvider
+// contract with `delivery: 'caller'`, so the child agent's own model turn and
+// tools run on that device, and the `result` promise resolves with the final
+// content blocks. No Room, no shared history: delegation is a one-shot task.
+const DEFAULT_DELEGATE_TIMEOUT_MS = 180_000
+const DEFAULT_PROVIDER = 'spawn'
+const DEFAULT_LABEL = 'fleet delegation'
+
+function textOf(result) {
+  const blocks = Array.isArray(result?.output) ? result.output : []
+  return blocks
+    .map((block) => (block?.type === 'text' ? block.text : `[${String(block?.type ?? 'block')}]`))
+    .join('\n')
+    .trim()
+}
+
+function withTimeout(promise, timeoutMs, onTimeout) {
+  let timer
+  return Promise.race([
+    promise.finally(() => clearTimeout(timer)),
+    new Promise((_, reject) => {
+      timer = setTimeout(() => reject(onTimeout()), timeoutMs)
+      timer.unref?.()
+    }),
+  ])
+}
+
+export class DelegationHost {
+  /**
+   * @param {object} options
+   * @param {object} options.subagents ctx.subagents service
+   * @param {object} options.slot ExecutionSlot
+   * @param {import('./tool-policy.js').ToolPolicy} options.policy
+   * @param {(request: object) => Promise<boolean>} [options.requestApproval]
+   * @param {string} [options.deviceId]
+   * @param {string} [options.defaultCwd]
+   * @param {string} [options.defaultAgentPreset]
+   * @param {string} [options.provider]
+   * @param {number} [options.timeoutMs]
+   */
+  constructor({
+    subagents,
+    slot,
+    policy,
+    requestApproval,
+    deviceId,
+    defaultCwd,
+    defaultAgentPreset,
+    provider = DEFAULT_PROVIDER,
+    timeoutMs = DEFAULT_DELEGATE_TIMEOUT_MS,
+  }) {
+    this.subagents = subagents
+    this.slot = slot
+    this.policy = policy
+    this.requestApproval = requestApproval
+    this.deviceId = deviceId
+    this.defaultCwd = defaultCwd
+    this.defaultAgentPreset = defaultAgentPreset
+    this.provider = provider
+    this.timeoutMs = timeoutMs
+  }
+
+  async delegate({ fromDeviceId, request = {} }) {
+    const task = typeof request.task === 'string' ? request.task.trim() : ''
+    if (task === '') throw Object.assign(new Error('delegate needs a non-empty task'), { code: 'bad-request' })
+
+    const decision = this.policy.decide({ capability: 'delegate', args: {} })
+    if (decision.decision === 'deny') {
+      throw Object.assign(new Error(decision.reason), { code: 'denied', data: { capability: 'delegate' } })
+    }
+    if (decision.decision === 'ask') {
+      const outcome =
+        typeof this.requestApproval === 'function'
+          ? await this.requestApproval({ fromDeviceId, capability: 'delegate', tool: 'delegate', args: { task }, reason: decision.reason })
+          : { approved: false, reason: 'no approval channel' }
+      const approved = outcome === true || outcome?.approved === true
+      if (!approved) {
+        throw Object.assign(new Error(outcome?.reason ?? 'local approval was not granted'), { code: 'approval_denied' })
+      }
+      this.policy.grant(decision.key, { scope: outcome?.scope === 'ttl' ? 'ttl' : 'once' })
+    }
+
+    const agent = await this.slot.ensureAgent()
+    const controller = new AbortController()
+    const startedAt = Date.now()
+    let activation
+    try {
+      activation = await this.subagents.startActivation({
+        provider: request.provider ?? this.provider,
+        label: typeof request.label === 'string' && request.label !== '' ? request.label : DEFAULT_LABEL,
+        request: {
+          prompt: [{ type: 'text', text: task }],
+          parent: agent,
+          ...(request.cwd ?? this.defaultCwd ? { cwd: request.cwd ?? this.defaultCwd } : {}),
+          ...(request.agentPreset ?? this.defaultAgentPreset
+            ? { agentPreset: request.agentPreset ?? this.defaultAgentPreset }
+            : {}),
+        },
+        signal: controller.signal,
+        delivery: 'caller',
+      })
+      const result = await withTimeout(
+        activation.result,
+        Number.isFinite(request.timeoutMs) ? request.timeoutMs : this.timeoutMs,
+        () => {
+          controller.abort()
+          return Object.assign(new Error('delegation timed out; the child agent was asked to stop'), { code: 'delegate-timeout' })
+        },
+      )
+      return {
+        text: textOf(result) || '(delegated agent returned no text)',
+        stopReason: result?.stopReason ?? null,
+        childId: activation.childId,
+        durationMs: Date.now() - startedAt,
+      }
+    } finally {
+      try {
+        await activation?.dispose?.()
+      } catch {
+        /* best effort */
+      }
+    }
+  }
+}