@osolmaz/pi-workflows 0.16.4 → 0.16.6

package/dist/workflows/engine.js

@@ -5,12 +5,14 @@ import { StaleResourceError } from "../state/mutation.js";
 import { compileWorkflowDefinition, compositionMetadata, isCompiledWorkflow, } from "./composition.js";
 import { CancelledError, errorMessage, isAbortLikeError, isClaimLostError, isRunParkedError, RunParkedError, TimeoutError, WorkflowSourceChangedError, } from "./errors.js";
 import { resolveNext, resolveNextForOutcome, validateWorkflowDefinition } from "./graph.js";
-import { createHumanDecisionRequest, validateHumanDecisionResponse } from "./human-decision.js";
+import { createHumanDecisionRequest } from "./human-decision.js";
 import { extractJsonValue } from "./json.js";
+import { workflowRequestId } from "./requests.js";
 import { parseWorkflowSettingsValue, resolveInitialWorkflowSettings, } from "./settings.js";
 import { runShellAction, shellResultFromError } from "./shell.js";
 import { RUN_STATE_SCHEMA, WorkflowRunStore, createDefinitionSnapshot, createRunId, } from "./store.js";
-import { UpdateRateLimiter, updateReceipt, validateWorkflowUpdate } from "./updates.js";
+import { executionTransition } from "./transitions.js";
+import { UpdateRateLimiter, updateProjection, updateReceipt, validateWorkflowUpdate, } from "./updates.js";
 const DEFAULT_NODE_TIMEOUT_MS = 15 * 60_000;
 const DEFAULT_MAX_STEPS = 100;
 const TITLE_TIMEOUT_MS = 30_000;
@@ -32,7 +34,6 @@ export class WorkflowEngine {
     maxSteps;
     onEvent;
     onRunStarted;
-    onRunFinishing;
     activeAbort = null;
     activeAttempt;
     updateLimiters = new Map();
@@ -40,7 +41,6 @@ export class WorkflowEngine {
     cancelled = false;
     parked = false;
     paused = false;
-    presentationRequired = false;
     wakePause = null;
     constructor(options) {
         this.executor = options.executor;
@@ -50,7 +50,6 @@ export class WorkflowEngine {
         this.maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
         this.onEvent = options.onEvent;
         this.onRunStarted = options.onRunStarted;
-        this.onRunFinishing = options.onRunFinishing;
     }
     get databasePath() {
         return this.store.databasePath;
@@ -80,7 +79,10 @@ export class WorkflowEngine {
                 this.updateLimiters.set(active.state.runId, limiter);
             }
             limiter.take();
-            const { event, record } = await this.store.publishUpdate(active.runId, active.state, active.nodeId, active.attemptId, update, { signal: active.signal });
+            const { event, record } = await this.store.publishUpdate(active.runId, active.nodeId, active.attemptId, update, { signal: active.signal });
+            active.state.updates = updateProjection(active.state.updates, record);
+            active.state.traceSeq = event.seq;
+            active.state.updatedAt = event.at;
             try {
                 this.onEvent?.(event, active.state);
             }
@@ -133,7 +135,6 @@ export class WorkflowEngine {
     async run(workflow, input, options = {}) {
         workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
         validateWorkflowDefinition(workflow);
-        this.presentationRequired = workflow.presentationPrompt !== undefined;
         // Fail before any run row exists so bad input cannot leave partial state.
         const suppliedInput = input === undefined ? null : input;
         const normalizedInput = workflow.input ? await workflow.input(suppliedInput) : suppliedInput;
@@ -191,34 +192,37 @@ export class WorkflowEngine {
     async resumeRun(workflow, runId, options = {}) {
         workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
         validateWorkflowDefinition(workflow);
-        this.presentationRequired = workflow.presentationPrompt !== undefined;
         // Reset before any await: a park or cancel landing during preparation
         // must survive, or a server drain would hang while the run executes.
         this.cancelled = false;
         this.paused = false;
         this.parked = false;
-        const state = await this.store.prepareRunResume(runId);
-        const sourceMismatch = workflowIdentityMismatch(state, workflow, options.workflowSource);
+        const stored = await this.store.readRunState(runId);
+        if (stored === null)
+            throw new Error(`Cannot resume unreadable workflow run: ${runId}`);
+        const sourceMismatch = workflowIdentityMismatch(stored, workflow, options.workflowSource);
         if (sourceMismatch && options.force !== true) {
             throw new WorkflowSourceChangedError(runId);
         }
-        const point = this.resumePointFor(workflow, state, "wait");
+        const state = await this.store.prepareRunResume(runId);
+        const point = this.resumePointFor(workflow, state);
         const interruptedNode = state.currentNode !== undefined ? workflow.nodes[state.currentNode] : undefined;
         let resumedAttempt;
         if (state.currentNode !== undefined &&
             state.currentAttemptId !== undefined &&
             state.currentNodeStartedAt !== undefined &&
-            interruptedNode?.nodeType === "agent" &&
-            (assistantMessageConfig(interruptedNode) !== undefined ||
-                options.resumeInteractionAttemptId === state.currentAttemptId)) {
+            (interruptedNode?.nodeType === "checkpoint" ||
+                (interruptedNode?.nodeType === "agent" &&
+                    (assistantMessageConfig(interruptedNode) !== undefined ||
+                        options.resumeInteractionAttemptId === state.currentAttemptId)))) {
             const resumedSettings = await this.persistedSettingsBinding(state);
             resumedAttempt = {
                 nodeId: state.currentNode,
                 attemptId: state.currentAttemptId,
                 startedAt: state.currentNodeStartedAt,
-                ...(state.currentNodeDeadlineAt === undefined
+                ...(state.currentNodeTimeoutMs === undefined
                     ? {}
-                    : { deadlineAt: state.currentNodeDeadlineAt }),
+                    : { timeoutMs: state.currentNodeTimeoutMs, elapsedMs: state.currentNodeElapsedMs ?? 0 }),
                 ...(resumedSettings !== undefined ? { settings: resumedSettings } : {}),
             };
         }
@@ -231,7 +235,8 @@ export class WorkflowEngine {
             delete state.currentNode;
             delete state.currentAttemptId;
             delete state.currentNodeStartedAt;
-            delete state.currentNodeDeadlineAt;
+            delete state.currentNodeTimeoutMs;
+            delete state.currentNodeElapsedMs;
             delete state.currentSettingsScopeId;
             delete state.currentSettingsChangeNumber;
             delete state.currentSettingsHash;
@@ -249,16 +254,8 @@ export class WorkflowEngine {
         });
         await this.onRunStarted?.(runId, state);
         if (point.nodeId === null) {
-            // The last recorded transition already finished the graph; the crash
-            // happened before the terminal event was written. A finished
-            // checkpoint restores its waiting gate rather than completing.
-            if (point.waitingOn !== undefined) {
-                await this.finishRun(runId, state, "waiting", {
-                    waitingOn: point.waitingOn,
-                    finalOutput: point.lastOutput,
-                });
-            }
-            else if (point.failedResult === undefined) {
+            // The last attempt finished before the terminal event was committed.
+            if (point.failedResult === undefined) {
                 await this.finishRun(runId, state, "completed", { finalOutput: point.lastOutput });
             }
             else {
@@ -283,138 +280,12 @@ export class WorkflowEngine {
         }
         return { runId, state };
     }
-    /**
-     * Start a continuation run from a checkpointed parent. The new run gets a
-     * fresh run and event stream, carries forward the parent's outputs, results,
-     * and step accounting, and continues routing after the checkpoint.
-     */
-    async continueRun(workflow, parentRunId, input, options = {}) {
-        workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
-        validateWorkflowDefinition(workflow);
-        this.presentationRequired = workflow.presentationPrompt !== undefined;
-        this.cancelled = false;
-        this.paused = false;
-        this.parked = false;
-        const parentState = await this.store.readRunState(parentRunId);
-        if (parentState === null) {
-            throw new Error(`Cannot continue from unreadable workflow run: ${parentRunId}`);
-        }
-        if (parentState.status !== "waiting" || parentState.waitingOn === undefined) {
-            throw new Error(`Cannot continue workflow run ${parentRunId} with status ${parentState.status}`);
-        }
-        const sourceMismatch = workflowIdentityMismatch(parentState, workflow, options.workflowSource);
-        if (sourceMismatch && options.force !== true) {
-            throw new WorkflowSourceChangedError(parentRunId);
-        }
-        const waitingNodeId = parentState.waitingOn;
-        const waitingNode = workflow.nodes[waitingNodeId];
-        const humanContract = waitingNode?.nodeType === "checkpoint" ? waitingNode.humanDecision : undefined;
-        let acceptedResponse;
-        let acceptedNodeId;
-        let normalizedInput;
-        if (humanContract !== undefined) {
-            if (options.humanDecision === undefined) {
-                throw new Error(`Checkpoint ${waitingNodeId} requires an accepted verified human decision`);
-            }
-            const request = parentState.finalOutput;
-            if (request?.schema !== "pi-workflows.human-decision-request.v1" ||
-                request.decisionId !== options.humanDecision.decisionId ||
-                request.requestDigest !== options.humanDecision.requestDigest) {
-                throw new Error("Accepted human decision does not match the waiting request");
-            }
-            const durableDecision = await this.store.readResolvedHumanDecision(request.decisionId);
-            if (durableDecision === null || !isDeepStrictEqual(durableDecision, options.humanDecision)) {
-                throw new Error("Accepted human decision does not match the durable decision record");
-            }
-            acceptedResponse = validateHumanDecisionResponse(request, durableDecision.response);
-            acceptedNodeId = request.nodeId;
-            normalizedInput = structuredClone(parentState.input);
-        }
-        else {
-            const suppliedInput = input === undefined ? null : input;
-            normalizedInput = workflow.input ? await workflow.input(suppliedInput) : suppliedInput;
-        }
-        assertJsonSerializable(normalizedInput, "Workflow run input");
-        if (options.runId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._-]{0,199}$/.test(options.runId)) {
-            throw new Error(`Invalid workflow run id: ${JSON.stringify(options.runId)}`);
-        }
-        const state = await this.createRunState(workflow, normalizedInput, options.workflowSource, options.runId);
-        state.parentRunId = parentRunId;
-        state.outputs = structuredClone(parentState.outputs);
-        state.results = structuredClone(parentState.results);
-        state.steps = structuredClone(parentState.steps);
-        if (humanContract !== undefined && options.humanDecision !== undefined) {
-            const receipt = {
-                decisionId: options.humanDecision.decisionId,
-                requestDigest: options.humanDecision.requestDigest,
-                nodeId: acceptedNodeId ?? waitingNodeId,
-                response: options.humanDecision.response,
-                provenance: options.humanDecision.provenance,
-                acceptedAt: options.humanDecision.acceptedAt,
-                answerDigest: options.humanDecision.answerDigest,
-            };
-            state.humanDecision = {
-                schema: "pi-workflows.human-decision-receipt.v1",
-                ...receipt,
-                subjectDigest: options.humanDecision.subjectDigest,
-                presentationDigest: options.humanDecision.presentationDigest,
-                revision: options.humanDecision.revision,
-            };
-            state.outputs[waitingNodeId] = acceptedResponse;
-            const priorResult = state.results[waitingNodeId];
-            if (priorResult === undefined) {
-                throw new Error(`Waiting human decision result is missing for ${waitingNodeId}`);
-            }
-            state.results[waitingNodeId] = { ...priorResult, output: acceptedResponse };
-            const stepIndex = state.steps.findLastIndex((step) => step.nodeId === waitingNodeId);
-            if (stepIndex < 0)
-                throw new Error(`Waiting human decision step is missing for ${waitingNodeId}`);
-            const priorStep = state.steps[stepIndex];
-            if (priorStep === undefined)
-                throw new Error("Waiting human decision step became unavailable");
-            state.steps[stepIndex] = { ...priorStep, output: acceptedResponse };
-        }
-        state.carriedStepCount = state.steps.length;
-        const runId = await this.store.initializeRun(workflow, state);
-        await this.persist(runId, state, {
-            scope: "run",
-            type: "run_started",
-            payload: {
-                workflowName: workflow.name,
-                ...(state.runTitle ? { runTitle: state.runTitle } : {}),
-                input: state.input,
-                continuedFrom: parentRunId,
-                checkpoint: parentState.waitingOn,
-                carriedSteps: state.steps.length,
-            },
-        });
-        await this.onRunStarted?.(runId, state);
-        const point = this.resumePointFor(workflow, state, "continue");
-        if (point.nodeId === null) {
-            // The checkpoint was the final node; the answer completes the chain.
-            await this.finishRun(runId, state, "completed", { finalOutput: point.lastOutput });
-            return { runId, state };
-        }
-        try {
-            await this.executeGraph(workflow, state, runId, point.nodeId, countExecutableSteps(workflow, state.steps), point.lastOutput);
-        }
-        catch (error) {
-            if (isClaimLostError(error))
-                throw error;
-            if (isRunParkedError(error) || this.parked) {
-                return { runId, state };
-            }
-            await this.finishAfterError(runId, state, error);
-            return { runId, state };
-        }
-        return { runId, state };
-    }
     /**
      * Find where a resumed run continues. An in-flight node reruns; otherwise
      * routing continues from the last recorded step. A null nodeId means the
      * graph was already done when the crash hit.
      */
-    resumePointFor(workflow, state, checkpointBehavior) {
+    resumePointFor(workflow, state) {
         if (state.currentNode !== undefined) {
             if (workflow.nodes[state.currentNode] === undefined) {
                 throw new Error(`Resume node is missing from the workflow: ${state.currentNode}`);
@@ -430,17 +301,6 @@ export class WorkflowEngine {
             return { nodeId: lastStep.nodeId };
         }
         if (result.outcome === "ok") {
-            // A recorded checkpoint means the run should be waiting; a crash
-            // before the run_waiting persist restores the gate instead of
-            // routing past it. The gate applies to this run's own checkpoint
-            // only: a continuation's carried steps end with the parent's
-            // already-answered checkpoint, and routing must continue from it.
-            const isCarriedStep = state.steps.length <= (state.carriedStepCount ?? 0);
-            if (checkpointBehavior === "wait" &&
-                !isCarriedStep &&
-                workflow.nodes[lastStep.nodeId]?.nodeType === "checkpoint") {
-                return { nodeId: null, waitingOn: lastStep.nodeId, lastOutput: result.output };
-            }
             const next = resolveNext(workflow.edges, lastStep.nodeId, result.output, result);
             return next === null
                 ? { nodeId: null, lastOutput: result.output }
@@ -602,6 +462,7 @@ export class WorkflowEngine {
                         scopeId: latest.scopeId,
                         previousChangeNumber: attempt.settings.changeNumber,
                         changeNumber: latest.changeNumber,
+                        settingsHash: latest.settingsHash,
                     },
                 });
                 resumedAttempt = {
@@ -647,13 +508,6 @@ export class WorkflowEngine {
                 });
             }
             lastOutput = attempt.result.output;
-            if (node.nodeType === "checkpoint") {
-                await this.finishRun(runId, state, "waiting", {
-                    waitingOn: attempt.result.nodeId,
-                    finalOutput: lastOutput,
-                });
-                return;
-            }
             currentNodeId = resolveNext(workflow.edges, attempt.result.nodeId, attempt.result.output, attempt.result);
         }
         await this.finishRun(runId, state, "completed", { finalOutput: lastOutput });
@@ -749,7 +603,8 @@ export class WorkflowEngine {
         delete state.currentNode;
         delete state.currentAttemptId;
         delete state.currentNodeStartedAt;
-        delete state.currentNodeDeadlineAt;
+        delete state.currentNodeTimeoutMs;
+        delete state.currentNodeElapsedMs;
         delete state.currentSettingsScopeId;
         delete state.currentSettingsChangeNumber;
         delete state.currentSettingsHash;
@@ -795,7 +650,7 @@ export class WorkflowEngine {
         }
         const meta = { promptText: null };
         try {
-            const execution = await this.runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings, resumedAttempt?.deadlineAt);
+            const execution = await this.runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings, resumedAttempt?.timeoutMs, resumedAttempt?.elapsedMs);
             return {
                 result: this.createNodeResult(nodeId, node, attemptId, startedAt, "ok", execution.output),
                 execution,
@@ -845,7 +700,7 @@ export class WorkflowEngine {
             ...(output !== undefined ? { output } : {}),
         };
     }
-    async runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings, persistedDeadlineAt) {
+    async runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta, settings, persistedTimeoutMs, elapsedMs = 0) {
         const abort = new AbortController();
         const context = this.createNodeContext(state, abort.signal, settings);
         let timer;
@@ -862,43 +717,41 @@ export class WorkflowEngine {
             }
             let timeoutMs;
             let timeoutErrorMs;
-            if (persistedDeadlineAt === undefined) {
+            if (persistedTimeoutMs === undefined) {
                 timeoutMs = await this.resolveNodeTimeout(node, context, abort);
                 timeoutErrorMs = timeoutMs;
-                if (node.nodeType === "agent" && this.executor.preservesDeadlineWhileParked === true) {
-                    state.currentNodeDeadlineAt =
-                        timeoutMs === null ? null : new Date(Date.now() + timeoutMs).toISOString();
+                if (node.nodeType === "agent" && this.executor.preservesActiveTimeBudget === true) {
+                    state.currentNodeTimeoutMs = timeoutMs;
+                    state.currentNodeElapsedMs = 0;
                     await this.persist(runId, state, {
                         scope: "node",
-                        type: "node_deadline_set",
+                        type: "node_timeout_set",
                         nodeId,
                         attemptId,
-                        payload: { deadlineAt: state.currentNodeDeadlineAt },
+                        payload: { timeoutMs },
                     });
-                    if (state.currentNodeDeadlineAt !== null && timeoutErrorMs !== null) {
-                        timeoutMs = Date.parse(state.currentNodeDeadlineAt) - Date.now();
-                        if (timeoutMs <= 0)
-                            throw new TimeoutError(timeoutErrorMs);
-                    }
                 }
                 else {
-                    delete state.currentNodeDeadlineAt;
+                    delete state.currentNodeTimeoutMs;
+                    delete state.currentNodeElapsedMs;
                 }
             }
-            else if (persistedDeadlineAt === null) {
-                state.currentNodeDeadlineAt = null;
+            else if (persistedTimeoutMs === null) {
+                state.currentNodeTimeoutMs = null;
                 timeoutMs = null;
                 timeoutErrorMs = null;
             }
             else {
-                const deadline = Date.parse(persistedDeadlineAt);
-                const started = Date.parse(state.currentNodeStartedAt ?? persistedDeadlineAt);
-                if (!Number.isFinite(deadline) || !Number.isFinite(started)) {
-                    throw new Error("Persisted node deadline is invalid");
+                if (!Number.isFinite(persistedTimeoutMs) ||
+                    persistedTimeoutMs <= 0 ||
+                    !Number.isFinite(elapsedMs) ||
+                    elapsedMs < 0) {
+                    throw new Error("Persisted node timeout is invalid");
                 }
-                state.currentNodeDeadlineAt = persistedDeadlineAt;
-                timeoutMs = deadline - Date.now();
-                timeoutErrorMs = Math.max(1, deadline - started);
+                state.currentNodeTimeoutMs = persistedTimeoutMs;
+                state.currentNodeElapsedMs = elapsedMs;
+                timeoutMs = persistedTimeoutMs - elapsedMs;
+                timeoutErrorMs = persistedTimeoutMs;
                 if (timeoutMs <= 0)
                     throw new TimeoutError(timeoutErrorMs);
             }
@@ -1010,13 +863,42 @@ export class WorkflowEngine {
             }
             case "action":
                 return await this.runActionNode(node, context, nodeId, attemptId, signal, meta);
-            case "checkpoint":
-                return await runCheckpointNode(node, context, {
-                    store: this.store,
-                    workflowName: workflow.name,
-                    nodeId,
-                    attemptId,
-                });
+            case "checkpoint": {
+                const saved = await this.store.readCheckpoint(state.runId, attemptId);
+                if (saved !== undefined) {
+                    if (saved.request.status === "cancelled")
+                        throw new Error("Checkpoint request is cancelled");
+                    if (saved.request.status === "settled") {
+                        if (saved.humanDecision !== undefined)
+                            state.humanDecision = saved.humanDecision;
+                        return { output: saved.output, promptText: null };
+                    }
+                }
+                else {
+                    const request = await checkpointRequest(node, context, {
+                        workflowName: workflow.name,
+                        nodeId,
+                        attemptId,
+                    });
+                    const event = await this.store.commitTransition(state.runId, {
+                        kind: "waitForInput",
+                        ...request,
+                        event: {
+                            scope: "node",
+                            type: "checkpoint_requested",
+                            nodeId,
+                            attemptId,
+                            payload: { requestId: request.requestId, requestKind: request.requestKind },
+                        },
+                    });
+                    state.traceSeq = event.seq;
+                    state.updatedAt = event.at;
+                }
+                state.status = "waiting";
+                state.waitingOn = nodeId;
+                delete state.finishedAt;
+                throw new RunParkedError();
+            }
         }
     }
     async captureSettingsBinding(workflow, state, nodeId) {
@@ -1072,11 +954,12 @@ export class WorkflowEngine {
         return scope;
     }
     createNodeContext(state, signal, settings) {
+        const snapshot = deepFreezeJson(structuredClone(state));
         return {
-            input: state.input,
-            outputs: state.outputs,
-            results: state.results,
-            state,
+            input: snapshot.input,
+            outputs: snapshot.outputs,
+            results: snapshot.results,
+            state: snapshot,
             ...(settings !== undefined
                 ? {
                     settings: deepFreezeJson(structuredClone(settings.settings)),
@@ -1114,7 +997,17 @@ export class WorkflowEngine {
             // may already be terminal.
             throw abortError(signal);
         }
-        const prompt = appendStepContract(basePrompt, workflow.name, nodeId, attemptId, node.expectedOutput);
+        const contract = {
+            requestId: workflowRequestId(state.runId, attemptId),
+            runId: state.runId,
+            workflowName: workflow.name,
+            nodeId,
+            attemptId,
+            completion: assistant === undefined ? "submit" : "assistant",
+            ...(typeof node.expectedOutput === "string" ? { expectedOutput: node.expectedOutput } : {}),
+            ...(assistant?.maxChars !== undefined ? { maxOutputChars: assistant.maxChars } : {}),
+        };
+        const prompt = appendStepContract(basePrompt, contract);
         meta.promptText = prompt;
         await this.persist(runId, state, {
             scope: "agent",
@@ -1124,17 +1017,7 @@ export class WorkflowEngine {
             payload: { prompt, completion: assistant === undefined ? "submit" : "assistant" },
         });
         const submission = await this.executor.runAgentStep({
-            contract: {
-                runId: state.runId,
-                workflowName: workflow.name,
-                nodeId,
-                attemptId,
-                completion: assistant === undefined ? "submit" : "assistant",
-                ...(typeof node.expectedOutput === "string"
-                    ? { expectedOutput: node.expectedOutput }
-                    : {}),
-                ...(assistant?.maxChars !== undefined ? { maxOutputChars: assistant.maxChars } : {}),
-            },
+            contract,
             prompt,
             ...(state.runTitle !== undefined || node.statusDetail !== undefined
                 ? {
@@ -1251,7 +1134,9 @@ export class WorkflowEngine {
         }
     }
     async persist(runId, state, event) {
-        const traceEvent = await this.store.writeSnapshot(runId, state, event);
+        const traceEvent = await this.store.commitTransition(runId, executionTransition(state, event));
+        state.traceSeq = traceEvent.seq;
+        state.updatedAt = traceEvent.at;
         try {
             this.onEvent?.(traceEvent, state);
         }
@@ -1270,41 +1155,29 @@ export class WorkflowEngine {
         if (fields.error !== undefined) {
             state.error = fields.error;
         }
-        if (fields.waitingOn !== undefined) {
-            state.waitingOn = fields.waitingOn;
-        }
         if (fields.finalOutput !== undefined) {
             state.finalOutput = fields.finalOutput;
         }
         delete state.currentNode;
         delete state.currentAttemptId;
         delete state.currentNodeStartedAt;
-        delete state.currentNodeDeadlineAt;
+        delete state.currentNodeTimeoutMs;
+        delete state.currentNodeElapsedMs;
         delete state.currentSettingsScopeId;
         delete state.currentSettingsChangeNumber;
         delete state.currentSettingsHash;
-        // Let observers stop, drain, and prepare terminal delivery from the final
-        // in-memory state before the immutable terminal event is committed.
-        try {
-            await this.onRunFinishing?.(runId, state);
-        }
-        catch {
-            // Finishing the run wins over observer failures.
-        }
         await this.persist(runId, state, {
             scope: "run",
             type: `run_${status}`,
             payload: {
                 status,
                 ...(fields.error !== undefined ? { error: fields.error } : {}),
-                ...(fields.waitingOn !== undefined ? { waitingOn: fields.waitingOn } : {}),
                 ...(fields.finalOutput !== undefined ? { finalOutput: fields.finalOutput } : {}),
-                presentationRequired: status === "completed" && this.presentationRequired,
             },
         });
     }
 }
-async function runCheckpointNode(node, context, execution) {
+async function checkpointRequest(node, context, execution) {
     if (node.humanDecision !== undefined) {
         const prompt = await node.humanDecision.request(context);
         const audience = typeof node.humanDecision.audience === "function"
@@ -1322,11 +1195,18 @@ async function runCheckpointNode(node, context, execution) {
             prompt,
             ...(timeout !== undefined ? { timeout } : {}),
         });
-        await execution.store.createHumanDecisionRequest(request);
-        return { output: request, promptText: null };
+        return {
+            requestId: request.decisionId,
+            requestKind: "decision",
+            contract: request,
+        };
     }
     const output = node.run ? await node.run(context) : { summary: node.summary ?? "checkpoint" };
-    return { output, promptText: null };
+    return {
+        requestId: workflowRequestId(context.state.runId, execution.attemptId),
+        requestKind: "checkpoint",
+        contract: output,
+    };
 }
 function shellReceipt(result) {
     return {
@@ -1578,9 +1458,9 @@ function settingsDefinitionForNode(workflow, nodeId) {
  * The step contract appended to every agent-node prompt. This is the
  * documented standard for how the model completes a workflow step.
  */
-export function appendStepContract(prompt, workflowName, nodeId, attemptId, expectedOutput) {
-    const assistant = assistantMessageOutput(expectedOutput);
-    if (assistant !== undefined) {
+export function appendStepContract(prompt, contract) {
+    const { requestId, workflowName, nodeId, attemptId, expectedOutput } = contract;
+    if (contract.completion === "assistant") {
         return [
             prompt.trimEnd(),
             "",
@@ -1590,8 +1470,8 @@ export function appendStepContract(prompt, workflowName, nodeId, attemptId, expe
             "Reply with a normal assistant message.",
             "Do not call the workflow tool to complete this step.",
             "Your visible reply becomes the workflow step output after the turn settles.",
-            ...(assistant.maxChars !== undefined
-                ? [`Keep the visible reply within ${assistant.maxChars} characters.`]
+            ...(contract.maxOutputChars !== undefined
+                ? [`Keep the visible reply within ${contract.maxOutputChars} characters.`]
                 : []),
         ].join("\n");
     }
@@ -1602,9 +1482,9 @@ export function appendStepContract(prompt, workflowName, nodeId, attemptId, expe
         `Workflow step contract (workflow: ${workflowName}, step: ${nodeId}, attempt: ${attemptId})`,
         "",
         "While this step is active, you may publish non-completing updates with:",
-        `{"action": "update", "step": ${JSON.stringify(nodeId)}, "attempt": ${JSON.stringify(attemptId)}, "update": {"type": "...", "key": "...", "data": {...}}}`,
+        `{"action": "update", "requestId": ${JSON.stringify(requestId)}, "update": {"type": "...", "key": "...", "data": {...}}}`,
         "Complete this step by calling the `workflow` tool exactly once with:",
-        `{"action": "submit", "step": ${JSON.stringify(nodeId)}, "attempt": ${JSON.stringify(attemptId)}, "output": <your result>}`,
+        `{"action": "submit", "requestId": ${JSON.stringify(requestId)}, "output": <your result>}`,
         `Expected output: ${typeof expectedOutput === "string" ? expectedOutput : "a JSON object with your result"}`,
         "The step is complete only after the workflow tool accepts the output.",
         "If the tool reports a validation error, correct the output and call it again.",