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

package/docs/notes/dev-release.md

@@ -38,4 +38,10 @@ 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 会自动固定对端公钥。
+- `fleet_list` 仍是本地视图；配对成功后双方 roster 会自动固定对端公钥。
+## 0.1.0-dev.6（稳定化）
+
+- 直连端口可固定（profile `direct.port`），插件重载不再换端口；
+- 连接断开后自动重试已知地址（不再只在启动时试一次）；
+- `fleet_connect` 手动地址会持久化到 `peer-hints.json`，重启后继续回连；
+- 新增 `fleet_delegate`（dev.5）：目标设备用 `SubagentProvider` + `delivery:'caller'` 跑 agent 并返回最终结果。

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

@@ -1,6 +1,6 @@
 {
   "name": "dsh-device-fleet",
-  "version": "0.1.0-dev.6",
+  "version": "0.1.0-dev.7",
   "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",

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

@@ -72,12 +72,15 @@ export class DelegationHost {
       throw Object.assign(new Error(decision.reason), { code: 'denied', data: { capability: 'delegate' } })
     }
     if (decision.decision === 'ask') {
-      const approved =
+      const outcome =
         typeof this.requestApproval === 'function'
           ? await this.requestApproval({ fromDeviceId, capability: 'delegate', tool: 'delegate', args: { task }, reason: decision.reason })
-          : false
-      if (approved !== true) throw Object.assign(new Error('local approval was not granted'), { code: 'approval_denied' })
-      this.policy.grant(decision.key, { scope: 'once' })
+          : { 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()

package/src/host/direct-call.js

@@ -97,9 +97,11 @@ export class DirectCallHost {
       throw Object.assign(new Error(decision.reason), { code: 'denied', data: { capability, tool } })
     }
     if (decision.decision === 'ask') {
-      const approved = await this.askApproval({ fromDeviceId, capability, tool, args, reason: decision.reason })
-      if (!approved) throw Object.assign(new Error('local approval was not granted'), { code: 'approval_denied' })
-      this.policy.grant(decision.key, { scope: 'once' })
+      const outcome = await this.askApproval({ fromDeviceId, capability, tool, args, reason: decision.reason })
+      if (outcome.approved !== true) {
+        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 startedAt = Date.now()
     const result = await this.execute({ capability, tool, args })
@@ -116,12 +118,16 @@ export class DirectCallHost {
   }
 
   async askApproval({ fromDeviceId, capability, tool, args, reason }) {
-    if (typeof this.requestApproval !== 'function') return false
+    if (typeof this.requestApproval !== 'function') return { approved: false, reason: 'no approval channel' }
     try {
-      const approved = await this.requestApproval({ fromDeviceId, capability, tool, args, reason })
-      return approved === true
-    } catch {
-      return false
+      const outcome = await this.requestApproval({ fromDeviceId, capability, tool, args, reason })
+      if (outcome === true) return { approved: true, scope: 'once' }
+      if (outcome && typeof outcome === 'object') {
+        return { approved: outcome.approved === true, scope: outcome.scope ?? 'once', reason: outcome.reason }
+      }
+      return { approved: false, reason: 'approval not granted' }
+    } catch (error) {
+      return { approved: false, reason: String(error?.message ?? error) }
     }
   }
 

package/src/host/tools.js

@@ -22,8 +22,53 @@ function fail(error) {
 }
 
 /** Pure handlers; wrapped into ToolDefinitions by `createFleetToolDefinitions`. */
-export function createFleetHandlers({ node, client = new DirectCallClient({ node }), pairing = null, onPeerHint = null }) {
+export function createFleetHandlers({
+  node,
+  client = new DirectCallClient({ node }),
+  pairing = null,
+  onPeerHint = null,
+  approvals = null,
+}) {
   return {
+    async fleet_approvals() {
+      if (!approvals?.list) return { text: 'Error: [unsupported] the approval inbox is unavailable' }
+      const items = approvals.list()
+      if (items.length === 0) return { text: '(no pending approvals)' }
+      const lines = items.map(
+        (item) =>
+          `- ${item.id} · ${item.fromDeviceId} · ${item.capability}${item.tool ? `/${String(item.tool)}` : ''} · ${item.expiresInMs}ms left · ${item.argsSummary}`,
+      )
+      return { text: lines.join('\n') }
+    },
+
+    async fleet_approve({ id, scope }) {
+      if (!approvals?.approve) return { text: 'Error: [unsupported] the approval inbox is unavailable' }
+      try {
+        const result = approvals.approve(id, { scope: scope ?? 'once' })
+        return { text: `approved ${result.id} (${result.scope})` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_deny({ id, reason }) {
+      if (!approvals?.deny) return { text: 'Error: [unsupported] the approval inbox is unavailable' }
+      try {
+        const result = approvals.deny(id, reason ?? 'denied by local user')
+        return { text: `denied ${result.id}` }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_simulate_request({ fromDeviceId, capability, tool, reason }) {
+      if (!approvals?.simulate) return { text: 'Error: [unsupported] approval simulation is disabled' }
+      try {
+        return { text: await approvals.simulate({ fromDeviceId, capability, tool, reason }) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
     async fleet_status() {
       if (typeof node.status !== 'function') return { text: 'Error: [unsupported] status is unavailable' }
       return { text: JSON.stringify(node.status(), null, 2) }
@@ -180,6 +225,48 @@ export function createFleetToolDefinitions({ defineTool, handlers }) {
       output,
       execute: (args) => handlers.fleet_connect(args),
     }),
+    defineTool({
+      name: 'fleet_approvals',
+      description:
+        'List pending approval requests waiting on this device (remote direct calls or delegations whose Tool Policy is `ask`). Approve or deny them with `fleet_approve` / `fleet_deny`. Approvals expire after the configured timeout and fail closed.',
+      parameters: {},
+      output,
+      execute: () => handlers.fleet_approvals(),
+    }),
+    defineTool({
+      name: 'fleet_approve',
+      description:
+        'Approve one pending approval request on this device. `scope: "once"` allows one call; `scope: "ttl"` allows that capability for the configured TTL (default 15 minutes). Permanent grants belong in the device settings, not here.',
+      parameters: {
+        id: { type: 'string', required: true, description: 'Approval request id from `fleet_approvals`.' },
+        scope: { type: 'string', enum: ['once', 'ttl'], description: 'Approval scope; defaults to once.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_approve(args),
+    }),
+    defineTool({
+      name: 'fleet_deny',
+      description: 'Deny one pending approval request on this device.',
+      parameters: {
+        id: { type: 'string', required: true, description: 'Approval request id from `fleet_approvals`.' },
+        reason: { type: 'string', description: 'Optional reason returned to the caller.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_deny(args),
+    }),
+    defineTool({
+      name: 'fleet_simulate_request',
+      description:
+        'Development helper (only when approval simulation is enabled): create a fake pending approval request so the inbox flow can be exercised without a second device. It does not execute anything.',
+      parameters: {
+        fromDeviceId: { type: 'string', description: 'Pretend caller device id.' },
+        capability: { type: 'string', description: 'Capability name, e.g. run.' },
+        tool: { type: 'string', description: 'Optional tool name.' },
+        reason: { type: 'string', description: 'Optional reason shown in the request.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_simulate_request(args),
+    }),
     defineTool({
       name: 'fleet_invite',
       description:

package/src/plugin/index.js

@@ -14,6 +14,7 @@ import { FleetNode } from '../net/fleet-node.js'
 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 { ExecutionSlot, DEFAULT_SHELL_TOOL } from '../host/execution-slot.js'
 import { ToolPolicy } from '../host/tool-policy.js'
 import { createFleetHandlers, createFleetToolDefinitions } from '../host/tools.js'
@@ -76,6 +77,13 @@ export const Config = Schema.object({
     .description('Direct-call Tool Policy owned by this device (ADR-0004/ADR-0019).'),
   promptSection: Schema.boolean().default(true).description('Render the one-sentence Fleet nudge when the Fleet has members.'),
   autoApproveAsk: Schema.boolean().default(false).description('Testing only: auto-approve every local approval request.'),
+  approvals: Schema.object({
+    ttlMs: Schema.number().default(60000),
+    maxPending: Schema.number().default(50),
+    simulation: Schema.boolean().default(false),
+  })
+    .default({ ttlMs: 60000, maxPending: 50, simulation: false })
+    .description('Local approval inbox (ADR-0020). `simulation` exposes fleet_simulate_request for local testing.'),
 })
 
 function packageVersion() {
@@ -157,6 +165,35 @@ export function apply(ctx, config) {
   const sessionController = service('sessionController')
   const fs = service('fs')
   const subagents = service('subagents')
+  const inbox = new ApprovalInbox({
+    ttlMs: config.approvals?.ttlMs ?? 60_000,
+    maxPending: config.approvals?.maxPending ?? 50,
+  })
+  inbox.on('request', (request) => logger.info?.(`[device-fleet] approval requested by ${request.fromDeviceId}: ${request.capability}/${String(request.tool ?? '')}`))
+  const approvalsApi = {
+    list: () => inbox.list(),
+    approve: (id, options) => inbox.approve(id, options),
+    deny: (id, reason) => inbox.deny(id, reason),
+    simulate: config.approvals?.simulation
+      ? async ({ fromDeviceId, capability, tool, reason }) => {
+          const promise = inbox.request({
+            fromDeviceId: fromDeviceId ?? 'simulated-device',
+            capability: capability ?? 'run',
+            tool: tool ?? null,
+            reason: reason ?? 'simulated approval request',
+            args: {},
+          })
+          const summary = inbox.list().at(-1)
+          // Keep the promise from becoming an unhandled rejection when the
+          // request expires without an answer; the demo only inspects the inbox.
+          promise.catch(() => {})
+          return `simulated approval request ${summary?.id ?? '?'} created; use fleet_approvals / fleet_approve / fleet_deny`
+        }
+      : null,
+  }
+  const requestApproval = config.autoApproveAsk
+    ? async () => ({ approved: true, scope: 'once' })
+    : async (request) => inbox.request(request)
   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 })
@@ -173,12 +210,7 @@ export function apply(ctx, config) {
           defaultAgentPreset: config.execution?.agentPreset,
           provider: config.execution?.subagentProvider ?? 'spawn',
           timeoutMs: config.execution?.delegateTimeoutMs ?? 180_000,
-          requestApproval: config.autoApproveAsk
-            ? async () => true
-            : async (request) => {
-                logger.info?.(`[device-fleet] delegation approval required from ${request.fromDeviceId} (no approval UI yet)`)
-                return false
-              },
+          requestApproval,
         })
       : null
 
@@ -195,12 +227,7 @@ export function apply(ctx, config) {
         shellTool: config.execution?.shellTool ?? DEFAULT_SHELL_TOOL,
         approvalTimeoutMs: config.execution?.approvalTimeoutMs ?? 60_000,
         delegation,
-        requestApproval: config.autoApproveAsk
-          ? async () => true
-          : async (request) => {
-              logger.info?.(`[device-fleet] approval required from ${request.fromDeviceId} for ${request.capability}/${String(request.tool)} (no approval UI yet)`)
-              return false
-            },
+        requestApproval,
       })
     : null
 
@@ -279,6 +306,7 @@ export function apply(ctx, config) {
         logger.warn?.(`[device-fleet] cannot persist peer hint: ${String(error?.message ?? error)}`)
       }
     },
+    approvals: approvalsApi,
   })
   const definitions = createFleetToolDefinitions({ defineTool, handlers })
   const wrapped = withManual(definitions.map((definition) => ({ ...definition, execute: safe(definition.execute) })))
@@ -328,6 +356,7 @@ export function apply(ctx, config) {
   })
 
   ctx.effect(() => () => {
+    inbox.close()
     void node.close()
   })