@osolmaz/pi-workflows 0.15.2 → 0.16.0

package/src/host/runner.ts

@@ -1,8 +1,20 @@
 import { createHash, randomUUID } from "node:crypto";
-import { once } from "node:events";
 import fs from "node:fs";
 import net, { type Socket } from "node:net";
 import path from "node:path";
+import { WorkflowClient } from "../client/client.js";
+import {
+  CLIENT_PROTOCOL_SCHEMA,
+  encodeProtocolLine,
+  clientSocketPath,
+  NdjsonFrameDecoder,
+  parseClientRequest,
+  type ClientEvent,
+  type ClientOutcome,
+  type ClientRequest,
+  type ClientResponse,
+} from "../client/protocol.js";
+import type { WorkflowRunView } from "../client/view.js";
 import { applyStatusPatch } from "../controllers/conditions.js";
 import { ResourceConflictError } from "../controllers/errors.js";
 import {
@@ -31,6 +43,7 @@ import {
 } from "../controllers/workflows.js";
 import { StateDatabase, workflowStatePath } from "../state/database.js";
 import { canonicalJson, type JsonValue } from "../state/json.js";
+import { pruneState } from "../state/prune.js";
 import { recordViewerDeltas } from "../state/viewer.js";
 import { errorMessage } from "../workflows/errors.js";
 import { HumanDecisionStore } from "../workflows/human-decision.js";
@@ -49,7 +62,6 @@ import type {
   WorkflowUpdateInput,
 } from "../workflows/types.js";
 import { validateWorkflowUpdate } from "../workflows/updates.js";
-import { WorkflowHostClient } from "./client.js";
 import type {
   ControllerWorkerLaunchEnvelope,
   ControllerWorkerMessage,
@@ -62,14 +74,6 @@ import {
   processParentPid,
   processStartIdentity,
 } from "./processes.js";
-import {
-  encodeProtocolLine,
-  hostSocketPath,
-  NdjsonFrameDecoder,
-  parseHostRequest,
-  type HostRequest,
-  type HostResponse,
-} from "./protocol.js";
 import {
   HostStateStore,
   type HostClaim,
@@ -77,11 +81,18 @@ import {
   type InteractiveSubmissionRecord,
   type WorkerLaunchEnvelope,
 } from "./state.js";
+import {
+  HostViewStore,
+  WORKFLOW_PAGE_KINDS,
+  type OriginActivityReport,
+  type WorkflowPageKind,
+} from "./view.js";
 import type { WorkerMessage, WorkerResponse } from "./worker-protocol.js";
 import { WorkflowWorkerSupervisor } from "./worker-supervisor.js";
 
 const HOST_LEASE_MS = 30_000;
 const HOST_RENEW_MS = 10_000;
+const PACKAGE_VERSION = runtimePackageVersion();
 const CLAIM_POLL_MS = 2_000;
 const RUN_CLAIM_LEASE_MS = 30_000;
 const PRESENTATION_CLAIM_LEASE_MS = 10_000;
@@ -130,6 +141,22 @@ type DeliveryClaim = {
   expiresAt: number;
 };
 
+type ClientSubscription = {
+  id: string;
+  kind: "runs" | "run" | "session";
+  target?: string;
+  revision: number;
+  limit?: number;
+  digest?: string;
+};
+
+type ClientConnection = {
+  id: string;
+  socket: Socket;
+  subscriptions: Map<string, ClientSubscription>;
+  publishing: boolean;
+};
+
 type ActiveController = {
   key: string;
   projectPath: string;
@@ -156,22 +183,26 @@ export class WorkflowHost {
   private readonly queue: SqliteControllerStore;
   private readonly decisions: HumanDecisionStore;
   private readonly runStore: WorkflowRunStore;
+  private readonly views: HostViewStore;
   private readonly registry: HostProcessRegistry;
   private readonly activeRuns = new Map<string, ActiveRun>();
   private readonly workerDescendants = new Map<string, Set<number>>();
   private readonly activeControllers = new Map<string, ActiveController>();
   private readonly controlClaims = new Map<string, string>();
   private readonly activationTasks = new Map<string, Promise<void>>();
+  private readonly maintenanceCommands = new Map<string, Promise<ClientResponse>>();
   private readonly pendingStarts = new Set<string>();
   private readonly pendingRunClaims = new Map<string, string>();
   private readonly pendingResumes = new Set<string>();
   private readonly blockedRuns = new Set<string>();
   private readonly deliveryClaims = new Map<string, DeliveryClaim>();
   private readonly sockets = new Set<Socket>();
+  private readonly connections = new Map<Socket, ClientConnection>();
   private server: net.Server | null = null;
   private claim: HostClaim | null = null;
   private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
   private pollTimer: ReturnType<typeof setInterval> | null = null;
+  private viewTimer: ReturnType<typeof setInterval> | null = null;
   private stopping = false;
   private started = false;
   private controllerPollActive = false;
@@ -182,7 +213,7 @@ export class WorkflowHost {
     this.hostId = options.runnerId ?? `host-${randomUUID()}`;
     this.databasePath = path.resolve(options.databasePath ?? workflowStatePath());
     this.stateDirectory = path.join(path.dirname(this.databasePath), "host");
-    this.socketPath = hostSocketPath(this.databasePath);
+    this.socketPath = clientSocketPath(this.databasePath);
     this.lockPath = path.join(this.stateDirectory, "host.lock.json");
     this.state = new StateDatabase({ filePath: this.databasePath });
     this.hostState = new HostStateStore(this.databasePath, { state: this.state });
@@ -202,6 +233,9 @@ export class WorkflowHost {
       },
       snapshotLifecycle: (context) => this.applyLifecycleProjection(context),
     });
+    this.views = new HostViewStore(this.state, this.queue, this.hostState, this.runStore, (runId) =>
+      this.activeRuns.has(runId),
+    );
     this.registry = options.registry ?? new HostProcessRegistry(this.stateDirectory);
   }
 
@@ -264,8 +298,10 @@ export class WorkflowHost {
     this.stopping = true;
     if (this.heartbeatTimer !== null) clearInterval(this.heartbeatTimer);
     if (this.pollTimer !== null) clearInterval(this.pollTimer);
+    if (this.viewTimer !== null) clearInterval(this.viewTimer);
     this.heartbeatTimer = null;
     this.pollTimer = null;
+    this.viewTimer = null;
     const server = this.server;
     this.server = null;
     await this.closeServer(server);
@@ -295,6 +331,7 @@ export class WorkflowHost {
       }),
     );
     await Promise.allSettled(this.activationTasks.values());
+    await Promise.allSettled(this.maintenanceCommands.values());
     this.registry.killAll();
     this.deliveryClaims.clear();
     if (this.claim !== null) this.hostState.releaseHost(this.claim);
@@ -378,6 +415,11 @@ export class WorkflowHost {
       void this.claimControllerOne();
     }, this.options.claimPollMs ?? CLAIM_POLL_MS);
     this.pollTimer.unref?.();
+    this.viewTimer = setInterval(() => {
+      this.views.expireActivity();
+      this.publishViews();
+    }, 250);
+    this.viewTimer.unref?.();
   }
 
   private async listen(): Promise<void> {
@@ -412,8 +454,22 @@ export class WorkflowHost {
 
   private handleConnection(socket: Socket): void {
     this.sockets.add(socket);
+    const connection: ClientConnection = {
+      id: `connection-${randomUUID()}`,
+      socket,
+      subscriptions: new Map(),
+      publishing: false,
+    };
+    this.connections.set(socket, connection);
+    socket.write(
+      encodeProtocolLine({
+        schema: CLIENT_PROTOCOL_SCHEMA,
+        type: "hello",
+        connectionId: connection.id,
+        packageVersion: PACKAGE_VERSION,
+      }),
+    );
     const decoder = new NdjsonFrameDecoder();
-    let processing = Promise.resolve();
     socket.on("data", (chunk: Buffer) => {
       let frames: Buffer[];
       try {
@@ -423,15 +479,14 @@ export class WorkflowHost {
         return;
       }
       for (const frame of frames) {
-        processing = processing
-          .then(async () => {
-            const request = parseHostRequest(frame);
-            const response = this.handleRequest(request);
-            if (!socket.write(encodeProtocolLine(response))) await once(socket, "drain");
-          })
-          .catch(() => {
-            socket.destroy();
-          });
+        void (async () => {
+          const request = parseClientRequest(frame);
+          const response = await this.handleClientRequest(connection, request);
+          if (!socket.write(encodeProtocolLine(response))) await waitForSocketDrain(socket);
+          this.publishConnection(connection);
+        })().catch(() => {
+          socket.destroy();
+        });
       }
     });
     socket.on("error", (error) => {
@@ -440,27 +495,331 @@ export class WorkflowHost {
     });
     socket.on("close", () => {
       this.sockets.delete(socket);
+      this.connections.delete(socket);
+      this.views.clearConnection(connection.id);
+    });
+  }
+
+  private async handleClientRequest(
+    connection: ClientConnection,
+    request: ClientRequest,
+  ): Promise<ClientResponse> {
+    try {
+      switch (request.operation) {
+        case "view.runs.watch":
+          this.addSubscription(connection, request, "runs");
+          return clientResponse(request.requestId, "accepted", { subscribed: true });
+        case "view.runs.page": {
+          const payload = requireRecord(request.payload, "view.runs.page payload");
+          const revision = requireString(payload.revision, "revision");
+          const page = this.views.list(
+            requireNonNegativeInteger(payload.cursor, "cursor"),
+            payload.limit === undefined
+              ? undefined
+              : requirePositiveInteger(payload.limit, "limit"),
+          );
+          return page.revision === revision
+            ? clientResponse(request.requestId, "accepted", toJsonValue(page))
+            : clientResponse(
+                request.requestId,
+                "conflict",
+                toJsonValue(page),
+                "Workflow run list changed while paging",
+              );
+        }
+        case "view.run.get": {
+          const view = this.views.run(requireRunId(request));
+          return view === null
+            ? clientResponse(request.requestId, "notFound", undefined, "Workflow run not found")
+            : clientResponse(
+                request.requestId,
+                "accepted",
+                toJsonValue(view),
+                undefined,
+                view.revision,
+              );
+        }
+        case "view.run.watch": {
+          const runId = requireRunId(request);
+          if (this.views.run(runId) === null) {
+            return clientResponse(
+              request.requestId,
+              "notFound",
+              undefined,
+              "Workflow run not found",
+            );
+          }
+          this.addSubscription(connection, request, "run", runId);
+          return clientResponse(request.requestId, "accepted", { subscribed: true });
+        }
+        case "view.session.watch": {
+          const payload = requireRecord(request.payload, "view.session.watch payload");
+          this.addSubscription(
+            connection,
+            request,
+            "session",
+            requireString(payload.sessionId, "sessionId"),
+          );
+          return clientResponse(request.requestId, "accepted", { subscribed: true });
+        }
+        case "view.run.unwatch": {
+          const payload = requireRecord(request.payload, "view.run.unwatch payload");
+          connection.subscriptions.delete(requireString(payload.subscriptionId, "subscriptionId"));
+          return clientResponse(request.requestId, "accepted", { subscribed: false });
+        }
+        case "view.page": {
+          const payload = requireRecord(request.payload, "view.page payload");
+          const kind = requireString(payload.kind, "kind");
+          if (!WORKFLOW_PAGE_KINDS.includes(kind as WorkflowPageKind)) {
+            throw new Error("view.page kind is invalid");
+          }
+          const view = this.views.page(requireRunId(request), {
+            kind: kind as WorkflowPageKind,
+            cursor: requireNonNegativeInteger(payload.cursor, "cursor"),
+          });
+          return view === null
+            ? clientResponse(request.requestId, "notFound", undefined, "Workflow run not found")
+            : clientResponse(
+                request.requestId,
+                "accepted",
+                runPageReceipt(
+                  view,
+                  kind as WorkflowPageKind,
+                  requireNonNegativeInteger(payload.cursor, "cursor"),
+                ),
+                undefined,
+                view.revision,
+              );
+        }
+        case "view.content": {
+          const payload = requireRecord(request.payload, "view.content payload");
+          const content = this.views.content(
+            requireRunId(request),
+            requireString(payload.path, "path"),
+            requireNonNegativeInteger(payload.offset, "offset"),
+          );
+          return content === null
+            ? clientResponse(request.requestId, "notFound", undefined, "Workflow content not found")
+            : clientResponse(request.requestId, "accepted", content);
+        }
+        case "activity.report": {
+          this.views.reportActivity(connection.id, parseActivityReport(request.payload));
+          return clientResponse(request.requestId, "accepted", { recorded: true });
+        }
+        case "interaction.submit":
+          return await this.submitInteractionAndWait(request);
+        case "state.status":
+          return clientResponse(request.requestId, "accepted", this.stateStatusReceipt());
+        case "state.verify":
+          this.state.integrityCheck();
+          return clientResponse(request.requestId, "accepted", { valid: true });
+        case "state.backup":
+          return await this.executeMaintenanceCommand(request, async () => {
+            const payload = requireRecord(request.payload, "state.backup payload");
+            const destination = requireAbsolutePath(payload.destination, "destination");
+            await this.state.backup(destination);
+            return { destination };
+          });
+        case "state.prune":
+          return await this.executeMaintenanceCommand(request, async () => {
+            const payload = requireRecord(request.payload, "state.prune payload");
+            const before = requireString(payload.before, "before");
+            const apply = requireBoolean(payload.apply, "apply");
+            const backupPath =
+              payload.backupPath === undefined
+                ? undefined
+                : requireAbsolutePath(payload.backupPath, "backupPath");
+            const report = await pruneState(this.state, this.databasePath, {
+              before,
+              apply,
+              ...(backupPath === undefined ? {} : { backupPath }),
+            });
+            return toJsonValue(report);
+          });
+        default:
+          return this.handleRequest(request);
+      }
+    } catch (error) {
+      return clientResponse(request.requestId, "rejected", undefined, errorMessage(error));
+    }
+  }
+
+  private async executeMaintenanceCommand(
+    request: ClientRequest,
+    operation: () => Promise<JsonValue>,
+  ): Promise<ClientResponse> {
+    const adopted = this.hostState.adoptCommand(request);
+    if (adopted !== undefined) return adopted;
+    const claim = this.claim;
+    if (claim === null || this.stopping) {
+      return clientResponse(
+        request.requestId,
+        "unavailable",
+        undefined,
+        "Workflow host is stopping",
+      );
+    }
+    const key = canonicalJson([request.clientId, request.idempotencyKey]);
+    const active = this.maintenanceCommands.get(key);
+    if (active !== undefined) {
+      await active;
+      return (
+        this.hostState.adoptCommand(request) ??
+        clientResponse(
+          request.requestId,
+          "unavailable",
+          undefined,
+          "Workflow maintenance command did not complete durably",
+        )
+      );
+    }
+
+    const execution = (async (): Promise<ClientResponse> => {
+      let result: Omit<ClientResponse, "schema" | "type" | "requestId">;
+      try {
+        result = { outcome: "accepted", receipt: await operation() };
+      } catch (error) {
+        result = { outcome: "rejected", error: errorMessage(error) };
+      }
+      return this.hostState.executeCommand(request, claim.epoch, () => result);
+    })();
+    this.maintenanceCommands.set(key, execution);
+    try {
+      return await execution;
+    } finally {
+      if (this.maintenanceCommands.get(key) === execution) {
+        this.maintenanceCommands.delete(key);
+      }
+    }
+  }
+
+  private addSubscription(
+    connection: ClientConnection,
+    request: ClientRequest,
+    kind: ClientSubscription["kind"],
+    target?: string,
+  ): void {
+    const payload = requireRecord(request.payload, `${request.operation} payload`);
+    const id = requireString(payload.subscriptionId, "subscriptionId");
+    const limit =
+      kind === "runs" && payload.limit !== undefined
+        ? requirePositiveInteger(payload.limit, "limit")
+        : undefined;
+    connection.subscriptions.set(id, {
+      id,
+      kind,
+      ...(target === undefined ? {} : { target }),
+      ...(limit === undefined ? {} : { limit }),
+      revision: 0,
     });
   }
 
-  private handleRequest(request: HostRequest): HostResponse {
+  private publishViews(): void {
+    for (const connection of this.connections.values()) void this.publishConnection(connection);
+  }
+
+  private async publishConnection(connection: ClientConnection): Promise<void> {
+    if (connection.publishing || connection.socket.destroyed) return;
+    connection.publishing = true;
+    try {
+      for (const subscription of connection.subscriptions.values()) {
+        const payload =
+          subscription.kind === "runs"
+            ? toJsonValue(this.views.list(0, subscription.limit))
+            : subscription.kind === "run"
+              ? toJsonValue(this.views.run(subscription.target ?? ""))
+              : toJsonValue(this.views.session(subscription.target ?? ""));
+        const digest = createHash("sha256").update(canonicalJson(payload)).digest("hex");
+        if (subscription.digest === digest) continue;
+        subscription.digest = digest;
+        subscription.revision += 1;
+        const event: ClientEvent = {
+          schema: CLIENT_PROTOCOL_SCHEMA,
+          type: "event",
+          subscriptionId: subscription.id,
+          event:
+            subscription.kind === "runs"
+              ? "runs"
+              : subscription.kind === "run"
+                ? "run_snapshot"
+                : "session_snapshot",
+          revision: subscription.revision,
+          ...(subscription.kind === "run" && subscription.target !== undefined
+            ? { runId: subscription.target }
+            : {}),
+          payload,
+        };
+        if (!connection.socket.write(encodeProtocolLine(event))) {
+          await waitForSocketDrain(connection.socket);
+          if (connection.socket.destroyed) return;
+        }
+      }
+    } catch (error) {
+      this.log(`client view error: ${errorMessage(error)}`);
+      connection.socket.destroy();
+    } finally {
+      connection.publishing = false;
+    }
+  }
+
+  private async submitInteractionAndWait(request: ClientRequest): Promise<ClientResponse> {
+    const started = this.submitInteraction(request);
+    if (started.outcome !== "accepted" && started.outcome !== "adopted") {
+      return clientResponse(request.requestId, started.outcome, started.receipt, started.error);
+    }
+    const payload = requireRecord(request.payload, "interaction payload");
+    const requestId = requireString(payload.requestId, "requestId");
+    const startedReceipt = requireRecord(started.receipt, "interaction submission receipt");
+    const submissionId = requireString(startedReceipt.submissionId, "submissionId");
+    for (;;) {
+      if (this.stopping) {
+        return clientResponse(
+          request.requestId,
+          "unavailable",
+          undefined,
+          "Workflow host stopped while validating the submission",
+        );
+      }
+      const submission = this.hostState.interactionSubmission(requestId, submissionId);
+      if (submission?.outcome === "accepted" || submission?.outcome === "adopted") {
+        return clientResponse(
+          request.requestId,
+          started.outcome,
+          submission.receipt ?? { requestId, submissionId },
+        );
+      }
+      if (submission?.outcome === "rejected") {
+        const receipt = submission.receipt ?? { requestId, submissionId };
+        const detail =
+          isObjectRecord(receipt) && typeof receipt.error === "string"
+            ? receipt.error
+            : "Workflow step output failed validation";
+        return clientResponse(request.requestId, "rejected", receipt, detail);
+      }
+      await hostDelay(25);
+    }
+  }
+
+  private handleRequest(request: ClientRequest): ClientResponse {
     if (this.claim === null || this.stopping) {
       return {
-        schema: "pi-workflows.host-response.v1",
+        schema: CLIENT_PROTOCOL_SCHEMA,
+        type: "response",
         requestId: request.requestId,
         outcome: "unavailable",
         error: "Workflow host is stopping",
       };
     }
     const afterCommit: Array<() => void> = [];
-    let response: HostResponse;
+    let response: ClientResponse;
     try {
       response = this.hostState.executeCommand(request, this.claim.epoch, () =>
         this.executeOperation(request, afterCommit),
       );
     } catch (error) {
       response = {
-        schema: "pi-workflows.host-response.v1",
+        schema: CLIENT_PROTOCOL_SCHEMA,
+        type: "response",
         requestId: request.requestId,
         outcome: "rejected",
         error: errorMessage(error),
@@ -471,9 +830,9 @@ export class WorkflowHost {
   }
 
   private executeOperation(
-    request: HostRequest,
+    request: ClientRequest,
     afterCommit: Array<() => void>,
-  ): Omit<HostResponse, "schema" | "requestId"> {
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     switch (request.operation) {
       case "host.status":
         return { outcome: "accepted", receipt: this.statusReceipt() };
@@ -526,14 +885,37 @@ export class WorkflowHost {
       case "run.pause": {
         const runId = requireRunId(request);
         const active = this.activeRuns.get(runId);
-        if (active === undefined) return { outcome: "rejected", error: "Run is not active" };
-        this.commitActivePause(active);
-        active.control = "pause";
-        afterCommit.push(() => void active.supervisor.stop("cancelled"));
-        return { outcome: "accepted", receipt: { runId, status: "parked", paused: true } };
+        if (active !== undefined) {
+          if (active.control === "pause") {
+            return { outcome: "adopted", receipt: { runId, status: "parked", paused: true } };
+          }
+          if (active.control === "handoff") {
+            const paused = this.queue.pauseParkedWorkflowRun({ runId });
+            return paused
+              ? { outcome: "accepted", receipt: { runId, status: "parked", paused: true } }
+              : { outcome: "rejected", error: "Run handoff is not pausable" };
+          }
+          if (active.control !== undefined) {
+            return { outcome: "rejected", error: `Run is already handling ${active.control}` };
+          }
+          this.commitActivePause(active);
+          active.control = "pause";
+          afterCommit.push(() => void active.supervisor.stop("cancelled"));
+          return { outcome: "accepted", receipt: { runId, status: "parked", paused: true } };
+        }
+        const paused = this.queue.pauseParkedWorkflowRun({ runId });
+        return paused
+          ? { outcome: "accepted", receipt: { runId, status: "parked", paused: true } }
+          : { outcome: "rejected", error: "Run is not pausable" };
       }
       case "run.resume": {
         const runId = requireRunId(request);
+        if (this.queue.resumePausedInteraction({ runId })) {
+          return {
+            outcome: "accepted",
+            receipt: { runId, status: "parked", paused: false, waitingForInteraction: true },
+          };
+        }
         if (this.activeRuns.has(runId) || this.pendingStarts.has(runId)) {
           return { outcome: "adopted", receipt: { runId, active: true } };
         }
@@ -569,21 +951,49 @@ export class WorkflowHost {
         return this.executeControllerOperation(request);
       case "interaction.update": {
         const payload = requireRecord(request.payload, "interaction update payload");
+        if (payload.validatePresentation === true) {
+          const interaction = this.hostState.getInteraction(
+            requireString(payload.requestId, "requestId"),
+          );
+          const expectedRevision = requireNonNegativeInteger(
+            request.expectedRevision,
+            "expectedRevision",
+          );
+          const expiresAt = interaction?.presentationClaimExpiresAt;
+          const live =
+            interaction !== undefined &&
+            interaction.runId === requireRunId(request) &&
+            interaction.status === "presenting" &&
+            interaction.presenterId === request.clientId &&
+            interaction.revision === expectedRevision &&
+            interaction.presentationSessionEntryId === null &&
+            typeof expiresAt === "string" &&
+            Date.parse(expiresAt) > Date.now() &&
+            !this.queue.isWorkflowRunPaused(interaction.runId);
+          return { outcome: "accepted", receipt: { live } };
+        }
         if (payload.claimPresentation === true) {
-          const interaction = this.hostState.claimInteractionPresentation({
-            requestId: requireString(payload.requestId, "requestId"),
-            expectedRevision: requireNonNegativeInteger(
-              request.expectedRevision,
-              "expectedRevision",
-            ),
-            presenterId: request.clientId,
-            leaseMs: PRESENTATION_CLAIM_LEASE_MS,
-          });
-          return {
-            outcome: "accepted",
-            revision: interaction.revision,
-            receipt: interaction as unknown as JsonValue,
-          };
+          try {
+            const interaction = this.hostState.claimInteractionPresentation({
+              requestId: requireString(payload.requestId, "requestId"),
+              expectedRevision: requireNonNegativeInteger(
+                request.expectedRevision,
+                "expectedRevision",
+              ),
+              presenterId: request.clientId,
+              leaseMs: PRESENTATION_CLAIM_LEASE_MS,
+            });
+            return {
+              outcome: "accepted",
+              revision: interaction.revision,
+              receipt: interaction as unknown as JsonValue,
+            };
+          } catch (error) {
+            if (errorMessage(error) === "Interactive request presentation claim conflict") {
+              return { outcome: "conflict", error: errorMessage(error) };
+            }
+            throw error;
+          }
         }
         if (typeof payload.sessionEntryId === "string") {
           const interaction = this.hostState.markInteractionPresented({
@@ -606,12 +1016,26 @@ export class WorkflowHost {
         return this.submitInteraction(request);
       case "decision.answer":
         return this.answerDecision(request, afterCommit);
+      case "view.runs.watch":
+      case "view.runs.page":
+      case "view.run.get":
+      case "view.run.watch":
+      case "view.run.unwatch":
+      case "view.page":
+      case "view.content":
+      case "view.session.watch":
+      case "activity.report":
+      case "state.status":
+      case "state.verify":
+      case "state.backup":
+      case "state.prune":
+        throw new Error(`${request.operation} must use the live client connection`);
     }
   }
 
   private executeControllerOperation(
-    request: HostRequest,
-  ): Omit<HostResponse, "schema" | "requestId"> {
+    request: ClientRequest,
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const payload = requireRecord(request.payload, "controller payload");
     const projectPath = path.resolve(requireString(payload.projectPath, "projectPath"));
     if (payload.projectPath !== projectPath) {
@@ -722,17 +1146,51 @@ export class WorkflowHost {
     };
   }
 
-  private rememberDeliveryClaim(options: Omit<DeliveryClaim, "expiresAt">): string {
+  private stateStatusReceipt(): JsonValue {
+    const count = (sql: string, ...params: unknown[]): number => {
+      const row = this.state.connection.prepare(sql).get(...params) as
+        | { count?: unknown }
+        | undefined;
+      return typeof row?.count === "number" ? row.count : 0;
+    };
+    const now = Date.now();
+    return {
+      sizeBytes: fs.statSync(this.databasePath).size,
+      counts: {
+        resources: count("SELECT COUNT(*) AS count FROM resources"),
+        runs: count("SELECT COUNT(*) AS count FROM runs"),
+        controllers: count("SELECT COUNT(*) AS count FROM controller_resources"),
+        decisions: count("SELECT COUNT(*) AS count FROM human_decisions"),
+        settingsScopes: count("SELECT COUNT(*) AS count FROM workflow_settings"),
+        pendingInteractions: count(
+          "SELECT COUNT(*) AS count FROM interactive_requests WHERE status IN ('pending', 'presenting')",
+        ),
+        pendingFollowUps: count(
+          "SELECT COUNT(*) AS count FROM workflow_follow_ups WHERE status IN ('queued', 'pending_presentation', 'ready')",
+        ),
+        activeLeases: count(
+          "SELECT COUNT(*) AS count FROM leases WHERE owner_id IS NOT NULL AND expires_at > ?",
+          now,
+        ),
+        unsettledEffects: count(
+          "SELECT COUNT(*) AS count FROM effects WHERE status IN ('pending', 'applying', 'ambiguous')",
+        ),
+      },
+    };
+  }
+
+  private rememberDeliveryClaim(options: Omit<DeliveryClaim, "expiresAt">): {
+    claimId: string;
+    claimExpiresAt: string;
+  } {
     const now = Date.now();
     for (const [claimId, claim] of this.deliveryClaims) {
       if (claim.expiresAt <= now) this.deliveryClaims.delete(claimId);
     }
     const claimId = randomUUID();
-    this.deliveryClaims.set(claimId, {
-      ...options,
-      expiresAt: now + DELIVERY_CLAIM_LEASE_MS,
-    });
-    return claimId;
+    const expiresAt = now + DELIVERY_CLAIM_LEASE_MS;
+    this.deliveryClaims.set(claimId, { ...options, expiresAt });
+    return { claimId, claimExpiresAt: new Date(expiresAt).toISOString() };
   }
 
   private deliveryClaim(
@@ -757,8 +1215,41 @@ export class WorkflowHost {
     return claim;
   }
 
-  private claimNotification(command: HostRequest): Omit<HostResponse, "schema" | "requestId"> {
+  private validateDelivery(
+    command: ClientRequest,
+    payload: Record<string, unknown>,
+    kind: DeliveryClaim["kind"],
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
+    const resourceId = requireString(payload.resourceId, "resourceId");
+    const targetSessionId = requireString(payload.targetSessionId, "targetSessionId");
+    const claimId = requireString(payload.claimId, "claimId");
+    const claim = this.deliveryClaim(claimId, command.clientId, kind, resourceId, targetSessionId);
+    if (claim === undefined) {
+      return { outcome: "accepted", receipt: { claimId, live: false } };
+    }
+    const live =
+      kind === "notification"
+        ? this.queue.isWorkflowNotificationClaimLive({
+            notificationId: resourceId,
+            targetSessionId,
+            claimToken: claim.token,
+          })
+        : this.queue.isWorkflowTurnIntentClaimLive({
+            intentId: resourceId,
+            targetSessionId,
+            claimToken: claim.token,
+          });
+    if (!live) this.deliveryClaims.delete(claimId);
+    return { outcome: "accepted", receipt: { claimId, live } };
+  }
+
+  private claimNotification(
+    command: ClientRequest,
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const payload = requireRecord(command.payload, "notification claim payload");
+    if (payload.validateClaim === true) {
+      return this.validateDelivery(command, payload, "notification");
+    }
     const targetSessionId = requireString(payload.targetSessionId, "targetSessionId");
     const token = randomUUID();
     const notification = this.queue.claimPendingWorkflowNotifications({
@@ -770,7 +1261,7 @@ export class WorkflowHost {
     if (notification === undefined) {
       return { outcome: "accepted", receipt: { notification: null } };
     }
-    const claimId = this.rememberDeliveryClaim({
+    const claim = this.rememberDeliveryClaim({
       clientId: command.clientId,
       token,
       targetSessionId,
@@ -779,11 +1270,13 @@ export class WorkflowHost {
     });
     return {
       outcome: "accepted",
-      receipt: { claimId, notification } as unknown as JsonValue,
+      receipt: { ...claim, notification } as unknown as JsonValue,
     };
   }
 
-  private deliverNotification(command: HostRequest): Omit<HostResponse, "schema" | "requestId"> {
+  private deliverNotification(
+    command: ClientRequest,
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const payload = requireRecord(command.payload, "notification delivery payload");
     const notificationId = requireString(payload.notificationId, "notificationId");
     const targetSessionId = requireString(payload.targetSessionId, "targetSessionId");
@@ -809,8 +1302,11 @@ export class WorkflowHost {
       : { outcome: "conflict", error: "Notification delivery claim is stale" };
   }
 
-  private claimTurn(command: HostRequest): Omit<HostResponse, "schema" | "requestId"> {
+  private claimTurn(command: ClientRequest): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const payload = requireRecord(command.payload, "turn claim payload");
+    if (payload.validateClaim === true) {
+      return this.validateDelivery(command, payload, "turn");
+    }
     const targetSessionId = requireString(payload.targetSessionId, "targetSessionId");
     const token = randomUUID();
     const intent = this.queue.claimEligibleWorkflowTurnIntents({
@@ -822,7 +1318,7 @@ export class WorkflowHost {
     if (intent === undefined) {
       return { outcome: "accepted", receipt: { turn: null } };
     }
-    const claimId = this.rememberDeliveryClaim({
+    const claim = this.rememberDeliveryClaim({
       clientId: command.clientId,
       token,
       targetSessionId,
@@ -831,11 +1327,13 @@ export class WorkflowHost {
     });
     return {
       outcome: "accepted",
-      receipt: { claimId, turn: intent } as unknown as JsonValue,
+      receipt: { ...claim, turn: intent } as unknown as JsonValue,
     };
   }
 
-  private resolveTurn(command: HostRequest): Omit<HostResponse, "schema" | "requestId"> {
+  private resolveTurn(
+    command: ClientRequest,
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const payload = requireRecord(command.payload, "turn resolution payload");
     const intentId = requireString(payload.intentId, "intentId");
     const targetSessionId = requireString(payload.targetSessionId, "targetSessionId");
@@ -858,9 +1356,9 @@ export class WorkflowHost {
   }
 
   private answerCheckpoint(
-    command: HostRequest,
+    command: ClientRequest,
     afterCommit: Array<() => void>,
-  ): Omit<HostResponse, "schema" | "requestId"> {
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const parentRunId = requireRunId(command);
     const payload = requireRecord(command.payload, "checkpoint answer payload");
     const continuationRunId = requireString(payload.continuationRunId, "continuationRunId");
@@ -904,15 +1402,18 @@ export class WorkflowHost {
   }
 
   private answerDecision(
-    command: HostRequest,
+    command: ClientRequest,
     afterCommit: Array<() => void>,
-  ): Omit<HostResponse, "schema" | "requestId"> {
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const payload = requireRecord(command.payload, "decision answer payload");
     const requestId = requireString(payload.requestId, "requestId");
     const interaction = this.hostState.getInteraction(requestId);
     if (interaction === undefined || interaction.kind !== "decision") {
       return { outcome: "notFound", error: `Decision request not found: ${requestId}` };
     }
+    if (this.queue.isWorkflowRunPaused(interaction.runId)) {
+      return { outcome: "conflict", error: "Workflow run is paused" };
+    }
     const request = interaction.contract as unknown as HumanDecisionRequest;
     const response = payload.response as HumanDecisionResponse;
     const accepted = this.decisions.acceptSync(request, {
@@ -1028,9 +1529,9 @@ export class WorkflowHost {
   }
 
   private startRun(
-    request: HostRequest,
+    request: ClientRequest,
     afterCommit: Array<() => void>,
-  ): Omit<HostResponse, "schema" | "requestId"> {
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const runId = requireRunId(request);
     const payload = requireRecord(request.payload, "run.start payload");
     const projectPath = requireAbsolutePath(payload.projectPath, "projectPath");
@@ -1076,8 +1577,8 @@ export class WorkflowHost {
   }
 
   private publishInteractionUpdate(
-    request: HostRequest,
-  ): Omit<HostResponse, "schema" | "requestId"> {
+    request: ClientRequest,
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const runId = requireRunId(request);
     const payload = requireRecord(request.payload, "interaction update payload");
     const requestId = requireString(payload.requestId, "requestId");
@@ -1085,6 +1586,9 @@ export class WorkflowHost {
     if (interaction === undefined || interaction.runId !== runId) {
       return { outcome: "notFound", error: `Interactive request not found: ${requestId}` };
     }
+    if (this.queue.isWorkflowRunPaused(runId)) {
+      return { outcome: "conflict", error: "Workflow run is paused" };
+    }
     const attemptId = requireString(payload.attempt, "attempt");
     const nodeId = requireString(payload.step, "step");
     const storedContract = requireRecord(interaction.contract, "interactive contract");
@@ -1141,13 +1645,18 @@ export class WorkflowHost {
     }
   }
 
-  private submitInteraction(request: HostRequest): Omit<HostResponse, "schema" | "requestId"> {
+  private submitInteraction(
+    request: ClientRequest,
+  ): Omit<ClientResponse, "schema" | "type" | "requestId"> {
     const payload = requireRecord(request.payload, "interaction payload");
     const requestId = requireString(payload.requestId, "requestId");
     const current = this.hostState.getInteraction(requestId);
     if (current === undefined || current.runId !== requireRunId(request)) {
       return { outcome: "notFound", error: `Interactive request not found: ${requestId}` };
     }
+    if (this.queue.isWorkflowRunPaused(current.runId)) {
+      return { outcome: "conflict", error: "Workflow run is paused" };
+    }
     const attemptId = requireString(payload.attempt, "attempt");
     const nodeId = requireString(payload.step, "step");
     const storedContract = requireRecord(current.contract, "interactive contract");
@@ -1173,6 +1682,9 @@ export class WorkflowHost {
       },
     });
     const interaction = submission.interaction;
+    const receipt = isObjectRecord(submission.receipt)
+      ? { ...submission.receipt, requestId, submissionId: submission.submissionId }
+      : { requestId, submissionId: submission.submissionId, receipt: submission.receipt };
     if (this.activeRuns.has(interaction.runId) || this.activationTasks.has(interaction.runId)) {
       this.pendingResumes.add(interaction.runId);
     } else {
@@ -1191,7 +1703,7 @@ export class WorkflowHost {
     return {
       outcome: submission.outcome,
       revision: interaction.revision,
-      receipt: submission.receipt,
+      receipt,
     };
   }
 
@@ -1504,7 +2016,7 @@ export class WorkflowHost {
     }
     const projectPath = this.queue.workflowRunProjectPath(request.runId);
     if (projectPath === undefined) throw new Error("Workflow run project is missing");
-    const resolver = new WorkflowHostClient({
+    const resolver = new WorkflowClient({
       databasePath: this.databasePath,
       ...(this.options.env === undefined ? {} : { env: this.options.env }),
     });
@@ -1554,7 +2066,7 @@ export class WorkflowHost {
   ): Promise<WorkflowSchedulerResult> {
     const existing = this.queue.getWorkflowRun(request.runId);
     if (existing !== undefined) return controllerWorkflowResult(existing);
-    const resolver = new WorkflowHostClient({
+    const resolver = new WorkflowClient({
       databasePath: this.databasePath,
       ...(this.options.env === undefined ? {} : { env: this.options.env }),
     });
@@ -2850,17 +3362,157 @@ function controllerPathAllowed(
   );
 }
 
+function waitForSocketDrain(socket: Socket): Promise<void> {
+  if (socket.destroyed) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const cleanup = (): void => {
+      socket.off("drain", onDrain);
+      socket.off("close", onClose);
+      socket.off("error", onError);
+    };
+    const onDrain = (): void => {
+      cleanup();
+      resolve();
+    };
+    const onClose = (): void => {
+      cleanup();
+      resolve();
+    };
+    const onError = (error: Error): void => {
+      cleanup();
+      reject(error);
+    };
+    socket.once("drain", onDrain);
+    socket.once("close", onClose);
+    socket.once("error", onError);
+    if (socket.destroyed) onClose();
+  });
+}
+
+function hostDelay(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function runPageReceipt(view: WorkflowRunView, kind: WorkflowPageKind, cursor: number): JsonValue {
+  const base = {
+    schema: "pi-workflows.run-page.v1",
+    runId: view.runId,
+    revision: view.revision,
+    kind,
+    cursor,
+  };
+  if (kind === "steps") {
+    const state = requireRecord(view.state, "run state view");
+    return {
+      ...base,
+      start: view.stepStart,
+      total: view.stepTotal,
+      items: Array.isArray(state.steps) ? state.steps : [],
+      graphSteps: view.graphSteps,
+      graphCursor: view.graphCursor,
+      takenTransitions: view.takenTransitions,
+    };
+  }
+  if (kind === "trace" || kind === "trace_at_step") {
+    return { ...base, ...requireRecord(view.tracePage, "trace page") } as JsonValue;
+  }
+  if (kind === "session_entries" || kind === "session_events") {
+    const session = requireRecord(view.session, "session view");
+    const page = requireRecord(
+      kind === "session_entries" ? session.entryPage : session.eventPage,
+      "session page",
+    );
+    return {
+      ...base,
+      ...page,
+      ...(kind === "session_events" ? { replayCheckpoint: session.replayCheckpoint } : {}),
+    } as JsonValue;
+  }
+  if (kind === "settings") {
+    return {
+      ...base,
+      start: view.settingsStart,
+      total: view.settingsTotal,
+      items: view.settingsScopes,
+    };
+  }
+  if (kind === "follow_ups") {
+    const queue = isObjectRecord(view.followUpQueue) ? view.followUpQueue : {};
+    return {
+      ...base,
+      start: view.followUpStart,
+      total: view.followUpTotal,
+      items: Array.isArray(queue.items) ? queue.items : [],
+    };
+  }
+  return {
+    ...base,
+    start: view.updateStart,
+    total: view.updateTotal,
+    items: view.updates,
+  };
+}
+
+function clientResponse(
+  requestId: string,
+  outcome: ClientOutcome,
+  receipt?: JsonValue,
+  error?: string,
+  revision?: number,
+): ClientResponse {
+  return {
+    schema: CLIENT_PROTOCOL_SCHEMA,
+    type: "response",
+    requestId,
+    outcome,
+    ...(revision === undefined ? {} : { revision }),
+    ...(receipt === undefined ? {} : { receipt }),
+    ...(error === undefined ? {} : { error: boundedClientError(error) }),
+  };
+}
+
+function boundedClientError(error: string): string {
+  const singleLine = error.replaceAll(/[\r\n\t]+/gu, " ").trim();
+  if (singleLine.length === 0) return "Workflow request failed";
+  return singleLine.length <= 1_000 ? singleLine : `${singleLine.slice(0, 997)}...`;
+}
+
+function parseActivityReport(payload: JsonValue): OriginActivityReport {
+  const value = requireRecord(payload, "activity.report payload");
+  const state = requireString(value.state, "state");
+  if (state !== "started" && state !== "refresh" && state !== "settled") {
+    throw new Error("activity state must be started, refresh, or settled");
+  }
+  return {
+    sessionId: requireString(value.sessionId, "sessionId"),
+    runId: requireString(value.runId, "runId"),
+    requestId: requireString(value.requestId, "requestId"),
+    deliveryId: requireString(value.deliveryId, "deliveryId"),
+    sessionEntryId: requireString(value.sessionEntryId, "sessionEntryId"),
+    sequence: requireNonNegativeInteger(value.sequence, "sequence"),
+    state,
+  };
+}
+
+function toJsonValue(value: unknown): JsonValue {
+  return JSON.parse(canonicalJson(value)) as JsonValue;
+}
+
 function payloadLimit(payload: JsonValue): number {
   if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return 100;
   const limit = (payload as Record<string, unknown>).limit;
   return typeof limit === "number" && Number.isSafeInteger(limit) && limit > 0 ? limit : 100;
 }
 
-function requireRunId(request: HostRequest): string {
+function requireRunId(request: ClientRequest): string {
   if (request.runId === undefined) throw new Error(`${request.operation} requires runId`);
   return request.runId;
 }
 
+function isObjectRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 function requireRecord(value: unknown, name: string): Record<string, unknown> {
   if (typeof value !== "object" || value === null || Array.isArray(value)) {
     throw new Error(`${name} must be an object`);
@@ -2881,6 +3533,18 @@ function requireAbsolutePath(value: unknown, name: string): string {
   return parsed;
 }
 
+function requireBoolean(value: unknown, name: string): boolean {
+  if (typeof value !== "boolean") throw new Error(`${name} must be a boolean`);
+  return value;
+}
+
+function requirePositiveInteger(value: unknown, name: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) <= 0) {
+    throw new Error(`${name} must be a positive integer`);
+  }
+  return value as number;
+}
+
 function requireNonNegativeInteger(value: unknown, name: string): number {
   if (!Number.isSafeInteger(value) || (value as number) < 0) {
     throw new Error(`${name} must be a non-negative integer`);
@@ -2896,6 +3560,16 @@ function isRevisionRow(value: unknown): value is { revision: number } {
   );
 }
 
+function runtimePackageVersion(): string {
+  const parsed = JSON.parse(
+    fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+  ) as { version?: unknown };
+  if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+    throw new Error("Package version is missing");
+  }
+  return parsed.version;
+}
+
 function isLockRecord(
   value: unknown,
 ): value is { schema: string; pid: number; startIdentity: string; hostId: string } {