@osolmaz/pi-workflows 0.16.2 → 0.16.4

package/src/{host/child-worker-supervisor.ts → server/child-runner-supervisor.ts}

@@ -2,62 +2,66 @@ import { spawn, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { once } from "node:events";
 import { NdjsonFrameDecoder } from "../client/protocol.js";
 import { errorMessage } from "../workflows/errors.js";
-import { HostProcessRegistry, type ProcessIdentity } from "./processes.js";
-import type { WorkerOutcome } from "./state.js";
+import { ServerProcessRegistry, type ProcessIdentity } from "./processes.js";
+import type { RunnerOutcome } from "./state.js";
 
 const DEFAULT_STARTUP_TIMEOUT_MS = 15_000;
 const DEFAULT_KILL_GRACE_MS = 2_000;
 const MAX_DIAGNOSTIC_BYTES = 64 * 1024;
 
-export type SupervisedWorkerResult = {
-  outcome: WorkerOutcome;
+export type SupervisedRunnerResult = {
+  outcome: RunnerOutcome;
   exitCode: number | null;
   signal: NodeJS.Signals | null;
   diagnostic?: string;
 };
 
-type ChildWorkerSupervisorOptions<Message, Response> = {
+type ChildRunnerSupervisorOptions<Message, Response> = {
   label: string;
-  registry: HostProcessRegistry;
+  registry: ServerProcessRegistry;
   onMessage: (message: Message) => Promise<Response>;
   parseMessage: (frame: Buffer) => Message;
   encodeResponse: (response: Response) => Buffer;
   isReady: (message: Message) => boolean;
   isTerminal: (message: Message) => boolean;
   startupTimeoutMs?: number;
+  maxMessageBytes?: number;
+  oversizedMessage?: string;
   onSpawn?: (identity: ProcessIdentity) => void;
   onDiagnostic?: (message: string) => void;
 };
 
-type ChildWorkerStartOptions = {
+type ChildRunnerStartOptions = {
   args: string[];
   cwd: string;
   env: NodeJS.ProcessEnv;
 };
 
-/** Shared supervision, framing, diagnostics, and process-group shutdown for host workers. */
-export class ChildWorkerSupervisor<Message, Response> {
+/** Shared supervision, framing, diagnostics, and process-group shutdown for server runners. */
+export class ChildRunnerSupervisor<Message, Response> {
   private child: ChildProcessWithoutNullStreams | null = null;
   private identity: ProcessIdentity | null = null;
-  private readonly decoder = new NdjsonFrameDecoder();
+  private readonly decoder: NdjsonFrameDecoder;
   private diagnostic = Buffer.alloc(0);
   private terminalMessage = false;
-  private stopping: WorkerOutcome | null = null;
+  private stopping: RunnerOutcome | null = null;
   private processing = Promise.resolve();
   private readyResolve: (() => void) | undefined;
   private readyReject: ((error: Error) => void) | undefined;
-  private exitResolve: ((result: SupervisedWorkerResult) => void) | undefined;
+  private exitResolve: ((result: SupervisedRunnerResult) => void) | undefined;
   private readonly readyPromise = new Promise<void>((resolve, reject) => {
     this.readyResolve = resolve;
     this.readyReject = reject;
   });
-  private readonly exitPromise = new Promise<SupervisedWorkerResult>((resolve) => {
+  private readonly exitPromise = new Promise<SupervisedRunnerResult>((resolve) => {
     this.exitResolve = resolve;
   });
 
-  constructor(private readonly options: ChildWorkerSupervisorOptions<Message, Response>) {}
+  constructor(private readonly options: ChildRunnerSupervisorOptions<Message, Response>) {
+    this.decoder = new NdjsonFrameDecoder(options.maxMessageBytes, options.oversizedMessage);
+  }
 
-  async start(options: ChildWorkerStartOptions): Promise<void> {
+  async start(options: ChildRunnerStartOptions): Promise<void> {
     if (this.child !== null) throw new Error(`${this.options.label} already started`);
     const child = spawn(process.execPath, options.args, {
       cwd: options.cwd,
@@ -86,11 +90,11 @@ export class ChildWorkerSupervisor<Message, Response> {
     }
   }
 
-  async wait(): Promise<SupervisedWorkerResult> {
+  async wait(): Promise<SupervisedRunnerResult> {
     return await this.exitPromise;
   }
 
-  async stop(outcome: WorkerOutcome = "cancelled"): Promise<void> {
+  async stop(outcome: RunnerOutcome = "cancelled"): Promise<void> {
     if (this.child === null) {
       this.exitResolve?.({ outcome, exitCode: null, signal: null });
       return;
@@ -154,7 +158,7 @@ export class ChildWorkerSupervisor<Message, Response> {
     const outcome =
       this.stopping ?? (code === 0 && this.terminalMessage ? "exited" : ("crashed" as const));
     const diagnostic = this.diagnostic.toString("utf8").trim();
-    const result: SupervisedWorkerResult = {
+    const result: SupervisedRunnerResult = {
       outcome,
       exitCode: code,
       signal,

package/src/{host → server}/processes.ts

@@ -14,9 +14,9 @@ type ProcessRegistryFile = {
 
 /**
  * Tracks supervised process groups by PID and operating-system start identity.
- * A later host kills a recorded process only when both values still match.
+ * A later server kills a recorded process only when both values still match.
  */
-export class HostProcessRegistry {
+export class ServerProcessRegistry {
   private readonly filePath: string;
   private readonly processes = new Map<number, ProcessIdentity>();
 
@@ -69,7 +69,7 @@ export class HostProcessRegistry {
     this.persist();
   }
 
-  /** Reap only exact stale process identities recorded by an older host. */
+  /** Reap only exact stale process identities recorded by an older server. */
   reapOrphans(): number[] {
     const recorded = this.readFile();
     const reaped: number[] = [];

package/src/{host → server}/resolver-entry.ts

@@ -5,11 +5,11 @@ import { fileURLToPath } from "node:url";
 import { builtinWorkflowCatalog } from "../builtins/catalog.js";
 import { MAX_PROTOCOL_MESSAGE_BYTES } from "../client/protocol.js";
 import type {
-  ResolvedControllerInitialization,
+  ResolvedResourceManagerInitialization,
   ResolvedSettingsChange,
   ResolvedWorkflowLaunch,
 } from "../client/resolver.js";
-import { discoverControllers, loadControllerFile } from "../controllers/loader.js";
+import { discoverResourceManagers, loadResourceManagerFile } from "../resource-managers/loader.js";
 import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
 import { compositionMetadata } from "../workflows/composition.js";
 import { errorMessage } from "../workflows/errors.js";
@@ -19,7 +19,7 @@ import { applyWorkflowSettingsPatch } from "../workflows/settings.js";
 import { createDefinitionSnapshot } from "../workflows/store.js";
 import type { WorkflowDefinition, WorkflowSource } from "../workflows/types.js";
 export type {
-  ResolvedControllerInitialization,
+  ResolvedResourceManagerInitialization,
   ResolvedSettingsChange,
   ResolvedWorkflowLaunch,
 } from "../client/resolver.js";
@@ -41,18 +41,21 @@ type SettingsValidationRequest = {
   actorId: string;
 };
 
-type ControllerInitializationRequest = {
-  schema: "pi-workflows.controller-initialization-request.v1";
+type ResourceManagerInitializationRequest = {
+  schema: "pi-workflows.resource-manager-initialization-request.v1";
   cwd: string;
-  controllerName: string;
+  resourceManagerName: string;
   spec: JsonValue;
 };
 
-type ResolverInput = ResolverRequest | SettingsValidationRequest | ControllerInitializationRequest;
+type ResolverInput =
+  | ResolverRequest
+  | SettingsValidationRequest
+  | ResourceManagerInitializationRequest;
 type ResolverOutput =
   | ResolvedWorkflowLaunch
   | ResolvedSettingsChange
-  | ResolvedControllerInitialization;
+  | ResolvedResourceManagerInitialization;
 
 export async function resolveWorkflowLaunch(
   request: ResolverRequest,
@@ -74,27 +77,27 @@ export async function resolveWorkflowLaunch(
   };
 }
 
-export async function resolveControllerInitialization(
-  request: ControllerInitializationRequest,
-): Promise<ResolvedControllerInitialization> {
-  const discovered = (await discoverControllers({ cwd: request.cwd })).find(
-    (candidate) => candidate.name === request.controllerName,
+export async function resolveResourceManagerInitialization(
+  request: ResourceManagerInitializationRequest,
+): Promise<ResolvedResourceManagerInitialization> {
+  const discovered = (await discoverResourceManagers({ cwd: request.cwd })).find(
+    (candidate) => candidate.name === request.resourceManagerName,
   );
   if (discovered === undefined) {
-    throw new Error(`Controller not found: ${request.controllerName}`);
+    throw new Error(`ResourceManager not found: ${request.resourceManagerName}`);
   }
-  const definition = await loadControllerFile(discovered.path);
-  if (definition.name !== request.controllerName) {
-    throw new Error("Controller source name does not match its discovered name");
+  const definition = await loadResourceManagerFile(discovered.path);
+  if (definition.name !== request.resourceManagerName) {
+    throw new Error("ResourceManager source name does not match its discovered name");
   }
   const initialStatus = parseJson(canonicalJson(definition.initialStatus(request.spec)));
   const sourceHash = createHash("sha256")
     .update(await fs.readFile(discovered.path))
     .digest("hex");
   return {
-    schema: "pi-workflows.resolved-controller-initialization.v1",
-    controllerName: definition.name,
-    controllerPath: discovered.path,
+    schema: "pi-workflows.resolved-resource-manager-initialization.v1",
+    resourceManagerName: definition.name,
+    resourceManagerPath: discovered.path,
     sourceHash,
     initialStatus,
   };
@@ -179,11 +182,11 @@ async function readRequest(): Promise<ResolverInput> {
     return value as ResolverRequest;
   }
   if (
-    value.schema === "pi-workflows.controller-initialization-request.v1" &&
-    typeof value.controllerName === "string" &&
+    value.schema === "pi-workflows.resource-manager-initialization-request.v1" &&
+    typeof value.resourceManagerName === "string" &&
     Object.hasOwn(value, "spec")
   ) {
-    return value as ControllerInitializationRequest;
+    return value as ResourceManagerInitializationRequest;
   }
   if (
     value.schema === "pi-workflows.settings-validation-request.v1" &&
@@ -205,8 +208,8 @@ async function main(): Promise<void> {
     const result: ResolverOutput =
       request.schema === "pi-workflows.resolve-request.v1"
         ? await resolveWorkflowLaunch(request)
-        : request.schema === "pi-workflows.controller-initialization-request.v1"
-          ? await resolveControllerInitialization(request)
+        : request.schema === "pi-workflows.resource-manager-initialization-request.v1"
+          ? await resolveResourceManagerInitialization(request)
           : await resolveSettingsChange(request);
     const encoded = `${canonicalJson(result)}\n`;
     if (Buffer.byteLength(encoded) > MAX_PROTOCOL_MESSAGE_BYTES) {

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

@@ -2,66 +2,66 @@
 import { randomUUID } from "node:crypto";
 import { once } from "node:events";
 import { fileURLToPath } from "node:url";
-import { jsonFingerprint } from "../controllers/json.js";
-import { loadControllerFile } from "../controllers/loader.js";
-import { createResultHelpers } from "../controllers/results.js";
+import { jsonFingerprint } from "../resource-managers/json.js";
+import { loadResourceManagerFile } from "../resource-managers/loader.js";
+import { createResultHelpers } from "../resource-managers/results.js";
 import type {
   ChildWorkflowRecord,
-  ControllerEffects,
-  ControllerFollowUpResult,
-  ControllerQueueFollowUpRequest,
-  ControllerRemoveFollowUpRequest,
-  ControllerSettingsChangeRequest,
-  ControllerSettingsChangeResult,
-  ControllerWorkflows,
+  ResourceManagerEffects,
+  ResourceManagerFollowUpResult,
+  ResourceManagerQueueFollowUpRequest,
+  ResourceManagerRemoveFollowUpRequest,
+  ResourceManagerSettingsChangeRequest,
+  ResourceManagerSettingsChangeResult,
+  ResourceManagerWorkflows,
   EffectApplication,
   EffectDefinition,
   EffectObservation,
   EffectRecord,
   ReconcileContext,
   ReconcileResult,
-} from "../controllers/types.js";
+} from "../resource-managers/types.js";
 import { parseJson, type JsonValue } from "../state/json.js";
 import { errorMessage } from "../workflows/errors.js";
 import {
-  CONTROLLER_WORKER_LAUNCH_SCHEMA,
-  encodeControllerWorkerLine,
-  parseControllerWorkerResponse,
-  type ControllerWorkerLaunchEnvelope,
-  type ControllerWorkerMessage,
-  type ControllerWorkerOperation,
-  type ControllerWorkerResponse,
-} from "./controller-worker-protocol.js";
+  RESOURCE_RUNNER_LAUNCH_SCHEMA,
+  encodeResourceRunnerLine,
+  parseResourceRunnerResponse,
+  type ResourceRunnerLaunchEnvelope,
+  type ResourceRunnerMessage,
+  type ResourceRunnerOperation,
+  type ResourceRunnerResponse,
+} from "./resource-runner-protocol.js";
 
-const STARTUP_ENV = "PI_WORKFLOWS_CONTROLLER_WORKER_LAUNCH";
+const STARTUP_ENV = "PI_WORKFLOWS_RESOURCE_RUNNER_LAUNCH";
 const MAX_FRAME_BYTES = 1024 * 1024;
 
-class ControllerWorkerTransport {
+class ResourceRunnerTransport {
   private readonly pending = new Map<
     string,
-    { resolve: (response: ControllerWorkerResponse) => void; reject: (error: Error) => void }
+    { resolve: (response: ResourceRunnerResponse) => void; reject: (error: Error) => void }
   >();
   private buffered = Buffer.alloc(0);
 
-  constructor(private readonly launch: ControllerWorkerLaunchEnvelope) {
+  constructor(private readonly launch: ResourceRunnerLaunchEnvelope) {
     process.stdin.on("data", (chunk: Buffer) => this.onData(chunk));
     process.stdin.on("error", (error) => this.failAll(error));
     process.stdin.resume();
   }
 
-  async request<T>(operation: ControllerWorkerOperation, payload: JsonValue): Promise<T> {
-    const message: ControllerWorkerMessage = {
+  async request<T>(operation: ResourceRunnerOperation, payload: JsonValue): Promise<T> {
+    const message: ResourceRunnerMessage = {
       schema: "pi-workflows.controller-worker-message.v1",
       launchSchema: this.launch.schema,
       messageId: randomUUID(),
-      workerEpoch: this.launch.workerEpoch,
+      runnerEpoch: this.launch.runnerEpoch,
       generation: this.launch.generation,
       operation,
       payload,
     };
     const response = await this.send(message);
     if (response.outcome !== "accepted") {
-      throw new Error(response.error ?? `Controller worker ${response.outcome}`);
+      throw new Error(response.error ?? `Resource runner ${response.outcome}`);
     }
     return response.result as T;
   }
@@ -70,14 +70,14 @@ class ControllerWorkerTransport {
     process.stdin.pause();
     process.stdin.removeAllListeners("data");
     process.stdin.removeAllListeners("error");
-    this.failAll(new Error("Controller worker transport closed"));
+    this.failAll(new Error("Resource runner transport closed"));
   }
 
-  private async send(message: ControllerWorkerMessage): Promise<ControllerWorkerResponse> {
-    const response = new Promise<ControllerWorkerResponse>((resolve, reject) => {
+  private async send(message: ResourceRunnerMessage): Promise<ResourceRunnerResponse> {
+    const response = new Promise<ResourceRunnerResponse>((resolve, reject) => {
       this.pending.set(message.messageId, { resolve, reject });
     });
-    if (!process.stdout.write(encodeControllerWorkerLine(message))) {
+    if (!process.stdout.write(encodeResourceRunnerLine(message))) {
       await once(process.stdout, "drain");
     }
     return await response;
@@ -86,7 +86,7 @@ class ControllerWorkerTransport {
   private onData(chunk: Buffer): void {
     this.buffered = Buffer.concat([this.buffered, chunk]);
     if (this.buffered.byteLength > MAX_FRAME_BYTES && !this.buffered.includes(0x0a)) {
-      this.failAll(new Error("Controller worker response exceeds 1 MiB"));
+      this.failAll(new Error("Resource runner response exceeds 1 MiB"));
       return;
     }
     for (;;) {
@@ -96,9 +96,9 @@ class ControllerWorkerTransport {
       this.buffered = this.buffered.subarray(newline + 1);
       if (frame.byteLength === 0) continue;
       try {
-        const response = parseControllerWorkerResponse(frame);
+        const response = parseResourceRunnerResponse(frame);
         const pending = this.pending.get(response.messageId);
-        if (pending === undefined) throw new Error("Controller worker response is unexpected");
+        if (pending === undefined) throw new Error("Resource runner response is unexpected");
         this.pending.delete(response.messageId);
         pending.resolve(response);
       } catch (error) {
@@ -113,11 +113,11 @@ class ControllerWorkerTransport {
   }
 }
 
-class HostedControllerEffects implements ControllerEffects {
+class ServerBackedResourceManagerEffects implements ResourceManagerEffects {
   private used = false;
 
   constructor(
-    private readonly transport: ControllerWorkerTransport,
+    private readonly transport: ResourceRunnerTransport,
     private readonly signal: AbortSignal,
   ) {}
 
@@ -173,8 +173,8 @@ class HostedControllerEffects implements ControllerEffects {
   }
 }
 
-class HostedControllerWorkflows implements ControllerWorkflows {
-  constructor(private readonly transport: ControllerWorkerTransport) {}
+class ServerBackedResourceManagerWorkflows implements ResourceManagerWorkflows {
+  constructor(private readonly transport: ResourceRunnerTransport) {}
 
   async ensure(request: {
     requestKey: string;
@@ -188,42 +188,44 @@ class HostedControllerWorkflows implements ControllerWorkflows {
   }
 
   async changeSettings(
-    request: ControllerSettingsChangeRequest,
-  ): Promise<ControllerSettingsChangeResult> {
-    return await this.transport.request<ControllerSettingsChangeResult>(
+    request: ResourceManagerSettingsChangeRequest,
+  ): Promise<ResourceManagerSettingsChangeResult> {
+    return await this.transport.request<ResourceManagerSettingsChangeResult>(
       "workflow.changeSettings",
       request as unknown as JsonValue,
     );
   }
 
-  async queueFollowUp(request: ControllerQueueFollowUpRequest): Promise<ControllerFollowUpResult> {
-    return await this.transport.request<ControllerFollowUpResult>(
+  async queueFollowUp(
+    request: ResourceManagerQueueFollowUpRequest,
+  ): Promise<ResourceManagerFollowUpResult> {
+    return await this.transport.request<ResourceManagerFollowUpResult>(
       "workflow.queueFollowUp",
       request as unknown as JsonValue,
     );
   }
 
   async removeFollowUp(
-    request: ControllerRemoveFollowUpRequest,
-  ): Promise<ControllerFollowUpResult> {
-    return await this.transport.request<ControllerFollowUpResult>(
+    request: ResourceManagerRemoveFollowUpRequest,
+  ): Promise<ResourceManagerFollowUpResult> {
+    return await this.transport.request<ResourceManagerFollowUpResult>(
       "workflow.removeFollowUp",
       request as unknown as JsonValue,
     );
   }
 }
 
-export async function runControllerWorker(): Promise<number> {
+export async function runResourceRunner(): Promise<number> {
   const launch = readLaunchEnvelope();
-  const transport = new ControllerWorkerTransport(launch);
+  const transport = new ResourceRunnerTransport(launch);
   try {
-    const definition = await loadControllerFile(launch.definitionPath);
-    if (definition.name !== launch.controllerName) {
+    const definition = await loadResourceManagerFile(launch.definitionPath);
+    if (definition.name !== launch.resourceManagerName) {
       throw new Error(
-        `Controller source name changed: expected ${launch.controllerName}, got ${definition.name}`,
+        `ResourceManager source name changed: expected ${launch.resourceManagerName}, got ${definition.name}`,
       );
     }
-    await transport.request("worker.ready", {});
+    await transport.request("runner.ready", {});
     const abort = new AbortController();
     const timeoutMs = definition.timeoutMs ?? launch.timeoutMs;
     const timer = setTimeout(
@@ -233,8 +235,8 @@ export async function runControllerWorker(): Promise<number> {
     try {
       const context: ReconcileContext<unknown> = {
         signal: abort.signal,
-        effects: new HostedControllerEffects(transport, abort.signal),
-        workflows: new HostedControllerWorkflows(transport),
+        effects: new ServerBackedResourceManagerEffects(transport, abort.signal),
+        workflows: new ServerBackedResourceManagerWorkflows(transport),
         ...createResultHelpers<unknown>(),
       };
       const result = await raceWithAbort(
@@ -242,9 +244,9 @@ export async function runControllerWorker(): Promise<number> {
         abort.signal,
       );
       validateResult(result);
-      await transport.request("worker.finished", result as unknown as JsonValue);
+      await transport.request("runner.finished", result as unknown as JsonValue);
     } catch (error) {
-      await transport.request("worker.failed", { error: boundedError(error) });
+      await transport.request("runner.failed", { error: boundedError(error) });
     } finally {
       clearTimeout(timer);
     }
@@ -254,34 +256,34 @@ export async function runControllerWorker(): Promise<number> {
   }
 }
 
-function readLaunchEnvelope(): ControllerWorkerLaunchEnvelope {
+function readLaunchEnvelope(): ResourceRunnerLaunchEnvelope {
   const encoded = process.env[STARTUP_ENV];
-  if (encoded === undefined) throw new Error("Controller worker launch envelope is missing");
+  if (encoded === undefined) throw new Error("Resource runner 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 !== CONTROLLER_WORKER_LAUNCH_SCHEMA
+    (value as { schema?: unknown }).schema !== RESOURCE_RUNNER_LAUNCH_SCHEMA
   ) {
-    throw new Error("Controller worker launch envelope is invalid");
+    throw new Error("Resource runner launch envelope is invalid");
   }
-  return value as unknown as ControllerWorkerLaunchEnvelope;
+  return value as unknown as ResourceRunnerLaunchEnvelope;
 }
 
 function validateResult(value: unknown): asserts value is ReconcileResult<unknown> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    throw new Error("Controller reconcile result must be an object");
+    throw new Error("ResourceManager reconcile result must be an object");
   }
   const result = value as { kind?: unknown; afterMs?: unknown };
   if (result.kind !== "settled" && result.kind !== "requeue") {
-    throw new Error("Controller reconcile result kind is invalid");
+    throw new Error("ResourceManager reconcile result kind is invalid");
   }
   if (
     result.afterMs !== undefined &&
     (!Number.isSafeInteger(result.afterMs) || (result.afterMs as number) < 0)
   ) {
-    throw new Error("Controller reconcile afterMs must be a non-negative safe integer");
+    throw new Error("ResourceManager reconcile afterMs must be a non-negative safe integer");
   }
 }
 
@@ -301,7 +303,7 @@ function boundedError(error: unknown): string {
 
 async function main(): Promise<void> {
   try {
-    process.exitCode = await runControllerWorker();
+    process.exitCode = await runResourceRunner();
   } catch (error) {
     process.stderr.write(`${errorMessage(error)}\n`);
     process.exitCode = 1;

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

@@ -0,0 +1,103 @@
+import type { ManagedResource } from "../resource-managers/types.js";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+
+export const RESOURCE_RUNNER_LAUNCH_SCHEMA = "pi-workflows.controller-worker-launch.v1" as const;
+export const RESOURCE_RUNNER_MESSAGE_SCHEMA = "pi-workflows.controller-worker-message.v1" as const;
+export const RESOURCE_RUNNER_RESPONSE_SCHEMA =
+  "pi-workflows.controller-worker-response.v1" as const;
+
+export type ResourceRunnerLaunchEnvelope = {
+  schema: typeof RESOURCE_RUNNER_LAUNCH_SCHEMA;
+  runnerEpoch: string;
+  serverEpoch: number;
+  generation: number;
+  projectPath: string;
+  definitionPath: string;
+  resourceManagerName: string;
+  resource: ManagedResource;
+  timeoutMs: number;
+};
+
+export type ResourceRunnerOperation =
+  | "runner.ready"
+  | "effect.reserve"
+  | "effect.settle"
+  | "workflow.ensure"
+  | "workflow.changeSettings"
+  | "workflow.queueFollowUp"
+  | "workflow.removeFollowUp"
+  | "runner.finished"
+  | "runner.failed";
+
+export type ResourceRunnerMessage = {
+  schema: typeof RESOURCE_RUNNER_MESSAGE_SCHEMA;
+  launchSchema: typeof RESOURCE_RUNNER_LAUNCH_SCHEMA;
+  messageId: string;
+  runnerEpoch: string;
+  generation: number;
+  operation: ResourceRunnerOperation;
+  payload: JsonValue;
+};
+
+export type ResourceRunnerResponse = {
+  schema: typeof RESOURCE_RUNNER_RESPONSE_SCHEMA;
+  messageId: string;
+  outcome: "accepted" | "rejected" | "claimLost";
+  result?: JsonValue;
+  error?: string;
+};
+
+export function encodeResourceRunnerLine(
+  value: ResourceRunnerMessage | ResourceRunnerResponse,
+): Buffer {
+  return Buffer.from(`${canonicalJson(value)}\n`, "utf8");
+}
+
+export function parseResourceRunnerMessage(frame: Buffer): ResourceRunnerMessage {
+  const value = parseJson(frame.toString("utf8"));
+  if (!isRecord(value) || value.schema !== RESOURCE_RUNNER_MESSAGE_SCHEMA) {
+    throw new Error("Invalid resource runner message schema");
+  }
+  if (
+    value.launchSchema !== RESOURCE_RUNNER_LAUNCH_SCHEMA ||
+    typeof value.messageId !== "string" ||
+    typeof value.runnerEpoch !== "string" ||
+    !Number.isSafeInteger(value.generation) ||
+    typeof value.operation !== "string" ||
+    !OPERATIONS.has(value.operation as ResourceRunnerOperation) ||
+    !Object.hasOwn(value, "payload")
+  ) {
+    throw new Error("Invalid resource runner message");
+  }
+  return value as ResourceRunnerMessage;
+}
+
+export function parseResourceRunnerResponse(frame: Buffer): ResourceRunnerResponse {
+  const value = parseJson(frame.toString("utf8"));
+  if (!isRecord(value) || value.schema !== RESOURCE_RUNNER_RESPONSE_SCHEMA) {
+    throw new Error("Invalid resource runner response schema");
+  }
+  if (
+    typeof value.messageId !== "string" ||
+    !["accepted", "rejected", "claimLost"].includes(String(value.outcome))
+  ) {
+    throw new Error("Invalid resource runner response");
+  }
+  return value as ResourceRunnerResponse;
+}
+
+const OPERATIONS = new Set<ResourceRunnerOperation>([
+  "runner.ready",
+  "effect.reserve",
+  "effect.settle",
+  "workflow.ensure",
+  "workflow.changeSettings",
+  "workflow.queueFollowUp",
+  "workflow.removeFollowUp",
+  "runner.finished",
+  "runner.failed",
+]);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}