dsh-foreman-node 0.0.0-stage → 0.1.1

package/src/protocol.ts

@@ -0,0 +1,160 @@
+/**
+ * The foreman protocol: one JSON frame per WebSocket text message, versioned by `v`.
+ *
+ * This file is the only definition of a frame. `dsh-foreman` (the hub) depends on
+ * this package and imports it, so the two sides cannot drift; nothing here may
+ * import a DSH service, the core domain, or a database.
+ */
+
+/** Bumped whenever a frame's shape changes incompatibly; a peer on another version is refused at handshake. */
+export const FOREMAN_PROTOCOL_VERSION = 1
+
+/** Largest frame accepted, in bytes of UTF-8. A larger one is refused, never truncated. */
+export const MAX_FRAME_BYTES = 256 * 1024
+
+/** A project a device can work on: the hub's logical name and the device's own absolute path. */
+export interface Root {
+  /** The project name both sides agree on; the hub never sees the device path before a job is assigned. */
+  project: string
+  /** An absolute path on the device. Kept verbatim, including spaces and non-ASCII characters. */
+  path: string
+}
+
+/** A file travelling with a task, base64-encoded. The device writes it where its job session can read it. */
+export interface FrameAttachment {
+  id: string
+  mediaType?: string
+  name?: string
+  bytes: string
+}
+
+/**
+ * What a device may report. `dropped` is deliberately absent: deciding that work
+ * should not be done is a judgement, and a device has none.
+ */
+export type NodeReportState = 'progress' | 'ready' | 'blocked' | 'failed'
+
+interface Base {
+  v: number
+  frameId: string
+}
+
+/** First frame a device sends on every connection; it states what it is running so the hub can align, rather than guess. */
+export interface HelloFrame extends Base {
+  type: 'hello'
+  deviceId: string
+  token: string
+  version: string
+  roots: Root[]
+  running: string[]
+}
+
+export interface HeartbeatFrame extends Base {
+  type: 'heartbeat'
+  deviceId: string
+  running: number
+}
+
+/** A task for the device. `text` is finished on the hub side: no resource pointer, no hub path. */
+export interface AssignFrame extends Base {
+  type: 'assign'
+  assignmentId: string
+  ticketId: string
+  /** An absolute path on the device, already mapped through its declared roots. */
+  directory: string
+  text: string
+  attachments: FrameAttachment[]
+  permissionPreset: string
+}
+
+export interface InputFrame extends Base {
+  type: 'input'
+  assignmentId: string
+  text: string
+  attachments: FrameAttachment[]
+}
+
+export interface StopFrame extends Base {
+  type: 'stop'
+  assignmentId: string
+  reason: string
+}
+
+export interface AcceptedFrame extends Base {
+  type: 'accepted'
+  assignmentId: string
+}
+
+export interface ReportFrame extends Base {
+  type: 'report'
+  assignmentId: string
+  state: NodeReportState
+  summary: string
+  question?: string
+}
+
+export interface AckFrame extends Base {
+  type: 'ack'
+  /** The `frameId` of the frame being acknowledged. */
+  of: string
+}
+
+/** Sent by the hub before it closes a connection it refuses, so the device can log why. */
+export interface ErrorFrame extends Base {
+  type: 'error'
+  reason: string
+}
+
+export type Frame =
+  | HelloFrame | HeartbeatFrame | AssignFrame | InputFrame | StopFrame
+  | AcceptedFrame | ReportFrame | AckFrame | ErrorFrame
+
+/** A frame the receiver cannot accept: wrong version, unknown type, malformed JSON, or over the size cap. */
+export class FrameError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'FrameError'
+  }
+}
+
+const TYPES = new Set(['hello', 'heartbeat', 'assign', 'input', 'stop', 'accepted', 'report', 'ack', 'error'])
+
+export function encodeFrame(frame: Frame): string {
+  return JSON.stringify(frame)
+}
+
+/**
+ * Parses one frame, refusing anything this build cannot honour.
+ * @throws FrameError for oversized text, malformed JSON, another protocol version, or an unknown type.
+ */
+export function parseFrame(text: string): Frame {
+  const size = Buffer.byteLength(text, 'utf8')
+  if (size > MAX_FRAME_BYTES) throw new FrameError(`frame too large: ${size} bytes, limit ${MAX_FRAME_BYTES}`)
+  let value: unknown
+  try {
+    value = JSON.parse(text)
+  } catch (error) {
+    throw new FrameError(`malformed frame: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  if (typeof value !== 'object' || value === null) throw new FrameError('a frame must be a JSON object')
+  const frame = value as Record<string, unknown>
+  const version = frame['v']
+  if (version !== FOREMAN_PROTOCOL_VERSION) {
+    throw new FrameError(`unsupported protocol version ${String(version)}; this build speaks ${FOREMAN_PROTOCOL_VERSION}`)
+  }
+  const type = frame['type']
+  if (typeof type !== 'string' || !TYPES.has(type)) throw new FrameError(`unknown frame type ${String(type)}`)
+  if (typeof frame['frameId'] !== 'string' || frame['frameId'] === '') throw new FrameError('a frame needs a frameId')
+  return frame as unknown as Frame
+}
+
+/** Remembers the frame ids a peer has already acted on, so a retried frame does nothing twice. */
+export class FrameDedupe {
+  constructor(private readonly seen: Set<string> = new Set()) {}
+  /** Returns true the first time a frame id is seen, false for a repeat. */
+  take(frameId: string): boolean {
+    if (this.seen.has(frameId)) return false
+    this.seen.add(frameId)
+    return true
+  }
+}

package/src/report-tool.ts

@@ -0,0 +1,93 @@
+/**
+ * The `foreman_report` tool a device registers on a job Session.
+ *
+ * Reporting is a hard requirement rather than a convenience: in the domain, "waiting for a person" is a structured
+ * fact that a report carries, and inferring it from a turn ending is an explicitly rejected approach. So a device
+ * states outcomes through this tool and nothing else.
+ *
+ * `dropped` is not in its enum. Deciding that work should not be done is a judgement, a device has no judgement, and
+ * the hub's ledger already refuses that state from a device (see the protocol). A device that believes the same thing
+ * must report `blocked` and let a person decide.
+ *
+ * The schema is written as JSON Schema and validated here rather than through `zod`, so this package stays free of
+ * runtime dependencies beyond the DSH services it is a peer plugin of.
+ */
+
+/** What a device may report; the same set the protocol's `NodeReportState` names. */
+export const REPORT_STATES = ['progress', 'ready', 'blocked', 'failed'] as const
+export type ReportState = typeof REPORT_STATES[number]
+
+/** A report as the tool's caller gives it. */
+export interface DeviceReport {
+  state: ReportState
+  summary: string
+  /** One question a person must answer; paired with `state: 'blocked'` in practice. */
+  question?: string
+}
+
+/** The host a tool reports through: the client that owns the connection, or a test. */
+export interface ReportHost {
+  report(assignmentId: string, report: DeviceReport): void
+}
+
+/** The parts of a tool definition DSH registers: name, description, JSON Schema, and the executor. */
+export interface DeviceTool {
+  name: string
+  description: string
+  parameters: Record<string, unknown>
+  execute(args: Record<string, unknown>, execution: { signal: AbortSignal }): Promise<unknown>
+}
+
+/** The JSON Schema a model sees, which is also what `execute` validates against. */
+const PARAMETERS: Record<string, unknown> = {
+  type: 'object',
+  additionalProperties: false,
+  required: ['state', 'summary'],
+  properties: {
+    state: { type: 'string', enum: [...REPORT_STATES], description: 'progress while working, ready when the result is in, blocked when a person must act, failed when the work cannot be done.' },
+    summary: { type: 'string', minLength: 1, description: 'What was done, or what is needed, in one or two sentences.' },
+    question: { type: 'string', minLength: 1, description: 'One concrete question for a person, with state=blocked.' },
+  },
+}
+
+/** Thrown for arguments this tool refuses; the model sees the message and can correct itself. */
+class ReportRefusal extends Error {
+  constructor(message: string) { super(message); this.name = 'ReportRefusal' }
+}
+
+/** Validate the arguments to a report, refusing `dropped`, an unknown state, or an empty summary. */
+export function readReport(args: Record<string, unknown>): DeviceReport {
+  const state = args['state']
+  if (typeof state !== 'string') throw new ReportRefusal('state must be a string')
+  if (state === 'dropped') {
+    throw new ReportRefusal('a device may not report dropped: deciding that work should not be done is the hub\'s judgement, so report blocked instead')
+  }
+  if (!(REPORT_STATES as readonly string[]).includes(state)) {
+    throw new ReportRefusal(`state must be one of ${REPORT_STATES.join(', ')}, not ${state}`)
+  }
+  const summary = typeof args['summary'] === 'string' ? args['summary'].trim() : ''
+  if (summary === '') throw new ReportRefusal('summary must say what was done or what is needed')
+  const question = typeof args['question'] === 'string' ? args['question'].trim() : undefined
+  if (args['question'] !== undefined && (question === undefined || question === '')) {
+    throw new ReportRefusal('question must be a question when given')
+  }
+  return { state: state as ReportState, summary, ...(question === undefined ? {} : { question }) }
+}
+
+/**
+ * Build the `foreman_report` tool for one assignment.
+ *
+ * The assignment id is bound here rather than passed by the model: a job Session reports on the assignment it was
+ * started for, and a model should not be able to name a different one.
+ */
+export function foremanReportTool(host: ReportHost, assignmentId: string): DeviceTool {
+  return {
+    name: 'foreman_report',
+    description: 'Report this job to the foreman: progress, ready, blocked or failed, with a one-sentence summary and, when a person must answer, one question.',
+    parameters: PARAMETERS,
+    async execute(args) {
+      host.report(assignmentId, readReport(args))
+      return { reported: true }
+    },
+  }
+}

package/src/session.ts

@@ -0,0 +1,156 @@
+/**
+ * Job sessions on a device: one Session per assignment, in the directory the hub named.
+ *
+ * This is the device-side counterpart of `Sessions.ensure` on the hub, and it deliberately sets a different
+ * permission preset. A hub session runs with `danger-full-access` because a person is sitting in front of it and
+ * approves; a job session runs `workspace-write` inside a directory the device declared, because nobody is there to
+ * answer a prompt. Work that needs more is reported `blocked`, not silently elevated.
+ *
+ * Nothing here touches the hub's domain, its database, or its policy: a device has no ledger.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-api-session-controller'
+import type {} from '@deepseek-ai/dsh-workspace'
+import type {} from '@deepseek-ai/dsh-permission-presets'
+import type {} from '@deepseek-ai/dsh-session-persistence'
+import type {} from '@deepseek-ai/dsh-tools'
+import { MessageId, freezeMessage } from '@deepseek-ai/dsh-llm'
+import { foremanReportTool, type DeviceReport } from './report-tool.ts'
+
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'dsh-foreman-node': { kind: 'dsh-foreman-node'; form: 'relay' }
+  }
+}
+
+/** The permission preset a job runs under: bounded to the directory the device declared. */
+export const JOB_PRESET = 'workspace-write'
+
+/** The Session a job runs in, named the way a hub names its own worker: `job-<assignmentId>`. */
+export const jobSessionId = (assignmentId: string): string => `job-${assignmentId}`
+
+/** The message id of one delivery, derived from the hub's request id so a redelivery adds nothing. */
+const requestMessage = (requestId: string): MessageId => MessageId(`dsh-foreman-node:${requestId}`)
+
+export interface EnsureInput {
+  assignmentId: string
+  /** The absolute directory on this device; the hub mapped it through the device's declared roots. */
+  directory: string
+  title: string
+}
+
+/** What the tool registrar looks like, narrowed to what this file uses. */
+export interface ToolRegistrar {
+  register(definition: { name: string; description: string; parameters: Record<string, unknown>
+    output: { schema: Record<string, unknown>; render: (args: unknown, value: unknown) => unknown }
+    execute: (args: unknown, execution: { signal: AbortSignal }) => Promise<unknown> }): unknown
+}
+
+/**
+ * Keeps the device's job Sessions and delivers work into them.
+ *
+ * A Session is created only when it does not exist yet, so a redelivered `assign` reuses the Session and the work
+ * already in it instead of starting a second one. Delivery is idempotent by request id: the hub retrying a frame
+ * that it never saw acknowledged cannot append the task twice.
+ */
+export class JobSessions {
+  /** Jobs by assignment id, so `running()` reports what this device actually holds rather than what it was told. */
+  private readonly jobs = new Map<string, string>()
+  /** Assignments whose Session already carries the report tool, so a redelivered assign registers it only once. */
+  private readonly reported = new Set<string>()
+
+  constructor(private readonly ctx: Context) {}
+
+  /**
+   * Resolve or create the `job-<assignmentId>` Session in the given directory, attach its `foreman_report` tool, and
+   * register it so a heartbeat counts it.
+   *
+   * The tool is attached here rather than left to the caller because it is the only way a device can say what
+   * happened: without it a job Session's model has no `progress`/`ready`/`blocked`/`failed` channel, the hub waits
+   * forever, and the whole design's "never infer state from session events" requirement is moot. Registration is
+   * idempotent per assignment, so a redelivered `assign` does not stack a second tool on the same Session.
+   *
+   * @returns the Session id.
+   */
+  async ensure(input: EnsureInput, onReport?: (assignmentId: string, report: DeviceReport) => void): Promise<string> {
+    const id = jobSessionId(input.assignmentId)
+    const workspace = await this.ctx.workspaceRegistry.create(input.directory)
+    let result = await this.ctx.sessionController.resolveAgent(id as SessionId)
+    if ('error' in result && result.error.code === 'session/not-found') {
+      await this.ctx.sessionController.create({ sessionId: id as SessionId, workspaceId: workspace.id })
+      result = await this.ctx.sessionController.resolveAgent(id as SessionId)
+    }
+    if ('error' in result) throw result.error
+    await workspace.attachSession(id as SessionId)
+    // The one place the device's policy differs from the hub's: bounded, because no person is here to approve more.
+    this.ctx.permissionPresets.set(result.agent.session, JOB_PRESET)
+    await this.ctx.sessionController.rename({ sessionId: id as SessionId, title: input.title })
+    if (onReport !== undefined && !this.reported.has(input.assignmentId)) {
+      this.reported.add(input.assignmentId)
+      try { this.reportTools(result.agent as Agent, input.assignmentId, onReport) }
+      catch (error) {
+        // A Session that refuses the tool would never report: forget the guard so a later assign retries it.
+        this.reported.delete(input.assignmentId)
+        throw new Error(`could not attach foreman_report to ${id}: ${String(error)}`)
+      }
+    }
+    this.jobs.set(input.assignmentId, id)
+    return id
+  }
+
+  /**
+   * Deliver a task into its job Session, once per request id.
+   *
+   * `queue` rather than `steer` on the first delivery: the job's task should start a turn, not interrupt one that is
+   * already running. A redelivery finds the message already recorded and adds nothing.
+   */
+  async deliver(sessionId: string, text: string, requestId: string): Promise<void> {
+    const result = await this.ctx.sessionController.resolveAgent(sessionId as SessionId)
+    if ('error' in result) throw result.error
+    const agent = result.agent as Agent
+    if (await this.holds(agent, requestId)) return
+    const source = { kind: 'dsh-foreman-node' as const, form: 'relay' as const }
+    agent.followup(freezeMessage({ id: requestMessage(requestId), role: 'user' as const, content: [{ type: 'text' as const, text }], source }))
+    await this.ctx.sessionPersistence.flush()
+  }
+
+  /** Whether the Session already holds the delivery for `requestId`, in its live inbox or its stored history. */
+  async holds(agent: Agent, requestId: string): Promise<boolean> {
+    const id = requestMessage(requestId)
+    if ([...agent.inbox.nextTurn, ...agent.inbox.nextStep].some(message => message.id === id)) return true
+    try {
+      await this.ctx.sessionPersistence.flush()
+      await using handle = await this.ctx.sessionPersistence.open(agent.id, 'read')
+      for (let offset = 0; ;) {
+        const { events } = await handle.read(offset, 512)
+        if (events.length === 0) return false
+        for (const event of events) {
+          if (event.type === 'user/message' && (event.data as { id?: string }).id === id) return true
+        }
+        offset += events.length
+      }
+    } catch (error) {
+      // A Session whose history cannot be read is not proof of a delivery: deliver again rather than lose the task.
+      this.ctx.logger.warn('dsh-foreman-node could not read %s history: %s', agent.id, String(error))
+      return false
+    }
+  }
+
+  /** The assignment ids this device currently holds a job for: what a heartbeat and a reconnected hello report. */
+  running(): string[] { return [...this.jobs.keys()] }
+
+  /** Forget a job whose assignment the hub stopped, so this device stops reporting it as running. */
+  forget(assignmentId: string): void { this.jobs.delete(assignmentId) }
+
+  /** Attach the `foreman_report` tool to a job Session, disposed with it. */
+  reportTools(agent: Agent, assignmentId: string, onReport: (assignmentId: string, report: DeviceReport) => void): void {
+    const registrar = agent.ctx.tools
+    const tool = foremanReportTool({ report: onReport }, assignmentId)
+    registrar.register({ name: tool.name, description: tool.description, parameters: tool.parameters,
+      output: { schema: { type: 'object', additionalProperties: true },
+        render: (_args: unknown, value: unknown) => [{ type: 'text' as const, text: JSON.stringify(value) }] },
+      execute: (args: unknown, execution: { signal: AbortSignal }) => tool.execute(args as Record<string, unknown>, execution) })
+  }
+}