dsh-foreman-node 0.0.0-stage → 0.1.0

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) })
+  }
+}