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

package/src/plugin/index.js

@@ -0,0 +1,276 @@
+// 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 { 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 { 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'
+
+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),
+  })
+    .default({ shellTool: DEFAULT_SHELL_TOOL, approvalTimeoutMs: 60000 })
+    .description('Execution Slot: the hidden DSH session used to execute remote tool calls.'),
+  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.'),
+})
+
+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'
+  const logger = ctx.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,
+    pluginVersion,
+    dshVersion,
+    capabilities: CAPABILITIES,
+  })
+
+  const policy = new ToolPolicy(config.policy)
+  const sessionController = ctx.sessionController ?? ctx.get?.('sessionController')
+  const fs = ctx.fs ?? ctx.get?.('fs')
+  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 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,
+        requestApproval: config.autoApproveAsk
+          ? async () => true
+          : async (request) => {
+              logger.info?.(`[device-fleet] approval required from ${request.fromDeviceId} for ${request.capability}/${String(request.tool)} (no approval UI yet)`)
+              return false
+            },
+      })
+    : 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 = ctx.get?.('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 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,
+      })
+    },
+    async join(code) {
+      writePendingEnrollment(state, code)
+    },
+  }
+  const handlers = createFleetHandlers({ node, client, pairing })
+  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 = ctx.get?.('systemPrompt') ?? ctx.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(() => () => {
+    void node.close()
+  })
+
+  ctx.logger?.info?.(`[device-fleet] v${pluginVersion} device ${state.identity.deviceId} (${config.deviceName})`)
+  void ready
+}