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

package/src/host/direct-call.js

@@ -0,0 +1,190 @@
+// Direct-call host/client over the fleet RPC layer (ADR-0003, ADR-0004, ADR-0014).
+//
+// Host side runs on the resource-owner device: it applies Tool Policy, may ask
+// for local approval, then executes through the Execution Slot (or a direct fs
+// read for list/fetch). Client side runs on the caller device and backs the
+// `fleet_*` model tools.
+import { DEFAULT_SHELL_TOOL } from './execution-slot.js'
+
+const DEFAULT_POLICY_TIMEOUT_MS = 60_000
+
+function toolText(result) {
+  if (!result) return ''
+  if (result.isError) return `Error: ${result.text || 'tool failed'}`
+  return result.text ?? ''
+}
+
+export class DirectCallHost {
+  /**
+   * @param {object} options
+   * @param {object} options.slot ExecutionSlot
+   * @param {import('./tool-policy.js').ToolPolicy} options.policy
+   * @param {{resolve: Function, listDir: Function, stat?: Function, readText?: Function}} [options.fs]
+   * @param {(request: object) => Promise<boolean>} [options.requestApproval]
+   * @param {string} options.deviceId
+   * @param {string} [options.name]
+   * @param {string} [options.pluginVersion]
+   * @param {string} [options.dshVersion]
+   * @param {string[]} [options.capabilities]
+   * @param {string} [options.shellTool]
+   */
+  constructor({
+    slot,
+    policy,
+    fs,
+    requestApproval,
+    deviceId,
+    name = 'device',
+    pluginVersion = '0.0.0',
+    dshVersion = 'unknown',
+    capabilities = [],
+    shellTool = DEFAULT_SHELL_TOOL,
+    approvalTimeoutMs = DEFAULT_POLICY_TIMEOUT_MS,
+  }) {
+    this.slot = slot
+    this.policy = policy
+    this.fs = fs
+    this.requestApproval = requestApproval
+    this.deviceId = deviceId
+    this.name = name
+    this.pluginVersion = pluginVersion
+    this.dshVersion = dshVersion
+    this.capabilities = capabilities
+    this.shellTool = shellTool
+    this.approvalTimeoutMs = approvalTimeoutMs
+  }
+
+  info() {
+    return {
+      deviceId: this.deviceId,
+      name: this.name,
+      pluginVersion: this.pluginVersion,
+      dshVersion: this.dshVersion,
+      capabilities: this.capabilities,
+      policy: this.policy.summarize(),
+    }
+  }
+
+  async handleRequest({ deviceId, method, params }) {
+    switch (method) {
+      case 'fleet.ping':
+        return { pong: true, deviceId: this.deviceId }
+      case 'fleet.info':
+        return this.info()
+      case 'fleet.tools':
+        return { deviceId: this.deviceId, tools: await this.slot.listTools(), policy: this.policy.summarize() }
+      case 'fleet.call':
+        return this.handleCall({ fromDeviceId: deviceId, request: params ?? {} })
+      default:
+        throw Object.assign(new Error(`unknown fleet method: ${String(method)}`), { code: 'unknown-method' })
+    }
+  }
+
+  async handleCall({ fromDeviceId, request }) {
+    const capability = request.capability ?? 'tool'
+    const tool = request.tool ?? null
+    const args = request.args ?? {}
+    const decision = this.policy.decide({ capability, tool, args })
+    if (decision.decision === 'deny') {
+      throw Object.assign(new Error(decision.reason), { code: 'denied', data: { capability, tool } })
+    }
+    if (decision.decision === 'ask') {
+      const approved = await this.askApproval({ fromDeviceId, capability, tool, args, reason: decision.reason })
+      if (!approved) throw Object.assign(new Error('local approval was not granted'), { code: 'approval_denied' })
+      this.policy.grant(decision.key, { scope: 'once' })
+    }
+    const startedAt = Date.now()
+    const result = await this.execute({ capability, tool, args })
+    return {
+      ...result,
+      meta: {
+        ...(result.meta ?? {}),
+        capability,
+        tool,
+        deviceId: this.deviceId,
+        durationMs: Date.now() - startedAt,
+      },
+    }
+  }
+
+  async askApproval({ fromDeviceId, capability, tool, args, reason }) {
+    if (typeof this.requestApproval !== 'function') return false
+    try {
+      const approved = await this.requestApproval({ fromDeviceId, capability, tool, args, reason })
+      return approved === true
+    } catch {
+      return false
+    }
+  }
+
+  async execute({ capability, tool, args }) {
+    switch (capability) {
+      case 'read':
+      case 'grep':
+      case 'run':
+      case 'tool': {
+        const name = capability === 'run' ? this.shellTool : tool
+        if (typeof name !== 'string' || name === '') {
+          throw Object.assign(new Error(`capability ${capability} needs a tool name`), { code: 'bad-request' })
+        }
+        return this.slot.executeTool({ name, args })
+      }
+      case 'list':
+        return this.readDirectory(args)
+      case 'fetch':
+        return this.fetchFile(args)
+      default:
+        throw Object.assign(new Error(`unsupported capability: ${String(capability)}`), { code: 'unsupported' })
+    }
+  }
+
+  async readDirectory(args) {
+    if (!this.fs) throw Object.assign(new Error('filesystem is unavailable'), { code: 'unsupported' })
+    const path = String(args?.path ?? args?.dir ?? '')
+    if (!path) throw Object.assign(new Error('list needs path'), { code: 'bad-request' })
+    const target = await this.fs.resolve(path)
+    const entries = await this.fs.listDir(target)
+    const lines = entries.map((entry) => `${entry.type}\t${entry.name}${entry.size === undefined ? '' : `\t${entry.size}`}`)
+    return { isError: false, text: lines.join('\n') || '(empty directory)', content: [], meta: { path } }
+  }
+
+  async fetchFile(args) {
+    if (!this.fs) throw Object.assign(new Error('filesystem is unavailable'), { code: 'unsupported' })
+    const path = String(args?.path ?? '')
+    if (!path) throw Object.assign(new Error('fetch needs path'), { code: 'bad-request' })
+    const target = await this.fs.resolve(path)
+    if (typeof this.fs.readText !== 'function') {
+      throw Object.assign(new Error('fetch is unavailable on this device'), { code: 'unsupported' })
+    }
+    const text = await this.fs.readText(target)
+    return { isError: false, text, content: [], meta: { path, bytes: Buffer.byteLength(text) } }
+  }
+}
+
+export class DirectCallClient {
+  constructor({ node }) {
+    this.node = node
+  }
+
+  async info(deviceId) {
+    return this.node.request(deviceId, 'fleet.info', {})
+  }
+
+  async listTools(deviceId) {
+    return this.node.request(deviceId, 'fleet.tools', {})
+  }
+
+  async call(deviceId, { capability, tool = null, args = {} }, options = {}) {
+    return this.node.request(deviceId, 'fleet.call', { capability, tool, args }, options)
+  }
+
+  /** Format a remote result for a model-facing text tool. */
+  render(result) {
+    if (result?.isError) return `Error: ${result.text || 'remote tool failed'}`
+    const meta = result?.meta ?? {}
+    const footer = meta.durationMs !== undefined ? `\n[${String(meta.capability ?? 'call')} on ${String(meta.deviceId ?? 'peer')} · ${String(meta.durationMs)}ms]` : ''
+    return `${result?.text ?? ''}${footer}`.trim()
+  }
+}
+
+export { toolText }

package/src/host/execution-slot.js

@@ -0,0 +1,82 @@
+// Execution Slot: a hidden DSH session/agent that gives remote direct calls a
+// legal tool-execution context (cwd, sandbox policy, approval routing) without
+// running any model turn. See ADR-0003 and ADR-0019.
+import { randomUUID } from 'node:crypto'
+
+export const DEFAULT_SHELL_TOOL = process.platform === 'win32' ? 'pwsh' : 'bash'
+
+export class ExecutionSlot {
+  /**
+   * @param {{sessionController: object, tools: object, config?: {cwd?: string, agentPreset?: string}}} options
+   */
+  constructor({ sessionController, tools, config = {} }) {
+    this.sessionController = sessionController
+    this.tools = tools
+    this.config = config
+    this.agent = null
+    this.sessionId = null
+    this.initializing = null
+  }
+
+  async ensureAgent() {
+    if (this.agent) return this.agent
+    if (this.initializing) return this.initializing
+    this.initializing = (async () => {
+      const created = await this.sessionController.create({
+        cwd: this.config.cwd,
+        agentPreset: this.config.agentPreset,
+      })
+      const sessionId = created?.sessionId
+      if (!sessionId) throw Object.assign(new Error('execution slot could not create a session'), { code: 'slot-unavailable' })
+      const resolved = await this.sessionController.resolveAgent(sessionId)
+      if (!resolved?.agent) {
+        const reason = resolved?.error?.code ?? 'session/agent-busy'
+        throw Object.assign(new Error(`execution slot agent unavailable: ${String(reason)}`), { code: 'slot-unavailable' })
+      }
+      this.sessionId = sessionId
+      this.agent = resolved.agent
+      return this.agent
+    })().finally(() => {
+      this.initializing = null
+    })
+    return this.initializing
+  }
+
+  /** Model-facing tool schemas visible to the execution slot agent. */
+  async listTools() {
+    const agent = await this.ensureAgent()
+    const schemas = this.tools.schemas?.(agent) ?? this.tools.schemas?.() ?? []
+    return schemas
+  }
+
+  /**
+   * Execute one tool inside the slot context and normalize the result.
+   * @param {{name: string, args: object, signal?: AbortSignal}} call
+   */
+  async executeTool({ name, args = {}, signal }) {
+    const agent = await this.ensureAgent()
+    const batch = await this.tools.execute({
+      calls: [{ id: randomUUID(), name, arguments: JSON.stringify(args ?? {}) }],
+      agent,
+      signal,
+    })
+    const first = batch?.results?.[0]?.result
+    if (!first) throw Object.assign(new Error(`tool ${name} returned no result`), { code: 'tool-no-result' })
+    const text = (first.content ?? [])
+      .map((block) => (block?.type === 'text' ? block.text : `[${String(block?.type ?? 'block')}]`))
+      .join('\n')
+    return {
+      isError: first.isError === true,
+      text,
+      content: first.content ?? [],
+      error: first.error ?? null,
+      meta: first.meta ?? null,
+    }
+  }
+
+  /** Tool names currently visible to the slot agent. */
+  async toolNames() {
+    const tools = await this.listTools()
+    return tools.map((tool) => tool.name).filter((name) => typeof name === 'string')
+  }
+}

package/src/host/index.js

@@ -0,0 +1,6 @@
+// Public host-side exports for the fleet plugin.
+export * from './store.js'
+export * from './tool-policy.js'
+export * from './execution-slot.js'
+export * from './direct-call.js'
+export * from './tools.js'

package/src/host/store.js

@@ -0,0 +1,128 @@
+// Persistent device state for the fleet plugin: identity, fleet, roster, config.
+// Everything lives under `$DSH_HOME/device-fleet/` (or DEVICE_FLEET_DATA_DIR).
+import fs from 'node:fs'
+import path from 'node:path'
+import { createFleet, decodeInvite, encodeInvite, generateIdentity } from '../net/identity.js'
+
+export function resolveDataDir({ dshHome, override } = {}) {
+  if (override) return path.resolve(override)
+  if (process.env.DEVICE_FLEET_DATA_DIR) return path.resolve(process.env.DEVICE_FLEET_DATA_DIR)
+  const home = dshHome ?? process.env.DSH_HOME ?? process.cwd()
+  return path.join(home, 'device-fleet')
+}
+
+function readJson(file, fallback) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'))
+  } catch {
+    return fallback
+  }
+}
+
+function writeJsonAtomic(file, value) {
+  fs.mkdirSync(path.dirname(file), { recursive: true })
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`
+  fs.writeFileSync(tmp, JSON.stringify(value, null, 2))
+  fs.renameSync(tmp, file)
+}
+
+/**
+ * Load or create the persistent device state.
+ * @returns {{dataDir: string, identity: object, fleet: object, roster: object[], config: object, enrollment: object|null, createdFleet: boolean}}
+ */
+export function loadState({ dshHome, dataDir, name = 'device' } = {}) {
+  const dir = resolveDataDir({ dshHome, override: dataDir })
+  fs.mkdirSync(dir, { recursive: true })
+
+  let identity = readJson(path.join(dir, 'identity.json'), null)
+  if (!identity) {
+    identity = generateIdentity({ name })
+    writeJsonAtomic(path.join(dir, 'identity.json'), identity)
+  }
+
+  let createdFleet = false
+  let fleet = readJson(path.join(dir, 'fleet.json'), null)
+  if (!fleet) {
+    fleet = createFleet({ name: `${name} fleet` })
+    writeJsonAtomic(path.join(dir, 'fleet.json'), fleet)
+    createdFleet = true
+  }
+
+  const roster = readJson(path.join(dir, 'roster.json'), [])
+  const config = readJson(path.join(dir, 'config.json'), {})
+  let enrollment = readJson(path.join(dir, 'enrollment.json'), null)
+  let pendingEnrollment = readJson(path.join(dir, 'enrollment.pending.json'), null)
+
+  // A pending invite written by `fleet_join` takes effect on the next load:
+  // enrolling while the network node is already running would leave the two
+  // sides on different fleets.
+  if (pendingEnrollment?.code) {
+    try {
+      const decoded = decodeInvite(pendingEnrollment.code)
+      fleet = decoded.fleet
+      enrollment = {
+        joinedAt: Date.now(),
+        accountFingerprint: decoded.accountFingerprint ?? null,
+        relay: decoded.relay ?? null,
+      }
+      writeJsonAtomic(path.join(dir, 'fleet.json'), fleet)
+      writeJsonAtomic(path.join(dir, 'enrollment.json'), enrollment)
+      fs.unlinkSync(path.join(dir, 'enrollment.pending.json'))
+      pendingEnrollment = null
+    } catch {
+      // Keep the pending file; the user can fix the invite and restart again.
+    }
+  }
+
+  return { dataDir: dir, identity, fleet, roster: Array.isArray(roster) ? roster : [], config, enrollment, pendingEnrollment, createdFleet }
+}
+
+/** Queue an invite for the next plugin load (the running node keeps its fleet). */
+export function writePendingEnrollment(state, code) {
+  decodeInvite(code) // validate before writing
+  writeJsonAtomic(path.join(state.dataDir, 'enrollment.pending.json'), { code, queuedAt: Date.now() })
+}
+
+export function saveIdentity(state) {
+  writeJsonAtomic(path.join(state.dataDir, 'identity.json'), state.identity)
+}
+
+export function saveFleet(state) {
+  writeJsonAtomic(path.join(state.dataDir, 'fleet.json'), state.fleet)
+}
+
+export function saveRoster(state, roster) {
+  state.roster = roster
+  writeJsonAtomic(path.join(state.dataDir, 'roster.json'), roster)
+}
+
+export function saveConfig(state, config) {
+  state.config = config
+  writeJsonAtomic(path.join(state.dataDir, 'config.json'), config)
+}
+
+/** Create an invite for this device's fleet. */
+export function createInvite(state, { accountFingerprint = null, relay = null } = {}) {
+  return encodeInvite({ fleet: state.fleet, accountFingerprint, relay })
+}
+
+/** Join a fleet from an invite code (overwrites fleet/enrollment, keeps identity). */
+export function enrollFromInvite(state, code) {
+  const decoded = decodeInvite(code)
+  state.fleet = decoded.fleet
+  state.enrollment = {
+    joinedAt: Date.now(),
+    accountFingerprint: decoded.accountFingerprint ?? null,
+    relay: decoded.relay ?? null,
+  }
+  saveFleet(state)
+  writeJsonAtomic(path.join(state.dataDir, 'enrollment.json'), state.enrollment)
+  return state.enrollment
+}
+
+/** Check a locally observed account fingerprint against the invite's binding. */
+export function accountMatches(state, fingerprint) {
+  const expected = state.enrollment?.accountFingerprint ?? null
+  if (!expected) return true // unbound invite: accept the first account and caller may bind
+  return fingerprint !== null && fingerprint === expected
+}

package/src/host/tool-policy.js

@@ -0,0 +1,150 @@
+// Target-device tool policy (ADR-0004, ADR-0019, ADR-0020).
+// The policy owns: allowed roots, per-capability mode (auto/ask/deny),
+// 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 DEFAULT_POLICY = Object.freeze({
+  allowedRoots: [],
+  capabilities: {
+    read: 'auto',
+    list: 'auto',
+    grep: 'auto',
+    fetch: 'auto',
+    run: 'ask',
+    tool: 'deny',
+  },
+  allowedTools: [],
+  approvalTtlMs: 15 * 60 * 1000,
+})
+
+/** True when `candidate` resolves inside one of `roots`. */
+export function pathWithinRoots(roots, candidate) {
+  const resolved = path.resolve(String(candidate))
+  return roots.some((root) => {
+    const base = path.resolve(String(root))
+    const relative = path.relative(base, resolved)
+    return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))
+  })
+}
+
+export class ToolPolicy {
+  constructor(config = {}) {
+    this.config = normalizeConfig(config)
+    /** @type {Map<string, {expiresAt: number, remaining: number}>} */
+    this.grants = new Map()
+  }
+
+  get roots() {
+    return this.config.allowedRoots
+  }
+
+  summarize() {
+    return {
+      allowedRoots: this.roots,
+      capabilities: { ...this.config.capabilities },
+      allowedTools: [...this.config.allowedTools],
+    }
+  }
+
+  /** Decide one call: { decision: 'allow' | 'ask' | 'deny', reason, key } */
+  decide({ capability, tool = null, args = {} } = {}) {
+    const capabilityName = CAPABILITIES.includes(capability) ? capability : 'tool'
+    const mode = this.config.capabilities[capabilityName] ?? 'deny'
+    const grantKey = `${capabilityName}:${capabilityName === 'tool' ? String(tool) : '*'}`
+    if (this.consumeGrant(grantKey)) return { decision: 'allow', reason: 'approved grant', key: grantKey, capability: capabilityName }
+
+    const paths = collectPaths(args)
+    const needsRoots = ['read', 'list', 'grep', 'fetch'].includes(capabilityName)
+    if (needsRoots) {
+      if (this.roots.length === 0) {
+        return { decision: 'deny', reason: 'no allowed roots configured on this device', key: grantKey, capability: capabilityName }
+      }
+      for (const candidate of paths) {
+        if (!pathWithinRoots(this.roots, candidate)) {
+          return {
+            decision: 'deny',
+            reason: `path is outside the allowed roots: ${String(candidate)}`,
+            key: grantKey,
+            capability: capabilityName,
+          }
+        }
+      }
+    }
+    if (capabilityName === 'run' && this.config.capabilities.run === 'allow') {
+      return { decision: 'allow', reason: 'run is allowed by policy', key: grantKey, capability: capabilityName }
+    }
+    if (capabilityName === 'tool') {
+      if (!this.config.allowedTools.includes(String(tool))) {
+        return {
+          decision: 'deny',
+          reason: `tool ${String(tool)} is not in the allowed tools list`,
+          key: grantKey,
+          capability: capabilityName,
+        }
+      }
+      return { decision: 'allow', reason: 'tool is allowlisted', key: grantKey, capability: capabilityName }
+    }
+    if (mode === 'allow') return { decision: 'allow', reason: 'capability is allowed by policy', key: grantKey, capability: capabilityName }
+    if (mode === 'auto') return { decision: 'allow', reason: 'capability is auto-approved', key: grantKey, capability: capabilityName }
+    if (mode === 'ask') return { decision: 'ask', reason: 'capability requires local approval', key: grantKey, capability: capabilityName }
+    return { decision: 'deny', reason: 'capability is disabled by policy', key: grantKey, capability: capabilityName }
+  }
+
+  /** Remember an approval as a expiring grant (TTL scope) or allow one call (once scope). */
+  grant(key, { scope = 'once', ttlMs = this.config.approvalTtlMs, now = Date.now() } = {}) {
+    if (typeof key !== 'string' || key === '') return
+    const current = this.grants.get(key)
+    if (scope === 'once') {
+      this.grants.set(key, { expiresAt: now + ttlMs, remaining: (current?.remaining ?? 0) + 1 })
+      return
+    }
+    this.grants.set(key, { expiresAt: now + ttlMs, remaining: Infinity })
+  }
+
+  consumeGrant(key) {
+    const grant = this.grants.get(key)
+    if (!grant) return false
+    if (grant.expiresAt <= Date.now()) {
+      this.grants.delete(key)
+      return false
+    }
+    if (Number.isFinite(grant.remaining)) {
+      grant.remaining -= 1
+      if (grant.remaining <= 0) this.grants.delete(key)
+    }
+    return true
+  }
+
+  revokeAll() {
+    this.grants.clear()
+  }
+}
+
+function normalizeConfig(config) {
+  const capabilities = { ...DEFAULT_POLICY.capabilities }
+  for (const [key, value] of Object.entries(config.capabilities ?? {})) {
+    if (CAPABILITIES.includes(key) && ['auto', 'ask', 'deny', 'allow'].includes(value)) capabilities[key] = value
+  }
+  return {
+    allowedRoots: Array.isArray(config.allowedRoots) ? config.allowedRoots.map(String) : [],
+    capabilities,
+    allowedTools: Array.isArray(config.allowedTools) ? config.allowedTools.map(String) : [],
+    approvalTtlMs:
+      Number.isFinite(config.approvalTtlMs) && config.approvalTtlMs > 0
+        ? config.approvalTtlMs
+        : DEFAULT_POLICY.approvalTtlMs,
+  }
+}
+
+function collectPaths(args) {
+  const paths = []
+  for (const key of ['path', 'file_path', 'cwd', 'dir', 'directory']) {
+    if (typeof args?.[key] === 'string' && args[key] !== '') paths.push(args[key])
+  }
+  if (Array.isArray(args?.paths)) {
+    for (const value of args.paths) if (typeof value === 'string' && value !== '') paths.push(value)
+  }
+  return paths
+}