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

package/src/host/tools.js

@@ -0,0 +1,215 @@
+// Model-facing fleet tools (ADR-0014, ADR-0022).
+//
+// fleet_list / fleet_tools / fleet_call are the fixed tool surface; fleet_read,
+// fleet_fetch and fleet_run are typed shortcuts over the same fleet.call path.
+import { DirectCallClient } from './direct-call.js'
+
+/** Shared text output contract (same shape the harness's own tools use). */
+export function textOutput() {
+  return {
+    schema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: { text: { type: 'string', required: true } },
+    },
+    render: (_args, value) => [{ type: 'text', text: value.text }],
+  }
+}
+
+function fail(error) {
+  const code = error?.code ?? 'error'
+  return { text: `Error: [${String(code)}] ${String(error?.message ?? error)}` }
+}
+
+/** Pure handlers; wrapped into ToolDefinitions by `createFleetToolDefinitions`. */
+export function createFleetHandlers({ node, client = new DirectCallClient({ node }), pairing = null }) {
+  return {
+    async fleet_invite() {
+      if (!pairing?.invite) return { text: 'Error: [unsupported] this device cannot create an invite' }
+      try {
+        const code = await pairing.invite()
+        return {
+          text: [
+            'Fleet invite for another device (single use, keep it private):',
+            '',
+            code,
+            '',
+            'On the other device install this plugin, then ask its agent to join with this code (`fleet_join`). It takes effect after that DSH restarts.',
+          ].join('\n'),
+        }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_join({ code }) {
+      if (!pairing?.join) return { text: 'Error: [unsupported] this device cannot join a fleet' }
+      try {
+        await pairing.join(code)
+        return { text: 'Invite queued. Restart DSH on this device; the plugin will enroll on the next load and then be able to reach the Fleet.' }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_list() {
+      const lines = []
+      lines.push(`this device: ${node.identity.deviceId} (${node.name})`)
+      const seen = new Set([node.identity.deviceId])
+      const online = new Set(node.peerIds())
+      const discovered = new Map([...node.discovered.values()].map((peer) => [peer.deviceId, peer]))
+      for (const entry of node.rosterEntries()) {
+        if (seen.has(entry.deviceId)) continue
+        seen.add(entry.deviceId)
+        lines.push(`- ${entry.deviceId} (${entry.name ?? 'device'}) ${online.has(entry.deviceId) ? 'online' : 'offline'}${online.has(entry.deviceId) ? '' : ' — direct calls fail while offline'}`)
+      }
+      for (const [deviceId, peer] of discovered) {
+        if (seen.has(deviceId)) continue
+        seen.add(deviceId)
+        lines.push(`- ${deviceId} (${peer.name ?? 'device'}) discovered${online.has(deviceId) ? ', online' : ''}`)
+      }
+      if (lines.length === 1) lines.push('(no other devices known yet; pair/enroll one with an invite first)')
+      return { text: lines.join('\n') }
+    },
+
+    async fleet_tools({ device }) {
+      try {
+        const result = await client.listTools(device)
+        const tools = Array.isArray(result?.tools) ? result.tools : []
+        if (tools.length === 0) return { text: `(no tools visible on ${device})` }
+        const lines = tools.map((tool) => `- ${tool.name}${tool.description ? `: ${String(tool.description).slice(0, 160)}` : ''}`)
+        return { text: lines.join('\n') }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_call({ device, tool, parameters }) {
+      try {
+        const result = await client.call(device, { capability: 'tool', tool, args: parameters ?? {} })
+        return { text: client.render(result) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_read({ device, path, offset, limit }) {
+      try {
+        const args = { file_path: path }
+        if (offset !== undefined) args.offset = offset
+        if (limit !== undefined) args.limit = limit
+        const result = await client.call(device, { capability: 'read', tool: 'read', args })
+        return { text: client.render(result) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_fetch({ device, path }) {
+      try {
+        const result = await client.call(device, { capability: 'fetch', args: { path } })
+        return { text: client.render(result) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+
+    async fleet_run({ device, command }) {
+      try {
+        const result = await client.call(device, { capability: 'run', args: { command } })
+        return { text: client.render(result) }
+      } catch (error) {
+        return fail(error)
+      }
+    },
+  }
+}
+
+/** Build the model-facing ToolDefinitions once `defineTool` is available. */
+export function createFleetToolDefinitions({ defineTool, handlers }) {
+  const output = textOutput()
+  const commonDevice = { type: 'string', required: true, description: 'Target device id from `fleet_list`.' }
+  return [
+    defineTool({
+      name: 'fleet_invite',
+      description:
+        'Create a Fleet invite code for another device. Only do this when the user asks to pair a new device. Treat the returned code as a secret; it carries the fleet key.',
+      parameters: {},
+      output,
+      execute: () => handlers.fleet_invite(),
+    }),
+    defineTool({
+      name: 'fleet_join',
+      description:
+        'Join an existing Fleet with an invite code from `fleet_invite` on another device. The enrollment is queued and takes effect after DSH restarts on this device.',
+      parameters: {
+        code: { type: 'string', required: true, description: 'Invite code produced by fleet_invite on another device.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_join(args),
+    }),
+    defineTool({
+      name: 'fleet_list',
+      description:
+        'List the devices in this Fleet with their online status. Call it before any `fleet_*` call to learn which device id to use. Offline devices are listed too, but direct calls to them fail fast; use a Room/delegation instead of waiting.',
+      parameters: {},
+      output,
+      execute: () => handlers.fleet_list(),
+    }),
+    defineTool({
+      name: 'fleet_tools',
+      description:
+        'List the tools another device exposes to direct calls (name + description). Use it only when you need an untyped tool; the typed shortcuts `fleet_read` / `fleet_fetch` / `fleet_run` cover the common cases.',
+      parameters: { device: commonDevice },
+      output,
+      execute: (args) => handlers.fleet_tools(args),
+    }),
+    defineTool({
+      name: 'fleet_call',
+      description:
+        'Call one tool on another device directly. Direct calls are stateless: no Room, no shared conversation, no remote history. Use `fleet_tools` first to discover names/arguments, or prefer the typed shortcuts. The target device decides whether to allow, ask its user, or reject.',
+      parameters: {
+        device: commonDevice,
+        tool: { type: 'string', required: true, description: 'Tool name on the target device.' },
+        parameters: { type: 'object', additionalProperties: true, description: 'Arguments object for that tool.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_call(args),
+    }),
+    defineTool({
+      name: 'fleet_read',
+      description:
+        'Read a file on another device (shortcut over `fleet_call` with the target `read` tool). Paths must be inside the roots that device allows. Use it to inspect logs/docs on another machine without opening a Room.',
+      parameters: {
+        device: commonDevice,
+        path: { type: 'string', required: true, description: 'Absolute path on the target device.' },
+        offset: { type: 'number', description: 'Line offset, when supported by the target read tool.' },
+        limit: { type: 'number', description: 'Maximum lines to return.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_read(args),
+    }),
+    defineTool({
+      name: 'fleet_fetch',
+      description:
+        'Fetch a file from another device and return its text content. Use it for "look at B\'s file and bring it over"; for large binaries prefer `fleet_run` with a transfer command.',
+      parameters: {
+        device: commonDevice,
+        path: { type: 'string', required: true, description: 'Absolute path on the target device.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_fetch(args),
+    }),
+    defineTool({
+      name: 'fleet_run',
+      description:
+        'Run a shell command on another device (shortcut over `fleet_call` with the target shell tool). The target device\'s Tool Policy decides whether the command is auto-allowed, needs its local approval, or is rejected; an offline or timed-out approval fails. Use it for builds/tests and other work that belongs on that machine.',
+      parameters: {
+        device: commonDevice,
+        command: { type: 'string', required: true, description: 'Shell command to run on the target device.' },
+      },
+      output,
+      execute: (args) => handlers.fleet_run(args),
+    }),
+  ]
+}

package/src/index.js

@@ -0,0 +1,3 @@
+// Placeholder entry for the DSH plugin. The Host/Client halves land in a later
+// step; for now the network layer is exported so it can be tested and reused.
+export * as net from './net/index.js'

package/src/net/direct.js

@@ -0,0 +1,69 @@
+// Plain TCP direct transport: a listening server and an outbound dialer.
+// The secure channel runs on top; this module only owns sockets.
+import net from 'node:net'
+
+/**
+ * Start a direct listener.
+ * @param {{host?: string, port?: number}} [options]
+ * @returns {{server: net.Server, ready: Promise<{host: string, port: number}>, close: () => Promise<void>}}
+ */
+export function createDirectServer({ host = '0.0.0.0', port = 0 } = {}) {
+  const server = net.createServer({ allowHalfOpen: false })
+  const ready = new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening)
+      reject(error)
+    }
+    const onListening = () => {
+      server.off('error', onError)
+      const address = server.address()
+      resolve({ host: typeof address === 'object' && address ? address.address : host, port: address?.port ?? port })
+    }
+    server.once('error', onError)
+    server.once('listening', onListening)
+    server.listen(port, host)
+  })
+  return {
+    server,
+    ready,
+    close: () =>
+      new Promise((resolve) => {
+        if (!server.listening) return resolve()
+        server.close(() => resolve())
+      }),
+  }
+}
+
+/**
+ * Dial a direct endpoint.
+ * @param {{host: string, port: number, timeoutMs?: number}} options
+ * @returns {Promise<import('node:net').Socket>}
+ */
+export function connectDirect({ host, port, timeoutMs = 5_000 }) {
+  return new Promise((resolve, reject) => {
+    const socket = net.connect({ host, port })
+    const timer = setTimeout(() => {
+      cleanup()
+      socket.destroy()
+      const error = new Error(`direct connect to ${host}:${String(port)} timed out`)
+      error.code = 'connect-timeout'
+      reject(error)
+    }, timeoutMs)
+    timer.unref?.()
+    const cleanup = () => {
+      clearTimeout(timer)
+      socket.off('connect', onConnect)
+      socket.off('error', onError)
+    }
+    const onConnect = () => {
+      cleanup()
+      resolve(socket)
+    }
+    const onError = (error) => {
+      cleanup()
+      reject(error)
+    }
+    socket.once('connect', onConnect)
+    socket.once('error', onError)
+  })
+}

package/src/net/discovery.js

@@ -0,0 +1,105 @@
+// LAN discovery over UDP multicast. Announcements carry only a fleet hash,
+// device id, display name and the direct listening port; the real trust
+// decision happens in the secure-channel handshake.
+import dgram from 'node:dgram'
+import { EventEmitter } from 'node:events'
+import { fleetHash } from './identity.js'
+
+export const DEFAULT_DISCOVERY_GROUP = '239.255.42.99'
+export const DEFAULT_DISCOVERY_PORT = 47833
+
+export class LanDiscovery extends EventEmitter {
+  constructor({
+    fleetId,
+    deviceId,
+    name = 'device',
+    directPort,
+    group = DEFAULT_DISCOVERY_GROUP,
+    port = DEFAULT_DISCOVERY_PORT,
+    intervalMs = 3_000,
+  }) {
+    super()
+    this.fleetId = fleetId
+    this.deviceId = deviceId
+    this.name = name
+    this.directPort = directPort
+    this.group = group
+    this.port = port
+    this.intervalMs = intervalMs
+    this.socket = null
+    this.timer = null
+    this.closed = false
+    this.peers = new Map()
+  }
+
+  start() {
+    if (this.socket) return
+    this.socket = dgram.createSocket({ type: 'udp4', reuseAddr: true })
+    this.socket.on('message', (buffer, rinfo) => this.onMessage(buffer, rinfo))
+    this.socket.on('error', (error) => this.emit('error', error))
+    this.socket.bind(this.port, () => {
+      try {
+        this.socket.addMembership(this.group)
+        this.socket.setMulticastTTL(1)
+        this.socket.setMulticastLoopback(true)
+      } catch (error) {
+        this.emit('error', error)
+      }
+      this.announce()
+      this.timer = setInterval(() => this.announce(), this.intervalMs)
+      this.timer.unref?.()
+      this.emit('listening', { group: this.group, port: this.port })
+    })
+  }
+
+  announce() {
+    if (!this.socket || this.closed) return
+    const payload = Buffer.from(
+      JSON.stringify({
+        v: 1,
+        fleetHash: fleetHash(this.fleetId),
+        deviceId: this.deviceId,
+        name: this.name,
+        port: this.directPort,
+        ts: Date.now(),
+      }),
+    )
+    this.socket.send(payload, 0, payload.length, this.port, this.group, () => {})
+  }
+
+  onMessage(buffer, rinfo) {
+    if (this.closed) return
+    let message
+    try {
+      message = JSON.parse(buffer.toString('utf8'))
+    } catch {
+      return
+    }
+    if (message?.v !== 1) return
+    if (message.fleetHash !== fleetHash(this.fleetId)) return
+    if (typeof message.deviceId !== 'string' || message.deviceId === this.deviceId) return
+    if (typeof message.port !== 'number' || message.port <= 0) return
+    const peer = {
+      deviceId: message.deviceId,
+      name: typeof message.name === 'string' ? message.name : 'device',
+      host: rinfo.address,
+      port: message.port,
+      lastSeen: Date.now(),
+    }
+    this.peers.set(peer.deviceId, peer)
+    this.emit('peer', peer)
+  }
+
+  close() {
+    this.closed = true
+    clearInterval(this.timer)
+    if (this.socket) {
+      try {
+        this.socket.close()
+      } catch {
+        /* ignore */
+      }
+      this.socket = null
+    }
+  }
+}