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

package/package.json

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

@@ -0,0 +1,124 @@
+// 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 approved =
+        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' })
+    }
+
+    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' })
     }
@@ -178,6 +186,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/index.js

@@ -3,4 +3,5 @@ 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 './tools.js'

package/src/host/store.js

@@ -50,6 +50,7 @@ export function loadState({ dshHome, dataDir, name = 'device' } = {}) {
 
   const roster = readJson(path.join(dir, 'roster.json'), [])
   const config = readJson(path.join(dir, 'config.json'), {})
+  const peerHints = readJson(path.join(dir, 'peer-hints.json'), [])
   let enrollment = readJson(path.join(dir, 'enrollment.json'), null)
   let pendingEnrollment = readJson(path.join(dir, 'enrollment.pending.json'), null)
 
@@ -75,7 +76,32 @@ export function loadState({ dshHome, dataDir, name = 'device' } = {}) {
     }
   }
 
-  return { dataDir: dir, identity, fleet, roster: Array.isArray(roster) ? roster : [], config, enrollment, pendingEnrollment, createdFleet }
+  return {
+    dataDir: dir,
+    identity,
+    fleet,
+    roster: Array.isArray(roster) ? roster : [],
+    config,
+    enrollment,
+    pendingEnrollment,
+    peerHints: Array.isArray(peerHints) ? peerHints : [],
+    createdFleet,
+  }
+}
+
+/** Persist one manually supplied peer address (from fleet_connect) for reconnects. */
+export function savePeerHint(state, hint) {
+  if (!hint || typeof hint.host !== 'string' || !Number.isInteger(hint.port) || hint.port <= 0) return
+  const entry = {
+    host: hint.host,
+    port: hint.port,
+    ...(typeof hint.deviceId === 'string' ? { deviceId: hint.deviceId } : {}),
+  }
+  const hints = Array.isArray(state.peerHints) ? state.peerHints : []
+  const exists = hints.some((item) => item.host === entry.host && item.port === entry.port && item.deviceId === entry.deviceId)
+  if (!exists) hints.push(entry)
+  state.peerHints = hints
+  writeJsonAtomic(path.join(state.dataDir, 'peer-hints.json'), hints)
 }
 
 /** Queue an invite for the next plugin load (the running node keeps its fleet). */

package/src/host/tool-policy.js

@@ -3,7 +3,7 @@
 // the raw-tool allowlist, and short-lived grants created by approvals.
 import path from 'node:path'
 
-export const CAPABILITIES = ['read', 'list', 'grep', 'fetch', 'run', 'tool']
+export const CAPABILITIES = ['read', 'list', 'grep', 'fetch', 'run', 'tool', 'delegate']
 
 export const DEFAULT_POLICY = Object.freeze({
   allowedRoots: [],
@@ -14,6 +14,7 @@ export const DEFAULT_POLICY = Object.freeze({
     fetch: 'auto',
     run: 'ask',
     tool: 'deny',
+    delegate: 'ask',
   },
   allowedTools: [],
   approvalTtlMs: 15 * 60 * 1000,

package/src/host/tools.js

@@ -22,7 +22,7 @@ function fail(error) {
 }
 
 /** Pure handlers; wrapped into ToolDefinitions by `createFleetToolDefinitions`. */
-export function createFleetHandlers({ node, client = new DirectCallClient({ node }), pairing = null }) {
+export function createFleetHandlers({ node, client = new DirectCallClient({ node }), pairing = null, onPeerHint = null }) {
   return {
     async fleet_status() {
       if (typeof node.status !== 'function') return { text: 'Error: [unsupported] status is unavailable' }
@@ -34,6 +34,7 @@ export function createFleetHandlers({ node, client = new DirectCallClient({ node
       try {
         node.addPeerHint?.({ host, port })
         const peer = await node.connectAddress(host, port)
+        await onPeerHint?.({ host, port })
         return { text: `connected to ${peer.deviceId} (${peer.name ?? 'device'}) at ${host}:${port}` }
       } catch (error) {
         return fail(error)
@@ -109,6 +110,20 @@ export function createFleetHandlers({ node, client = new DirectCallClient({ node
       }
     },
 
+    async fleet_delegate({ device, task, label, cwd }) {
+      try {
+        const result = await client.delegate(
+          device,
+          { task, ...(label ? { label } : {}), ...(cwd ? { cwd } : {}) },
+          { timeoutMs: 200_000 },
+        )
+        const meta = result?.childId ? `\n[delegated on ${device} · ${String(result.durationMs ?? 0)}ms · child ${String(result.childId)}]` : ''
+        return { text: `${String(result?.text ?? '')}${meta}`.trim() }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
     async fleet_read({ device, path, offset, limit }) {
       try {
         const args = { file_path: path }
@@ -211,6 +226,19 @@ export function createFleetToolDefinitions({ defineTool, handlers }) {
       output,
       execute: (args) => handlers.fleet_call(args),
     }),
+    defineTool({
+      name: 'fleet_delegate',
+      description:
+        'Delegate a one-shot task to another device\'s agent and wait for its final answer. Use it when the work needs that device\'s model and tools ("let B build/check this"), not just one tool call. The delegated agent runs on the target device; it does not join a Room and its history is not shared. The target device decides whether delegation is allowed or needs local approval.',
+      parameters: {
+        device: commonDevice,
+        task: { type: 'string', required: true, description: 'Self-contained task instructions for the target agent.' },
+        label: { type: 'string', description: 'Short label shown in the target device\'s subagent list.' },
+        cwd: { type: 'string', description: 'Optional working directory on the target device.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_delegate(args),
+    }),
     defineTool({
       name: 'fleet_read',
       description:

package/src/net/fleet-node.js

@@ -281,6 +281,14 @@ export class FleetNode extends EventEmitter {
       if (current === channel) this.channels.delete(channel.peer.deviceId)
       this.rejectPendingForChannel(channel, Object.assign(new Error('peer connection closed'), { code: 'peer-offline' }))
       this.emit('peer-disconnected', { deviceId: channel.peer?.deviceId, via })
+      // Recover automatically: the peer may have restarted or moved; retry the
+      // known addresses instead of waiting for the next process start.
+      if (!this.closed && this.channels.size === 0 && this.peerHints.length > 0) {
+        clearTimeout(this.hintTimer)
+        this.hintTimer = null
+        this.hintAttempt = 0
+        this.scheduleHintConnects()
+      }
     })
   }
 

package/src/plugin/index.js

@@ -13,10 +13,11 @@ import Schema from '@deepseek-ai/schemastery'
 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 { ExecutionSlot, DEFAULT_SHELL_TOOL } from '../host/execution-slot.js'
 import { ToolPolicy } from '../host/tool-policy.js'
 import { createFleetHandlers, createFleetToolDefinitions } from '../host/tools.js'
-import { accountMatches, createInvite, loadState, saveRoster, writePendingEnrollment } from '../host/store.js'
+import { accountMatches, createInvite, loadState, savePeerHint, saveRoster, writePendingEnrollment } from '../host/store.js'
 
 export const name = 'device-fleet'
 
@@ -60,9 +61,11 @@ export const Config = Schema.object({
     agentPreset: Schema.string(),
     shellTool: Schema.string().default(DEFAULT_SHELL_TOOL),
     approvalTimeoutMs: Schema.number().default(60000),
+    delegateTimeoutMs: Schema.number().default(180000),
+    subagentProvider: Schema.string().default('spawn'),
   })
-    .default({ shellTool: DEFAULT_SHELL_TOOL, approvalTimeoutMs: 60000 })
-    .description('Execution Slot: the hidden DSH session used to execute remote tool calls.'),
+    .default({ shellTool: DEFAULT_SHELL_TOOL, approvalTimeoutMs: 60000, delegateTimeoutMs: 180000, subagentProvider: 'spawn' })
+    .description('Execution Slot and delegation settings for direct calls and one-shot delegation.'),
   policy: Schema.object({
     allowedRoots: Schema.array(Schema.string()).default([]),
     capabilities: Schema.any().default({}),
@@ -144,7 +147,7 @@ export function apply(ctx, config) {
     discovery: config.discovery ? true : false,
     relay: config.relay ?? state.enrollment?.relay ?? null,
     roster: state.roster,
-    peerHints: state.enrollment?.endpoints ?? [],
+    peerHints: [...(state.enrollment?.endpoints ?? []), ...(state.peerHints ?? [])],
     pluginVersion,
     dshVersion,
     capabilities: CAPABILITIES,
@@ -153,11 +156,32 @@ export function apply(ctx, config) {
   const policy = new ToolPolicy(config.policy)
   const sessionController = service('sessionController')
   const fs = service('fs')
+  const subagents = service('subagents')
   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 })
     : null
 
+  const delegation =
+    slot && subagents
+      ? new DelegationHost({
+          subagents,
+          slot,
+          policy,
+          deviceId: state.identity.deviceId,
+          defaultCwd: config.execution?.cwd,
+          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
+              },
+        })
+      : null
+
   const host = slot
     ? new DirectCallHost({
         slot,
@@ -170,6 +194,7 @@ export function apply(ctx, config) {
         capabilities: CAPABILITIES,
         shellTool: config.execution?.shellTool ?? DEFAULT_SHELL_TOOL,
         approvalTimeoutMs: config.execution?.approvalTimeoutMs ?? 60_000,
+        delegation,
         requestApproval: config.autoApproveAsk
           ? async () => true
           : async (request) => {
@@ -243,7 +268,18 @@ export function apply(ctx, config) {
       writePendingEnrollment(state, code)
     },
   }
-  const handlers = createFleetHandlers({ node, client, pairing })
+  const handlers = createFleetHandlers({
+    node,
+    client,
+    pairing,
+    onPeerHint: async (hint) => {
+      try {
+        savePeerHint(state, hint)
+      } catch (error) {
+        logger.warn?.(`[device-fleet] cannot persist peer hint: ${String(error?.message ?? error)}`)
+      }
+    },
+  })
   const definitions = createFleetToolDefinitions({ defineTool, handlers })
   const wrapped = withManual(definitions.map((definition) => ({ ...definition, execute: safe(definition.execute) })))
   for (const definition of wrapped) ctx.tools.register(definition)