@osolmaz/pi-workflows 0.16.2 → 0.16.4

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

@@ -17,10 +17,10 @@ import {
   decisionWorkflowMessageContent,
   stepWorkflowMessageContent,
 } from "../workflows/workflow-message-content.js";
-import type { WorkerMessage, WorkerResponse } from "./worker-protocol.js";
+import type { WorkflowRunnerMessage, WorkflowRunnerResponse } from "./workflow-runner-protocol.js";
 
-export type HostClaim = {
-  hostId: string;
+export type ServerClaim = {
+  serverId: string;
   token: string;
   epoch: number;
   pid: number;
@@ -28,9 +28,9 @@ export type HostClaim = {
   expiresAt: number;
 };
 
-export type HostStatusRecord = {
+export type WorkflowServerStatusRecord = {
   epoch: number;
-  hostId: string | null;
+  serverId: string | null;
   pid: number | null;
   processStartIdentity: string | null;
   startedAt: string | null;
@@ -39,11 +39,11 @@ export type HostStatusRecord = {
   live: boolean;
 };
 
-export type WorkerLaunchEnvelope = {
+export type WorkflowRunnerLaunchEnvelope = {
   schema: "pi-workflows.worker-launch.v1";
   runId: string;
   generation: number;
-  workerEpoch: string;
+  runnerEpoch: string;
   projectPath: string;
   workflowSource: JsonValue;
   definitionDigest: string;
@@ -51,7 +51,7 @@ export type WorkerLaunchEnvelope = {
   protocolVersion: 1;
 };
 
-export type WorkerOutcome =
+export type RunnerOutcome =
   | "exited"
   | "cancelled"
   | "timedOut"
@@ -86,7 +86,7 @@ export type InteractiveRequestRecord = {
   consumedAt: string | null;
 };
 
-export class HostStateStore {
+export class ServerStateStore {
   readonly state: StateDatabase;
   private readonly ownsState: boolean;
   readonly workflowMessages: WorkflowMessageStore;
@@ -106,19 +106,19 @@ export class HostStateStore {
     if (this.ownsState) this.state.close();
   }
 
-  acquireHost(options: {
-    hostId: string;
+  acquireServer(options: {
+    serverId: string;
     pid: number;
     processStartIdentity: string;
     leaseMs: number;
     now?: number;
-  }): HostClaim {
+  }): ServerClaim {
     const now = options.now ?? Date.now();
     requireLeaseMs(options.leaseMs);
     return this.state.transaction(() => {
-      const current = this.hostRow();
-      if (current.hostId !== null && current.expiresAt !== null && current.expiresAt > now) {
-        throw new Error(`A live Pi Workflows host already owns epoch ${current.epoch}`);
+      const current = this.serverRow();
+      if (current.serverId !== null && current.expiresAt !== null && current.expiresAt > now) {
+        throw new Error(`A live Pi Workflows server already owns epoch ${current.epoch}`);
       }
       const token = randomBytes(32).toString("base64url");
       const epoch = current.epoch + 1;
@@ -132,7 +132,7 @@ export class HostStateStore {
         )
         .run(
           epoch,
-          options.hostId,
+          options.serverId,
           tokenHash(token),
           options.pid,
           options.processStartIdentity,
@@ -142,9 +142,10 @@ export class HostStateStore {
           current.epoch,
           now,
         );
-      if (changed.changes !== 1) throw new Error("Pi Workflows host claim changed during startup");
+      if (changed.changes !== 1)
+        throw new Error("Pi Workflows server claim changed during startup");
       return {
-        hostId: options.hostId,
+        serverId: options.serverId,
         token,
         epoch,
         pid: options.pid,
@@ -154,7 +155,7 @@ export class HostStateStore {
     });
   }
 
-  renewHost(claim: HostClaim, leaseMs: number, now: number = Date.now()): HostClaim {
+  renewServer(claim: ServerClaim, leaseMs: number, now: number = Date.now()): ServerClaim {
     requireLeaseMs(leaseMs);
     return this.state.transaction(() => {
       const expiresAt = now + leaseMs;
@@ -168,18 +169,18 @@ export class HostStateStore {
           now,
           expiresAt,
           claim.epoch,
-          claim.hostId,
+          claim.serverId,
           tokenHash(claim.token),
           claim.pid,
           claim.processStartIdentity,
           now,
         );
-      if (changed.changes !== 1) throw new Error("Pi Workflows host claim lost");
+      if (changed.changes !== 1) throw new Error("Pi Workflows server claim lost");
       return { ...claim, expiresAt };
     });
   }
 
-  releaseHost(claim: HostClaim, _now: number = Date.now()): boolean {
+  releaseServer(claim: ServerClaim, _now: number = Date.now()): boolean {
     return this.state.transaction(
       () =>
         this.state.connection
@@ -192,7 +193,7 @@ export class HostStateStore {
           )
           .run(
             claim.epoch,
-            claim.hostId,
+            claim.serverId,
             tokenHash(claim.token),
             claim.pid,
             claim.processStartIdentity,
@@ -200,17 +201,17 @@ export class HostStateStore {
     );
   }
 
-  hostStatus(now: number = Date.now()): HostStatusRecord {
-    const row = this.hostRow();
+  serverStatus(now: number = Date.now()): WorkflowServerStatusRecord {
+    const row = this.serverRow();
     return {
       epoch: row.epoch,
-      hostId: row.hostId,
+      serverId: row.serverId,
       pid: row.pid,
       processStartIdentity: row.processStartIdentity,
       startedAt: iso(row.startedAt),
       heartbeatAt: iso(row.heartbeatAt),
       expiresAt: iso(row.expiresAt),
-      live: row.hostId !== null && row.expiresAt !== null && row.expiresAt > now,
+      live: row.serverId !== null && row.expiresAt !== null && row.expiresAt > now,
     };
   }
 
@@ -260,7 +261,7 @@ export class HostStateStore {
 
   executeCommand(
     request: ClientRequest,
-    hostEpoch: number,
+    serverEpoch: number,
     operation: () => Omit<ClientResponse, "schema" | "type" | "requestId">,
   ): ClientResponse {
     const existing = this.adoptCommand(request);
@@ -300,7 +301,7 @@ export class HostStateStore {
           response.outcome,
           receiptHash,
           errorHash,
-          hostEpoch,
+          serverEpoch,
           now,
           now,
         );
@@ -308,7 +309,7 @@ export class HostStateStore {
     });
   }
 
-  recordWorkerStart(envelope: WorkerLaunchEnvelope, hostEpoch: number): void {
+  recordRunnerStart(envelope: WorkflowRunnerLaunchEnvelope, serverEpoch: number): void {
     const now = Date.now();
     this.state.transaction(() => {
       const launchHash = this.state.putJson(envelope, now);
@@ -319,34 +320,41 @@ export class HostStateStore {
              status, started_at
            ) VALUES (?, ?, ?, ?, ?, 'starting', ?)`,
         )
-        .run(envelope.workerEpoch, envelope.runId, envelope.generation, hostEpoch, launchHash, now);
+        .run(
+          envelope.runnerEpoch,
+          envelope.runId,
+          envelope.generation,
+          serverEpoch,
+          launchHash,
+          now,
+        );
     });
   }
 
-  attachWorkerProcess(workerEpoch: string, pid: number, processStartIdentity: string): void {
+  attachRunnerProcess(runnerEpoch: string, pid: number, processStartIdentity: string): void {
     const changed = this.state.connection
       .prepare(
         `UPDATE run_workers SET pid = ?, process_start_identity = ?
          WHERE worker_epoch = ? AND status = 'starting' AND pid IS NULL`,
       )
-      .run(pid, processStartIdentity, workerEpoch);
-    if (changed.changes !== 1) throw new Error(`Worker epoch is not starting: ${workerEpoch}`);
+      .run(pid, processStartIdentity, runnerEpoch);
+    if (changed.changes !== 1) throw new Error(`Runner epoch is not starting: ${runnerEpoch}`);
   }
 
-  markWorkerReady(workerEpoch: string): void {
+  markRunnerReady(runnerEpoch: string): void {
     const now = Date.now();
     const changed = this.state.connection
       .prepare(
         `UPDATE run_workers SET status = 'running', ready_at = ?
          WHERE worker_epoch = ? AND status = 'starting'`,
       )
-      .run(now, workerEpoch);
-    if (changed.changes !== 1) throw new Error(`Worker epoch cannot become ready: ${workerEpoch}`);
+      .run(now, runnerEpoch);
+    if (changed.changes !== 1) throw new Error(`Runner epoch cannot become ready: ${runnerEpoch}`);
   }
 
-  finishWorker(options: {
-    workerEpoch: string;
-    outcome: WorkerOutcome;
+  finishRunner(options: {
+    runnerEpoch: string;
+    outcome: RunnerOutcome;
     exitCode?: number | null;
     signal?: string | null;
     diagnostic?: string;
@@ -367,36 +375,39 @@ export class HostStateStore {
           options.exitCode ?? null,
           options.signal ?? null,
           diagnosticHash,
-          options.workerEpoch,
+          options.runnerEpoch,
         );
       if (changed.changes !== 1)
-        throw new Error(`Worker epoch is not active: ${options.workerEpoch}`);
+        throw new Error(`Runner epoch is not active: ${options.runnerEpoch}`);
     });
   }
 
-  readWorkerMessage(message: WorkerMessage): WorkerResponse | undefined {
+  readRunnerMessage(message: WorkflowRunnerMessage): WorkflowRunnerResponse | undefined {
     const row = this.state.connection
       .prepare(
         `SELECT request_fingerprint AS clientRequestFingerprint, outcome,
                 accepted_revision AS revision, result_hash AS resultHash, error_hash AS errorHash
          FROM worker_messages WHERE worker_epoch = ? AND message_id = ?`,
       )
-      .get(message.workerEpoch, message.messageId);
-    if (!isWorkerMessageRow(row)) return undefined;
-    if (!row.clientRequestFingerprint.equals(workerMessageFingerprint(message))) {
+      .get(message.runnerEpoch, message.messageId);
+    if (!isRunnerMessageRow(row)) return undefined;
+    if (!row.clientRequestFingerprint.equals(runnerMessageFingerprint(message))) {
       return {
         schema: "pi-workflows.worker-response.v1",
         messageId: message.messageId,
         outcome: "rejected",
-        error: "Worker message ID was reused with another payload",
+        error: "Runner message ID was reused with another payload",
       };
     }
-    return workerMessageResponse(this.state, message.messageId, row);
+    return runnerMessageResponse(this.state, message.messageId, row);
   }
 
-  recordWorkerMessage(message: WorkerMessage, response: WorkerResponse): WorkerResponse {
+  recordRunnerMessage(
+    message: WorkflowRunnerMessage,
+    response: WorkflowRunnerResponse,
+  ): WorkflowRunnerResponse {
     return this.state.transaction(() => {
-      const existing = this.readWorkerMessage(message);
+      const existing = this.readRunnerMessage(message);
       if (existing !== undefined) return existing;
       const now = Date.now();
       const resultHash =
@@ -411,9 +422,9 @@ export class HostStateStore {
            ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
         )
         .run(
-          message.workerEpoch,
+          message.runnerEpoch,
           message.messageId,
-          workerMessageFingerprint(message),
+          runnerMessageFingerprint(message),
           response.outcome,
           response.revision ?? null,
           resultHash,
@@ -1055,16 +1066,16 @@ export class HostStateStore {
     });
   }
 
-  private hostRow(): HostRow {
+  private serverRow(): ServerRow {
     const row = this.state.connection
       .prepare(
-        `SELECT epoch, host_id AS hostId, token_hash AS tokenHash, pid,
+        `SELECT epoch, host_id AS serverId, token_hash AS tokenHash, pid,
                 process_start_identity AS processStartIdentity, started_at AS startedAt,
                 heartbeat_at AS heartbeatAt, expires_at AS expiresAt
          FROM workflow_host_state WHERE id = 1`,
       )
       .get();
-    if (!isHostRow(row)) throw new Error("Pi Workflows host state is missing");
+    if (!isServerRow(row)) throw new Error("Pi Workflows server state is missing");
     return row;
   }
 
@@ -1151,16 +1162,16 @@ function conflictResponse(requestId: string, error: string): ClientResponse {
 
 function requireLeaseMs(value: number): void {
   if (!Number.isSafeInteger(value) || value <= 0)
-    throw new Error("Host lease duration must be positive");
+    throw new Error("Server lease duration must be positive");
 }
 
 function iso(value: number | null): string | null {
   return value === null ? null : new Date(value).toISOString();
 }
 
-type HostRow = {
+type ServerRow = {
   epoch: number;
-  hostId: string | null;
+  serverId: string | null;
   tokenHash: Buffer | null;
   pid: number | null;
   processStartIdentity: string | null;
@@ -1196,9 +1207,9 @@ type SubmissionDetailRow = {
   receiptHash: Buffer | null;
   submittedAt: number;
 };
-type WorkerMessageRow = {
+type WorkflowRunnerMessageRow = {
   clientRequestFingerprint: Buffer;
-  outcome: WorkerResponse["outcome"];
+  outcome: WorkflowRunnerResponse["outcome"];
   revision: number | null;
   resultHash: Buffer | null;
   errorHash: Buffer | null;
@@ -1249,11 +1260,11 @@ type InteractiveRequestRow = {
   consumedAt: number | null;
 };
 
-function isHostRow(value: unknown): value is HostRow {
+function isServerRow(value: unknown): value is ServerRow {
   return (
     isRecord(value) &&
     typeof value.epoch === "number" &&
-    nullableString(value.hostId) &&
+    nullableString(value.serverId) &&
     (value.tokenHash === null || Buffer.isBuffer(value.tokenHash)) &&
     (value.pid === null || typeof value.pid === "number") &&
     nullableString(value.processStartIdentity) &&
@@ -1290,7 +1301,7 @@ function isRunIdRow(value: unknown): value is RunIdRow {
   return isRecord(value) && typeof value.runId === "string";
 }
 
-function isWorkerMessageRow(value: unknown): value is WorkerMessageRow {
+function isRunnerMessageRow(value: unknown): value is WorkflowRunnerMessageRow {
   return (
     isRecord(value) &&
     Buffer.isBuffer(value.clientRequestFingerprint) &&
@@ -1401,15 +1412,15 @@ function isInteractiveRequestRow(value: unknown): value is InteractiveRequestRow
   );
 }
 
-function workerMessageFingerprint(message: WorkerMessage): Buffer {
+function runnerMessageFingerprint(message: WorkflowRunnerMessage): Buffer {
   return createHash("sha256").update(canonicalJson(message)).digest();
 }
 
-function workerMessageResponse(
+function runnerMessageResponse(
   state: StateDatabase,
   messageId: string,
-  row: WorkerMessageRow,
-): WorkerResponse {
+  row: WorkflowRunnerMessageRow,
+): WorkflowRunnerResponse {
   const result = row.resultHash === null ? undefined : state.readJson(row.resultHash);
   const error =
     row.errorHash === null ? undefined : state.readBlob(row.errorHash)?.content.toString("utf8");

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

@@ -11,10 +11,10 @@ import {
   type WorkflowSessionView,
 } from "../client/view.js";
 import type {
-  SqliteControllerStore,
+  SqliteResourceManagerStore,
   WorkflowRunQueueRecord,
   WorkflowRunQueueViewRecord,
-} from "../controllers/sqlite.js";
+} from "../resource-managers/sqlite.js";
 import type { StateDatabase } from "../state/database.js";
 import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
 import { WorkflowMessageStore, type WorkflowMessage } from "../state/workflow-messages.js";
@@ -27,7 +27,7 @@ import type {
   WorkflowTraceEvent,
   WorkflowUpdateRecord,
 } from "../workflows/types.js";
-import type { HostStateStore } from "./state.js";
+import type { ServerStateStore } from "./state.js";
 
 export const WORKFLOW_PAGE_KINDS = [
   "steps",
@@ -63,7 +63,7 @@ const CONTENT_CACHE_BYTES = 64 * 1024 * 1024;
 const VIEW_CACHE_ITEMS = 64;
 const TERMINAL_VIEW_RETENTION_MS = 60_000;
 
-export class HostViewStore {
+export class ServerViewStore {
   private readonly contentRecords = new Map<string, ContentRecord>();
   private readonly listCache = new Map<string, { revision: string; page: WorkflowRunListPage }>();
   private readonly runCache = new Map<string, { version: string; view: WorkflowRunView | null }>();
@@ -74,13 +74,13 @@ export class HostViewStore {
 
   constructor(
     private readonly state: StateDatabase,
-    private readonly queue: SqliteControllerStore,
-    private readonly hostState: HostStateStore,
+    private readonly queue: SqliteResourceManagerStore,
+    private readonly serverState: ServerStateStore,
     private readonly runs: WorkflowRunStore,
-    private readonly hasLiveWorker: (runId: string) => boolean,
+    private readonly hasLiveRunner: (runId: string) => boolean,
     private readonly hasActiveSessionTurn: (targetSessionId: string) => boolean,
   ) {
-    this.workflowMessages = hostState.workflowMessages;
+    this.workflowMessages = serverState.workflowMessages;
   }
 
   noteOriginActivityChange(): void {
@@ -324,7 +324,7 @@ export class HostViewStore {
       const retainedRunId =
         activeQueue === undefined ? this.retainedTerminalRunId(sessionId) : undefined;
       const runId = activeQueue?.runId ?? retainedRunId;
-      const pending = this.hostState.listPendingInteractions(sessionId);
+      const pending = this.serverState.listPendingInteractions(sessionId);
       const pendingInteractions = byteBoundedForwardPage(pending, (request) =>
         this.projectRecordField(request.runId, request, "contract"),
       );
@@ -613,7 +613,7 @@ export class HostViewStore {
   }
 
   clearConnection(_connectionId: string): void {
-    // Coordinator fencing is process-local in the host. Durable turn state is
+    // Coordinator fencing is process-local in the server. Durable turn state is
     // reconciled from the Pi branch after the next coordinator connects.
   }
 
@@ -792,7 +792,7 @@ export class HostViewStore {
       durableStatus: state?.status,
       paused: state?.paused === true,
       ambiguous: this.hasAmbiguousEffect(queue.runId),
-      workerActive: this.hasLiveWorker(queue.runId),
+      runnerActive: this.hasLiveRunner(queue.runId),
       originTurnActive: this.hasActivity(queue.runId),
       pendingInteraction: this.hasPendingInteraction(queue.runId),
       errorMessage: state?.error ?? queue.errorMessage,
@@ -855,7 +855,7 @@ export class HostViewStore {
       row.runStatus,
       row.paused,
       this.workflowActivityRevision(),
-      this.hasLiveWorker(runId),
+      this.hasLiveRunner(runId),
       this.hasActivity(runId),
       this.hasPendingInteraction(runId),
       this.hasAmbiguousEffect(runId),
@@ -888,7 +888,7 @@ export type WorkflowDisplayFacts = {
   durableStatus: WorkflowRunState["status"] | undefined;
   paused: boolean;
   ambiguous: boolean;
-  workerActive: boolean;
+  runnerActive: boolean;
   originTurnActive: boolean;
   pendingInteraction: boolean;
   errorMessage: string | null;
@@ -902,9 +902,9 @@ export function reduceWorkflowDisplay(facts: WorkflowDisplayFacts): WorkflowDisp
   if (facts.ambiguous) {
     status = "ambiguous";
     reason = "An external effect needs explicit recovery.";
-  } else if (facts.workerActive || facts.originTurnActive) {
+  } else if (facts.runnerActive || facts.originTurnActive) {
     status = "running";
-    activity = facts.workerActive ? "supervised_worker" : "origin_turn";
+    activity = facts.runnerActive ? "supervised_runner" : "origin_turn";
   } else if (
     facts.durableStatus === "completed" ||
     facts.durableStatus === "failed" ||

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

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import type { StateDatabase } from "../state/database.js";
+import { canonicalJson, parseJson, type JsonValue } from "../state/json.js";
+import {
+  WORKFLOW_RUNNER_CONTENT_CHUNK_BYTES,
+  WORKFLOW_RUNNER_CONTENT_CHUNK_SCHEMA,
+  WORKFLOW_RUNNER_CONTENT_REFERENCE_SCHEMA,
+  encodeRunnerLine,
+  type WorkflowRunnerContentChunk,
+  type WorkflowRunnerContentReference,
+  type WorkflowRunnerResponse,
+} from "./workflow-runner-protocol.js";
+
+const CONTENT_MEDIA_TYPE = "application/json" as const;
+
+export function boundRunnerResponse(
+  state: StateDatabase,
+  allowedDigests: Set<string>,
+  response: WorkflowRunnerResponse,
+): WorkflowRunnerResponse {
+  try {
+    encodeRunnerLine(response);
+    return response;
+  } catch {
+    if (response.result === undefined) return responseTooLarge(response.messageId);
+    try {
+      const content = Buffer.from(canonicalJson(response.result), "utf8");
+      const sha256 = state.putBlob(content, CONTENT_MEDIA_TYPE).toString("hex");
+      allowedDigests.add(sha256);
+      const referenced: WorkflowRunnerResponse = {
+        ...response,
+        result: {
+          schema: WORKFLOW_RUNNER_CONTENT_REFERENCE_SCHEMA,
+          sha256,
+          mediaType: CONTENT_MEDIA_TYPE,
+          bytes: content.byteLength,
+        },
+      };
+      encodeRunnerLine(referenced);
+      return referenced;
+    } catch {
+      return responseTooLarge(response.messageId);
+    }
+  }
+}
+
+export function readRunnerContentChunk(
+  state: StateDatabase,
+  allowedDigests: ReadonlySet<string>,
+  sha256: string,
+  offset: number,
+): WorkflowRunnerContentChunk {
+  if (!/^[0-9a-f]{64}$/u.test(sha256) || !allowedDigests.has(sha256)) {
+    throw new Error("Workflow runner content is unavailable");
+  }
+  if (!Number.isSafeInteger(offset) || offset < 0) {
+    throw new Error("Workflow runner content offset is invalid");
+  }
+  const stored = state.readBlob(Buffer.from(sha256, "hex"));
+  if (stored === undefined || stored.mediaType !== CONTENT_MEDIA_TYPE) {
+    throw new Error("Workflow runner content is unavailable");
+  }
+  if (offset > stored.byteLength) throw new Error("Workflow runner content offset is invalid");
+  const nextOffset = Math.min(offset + WORKFLOW_RUNNER_CONTENT_CHUNK_BYTES, stored.byteLength);
+  return {
+    schema: WORKFLOW_RUNNER_CONTENT_CHUNK_SCHEMA,
+    sha256,
+    mediaType: CONTENT_MEDIA_TYPE,
+    bytes: stored.byteLength,
+    offset,
+    nextOffset,
+    complete: nextOffset === stored.byteLength,
+    data: stored.content.subarray(offset, nextOffset).toString("base64url"),
+  };
+}
+
+export async function materializeRunnerContent(
+  reference: WorkflowRunnerContentReference,
+  readChunk: (offset: number) => Promise<WorkflowRunnerContentChunk>,
+): Promise<JsonValue> {
+  const parts: Buffer[] = [];
+  let offset = 0;
+  for (;;) {
+    const chunk = await readChunk(offset);
+    const bytes = Buffer.from(chunk.data, "base64url");
+    if (
+      chunk.sha256 !== reference.sha256 ||
+      chunk.mediaType !== reference.mediaType ||
+      chunk.bytes !== reference.bytes ||
+      chunk.offset !== offset ||
+      chunk.nextOffset !== offset + bytes.byteLength ||
+      chunk.nextOffset > reference.bytes ||
+      chunk.complete !== (chunk.nextOffset === reference.bytes)
+    ) {
+      throw new Error("Workflow runner content chunk is invalid");
+    }
+    parts.push(bytes);
+    offset = chunk.nextOffset;
+    if (chunk.complete) break;
+    if (bytes.byteLength === 0) throw new Error("Workflow runner content read made no progress");
+  }
+  const content = Buffer.concat(parts);
+  if (
+    content.byteLength !== reference.bytes ||
+    createHash("sha256").update(content).digest("hex") !== reference.sha256
+  ) {
+    throw new Error("Workflow runner content does not match its reference");
+  }
+  return parseJson(content.toString("utf8"));
+}
+
+function responseTooLarge(messageId: string): WorkflowRunnerResponse {
+  return {
+    schema: "pi-workflows.worker-response.v1",
+    messageId,
+    outcome: "rejected",
+    error: "Workflow runner response could not be transferred within the protocol limit",
+  };
+}