@osolmaz/pi-workflows 0.16.1 → 0.16.3

package/src/{host/worker-entry.ts → server/workflow-runner-entry.ts}

@@ -25,27 +25,31 @@ import type {
   WorkflowSource,
 } from "../workflows/types.js";
 import { RpcStepExecutor } from "./rpc-executor.js";
-import type { WorkerLaunchEnvelope } from "./state.js";
+import type { WorkflowRunnerLaunchEnvelope } from "./state.js";
+import { materializeRunnerContent } from "./workflow-runner-content.js";
 import {
-  encodeWorkerLine,
-  parseWorkerResponse,
-  type WorkerMessage,
-  type WorkerResponse,
-} from "./worker-protocol.js";
-import { HostBackedWorkflowStore, type WorkerStoreTransport } from "./worker-store.js";
+  MAX_WORKFLOW_RUNNER_PROTOCOL_MESSAGE_BYTES,
+  encodeRunnerLine,
+  isRunnerContentChunk,
+  isRunnerContentReference,
+  parseRunnerResponse,
+  type WorkflowRunnerMessage,
+  type WorkflowRunnerResponse,
+  type WorkflowRunnerCommand,
+} from "./workflow-runner-protocol.js";
+import {
+  ServerBackedWorkflowStore,
+  type WorkflowRunnerStoreTransport,
+} from "./workflow-runner-store.js";
 
-const STARTUP_ENV = "PI_WORKFLOWS_WORKER_LAUNCH";
+const STARTUP_ENV = "PI_WORKFLOWS_WORKFLOW_RUNNER_LAUNCH";
 const PRESENTATION_TIMEOUT_MS = 30_000;
 
-type WorkerBootstrap = {
-  initialized: boolean;
-  input: JsonValue;
-  launchOptions: JsonValue;
-  parentRunId: string | null;
+type WorkflowRunnerBootstrap = {
+  command: WorkflowRunnerCommand;
   originSessionId: string | null;
   stateDirectory: string;
   piArgs?: string[];
-  resumeInteractionAttemptId?: string;
   candidateInteraction?: {
     requestId: string;
     attemptId: string;
@@ -55,21 +59,21 @@ type WorkerBootstrap = {
   };
 };
 
-class StdioWorkerTransport implements WorkerStoreTransport {
+class StdioRunnerTransport implements WorkflowRunnerStoreTransport {
   private readonly pending = new Map<
     string,
-    { resolve: (response: WorkerResponse) => void; reject: (error: Error) => void }
+    { resolve: (response: WorkflowRunnerResponse) => void; reject: (error: Error) => void }
   >();
   private buffered = Buffer.alloc(0);
 
-  constructor(private readonly launch: WorkerLaunchEnvelope) {
+  constructor(private readonly launch: WorkflowRunnerLaunchEnvelope) {
     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 = {
+  async request(options: Parameters<WorkflowRunnerStoreTransport["request"]>[0]) {
+    const message: WorkflowRunnerMessage = {
       schema: "pi-workflows.worker-message.v1",
       launchSchema: this.launch.schema,
       messageId: options.messageId,
@@ -77,17 +81,17 @@ class StdioWorkerTransport implements WorkerStoreTransport {
       operation: options.operation,
       runId: this.launch.runId,
       generation: this.launch.generation,
-      workerEpoch: this.launch.workerEpoch,
+      runnerEpoch: this.launch.runnerEpoch,
       expectedRevision: options.expectedRevision,
       ...(options.attemptId === undefined ? {} : { attemptId: options.attemptId }),
       payload: options.payload,
     };
-    const response = await this.send(message);
+    const response = await this.sendResolved(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");
+      throw new Error(response.error ?? "Workflow runner message was rejected");
     }
     return {
       ...(response.result === undefined ? {} : { result: response.result }),
@@ -96,10 +100,10 @@ class StdioWorkerTransport implements WorkerStoreTransport {
   }
 
   async control(
-    operation: "worker.ready" | "worker.exiting",
+    operation: "runner.ready" | "runner.exiting",
     payload: JsonValue,
-  ): Promise<WorkerResponse> {
-    return await this.send({
+  ): Promise<WorkflowRunnerResponse> {
+    return await this.sendResolved({
       schema: "pi-workflows.worker-message.v1",
       launchSchema: this.launch.schema,
       messageId: randomUUID(),
@@ -107,7 +111,7 @@ class StdioWorkerTransport implements WorkerStoreTransport {
       operation,
       runId: this.launch.runId,
       generation: this.launch.generation,
-      workerEpoch: this.launch.workerEpoch,
+      runnerEpoch: this.launch.runnerEpoch,
       expectedRevision: 0,
       payload,
     });
@@ -117,21 +121,55 @@ class StdioWorkerTransport implements WorkerStoreTransport {
     process.stdin.pause();
     process.stdin.removeAllListeners("data");
     process.stdin.removeAllListeners("error");
-    this.failAll(new Error("Workflow worker transport closed"));
+    this.failAll(new Error("Workflow runner transport closed"));
+  }
+
+  private async sendResolved(message: WorkflowRunnerMessage): Promise<WorkflowRunnerResponse> {
+    const response = await this.send(message);
+    if (!isRunnerContentReference(response.result)) return response;
+    const reference = response.result;
+    const expectedRevision = response.revision ?? message.expectedRevision;
+    return {
+      ...response,
+      result: await materializeRunnerContent(reference, async (offset) => {
+        const chunkResponse = await this.send({
+          schema: "pi-workflows.worker-message.v1",
+          launchSchema: this.launch.schema,
+          messageId: randomUUID(),
+          kind: "runner.progress",
+          operation: "content.read",
+          runId: this.launch.runId,
+          generation: this.launch.generation,
+          runnerEpoch: this.launch.runnerEpoch,
+          expectedRevision,
+          payload: { sha256: reference.sha256, offset },
+        });
+        if (chunkResponse.outcome === "claimLost") {
+          throw new ClaimLostError(this.launch.runId, "ownerChanged");
+        }
+        if (chunkResponse.outcome !== "accepted" || !isRunnerContentChunk(chunkResponse.result)) {
+          throw new Error(chunkResponse.error ?? "Workflow runner content read was rejected");
+        }
+        return chunkResponse.result;
+      }),
+    };
   }
 
-  private async send(message: WorkerMessage): Promise<WorkerResponse> {
-    const response = new Promise<WorkerResponse>((resolve, reject) => {
+  private async send(message: WorkflowRunnerMessage): Promise<WorkflowRunnerResponse> {
+    const response = new Promise<WorkflowRunnerResponse>((resolve, reject) => {
       this.pending.set(message.messageId, { resolve, reject });
     });
-    if (!process.stdout.write(encodeWorkerLine(message))) await once(process.stdout, "drain");
+    if (!process.stdout.write(encodeRunnerLine(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"));
+    if (
+      this.buffered.byteLength > MAX_WORKFLOW_RUNNER_PROTOCOL_MESSAGE_BYTES &&
+      !this.buffered.includes(0x0a)
+    ) {
+      this.failAll(new Error("Runner response exceeds 1 MiB"));
       return;
     }
     for (;;) {
@@ -141,9 +179,9 @@ class StdioWorkerTransport implements WorkerStoreTransport {
       this.buffered = this.buffered.subarray(newline + 1);
       if (frame.byteLength === 0) continue;
       try {
-        const response = parseWorkerResponse(frame);
+        const response = parseRunnerResponse(frame);
         const pending = this.pending.get(response.messageId);
-        if (pending === undefined) throw new Error("Worker response has no pending request");
+        if (pending === undefined) throw new Error("Runner response has no pending request");
         this.pending.delete(response.messageId);
         pending.resolve(response);
       } catch (error) {
@@ -163,7 +201,7 @@ class InteractiveExecutor implements AgentStepExecutor {
   readonly preservesDeadlineWhileParked = true;
 
   constructor(
-    private readonly store: HostBackedWorkflowStore,
+    private readonly store: ServerBackedWorkflowStore,
     private readonly candidate:
       | {
           requestId: string;
@@ -278,30 +316,59 @@ export function validateAcceptedAssistantSubmission(
   };
 }
 
-export async function runWorkflowWorker(): Promise<number> {
+export async function executeRunnerRunCommand(
+  engine: Pick<WorkflowEngine, "run" | "resumeRun" | "continueRun">,
+  workflow: WorkflowDefinition,
+  runId: string,
+  workflowSource: WorkflowSource,
+  command: WorkflowRunnerCommand,
+) {
+  switch (command.kind) {
+    case "start":
+    case "restart":
+      return await engine.run(workflow, command.input, { runId, workflowSource });
+    case "resume":
+      return await engine.resumeRun(workflow, runId, {
+        workflowSource,
+        ...(command.resumeInteractionAttemptId === undefined
+          ? {}
+          : { resumeInteractionAttemptId: command.resumeInteractionAttemptId }),
+      });
+    case "continue":
+      return await engine.continueRun(workflow, command.parentRunId, command.input, {
+        runId,
+        workflowSource,
+        ...(command.humanDecision === undefined
+          ? {}
+          : { humanDecision: command.humanDecision as ResolvedHumanDecision }),
+      });
+  }
+}
+
+export async function runWorkflowRunner(): Promise<number> {
   const launch = readLaunchEnvelope();
-  const transport = new StdioWorkerTransport(launch);
+  const transport = new StdioRunnerTransport(launch);
   try {
-    const ready = await transport.control("worker.ready", {});
+    const ready = await transport.control("runner.ready", {});
     if (ready.outcome !== "accepted" || ready.result === undefined) {
-      throw new Error(ready.error ?? "Workflow host rejected worker startup");
+      throw new Error(ready.error ?? "Workflow server rejected runner startup");
     }
-    const bootstrap = ready.result as unknown as WorkerBootstrap;
-    const workflowSource = parseWorkerWorkflowSources(launch.workflowSource);
+    const bootstrap = ready.result as unknown as WorkflowRunnerBootstrap;
+    const workflowSource = parseRunnerWorkflowSources(launch.workflowSource);
     let workflow: WorkflowDefinition;
     try {
       workflow = await resolveVerifiedWorkflow(launch.runId, workflowSource);
     } catch (error) {
-      const response = await transport.control("worker.exiting", {
+      const response = await transport.control("runner.exiting", {
         status: "workflowLoadFailed",
         error: errorMessage(error),
       });
       if (response.outcome !== "accepted") {
-        throw new Error(response.error ?? "Workflow host rejected the load-failure report");
+        throw new Error(response.error ?? "Workflow server rejected the load-failure report");
       }
       return 1;
     }
-    const store = new HostBackedWorkflowStore(launch.runId, transport, ready.revision ?? 0);
+    const store = new ServerBackedWorkflowStore(launch.runId, transport, ready.revision ?? 0);
     let executor: AgentStepExecutor;
     let closeExecutor: (() => Promise<void>) | undefined;
     if (bootstrap.originSessionId !== null) {
@@ -316,7 +383,7 @@ export async function runWorkflowWorker(): Promise<number> {
             await transport.request({
               messageId: randomUUID(),
               operation: "process.register",
-              kind: "worker.progress",
+              kind: "runner.progress",
               expectedRevision: 0,
               payload: { pid },
             });
@@ -325,7 +392,7 @@ export async function runWorkflowWorker(): Promise<number> {
             await transport.request({
               messageId: randomUUID(),
               operation: "process.unregister",
-              kind: "worker.progress",
+              kind: "runner.progress",
               expectedRevision: 0,
               payload: { pid },
             });
@@ -360,33 +427,15 @@ export async function runWorkflowWorker(): Promise<number> {
         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", {
+      const result = await executeRunnerRunCommand(
+        engine,
+        workflow,
+        launch.runId,
+        workflowSource.root,
+        bootstrap.command,
+      );
+      await transport.control("runner.exiting", {
         status: result.state.status,
         traceSeq: result.state.traceSeq,
       });
@@ -436,25 +485,25 @@ async function resolvePresentationInstructions(
   }
 }
 
-type WorkerWorkflowSources = {
+type WorkflowRunnerSources = {
   root: WorkflowSource;
   mounted: WorkflowMountedSource[];
 };
 
-function parseWorkerWorkflowSources(value: JsonValue): WorkerWorkflowSources {
+function parseRunnerWorkflowSources(value: JsonValue): WorkflowRunnerSources {
   if (!isRecord(value) || !isWorkflowSource(value.root) || !Array.isArray(value.mounted)) {
-    throw new Error("Workflow worker source identity is invalid");
+    throw new Error("Workflow runner source identity is invalid");
   }
   const mounted = value.mounted;
   if (!mounted.every(isMountedWorkflowSource)) {
-    throw new Error("Workflow worker mounted source identity is invalid");
+    throw new Error("Workflow runner mounted source identity is invalid");
   }
   return { root: value.root, mounted };
 }
 
 async function resolveVerifiedWorkflow(
   runId: string,
-  sources: WorkerWorkflowSources,
+  sources: WorkflowRunnerSources,
 ): Promise<WorkflowDefinition> {
   for (const source of [sources.root, ...sources.mounted.map((mounted) => mounted.source)]) {
     if (source.kind === "file") {
@@ -506,9 +555,9 @@ function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function readLaunchEnvelope(): WorkerLaunchEnvelope {
+function readLaunchEnvelope(): WorkflowRunnerLaunchEnvelope {
   const encoded = process.env[STARTUP_ENV];
-  if (encoded === undefined) throw new Error("Workflow worker launch envelope is missing");
+  if (encoded === undefined) throw new Error("Workflow runner launch envelope is missing");
   const value = parseJson(Buffer.from(encoded, "base64url").toString("utf8"));
   if (
     typeof value !== "object" ||
@@ -516,14 +565,14 @@ function readLaunchEnvelope(): WorkerLaunchEnvelope {
     Array.isArray(value) ||
     (value as { schema?: unknown }).schema !== "pi-workflows.worker-launch.v1"
   ) {
-    throw new Error("Workflow worker launch envelope is invalid");
+    throw new Error("Workflow runner launch envelope is invalid");
   }
-  return value as unknown as WorkerLaunchEnvelope;
+  return value as unknown as WorkflowRunnerLaunchEnvelope;
 }
 
 async function main(): Promise<void> {
   try {
-    process.exitCode = await runWorkflowWorker();
+    process.exitCode = await runWorkflowRunner();
   } catch (error) {
     process.stderr.write(`${errorMessage(error)}\n`);
     process.exitCode = 1;

package/src/server/workflow-runner-protocol.ts

@@ -0,0 +1,241 @@
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+
+export const MAX_WORKFLOW_RUNNER_PROTOCOL_MESSAGE_BYTES = 1024 * 1024;
+export const WORKFLOW_RUNNER_CONTENT_CHUNK_BYTES = 512 * 1024;
+export const WORKFLOW_RUNNER_MESSAGE_SCHEMA = "pi-workflows.worker-message.v1" as const;
+export const WORKFLOW_RUNNER_RESPONSE_SCHEMA = "pi-workflows.worker-response.v1" as const;
+export const WORKFLOW_RUNNER_CONTENT_REFERENCE_SCHEMA =
+  "pi-workflows.worker-content-reference.v1" as const;
+export const WORKFLOW_RUNNER_CONTENT_CHUNK_SCHEMA = "pi-workflows.worker-content-chunk.v1" as const;
+
+export type WorkflowRunnerCommand =
+  | { kind: "start"; input: JsonValue }
+  | { kind: "resume"; resumeInteractionAttemptId?: string }
+  | {
+      kind: "continue";
+      parentRunId: string;
+      input: JsonValue;
+      humanDecision?: JsonValue;
+    }
+  | { kind: "restart"; input: JsonValue };
+
+export const WORKFLOW_RUNNER_MESSAGE_KINDS = [
+  "runner.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",
+  "runner.progress",
+  "runner.exiting",
+] as const;
+
+export type WorkflowRunnerMessageKind = (typeof WORKFLOW_RUNNER_MESSAGE_KINDS)[number];
+export const WORKFLOW_RUNNER_STORE_OPERATIONS = [
+  "store.initializeRun",
+  "store.prepareRunResume",
+  "store.readRunState",
+  "store.writeSnapshot",
+  "store.publishUpdate",
+  "store.findSettingsScope",
+  "store.ensureSettingsScope",
+  "store.getSettingsScopeAtChange",
+  "store.createHumanDecisionRequest",
+  "store.readResolvedHumanDecision",
+  "store.reserveEffect",
+  "store.settleEffect",
+  "content.read",
+  "process.register",
+  "process.unregister",
+  "interaction.request",
+  "interaction.accept",
+  "interaction.reject",
+  "notification.request",
+  "presentation.request",
+] as const;
+export type WorkflowRunnerStoreOperation = (typeof WORKFLOW_RUNNER_STORE_OPERATIONS)[number];
+const WORKFLOW_RUNNER_CONTROL_OPERATIONS = ["runner.ready", "runner.exiting"] as const;
+
+export type WorkflowRunnerMessage = {
+  schema: typeof WORKFLOW_RUNNER_MESSAGE_SCHEMA;
+  launchSchema: "pi-workflows.worker-launch.v1";
+  messageId: string;
+  kind: WorkflowRunnerMessageKind;
+  operation: WorkflowRunnerStoreOperation | "runner.ready" | "runner.exiting";
+  runId: string;
+  generation: number;
+  runnerEpoch: string;
+  expectedRevision: number;
+  attemptId?: string;
+  payload: JsonValue;
+};
+
+export type WorkflowRunnerResponse = {
+  schema: typeof WORKFLOW_RUNNER_RESPONSE_SCHEMA;
+  messageId: string;
+  outcome: "accepted" | "adopted" | "rejected" | "claimLost";
+  revision?: number;
+  result?: JsonValue;
+  error?: string;
+};
+
+export type WorkflowRunnerContentReference = {
+  schema: typeof WORKFLOW_RUNNER_CONTENT_REFERENCE_SCHEMA;
+  sha256: string;
+  mediaType: "application/json";
+  bytes: number;
+};
+
+export type WorkflowRunnerContentChunk = {
+  schema: typeof WORKFLOW_RUNNER_CONTENT_CHUNK_SCHEMA;
+  sha256: string;
+  mediaType: "application/json";
+  bytes: number;
+  offset: number;
+  nextOffset: number;
+  complete: boolean;
+  data: string;
+};
+
+export function isRunnerContentReference(value: unknown): value is WorkflowRunnerContentReference {
+  return (
+    isRecord(value) &&
+    value.schema === WORKFLOW_RUNNER_CONTENT_REFERENCE_SCHEMA &&
+    typeof value.sha256 === "string" &&
+    /^[0-9a-f]{64}$/u.test(value.sha256) &&
+    value.mediaType === "application/json" &&
+    Number.isSafeInteger(value.bytes) &&
+    (value.bytes as number) >= 0
+  );
+}
+
+export function isRunnerContentChunk(value: unknown): value is WorkflowRunnerContentChunk {
+  return (
+    isRecord(value) &&
+    value.schema === WORKFLOW_RUNNER_CONTENT_CHUNK_SCHEMA &&
+    typeof value.sha256 === "string" &&
+    /^[0-9a-f]{64}$/u.test(value.sha256) &&
+    value.mediaType === "application/json" &&
+    Number.isSafeInteger(value.bytes) &&
+    (value.bytes as number) >= 0 &&
+    Number.isSafeInteger(value.offset) &&
+    (value.offset as number) >= 0 &&
+    Number.isSafeInteger(value.nextOffset) &&
+    (value.nextOffset as number) >= (value.offset as number) &&
+    typeof value.complete === "boolean" &&
+    typeof value.data === "string"
+  );
+}
+
+export function runnerKindForOperation(
+  operation: WorkflowRunnerStoreOperation,
+  payload: Record<string, unknown>,
+): WorkflowRunnerMessageKind {
+  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 "runner.progress";
+}
+
+export function encodeRunnerLine(message: WorkflowRunnerMessage | WorkflowRunnerResponse): Buffer {
+  const encoded = Buffer.from(`${canonicalJson(message)}\n`, "utf8");
+  if (encoded.byteLength > MAX_WORKFLOW_RUNNER_PROTOCOL_MESSAGE_BYTES) {
+    throw new Error("Runner protocol message exceeds 1 MiB");
+  }
+  return encoded;
+}
+
+export function parseRunnerMessage(line: Buffer | string): WorkflowRunnerMessage {
+  const value = parseRunnerValue(line);
+  if (
+    value.schema !== WORKFLOW_RUNNER_MESSAGE_SCHEMA ||
+    value.launchSchema !== "pi-workflows.worker-launch.v1"
+  ) {
+    throw new Error("Invalid workflow runner message schema");
+  }
+  requireText(value.messageId, "messageId");
+  requireText(value.runId, "runId");
+  requireText(value.runnerEpoch, "runnerEpoch");
+  if (!WORKFLOW_RUNNER_MESSAGE_KINDS.includes(value.kind as WorkflowRunnerMessageKind)) {
+    throw new Error("Invalid workflow runner message kind");
+  }
+  if (!Number.isSafeInteger(value.generation) || (value.generation as number) <= 0) {
+    throw new Error("Runner generation must be positive");
+  }
+  if (!Number.isSafeInteger(value.expectedRevision) || (value.expectedRevision as number) < 0) {
+    throw new Error("Runner expectedRevision must be non-negative");
+  }
+  requireText(value.operation, "operation");
+  if (
+    !WORKFLOW_RUNNER_STORE_OPERATIONS.includes(value.operation as WorkflowRunnerStoreOperation) &&
+    !WORKFLOW_RUNNER_CONTROL_OPERATIONS.includes(
+      value.operation as (typeof WORKFLOW_RUNNER_CONTROL_OPERATIONS)[number],
+    )
+  ) {
+    throw new Error("Invalid workflow runner operation");
+  }
+  if (value.attemptId !== undefined) requireText(value.attemptId, "attemptId");
+  if (!Object.hasOwn(value, "payload")) throw new Error("Runner payload is required");
+  return value as WorkflowRunnerMessage;
+}
+
+export function parseRunnerResponse(line: Buffer | string): WorkflowRunnerResponse {
+  const value = parseRunnerValue(line);
+  if (value.schema !== WORKFLOW_RUNNER_RESPONSE_SCHEMA)
+    throw new Error("Invalid workflow runner response schema");
+  requireText(value.messageId, "messageId");
+  if (!["accepted", "adopted", "rejected", "claimLost"].includes(value.outcome as string)) {
+    throw new Error("Invalid workflow runner response outcome");
+  }
+  if (value.error !== undefined && typeof value.error !== "string") {
+    throw new Error("Runner response error must be text");
+  }
+  return value as WorkflowRunnerResponse;
+}
+
+function parseRunnerValue(line: Buffer | string): Record<string, unknown> {
+  const buffer = Buffer.isBuffer(line) ? line : Buffer.from(line, "utf8");
+  if (buffer.byteLength + 1 > MAX_WORKFLOW_RUNNER_PROTOCOL_MESSAGE_BYTES) {
+    throw new Error("Runner protocol message exceeds 1 MiB");
+  }
+  const text = buffer.toString("utf8");
+  const value = parseJson(text);
+  if (!isRecord(value) || canonicalJson(value) !== text) {
+    throw new Error("Runner 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(`Runner ${field} must be nonempty bounded text`);
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}