dsh-device-fleet 0.1.0-dev.3 → 0.1.0-dev.31

package/src/host/approval-inbox.js

@@ -0,0 +1,163 @@
+// 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, historyLimit = 50, now = Date.now } = {}) {
+    super()
+    this.ttlMs = ttlMs
+    this.maxPending = maxPending
+    this.historyLimit = historyLimit
+    this.now = now
+    this.closed = false
+    /** @type {Map<string, any>} */
+    this.pending = new Map()
+    /** @type {any[]} */
+    this.historyEntries = []
+  }
+
+  record(entry, outcome, extra = {}) {
+    this.historyEntries.unshift({
+      id: entry.id,
+      fromDeviceId: entry.fromDeviceId,
+      capability: entry.capability,
+      tool: entry.tool,
+      reason: entry.reason,
+      argsSummary: entry.argsSummary,
+      createdAt: entry.createdAt,
+      resolvedAt: this.now(),
+      outcome,
+      ...extra,
+    })
+    if (this.historyEntries.length > this.historyLimit) this.historyEntries.length = this.historyLimit
+  }
+
+  /** Recently resolved requests (newest first). */
+  history() {
+    return this.historyEntries.map((entry) => ({ ...entry }))
+  }
+
+  /**
+   * 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.record(entry, 'approved', { 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.record(entry, 'denied', { 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.record(entry, 'expired')
+    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.record(entry, '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/avatar-web.js

@@ -0,0 +1,179 @@
+// Agent avatars used by the Room conversation (dev.25/26). Built-in PNG files
+// ship with the package; the user can upload a library into the state dir and
+// Room members cycle through it.
+import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs'
+import { basename, join } from 'node:path'
+
+export const AVATARS = {
+  host: 'host.png',
+  worker: 'worker.png',
+  user: 'user.png',
+}
+
+const EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.webp'])
+const MAX_UPLOAD_BYTES = 3 * 1024 * 1024
+
+function safeFileName(input, extension) {
+  const base = String(input ?? 'avatar')
+    .replace(/[^a-zA-Z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 48)
+  return `${base || 'avatar'}-${Date.now().toString(36)}${extension}`
+}
+
+function listLibrary(dir) {
+  if (!existsSync(dir)) return []
+  return readdirSync(dir)
+    .filter((name) => EXTENSIONS.has(name.slice(name.lastIndexOf('.')).toLowerCase()))
+    .sort()
+    .map((name) => ({ name, url: `/device-fleet/avatar-file?name=${encodeURIComponent(name)}` }))
+}
+
+function parseDataUrl(dataUrl) {
+  const match = /^data:image\/(png|jpe?g|webp);base64,([A-Za-z0-9+/=]+)$/.exec(String(dataUrl ?? ''))
+  if (!match) throw Object.assign(new Error('dataUrl must be a base64 png/jpeg/webp image'), { code: 'bad-request' })
+  const extension = match[1] === 'jpeg' ? '.jpg' : `.${match[1]}`
+  const buffer = Buffer.from(match[2], 'base64')
+  if (buffer.length === 0 || buffer.length > MAX_UPLOAD_BYTES) {
+    throw Object.assign(new Error(`avatar must be between 1 byte and ${MAX_UPLOAD_BYTES} bytes`), { code: 'bad-request' })
+  }
+  return { extension, buffer }
+}
+
+function json(res, status, value) {
+  res.statusCode = status
+  res.setHeader('content-type', 'application/json; charset=utf-8')
+  res.end(JSON.stringify(value))
+}
+
+async function readJson(req) {
+  const chunks = []
+  for await (const chunk of req) 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 {string} options.dir built-in avatar directory
+ * @param {string} options.libraryDir user-uploaded avatar directory
+ */
+export function registerAvatarRoutes({ webServer, dir, libraryDir = null, logger = null }) {
+  if (!webServer?.register || !dir) return () => {}
+  const disposers = []
+  const sendPng = (res, file, alt = null) => {
+    try {
+      const data = readFileSync(file)
+      res.statusCode = 200
+      res.setHeader('content-type', alt ?? 'image/png')
+      res.setHeader('cache-control', 'public, max-age=3600')
+      res.setHeader('content-length', String(data.length))
+      res.end(data)
+    } catch {
+      logger?.warn?.(`[device-fleet] avatar missing: ${file}`)
+      res.statusCode = 404
+      res.end()
+    }
+  }
+  for (const [name, file] of Object.entries(AVATARS)) {
+    disposers.push(
+      webServer.register({
+        kind: 'exact',
+        path: `/device-fleet/avatar/${name}`,
+        handler: async (req, res) => {
+          if (req.method !== 'GET' && req.method !== 'HEAD') {
+            res.statusCode = 405
+            res.end()
+            return
+          }
+          if (req.method === 'HEAD') {
+            res.statusCode = 200
+            res.end()
+            return
+          }
+          sendPng(res, join(dir, file))
+        },
+      }),
+    )
+  }
+  if (libraryDir) {
+    try {
+      mkdirSync(libraryDir, { recursive: true })
+    } catch {
+      /* best effort */
+    }
+    disposers.push(
+      webServer.register({
+        kind: 'exact',
+        path: '/device-fleet/avatar-library',
+        handler: async (req, res) => {
+          try {
+            if (req.method === 'GET') return json(res, 200, { items: listLibrary(libraryDir) })
+            if (req.method === 'POST') {
+              const body = await readJson(req)
+              const { extension, buffer } = parseDataUrl(body.dataUrl)
+              const name = safeFileName(body.name, extension)
+              writeFileSync(join(libraryDir, name), buffer)
+              return json(res, 200, { ok: true, item: { name, url: `/device-fleet/avatar-file?name=${encodeURIComponent(name)}` } })
+            }
+            return json(res, 405, { error: 'method not allowed' })
+          } catch (error) {
+            return json(res, 400, { error: String(error?.message ?? error), code: error?.code ?? 'bad-request' })
+          }
+        },
+      }),
+    )
+    disposers.push(
+      webServer.register({
+        kind: 'exact',
+        path: '/device-fleet/avatar-file',
+        handler: async (req, res) => {
+          if (req.method !== 'GET') {
+            res.statusCode = 405
+            res.end()
+            return
+          }
+          let name = ''
+          try {
+            name = new URL(req.url ?? '/', 'http://local').searchParams.get('name') ?? ''
+          } catch {
+            name = ''
+          }
+          const clean = basename(name)
+          if (clean === '' || clean !== name || !EXTENSIONS.has(clean.slice(clean.lastIndexOf('.')).toLowerCase())) {
+            res.statusCode = 400
+            res.end()
+            return
+          }
+          sendPng(res, join(libraryDir, clean))
+        },
+      }),
+    )
+    disposers.push(
+      webServer.register({
+        kind: 'exact',
+        path: '/device-fleet/avatar-library/remove',
+        handler: async (req, res) => {
+          if (req.method !== 'POST') return json(res, 405, { error: 'method not allowed' })
+          try {
+            const body = await readJson(req)
+            const clean = basename(String(body.name ?? ''))
+            if (clean === '' || clean !== body.name) throw Object.assign(new Error('invalid name'), { code: 'bad-request' })
+            unlinkSync(join(libraryDir, clean))
+            return json(res, 200, { ok: true })
+          } catch (error) {
+            return json(res, 400, { error: String(error?.message ?? 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 */
+      }
+    }
+  }
+}