dsh-device-fleet 0.1.0-dev.2 → 0.1.0-dev.20

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/config-web.js

@@ -0,0 +1,84 @@
+// Runtime config HTTP surface (dev.15): read effective config, list UI options,
+// and apply a patch live. The UI posts here; no plugin or DSH restart is involved.
+const MAX_BODY_BYTES = 256 * 1024
+
+function json(res, status, value) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.setHeader('cache-control', 'no-store')
+  res.end(JSON.stringify(value))
+}
+
+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' })
+  }
+}
+
+/**
+ * @param {object} options
+ * @param {object} options.webServer ctx.webServer
+ * @param {object} options.runtime RuntimeConfig
+ * @param {() => Promise<object>|object} [options.getOptions] UI option catalog (presets, shells, paths)
+ * @param {(patch: object) => Promise<object>|object} [options.preparePatch] side effects before applying (e.g. mkdir)
+ */
+export function registerConfigRoutes({ webServer, runtime, getOptions = null, preparePatch = null, logger = null }) {
+  if (!webServer?.register || !runtime) return () => {}
+  const disposers = []
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/device-fleet/options',
+      handler: async (req, res) => {
+        if (req.method !== 'GET') return json(res, 405, { error: 'method not allowed' })
+        try {
+          json(res, 200, (await getOptions?.()) ?? {})
+        } catch (error) {
+          logger?.warn?.(`[device-fleet] options failed: ${String(error?.message ?? error)}`)
+          json(res, 500, { error: 'internal error' })
+        }
+      },
+    }),
+  )
+  disposers.push(
+    webServer.register({
+      kind: 'exact',
+      path: '/device-fleet/config',
+      handler: async (req, res) => {
+        if (req.method === 'GET') {
+          try {
+            json(res, 200, runtime.snapshot())
+          } catch (error) {
+            json(res, 500, { error: String(error?.message ?? error) })
+          }
+          return
+        }
+        if (req.method !== 'POST') return json(res, 405, { error: 'method not allowed' })
+        try {
+          const body = await readJsonBody(req)
+          const patch = body?.patch ?? body
+          const prepared = preparePatch ? await preparePatch(patch) : patch
+          const config = await runtime.update(prepared ?? patch)
+          json(res, 200, { ok: true, config, appliedAt: Date.now() })
+        } catch (error) {
+          const status = ['bad-request', 'bad-json', 'body-too-large', 'readonly'].includes(error?.code) ? 400 : 500
+          if (status === 500) logger?.warn?.(`[device-fleet] config update failed: ${String(error?.message ?? error)}`)
+          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

@@ -18,6 +18,14 @@ export class ExecutionSlot {
     this.initializing = null
   }
 
+  /** Replace the slot's creation config; the next call lazily recreates the agent. */
+  setConfig(next = {}) {
+    this.config = { ...this.config, ...(next ?? {}) }
+    this.agent = null
+    this.sessionId = null
+    this.initializing = null
+  }
+
   async ensureAgent() {
     if (this.agent) return this.agent
     if (this.initializing) return this.initializing
@@ -55,11 +63,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,11 @@ 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 './ui-web.js'
+export * from './config-web.js'
+export * from './runtime-config.js'
+export * from './room-service.js'
 export * from './tools.js'