@osolmaz/pi-workflows 0.12.0 → 0.13.0

package/src/workflows/engine.ts

@@ -1,6 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-import { resolveArtifacts } from "./artifacts.js";
 import {
   compileWorkflowDefinition,
   compositionMetadata,
@@ -29,12 +28,14 @@ import {
   WorkflowRunStore,
   createDefinitionSnapshot,
   createRunId,
-  readRunBundle,
 } from "./store.js";
 import type {
-  AcceptedHumanDecision,
+  ResolvedHumanDecision,
+  AgentExpectedOutput,
   AgentNodeDefinition,
   AgentStepExecutor,
+  AssistantMessageOutput,
+  AssistantMessageReceipt,
   ActionNodeDefinition,
   CheckpointNodeDefinition,
   ConversationRange,
@@ -71,6 +72,7 @@ type NodeExecution = {
   output: unknown;
   promptText: string | null;
   action?: WorkflowActionReceipt;
+  assistantMessage?: AssistantMessageReceipt;
   conversation?: ConversationRange;
 };
 
@@ -89,11 +91,17 @@ type NodeAttempt = {
   error?: unknown;
 };
 
+type ResumedNodeAttempt = {
+  nodeId: string;
+  attemptId: string;
+  startedAt: string;
+};
+
 /**
  * Executes a workflow graph step by step. Agent steps are delegated to the
  * configured executor; compute/action/checkpoint nodes run inline. Every
- * state transition is persisted to the run bundle before the engine moves on,
- * so a live viewer can follow along by watching the bundle directory.
+ * state transition is persisted to the SQLite run state before the engine moves on,
+ * so a live viewer can follow committed SQLite events.
  */
 export class WorkflowEngine {
   private readonly executor: AgentStepExecutor;
@@ -107,7 +115,7 @@ export class WorkflowEngine {
   private activeAbort: AbortController | null = null;
   private activeAttempt:
     | {
-        runDir: string;
+        runId: string;
         state: WorkflowRunState;
         nodeId: string;
         attemptId: string;
@@ -124,7 +132,7 @@ export class WorkflowEngine {
   constructor(options: WorkflowEngineOptions) {
     this.executor = options.executor;
     this.notificationSink = options.notificationSink;
-    this.store = options.store ?? new WorkflowRunStore(options.outputRoot);
+    this.store = options.store ?? new WorkflowRunStore(options.databasePath);
     this.defaultNodeTimeoutMs = options.defaultNodeTimeoutMs ?? DEFAULT_NODE_TIMEOUT_MS;
     this.maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
     this.onEvent = options.onEvent;
@@ -132,8 +140,8 @@ export class WorkflowEngine {
     this.onRunFinishing = options.onRunFinishing;
   }
 
-  get outputRoot(): string {
-    return this.store.outputRoot;
+  get databasePath(): string {
+    return this.store.databasePath;
   }
 
   /** Publish a durable update for the currently active attempt without completing it. */
@@ -171,7 +179,7 @@ export class WorkflowEngine {
       }
       limiter.take();
       const { event, record } = await this.store.publishUpdate(
-        active.runDir,
+        active.runId,
         active.state,
         active.nodeId,
         active.attemptId,
@@ -235,8 +243,7 @@ export class WorkflowEngine {
   ): Promise<WorkflowRunResult> {
     workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
     validateWorkflowDefinition(workflow);
-    // Fail before any bundle exists so bad input cannot leave a partial run
-    // on disk or silently change shape when state.json round-trips.
+    // 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;
     assertJsonSerializable(normalizedInput, "Workflow run input");
@@ -253,8 +260,8 @@ export class WorkflowEngine {
       options.workflowSource,
       options.runId,
     );
-    const runDir = await this.store.initializeRunBundle(workflow, state);
-    await this.persist(runDir, state, {
+    const runId = await this.store.initializeRun(workflow, state);
+    await this.persist(runId, state, {
       scope: "run",
       type: "run_started",
       payload: {
@@ -266,18 +273,18 @@ export class WorkflowEngine {
     // Awaited so anything the hook writes (e.g. a session binding and its
     // `session_bound` event) lands before node events and can never trail
     // the terminal event of a fast run.
-    await this.onRunStarted?.(runDir, state);
+    await this.onRunStarted?.(runId, state);
 
     try {
-      await this.executeGraph(workflow, state, runDir);
+      await this.executeGraph(workflow, state, runId);
     } catch (error) {
       if (isRunParkedError(error) || this.parked) {
-        return { runDir, state };
+        return { runId, state };
       }
-      await this.finishAfterError(runDir, state, error);
-      return { runDir, state };
+      await this.finishAfterError(runId, state, error);
+      return { runId, state };
     }
-    return { runDir, state };
+    return { runId, state };
   }
 
   /**
@@ -297,76 +304,94 @@ export class WorkflowEngine {
     this.cancelled = false;
     this.paused = false;
     this.parked = false;
-    const bundle = await this.store.prepareRunResume(runId);
-    const { runDir } = bundle;
-    const state = bundle.state;
+    const loaded = await this.store.prepareRunResume(runId);
+    const state = loaded.state;
     const sourceMismatch = workflowIdentityMismatch(state, workflow, options.workflowSource);
     if (sourceMismatch && options.force !== true) {
       throw new WorkflowSourceChangedError(runId);
     }
 
     const point = this.resumePointFor(workflow, state, "wait");
-    // A resumed run starts unpaused; the operator can pause again. The
-    // interrupted node's stale in-flight markers go away before the resume
-    // event so the projection matches what the engine is about to do.
+    const interruptedNode =
+      state.currentNode !== undefined ? workflow.nodes[state.currentNode] : undefined;
+    const resumedAttempt: ResumedNodeAttempt | undefined =
+      state.currentNode !== undefined &&
+      state.currentAttemptId !== undefined &&
+      state.currentNodeStartedAt !== undefined &&
+      interruptedNode?.nodeType === "agent" &&
+      assistantMessageConfig(interruptedNode) !== undefined
+        ? {
+            nodeId: state.currentNode,
+            attemptId: state.currentAttemptId,
+            startedAt: state.currentNodeStartedAt,
+          }
+        : undefined;
+    // A resumed run starts unpaused. Submitted and non-agent nodes discard
+    // stale in-flight markers and start a new attempt. Assistant-message
+    // nodes keep their attempt id so the origin session can adopt an already
+    // visible response without showing it twice.
     delete state.paused;
-    delete state.currentNode;
-    delete state.currentAttemptId;
-    delete state.currentNodeStartedAt;
-    delete state.statusDetail;
-    await this.persist(runDir, state, {
+    if (resumedAttempt === undefined) {
+      delete state.currentNode;
+      delete state.currentAttemptId;
+      delete state.currentNodeStartedAt;
+      delete state.statusDetail;
+    }
+    await this.persist(runId, state, {
       scope: "run",
       type: "run_resumed",
       payload: {
         ...(point.nodeId !== null ? { resumeAt: point.nodeId } : {}),
+        ...(resumedAttempt !== undefined ? { resumedAttemptId: resumedAttempt.attemptId } : {}),
         replayedSteps: state.steps.length,
         ...(sourceMismatch ? { workflowSourceMismatch: true, forced: true } : {}),
       },
     });
-    await this.onRunStarted?.(runDir, state);
+    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(runDir, state, "waiting", {
+        await this.finishRun(runId, state, "waiting", {
           waitingOn: point.waitingOn,
           finalOutput: point.lastOutput,
         });
       } else if (point.failedResult === undefined) {
-        await this.finishRun(runDir, state, "completed", { finalOutput: point.lastOutput });
+        await this.finishRun(runId, state, "completed", { finalOutput: point.lastOutput });
       } else {
         const timedOut = point.failedResult.outcome === "timed_out";
-        await this.finishRun(runDir, state, timedOut ? "timed_out" : "failed", {
+        await this.finishRun(runId, state, timedOut ? "timed_out" : "failed", {
           error: point.failedResult.error ?? `Workflow node failed: ${point.failedResult.nodeId}`,
         });
       }
-      return { runDir, state };
+      return { runId, state };
     }
 
     try {
       await this.executeGraph(
         workflow,
         state,
-        runDir,
+        runId,
         point.nodeId,
         countExecutableSteps(workflow, state.steps),
         point.lastOutput,
+        resumedAttempt,
       );
     } catch (error) {
       if (isRunParkedError(error) || this.parked) {
-        return { runDir, state };
+        return { runId, state };
       }
-      await this.finishAfterError(runDir, state, error);
-      return { runDir, state };
+      await this.finishAfterError(runId, state, error);
+      return { runId, state };
     }
-    return { runDir, state };
+    return { runId, state };
   }
 
   /**
    * Start a continuation run from a checkpointed parent. The new run gets a
-   * fresh bundle and trace, carries forward the parent's outputs, results,
+   * fresh run and event stream, carries forward the parent's outputs, results,
    * and step accounting, and continues routing after the checkpoint.
    */
   async continueRun(
@@ -377,7 +402,7 @@ export class WorkflowEngine {
       workflowSource?: WorkflowSource;
       runId?: string;
       force?: boolean;
-      humanDecision?: AcceptedHumanDecision;
+      humanDecision?: ResolvedHumanDecision;
     } = {},
   ): Promise<WorkflowRunResult> {
     workflow = isCompiledWorkflow(workflow) ? workflow : compileWorkflowDefinition(workflow);
@@ -385,7 +410,7 @@ export class WorkflowEngine {
     this.cancelled = false;
     this.paused = false;
     this.parked = false;
-    const parent = await readRunBundle(this.store.runDirFor(parentRunId));
+    const parent = this.store.readRun(parentRunId);
     if (parent === null) {
       throw new Error(`Cannot continue from unreadable workflow run: ${parentRunId}`);
     }
@@ -412,22 +437,21 @@ export class WorkflowEngine {
       }
       const request = parent.state.finalOutput as HumanDecisionRequest;
       if (
-        (request?.schema !== "pi-workflows.human-decision-request.v1" &&
-          request?.schema !== "pi-workflows.human-decision-request.v2") ||
+        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 new HumanDecisionStore(this.store.outputRoot).readAccepted(
-        request.decisionId,
-      );
+      const durableDecision = await new HumanDecisionStore(this.store.databasePath, {
+        state: this.store.state,
+      }).readResolved(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 = await resolveArtifacts(parent.state.input, parent.runDir);
+      normalizedInput = structuredClone(parent.state.input);
     } else {
       const suppliedInput = input === undefined ? null : input;
       normalizedInput = workflow.input ? await workflow.input(suppliedInput) : suppliedInput;
@@ -444,39 +468,26 @@ export class WorkflowEngine {
       options.runId,
     );
     state.parentRunId = parentRunId;
-    // Artifact references point into the parent's bundle, so carried values
-    // are fully resolved here and re-externalized into the new bundle.
-    state.outputs = (await resolveArtifacts(
-      parent.state.outputs,
-      parent.runDir,
-    )) as WorkflowRunState["outputs"];
-    state.results = (await resolveArtifacts(
-      parent.state.results,
-      parent.runDir,
-    )) as WorkflowRunState["results"];
-    state.steps = (await resolveArtifacts(
-      parent.state.steps,
-      parent.runDir,
-    )) as WorkflowRunState["steps"];
+    state.outputs = structuredClone(parent.state.outputs);
+    state.results = structuredClone(parent.state.results);
+    state.steps = structuredClone(parent.state.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 =
-        options.humanDecision.schema === "pi-workflows.human-decision-accepted.v2"
-          ? {
-              schema: "pi-workflows.human-decision-receipt.v2",
-              ...receipt,
-              subjectDigest: options.humanDecision.subjectDigest,
-              presentationDigest: options.humanDecision.presentationDigest,
-              revision: options.humanDecision.revision,
-            }
-          : { schema: "pi-workflows.human-decision-receipt.v1", ...receipt };
+      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) {
@@ -493,8 +504,8 @@ export class WorkflowEngine {
     }
     state.carriedStepCount = state.steps.length;
 
-    const runDir = await this.store.initializeRunBundle(workflow, state);
-    await this.persist(runDir, state, {
+    const runId = await this.store.initializeRun(workflow, state);
+    await this.persist(runId, state, {
       scope: "run",
       type: "run_started",
       payload: {
@@ -506,31 +517,31 @@ export class WorkflowEngine {
         carriedSteps: state.steps.length,
       },
     });
-    await this.onRunStarted?.(runDir, state);
+    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(runDir, state, "completed", { finalOutput: point.lastOutput });
-      return { runDir, state };
+      await this.finishRun(runId, state, "completed", { finalOutput: point.lastOutput });
+      return { runId, state };
     }
     try {
       await this.executeGraph(
         workflow,
         state,
-        runDir,
+        runId,
         point.nodeId,
         countExecutableSteps(workflow, state.steps),
         point.lastOutput,
       );
     } catch (error) {
       if (isRunParkedError(error) || this.parked) {
-        return { runDir, state };
+        return { runId, state };
       }
-      await this.finishAfterError(runDir, state, error);
-      return { runDir, state };
+      await this.finishAfterError(runId, state, error);
+      return { runId, state };
     }
-    return { runDir, state };
+    return { runId, state };
   }
 
   /**
@@ -586,17 +597,17 @@ export class WorkflowEngine {
   }
 
   private async finishAfterError(
-    runDir: string,
+    runId: string,
     state: WorkflowRunState,
     error: unknown,
   ): Promise<void> {
     const cancelled = this.cancelled || isAbortLikeError(error);
     try {
-      await this.finishRun(runDir, state, cancelled ? "cancelled" : "failed", {
+      await this.finishRun(runId, state, cancelled ? "cancelled" : "failed", {
         error: errorMessage(error),
       });
     } catch (finishError) {
-      // A fenced-out runner must not touch the bundle, including terminal
+      // A fenced-out runner must not touch run state, including terminal
       // projections. Propagate the claim loss instead of the node error.
       if (isClaimLostError(finishError)) {
         throw finishError;
@@ -664,10 +675,11 @@ export class WorkflowEngine {
   private async executeGraph(
     workflow: WorkflowDefinition,
     state: WorkflowRunState,
-    runDir: string,
+    runId: string,
     startNodeId: string | null = workflow.startAt,
     executedStepsBase = 0,
     initialLastOutput?: unknown,
+    resumedAttempt?: ResumedNodeAttempt,
   ): Promise<void> {
     const maxSteps = workflow.maxSteps ?? this.maxSteps;
     const composition = compositionMetadata(workflow);
@@ -676,7 +688,7 @@ export class WorkflowEngine {
     let lastOutput: unknown = initialLastOutput;
 
     while (currentNodeId !== null) {
-      await this.holdWhilePaused(state, runDir);
+      await this.holdWhilePaused(state, runId);
       const isTransition =
         composition?.entries[currentNodeId] !== undefined ||
         composition?.exits[currentNodeId] !== undefined;
@@ -695,7 +707,16 @@ export class WorkflowEngine {
         throw new Error(`Workflow node is missing: ${currentNodeId}`);
       }
 
-      const attempt = await this.executeNode(workflow, state, runDir, currentNodeId, node);
+      const activeResume = resumedAttempt?.nodeId === currentNodeId ? resumedAttempt : undefined;
+      resumedAttempt = undefined;
+      const attempt = await this.executeNode(
+        workflow,
+        state,
+        runId,
+        currentNodeId,
+        node,
+        activeResume,
+      );
       if (this.parked) {
         // Do not record the aborted attempt: the projection keeps the node
         // as in-flight, and resume reruns it with a fresh attempt.
@@ -704,7 +725,7 @@ export class WorkflowEngine {
       this.recordAttempt(workflow, state, attempt);
       // The terminal node event carries the output, receipt, and conversation
       // linkage so the trace alone is sufficient to reconstruct the run.
-      await this.persist(runDir, state, {
+      await this.persist(runId, state, {
         scope: "node",
         type: attempt.result.outcome === "ok" ? "node_finished" : "node_failed",
         nodeId: attempt.result.nodeId,
@@ -715,6 +736,9 @@ export class WorkflowEngine {
           ...(attempt.result.outcome === "ok" ? { output: attempt.result.output ?? null } : {}),
           ...(attempt.result.error !== undefined ? { error: attempt.result.error } : {}),
           ...(attempt.execution?.action !== undefined ? { action: attempt.execution.action } : {}),
+          ...(attempt.execution?.assistantMessage !== undefined
+            ? { assistantMessage: attempt.execution.assistantMessage }
+            : {}),
           ...(attempt.execution?.conversation !== undefined
             ? { conversation: attempt.execution.conversation }
             : {}),
@@ -729,7 +753,7 @@ export class WorkflowEngine {
       const entered = composition?.entries[attempt.result.nodeId];
       if (entered !== undefined) {
         const value = attempt.result.output as { invocation?: number } | undefined;
-        await this.persist(runDir, state, {
+        await this.persist(runId, state, {
           scope: "run",
           type: "include_entered",
           payload: {
@@ -742,7 +766,7 @@ export class WorkflowEngine {
       const exited = composition?.exits[attempt.result.nodeId];
       if (exited !== undefined) {
         const entrySteps = state.steps.filter((step) => step.nodeId === exited.mountPath);
-        await this.persist(runDir, state, {
+        await this.persist(runId, state, {
           scope: "run",
           type: "include_exited",
           payload: {
@@ -757,7 +781,7 @@ export class WorkflowEngine {
 
       lastOutput = attempt.result.output;
       if (node.nodeType === "checkpoint") {
-        await this.finishRun(runDir, state, "waiting", {
+        await this.finishRun(runId, state, "waiting", {
           waitingOn: attempt.result.nodeId,
           finalOutput: lastOutput,
         });
@@ -771,14 +795,14 @@ export class WorkflowEngine {
       );
     }
 
-    await this.finishRun(runDir, state, "completed", { finalOutput: lastOutput });
+    await this.finishRun(runId, state, "completed", { finalOutput: lastOutput });
   }
 
   /**
    * Hold the run at the step boundary while a pause is in effect. Pausing
    * never interrupts a node mid-flight; it only delays the next dispatch.
    */
-  private async holdWhilePaused(state: WorkflowRunState, runDir: string): Promise<void> {
+  private async holdWhilePaused(state: WorkflowRunState, runId: string): Promise<void> {
     if (this.parked) {
       throw new RunParkedError();
     }
@@ -789,7 +813,7 @@ export class WorkflowEngine {
       return;
     }
     state.paused = true;
-    await this.persist(runDir, state, { scope: "run", type: "run_paused", payload: {} });
+    await this.persist(runId, state, { scope: "run", type: "run_paused", payload: {} });
     while (this.paused && !this.cancelled && !this.parked) {
       await new Promise<void>((resolve) => {
         this.wakePause = resolve;
@@ -803,7 +827,7 @@ export class WorkflowEngine {
     if (this.cancelled) {
       throw new CancelledError();
     }
-    await this.persist(runDir, state, { scope: "run", type: "run_resumed", payload: {} });
+    await this.persist(runId, state, { scope: "run", type: "run_resumed", payload: {} });
   }
 
   private routeAfterFailure(
@@ -856,6 +880,9 @@ export class WorkflowEngine {
       output: attempt.result.output ?? null,
       ...(attempt.result.error !== undefined ? { error: attempt.result.error } : {}),
       ...(attempt.execution?.action !== undefined ? { action: attempt.execution.action } : {}),
+      ...(attempt.execution?.assistantMessage !== undefined
+        ? { assistantMessage: attempt.execution.assistantMessage }
+        : {}),
       ...(attempt.execution?.conversation !== undefined
         ? { conversation: attempt.execution.conversation }
         : {}),
@@ -870,32 +897,35 @@ export class WorkflowEngine {
   private async executeNode(
     workflow: WorkflowDefinition,
     state: WorkflowRunState,
-    runDir: string,
+    runId: string,
     nodeId: string,
     node: WorkflowNodeDefinition,
+    resumedAttempt?: ResumedNodeAttempt,
   ): Promise<NodeAttempt> {
-    const attemptId = randomUUID();
-    const startedAt = new Date().toISOString();
+    const attemptId = resumedAttempt?.attemptId ?? randomUUID();
+    const startedAt = resumedAttempt?.startedAt ?? new Date().toISOString();
     state.currentNode = nodeId;
     state.currentAttemptId = attemptId;
     state.currentNodeStartedAt = startedAt;
     if (node.statusDetail !== undefined) {
       state.statusDetail = node.statusDetail;
     }
-    await this.persist(runDir, state, {
-      scope: "node",
-      type: "node_started",
-      nodeId,
-      attemptId,
-      payload: { nodeType: node.nodeType },
-    });
+    if (resumedAttempt === undefined) {
+      await this.persist(runId, state, {
+        scope: "node",
+        type: "node_started",
+        nodeId,
+        attemptId,
+        payload: { nodeType: node.nodeType },
+      });
+    }
 
     const meta: NodeExecutionMeta = { promptText: null };
     try {
       const execution = await this.runNodeWithTimeout(
         workflow,
         state,
-        runDir,
+        runId,
         nodeId,
         attemptId,
         node,
@@ -958,7 +988,7 @@ export class WorkflowEngine {
   private async runNodeWithTimeout(
     workflow: WorkflowDefinition,
     state: WorkflowRunState,
-    runDir: string,
+    runId: string,
     nodeId: string,
     attemptId: string,
     node: WorkflowNodeDefinition,
@@ -988,11 +1018,11 @@ export class WorkflowEngine {
           abort.abort(new TimeoutError(timeoutMs));
         }, timeoutMs);
       }
-      this.activeAttempt = { runDir, state, nodeId, attemptId, signal: abort.signal };
+      this.activeAttempt = { runId, state, nodeId, attemptId, signal: abort.signal };
       const dispatched = this.dispatchNode(
         workflow,
         state,
-        runDir,
+        runId,
         nodeId,
         attemptId,
         node,
@@ -1009,7 +1039,7 @@ export class WorkflowEngine {
       const execution = await Promise.race([dispatched, abortRejection(abort.signal)]);
       if (execution.output === undefined) {
         // JSON cannot represent undefined; normalize so the in-memory state
-        // matches what the persisted bundle round-trips to.
+        // matches what persisted canonical JSON round-trips to.
         execution.output = null;
       }
       assertJsonSerializable(execution.output, `Node ${nodeId} output`);
@@ -1073,7 +1103,7 @@ export class WorkflowEngine {
   private async dispatchNode(
     workflow: WorkflowDefinition,
     state: WorkflowRunState,
-    runDir: string,
+    runId: string,
     nodeId: string,
     attemptId: string,
     node: WorkflowNodeDefinition,
@@ -1086,7 +1116,7 @@ export class WorkflowEngine {
         return await this.runAgentNode(
           workflow,
           state,
-          runDir,
+          runId,
           nodeId,
           attemptId,
           node,
@@ -1144,7 +1174,7 @@ export class WorkflowEngine {
   private async runAgentNode(
     workflow: WorkflowDefinition,
     state: WorkflowRunState,
-    runDir: string,
+    runId: string,
     nodeId: string,
     attemptId: string,
     node: AgentNodeDefinition,
@@ -1152,10 +1182,29 @@ export class WorkflowEngine {
     signal: AbortSignal,
     meta: NodeExecutionMeta,
   ): Promise<NodeExecution> {
+    const assistant = assistantMessageConfig(node);
+    if (assistant !== undefined) {
+      if (this.executor.assistantMessageMode === "park") {
+        state.statusDetail = "waiting for origin Pi session";
+        await this.persist(runId, state, {
+          scope: "agent",
+          type: "agent_session_required",
+          nodeId,
+          attemptId,
+          payload: { completion: "assistant" },
+        });
+        this.parked = true;
+        throw new RunParkedError();
+      }
+      if (this.executor.assistantMessageMode !== "visible") {
+        throw new Error("Assistant completion requires an origin Pi session");
+      }
+    }
+
     const basePrompt = await node.prompt(context);
     if (signal.aborted) {
       // The node timed out or the run was cancelled while the async prompt
-      // builder ran; a late continuation must not write into a bundle that
+      // builder ran; a late continuation must not write into a run that
       // may already be terminal.
       throw abortError(signal);
     }
@@ -1167,12 +1216,12 @@ export class WorkflowEngine {
       node.expectedOutput,
     );
     meta.promptText = prompt;
-    await this.persist(runDir, state, {
+    await this.persist(runId, state, {
       scope: "agent",
       type: "agent_prompt_sent",
       nodeId,
       attemptId,
-      payload: { prompt },
+      payload: { prompt, completion: assistant === undefined ? "submit" : "assistant" },
     });
 
     const submission = await this.executor.runAgentStep(
@@ -1182,7 +1231,11 @@ export class WorkflowEngine {
           workflowName: workflow.name,
           nodeId,
           attemptId,
-          ...(node.expectedOutput !== undefined ? { expectedOutput: node.expectedOutput } : {}),
+          completion: assistant === undefined ? "submit" : "assistant",
+          ...(typeof node.expectedOutput === "string"
+            ? { expectedOutput: node.expectedOutput }
+            : {}),
+          ...(assistant?.maxChars !== undefined ? { maxOutputChars: assistant.maxChars } : {}),
         },
         prompt,
         ...(state.runTitle !== undefined || node.statusDetail !== undefined
@@ -1202,6 +1255,9 @@ export class WorkflowEngine {
     return {
       output: submission.output,
       promptText: prompt,
+      ...(submission.assistantMessage !== undefined
+        ? { assistantMessage: submission.assistantMessage }
+        : {}),
       ...(submission.conversation !== undefined ? { conversation: submission.conversation } : {}),
     };
   }
@@ -1211,6 +1267,13 @@ export class WorkflowEngine {
     context: WorkflowNodeContext,
     output: unknown,
   ): Promise<{ ok: true; value: unknown } | { ok: false; error: string }> {
+    if (assistantMessageConfig(node) !== undefined) {
+      return {
+        ok: false,
+        error:
+          "This step completes with a normal assistant response. Do not submit workflow output.",
+      };
+    }
     try {
       const normalized = normalizeAgentOutput(output);
       const validated = node.validate ? await node.validate(normalized, context) : normalized;
@@ -1245,11 +1308,11 @@ export class WorkflowEngine {
   }
 
   private async persist(
-    runDir: string,
+    runId: string,
     state: WorkflowRunState,
     event: WorkflowTraceEventDraft,
   ): Promise<void> {
-    const traceEvent = await this.store.writeSnapshot(runDir, state, event);
+    const traceEvent = await this.store.writeSnapshot(runId, state, event);
     try {
       this.onEvent?.(traceEvent, state);
     } catch {
@@ -1259,7 +1322,7 @@ export class WorkflowEngine {
   }
 
   private async finishRun(
-    runDir: string,
+    runId: string,
     state: WorkflowRunState,
     status: WorkflowRunState["status"],
     fields: { error?: string; waitingOn?: string; finalOutput?: unknown },
@@ -1268,9 +1331,9 @@ export class WorkflowEngine {
       status = "timed_out";
     }
     // Let observers (e.g. the session recorder) stop and drain before the
-    // terminal event exists, so the bundle is immutable from that point on.
+    // terminal event exists, so the terminal fact is immutable from that point on.
     try {
-      await this.onRunFinishing?.(runDir, state);
+      await this.onRunFinishing?.(runId, state);
     } catch {
       // Finishing the run wins over observer failures.
     }
@@ -1288,7 +1351,7 @@ export class WorkflowEngine {
     delete state.currentNode;
     delete state.currentAttemptId;
     delete state.currentNodeStartedAt;
-    await this.persist(runDir, state, {
+    await this.persist(runId, state, {
       scope: "run",
       type: `run_${status}`,
       payload: {
@@ -1317,6 +1380,10 @@ async function runCheckpointNode(
       typeof node.humanDecision.audience === "function"
         ? await node.humanDecision.audience(context)
         : node.humanDecision.audience;
+    const timeout =
+      typeof node.humanDecision.onTimeout === "function"
+        ? await node.humanDecision.onTimeout(context)
+        : node.humanDecision.onTimeout;
     const request = createHumanDecisionRequest({
       runId: context.state.runId,
       workflowName: execution.workflowName,
@@ -1324,8 +1391,11 @@ async function runCheckpointNode(
       attemptId: execution.attemptId,
       contract: { audience, choices: node.humanDecision.choices },
       prompt,
+      ...(timeout !== undefined ? { timeout } : {}),
     });
-    await new HumanDecisionStore(execution.store.outputRoot).createRequest(request);
+    await new HumanDecisionStore(execution.store.databasePath, {
+      state: execution.store.state,
+    }).createRequest(request);
     return { output: request, promptText: null };
   }
   const output = node.run ? await node.run(context) : { summary: node.summary ?? "checkpoint" };
@@ -1456,7 +1526,7 @@ function assertInvocationStepLimit(
 }
 
 /**
- * Outputs are persisted to the run bundle, so they must be JSON-serializable.
+ * Outputs are persisted to the SQLite run state, so they must be JSON-serializable.
  * Failing here turns a bad callback return value into a normal node failure
  * instead of corrupting the run state.
  */
@@ -1525,6 +1595,18 @@ function normalizeAgentOutput(output: unknown): unknown {
   }
 }
 
+function assistantMessageOutput(
+  expectedOutput: AgentExpectedOutput | undefined,
+): AssistantMessageOutput | undefined {
+  return typeof expectedOutput === "object" && expectedOutput?.kind === "assistant-message"
+    ? expectedOutput
+    : undefined;
+}
+
+function assistantMessageConfig(node: AgentNodeDefinition): AssistantMessageOutput | undefined {
+  return assistantMessageOutput(node.expectedOutput);
+}
+
 /**
  * The step contract appended to every agent-node prompt. This is the
  * documented standard for how the model completes a workflow step.
@@ -1534,8 +1616,24 @@ export function appendStepContract(
   workflowName: string,
   nodeId: string,
   attemptId: string,
-  expectedOutput: string | undefined,
+  expectedOutput: AgentExpectedOutput | undefined,
 ): string {
+  const assistant = assistantMessageOutput(expectedOutput);
+  if (assistant !== undefined) {
+    return [
+      prompt.trimEnd(),
+      "",
+      "---",
+      `Workflow step contract (workflow: ${workflowName}, step: ${nodeId}, attempt: ${attemptId})`,
+      "",
+      "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.`]
+        : []),
+    ].join("\n");
+  }
   return [
     prompt.trimEnd(),
     "",
@@ -1546,7 +1644,7 @@ export function appendStepContract(
     `{"action": "update", "step": ${JSON.stringify(nodeId)}, "attempt": ${JSON.stringify(attemptId)}, "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>}`,
-    `Expected output: ${expectedOutput ?? "a JSON object with 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.",
   ].join("\n");