@bastani/atomic 0.9.13 → 0.9.14-alpha.2

package/dist/builtin/workflows/src/extension/workflow-prompts.ts

@@ -3,6 +3,7 @@ export const WORKFLOW_TOOL_DESCRIPTION =
 	"when workflow execution fits but another shape would better achieve the task, author a custom TypeScript workflow({...}) inline with normal coding tools, reload it, and run it; after successfully creating and reloading a newly authored custom workflow, report the folder containing its generated code as 'Custom workflow created. You can inspect its code at: <workflow-folder-path>'; do this only for newly created custom workflows, never builtin or pre-existing workflows; " +
 	"discover with list/get/inputs/models, list session runs with status (no runId; statusFilter narrows the list), inspect status/stages/stage details, " +
 	"send prompt answers or steering only while the root workflow is nonterminal, pause/resume/interrupt/quit runs, and reload workflow resources. " +
+	"For primitive prompt answers, use booleans or the documented confirm labels, exact case-insensitive select labels or 1-based indexes, and text strings for input/editor; an invalid answer remains pending and returns guidance instead of choosing a default. " +
 	"For large stage handoffs, write context to files/artifacts, pass paths via reads, and prompt downstream agents to 'Read the file at <path>...' instead of injecting large previous text. " +
 	"Wrap critical parts of run inputs and steering messages in <keepContext>...</keepContext> so compaction preserves them verbatim in the stages that inherit them; tag role constraints, prohibitions, must-hold criteria, and identifiers, not background or bulk reference material. " +
 	"For transcripts, prefer status/stages/stage to get sessionFile/transcriptPath, " +
@@ -50,6 +51,8 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
 	`**Workflow authoring and handoffs**:
   - When a user asks to create or edit a workflow, clarify only unresolved requirements that materially affect its purpose, inputs, stages, handoffs, validation, success criteria, or starter pattern. Read the workflow docs/examples, implement the TypeScript definition with normal coding tools, reload it, and run representative test inputs before presenting it. Use the create-spec skill when it adds value; it is not mandatory when context is already sufficient.
   - After creating and reloading a newly authored custom workflow, close the loop by stating the folder containing the workflow file just written, for example \`.atomic/workflows/\`, in this shape: \`Custom workflow created. You can inspect its code at: <workflow-folder-path>\`. Do this only for newly created custom workflows, never builtin or pre-existing workflows.
+  - Keep a small, readable workflow in one entry file. Do not split short one-use prompts, create one file per stage, add wrapper-only modules, hide the graph across files, or use line counts alone as a module boundary.
+  - When a meaningful source boundary improves clarity, reuse, ownership, or testability, keep the graph and control flow in the top-level workflow entry file and extract cohesive concerns such as long or reused prompt builders, shared TypeBox schemas and workflow-specific types, model-policy constants shared by several stages, deterministic helpers with their own testable behavior, or reusable child workflow definitions into a subdirectory below the top-level discovery directory — either one owned by a single workflow or a shared support directory. Project and user discovery scans only top-level \`.ts\`/\`.js\`/\`.mjs\`/\`.cjs\` files in the workflow directory, so those support modules are not scanned as extra top-level workflow candidates; use \`.js\` import extensions from TypeScript source.
   - When creating or editing a workflow that pins an explicit stage \`model\` or \`fallbackModels\`, consult \`packages/coding-agent/docs/models/model-selection.md\` for role-based recommendations, treating benchmark thinking levels as measurement configurations rather than universal workflow defaults, then call \`workflow({ action: "models" })\` to see the models actually present in the user's configured catalog. Use only the catalog's returned \`fullId\` values as model strings, and append a thinking suffix only when that exact level appears in the entry's \`availableThinkingLevels\`; apply the stage role and failure-cost policy independently to the primary and every fallback; treat an absent or empty \`availableThinkingLevels\` as no suffix support rather than inferring one. If a guide-recommended model for the role is unavailable, try another guide-recommended model that is present in the catalog. If the selected model does not support the role's level, choose another catalog model that does or leave the stage unpinned rather than inventing or silently promoting a level. An explicit user request for a level overrides the role default, but never fabricate an unsupported catalog level. If no recommendation intersects with the catalog, leave the stage unpinned rather than inventing a substitute, and mention the limitation, asking the user only if the workflow requires an explicit model choice. If the catalog is empty, continue with unpinned stages, state that no configured models were returned, and do not fabricate model IDs. Do not inspect or infer credentials, environment variables, auth files, token validity, entitlements, or the reason a model is absent; \`isCurrent\` marks the active selection, not a quality recommendation.
   - Consult docs/workflows.md and its starter patterns (Classify-and-act, Fan-out-and-synthesize, Adversarial verification, Generate-and-filter, Tournament, Loop until done, and Stacked implementation slices) when designing a stage graph.
   - Treat workflow composition as a first-class authoring option. Before duplicating stages, inspect reusable workflow modules and builtin exports; import their definitions and invoke them with \`ctx.workflow(...)\`, mapping typed inputs and consuming only declared outputs. Nested workflows can themselves import children, so combine small reusable graphs into a richer parent while respecting \`maxDepth\`.
@@ -61,7 +64,7 @@ export const DEFAULT_PROMPT_GUIDANCE: string[] = [
   - Bounded loops must create distinct tracked work for every iteration; never reopen an ancestor below its downstream work. Stacked implementation slices are unrolled, not looped: each slice gets a fresh child boundary and distinct tracked nodes, and no slice may add an edge back to the current frontier, itself, or an ancestor. If a retained session receives follow-up without new dependency work, keep it as non-topological activity metadata rather than adding a back-edge. Before launch, sketch nodes and dependencies for every branch and loop and reject any proposed parent edge to the node itself or an ancestor.
   - Treat dynamic graph validation during execution, replay, and DBOS hydration as the authoritative cycle boundary. If runtime topology code changes, require incremental edge checks and DBOS hydration validation; prompt guidance and TypeScript types cannot replace those runtime checks.
   - Every workflow invocation automatically receives one stable, non-default Intercom group. Intercom-capable stages inherit it, nested workflows keep the top-level invocation group, and subagents inherit their launching stage's group. Do not mint or thread group names through ordinary workflow definitions. Use an explicit \`group\` only for an intentional override: a named group or \`group: true\` creates a subgroup, while \`group: "default"\` opts into the shared default group. Stages without Intercom access receive no group, and \`contact_supervisor\` still crosses group boundaries for authorized escalation.
-  - Prefer \`ctx.tool(name, args, fn)\` for workflow-owned TypeScript operations with side effects, such as filesystem writes, network mutations, and external API actions. It creates a tracked, non-attachable durable graph node before invoking \`fn\`; it may be used before, between, after, or without model stages. A completed \`ctx.tool\` call is durably checkpointed with its serializable result, so resume replays that result without rerunning \`fn\`. For checks that may fail during a bounded repair loop, opt into \`failureMode: "return"\`, branch on the typed outcome, and pass only the needed error fields to the repair stage or artifact yourself; Atomic does not inject failure evidence into later prompts. Cancellation and storage faults still throw. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately; this rule applies to side effects orchestrated directly by the workflow definition.
+  - Prefer \`ctx.tool(name, args, fn)\` for workflow-owned TypeScript operations with side effects, such as filesystem writes, network mutations, and external API actions. It creates a tracked, non-attachable durable graph node before invoking \`fn\`; it may be used before, between, after, or without model stages. A completed \`ctx.tool\` call is durably checkpointed with its serializable result, so resume replays that result without rerunning \`fn\`. For checks that may fail during a bounded repair loop, opt into \`failureMode: "return"\`, branch on the typed outcome, and pass only the needed error fields to the repair stage or artifact yourself; Atomic does not inject failure evidence into later prompts. Retries do not bound a hung callback, so every \`ctx.tool\` callback that starts a child process or performs network I/O MUST set an explicit positive finite \`timeoutMs\` and forward the supplied \`signal\` to cancellable work. A timeout applies per attempt, aborts that attempt's signal, and gives retries a fresh deadline and signal. Cancellation and storage faults still throw. Keep pure computation and side-effect-free transformations as ordinary TypeScript. Do not wrap agent-stage internals or every function call indiscriminately; this rule applies to side effects orchestrated directly by the workflow definition.
   - Pass large stage context through files/artifacts and \`reads\` with an explicit \`Read the file at <path>...\` prompt rather than large \`previous\` payloads or injected session history.
   - Wrap critical stage-prompt content in \`<keepContext>\` / \`</keepContext>\`. Tagged content survives compression verbatim regardless of the compression ratio, and every line of the span including the tag lines is protected. A long-running stage will be compacted, and compaction ranks lines individually: an objective is verbose and restated while the constraint that narrows it is usually one line, so the constraint is the cheaper deletion and what survives reads as broader permission than intended. Tag role constraints that bound a stage to part of the work, acceptance criteria and immutable contracts, explicit prohibitions, and identifiers a stage must not lose such as a target branch, worktree path, or run ID. Do not tag bulk context: protected lines count against the keep target rather than raising it, so a large protected span makes the surrounding transcript compress harder — tag the constraint, not the material it applies to.
   - Separate implementation/review acceptance from explicitly authorized final actions such as PR/MR/review creation, release tagging, deployment, or publication. Stop implementation loops once acceptance is proven and carry a remaining final action separately.

package/dist/builtin/workflows/src/extension/workflow-schema.ts

@@ -1,5 +1,33 @@
 import { type Static, Type } from "typebox";
 
+/**
+ * Advertise the JSON value types accepted by workflow-send responses.
+ *
+ * `Type.Unknown()` emits `{}`, which tells a provider nothing about this
+ * property. A retained session shows an assistant tool call that answered a
+ * `ctx.ui.confirm` prompt with the string `"true"` rather than a boolean, so
+ * naming the accepted types is worth doing. It is not the runtime fix: no
+ * inspected host or pi-ai layer converts a boolean to a string, and prompt-kind
+ * normalization happens at the pending-prompt boundary, not in provider
+ * argument validation.
+ *
+ * String comes first so validation does not convert text answers to booleans.
+ */
+const WorkflowResponseSchema = Type.Union(
+	[
+		Type.String(),
+		Type.Boolean(),
+		Type.Number(),
+		Type.Null(),
+		Type.Array(Type.Unknown()),
+		Type.Record(Type.String(), Type.Unknown()),
+	],
+	{
+		description:
+			"Answer payload for a pending stage prompt. Primitive prompts accept text strings, booleans, or numeric select indexes according to the prompt kind; structured prompts may accept JSON arrays or objects.",
+	},
+);
+
 export const WorkflowParametersSchema = Type.Object(
 	{
 		workflow: Type.Optional(
@@ -114,11 +142,7 @@ export const WorkflowParametersSchema = Type.Object(
 				description: "Text to send to a stage for prompt answers, steering, follow-ups, or resume messages.",
 			}),
 		),
-		response: Type.Optional(
-			Type.Unknown({
-				description: "Structured response payload for answering a pending stage prompt.",
-			}),
-		),
+		response: Type.Optional(WorkflowResponseSchema),
 		delivery: Type.Optional(
 			Type.Union(
 				[

package/dist/builtin/workflows/src/extension/workflow-tool-send.ts

@@ -10,6 +10,11 @@ import {
 	expandedStageLabel,
 	expandWorkflowGraph,
 } from "../shared/expanded-workflow-graph.js";
+import {
+	coercePrimitivePromptAnswer,
+	isPrimitivePrompt,
+	primitivePromptAnswerRejection,
+} from "../shared/prompt-answer.js";
 import { coerceStageInputAnswer, hasStageInputAnswerContent, type StageInputAnswer } from "../shared/stage-prompt.js";
 import { stageUiBroker } from "../shared/stage-ui-broker.js";
 import { store } from "../shared/store.js";
@@ -287,7 +292,33 @@ export async function workflowSendAction(
 				`Input request ${promptId} was already answered.`,
 			);
 		}
-		const ok = store.resolveStagePendingPrompt(stageRunId, stage.stageId, promptId, promptPayloadFromArgs(args), {
+		const rawPayload = promptPayloadFromArgs(args);
+		const pendingPrompt = snapshot?.pendingPrompt;
+		const primitivePrompt =
+			pendingPrompt?.id === promptId && isPrimitivePrompt(pendingPrompt) ? pendingPrompt : undefined;
+		if (primitivePrompt !== undefined) {
+			const coercedPayload = coercePrimitivePromptAnswer(primitivePrompt, rawPayload);
+			if (!coercedPayload.ok) {
+				return workflowSendResult(
+					stageRunId,
+					stage.stageId,
+					"answer",
+					"noop",
+					primitivePromptAnswerRejection(promptId, primitivePrompt),
+				);
+			}
+			const ok = store.resolveStagePendingPrompt(stageRunId, stage.stageId, promptId, coercedPayload.value, {
+				answerSource: "workflow_tool",
+			});
+			return workflowSendResult(
+				stageRunId,
+				stage.stageId,
+				"answer",
+				ok ? "ok" : "noop",
+				ok ? `Answered prompt ${promptId}.` : `No matching pending prompt ${promptId}.`,
+			);
+		}
+		const ok = store.resolveStagePendingPrompt(stageRunId, stage.stageId, promptId, rawPayload, {
 			answerSource: "workflow_tool",
 		});
 		return workflowSendResult(

package/dist/builtin/workflows/src/runs/background/cancellation-registry.ts

@@ -13,6 +13,8 @@
  * cross-ref: spec §8.1 Phase D (kill-runtime-wiring downstream)
  */
 
+import { createSessionScopedSingleton } from "../../shared/session-scoped-singleton.js";
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -123,4 +125,11 @@ export function createCancellationRegistry(): CancellationRegistry {
  * Singleton registry for the default runtime. Consumers needing isolation
  * should call createCancellationRegistry() instead.
  */
-export const cancellationRegistry: CancellationRegistry = createCancellationRegistry();
+const SESSION_KEY = "workflows:cancellation:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, createCancellationRegistry);
+
+export const cancellationRegistry: CancellationRegistry = singleton.facade;
+
+export function adoptCancellationRegistry(scope: object): CancellationRegistry {
+	return singleton.adopt(scope);
+}

package/dist/builtin/workflows/src/runs/background/job-tracker.ts

@@ -9,6 +9,8 @@
  * cross-ref: spec detached-runner §job-tracker
  */
 
+import { createSessionScopedSingleton } from "../../shared/session-scoped-singleton.js";
+
 // ---------------------------------------------------------------------------
 // Types
 // ---------------------------------------------------------------------------
@@ -113,4 +115,11 @@ export function createJobTracker(): JobTracker {
 /**
  * Singleton tracker for the default runtime.
  */
-export const jobTracker: JobTracker = createJobTracker();
+const SESSION_KEY = "workflows:job-tracker:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, createJobTracker);
+
+export const jobTracker: JobTracker = singleton.facade;
+
+export function adoptJobTracker(scope: object): JobTracker {
+	return singleton.adopt(scope);
+}

package/dist/builtin/workflows/src/runs/foreground/executor-prompt-nodes.ts

@@ -2,6 +2,7 @@ import type { DurableStageTopology } from "../../durable/types.js";
 import type { DurableUiReplayRequest } from "../../durable/ui-primitive.js";
 import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
 import { appendStageEnd, appendStageStart } from "../../shared/persistence-session-entries.js";
+import { requirePrimitivePromptAnswer } from "../../shared/prompt-answer.js";
 import { withPromptCallerStack } from "../../shared/prompt-callsite-context.js";
 import { stageUiBroker } from "../../shared/stage-ui-broker.js";
 import type { Store } from "../../shared/store.js";
@@ -221,8 +222,16 @@ export function buildPromptNodeUiAdapter(input: {
 		if (shouldReplay) {
 			await Promise.resolve();
 			input.throwIfWorkflowExitSelected();
+			let response = replayAnswer.value;
+			try {
+				if (!isCustom) response = requirePrimitivePromptAnswer(descriptor, response);
+			} catch (err) {
+				applyFailureToStage(stageSnapshot, input.classifyExecutorFailure(err));
+				await finalizePromptStage("failed");
+				throw err;
+			}
 			await finalizePromptStage("completed");
-			return replayAnswer.value;
+			return response;
 		}
 
 		try {
@@ -323,9 +332,10 @@ export function buildPromptNodeUiAdapter(input: {
 					},
 				);
 			});
+			const normalizedResponse = requirePrimitivePromptAnswer(descriptor, response);
 			await waitForExplicitResume();
 			await finalizePromptStage("completed");
-			return response;
+			return normalizedResponse;
 		} catch (err) {
 			if (input.signal.aborted) {
 				input.preserveWorkflowExitSkippedReason(stageSnapshot, "run-aborted");
@@ -355,22 +365,17 @@ export function buildPromptNodeUiAdapter(input: {
 			});
 		},
 		async input(promptText: string): Promise<string> {
-			const response = await ask({ kind: "input", message: promptText });
-			return typeof response === "string" ? response : String(response ?? "");
+			return (await ask({ kind: "input", message: promptText })) as string;
 		},
 		async confirm(message: string): Promise<boolean> {
-			const response = await ask({ kind: "confirm", message });
-			return response === true;
+			return (await ask({ kind: "confirm", message })) as boolean;
 		},
 		async select<T extends string>(message: string, options: readonly T[]): Promise<T> {
 			if (options.length === 0) throw new Error("atomic-workflows: ctx.ui.select requires at least one option");
-			const response = await ask({ kind: "select", message, choices: options });
-			if (typeof response === "string" && (options as readonly string[]).includes(response)) return response as T;
-			return options[0]!;
+			return (await ask({ kind: "select", message, choices: options })) as T;
 		},
 		async editor(initial?: string): Promise<string> {
-			const response = await ask({ kind: "editor", message: "Edit and save to continue.", initial });
-			return typeof response === "string" ? response : (initial ?? "");
+			return (await ask({ kind: "editor", message: "Edit and save to continue.", initial })) as string;
 		},
 		async custom<T>(factory: WorkflowCustomUiFactory<T>, options?: WorkflowCustomUiOptions): Promise<T> {
 			const response = await ask(customPromptDescriptor(factory, options));

package/dist/builtin/workflows/src/runs/foreground/stage-control-registry.ts

@@ -26,6 +26,7 @@
  */
 
 import type { AgentSession, AgentSessionEvent } from "@bastani/atomic";
+import { createSessionScopedSingleton } from "../../shared/session-scoped-singleton.js";
 import type { StageDeliveryActivityEvent } from "./stage-delivery-activity.js";
 import type { StageQueuedUserMessages } from "./stage-queued-user-messages.js";
 import type { StageUserMessageDeliveryAction } from "./stage-runner-types.js";
@@ -188,6 +189,8 @@ export interface StageControlRegistry {
 	get(runId: string, stageId: string): StageControlHandle | undefined;
 	/** Resolve all currently-registered chat handles for a run. */
 	forRun(runId: string): readonly StageControlHandle[];
+	/** True when this run currently has a registration map. */
+	has(runId: string): boolean;
 	/** Build a run-level control aggregate. Cheap; not memoised. */
 	run(runId: string): WorkflowRunControlHandle;
 	/**
@@ -196,6 +199,13 @@ export interface StageControlRegistry {
 	 * their subscriptions when the host store is cleared.
 	 */
 	clear(): void;
+	/**
+	 * Drop only handles detached from run-level control (`controlsDependencies`
+	 * false), disposing them through the background-dispose path. Live executor
+	 * handles that still own workflow execution stay registered. Emptied run
+	 * maps are pruned.
+	 */
+	clearDetached(): void;
 }
 
 /**
@@ -415,6 +425,9 @@ export function createStageControlRegistry(): StageControlRegistry {
 			if (!runMap) return [];
 			return [...runMap.values()].map((entry) => entry.handle);
 		},
+		has(runId: string): boolean {
+			return _byRun.has(runId);
+		},
 		run(runId: string): WorkflowRunControlHandle {
 			return makeRunHandle(runId);
 		},
@@ -425,6 +438,16 @@ export function createStageControlRegistry(): StageControlRegistry {
 				disposeEntryInBackground(entry, "atomic-workflows: stage handle dispose failed");
 			}
 		},
+		clearDetached(): void {
+			for (const [runId, runMap] of [..._byRun]) {
+				for (const [stageId, entry] of [...runMap]) {
+					if (entry.controlsDependencies) continue;
+					runMap.delete(stageId);
+					disposeEntryInBackground(entry, "atomic-workflows: detached stage handle dispose failed");
+				}
+				if (runMap.size === 0) _byRun.delete(runId);
+			}
+		},
 	};
 }
 
@@ -433,4 +456,11 @@ export function createStageControlRegistry(): StageControlRegistry {
  * explicit instance via `RunOpts.stageControlRegistry`; the singleton
  * is the default consumer surface used by the extension factory.
  */
-export const stageControlRegistry: StageControlRegistry = createStageControlRegistry();
+const SESSION_KEY = "workflows:stage-control:v1";
+const singleton = createSessionScopedSingleton(SESSION_KEY, createStageControlRegistry);
+
+export const stageControlRegistry: StageControlRegistry = singleton.facade;
+
+export function adoptStageControlRegistry(scope: object): StageControlRegistry {
+	return singleton.adopt(scope);
+}

package/dist/builtin/workflows/src/runs/foreground/stage-runner-context.ts

@@ -1,7 +1,8 @@
 import { createStructuredOutputCapture, runCallback } from "@bastani/atomic";
+import type { Static, TSchema } from "typebox";
 import type { StageExecutionMeta } from "../../shared/types.js";
 import { StageSessionController } from "./stage-runner-controller.js";
-import { assistantMessage } from "./stage-runner-messages.js";
+import { assistantArtifactTextForToolCall, assistantMessage } from "./stage-runner-messages.js";
 import {
 	finalizePromptOutput,
 	splitPromptOptions,
@@ -12,6 +13,7 @@ import {
 	formatStructuredOutputCorrectionPrompt,
 	STRUCTURED_OUTPUT_MAX_CORRECTIVE_PROMPTS,
 	STRUCTURED_OUTPUT_MISSING_ERROR,
+	type StructuredOutputExecutionCapture,
 	stageOptionsWithStructuredOutput,
 	stringifyStructuredOutputValue,
 } from "./stage-runner-structured-output.js";
@@ -19,8 +21,14 @@ import type { InternalStageContext, StageRunnerOpts } from "./stage-runner-types
 
 export function createStageContext(opts: StageRunnerOpts): InternalStageContext {
 	const { stageId, stageName, adapters, runId, workflowIntercomGroup, signal, stageOptions, executionMode } = opts;
-	const structuredOutputCapture = stageOptions?.schema ? createStructuredOutputCapture<unknown>() : undefined;
-	const effectiveStageOptions = stageOptionsWithStructuredOutput(stageOptions, structuredOutputCapture);
+	const structuredOutputCapture = stageOptions?.schema ? createStructuredOutputCapture<Static<TSchema>>() : undefined;
+	const structuredOutputExecutionCapture: StructuredOutputExecutionCapture<Static<TSchema>> | undefined =
+		stageOptions?.schema ? {} : undefined;
+	const effectiveStageOptions = stageOptionsWithStructuredOutput(
+		stageOptions,
+		structuredOutputCapture,
+		structuredOutputExecutionCapture,
+	);
 	const meta: StageExecutionMeta = {
 		runId,
 		stageId,
@@ -34,6 +42,7 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 	let lastAssistantText: string | undefined;
 	let lastFinalizedOutput: string | undefined;
 	let lastFinalizedMessageCount: number | undefined;
+	let structuredArtifactFinalized = false;
 	let adapterMessages = [] as InternalStageContext["messages"];
 
 	function runtimeCwd(): string {
@@ -43,7 +52,8 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 	function finalizedOutputIsCurrent(): boolean {
 		return (
 			lastFinalizedOutput !== undefined &&
-			(lastFinalizedMessageCount === undefined ||
+			(structuredArtifactFinalized ||
+				lastFinalizedMessageCount === undefined ||
 				controller.currentSession?.messages.length === lastFinalizedMessageCount)
 		);
 	}
@@ -54,9 +64,10 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 		async prompt(text, options) {
 			const { sdkOptions, outputOptions } = splitPromptOptions(options);
 			validatePromptOutputOptions(outputOptions);
+			const hasOutputArtifact = typeof outputOptions.output === "string" && outputOptions.output.length > 0;
 			// The runtime owns the artifact write, so it states that contract itself
 			// rather than relying on every workflow definition to describe it.
-			const promptText = `${text}${stageOutputInstruction(outputOptions)}`;
+			const promptText = `${text}${stageOutputInstruction(outputOptions, structuredOutputCapture !== undefined)}`;
 			if (structuredOutputCapture?.called) {
 				throw new Error(
 					"atomic-workflows: stage schema supports one prompt() call per stage context because structured_output may be called exactly once. Create a new ctx.stage(...) for each additional schema-backed prompt.",
@@ -97,19 +108,39 @@ export function createStageContext(opts: StageRunnerOpts): InternalStageContext
 						throw new Error(structuredOutputError);
 					}
 					correctiveAttempts += 1;
-					nextPrompt = formatStructuredOutputCorrectionPrompt(structuredOutputError, correctiveAttempts);
+					nextPrompt = formatStructuredOutputCorrectionPrompt(
+						structuredOutputError,
+						correctiveAttempts,
+						hasOutputArtifact,
+					);
+				}
+				const sessionMessages = controller.currentSession?.messages;
+				const executionSnapshot = structuredOutputExecutionCapture?.snapshot;
+				if (executionSnapshot === undefined) {
+					throw new Error(
+						"atomic-workflows: structured_output completed without an execution snapshot; the successful tool call could not be paired with its result.",
+					);
 				}
-				const rawStructuredText = stringifyStructuredOutputValue(structuredOutputCapture.value);
+				// The exact successful tool-call message owns the artifact. When it
+				// carries no ordinary text — or the session no longer holds it after
+				// model-fallback recreation — fall back to the last non-structured
+				// assistant text so an earlier-turn deliverable is not discarded
+				// (issue #2198); only when no prose exists anywhere is the artifact
+				// empty, and its receipt then carries the empty-artifact warning.
+				const rawOutputText = hasOutputArtifact
+					? (assistantArtifactTextForToolCall(sessionMessages ?? [], executionSnapshot.toolCallId) ?? "")
+					: stringifyStructuredOutputValue(executionSnapshot.value);
 				lastAssistantText = await finalizePromptOutput(
-					rawStructuredText,
+					rawOutputText,
 					outputOptions,
 					runtimeCwd(),
 					runId,
-					controller.currentSession?.messages,
+					sessionMessages,
 				);
 				lastFinalizedOutput = lastAssistantText;
 				lastFinalizedMessageCount = controller.currentSession?.messages.length;
-				return structuredOutputCapture.value as never;
+				if (hasOutputArtifact) structuredArtifactFinalized = true;
+				return executionSnapshot.value as never;
 			}
 			await controller.promptWithFallback(promptText, sdkOptions);
 			const rawText = controller.lastAssistantText(lastAssistantText) ?? "";

package/dist/builtin/workflows/src/runs/foreground/stage-runner-messages.ts

@@ -5,6 +5,8 @@ import type { StageSessionRuntime } from "./stage-runner-types.js";
 type TextLikeContent = {
 	readonly type?: string;
 	readonly text?: string;
+	readonly id?: string;
+	readonly name?: string;
 };
 
 type MessageWithTextContent = {
@@ -33,6 +35,52 @@ export function lastAssistantTextFromMessages(messages: AgentSession["messages"]
 	return undefined;
 }
 
+/**
+ * Artifact text for a successful `structured_output` call (issue #2198).
+ *
+ * Primary: the ordinary text of the exact assistant message that carried the
+ * successful tool call, so corrective attempts and later admitted turns cannot
+ * replace the pairing. Fallback: when that message carries no ordinary text —
+ * or the session no longer holds it after model-fallback recreation — the most
+ * recent earlier assistant message that carries text and makes no
+ * `structured_output` call. Assistant turns after the successful call never
+ * win. When neither side exists the caller writes an empty artifact and its
+ * receipt carries the standard empty-artifact warning; the companion
+ * transcript remains the recovery path.
+ */
+export function assistantArtifactTextForToolCall(
+	messages: AgentSession["messages"],
+	toolCallId: string,
+): string | undefined {
+	for (let index = messages.length - 1; index >= 0; index -= 1) {
+		const message = messages[index];
+		if (message?.role !== "assistant") continue;
+		const { content } = message as MessageWithTextContent;
+		if (!Array.isArray(content)) continue;
+		if (!content.some((block) => block.type === "toolCall" && block.id === toolCallId)) continue;
+		const text = extractMessageText(message);
+		if (text.trim().length > 0) return text;
+		return lastNonStructuredAssistantTextBefore(messages, index);
+	}
+	return lastNonStructuredAssistantTextBefore(messages, messages.length);
+}
+
+function lastNonStructuredAssistantTextBefore(
+	messages: AgentSession["messages"],
+	endIndex: number,
+): string | undefined {
+	for (let index = endIndex - 1; index >= 0; index -= 1) {
+		const message = messages[index];
+		if (message?.role !== "assistant") continue;
+		const { content } = message as MessageWithTextContent;
+		if (!Array.isArray(content)) continue;
+		if (content.some((block) => block.type === "toolCall" && block.name === "structured_output")) continue;
+		const text = extractMessageText(message);
+		if (text.trim().length > 0) return text;
+	}
+	return undefined;
+}
+
 function messageStopReason(message: AgentSession["messages"][number]): string | undefined {
 	const record = message as { readonly stopReason?: unknown };
 	return typeof record.stopReason === "string" ? record.stopReason : undefined;

package/dist/builtin/workflows/src/runs/foreground/stage-runner-output.ts

@@ -218,8 +218,11 @@ export function validatePromptOutputOptions(outputOptions: StageOutputOptions):
  * "done, see the file" and persist that sentence as its deliverable, which is a
  * foot-gun the workflow definition cannot see.
  */
-export function stageOutputInstruction(outputOptions: StageOutputOptions): string {
+export function stageOutputInstruction(outputOptions: StageOutputOptions, hasStructuredOutput = false): string {
 	if (typeof outputOptions.output !== "string" || outputOptions.output.length === 0) return "";
+	if (hasStructuredOutput) {
+		return "\n\n[This stage has two final output channels. In the same final assistant message, write the complete human-readable artifact as ordinary assistant text before calling structured_output. That text is saved verbatim as the artifact and is what later stages read; the structured_output tool arguments are the machine-readable result for workflow logic. Do not replace the artifact text with JSON or a pointer to another file. Files you write yourself are not the artifact.]";
+	}
 	return "\n\n[This stage's final message is saved verbatim as its artifact and is what later stages read. Return the complete result in that message rather than a pointer to it. Files you write yourself are not the artifact.]";
 }
 

package/dist/builtin/workflows/src/runs/foreground/stage-runner-structured-output.ts

@@ -8,6 +8,15 @@ export const STRUCTURED_OUTPUT_MISSING_ERROR =
 
 const STRUCTURED_OUTPUT_TOOL_NAME = "structured_output";
 
+export interface StructuredOutputExecutionSnapshot<TValue> {
+	readonly toolCallId: string;
+	readonly value: TValue;
+}
+
+export interface StructuredOutputExecutionCapture<TValue> {
+	snapshot?: StructuredOutputExecutionSnapshot<TValue>;
+}
+
 type ToolResultContentBlock = {
 	readonly type?: unknown;
 	readonly text?: unknown;
@@ -36,7 +45,11 @@ export function structuredOutputToolErrorFromEvent(event: unknown): string | und
 	return toolResultText(resultRecord?.content) ?? "structured_output tool call failed schema validation.";
 }
 
-export function formatStructuredOutputCorrectionPrompt(error: string, attempt: number): string {
+export function formatStructuredOutputCorrectionPrompt(
+	error: string,
+	attempt: number,
+	needsArtifactText = false,
+): string {
 	return [
 		"The previous response failed this stage's structured-output contract.",
 		"",
@@ -46,7 +59,10 @@ export function formatStructuredOutputCorrectionPrompt(error: string, attempt: n
 		error,
 		"",
 		"You must finish by calling the `structured_output` tool exactly once with arguments matching the registered schema.",
-		"Do not answer with plain JSON text, Markdown, or prose. If you attempted `structured_output` and validation failed, correct the tool arguments and call `structured_output` again.",
+		"If you attempted `structured_output` and validation failed, correct the tool arguments and call `structured_output` again.",
+		needsArtifactText
+			? "In the same final assistant message, include the complete human-readable artifact as ordinary text before calling `structured_output`; the tool arguments are the separate machine-readable result. Do not put prose after the tool call, and do not write the artifact as plain JSON text or Markdown code."
+			: "Do not answer with plain JSON text, Markdown, or prose.",
 	].join("\n");
 }
 
@@ -60,11 +76,34 @@ export function stringifyStructuredOutputValue(value: unknown): string {
 	}
 }
 
-export function stageOptionsWithStructuredOutput(
-	options: StageOptions | undefined,
-	capture: StructuredOutputCapture<unknown> | undefined,
+export function stageOptionsWithStructuredOutput<TSchemaDef extends TSchema>(
+	options: StageOptions<TSchemaDef | undefined> | undefined,
+	capture: StructuredOutputCapture<Static<TSchemaDef>> | undefined,
+	executionCapture?: StructuredOutputExecutionCapture<Static<TSchemaDef>>,
 ): StageOptions | undefined {
 	if (!options?.schema || !capture) return options;
+	const structuredOutputTool = createStructuredOutputTool({
+		schema: options.schema,
+		capture,
+	});
+	const executeStructuredOutput = structuredOutputTool.execute;
+	const capturedStructuredOutputTool = {
+		...structuredOutputTool,
+		async execute(...args: Parameters<typeof executeStructuredOutput>) {
+			const result = await executeStructuredOutput(...args);
+			// Mirror the shared capture, which keeps the latest successful call:
+			// a model-fallback session recreation can execute the tool a second
+			// time, and the snapshot must describe the call the live session (and
+			// its messages) actually holds, not an abandoned earlier one.
+			if (executionCapture !== undefined && capture.called) {
+				executionCapture.snapshot = {
+					toolCallId: args[0],
+					value: args[1],
+				};
+			}
+			return result;
+		},
+	};
 	const tools =
 		options.tools === undefined
 			? options.noTools === "all"
@@ -76,12 +115,6 @@ export function stageOptionsWithStructuredOutput(
 		...options,
 		...(tools !== undefined ? { tools } : {}),
 		...(excludedTools !== undefined ? { excludedTools } : {}),
-		customTools: [
-			...(options.customTools ?? []),
-			createStructuredOutputTool({
-				schema: options.schema as TSchema,
-				capture: capture as StructuredOutputCapture<Static<TSchema>>,
-			}),
-		],
+		customTools: [...(options.customTools ?? []), capturedStructuredOutputTool],
 	};
 }

package/dist/builtin/workflows/src/sdk-surface.ts

@@ -8,6 +8,15 @@
 export type { Static, TSchema } from "typebox";
 export { KEEP_CONTEXT_CLOSE_TAG, KEEP_CONTEXT_OPEN_TAG, keepContext } from "./authoring/keep-context.js";
 export { workflow } from "./authoring/workflow.js";
+export type {
+	WorkflowHeartbeatEvent,
+	WorkflowHeartbeatEventDetails,
+	WorkflowHeartbeatIdentity,
+} from "./shared/workflow-heartbeat-contract.js";
+export {
+	DEFAULT_WORKFLOW_HEARTBEAT_INTERVAL_MINUTES,
+	WORKFLOW_HEARTBEAT_CUSTOM_TYPE,
+} from "./shared/workflow-heartbeat-contract.js";
 
 const REMOVED_RUN_WORKFLOW_MESSAGE =
 	"@bastani/workflows no longer exports runWorkflow; author workflows with workflow({...})";

package/dist/builtin/workflows/src/shared/authoring-contract-ui.d.ts

@@ -98,6 +98,8 @@ export interface WorkflowToolOptions {
     readonly maxAttempts?: number;
     readonly intervalMs?: number;
     readonly backoffRate?: number;
+    /** Maximum duration in milliseconds for each callback attempt. */
+    readonly timeoutMs?: number;
 }
 export type WorkflowToolReturnOptions = WorkflowToolOptions & {
     readonly failureMode: "return";
@@ -149,6 +151,7 @@ export interface WorkflowDefinition<TInputs extends WorkflowInputValues = Workfl
     readonly normalizedName: string;
     readonly description: string;
     readonly autoAttach?: true;
+    readonly heartbeatIntervalMinutes: number;
     readonly inputs: WorkflowInputSchemaMap;
     readonly outputs?: WorkflowOutputSchemaMap;
     readonly inputBindings?: WorkflowInputBindings;
@@ -264,6 +267,8 @@ export interface ToolNodeSnapshot extends WorkflowSerializableObject {
     /** Stable durable node identity. */
     readonly id: string;
     readonly name: string;
+    /** Exact invocation arguments retained for read-only graph inspection. */
+    readonly args?: Readonly<Record<string, WorkflowSerializableValue>>;
     readonly argsHash: string;
     readonly ordinal: number;
     readonly parentIds: readonly string[];
@@ -273,6 +278,11 @@ export interface ToolNodeSnapshot extends WorkflowSerializableObject {
     readonly executionOrder?: number;
     readonly startedAt?: number;
     readonly endedAt?: number;
+    readonly durationMs?: number;
+    /** Full serializable callback result, when one was retained. */
+    readonly result?: WorkflowSerializableValue;
+    /** Callback source captured from `fn.toString()` at registration. */
+    readonly source?: string;
     readonly resultSummary?: string;
     readonly error?: string;
     readonly attachable: false;