@osolmaz/pi-workflows 0.15.2 → 0.16.0

package/dist/host/runner.js

@@ -1,8 +1,9 @@
 import { createHash, randomUUID } from "node:crypto";
-import { once } from "node:events";
 import fs from "node:fs";
 import net, {} from "node:net";
 import path from "node:path";
+import { WorkflowClient } from "../client/client.js";
+import { CLIENT_PROTOCOL_SCHEMA, encodeProtocolLine, clientSocketPath, NdjsonFrameDecoder, parseClientRequest, } from "../client/protocol.js";
 import { applyStatusPatch } from "../controllers/conditions.js";
 import { ResourceConflictError } from "../controllers/errors.js";
 import { controllerFileStem, controllerSearchDirs, discoverControllers, } from "../controllers/loader.js";
@@ -10,20 +11,21 @@ import { SqliteControllerStore, } from "../controllers/sqlite.js";
 import { ControllerWorkflowCoordinator, } from "../controllers/workflows.js";
 import { StateDatabase, workflowStatePath } from "../state/database.js";
 import { canonicalJson } 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";
 import {} from "../workflows/settings.js";
 import { WorkflowRunStore } from "../workflows/store.js";
 import { validateWorkflowUpdate } from "../workflows/updates.js";
-import { WorkflowHostClient } from "./client.js";
 import { ControllerWorkerSupervisor } from "./controller-worker-supervisor.js";
 import { HostProcessRegistry, matchesProcessIdentity, processParentPid, processStartIdentity, } from "./processes.js";
-import { encodeProtocolLine, hostSocketPath, NdjsonFrameDecoder, parseHostRequest, } from "./protocol.js";
 import { HostStateStore, } from "./state.js";
+import { HostViewStore, WORKFLOW_PAGE_KINDS, } from "./view.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;
@@ -45,22 +47,26 @@ export class WorkflowHost {
     queue;
     decisions;
     runStore;
+    views;
     registry;
     activeRuns = new Map();
     workerDescendants = new Map();
     activeControllers = new Map();
     controlClaims = new Map();
     activationTasks = new Map();
+    maintenanceCommands = new Map();
     pendingStarts = new Set();
     pendingRunClaims = new Map();
     pendingResumes = new Set();
     blockedRuns = new Set();
     deliveryClaims = new Map();
     sockets = new Set();
+    connections = new Map();
     server = null;
     claim = null;
     heartbeatTimer = null;
     pollTimer = null;
+    viewTimer = null;
     stopping = false;
     started = false;
     controllerPollActive = false;
@@ -70,7 +76,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 });
@@ -90,6 +96,7 @@ 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);
     }
     get endpoint() {
@@ -156,8 +163,11 @@ export class WorkflowHost {
             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);
@@ -179,6 +189,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)
@@ -258,6 +269,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?.();
     }
     async listen() {
         if (process.platform !== "win32")
@@ -293,8 +309,20 @@ export class WorkflowHost {
     }
     handleConnection(socket) {
         this.sockets.add(socket);
+        const connection = {
+            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) => {
             let frames;
             try {
@@ -305,14 +333,13 @@ export class WorkflowHost {
                 return;
             }
             for (const frame of frames) {
-                processing = processing
-                    .then(async () => {
-                    const request = parseHostRequest(frame);
-                    const response = this.handleRequest(request);
+                void (async () => {
+                    const request = parseClientRequest(frame);
+                    const response = await this.handleClientRequest(connection, request);
                     if (!socket.write(encodeProtocolLine(response)))
-                        await once(socket, "drain");
-                })
-                    .catch(() => {
+                        await waitForSocketDrain(socket);
+                    this.publishConnection(connection);
+                })().catch(() => {
                     socket.destroy();
                 });
             }
@@ -323,12 +350,243 @@ export class WorkflowHost {
         });
         socket.on("close", () => {
             this.sockets.delete(socket);
+            this.connections.delete(socket);
+            this.views.clearConnection(connection.id);
+        });
+    }
+    async handleClientRequest(connection, request) {
+        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)) {
+                        throw new Error("view.page kind is invalid");
+                    }
+                    const view = this.views.page(requireRunId(request), {
+                        kind: kind,
+                        cursor: requireNonNegativeInteger(payload.cursor, "cursor"),
+                    });
+                    return view === null
+                        ? clientResponse(request.requestId, "notFound", undefined, "Workflow run not found")
+                        : clientResponse(request.requestId, "accepted", runPageReceipt(view, kind, 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));
+        }
+    }
+    async executeMaintenanceCommand(request, operation) {
+        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 () => {
+            let result;
+            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);
+            }
+        }
+    }
+    addSubscription(connection, request, kind, target) {
+        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,
         });
     }
+    publishViews() {
+        for (const connection of this.connections.values())
+            void this.publishConnection(connection);
+    }
+    async publishConnection(connection) {
+        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 = {
+                    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;
+        }
+    }
+    async submitInteractionAndWait(request) {
+        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);
+        }
+    }
     handleRequest(request) {
         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",
@@ -341,7 +599,8 @@ export class WorkflowHost {
         }
         catch (error) {
             response = {
-                schema: "pi-workflows.host-response.v1",
+                schema: CLIENT_PROTOCOL_SCHEMA,
+                type: "response",
                 requestId: request.requestId,
                 outcome: "rejected",
                 error: errorMessage(error),
@@ -402,15 +661,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 } };
                 }
@@ -447,18 +728,41 @@ 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,
-                    };
+                    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,
+                        };
+                    }
+                    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({
@@ -478,6 +782,20 @@ 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`);
         }
     }
     executeControllerOperation(request) {
@@ -578,6 +896,27 @@ export class WorkflowHost {
          )`),
         };
     }
+    stateStatusReceipt() {
+        const count = (sql, ...params) => {
+            const row = this.state.connection.prepare(sql).get(...params);
+            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')"),
+            },
+        };
+    }
     rememberDeliveryClaim(options) {
         const now = Date.now();
         for (const [claimId, claim] of this.deliveryClaims) {
@@ -585,11 +924,9 @@ export class WorkflowHost {
                 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() };
     }
     deliveryClaim(claimId, clientId, kind, resourceId, targetSessionId) {
         const claim = this.deliveryClaims.get(claimId);
@@ -604,8 +941,34 @@ export class WorkflowHost {
         }
         return claim;
     }
+    validateDelivery(command, payload, kind) {
+        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 } };
+    }
     claimNotification(command) {
         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({
@@ -617,7 +980,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,
@@ -626,7 +989,7 @@ export class WorkflowHost {
         });
         return {
             outcome: "accepted",
-            receipt: { claimId, notification },
+            receipt: { ...claim, notification },
         };
     }
     deliverNotification(command) {
@@ -650,6 +1013,9 @@ export class WorkflowHost {
     }
     claimTurn(command) {
         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({
@@ -661,7 +1027,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,
@@ -670,7 +1036,7 @@ export class WorkflowHost {
         });
         return {
             outcome: "accepted",
-            receipt: { claimId, turn: intent },
+            receipt: { ...claim, turn: intent },
         };
     }
     resolveTurn(command) {
@@ -740,6 +1106,9 @@ export class WorkflowHost {
         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;
         const response = payload.response;
         const accepted = this.decisions.acceptSync(request, {
@@ -878,6 +1247,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");
@@ -931,6 +1303,9 @@ export class WorkflowHost {
         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");
@@ -954,6 +1329,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);
         }
@@ -973,7 +1351,7 @@ export class WorkflowHost {
         return {
             outcome: submission.outcome,
             revision: interaction.revision,
-            receipt: submission.receipt,
+            receipt,
         };
     }
     async claimControllerOne() {
@@ -1256,7 +1634,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 }),
         });
@@ -1303,7 +1681,7 @@ export class WorkflowHost {
         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 }),
         });
@@ -2364,6 +2742,129 @@ function controllerPathAllowed(projectPath, controllerName, controllerPath) {
     }
     return controllerSearchDirs({ cwd: projectPath }).some(({ dir }) => path.dirname(controllerPath) === path.resolve(dir));
 }
+function waitForSocketDrain(socket) {
+    if (socket.destroyed)
+        return Promise.resolve();
+    return new Promise((resolve, reject) => {
+        const cleanup = () => {
+            socket.off("drain", onDrain);
+            socket.off("close", onClose);
+            socket.off("error", onError);
+        };
+        const onDrain = () => {
+            cleanup();
+            resolve();
+        };
+        const onClose = () => {
+            cleanup();
+            resolve();
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        socket.once("drain", onDrain);
+        socket.once("close", onClose);
+        socket.once("error", onError);
+        if (socket.destroyed)
+            onClose();
+    });
+}
+function hostDelay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function runPageReceipt(view, kind, cursor) {
+    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") };
+    }
+    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 } : {}),
+        };
+    }
+    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, outcome, receipt, error, revision) {
+    return {
+        schema: CLIENT_PROTOCOL_SCHEMA,
+        type: "response",
+        requestId,
+        outcome,
+        ...(revision === undefined ? {} : { revision }),
+        ...(receipt === undefined ? {} : { receipt }),
+        ...(error === undefined ? {} : { error: boundedClientError(error) }),
+    };
+}
+function boundedClientError(error) {
+    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) {
+    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) {
+    return JSON.parse(canonicalJson(value));
+}
 function payloadLimit(payload) {
     if (typeof payload !== "object" || payload === null || Array.isArray(payload))
         return 100;
@@ -2375,6 +2876,9 @@ function requireRunId(request) {
         throw new Error(`${request.operation} requires runId`);
     return request.runId;
 }
+function isObjectRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 function requireRecord(value, name) {
     if (typeof value !== "object" || value === null || Array.isArray(value)) {
         throw new Error(`${name} must be an object`);
@@ -2393,6 +2897,17 @@ function requireAbsolutePath(value, name) {
         throw new Error(`${name} must be an absolute path`);
     return parsed;
 }
+function requireBoolean(value, name) {
+    if (typeof value !== "boolean")
+        throw new Error(`${name} must be a boolean`);
+    return value;
+}
+function requirePositiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0) {
+        throw new Error(`${name} must be a positive integer`);
+    }
+    return value;
+}
 function requireNonNegativeInteger(value, name) {
     if (!Number.isSafeInteger(value) || value < 0) {
         throw new Error(`${name} must be a non-negative integer`);
@@ -2404,6 +2919,13 @@ function isRevisionRow(value) {
         value !== null &&
         typeof value.revision === "number");
 }
+function runtimePackageVersion() {
+    const parsed = JSON.parse(fs.readFileSync(new URL("../../package.json", import.meta.url), "utf8"));
+    if (typeof parsed.version !== "string" || parsed.version.length === 0) {
+        throw new Error("Package version is missing");
+    }
+    return parsed.version;
+}
 function isLockRecord(value) {
     return (typeof value === "object" &&
         value !== null &&