dsh-device-fleet 0.1.0-dev.1 → 0.1.0-dev.11

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 */
+      }
+    }
+  }
+}

package/src/host/direct-call.js

@@ -27,6 +27,7 @@ export class DirectCallHost {
    * @param {string} [options.dshVersion]
    * @param {string[]} [options.capabilities]
    * @param {string} [options.shellTool]
+   * @param {object} [options.delegation] DelegationHost for `fleet.delegate`
    */
   constructor({
     slot,
@@ -40,6 +41,7 @@ export class DirectCallHost {
     capabilities = [],
     shellTool = DEFAULT_SHELL_TOOL,
     approvalTimeoutMs = DEFAULT_POLICY_TIMEOUT_MS,
+    delegation = null,
   }) {
     this.slot = slot
     this.policy = policy
@@ -52,6 +54,7 @@ export class DirectCallHost {
     this.capabilities = capabilities
     this.shellTool = shellTool
     this.approvalTimeoutMs = approvalTimeoutMs
+    this.delegation = delegation
   }
 
   info() {
@@ -75,6 +78,11 @@ export class DirectCallHost {
         return { deviceId: this.deviceId, tools: await this.slot.listTools(), policy: this.policy.summarize() }
       case 'fleet.call':
         return this.handleCall({ fromDeviceId: deviceId, request: params ?? {} })
+      case 'fleet.delegate':
+        if (!this.delegation) {
+          throw Object.assign(new Error('delegation is unavailable on this device'), { code: 'unsupported' })
+        }
+        return this.delegation.delegate({ fromDeviceId: deviceId, request: params ?? {} })
       default:
         throw Object.assign(new Error(`unknown fleet method: ${String(method)}`), { code: 'unknown-method' })
     }
@@ -89,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 })
@@ -108,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) }
     }
   }
 
@@ -178,6 +192,11 @@ export class DirectCallClient {
     return this.node.request(deviceId, 'fleet.call', { capability, tool, args }, options)
   }
 
+  /** Ask the target device's agent to do a one-shot task and return its final text. */
+  async delegate(deviceId, request, options = {}) {
+    return this.node.request(deviceId, 'fleet.delegate', request, options)
+  }
+
   /** Format a remote result for a model-facing text tool. */
   render(result) {
     if (result?.isError) return `Error: ${result.text || 'remote tool failed'}`

package/src/host/execution-slot.js

@@ -55,11 +55,25 @@ export class ExecutionSlot {
    */
   async executeTool({ name, args = {}, signal }) {
     const agent = await this.ensureAgent()
-    const batch = await this.tools.execute({
-      calls: [{ id: randomUUID(), name, arguments: JSON.stringify(args ?? {}) }],
-      agent,
-      signal,
-    })
+    // execToolBatch requires a real AbortSignal: without one the pipeline
+    // throws before dispatch, which surfaces as "Tool batch execution failed".
+    const effectiveSignal = signal ?? new AbortController().signal
+    let batch
+    try {
+      batch = await this.tools.execute({
+        calls: [{ id: randomUUID(), name, arguments: JSON.stringify(args ?? {}) }],
+        agent,
+        signal: effectiveSignal,
+      })
+    } catch (error) {
+      const cause = error?.cause
+      const detail = cause?.message ?? error?.message ?? String(error)
+      throw Object.assign(new Error(`tool ${name} failed: ${String(detail)}`), {
+        code: 'tool-failed',
+        cause,
+        data: { causeCode: cause?.code ?? null, causeMessage: cause?.message ?? null },
+      })
+    }
     const first = batch?.results?.[0]?.result
     if (!first) throw Object.assign(new Error(`tool ${name} returned no result`), { code: 'tool-no-result' })
     const text = (first.content ?? [])

package/src/host/index.js

@@ -3,4 +3,8 @@ export * from './store.js'
 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'