dsh-device-fleet 0.0.0-stage → 0.1.0-dev.10

package/src/plugin/index.js

@@ -0,0 +1,380 @@
+// Cordis Host plugin entry for the device-fleet bundle.
+//
+// Step 1 wires the network layer, the FleetNode, the direct-call host/client,
+// the six `fleet_*` tools, and the two adoption mechanisms that are cheap to
+// land now (a prompt section and a first-use manual + orchestration nudge).
+// Room, Room Board, delegation and the UI land in later steps.
+import { readFileSync } from 'node:fs'
+import { networkInterfaces } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+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 { ApprovalInbox } from '../host/approval-inbox.js'
+import { RoomService } from '../host/room-service.js'
+import { registerApprovalRoutes } from '../host/approval-web.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, savePeerHint, saveRoster, writePendingEnrollment } from '../host/store.js'
+
+export const name = 'device-fleet'
+
+/** Only the tool registry is mandatory; everything else degrades. */
+export const inject = ['tools']
+
+const CAPABILITIES = ['direct-call', 'room', 'delegation']
+const PROMPT_SECTION_ORDER = 9000
+
+const FLEET_MANUAL = `# Fleet 使用手册
+
+你是设备联邦（Fleet）中的一个设备成员。其他设备通过 fleet 工具暴露能力，规则如下：
+
+- **先看图再动手**：调用任何 fleet 工具前先 \`fleet_list\` 拿到 device id；不认识的工具用 \`fleet_tools\` 查。
+- **直调 vs 协作**：只是借用另一台设备的工具（看文件、取文件、跑命令、取日志）用 \`fleet_read\` / \`fleet_fetch\` / \`fleet_run\` / \`fleet_call\`；需要对方 agent 持续参与、共享任务状态时，才建 Room（后续版本提供）。
+- **离线快速失败**：目标设备离线时直调立即报错，不要等待；改为稍后再试或换设备。
+- **审批在对方设备上**：需要本机审批的调用会等待对方用户；超时/被拒绝时按错误码处理，换方案或请用户处理，不要绕过。
+- **权限由对方决定**：你只能请求，能否执行、能访问哪些目录由目标设备配置决定。`
+
+/** Session ids already handed the fleet manual. */
+const manualDelivered = new Set()
+
+export const Config = Schema.object({
+  deviceName: Schema.string().default('device').description('Display name of this device in the Fleet.'),
+  dataDir: Schema.string().description('Override the device-fleet state directory (defaults to $DSH_HOME/device-fleet).'),
+  direct: Schema.object({
+    host: Schema.string().default('0.0.0.0'),
+    port: Schema.number().default(0),
+  })
+    .default({ host: '0.0.0.0', port: 0 })
+    .description('Direct LAN/VPN listener. Set port 0 to let the OS pick one; discovery announces it.'),
+  discovery: Schema.boolean().default(true).description('Advertise this device on the local network over UDP multicast.'),
+  relay: Schema.object({
+    host: Schema.string(),
+    port: Schema.number(),
+    dataPort: Schema.number(),
+  })
+    .description('Self-hosted relay (v2) used when a direct connection is not reachable.'),
+  execution: Schema.object({
+    cwd: Schema.string(),
+    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, 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({}),
+    allowedTools: Schema.array(Schema.string()).default([]),
+    approvalTtlMs: Schema.number().default(15 * 60 * 1000),
+  })
+    .default({ allowedRoots: [], capabilities: {}, allowedTools: [], approvalTtlMs: 15 * 60 * 1000 })
+    .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() {
+  try {
+    const file = fileURLToPath(new URL('../../package.json', import.meta.url))
+    return JSON.parse(readFileSync(file, 'utf8')).version ?? '0.0.0'
+  } catch {
+    return '0.0.0'
+  }
+}
+
+/** Wrap a handler so failures are reported as text instead of tool crashes. */
+function safe(handler) {
+  return async (...args) => {
+    try {
+      return await handler(...args)
+    } catch (error) {
+      const code = error?.code ?? 'error'
+      return { text: `Error: [${String(code)}] ${String(error?.message ?? error)}` }
+    }
+  }
+}
+
+function withManual(definitions) {
+  return definitions.map((definition) => ({
+    ...definition,
+    execute: async (...args) => {
+      const result = await definition.execute(...args)
+      const exec = args[1]
+      const sessionId = exec?.agent?.session?.id
+      if (typeof sessionId !== 'string' || manualDelivered.has(sessionId)) return result
+      manualDelivered.add(sessionId)
+      if (typeof result === 'object' && result !== null && 'text' in result) {
+        return { ...result, text: `${String(result.text)}\n\n---\n${FLEET_MANUAL}` }
+      }
+      return result
+    },
+  }))
+}
+
+export function apply(ctx, config) {
+  const pluginVersion = packageVersion()
+  const dshVersion = process.env.DSH_CLIENT_VERSION ?? 'unknown'
+  // Optional services: Cordis throws on direct property access for services the
+  // plugin did not inject, so every optional service goes through get().
+  const service = (name) => {
+    try {
+      return ctx.get?.(name)
+    } catch {
+      return undefined
+    }
+  }
+  const logger = service('logger') ?? console
+
+  let state
+  try {
+    state = loadState({ dshHome: process.env.DSH_HOME, dataDir: config.dataDir, name: config.deviceName })
+  } catch (error) {
+    logger.error?.(`[device-fleet] cannot load state: ${String(error?.message ?? error)}`)
+    return
+  }
+
+  const node = new FleetNode({
+    identity: state.identity,
+    fleet: state.fleet,
+    name: config.deviceName,
+    accountFingerprint: state.enrollment?.accountFingerprint ?? null,
+    direct: config.direct ?? { host: '127.0.0.1', port: 0 },
+    discovery: config.discovery ? true : false,
+    relay: config.relay ?? state.enrollment?.relay ?? null,
+    roster: state.roster,
+    peerHints: [...(state.enrollment?.endpoints ?? []), ...(state.peerHints ?? [])],
+    pluginVersion,
+    dshVersion,
+    capabilities: CAPABILITIES,
+  })
+
+  const policy = new ToolPolicy(config.policy)
+  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)
+
+  const rooms = new RoomService({ sessionController, createUserMessage })
+
+  // Client approval panel data plane (dev.9). Optional service: host-only
+  // deployments simply do not expose the panel routes.
+  const webServer = service('webServer')
+  if (webServer) {
+    ctx.effect(() => registerApprovalRoutes({ webServer, inbox, logger }))
+  }
+  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,
+        })
+      : null
+
+  const host = slot
+    ? new DirectCallHost({
+        slot,
+        policy,
+        fs,
+        deviceId: state.identity.deviceId,
+        name: config.deviceName,
+        pluginVersion,
+        dshVersion,
+        capabilities: CAPABILITIES,
+        shellTool: config.execution?.shellTool ?? DEFAULT_SHELL_TOOL,
+        approvalTimeoutMs: config.execution?.approvalTimeoutMs ?? 60_000,
+        delegation,
+        requestApproval,
+      })
+    : null
+
+  node.onRequest(async (request) => {
+    if (!host) throw Object.assign(new Error('this device cannot serve direct calls (no execution slot)'), { code: 'unsupported' })
+    return host.handleRequest(request)
+  })
+  node.on('roster', (roster) => {
+    try {
+      saveRoster(state, roster)
+    } catch (error) {
+      logger.warn?.(`[device-fleet] cannot persist roster: ${String(error?.message ?? error)}`)
+    }
+  })
+  node.on('warning', (error) => logger.warn?.(`[device-fleet] ${String(error?.message ?? error)}`))
+
+  const ready = node.start().catch((error) => {
+    logger.error?.(`[device-fleet] cannot start network layer: ${String(error?.message ?? error)}`)
+  })
+
+  // Bind the local account fingerprint when the account service is composed.
+  const account = service('deepseekAccount')
+  if (account && typeof account.getDeviceIdentity === 'function') {
+    void account
+      .getDeviceIdentity()
+      .then((identity) => {
+        if (!identity?.userId) return
+        const fingerprint = accountFingerprint(state.fleet.fleetKey, identity.userId)
+        if (!accountMatches(state, fingerprint)) {
+          logger.error?.('[device-fleet] signed-in account does not match the Fleet invite; connections will be refused')
+          node.accountFingerprint = 'mismatch'
+          return
+        }
+        node.accountFingerprint = fingerprint
+      })
+      .catch(() => {})
+  }
+
+  const client = new DirectCallClient({ node })
+  const localEndpoints = () => {
+    const port = node.directAddress?.port
+    if (!Number.isInteger(port) || port <= 0) return []
+    const endpoints = []
+    for (const entries of Object.values(networkInterfaces())) {
+      for (const entry of entries ?? []) {
+        if (entry.family !== 'IPv4' || entry.internal) continue
+        endpoints.push({ deviceId: state.identity.deviceId, host: entry.address, port })
+      }
+    }
+    return endpoints
+  }
+  const pairing = {
+    async invite() {
+      const fingerprint =
+        node.accountFingerprint && node.accountFingerprint !== 'mismatch'
+          ? node.accountFingerprint
+          : (state.enrollment?.accountFingerprint ?? null)
+      return createInvite(state, {
+        accountFingerprint: fingerprint,
+        relay: config.relay ?? state.enrollment?.relay ?? null,
+        endpoints: localEndpoints(),
+      })
+    },
+    async join(code) {
+      writePendingEnrollment(state, code)
+    },
+  }
+  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)}`)
+      }
+    },
+    approvals: approvalsApi,
+    rooms,
+  })
+  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)
+
+  // Adoption layer 2: one sentence, only when the Fleet has members.
+  const systemPrompt = service('systemPrompt')
+  if (systemPrompt && config.promptSection !== false) {
+    const order = systemPrompt.getSectionOrder?.('TOOL_SUBAGENT') ?? PROMPT_SECTION_ORDER
+    ctx.effect(() =>
+      systemPrompt.section({
+        name: 'device-fleet:members',
+        order,
+        text: () => {
+          const members = node.rosterEntries().length
+          if (members === 0) return ''
+          return `This DSH instance is part of a device Fleet with ${members} other device(s). Use fleet_list/fleet_read/fleet_fetch/fleet_run for work that belongs on another device; direct calls fail fast when that device is offline.`
+        },
+      }),
+    )
+  }
+
+  // Adoption layer 4: one-line nudge when the model starts orchestrating.
+  ctx.on?.('tools/post-execute', async (exec, _result, next) => {
+    const decision = await next()
+    const signal = exec?.name
+    if (signal !== 'todo_write' && !String(signal).startsWith('subagent') && signal !== 'workflow' && signal !== 'ralph') return decision
+    if (node.rosterEntries().length === 0) return decision
+    const sessionId = exec?.agent?.session?.id
+    if (typeof sessionId !== 'string' || manualDelivered.has(sessionId)) return decision
+    manualDelivered.add(sessionId)
+    return {
+      ...decision,
+      additionalContexts: [
+        ...(decision.additionalContexts ?? []),
+        createUserMessage({
+          content: [
+            {
+              type: 'text',
+              text: 'You are organising multi-step work on a device Fleet. If part of it belongs on another machine (builds, logs, files, tests), use fleet_list then fleet_read/fleet_fetch/fleet_run; keep the work on this device when it is local.',
+            },
+          ],
+          source: { kind: 'device-fleet', form: 'instructions' },
+        }),
+      ],
+    }
+  })
+
+  ctx.effect(() => () => {
+    inbox.close()
+    for (const roomId of rooms.openRooms()) {
+      void rooms.close({ roomId, reason: 'plugin unloaded' }).catch(() => {})
+    }
+    void node.close()
+  })
+
+  logger.info?.(`[device-fleet] v${pluginVersion} device ${state.identity.deviceId} (${config.deviceName})`)
+  void ready
+}