dsh-foreman-node 0.0.0-stage → 0.1.0

package/lib/protocol.js

@@ -0,0 +1,69 @@
+// src/protocol.ts
+/**
+* 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. */
+const FOREMAN_PROTOCOL_VERSION = 1;
+/** Largest frame accepted, in bytes of UTF-8. A larger one is refused, never truncated. */
+const MAX_FRAME_BYTES = 262144;
+/** A frame the receiver cannot accept: wrong version, unknown type, malformed JSON, or over the size cap. */
+var FrameError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "FrameError";
+	}
+};
+const TYPES = /* @__PURE__ */ new Set([
+	"hello",
+	"heartbeat",
+	"assign",
+	"input",
+	"stop",
+	"accepted",
+	"report",
+	"ack",
+	"error"
+]);
+function encodeFrame(frame) {
+	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.
+*/
+function parseFrame(text) {
+	const size = Buffer.byteLength(text, "utf8");
+	if (size > 262144) throw new FrameError(`frame too large: ${size} bytes, limit ${MAX_FRAME_BYTES}`);
+	let value;
+	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;
+	const version = frame["v"];
+	if (version !== 1) throw new FrameError(`unsupported protocol version ${String(version)}; this build speaks 1`);
+	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;
+}
+/** Remembers the frame ids a peer has already acted on, so a retried frame does nothing twice. */
+var FrameDedupe = class {
+	seen;
+	constructor(seen = /* @__PURE__ */ new Set()) {
+		this.seen = seen;
+	}
+	/** Returns true the first time a frame id is seen, false for a repeat. */
+	take(frameId) {
+		if (this.seen.has(frameId)) return false;
+		this.seen.add(frameId);
+		return true;
+	}
+};
+export { FOREMAN_PROTOCOL_VERSION, FrameDedupe, FrameError, MAX_FRAME_BYTES, encodeFrame, parseFrame };

package/package.json

@@ -1,6 +1,96 @@
 {
   "name": "dsh-foreman-node",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Device side of dsh-foreman: connects out to a foreman hub, takes a job into a local DSH session, reports back. No ledger, no policy, no database.",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./protocol": {
+      "types": "./lib/protocol.d.ts",
+      "default": "./lib/protocol.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src",
+    "cordis.patch.yml",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "engines": {
+      "dsh": "^0.2.1-alpha.2"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "check": "pnpm typecheck && pnpm test && pnpm build"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/cosmokit": "1.8.5",
+    "@deepseek-ai/dsh-agent": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-api-session-controller": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-permission-presets": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-tools": "0.2.1-alpha.2",
+    "@deepseek-ai/dsh-workspace": "0.2.1-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.5-alpha.1",
+    "@types/node": "22.20.0",
+    "tsdown": "0.22.14",
+    "typescript": "6.0.3",
+    "vitest": "4.1.8"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "4.0.5-alpha.1",
+    "@deepseek-ai/cosmokit": "1.8.5",
+    "@deepseek-ai/dsh-agent": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-api-session-controller": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-permission-presets": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-session-persistence": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.2.1-alpha.2",
+    "@deepseek-ai/dsh-workspace": "^0.2.1-alpha.2",
+    "@deepseek-ai/schemastery": "3.18.5-alpha.1"
+  },
+  "license": "MIT",
+  "author": "niechao136",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/niechao136/dsh-foreman-node.git"
+  },
+  "homepage": "https://github.com/niechao136/dsh-foreman-node#readme",
+  "bugs": {
+    "url": "https://github.com/niechao136/dsh-foreman-node/issues"
+  },
+  "keywords": [
+    "dsh",
+    "dsh-plugin",
+    "deepseek-harness",
+    "foreman",
+    "worker",
+    "device"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/client.ts

@@ -0,0 +1,209 @@
+/**
+ * The device's outbound connection to its hub.
+ *
+ * The direction is deliberate: a device dials out, so a machine behind NAT or a company firewall can take work. The
+ * connection is never the device's to command — it reports what it holds, sends frames the hub asked for, and
+ * reconnects with exponential backoff on its own.
+ *
+ * A frame is never built here by hand: the protocol module owns every shape, so the device and the hub cannot drift.
+ * Nothing in this file writes a ledger, reads a policy, or opens a database — a device has none of those.
+ */
+import { FOREMAN_PROTOCOL_VERSION, FrameDedupe, encodeFrame, parseFrame, type Frame, type HeartbeatFrame, type HelloFrame,
+  type ReportFrame, type Root, type AcceptedFrame, type AckFrame } from './protocol.ts'
+
+/** What a socket has to offer; the global `WebSocket` satisfies it, and tests supply an object that does too. */
+export interface SocketLike {
+  readyState: number
+  send(data: string): void
+  close(): void
+  addEventListener(type: 'open' | 'close' | 'error', listener: () => void): void
+  addEventListener(type: 'message', listener: (event: { data: unknown }) => void): void
+}
+
+/** Opens a socket; injectable so tests never touch the network. */
+export type Connect = (url: string) => SocketLike
+
+export interface NodeClientInput {
+  /** The hub's stable address, such as `wss://foreman.example.com`. */
+  url: string
+  deviceId: string
+  /** The device token; sent in the hello and nowhere else. */
+  token: string
+  version: string
+  /** The projects this device can work on, as its own absolute paths. Declared once and re-declared on every hello. */
+  roots: () => Root[]
+  /** The assignments this device currently holds. Reported on every hello so the hub aligns instead of guessing. */
+  running: () => string[]
+  /** Handles frames the hub sends. */
+  onFrame: (frame: Frame) => void
+  /** Milliseconds before the first reconnect; doubles up to `maxReconnectMs`. */
+  reconnectMs?: number
+  maxReconnectMs?: number
+  connect?: Connect
+  /** The heartbeat interval; a device that says nothing looks offline to the hub, which turns its work blocked. */
+  heartbeatMs?: number
+  log?: (text: string) => void
+  /** Frame ids the device has already acted on, so a redelivered frame does nothing twice. */
+  dedupe?: FrameDedupe
+}
+
+const OPEN = 1
+
+/** A counter for frame ids; unique within one connection is enough, since the hub drops repeats by id. */
+let counter = 0
+/** A fresh frame id. Time-based so two processes do not collide, with a counter so two frames in one millisecond differ. */
+export const nextFrameId = (prefix: string): string => `${prefix}:${Date.now().toString(36)}:${(counter++).toString(36)}`
+
+/**
+ * Keeps one connection to the hub open, reconnecting with backoff.
+ *
+ * The class owns the socket's lifecycle and nothing else: what a frame means is the plugin's business, and what
+ * happens when the connection is refused is the hub's. `start` and `stop` are idempotent.
+ */
+export class NodeClient {
+  private socket?: SocketLike
+  private stopped = false
+  private reconnectTimer?: ReturnType<typeof setTimeout>
+  private heartbeatTimer?: ReturnType<typeof setInterval>
+  private delay: number
+  private readonly dedupe: FrameDedupe
+  private readonly connect: Connect
+  private readonly log: (text: string) => void
+
+  constructor(private readonly input: NodeClientInput) {
+    this.delay = input.reconnectMs ?? 1_000
+    this.dedupe = input.dedupe ?? new FrameDedupe(new Set())
+    this.connect = input.connect ?? (url => new WebSocket(url) as unknown as SocketLike)
+    this.log = input.log ?? (() => {})
+  }
+
+  /** Open the connection, or do nothing if it is already open or opening. */
+  start(): void {
+    if (this.stopped || this.socket !== undefined) return
+    this.open()
+  }
+
+  /** Close the connection and stop reconnecting; a late socket event does nothing. */
+  stop(): void {
+    this.stopped = true
+    if (this.reconnectTimer !== undefined) clearTimeout(this.reconnectTimer)
+    if (this.heartbeatTimer !== undefined) clearInterval(this.heartbeatTimer)
+    this.socket?.close()
+    this.socket = undefined
+  }
+
+  /** Send a frame now if the connection is open. Returns whether it went out, so a caller can retry later. */
+  send(frame: Frame): boolean {
+    if (this.socket === undefined || this.socket.readyState !== OPEN) return false
+    try {
+      this.socket.send(encodeFrame(frame))
+      return true
+    } catch (error) {
+      this.log(`dsh-foreman-node could not send ${frame.type}: ${String(error)}`)
+      return false
+    }
+  }
+
+  /** Report an outcome on an assignment, which is the only way a hub learns what a job did. */
+  report(assignmentId: string, report: { state: 'progress' | 'ready' | 'blocked' | 'failed'; summary: string; question?: string }): void {
+    const frame: ReportFrame = { v: FOREMAN_PROTOCOL_VERSION, type: 'report', frameId: nextFrameId('report'), assignmentId,
+      state: report.state, summary: report.summary, ...(report.question === undefined ? {} : { question: report.question }) }
+    this.send(frame)
+  }
+
+  /** Whether the connection is open right now. */
+  connected(): boolean { return this.socket !== undefined && this.socket.readyState === OPEN }
+
+  private open(): void {
+    let socket: SocketLike
+    try {
+      socket = this.connect(this.input.url)
+    } catch (error) {
+      this.log(`dsh-foreman-node could not open ${this.input.url}: ${String(error)}`)
+      this.scheduleReconnect()
+      return
+    }
+    this.socket = socket
+    socket.addEventListener('open', () => {
+      if (this.stopped) return
+      this.delay = this.input.reconnectMs ?? 1_000
+      this.hello()
+      this.startHeartbeat()
+    })
+    socket.addEventListener('message', event => {
+      if (this.stopped) return
+      const text = typeof event.data === 'string' ? event.data : String(event.data)
+      this.receive(text)
+    })
+    socket.addEventListener('error', () => {
+      // A socket error is followed by a close; reconnecting there keeps one path.
+      this.log('dsh-foreman-node connection error')
+    })
+    socket.addEventListener('close', () => {
+      if (this.stopped) return
+      if (this.heartbeatTimer !== undefined) clearInterval(this.heartbeatTimer)
+      this.socket = undefined
+      this.scheduleReconnect()
+    })
+  }
+
+  private hello(): void {
+    const frame: HelloFrame = { v: FOREMAN_PROTOCOL_VERSION, type: 'hello', frameId: nextFrameId('hello'), deviceId: this.input.deviceId,
+      token: this.input.token, version: this.input.version, roots: this.input.roots(), running: this.input.running() }
+    this.send(frame)
+  }
+
+  private startHeartbeat(): void {
+    if (this.heartbeatTimer !== undefined) clearInterval(this.heartbeatTimer)
+    this.heartbeatTimer = setInterval(() => {
+      const frame: HeartbeatFrame = { v: FOREMAN_PROTOCOL_VERSION, type: 'heartbeat', frameId: nextFrameId('heartbeat'),
+        deviceId: this.input.deviceId, running: this.input.running().length }
+      this.send(frame)
+    }, this.input.heartbeatMs ?? 15_000)
+    this.heartbeatTimer.unref?.()
+  }
+
+  private receive(text: string): void {
+    let frame: Frame
+    try {
+      frame = parseFrame(text)
+    } catch (error) {
+      // A frame this build cannot read is a hub speaking another protocol: say so in the log and keep the socket,
+      // because a dropped connection would only make the same misreading happen again.
+      this.log(`dsh-foreman-node refused a frame: ${String(error)}`)
+      return
+    }
+    if (!this.dedupe.take(frame.frameId)) return
+    if (frame.type === 'ack') return
+    if (frame.type === 'error') {
+      this.log(`dsh-foreman-node was refused by the hub: ${frame.reason}`)
+      return
+    }
+    this.input.onFrame(frame)
+  }
+
+  /** Acknowledge a frame once its side effect is done, so the hub can stop resending it. */
+  ack(frame: Frame): void {
+    const ack: AckFrame = { v: FOREMAN_PROTOCOL_VERSION, type: 'ack', frameId: nextFrameId('ack'), of: frame.frameId }
+    this.send(ack)
+  }
+
+  /** Tell the hub a frame's work reached its Session, which is what lets it mark the assignment started. */
+  accepted(assignmentId: string): void {
+    const frame: AcceptedFrame = { v: FOREMAN_PROTOCOL_VERSION, type: 'accepted', frameId: nextFrameId('accepted'), assignmentId }
+    this.send(frame)
+  }
+
+  private scheduleReconnect(): void {
+    if (this.stopped) return
+    const wait = this.delay
+    // Back off exponentially, but never past the cap: a hub down for an hour must not delay a reconnect by an hour.
+    this.delay = Math.min(this.delay * 2, this.input.maxReconnectMs ?? 60_000)
+    this.reconnectTimer = setTimeout(() => {
+      this.reconnectTimer = undefined
+      if (!this.stopped) this.open()
+    }, wait)
+    this.reconnectTimer.unref?.()
+    this.log(`dsh-foreman-node reconnecting in ${wait} ms`)
+  }
+}

package/src/index.ts

@@ -0,0 +1,129 @@
+/**
+ * The device-side plugin entry.
+ *
+ * It is deliberately thin: one connection out to the hub, one job Session per assignment, one report tool per job.
+ * It imports no domain core, opens no database, and reads no policy, because a device holds no ledger — the hub is
+ * the only place work is recorded, and this side's job is to do it and say what happened.
+ */
+import type { Context } from '@deepseek-ai/cordis'
+import s from '@deepseek-ai/schemastery'
+import type {} from '@deepseek-ai/dsh-api-session-controller'
+import type {} from '@deepseek-ai/dsh-session-persistence'
+import type {} from '@deepseek-ai/dsh-workspace'
+import type {} from '@deepseek-ai/dsh-permission-presets'
+import type {} from '@deepseek-ai/dsh-tools'
+import { NodeClient } from './client.ts'
+import { JobSessions } from './session.ts'
+import type { Frame } from './protocol.ts'
+
+/** Version reported in the hello, so the hub can tell which device build is talking. */
+export const VERSION = '0.1.0'
+
+/** One project this device can work on: the hub's logical name and this machine's own absolute path. */
+export interface NodeRoot { project: string; path: string }
+
+/** What the `dsh-foreman-node` entry in a profile's patch configures. */
+export interface NodeConfig {
+  /** The hub's stable address; the device dials out to it. */
+  url: string
+  /** This device's id, as registered on the hub with `Devices.add`. */
+  deviceId: string
+  /** This device's token; sent in the hello and nowhere else. */
+  token: string
+  /** The projects this device can work on. */
+  roots: NodeRoot[]
+  /** How often to tell the hub this device is alive, in milliseconds. */
+  heartbeatMs: number
+  /** Delay before the first reconnect attempt, in milliseconds. */
+  reconnectMs: number
+}
+
+/**
+ * Configuration of one device, from the `dsh-foreman-node` entry in the profile's patch.
+ *
+ * The annotation names the schema type through the global `Schemastery` namespace rather than letting it be inferred:
+ * an inferred type here names a `cosmokit` symbol the emitted declaration cannot reference portably.
+ */
+export const Config: Schemastery<NodeConfig> = s.object({
+  url: s.string().required().description('The hub\'s address, such as wss://foreman.example.com. The device dials out to it.'),
+  deviceId: s.string().required().description('This device\'s id, as registered on the hub with `Devices.add`.'),
+  token: s.string().required().role('secret').description('This device\'s token; it is sent in the hello frame and nowhere else.'),
+  roots: s.array(s.object({ project: s.string().required(), path: s.string().required() })).default([])
+    .description('Projects this device can work on: a logical name and this machine\'s own absolute path, kept verbatim.'),
+  heartbeatMs: s.natural().default(15_000).description('How often to tell the hub this device is alive, in milliseconds.'),
+  reconnectMs: s.natural().default(1_000).description('Delay before the first reconnect attempt, in milliseconds.'),
+})
+
+export const name = 'dsh-foreman-node'
+/** DSH services a job needs; all are the host's own, and none is a foreman one. */
+export const inject = ['sessionController', 'sessionPersistence', 'workspaceRegistry', 'permissionPresets', 'tools', 'agents']
+
+/**
+ * Start the device.
+ *
+ * The plugin returns once the connection is attempted, not once it succeeds: a device must boot and stay usable
+ * while its hub is unreachable, and the client keeps retrying in the background.
+ */
+export async function apply(ctx: Context, config: NodeConfig): Promise<void> {
+  const jobs = new JobSessions(ctx)
+  const client = new NodeClient({
+    url: config.url,
+    deviceId: config.deviceId,
+    token: config.token,
+    version: VERSION,
+    roots: () => config.roots.map(root => ({ project: root.project, path: root.path })),
+    running: () => jobs.running(),
+    heartbeatMs: config.heartbeatMs,
+    reconnectMs: config.reconnectMs,
+    log: text => ctx.logger.warn('%s', text),
+    onFrame: frame => { void receive(ctx, jobs, client, frame) },
+  })
+  client.start()
+  ctx.effect(() => () => { client.stop() })
+  ctx.logger.info('dsh-foreman-node %s is dialling %s as %s', VERSION, config.url, config.deviceId)
+}
+
+/**
+ * Handle one frame from the hub.
+ *
+ * `assign` creates or reuses the job Session and delivers the task; `input` steers more text into the same Session;
+ * `stop` ends the job. Each is acknowledged so the hub stops resending it, and each is idempotent on this side, so a
+ * redelivery after a dropped ack does no harm.
+ */
+async function receive(ctx: Context, jobs: JobSessions, client: NodeClient, frame: Frame): Promise<void> {
+  try {
+    if (frame.type === 'assign') {
+      // The report tool is attached by `ensure`, which is why it needs the client: a job that cannot report back
+      // would leave the hub waiting with no way to learn what happened.
+      const sessionId = await jobs.ensure({ assignmentId: frame.assignmentId, directory: frame.directory, title: `job ${frame.assignmentId}` },
+        (assignmentId, report) => client.report(assignmentId, report))
+      await jobs.deliver(sessionId, frame.text, frame.frameId)
+      client.accepted(frame.assignmentId)
+      client.ack(frame)
+      return
+    }
+    if (frame.type === 'input') {
+      const sessionId = `job-${frame.assignmentId}`
+      await jobs.deliver(sessionId, frame.text, frame.frameId)
+      client.ack(frame)
+      return
+    }
+    if (frame.type === 'stop') {
+      // The job's Session is left in place: a person may still want to read what it did.
+      jobs.forget(frame.assignmentId)
+      client.ack(frame)
+    }
+    // Heartbeats and acks need no answer; a hello is the hub's own, which this side never sends.
+  } catch (error) {
+    // A frame that cannot be applied is reported blocked rather than swallowed: silence would leave the hub waiting.
+    ctx.logger.warn('dsh-foreman-node could not apply a %s frame: %s', frame.type, String(error))
+    if (frame.type === 'assign' || frame.type === 'input') {
+      client.report(frame.assignmentId, { state: 'blocked', summary: `this device could not start the job: ${String(error)}` })
+    }
+  }
+}
+
+export { NodeClient } from './client.ts'
+export { JobSessions } from './session.ts'
+export { foremanReportTool, REPORT_STATES } from './report-tool.ts'
+export type { Frame, Root, FrameAttachment } from './protocol.ts'

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