@osolmaz/pi-workflows 0.16.4 → 0.16.6

package/src/workflows/engine.ts

@@ -18,8 +18,9 @@ import {
   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,
@@ -33,11 +34,12 @@ import {
   createRunId,
   type WorkflowExecutionStore,
 } from "./store.js";
+import { executionTransition } from "./transitions.js";
 import type {
-  ResolvedHumanDecision,
   AgentExpectedOutput,
   AgentNodeDefinition,
   AgentStepExecutor,
+  AgentStepContract,
   AssistantMessageOutput,
   AssistantMessageReceipt,
   ActionNodeDefinition,
@@ -54,7 +56,6 @@ import type {
   WorkflowNodeOutcome,
   WorkflowNodeResult,
   WorkflowNotificationSink,
-  HumanDecisionRequest,
   WorkflowRunResult,
   WorkflowRunState,
   WorkflowSource,
@@ -63,7 +64,12 @@ import type {
   WorkflowUpdateInput,
   WorkflowUpdateReceipt,
 } from "./types.js";
-import { UpdateRateLimiter, updateReceipt, validateWorkflowUpdate } from "./updates.js";
+import {
+  UpdateRateLimiter,
+  updateProjection,
+  updateReceipt,
+  validateWorkflowUpdate,
+} from "./updates.js";
 
 const DEFAULT_NODE_TIMEOUT_MS = 15 * 60_000;
 const DEFAULT_MAX_STEPS = 100;
@@ -101,7 +107,8 @@ type ResumedNodeAttempt = {
   nodeId: string;
   attemptId: string;
   startedAt: string;
-  deadlineAt?: string | null;
+  timeoutMs?: number | null;
+  elapsedMs?: number;
   settings?: WorkflowSettingsScopeRecord;
 };
 
@@ -119,7 +126,6 @@ export class WorkflowEngine {
   private readonly maxSteps: number;
   private readonly onEvent?: WorkflowEngineOptions["onEvent"];
   private readonly onRunStarted?: WorkflowEngineOptions["onRunStarted"];
-  private readonly onRunFinishing?: WorkflowEngineOptions["onRunFinishing"];
   private activeAbort: AbortController | null = null;
   private activeAttempt:
     | {
@@ -136,7 +142,6 @@ export class WorkflowEngine {
   private cancelled = false;
   private parked = false;
   private paused = false;
-  private presentationRequired = false;
   private wakePause: (() => void) | null = null;
 
   constructor(options: WorkflowEngineOptions) {
@@ -147,7 +152,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(): string {
@@ -190,12 +194,14 @@ export class WorkflowEngine {
       limiter.take();
       const { event, record } = await this.store.publishUpdate(
         active.runId,
-        active.state,
         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);
       } catch {
@@ -257,7 +263,6 @@ export class WorkflowEngine {
   ): Promise<WorkflowRunResult> {
     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;
@@ -330,19 +335,20 @@ export class WorkflowEngine {
   ): Promise<WorkflowRunResult> {
     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 state = await this.store.prepareRunResume(runId);
 
-    const point = this.resumePointFor(workflow, state, "wait");
+    const point = this.resumePointFor(workflow, state);
     const interruptedNode =
       state.currentNode !== undefined ? workflow.nodes[state.currentNode] : undefined;
     let resumedAttempt: ResumedNodeAttempt | undefined;
@@ -350,18 +356,19 @@ export class WorkflowEngine {
       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 } : {}),
       };
     }
@@ -374,7 +381,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;
@@ -393,15 +401,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 {
         const timedOut = point.failedResult.outcome === "timed_out";
@@ -433,161 +434,6 @@ 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: WorkflowDefinition,
-    parentRunId: string,
-    input: unknown,
-    options: {
-      workflowSource?: WorkflowSource;
-      runId?: string;
-      force?: boolean;
-      humanDecision?: ResolvedHumanDecision;
-    } = {},
-  ): Promise<WorkflowRunResult> {
-    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: unknown;
-    let acceptedNodeId: string | undefined;
-    let normalizedInput: unknown;
-    if (humanContract !== undefined) {
-      if (options.humanDecision === undefined) {
-        throw new Error(`Checkpoint ${waitingNodeId} requires an accepted verified human decision`);
-      }
-      const request = parentState.finalOutput as HumanDecisionRequest;
-      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
@@ -596,12 +442,10 @@ export class WorkflowEngine {
   private resumePointFor(
     workflow: WorkflowDefinition,
     state: WorkflowRunState,
-    checkpointBehavior: "wait" | "continue",
   ): {
     nodeId: string | null;
     lastOutput?: unknown;
     failedResult?: WorkflowNodeResult;
-    waitingOn?: string;
   } {
     if (state.currentNode !== undefined) {
       if (workflow.nodes[state.currentNode] === undefined) {
@@ -618,19 +462,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 }
@@ -833,6 +664,7 @@ export class WorkflowEngine {
             scopeId: latest.scopeId,
             previousChangeNumber: attempt.settings.changeNumber,
             changeNumber: latest.changeNumber,
+            settingsHash: latest.settingsHash,
           },
         });
         resumedAttempt = {
@@ -881,13 +713,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,
@@ -999,7 +824,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;
@@ -1063,7 +889,8 @@ export class WorkflowEngine {
         node,
         meta,
         settings,
-        resumedAttempt?.deadlineAt,
+        resumedAttempt?.timeoutMs,
+        resumedAttempt?.elapsedMs,
       );
       return {
         result: this.createNodeResult(nodeId, node, attemptId, startedAt, "ok", execution.output),
@@ -1131,7 +958,8 @@ export class WorkflowEngine {
     node: WorkflowNodeDefinition,
     meta: NodeExecutionMeta,
     settings?: WorkflowSettingsScopeRecord,
-    persistedDeadlineAt?: string | null,
+    persistedTimeoutMs?: number | null,
+    elapsedMs = 0,
   ): Promise<NodeExecution> {
     const abort = new AbortController();
     const context = this.createNodeContext(state, abort.signal, settings);
@@ -1150,39 +978,40 @@ export class WorkflowEngine {
 
       let timeoutMs: number | null;
       let timeoutErrorMs: number | null;
-      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);
       }
       if (abort.signal.aborted) {
@@ -1333,13 +1162,40 @@ 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();
+      }
     }
   }
 
@@ -1414,11 +1270,12 @@ export class WorkflowEngine {
     signal: AbortSignal,
     settings?: WorkflowSettingsScopeRecord,
   ): WorkflowNodeContext {
+    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)),
@@ -1468,13 +1325,17 @@ export class WorkflowEngine {
       // may already be terminal.
       throw abortError(signal);
     }
-    const prompt = appendStepContract(
-      basePrompt,
-      workflow.name,
+    const contract: AgentStepContract = {
+      requestId: workflowRequestId(state.runId, attemptId),
+      runId: state.runId,
+      workflowName: workflow.name,
       nodeId,
       attemptId,
-      node.expectedOutput,
-    );
+      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",
@@ -1486,17 +1347,7 @@ export class WorkflowEngine {
 
     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
           ? {
@@ -1632,7 +1483,9 @@ export class WorkflowEngine {
     state: WorkflowRunState,
     event: WorkflowTraceEventDraft,
   ): Promise<void> {
-    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);
     } catch {
@@ -1645,8 +1498,8 @@ export class WorkflowEngine {
   private async finishRun(
     runId: string,
     state: WorkflowRunState,
-    status: WorkflowRunState["status"],
-    fields: { error?: string; waitingOn?: string; finalOutput?: unknown },
+    status: "completed" | "failed" | "timed_out" | "cancelled",
+    fields: { error?: string; finalOutput?: unknown },
   ): Promise<void> {
     if (status === "failed" && state.status === "timed_out") {
       status = "timed_out";
@@ -1656,50 +1509,38 @@ 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(
+async function checkpointRequest(
   node: CheckpointNodeDefinition,
   context: WorkflowNodeContext,
   execution: {
-    store: WorkflowExecutionStore;
     workflowName: string;
     nodeId: string;
     attemptId: string;
   },
-): Promise<NodeExecution> {
+): Promise<{ requestId: string; requestKind: "checkpoint" | "decision"; contract: JsonValue }> {
   if (node.humanDecision !== undefined) {
     const prompt = await node.humanDecision.request(context);
     const audience =
@@ -1719,11 +1560,18 @@ async function runCheckpointNode(
       prompt,
       ...(timeout !== undefined ? { timeout } : {}),
     });
-    await execution.store.createHumanDecisionRequest(request);
-    return { output: request, promptText: null };
+    return {
+      requestId: request.decisionId,
+      requestKind: "decision",
+      contract: request as unknown as JsonValue,
+    };
   }
   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 as JsonValue,
+  };
 }
 
 function shellReceipt(result: ShellActionResult): WorkflowActionReceipt {
@@ -2040,15 +1888,9 @@ function settingsDefinitionForNode(
  * 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: string,
-  workflowName: string,
-  nodeId: string,
-  attemptId: string,
-  expectedOutput: AgentExpectedOutput | undefined,
-): string {
-  const assistant = assistantMessageOutput(expectedOutput);
-  if (assistant !== undefined) {
+export function appendStepContract(prompt: string, contract: AgentStepContract): string {
+  const { requestId, workflowName, nodeId, attemptId, expectedOutput } = contract;
+  if (contract.completion === "assistant") {
     return [
       prompt.trimEnd(),
       "",
@@ -2058,8 +1900,8 @@ export function appendStepContract(
       "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");
   }
@@ -2070,9 +1912,9 @@ export function appendStepContract(
     `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.",