@osolmaz/pi-workflows 0.12.1 → 0.13.0

package/dist/workflows/engine.js

@@ -1,13 +1,12 @@
 import { createHash, randomUUID } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
-import { resolveArtifacts } from "./artifacts.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 { HumanDecisionStore, createHumanDecisionRequest, validateHumanDecisionResponse, } from "./human-decision.js";
 import { extractJsonValue } from "./json.js";
 import { runShellAction, shellResultFromError } from "./shell.js";
-import { RUN_STATE_SCHEMA, WorkflowRunStore, createDefinitionSnapshot, createRunId, readRunBundle, } from "./store.js";
+import { RUN_STATE_SCHEMA, WorkflowRunStore, createDefinitionSnapshot, createRunId, } from "./store.js";
 import { UpdateRateLimiter, updateReceipt, validateWorkflowUpdate } from "./updates.js";
 const DEFAULT_NODE_TIMEOUT_MS = 15 * 60_000;
 const DEFAULT_MAX_STEPS = 100;
@@ -18,8 +17,8 @@ const ABORT_CLEANUP_GRACE_MS = 2_000;
 /**
  * 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 {
     executor;
@@ -41,15 +40,15 @@ export class WorkflowEngine {
     constructor(options) {
         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;
         this.onRunStarted = options.onRunStarted;
         this.onRunFinishing = options.onRunFinishing;
     }
-    get outputRoot() {
-        return this.store.outputRoot;
+    get databasePath() {
+        return this.store.databasePath;
     }
     /** Publish a durable update for the currently active attempt without completing it. */
     async publishUpdate(step, attempt, input, idempotencyKey) {
@@ -76,7 +75,7 @@ export class WorkflowEngine {
                 this.updateLimiters.set(active.state.runId, limiter);
             }
             limiter.take();
-            const { event, record } = await this.store.publishUpdate(active.runDir, active.state, active.nodeId, active.attemptId, update, { signal: active.signal });
+            const { event, record } = await this.store.publishUpdate(active.runId, active.state, active.nodeId, active.attemptId, update, { signal: active.signal });
             try {
                 this.onEvent?.(event, active.state);
             }
@@ -126,8 +125,7 @@ export class WorkflowEngine {
     async run(workflow, input, options = {}) {
         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");
@@ -138,8 +136,8 @@ export class WorkflowEngine {
         this.paused = false;
         this.parked = false;
         const state = await this.createRunState(workflow, normalizedInput, 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: {
@@ -151,18 +149,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 };
     }
     /**
      * Resume an interrupted run at the node it stopped on. The caller must
@@ -177,68 +175,83 @@ 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 = 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, point.nodeId, countExecutableSteps(workflow, state.steps), point.lastOutput);
+            await this.executeGraph(workflow, state, 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(workflow, parentRunId, input, options = {}) {
@@ -247,7 +260,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}`);
         }
@@ -274,13 +287,15 @@ export class WorkflowEngine {
                 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).readResolved(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;
@@ -292,11 +307,9 @@ export class WorkflowEngine {
         }
         const state = await this.createRunState(workflow, normalizedInput, options.workflowSource, 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));
-        state.results = (await resolveArtifacts(parent.state.results, parent.runDir));
-        state.steps = (await resolveArtifacts(parent.state.steps, parent.runDir));
+        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,
@@ -329,8 +342,8 @@ export class WorkflowEngine {
             state.steps[stepIndex] = { ...priorStep, output: acceptedResponse };
         }
         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: {
@@ -342,24 +355,24 @@ 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, point.nodeId, countExecutableSteps(workflow, state.steps), point.lastOutput);
+            await this.executeGraph(workflow, state, 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 };
     }
     /**
      * Find where a resumed run continues. An in-flight node reruns; otherwise
@@ -401,15 +414,15 @@ export class WorkflowEngine {
         const next = resolveNextForOutcome(workflow.edges, lastStep.nodeId, result);
         return next === null ? { nodeId: null, failedResult: result } : { nodeId: next };
     }
-    async finishAfterError(runDir, state, error) {
+    async finishAfterError(runId, state, error) {
         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;
@@ -461,14 +474,14 @@ export class WorkflowEngine {
             updates: [],
         };
     }
-    async executeGraph(workflow, state, runDir, startNodeId = workflow.startAt, executedStepsBase = 0, initialLastOutput) {
+    async executeGraph(workflow, state, runId, startNodeId = workflow.startAt, executedStepsBase = 0, initialLastOutput, resumedAttempt) {
         const maxSteps = workflow.maxSteps ?? this.maxSteps;
         const composition = compositionMetadata(workflow);
         let currentNodeId = startNodeId;
         let executedSteps = executedStepsBase;
         let lastOutput = initialLastOutput;
         while (currentNodeId !== null) {
-            await this.holdWhilePaused(state, runDir);
+            await this.holdWhilePaused(state, runId);
             const isTransition = composition?.entries[currentNodeId] !== undefined ||
                 composition?.exits[currentNodeId] !== undefined;
             if (!isTransition) {
@@ -482,7 +495,9 @@ export class WorkflowEngine {
             if (!node) {
                 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.
@@ -491,7 +506,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,
@@ -502,6 +517,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 }
                         : {}),
@@ -514,7 +532,7 @@ export class WorkflowEngine {
             const entered = composition?.entries[attempt.result.nodeId];
             if (entered !== undefined) {
                 const value = attempt.result.output;
-                await this.persist(runDir, state, {
+                await this.persist(runId, state, {
                     scope: "run",
                     type: "include_entered",
                     payload: {
@@ -527,7 +545,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: {
@@ -541,7 +559,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,
                 });
@@ -549,13 +567,13 @@ export class WorkflowEngine {
             }
             currentNodeId = resolveNext(workflow.edges, attempt.result.nodeId, attempt.result.output, attempt.result);
         }
-        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.
      */
-    async holdWhilePaused(state, runDir) {
+    async holdWhilePaused(state, runId) {
         if (this.parked) {
             throw new RunParkedError();
         }
@@ -566,7 +584,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((resolve) => {
                 this.wakePause = resolve;
@@ -580,7 +598,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: {} });
     }
     routeAfterFailure(workflow, state, attempt) {
         if (attempt.result.outcome === "cancelled" || this.cancelled) {
@@ -624,6 +642,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 }
                 : {}),
@@ -634,25 +655,27 @@ export class WorkflowEngine {
         delete state.currentNodeStartedAt;
         delete state.statusDetail;
     }
-    async executeNode(workflow, state, runDir, nodeId, node) {
-        const attemptId = randomUUID();
-        const startedAt = new Date().toISOString();
+    async executeNode(workflow, state, runId, nodeId, node, resumedAttempt) {
+        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 = { promptText: null };
         try {
-            const execution = await this.runNodeWithTimeout(workflow, state, runDir, nodeId, attemptId, node, meta);
+            const execution = await this.runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta);
             return {
                 result: this.createNodeResult(nodeId, node, attemptId, startedAt, "ok", execution.output),
                 execution,
@@ -698,7 +721,7 @@ export class WorkflowEngine {
             ...(output !== undefined ? { output } : {}),
         };
     }
-    async runNodeWithTimeout(workflow, state, runDir, nodeId, attemptId, node, meta) {
+    async runNodeWithTimeout(workflow, state, runId, nodeId, attemptId, node, meta) {
         const abort = new AbortController();
         const context = this.createNodeContext(state, abort.signal);
         let timer;
@@ -722,15 +745,15 @@ export class WorkflowEngine {
                     abort.abort(new TimeoutError(timeoutMs));
                 }, timeoutMs);
             }
-            this.activeAttempt = { runDir, state, nodeId, attemptId, signal: abort.signal };
-            const dispatched = this.dispatchNode(workflow, state, runDir, nodeId, attemptId, node, context, abort.signal, meta);
+            this.activeAttempt = { runId, state, nodeId, attemptId, signal: abort.signal };
+            const dispatched = this.dispatchNode(workflow, state, runId, nodeId, attemptId, node, context, abort.signal, meta);
             dispatchSettled = dispatched.then(() => undefined, () => undefined);
             // Race the dispatch against the abort signal so timeouts and cancel
             // take effect even for node callbacks that never observe the signal.
             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`);
@@ -787,10 +810,10 @@ export class WorkflowEngine {
             clearTimeout(timer);
         }
     }
-    async dispatchNode(workflow, state, runDir, nodeId, attemptId, node, context, signal, meta) {
+    async dispatchNode(workflow, state, runId, nodeId, attemptId, node, context, signal, meta) {
         switch (node.nodeType) {
             case "agent":
-                return await this.runAgentNode(workflow, state, runDir, nodeId, attemptId, node, context, signal, meta);
+                return await this.runAgentNode(workflow, state, runId, nodeId, attemptId, node, context, signal, meta);
             case "compute":
                 return { output: await node.run(context), promptText: null };
             case "notify": {
@@ -833,22 +856,40 @@ export class WorkflowEngine {
             signal,
         };
     }
-    async runAgentNode(workflow, state, runDir, nodeId, attemptId, node, context, signal, meta) {
+    async runAgentNode(workflow, state, runId, nodeId, attemptId, node, context, signal, meta) {
+        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);
         }
         const prompt = appendStepContract(basePrompt, workflow.name, nodeId, attemptId, 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({
             contract: {
@@ -856,7 +897,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
@@ -873,10 +918,19 @@ export class WorkflowEngine {
         return {
             output: submission.output,
             promptText: prompt,
+            ...(submission.assistantMessage !== undefined
+                ? { assistantMessage: submission.assistantMessage }
+                : {}),
             ...(submission.conversation !== undefined ? { conversation: submission.conversation } : {}),
         };
     }
     async acceptSubmission(node, context, output) {
+        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;
@@ -902,8 +956,8 @@ export class WorkflowEngine {
         const output = await node.run(actionContext);
         return { output, promptText: null, action: { actionType: "function" } };
     }
-    async persist(runDir, state, event) {
-        const traceEvent = await this.store.writeSnapshot(runDir, state, event);
+    async persist(runId, state, event) {
+        const traceEvent = await this.store.writeSnapshot(runId, state, event);
         try {
             this.onEvent?.(traceEvent, state);
         }
@@ -912,14 +966,14 @@ export class WorkflowEngine {
             // correctness; a throwing observer would otherwise fail the run.
         }
     }
-    async finishRun(runDir, state, status, fields) {
+    async finishRun(runId, state, status, fields) {
         if (status === "failed" && state.status === "timed_out") {
             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.
@@ -938,7 +992,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: {
@@ -968,7 +1022,9 @@ async function runCheckpointNode(node, context, execution) {
             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" };
@@ -1072,7 +1128,7 @@ function assertInvocationStepLimit(metadata, nodeId, steps) {
     }
 }
 /**
- * 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.
  */
@@ -1130,11 +1186,35 @@ function normalizeAgentOutput(output) {
         return output;
     }
 }
+function assistantMessageOutput(expectedOutput) {
+    return typeof expectedOutput === "object" && expectedOutput?.kind === "assistant-message"
+        ? expectedOutput
+        : undefined;
+}
+function assistantMessageConfig(node) {
+    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.
  */
 export function appendStepContract(prompt, workflowName, nodeId, attemptId, expectedOutput) {
+    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(),
         "",
@@ -1145,7 +1225,7 @@ export function appendStepContract(prompt, workflowName, nodeId, attemptId, expe
         `{"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");