dsh-device-fleet 0.1.0-dev.7 → 0.1.0-dev.9

package/README.md

@@ -7,7 +7,9 @@ DeepSeek Harness 的设备联邦插件：把登录同一账号、且都安装本
 - ✅ **网络层 v1**：设备身份、邀请、端到端加密安全通道、直连（手动地址）、UDP 组播发现
 - ✅ **网络层 v2**：自建 Relay（fleetKey 鉴权的信令 + TCP 拼接数据面，不做 NAT 打洞）
 - ✅ **Host 插件 + 直调 MVP（代码完成、单测通过，待真实 DSH 安装联调）**：`fleet_list` / `fleet_tools` / `fleet_call` + `fleet_read` / `fleet_fetch` / `fleet_run`、Tool Policy、Execution Slot、审批 fail-closed
-- ⏳ Room / Room Board、委派、审批收件箱 UI、设备页/配对/房间 UI（下一步）
+- ✅ **审批收件箱逻辑层（dev.7）**：`fleet_approvals` / `fleet_approve` / `fleet_deny`，ask 档排队、超时 fail-closed、once/ttl 授权、`fleet_simulate_request` 本机演练；Client 审批面板待做
+- ✅ **Room 逻辑层（dev.8，单机模拟）**：`room_create` / `room_add_local` / `room_send` / `room_messages` / `room_status` / `room_task_*` / `room_close`；本地真实 agent 参与者、寻址唤醒、Room Board 串行交接；单机仿真验证通过
+- ⏳ Client 审批面板 / 房间视图、远程参与者传输、插件重载 rehydrate（下一步）
 
 ## 安装（开发版）
 

package/client.js

@@ -0,0 +1,167 @@
+// Fleet approval panel (Client half).
+// A floating button under shell.overlay polls the Host route registered by
+// src/host/approval-web.js. Decisions go through ApprovalInbox on the Host.
+window.__ModuleLoader__.load({
+  id: 'dsh-device-fleet',
+  factory(require) {
+    const React = require('react');
+    const h = React.createElement;
+    const { useEffect, useState } = React;
+
+    const POLL_MS = 2500;
+    const panelStyle = {
+      position: 'fixed',
+      right: 16,
+      bottom: 72,
+      width: 360,
+      maxHeight: '65vh',
+      overflow: 'auto',
+      zIndex: 900,
+      background: 'var(--dsw-alias-surface-raised, #1f1f1f)',
+      color: 'var(--dsw-alias-text, #e8e8e8)',
+      border: '1px solid var(--dsw-alias-border, #3a3a3a)',
+      borderRadius: 10,
+      boxShadow: '0 12px 32px rgba(0,0,0,.35)',
+      padding: 12,
+      font: '13px/1.5 system-ui, -apple-system, "Segoe UI", sans-serif',
+    };
+    const buttonStyle = {
+      position: 'fixed',
+      right: 16,
+      bottom: 16,
+      zIndex: 900,
+      display: 'flex',
+      alignItems: 'center',
+      gap: 8,
+      padding: '8px 12px',
+      borderRadius: 999,
+      border: '1px solid var(--dsw-alias-border, #3a3a3a)',
+      background: 'var(--dsw-alias-surface-raised, #1f1f1f)',
+      color: 'var(--dsw-alias-text, #e8e8e8)',
+      cursor: 'pointer',
+      boxShadow: '0 6px 18px rgba(0,0,0,.3)',
+      font: '13px system-ui, -apple-system, "Segoe UI", sans-serif',
+    };
+
+    function ActionButton({ children, onClick, tone = 'normal', disabled = false }) {
+      const colors = {
+        normal: { bg: 'var(--dsw-alias-surface, transparent)', border: 'var(--dsw-alias-border, #3a3a3a)' },
+        allow: { bg: 'var(--dsw-alias-accent, #2f6fed)', border: 'var(--dsw-alias-accent, #2f6fed)' },
+        deny: { bg: 'transparent', border: 'var(--dsw-alias-border, #3a3a3a)' },
+      };
+      const theme = colors[tone] ?? colors.normal;
+      return h(
+        'button',
+        {
+          type: 'button',
+          disabled,
+          onClick,
+          style: {
+            padding: '3px 9px',
+            borderRadius: 6,
+            border: '1px solid ' + theme.border,
+            background: theme.bg,
+            color: 'var(--dsw-alias-text, #e8e8e8)',
+            cursor: disabled ? 'default' : 'pointer',
+            opacity: disabled ? 0.55 : 1,
+            fontSize: 12,
+          },
+        },
+        children,
+      );
+    }
+
+    function ApprovalPanel() {
+      const [items, setItems] = useState([]);
+      const [open, setOpen] = useState(false);
+      const [busy, setBusy] = useState({});
+
+      useEffect(() => {
+        let disposed = false;
+        let timer;
+        const poll = async () => {
+          try {
+            const response = await fetch('/device-fleet/approvals', { headers: { accept: 'application/json' } });
+            if (!response.ok) throw new Error('HTTP ' + response.status);
+            const data = await response.json();
+            if (!disposed) setItems(Array.isArray(data.approvals) ? data.approvals : []);
+          } catch {
+            if (!disposed) setItems([]);
+          }
+          if (!disposed) timer = setTimeout(poll, POLL_MS);
+        };
+        poll();
+        return () => {
+          disposed = true;
+          clearTimeout(timer);
+        };
+      }, []);
+
+      const decide = async (id, action, scope) => {
+        setBusy((current) => ({ ...current, [id]: true }));
+        try {
+          const response = await fetch('/device-fleet/approvals/decide', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ id, action, ...(scope ? { scope } : {}) }),
+          });
+          if (response.ok) setItems((current) => current.filter((item) => item.id !== id));
+        } finally {
+          setBusy((current) => ({ ...current, [id]: false }));
+        }
+      };
+
+      const label = items.length > 0 ? 'Fleet 审批 (' + items.length + ')' : 'Fleet 审批';
+      return h(
+        'div',
+        null,
+        open
+          ? h(
+              'div',
+              { style: panelStyle, role: 'dialog', 'aria-label': 'Fleet 待审批请求' },
+              h(
+                'div',
+                { style: { display: 'flex', justifyContent: 'space-between', alignItems: 'center', marginBottom: 8 } },
+                h('strong', null, '待审批请求'),
+                h('button', { type: 'button', onClick: () => setOpen(false), style: { ...buttonStyle, position: 'static', boxShadow: 'none', padding: '3px 9px', fontSize: 12 } }, '收起'),
+              ),
+              items.length === 0
+                ? h('div', { style: { opacity: 0.7 } }, '暂无待审批请求')
+                : items.map((item) =>
+                    h(
+                      'div',
+                      { key: item.id, style: { borderTop: '1px solid var(--dsw-alias-border, #333)', padding: '8px 0' } },
+                      h('div', { style: { fontWeight: 600 } }, (item.capability || 'tool') + (item.tool ? ' / ' + item.tool : '')),
+                      h('div', { style: { opacity: 0.75, fontSize: 12 } }, '来自 ' + item.fromDeviceId + ' · ' + Math.max(0, Math.round(item.expiresInMs / 1000)) + 's 后超时'),
+                      item.reason ? h('div', { style: { opacity: 0.75, fontSize: 12, marginTop: 2 } }, item.reason) : null,
+                      h('div', { style: { fontFamily: 'ui-monospace, monospace', fontSize: 11, margin: '4px 0', opacity: 0.8, wordBreak: 'break-all' } }, item.argsSummary),
+                      h(
+                        'div',
+                        { style: { display: 'flex', gap: 6, marginTop: 4 } },
+                        h(ActionButton, { tone: 'allow', onClick: () => decide(item.id, 'approve') }, busy[item.id] ? '处理中…' : '允许一次'),
+                        h(ActionButton, { tone: 'allow', onClick: () => decide(item.id, 'approve', 'ttl') }, '允许 15 分钟'),
+                        h(ActionButton, { tone: 'deny', onClick: () => decide(item.id, 'deny') }, '拒绝'),
+                      ),
+                    ),
+                  ),
+            )
+          : null,
+        h(
+          'button',
+          { type: 'button', style: { ...buttonStyle, borderColor: items.length > 0 ? 'var(--dsw-alias-accent, #2f6fed)' : undefined }, onClick: () => setOpen((value) => !value) },
+          h('span', { 'aria-hidden': true }, '🛰️'),
+          h('span', null, label),
+        ),
+      );
+    }
+
+    return {
+      inject: ['slots'],
+      apply(ctx) {
+        ctx.slots.inject('shell.overlay', () =>
+          ctx.slots.register({ name: 'shell.overlay', id: 'fleet-approvals', order: 10 }, ApprovalPanel),
+        );
+      },
+    };
+  },
+});

package/docs/notes/approval-inbox-phase.md

@@ -0,0 +1,31 @@
+# 审批收件箱（逻辑层，dev.7）
+
+## 实现
+
+- `src/host/approval-inbox.js`：`ApprovalInbox`
+  - `request()`：排队、60s（可配）超时 fail-closed、事件 `request/approved/denied/expired/closed`；
+  - `list()`：待审列表（来源设备、能力、工具、参数摘要、剩余时间）；
+  - `approve(id, {scope})`：`once` / `ttl`（TTL 由 Tool Policy 的 `approvalTtlMs` 控制）；
+  - `deny(id, reason)`；`close()` 时全部失败关闭。
+- `DirectCallHost` / `DelegationHost` 的 `ask` 档改为等待收件箱结果（不再一律拒绝），批准后按 scope 写入 Tool Policy 授权。
+- 新工具：`fleet_approvals` / `fleet_approve` / `fleet_deny`；`fleet_simulate_request`（仅 `approvals.simulation: true`）用于本机无第二台设备时演练。
+- 配置：`approvals: {ttlMs, maxPending, simulation}`。
+
+## 已验证
+
+单元测试（`node test/host.test.mjs`，10/10）：
+- 收件箱排队/批准/拒绝/超时/关闭/上限；
+- DirectCallHost 在 `run=ask` 时阻塞等待收件箱批准后才执行；
+- 工具 handler 的列表/批准/拒绝/模拟。
+
+当前 DSH 环境内模拟（dev.7，无需第二台设备）：
+1. `fleet_simulate_request` 创建一条 `run/pwsh` 请求，`fleet_approvals` 显示 `58328ms left`；
+2. `fleet_approve(id, scope="ttl")` → `approved … (ttl)`，再次 `fleet_approvals` 为 `(no pending approvals)`；
+3. 再模拟一条 `delegate` 请求，`fleet_deny` → `denied …`；
+4. 对不存在的 id 调 `fleet_approve` → `Error: [unknown-request]`。
+
+## 未完成
+
+- **Client UI 审批面板/通知**（需 Client bundle）：当前只能通过工具或后续 UI 应答；Host 侧已发出 `request/approved/denied/expired` 事件，面板可直接消费；
+- `room` 级授权 scope（需 Room 概念落地后再加）；
+- 审批结果持久化审计日志（后续与 Room 事件一起做）。

package/docs/notes/dev-release.md

@@ -39,9 +39,23 @@ dsh plugin --profile desktop add dsh-device-fleet@dev
 - 邀请里新增 `endpoints`（创建者的局域网/热点 IPv4 + direct 端口），加入方重启后自动向这些地址回连，绕开组播发现失败；
 - 新增 `fleet_status`（deviceId/直连端口/发现/连接/roster/hints）与 `fleet_connect(host, port)`（手动直连，成功后会从握手学到对端 deviceId）；
 - `fleet_list` 仍是本地视图；配对成功后双方 roster 会自动固定对端公钥。
-## 0.1.0-dev.6（稳定化）
+## 0.1.0-dev.8（稳定化）
 
 - 直连端口可固定（profile `direct.port`），插件重载不再换端口；
 - 连接断开后自动重试已知地址（不再只在启动时试一次）；
 - `fleet_connect` 手动地址会持久化到 `peer-hints.json`，重启后继续回连；
-- 新增 `fleet_delegate`（dev.5）：目标设备用 `SubagentProvider` + `delivery:'caller'` 跑 agent 并返回最终结果。
+- 新增 `fleet_delegate`（dev.5）：目标设备用 `SubagentProvider` + `delivery:'caller'` 跑 agent 并返回最终结果。
+## 0.1.0-dev.8（审批收件箱，逻辑层）
+
+- 新增 `ApprovalInbox`：ask 档请求排队、超时 fail-closed、approve（once/ttl）/deny、关闭时全部失败关闭；
+- 直调与委派的 ask 档改为等待本机收件箱结果（不再一律拒绝）；
+- 新工具：`fleet_approvals` / `fleet_approve` / `fleet_deny`；`fleet_simulate_request`（仅 `approvals.simulation: true`）用于本机无第二台设备时演练流程；
+- 审批面板（Client UI）与通知尚未实现，当前通过工具/后续 UI 应答。
+## 0.1.0-dev.8（Room 逻辑层，本机模拟）
+
+- `RoomService`：当前会话升级为 Room Host；本地模拟参与者（真实 DSH session/agent）；
+- 寻址消息：`room_send` 只唤醒被点名成员，Host 会话写权威 `room/message` 事件；
+- 可见性：`room_messages` 提供完整 transcript；未点名成员不运行；
+- Room Board：`room_task_add/update/list`，`dependsOn` 串行交接（前置完成时唤醒下一个 owner），无依赖任务并行不受影响；
+- 工具：`room_create / room_add_local / room_remove_member / room_send / room_messages / room_status / room_task_* / room_close`；
+- 远程参与者传输与 Client UI 未做（下一步）。

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/package.json

@@ -1,11 +1,12 @@
 {
   "name": "dsh-device-fleet",
-  "version": "0.1.0-dev.7",
+  "version": "0.1.0-dev.9",
   "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"
@@ -16,6 +17,13 @@
   "dsh": {
     "bundle": {
       "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime"
+      ]
     }
   },
   "peerDependencies": {
@@ -31,6 +39,7 @@
   },
   "files": [
     "src",
+    "client.js",
     "cordis.patch.yml",
     "README.md",
     "CONTEXT.md",

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/index.js

@@ -4,4 +4,7 @@ export * from './tool-policy.js'
 export * from './execution-slot.js'
 export * from './direct-call.js'
 export * from './delegation.js'
+export * from './approval-inbox.js'
+export * from './approval-web.js'
+export * from './room-service.js'
 export * from './tools.js'

package/src/host/room-service.js

@@ -0,0 +1,324 @@
+// Room logic layer (ADR-0002/0005/0006/0011/0021), with local participants for
+// simulation inside one DSH. The Host session log carries the authoritative
+// room events; participant agents are real local DSH sessions woken with an
+// addressed message, so addressing/wake/visibility and board handoff can be
+// exercised before the remote transport and the client UI exist.
+import { randomUUID } from 'node:crypto'
+
+const MAX_MESSAGE_CHARS = 20_000
+
+const DEFAULT_POLICY = Object.freeze({
+  invite: 'members',
+  join: 'auto',
+  maxMembers: 8,
+  boardWrite: 'members',
+  remove: 'members',
+})
+
+function hostMemberId(sessionId) {
+  return `host:${sessionId}`
+}
+
+function localMemberId(sessionId) {
+  return `local:${sessionId}`
+}
+
+export class RoomService {
+  /**
+   * @param {object} options
+   * @param {object} options.sessionController ctx.sessionController
+   * @param {(input: object) => object} [options.createUserMessage] dsh-llm helper
+   * @param {(now?: number) => number} [options.now]
+   */
+  constructor({ sessionController, createUserMessage = null, now = Date.now } = {}) {
+    this.sessionController = sessionController
+    this.createUserMessage = createUserMessage
+    this.now = now
+    /** @type {Map<string, any>} */
+    this.rooms = new Map()
+  }
+
+  async upgradeHost({ agent, policy = {} } = {}) {
+    if (!agent?.session?.id) throw Object.assign(new Error('room upgrade needs the calling agent session'), { code: 'bad-request' })
+    const sessionId = agent.session.id
+    const existing = this.rooms.get(sessionId)
+    if (existing) return this.summary(existing)
+    const memberId = hostMemberId(sessionId)
+    const room = {
+      roomId: sessionId,
+      createdAt: this.now(),
+      hostSessionId: sessionId,
+      policy: { ...DEFAULT_POLICY, ...policy },
+      members: new Map(),
+      messages: [],
+      tasks: new Map(),
+      closed: false,
+    }
+    room.members.set(memberId, {
+      memberId,
+      role: 'host',
+      kind: 'local',
+      sessionId,
+      name: agent.session.header?.title ?? 'host',
+      agent,
+    })
+    this.rooms.set(sessionId, room)
+    await this.append(room, 'room/created', { roomId: room.roomId, policy: room.policy, hostMemberId: memberId })
+    return this.summary(room)
+  }
+
+  async addLocalParticipant({ roomId, name = 'worker', agentPreset, cwd } = {}) {
+    const room = this.requireRoom(roomId)
+    if (room.members.size >= room.policy.maxMembers) {
+      throw Object.assign(new Error(`room member limit reached (${room.policy.maxMembers})`), { code: 'room-full' })
+    }
+    if (!this.sessionController?.create) {
+      throw Object.assign(new Error('participant sessions are unavailable'), { code: 'unsupported' })
+    }
+    const created = await this.sessionController.create({
+      ...(cwd ? { cwd } : {}),
+      ...(agentPreset ? { agentPreset } : {}),
+    })
+    const sessionId = created?.sessionId
+    if (!sessionId) throw Object.assign(new Error('could not create the participant session'), { code: 'room-participant-failed' })
+    const resolved = await this.sessionController.resolveAgent(sessionId)
+    if (!resolved?.agent) throw Object.assign(new Error('participant agent could not be resolved'), { code: 'room-participant-failed' })
+    const memberId = localMemberId(sessionId)
+    const member = { memberId, role: 'participant', kind: 'local', sessionId, name, agent: resolved.agent }
+    room.members.set(memberId, member)
+    await this.append(room, 'room/member', {
+      roomId: room.roomId,
+      action: 'added',
+      memberId,
+      role: 'participant',
+      name,
+      sessionId,
+    })
+    return this.memberSummary(member)
+  }
+
+  async removeMember({ roomId, memberId, reason = 'removed' } = {}) {
+    const room = this.requireRoom(roomId)
+    const member = room.members.get(memberId)
+    if (!member) throw Object.assign(new Error(`unknown member: ${String(memberId)}`), { code: 'unknown-member' })
+    if (member.role === 'host') throw Object.assign(new Error('the host cannot be removed; close the room instead'), { code: 'forbidden' })
+    room.members.delete(memberId)
+    await this.append(room, 'room/member', { roomId: room.roomId, action: 'removed', memberId, reason })
+    return { roomId: room.roomId, memberId }
+  }
+
+  /**
+   * Send one addressed message. The Host appends it to the canonical log and
+   * wakes only the addressed local members (never the sender).
+   */
+  async send({ roomId, from, to, text } = {}) {
+    const room = this.requireRoom(roomId)
+    const body = typeof text === 'string' ? text.trim() : ''
+    if (body === '') throw Object.assign(new Error('room message needs text'), { code: 'bad-request' })
+    if (body.length > MAX_MESSAGE_CHARS) throw Object.assign(new Error('room message is too long'), { code: 'bad-request' })
+    const recipients = Array.isArray(to) ? to.filter((id) => typeof id === 'string') : []
+    if (recipients.length === 0) throw Object.assign(new Error('room message needs at least one recipient'), { code: 'bad-request' })
+    for (const memberId of recipients) {
+      if (!room.members.has(memberId)) throw Object.assign(new Error(`unknown member: ${memberId}`), { code: 'unknown-member' })
+    }
+    const sender = this.resolveSender(room, from)
+    const message = {
+      id: randomUUID(),
+      roomId: room.roomId,
+      from: sender,
+      to: recipients,
+      text: body,
+      createdAt: this.now(),
+    }
+    room.messages.push(message)
+    await this.append(room, 'room/message', {
+      roomId: room.roomId,
+      messageId: message.id,
+      from: sender,
+      to: recipients,
+      text: body,
+    })
+    const woken = []
+    for (const memberId of recipients) {
+      if (sender.memberId === memberId) continue
+      const member = room.members.get(memberId)
+      if (await this.wake(room, member, message)) woken.push(memberId)
+    }
+    return { messageId: message.id, to: recipients, woken }
+  }
+
+  resolveSender(room, from) {
+    if (from && typeof from === 'object') {
+      if (typeof from.memberId === 'string') {
+        const member = room.members.get(from.memberId)
+        if (!member) throw Object.assign(new Error(`unknown sender member: ${from.memberId}`), { code: 'unknown-member' })
+        return { kind: 'agent', memberId: member.memberId, name: member.name ?? 'agent' }
+      }
+      if (typeof from.sessionId === 'string') {
+        for (const member of room.members.values()) {
+          if (member.sessionId === from.sessionId) {
+            return { kind: 'agent', memberId: member.memberId, name: member.name ?? 'agent' }
+          }
+        }
+        throw Object.assign(new Error(`sender session is not a room member: ${from.sessionId}`), { code: 'unknown-member' })
+      }
+      if (from.kind === 'user') return { kind: 'user', name: 'user' }
+    }
+    return { kind: 'user', name: 'user' }
+  }
+
+  /** Wake one local participant by injecting the addressed message. */
+  async wake(room, member, message) {
+    if (!member?.agent || typeof member.agent.followup !== 'function' || typeof this.createUserMessage !== 'function') return false
+    const senderLabel = message.from.kind === 'user' ? 'user' : (message.from.name ?? 'agent')
+    const text = [
+      `[Fleet Room ${room.roomId}] ${senderLabel} → you:`,
+      message.text,
+      '',
+      `Reply with room_send (roomId="${room.roomId}", to=["${message.from.memberId ?? 'host'}"]) when you have an answer.`,
+    ].join('\n')
+    const userMessage = this.createUserMessage({ content: [{ type: 'text', text }], source: { kind: 'user' } })
+    try {
+      member.agent.followup(userMessage)
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  async append(room, type, data) {
+    const host = room.members.get(hostMemberId(room.hostSessionId))
+    const session = host?.agent?.session
+    if (session?.append) await session.append(type, data)
+  }
+
+  // --------------------------------------------------------------- room tasks
+
+  async addTask({ roomId, title, owner, dependsOn = [], description = '' } = {}) {
+    const room = this.requireRoom(roomId)
+    if (typeof title !== 'string' || title.trim() === '') throw Object.assign(new Error('task needs a title'), { code: 'bad-request' })
+    const ownerMember = room.members.get(owner)
+    if (!ownerMember) throw Object.assign(new Error(`unknown task owner: ${String(owner)}`), { code: 'unknown-member' })
+    const id = randomUUID()
+    const task = {
+      id,
+      roomId: room.roomId,
+      title: title.trim(),
+      description,
+      owner,
+      status: 'pending',
+      dependsOn: Array.isArray(dependsOn) ? dependsOn : [],
+      readyNotified: false,
+      createdAt: this.now(),
+      updatedAt: this.now(),
+    }
+    room.tasks.set(id, task)
+    await this.append(room, 'room/task', { roomId: room.roomId, action: 'added', task })
+    return task
+  }
+
+  async updateTask({ roomId, id, status, note } = {}) {
+    const room = this.requireRoom(roomId)
+    const task = room.tasks.get(id)
+    if (!task) throw Object.assign(new Error(`unknown task: ${String(id)}`), { code: 'unknown-task' })
+    const allowed = ['pending', 'running', 'done', 'blocked']
+    if (status !== undefined && !allowed.includes(status)) {
+      throw Object.assign(new Error(`invalid task status: ${String(status)}`), { code: 'bad-request' })
+    }
+    if (status !== undefined) task.status = status
+    if (typeof note === 'string' && note !== '') task.note = note
+    task.updatedAt = this.now()
+    await this.append(room, 'room/task', { roomId: room.roomId, action: 'updated', task })
+    let handedOff = []
+    if (status === 'done') handedOff = await this.handOffReady(room)
+    return { task, handedOff }
+  }
+
+  /** Wake owners of pending tasks whose dependencies all completed. */
+  async handOffReady(room) {
+    const ready = []
+    for (const task of room.tasks.values()) {
+      if (task.status !== 'pending' || task.readyNotified) continue
+      if (task.dependsOn.length === 0) continue
+      const depsDone = task.dependsOn.every((dep) => room.tasks.get(dep)?.status === 'done')
+      if (!depsDone) continue
+      task.readyNotified = true
+      task.updatedAt = this.now()
+      const owner = room.members.get(task.owner)
+      const message = {
+        id: randomUUID(),
+        roomId: room.roomId,
+        from: { kind: 'user', name: 'room' },
+        to: [task.owner],
+        text: `任务 "${task.title}" 的前置任务已完成，现在可以开始。`,
+        createdAt: this.now(),
+      }
+      room.messages.push(message)
+      await this.append(room, 'room/message', { roomId: room.roomId, messageId: message.id, from: message.from, to: message.to, text: message.text })
+      const woken = owner ? await this.wake(room, owner, message) : false
+      ready.push({ taskId: task.id, owner: task.owner, woken })
+    }
+    return ready
+  }
+
+  listTasks(roomId) {
+    const room = this.requireRoom(roomId)
+    return [...room.tasks.values()].sort((a, b) => a.createdAt - b.createdAt)
+  }
+
+  // ------------------------------------------------------------------- reads
+
+  messages({ roomId, limit = 50 } = {}) {
+    const room = this.requireRoom(roomId)
+    const items = room.messages.slice(-Math.max(1, Math.min(limit, 200)))
+    return items.map((message) => ({
+      ...message,
+      fromLabel: message.from.kind === 'user' ? 'user' : `${message.from.name ?? 'agent'} (${message.from.memberId ?? '?'})`,
+    }))
+  }
+
+  summary(room) {
+    return {
+      roomId: room.roomId,
+      createdAt: room.createdAt,
+      closed: room.closed,
+      policy: { ...room.policy },
+      members: [...room.members.values()].map((member) => this.memberSummary(member)),
+      messageCount: room.messages.length,
+      tasks: this.listTasks(room.roomId).length,
+    }
+  }
+
+  memberSummary(member) {
+    return {
+      memberId: member.memberId,
+      role: member.role,
+      kind: member.kind,
+      sessionId: member.sessionId,
+      name: member.name,
+    }
+  }
+
+  status(roomId) {
+    return this.summary(this.requireRoom(roomId))
+  }
+
+  /** All open rooms (for cleanup and diagnostics). */
+  openRooms() {
+    return [...this.rooms.keys()]
+  }
+
+  async close({ roomId, reason = 'closed by host' } = {}) {
+    const room = this.requireRoom(roomId)
+    room.closed = true
+    await this.append(room, 'room/closed', { roomId: room.roomId, reason, closedAt: this.now() })
+    this.rooms.delete(room.roomId)
+    return { roomId: room.roomId, closed: true, reason }
+  }
+
+  requireRoom(roomId) {
+    const room = this.rooms.get(roomId)
+    if (!room) throw Object.assign(new Error(`unknown or closed room: ${String(roomId)}`), { code: 'unknown-room' })
+    return room
+  }
+}

package/src/host/tools.js

@@ -28,6 +28,7 @@ export function createFleetHandlers({
   pairing = null,
   onPeerHint = null,
   approvals = null,
+  rooms = null,
 }) {
   return {
     async fleet_approvals() {
@@ -114,6 +115,123 @@ export function createFleetHandlers({
       }
     },
 
+    async room_create(args, exec) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const room = await rooms.upgradeHost({ agent: exec?.agent, policy: args?.policy ?? {} })
+        return {
+          text: [
+            `room created: ${room.roomId}`,
+            `host: ${room.members.find((member) => member.role === 'host')?.memberId ?? '?'}`,
+            'Add participants with room_add_local (simulation) or the remote invite flow later, then room_send.',
+          ].join('\n'),
+        }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_add_local({ roomId, name, agentPreset, cwd }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const member = await rooms.addLocalParticipant({ roomId, name, agentPreset, cwd })
+        return { text: `participant added: ${member.memberId} (${member.name}) session=${member.sessionId}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_remove_member({ roomId, memberId, reason }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const result = await rooms.removeMember({ roomId, memberId, reason })
+        return { text: `member removed: ${result.memberId}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_send({ roomId, to, text }, exec) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const from = { sessionId: exec?.agent?.session?.id }
+        const result = await rooms.send({ roomId, from, to, text })
+        const woken = result.woken.length > 0 ? `, woke ${result.woken.join(', ')}` : ''
+        return { text: `message ${result.messageId} sent to ${result.to.join(', ')}${woken}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_messages({ roomId, limit }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const items = rooms.messages({ roomId, limit })
+        if (items.length === 0) return { text: '(no messages)' }
+        const lines = items.map(
+          (message) => `- [${new Date(message.createdAt).toISOString()}] ${message.fromLabel} → ${message.to.join(', ')}: ${message.text}`,
+        )
+        return { text: lines.join('\n') }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_status({ roomId }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        return { text: JSON.stringify(rooms.status(roomId), null, 2) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_task_add({ roomId, title, owner, dependsOn, description }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const task = await rooms.addTask({ roomId, title, owner, dependsOn: dependsOn ?? [], description: description ?? '' })
+        return { text: `task ${task.id} added for ${task.owner}: ${task.title}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_task_update({ roomId, id, status, note }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const result = await rooms.updateTask({ roomId, id, status, note })
+        const handed = result.handedOff.length > 0 ? `; handed off to ${result.handedOff.map((item) => item.owner).join(', ')}` : ''
+        return { text: `task ${result.task.id} updated (${result.task.status})${handed}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_task_list({ roomId }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        const tasks = rooms.listTasks(roomId)
+        if (tasks.length === 0) return { text: '(no tasks)' }
+        return {
+          text: tasks
+            .map((task) => `- [${task.status}] ${task.title} (${task.id}) owner=${task.owner}${task.dependsOn.length ? ` deps=${task.dependsOn.join(',')}` : ''}`)
+            .join('\n'),
+        }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async room_close({ roomId, reason }) {
+      if (!rooms) return { text: 'Error: [unsupported] rooms are unavailable' }
+      try {
+        await rooms.close({ roomId, reason: reason ?? 'closed by host' })
+        return { text: `room closed: ${roomId}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
     async fleet_list() {
       const lines = []
       lines.push(`this device: ${node.identity.deviceId} (${node.name})`)
@@ -267,6 +385,113 @@ export function createFleetToolDefinitions({ defineTool, handlers }) {
       output,
       execute: (args) => handlers.fleet_simulate_request(args),
     }),
+    defineTool({
+      name: 'room_create',
+      description:
+        'Upgrade the current session into a Room Host (local logic layer) so multiple agents can collaborate with shared messages and a shared task board. Add participants with `room_add_local` (simulation) or the future remote invite flow. Only do this when the user explicitly wants multi-agent collaboration, not for a one-off remote tool call.',
+      parameters: {
+        policy: { type: 'object', additionalProperties: true, description: 'Optional room policy overrides (invite/join/maxMembers/boardWrite/remove).' },
+      },
+      output,
+      execute: (args, exec) => handlers.room_create(args, exec),
+    }),
+    defineTool({
+      name: 'room_add_local',
+      description:
+        'Simulation helper: add a real local DSH agent as a Room participant (its own session). Use it to exercise addressing/wake/board logic in one DSH before the remote participant transport exists.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id returned by room_create.' },
+        name: { type: 'string', description: 'Participant display name.' },
+        agentPreset: { type: 'string', description: 'Optional agent preset id for the participant session.' },
+        cwd: { type: 'string', description: 'Optional working directory for the participant session.' },
+      },
+      output,
+      execute: (args) => handlers.room_add_local(args),
+    }),
+    defineTool({
+      name: 'room_remove_member',
+      description: 'Remove a participant from a Room (the host cannot be removed; close the room instead).',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        memberId: { type: 'string', required: true, description: 'Member id from room_status.' },
+        reason: { type: 'string', description: 'Optional reason recorded in the room log.' },
+      },
+      output,
+      execute: (args) => handlers.room_remove_member(args),
+    }),
+    defineTool({
+      name: 'room_send',
+      description:
+        'Send one addressed Room message as the calling agent. The host appends it to the canonical room log and wakes only the addressed participants; unaddressed members do not run. To say different things to different members, send separate messages.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        to: { type: 'array', items: { type: 'string' }, required: true, description: 'Recipient member ids.' },
+        text: { type: 'string', required: true, description: 'Message body.' },
+      },
+      output,
+      execute: (args, exec) => handlers.room_send(args, exec),
+    }),
+    defineTool({
+      name: 'room_messages',
+      description: 'Read the Room transcript (the user-visible complete conversation, including agent-to-agent messages).',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        limit: { type: 'number', description: 'Maximum recent messages to return (default 50).' },
+      },
+      output,
+      execute: (args) => handlers.room_messages(args),
+    }),
+    defineTool({
+      name: 'room_status',
+      description: 'Show one Room\'s members, policy, message count and task count.',
+      parameters: { roomId: { type: 'string', required: true, description: 'Room id.' } },
+      output,
+      execute: (args) => handlers.room_status(args),
+    }),
+    defineTool({
+      name: 'room_task_add',
+      description:
+        'Add one shared Room Board task. Use dependsOn to express serial handoff: when all dependencies are done, the owner is woken with a "ready" message. Parallel tasks have no dependencies and do not block each other.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        title: { type: 'string', required: true, description: 'Task title.' },
+        owner: { type: 'string', required: true, description: 'Owner member id.' },
+        dependsOn: { type: 'array', items: { type: 'string' }, description: 'Task ids that must complete first.' },
+        description: { type: 'string', description: 'Optional task detail.' },
+      },
+      output,
+      execute: (args) => handlers.room_task_add(args),
+    }),
+    defineTool({
+      name: 'room_task_update',
+      description:
+        'Update one Room Board task. Marking it done triggers serial handoff: owners of pending dependent tasks are woken. Keep status/steps current when starting and finishing your block.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        id: { type: 'string', required: true, description: 'Task id.' },
+        status: { type: 'string', enum: ['pending', 'running', 'done', 'blocked'], description: 'New status.' },
+        note: { type: 'string', description: 'Optional progress note.' },
+      },
+      output,
+      execute: (args) => handlers.room_task_update(args),
+    }),
+    defineTool({
+      name: 'room_task_list',
+      description: 'List the shared Room Board tasks with status, owner and dependencies.',
+      parameters: { roomId: { type: 'string', required: true, description: 'Room id.' } },
+      output,
+      execute: (args) => handlers.room_task_list(args),
+    }),
+    defineTool({
+      name: 'room_close',
+      description: 'Close a Room (archives its canonical log); participants are no longer woken afterwards.',
+      parameters: {
+        roomId: { type: 'string', required: true, description: 'Room id.' },
+        reason: { type: 'string', description: 'Optional close reason.' },
+      },
+      output,
+      execute: (args) => handlers.room_close(args),
+    }),
     defineTool({
       name: 'fleet_invite',
       description:

package/src/plugin/index.js

@@ -15,6 +15,8 @@ import { accountFingerprint } from '../net/identity.js'
 import { DirectCallClient, DirectCallHost } from '../host/direct-call.js'
 import { DelegationHost } from '../host/delegation.js'
 import { ApprovalInbox } from '../host/approval-inbox.js'
+import { RoomService } from '../host/room-service.js'
+import { registerApprovalRoutes } from '../host/approval-web.js'
 import { ExecutionSlot, DEFAULT_SHELL_TOOL } from '../host/execution-slot.js'
 import { ToolPolicy } from '../host/tool-policy.js'
 import { createFleetHandlers, createFleetToolDefinitions } from '../host/tools.js'
@@ -194,6 +196,15 @@ export function apply(ctx, config) {
   const requestApproval = config.autoApproveAsk
     ? async () => ({ approved: true, scope: 'once' })
     : async (request) => inbox.request(request)
+
+  const rooms = new RoomService({ sessionController, createUserMessage })
+
+  // Client approval panel data plane (dev.9). Optional service: host-only
+  // deployments simply do not expose the panel routes.
+  const webServer = service('webServer')
+  if (webServer) {
+    ctx.effect(() => registerApprovalRoutes({ webServer, inbox, logger }))
+  }
   if (!sessionController) logger.warn?.('[device-fleet] sessionController unavailable: direct calls to stateful tools will fail')
   const slot = sessionController
     ? new ExecutionSlot({ sessionController, tools: ctx.tools, config: config.execution })
@@ -307,6 +318,7 @@ export function apply(ctx, config) {
       }
     },
     approvals: approvalsApi,
+    rooms,
   })
   const definitions = createFleetToolDefinitions({ defineTool, handlers })
   const wrapped = withManual(definitions.map((definition) => ({ ...definition, execute: safe(definition.execute) })))
@@ -357,6 +369,9 @@ export function apply(ctx, config) {
 
   ctx.effect(() => () => {
     inbox.close()
+    for (const roomId of rooms.openRooms()) {
+      void rooms.close({ roomId, reason: 'plugin unloaded' }).catch(() => {})
+    }
     void node.close()
   })