@osolmaz/pi-workflows 0.14.0 → 0.15.0

package/src/host/worker-entry.ts

@@ -0,0 +1,533 @@
+#!/usr/bin/env node
+import { createHash, randomUUID } from "node:crypto";
+import { once } from "node:events";
+import { fileURLToPath } from "node:url";
+import { builtinWorkflowCatalog } from "../builtins/catalog.js";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+import { compositionMetadata } from "../workflows/composition.js";
+import { WorkflowEngine } from "../workflows/engine.js";
+import {
+  ClaimLostError,
+  RunParkedError,
+  WorkflowSourceChangedError,
+  errorMessage,
+} from "../workflows/errors.js";
+import { hashWorkflowSource, resolveWorkflowSource } from "../workflows/loader.js";
+import type {
+  AgentStepContract,
+  AgentStepExecutor,
+  AgentStepRequest,
+  AgentStepSubmission,
+  ResolvedHumanDecision,
+  WorkflowDefinition,
+  WorkflowMountedSource,
+  WorkflowRunState,
+  WorkflowSource,
+} from "../workflows/types.js";
+import { RpcStepExecutor } from "./rpc-executor.js";
+import type { WorkerLaunchEnvelope } from "./state.js";
+import {
+  encodeWorkerLine,
+  parseWorkerResponse,
+  type WorkerMessage,
+  type WorkerResponse,
+} from "./worker-protocol.js";
+import { HostBackedWorkflowStore, type WorkerStoreTransport } from "./worker-store.js";
+
+const STARTUP_ENV = "PI_WORKFLOWS_WORKER_LAUNCH";
+const PRESENTATION_TIMEOUT_MS = 30_000;
+
+type WorkerBootstrap = {
+  initialized: boolean;
+  input: JsonValue;
+  launchOptions: JsonValue;
+  parentRunId: string | null;
+  originSessionId: string | null;
+  stateDirectory: string;
+  piArgs?: string[];
+  resumeInteractionAttemptId?: string;
+  candidateInteraction?: {
+    requestId: string;
+    attemptId: string;
+    nodeId: string;
+    submissionId: string;
+    payload: JsonValue;
+  };
+};
+
+class StdioWorkerTransport implements WorkerStoreTransport {
+  private readonly pending = new Map<
+    string,
+    { resolve: (response: WorkerResponse) => void; reject: (error: Error) => void }
+  >();
+  private buffered = Buffer.alloc(0);
+
+  constructor(private readonly launch: WorkerLaunchEnvelope) {
+    process.stdin.on("data", (chunk: Buffer) => this.onData(chunk));
+    process.stdin.on("error", (error) => this.failAll(error));
+    process.stdin.resume();
+  }
+
+  async request(options: Parameters<WorkerStoreTransport["request"]>[0]) {
+    const message: WorkerMessage = {
+      schema: "pi-workflows.worker-message.v1",
+      launchSchema: this.launch.schema,
+      messageId: options.messageId,
+      kind: options.kind,
+      operation: options.operation,
+      runId: this.launch.runId,
+      generation: this.launch.generation,
+      workerEpoch: this.launch.workerEpoch,
+      expectedRevision: options.expectedRevision,
+      ...(options.attemptId === undefined ? {} : { attemptId: options.attemptId }),
+      payload: options.payload,
+    };
+    const response = await this.send(message);
+    if (response.outcome === "claimLost") {
+      throw new ClaimLostError(this.launch.runId, "ownerChanged");
+    }
+    if (response.outcome === "rejected") {
+      throw new Error(response.error ?? "Workflow worker message was rejected");
+    }
+    return {
+      ...(response.result === undefined ? {} : { result: response.result }),
+      ...(response.revision === undefined ? {} : { revision: response.revision }),
+    };
+  }
+
+  async control(
+    operation: "worker.ready" | "worker.exiting",
+    payload: JsonValue,
+  ): Promise<WorkerResponse> {
+    return await this.send({
+      schema: "pi-workflows.worker-message.v1",
+      launchSchema: this.launch.schema,
+      messageId: randomUUID(),
+      kind: operation,
+      operation,
+      runId: this.launch.runId,
+      generation: this.launch.generation,
+      workerEpoch: this.launch.workerEpoch,
+      expectedRevision: 0,
+      payload,
+    });
+  }
+
+  close(): void {
+    process.stdin.pause();
+    process.stdin.removeAllListeners("data");
+    process.stdin.removeAllListeners("error");
+    this.failAll(new Error("Workflow worker transport closed"));
+  }
+
+  private async send(message: WorkerMessage): Promise<WorkerResponse> {
+    const response = new Promise<WorkerResponse>((resolve, reject) => {
+      this.pending.set(message.messageId, { resolve, reject });
+    });
+    if (!process.stdout.write(encodeWorkerLine(message))) await once(process.stdout, "drain");
+    return await response;
+  }
+
+  private onData(chunk: Buffer): void {
+    this.buffered = Buffer.concat([this.buffered, chunk]);
+    if (this.buffered.byteLength > 1024 * 1024 && !this.buffered.includes(0x0a)) {
+      this.failAll(new Error("Worker response exceeds 1 MiB"));
+      return;
+    }
+    for (;;) {
+      const newline = this.buffered.indexOf(0x0a);
+      if (newline < 0) return;
+      const frame = this.buffered.subarray(0, newline);
+      this.buffered = this.buffered.subarray(newline + 1);
+      if (frame.byteLength === 0) continue;
+      try {
+        const response = parseWorkerResponse(frame);
+        const pending = this.pending.get(response.messageId);
+        if (pending === undefined) throw new Error("Worker response has no pending request");
+        this.pending.delete(response.messageId);
+        pending.resolve(response);
+      } catch (error) {
+        this.failAll(error instanceof Error ? error : new Error(String(error)));
+      }
+    }
+  }
+
+  private failAll(error: Error): void {
+    for (const pending of this.pending.values()) pending.reject(error);
+    this.pending.clear();
+  }
+}
+
+class InteractiveExecutor implements AgentStepExecutor {
+  readonly assistantMessageMode = "visible" as const;
+  readonly preservesDeadlineWhileParked = true;
+
+  constructor(
+    private readonly store: HostBackedWorkflowStore,
+    private readonly candidate:
+      | {
+          requestId: string;
+          submissionId: string;
+          attemptId: string;
+          nodeId: string;
+          payload: JsonValue;
+        }
+      | undefined,
+  ) {}
+
+  async runAgentStep(request: AgentStepRequest): Promise<AgentStepSubmission> {
+    if (
+      this.candidate?.nodeId === request.contract.nodeId &&
+      this.candidate.attemptId === request.contract.attemptId
+    ) {
+      const submission = interactionSubmission(this.candidate.payload);
+      let value: AgentStepSubmission;
+      if (request.contract.completion === "assistant") {
+        const accepted = validateAcceptedAssistantSubmission(submission, request.contract);
+        if (!accepted.ok) return await this.rejectCandidate(accepted.error);
+        value = accepted.value;
+      } else {
+        const accepted = await request.accept(submission.output);
+        if (!accepted.ok) return await this.rejectCandidate(accepted.error);
+        value = { ...submission, output: accepted.value };
+      }
+      await this.store.acceptInteraction({
+        requestId: this.candidate.requestId,
+        submissionId: this.candidate.submissionId,
+        attemptId: this.candidate.attemptId,
+        value: value as unknown as JsonValue,
+      });
+      return value;
+    }
+    await this.store.requestInteraction({
+      attemptId: request.contract.attemptId,
+      kind: request.contract.completion === "assistant" ? "assistant" : "agent",
+      contract: {
+        contract: request.contract,
+        prompt: request.prompt,
+        ...(request.presentation === undefined ? {} : { presentation: request.presentation }),
+      } as JsonValue,
+    });
+    throw new RunParkedError();
+  }
+
+  private async rejectCandidate(error: string): Promise<never> {
+    if (this.candidate === undefined) throw new RunParkedError();
+    await this.store.rejectInteraction({
+      requestId: this.candidate.requestId,
+      submissionId: this.candidate.submissionId,
+      attemptId: this.candidate.attemptId,
+      error,
+    });
+    throw new RunParkedError();
+  }
+}
+
+function interactionSubmission(payload: JsonValue): AgentStepSubmission {
+  if (
+    typeof payload === "object" &&
+    payload !== null &&
+    !Array.isArray(payload) &&
+    Object.hasOwn(payload, "output")
+  ) {
+    return payload as unknown as AgentStepSubmission;
+  }
+  return { output: payload };
+}
+
+export function validateAcceptedAssistantSubmission(
+  submission: AgentStepSubmission,
+  contract: AgentStepContract,
+): { ok: true; value: AgentStepSubmission } | { ok: false; error: string } {
+  if (contract.completion !== "assistant") {
+    return { ok: false, error: "The interaction is not an assistant response" };
+  }
+  if (typeof submission.output !== "string" || submission.output.trim().length === 0) {
+    return { ok: false, error: "Assistant response has no visible text" };
+  }
+  if (contract.maxOutputChars !== undefined && submission.output.length > contract.maxOutputChars) {
+    return {
+      ok: false,
+      error: `Assistant response has ${submission.output.length} characters, above the configured limit of ${contract.maxOutputChars}`,
+    };
+  }
+  const receipt = submission.assistantMessage;
+  const conversation = submission.conversation;
+  const digest = createHash("sha256").update(submission.output).digest("hex");
+  if (
+    receipt === undefined ||
+    receipt.sha256 !== digest ||
+    typeof receipt.entryId !== "string" ||
+    receipt.entryId.length === 0 ||
+    receipt.recovered !== true ||
+    receipt.maxChars !== contract.maxOutputChars ||
+    conversation === undefined ||
+    typeof conversation.firstEntryId !== "string" ||
+    conversation.firstEntryId.length === 0 ||
+    conversation.lastEntryId !== receipt.entryId
+  ) {
+    return { ok: false, error: "Assistant response receipt is invalid" };
+  }
+  return {
+    ok: true,
+    value: {
+      output: submission.output,
+      assistantMessage: receipt,
+      conversation,
+    },
+  };
+}
+
+export async function runWorkflowWorker(): Promise<number> {
+  const launch = readLaunchEnvelope();
+  const transport = new StdioWorkerTransport(launch);
+  try {
+    const ready = await transport.control("worker.ready", {});
+    if (ready.outcome !== "accepted" || ready.result === undefined) {
+      throw new Error(ready.error ?? "Workflow host rejected worker startup");
+    }
+    const bootstrap = ready.result as unknown as WorkerBootstrap;
+    const workflowSource = parseWorkerWorkflowSources(launch.workflowSource);
+    let workflow: WorkflowDefinition;
+    try {
+      workflow = await resolveVerifiedWorkflow(launch.runId, workflowSource);
+    } catch (error) {
+      const response = await transport.control("worker.exiting", {
+        status: "workflowLoadFailed",
+        error: errorMessage(error),
+      });
+      if (response.outcome !== "accepted") {
+        throw new Error(response.error ?? "Workflow host rejected the load-failure report");
+      }
+      return 1;
+    }
+    const store = new HostBackedWorkflowStore(launch.runId, transport, ready.revision ?? 0);
+    let executor: AgentStepExecutor;
+    let closeExecutor: (() => Promise<void>) | undefined;
+    if (bootstrap.originSessionId !== null) {
+      executor = new InteractiveExecutor(store, bootstrap.candidateInteraction);
+    } else {
+      const rpc = new RpcStepExecutor({
+        cwd: launch.projectPath,
+        processGroup: "own",
+        abortGraceMs: 1_000,
+        registry: {
+          register: async (pid) => {
+            await transport.request({
+              messageId: randomUUID(),
+              operation: "process.register",
+              kind: "worker.progress",
+              expectedRevision: 0,
+              payload: { pid },
+            });
+          },
+          unregister: async (pid) => {
+            await transport.request({
+              messageId: randomUUID(),
+              operation: "process.unregister",
+              kind: "worker.progress",
+              expectedRevision: 0,
+              payload: { pid },
+            });
+          },
+        },
+        ...(bootstrap.piArgs === undefined ? {} : { piArgs: bootstrap.piArgs }),
+      });
+      const closeRpc = async () => await rpc.close();
+      const onShutdown = () => {
+        void closeRpc().catch((error: unknown) => {
+          process.stderr.write(`Headless pi shutdown failed: ${errorMessage(error)}\n`);
+        });
+      };
+      process.on("SIGTERM", onShutdown);
+      process.on("SIGINT", onShutdown);
+      executor = rpc;
+      closeExecutor = async () => {
+        process.removeListener("SIGTERM", onShutdown);
+        process.removeListener("SIGINT", onShutdown);
+        await closeRpc();
+      };
+    }
+    const engine = new WorkflowEngine({
+      store,
+      executor,
+      notificationSink: {
+        notify: async (request) => await store.requestNotification(request),
+      },
+      onRunFinishing: async (_runId, state) => {
+        if (state.status !== "completed" || workflow.presentationPrompt === undefined) return;
+        const instructions = await resolvePresentationInstructions(workflow, state);
+        await store.requestPresentation(instructions);
+      },
+    });
+    const launchOptions =
+      typeof bootstrap.launchOptions === "object" &&
+      bootstrap.launchOptions !== null &&
+      !Array.isArray(bootstrap.launchOptions)
+        ? (bootstrap.launchOptions as Record<string, unknown>)
+        : {};
+    try {
+      const result = bootstrap.initialized
+        ? await engine.resumeRun(workflow, launch.runId, {
+            workflowSource: workflowSource.root,
+            ...(bootstrap.resumeInteractionAttemptId === undefined
+              ? {}
+              : { resumeInteractionAttemptId: bootstrap.resumeInteractionAttemptId }),
+          })
+        : bootstrap.parentRunId === null
+          ? await engine.run(workflow, bootstrap.input, {
+              runId: launch.runId,
+              workflowSource: workflowSource.root,
+            })
+          : await engine.continueRun(workflow, bootstrap.parentRunId, bootstrap.input, {
+              runId: launch.runId,
+              workflowSource: workflowSource.root,
+              ...(launchOptions.humanDecision === undefined
+                ? {}
+                : { humanDecision: launchOptions.humanDecision as ResolvedHumanDecision }),
+            });
+      await transport.control("worker.exiting", {
+        status: result.state.status,
+        traceSeq: result.state.traceSeq,
+      });
+      return 0;
+    } finally {
+      await closeExecutor?.();
+    }
+  } finally {
+    transport.close();
+  }
+}
+
+async function resolvePresentationInstructions(
+  workflow: WorkflowDefinition,
+  state: WorkflowRunState,
+): Promise<string> {
+  const fallback = "Summarize the completed workflow result for the user in a normal response.";
+  if (typeof workflow.presentationPrompt === "string") {
+    return workflow.presentationPrompt.trim() || fallback;
+  }
+  if (workflow.presentationPrompt === undefined) return fallback;
+  const controller = new AbortController();
+  const timer = setTimeout(
+    () => controller.abort(new Error("Workflow presentation prompt timed out")),
+    PRESENTATION_TIMEOUT_MS,
+  );
+  timer.unref?.();
+  const snapshot = structuredClone(state);
+  try {
+    const instructions = await Promise.race([
+      workflow.presentationPrompt({
+        state: snapshot,
+        finalOutput: snapshot.finalOutput,
+        signal: controller.signal,
+      }),
+      new Promise<never>((_resolve, reject) => {
+        controller.signal.addEventListener("abort", () => reject(controller.signal.reason), {
+          once: true,
+        });
+      }),
+    ]);
+    return instructions?.trim() || fallback;
+  } catch {
+    return fallback;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+type WorkerWorkflowSources = {
+  root: WorkflowSource;
+  mounted: WorkflowMountedSource[];
+};
+
+function parseWorkerWorkflowSources(value: JsonValue): WorkerWorkflowSources {
+  if (!isRecord(value) || !isWorkflowSource(value.root) || !Array.isArray(value.mounted)) {
+    throw new Error("Workflow worker source identity is invalid");
+  }
+  const mounted = value.mounted;
+  if (!mounted.every(isMountedWorkflowSource)) {
+    throw new Error("Workflow worker mounted source identity is invalid");
+  }
+  return { root: value.root, mounted };
+}
+
+async function resolveVerifiedWorkflow(
+  runId: string,
+  sources: WorkerWorkflowSources,
+): Promise<WorkflowDefinition> {
+  for (const source of [sources.root, ...sources.mounted.map((mounted) => mounted.source)]) {
+    if (source.kind === "file") {
+      if ((await hashWorkflowSource(source.path)) !== source.hash) {
+        throw new WorkflowSourceChangedError(runId);
+      }
+    } else {
+      builtinWorkflowCatalog.resolve(source, runId);
+    }
+  }
+  const workflow = await resolveWorkflowSource(sources.root, builtinWorkflowCatalog, runId);
+  const observed = compositionMetadata(workflow)?.sources ?? [];
+  if (
+    canonicalJson(sortMountedSources(observed)) !==
+    canonicalJson(sortMountedSources(sources.mounted))
+  ) {
+    throw new WorkflowSourceChangedError(runId);
+  }
+  return workflow;
+}
+
+function sortMountedSources(sources: WorkflowMountedSource[]): WorkflowMountedSource[] {
+  return [...sources].sort((left, right) =>
+    left.mountPath.join("/").localeCompare(right.mountPath.join("/")),
+  );
+}
+
+function isWorkflowSource(value: unknown): value is WorkflowSource {
+  return (
+    isRecord(value) &&
+    ((value.kind === "builtin" &&
+      typeof value.id === "string" &&
+      typeof value.revision === "string") ||
+      (value.kind === "file" && typeof value.path === "string" && typeof value.hash === "string"))
+  );
+}
+
+function isMountedWorkflowSource(value: unknown): value is WorkflowMountedSource {
+  return (
+    isRecord(value) &&
+    Array.isArray(value.mountPath) &&
+    value.mountPath.every((part) => typeof part === "string") &&
+    typeof value.workflowName === "string" &&
+    isWorkflowSource(value.source)
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function readLaunchEnvelope(): WorkerLaunchEnvelope {
+  const encoded = process.env[STARTUP_ENV];
+  if (encoded === undefined) throw new Error("Workflow worker launch envelope is missing");
+  const value = parseJson(Buffer.from(encoded, "base64url").toString("utf8"));
+  if (
+    typeof value !== "object" ||
+    value === null ||
+    Array.isArray(value) ||
+    (value as { schema?: unknown }).schema !== "pi-workflows.worker-launch.v1"
+  ) {
+    throw new Error("Workflow worker launch envelope is invalid");
+  }
+  return value as unknown as WorkerLaunchEnvelope;
+}
+
+async function main(): Promise<void> {
+  try {
+    process.exitCode = await runWorkflowWorker();
+  } catch (error) {
+    process.stderr.write(`${errorMessage(error)}\n`);
+    process.exitCode = 1;
+  }
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) void main();

package/src/host/worker-protocol.ts

@@ -0,0 +1,165 @@
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+import { MAX_PROTOCOL_MESSAGE_BYTES } from "./protocol.js";
+
+export const WORKER_MESSAGE_SCHEMA = "pi-workflows.worker-message.v1" as const;
+export const WORKER_RESPONSE_SCHEMA = "pi-workflows.worker-response.v1" as const;
+
+export const WORKER_MESSAGE_KINDS = [
+  "worker.ready",
+  "node.started",
+  "node.update",
+  "node.finished",
+  "node.failed",
+  "run.parked",
+  "run.finished",
+  "interaction.requested",
+  "interaction.accepted",
+  "interaction.rejected",
+  "notification.requested",
+  "presentation.requested",
+  "effect.reserve",
+  "effect.settle",
+  "worker.progress",
+  "worker.exiting",
+] as const;
+
+export type WorkerMessageKind = (typeof WORKER_MESSAGE_KINDS)[number];
+export type WorkerStoreOperation =
+  | "store.initializeRun"
+  | "store.prepareRunResume"
+  | "store.readRun"
+  | "store.writeSnapshot"
+  | "store.publishUpdate"
+  | "store.findSettingsScope"
+  | "store.ensureSettingsScope"
+  | "store.getSettingsScopeAtChange"
+  | "store.createHumanDecisionRequest"
+  | "store.readResolvedHumanDecision"
+  | "store.reserveEffect"
+  | "store.settleEffect"
+  | "process.register"
+  | "process.unregister"
+  | "interaction.request"
+  | "interaction.accept"
+  | "interaction.reject"
+  | "notification.request"
+  | "presentation.request";
+
+export type WorkerMessage = {
+  schema: typeof WORKER_MESSAGE_SCHEMA;
+  launchSchema: "pi-workflows.worker-launch.v1";
+  messageId: string;
+  kind: WorkerMessageKind;
+  operation: WorkerStoreOperation | "worker.ready" | "worker.exiting";
+  runId: string;
+  generation: number;
+  workerEpoch: string;
+  expectedRevision: number;
+  attemptId?: string;
+  payload: JsonValue;
+};
+
+export type WorkerResponse = {
+  schema: typeof WORKER_RESPONSE_SCHEMA;
+  messageId: string;
+  outcome: "accepted" | "adopted" | "rejected" | "claimLost";
+  revision?: number;
+  result?: JsonValue;
+  error?: string;
+};
+
+export function workerKindForOperation(
+  operation: WorkerStoreOperation,
+  payload: Record<string, unknown>,
+): WorkerMessageKind {
+  if (operation === "store.publishUpdate") return "node.update";
+  if (operation === "store.reserveEffect") return "effect.reserve";
+  if (operation === "store.settleEffect") return "effect.settle";
+  if (operation === "store.createHumanDecisionRequest" || operation === "interaction.request") {
+    return "interaction.requested";
+  }
+  if (operation === "interaction.accept") return "interaction.accepted";
+  if (operation === "interaction.reject") return "interaction.rejected";
+  if (operation === "notification.request") return "notification.requested";
+  if (operation === "presentation.request") return "presentation.requested";
+  if (operation === "store.writeSnapshot") {
+    const event = payload.event;
+    const eventType = isRecord(event) && typeof event.type === "string" ? event.type : "";
+    if (eventType === "node_started") return "node.started";
+    if (eventType === "node_finished") return "node.finished";
+    if (eventType === "node_failed" || eventType === "node_timed_out") return "node.failed";
+    if (eventType === "run_waiting" || eventType.includes("park")) return "run.parked";
+    if (eventType.startsWith("run_") && eventType !== "run_started") return "run.finished";
+  }
+  return "worker.progress";
+}
+
+export function encodeWorkerLine(message: WorkerMessage | WorkerResponse): Buffer {
+  const encoded = Buffer.from(`${canonicalJson(message)}\n`, "utf8");
+  if (encoded.byteLength > MAX_PROTOCOL_MESSAGE_BYTES) {
+    throw new Error("Worker protocol message exceeds 1 MiB");
+  }
+  return encoded;
+}
+
+export function parseWorkerMessage(line: Buffer | string): WorkerMessage {
+  const value = parseWorkerValue(line);
+  if (
+    value.schema !== WORKER_MESSAGE_SCHEMA ||
+    value.launchSchema !== "pi-workflows.worker-launch.v1"
+  ) {
+    throw new Error("Invalid worker message schema");
+  }
+  requireText(value.messageId, "messageId");
+  requireText(value.runId, "runId");
+  requireText(value.workerEpoch, "workerEpoch");
+  if (!WORKER_MESSAGE_KINDS.includes(value.kind as WorkerMessageKind)) {
+    throw new Error("Invalid worker message kind");
+  }
+  if (!Number.isSafeInteger(value.generation) || (value.generation as number) <= 0) {
+    throw new Error("Worker generation must be positive");
+  }
+  if (!Number.isSafeInteger(value.expectedRevision) || (value.expectedRevision as number) < 0) {
+    throw new Error("Worker expectedRevision must be non-negative");
+  }
+  requireText(value.operation, "operation");
+  if (value.attemptId !== undefined) requireText(value.attemptId, "attemptId");
+  if (!Object.hasOwn(value, "payload")) throw new Error("Worker payload is required");
+  return value as WorkerMessage;
+}
+
+export function parseWorkerResponse(line: Buffer | string): WorkerResponse {
+  const value = parseWorkerValue(line);
+  if (value.schema !== WORKER_RESPONSE_SCHEMA) throw new Error("Invalid worker response schema");
+  requireText(value.messageId, "messageId");
+  if (!["accepted", "adopted", "rejected", "claimLost"].includes(value.outcome as string)) {
+    throw new Error("Invalid worker response outcome");
+  }
+  if (value.error !== undefined && typeof value.error !== "string") {
+    throw new Error("Worker response error must be text");
+  }
+  return value as WorkerResponse;
+}
+
+function parseWorkerValue(line: Buffer | string): Record<string, unknown> {
+  const buffer = Buffer.isBuffer(line) ? line : Buffer.from(line, "utf8");
+  if (buffer.byteLength + 1 > MAX_PROTOCOL_MESSAGE_BYTES) {
+    throw new Error("Worker protocol message exceeds 1 MiB");
+  }
+  const text = buffer.toString("utf8");
+  const value = parseJson(text);
+  if (!isRecord(value) || canonicalJson(value) !== text) {
+    throw new Error("Worker protocol message must be a canonical JSON object");
+  }
+  return value;
+}
+
+function requireText(value: unknown, field: string): asserts value is string {
+  if (typeof value !== "string" || value.length === 0 || value.length > 256) {
+    throw new Error(`Worker ${field} must be nonempty bounded text`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}