@bastani/atomic 0.9.13-alpha.1 → 0.9.13-alpha.3

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

@@ -5,15 +5,20 @@ import {
 import type { DetachedStageHandleLease, StageControlHandle } from "../runs/foreground/stage-control-registry.js";
 import { stageControlRegistry } from "../runs/foreground/stage-control-registry.js";
 import type { StageUserMessageDeliveryAction } from "../runs/foreground/stage-runner-types.js";
+import {
+	type ExpandedWorkflowStage,
+	expandedStageLabel,
+	expandWorkflowGraph,
+} from "../shared/expanded-workflow-graph.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";
 import { isTerminalRunStatus } from "../shared/store-internal.js";
-import { subscribeStoreInvalidation } from "../shared/store-observation.js";
+import { readGraphStoreSnapshot, subscribeStoreInvalidation } from "../shared/store-observation.js";
 import { reciprocalWorkflowRootRunId } from "../shared/workflow-run-ownership.js";
 import type { WorkflowToolArgs } from "./public-types.js";
 import type { WorkflowToolResult } from "./render-result.js";
-import { resolveToolRunTarget, resolveToolStageTarget } from "./workflow-targets.js";
+import { resolveToolRunTarget, resolveToolStageTarget, type ToolStageTarget } from "./workflow-targets.js";
 
 /**
  * Optional dependencies enabling `workflow send` to revive an eligible
@@ -49,6 +54,69 @@ function brokerAnswerFromArgs(args: WorkflowToolArgs): StageInputAnswer {
 	return text !== undefined ? { text } : {};
 }
 
+/**
+ * Whether this delivery is one whose destination a pending prompt determines.
+ *
+ * `answer` and `auto` are both documented as answering pending prompts first,
+ * and an explicit `promptId` names a prompt without naming its stage. Steering
+ * deliveries are excluded: a live stage is a destination in its own right, so
+ * there is nothing for a prompt to disambiguate.
+ */
+function answersPendingPrompt(delivery: string, promptId: string | undefined): boolean {
+	return delivery === "answer" || delivery === "auto" || promptId !== undefined;
+}
+
+/**
+ * Ids of the prompts an `answer` delivery could resolve on this stage.
+ *
+ * Covers the same three prompt kinds the delivery path dispatches on —
+ * brokered, custom-footprint, and plain pending prompts — so a stage counted
+ * here is one the send would actually act on rather than merely mention.
+ */
+function answerablePromptIds(stage: ExpandedWorkflowStage): string[] {
+	const target = stage.workflowGraphTarget;
+	const ids: string[] = [];
+	const brokered = stageUiBroker.peekStagePrompt(target.runId, target.stageId);
+	if (brokered !== undefined) ids.push(brokered.id);
+	if (stage.pendingPrompt !== undefined) ids.push(stage.pendingPrompt.id);
+	if (stage.status === "awaiting_input" && stage.promptFootprint?.kind === "custom") {
+		ids.push(stage.promptFootprint.id);
+	}
+	return ids;
+}
+
+/**
+ * Resolve the stage an answer is for when the caller named a prompt but no stage.
+ *
+ * A named `promptId` already identifies its stage, so it narrows the candidates
+ * before uniqueness is decided — otherwise naming one of two pending prompts
+ * would be rejected as ambiguous, and naming an unknown one would target the
+ * unrelated stage that happened to be the only one waiting.
+ *
+ * Returns the target unchanged when nothing is pending, so a run with no prompt
+ * still reports that a stage is required rather than inventing a destination.
+ */
+function inferPromptStageTarget(runId: string, delivery: string, promptId: string | undefined): ToolStageTarget {
+	if (!answersPendingPrompt(delivery, promptId)) return { ok: true, runId };
+	const pending = expandWorkflowGraph(readGraphStoreSnapshot(store), runId).stages.filter((stage) => {
+		const ids = answerablePromptIds(stage);
+		return promptId === undefined ? ids.length > 0 : ids.includes(promptId);
+	});
+	const only = pending[0];
+	if (pending.length === 1 && only !== undefined) {
+		return { ok: true, runId: only.workflowGraphTarget.runId, stageId: only.workflowGraphTarget.stageId };
+	}
+	if (pending.length === 0) {
+		return promptId === undefined
+			? { ok: true, runId }
+			: { ok: false, message: `No pending prompt ${promptId} in run ${runId}.` };
+	}
+	return {
+		ok: false,
+		message: `${pending.length} prompts pending; pass stageId: ${pending.map(expandedStageLabel).join(", ")}`,
+	};
+}
+
 type WorkflowSendToolResult = Extract<WorkflowToolResult, { action: "send" }>;
 
 function workflowSendResult(
@@ -131,7 +199,11 @@ export async function workflowSendAction(
 	if (rootRun !== undefined && isTerminalRunStatus(rootRun.status)) {
 		return terminalWorkflowSendResult(rootRun.id, args.stageId?.trim() ?? "", rootRun.status);
 	}
-	const stage = resolveToolStageTarget(target.runId, args.stageId);
+	const requested = resolveToolStageTarget(target.runId, args.stageId);
+	const stage =
+		requested.ok && requested.stageId === undefined
+			? inferPromptStageTarget(target.runId, requestedDelivery, args.promptId)
+			: requested;
 	if (!stage.ok || stage.stageId === undefined) {
 		return workflowSendResult(
 			target.runId,

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

@@ -18,9 +18,49 @@ import {
 	workflowReloadAction,
 	workflowResumeAction,
 } from "./workflow-tool-control.js";
-import { workflowStageResult, workflowStagesResult, workflowTranscriptResult } from "./workflow-tool-inspection.js";
+import {
+	type WorkflowInspectionSource,
+	workflowStageResult,
+	workflowStagesResult,
+	workflowTranscriptResult,
+} from "./workflow-tool-inspection.js";
 import { type WorkflowSendDeps, workflowSendAction } from "./workflow-tool-send.js";
 
+type DurableInspectionSourceResolution =
+	| { readonly kind: "local" }
+	| { readonly kind: "durable"; readonly source: WorkflowInspectionSource }
+	| { readonly kind: "error"; readonly message: string };
+
+async function resolveDurableInspectionSource(
+	args: WorkflowToolArgs,
+	runtime: ExtensionRuntime,
+): Promise<DurableInspectionSourceResolution> {
+	const target = args.runId?.trim();
+	if (args.all === true || target === undefined || target.length === 0 || target === "--all") return { kind: "local" };
+	const local = resolveRunId(target);
+	if (local.kind !== "not_found") return { kind: "local" };
+	const durable = await runtime.inspectDurableWorkflow(target);
+	if (durable.kind !== "found") return { kind: "error", message: durable.message };
+	return { kind: "durable", source: { store: durable.store, allowLiveHandles: false } };
+}
+
+function durableInspectionError(
+	action: "stages" | "stage" | "transcript",
+	runId: string,
+	message: string,
+): WorkflowToolResult {
+	if (action === "stages") return { action, runId, filter: "all", stages: [], error: message };
+	if (action === "stage") return { action, runId, error: message };
+	return {
+		action,
+		runId,
+		stageId: "",
+		source: "error",
+		entries: [{ role: "notice", text: message }],
+		truncated: false,
+	};
+}
+
 export function makeExecuteWorkflowTool(
 	runtime: ExtensionRuntime | ((ctx: PiExecuteContext) => ExtensionRuntime),
 	reloadWorkflowResources: () => Promise<WorkflowReloadReport | undefined> | undefined,
@@ -87,7 +127,10 @@ export function makeExecuteWorkflowTool(
 						return { action: "statusDetail", runId: target, error: resolved.message };
 					}
 					if (resolved.kind === "not_found") {
-						return { action: "statusDetail", runId: target, error: `run not found: ${target}` };
+						const durable = await getRuntime().inspectDurableWorkflow(target);
+						return durable.kind === "found"
+							? { action: "statusDetail", runId: target, detail: durable.detail }
+							: { action: "statusDetail", runId: target, error: durable.message };
 					}
 					const result = inspectRun(resolved.runId);
 					return result.ok
@@ -105,11 +148,15 @@ export function makeExecuteWorkflowTool(
 				return result;
 			}
 			case "stages":
-				return workflowStagesResult(args);
 			case "stage":
-				return workflowStageResult(args);
-			case "transcript":
-				return workflowTranscriptResult(args);
+			case "transcript": {
+				const resolved = await resolveDurableInspectionSource(args, getRuntime());
+				if (resolved.kind === "error") return durableInspectionError(action, args.runId ?? "", resolved.message);
+				const source = resolved.kind === "durable" ? resolved.source : undefined;
+				if (action === "stages") return workflowStagesResult(args, source);
+				if (action === "stage") return workflowStageResult(args, source);
+				return workflowTranscriptResult(args, source);
+			}
 			case "send":
 				return workflowSendAction(args, sendDeps);
 			case "pause":

package/dist/builtin/workflows/src/intercom/intercom-routing.ts

@@ -7,6 +7,7 @@
  * cross-ref: spec §5.10, RFC §8.1 Phase G
  */
 
+import { isStaleExtensionContextError } from "@bastani/atomic";
 import type { Store } from "../shared/store.js";
 import type { NoticeLevel } from "../shared/store-types.js";
 import type { IntercomControlCallbacks, IntercomControlPayload } from "./result-intercom.js";
@@ -90,12 +91,17 @@ export function buildIntercomCallbacks(deps: IntercomRoutingDeps): IntercomContr
 					? await confirm("Subagent needs decision", payload.message).catch(() => false)
 					: false;
 
-			emit?.("subagent:control-intercom:response", {
-				requestId: payload.requestId ?? "",
-				runId: payload.runId ?? "",
-				stageId: payload.stageId ?? "",
-				accepted,
-			});
+			try {
+				emit?.("subagent:control-intercom:response", {
+					requestId: payload.requestId ?? "",
+					runId: payload.runId ?? "",
+					stageId: payload.stageId ?? "",
+					accepted,
+				});
+			} catch (error) {
+				if (!isStaleExtensionContextError(error)) throw error;
+				// The decision can finish after the workflow extension reloads.
+			}
 
 			store.ackNotice(noticeId);
 		},

package/dist/builtin/workflows/src/intercom/result-intercom.ts

@@ -15,6 +15,7 @@
  * cross-ref: spec §5.10 Integration with pi-intercom, §8.1 Phase G
  */
 
+import { isStaleExtensionContextError } from "@bastani/atomic";
 import type { WorkflowDetails } from "../shared/types.js";
 
 // ---------------------------------------------------------------------------
@@ -103,6 +104,10 @@ export interface WorkflowControlIntercomPayload {
 	readonly mode: WorkflowDetails["mode"];
 	readonly status: WorkflowDetails["status"];
 	readonly message: string;
+	/** Terminal ctx.exit() discriminator and payload for parent sessions. */
+	readonly exited?: boolean;
+	readonly exitReason?: string;
+	readonly outputs?: WorkflowDetails["output"];
 	readonly parentSession?: string;
 	readonly createdAt: number;
 }
@@ -150,10 +155,19 @@ export function emitWorkflowControlIntercom(
 		mode: details.mode,
 		status: details.status,
 		message,
+		...(details.exited !== undefined ? { exited: details.exited } : {}),
+		...(details.exitReason !== undefined ? { exitReason: details.exitReason } : {}),
+		...(details.output !== undefined ? { outputs: details.output } : {}),
 		...(parentSession !== undefined ? { parentSession } : {}),
 		createdAt: Date.now(),
 	};
-	port!.emit!("workflow:control-intercom", payload as unknown as Record<string, unknown>);
+	try {
+		port!.emit!("workflow:control-intercom", payload as unknown as Record<string, unknown>);
+	} catch (error) {
+		if (!isStaleExtensionContextError(error)) throw error;
+		// A workflow can outlive the extension runtime that supplied the port.
+		return false;
+	}
 	return true;
 }
 
@@ -174,7 +188,13 @@ export function emitWorkflowResultIntercom(
 		...(parentSession !== undefined ? { parentSession } : {}),
 		createdAt: Date.now(),
 	};
-	port!.emit!("workflow:result-intercom", payload as unknown as Record<string, unknown>);
+	try {
+		port!.emit!("workflow:result-intercom", payload as unknown as Record<string, unknown>);
+	} catch (error) {
+		if (!isStaleExtensionContextError(error)) throw error;
+		// A workflow can outlive the extension runtime that supplied the port.
+		return false;
+	}
 	return true;
 }
 
@@ -231,10 +251,21 @@ export function subscribeIntercomControl(
 		});
 	};
 
-	const unsubscribe = pi.events!.on!("subagent:control-intercom", handler);
+	let unsubscribe: unknown;
+	try {
+		unsubscribe = pi.events!.on!("subagent:control-intercom", handler);
+	} catch (error) {
+		if (!isStaleExtensionContextError(error)) throw error;
+		return null;
+	}
 
 	return () => {
 		active = false;
-		if (typeof unsubscribe === "function") unsubscribe();
+		try {
+			if (typeof unsubscribe === "function") unsubscribe();
+		} catch (error) {
+			if (!isStaleExtensionContextError(error)) throw error;
+			// Stale event-bus cleanup is best effort.
+		}
 	};
 }

package/dist/builtin/workflows/src/runs/background/run-inspect.ts

@@ -28,7 +28,7 @@ import type { WorkflowInputValues, WorkflowOutputValues } from "../../shared/typ
 export interface RunDetail {
 	readonly runId: string;
 	readonly name: string;
-	readonly status: RunStatus;
+	readonly status: RunStatus | "crashed";
 	readonly mode: "single" | "chain";
 	readonly startedAt: number;
 	readonly endedAt?: number;
@@ -54,6 +54,10 @@ export interface RunDetail {
 	readonly failedToolNodeId?: string;
 	readonly resumable?: boolean;
 	readonly retryAfterMs?: number;
+	/** Actionable guidance for a snapshot hydrated from durable storage. */
+	readonly resumeGuidance?: string;
+	/** True when a fresh durable owner is active in another Atomic process. */
+	readonly ownerActiveElsewhere?: boolean;
 	readonly blockedAt?: number;
 }
 

package/dist/builtin/workflows/src/runs/background/status.ts

@@ -342,6 +342,21 @@ export async function resumeRun(
 			message: "This workflow is not resumable; inspect the snapshot and start a new workflow run when ready.",
 		};
 	}
+	if (
+		current.status === "failed" &&
+		current.endedAt !== undefined &&
+		current.exited === true &&
+		current.resumable === true
+	) {
+		return {
+			ok: true,
+			runId,
+			snapshot,
+			resumed: resumedCopy,
+			mode: "snapshot",
+			message: `This failed run is marked resumable; use /workflow resume ${runId} to ask the durable backend to retry it or start a new workflow run.`,
+		};
+	}
 	if (
 		current.endedAt === undefined &&
 		current.resumable === true &&

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

@@ -7,6 +7,7 @@ const WORKFLOW_EXIT_STATUSES: ReadonlySet<WorkflowExitStatus> = new Set([
 	"skipped",
 	"cancelled",
 	"blocked",
+	"failed",
 ]);
 
 export type WorkflowExitOutputSnapshot =
@@ -24,6 +25,7 @@ export interface WorkflowExitSignal {
 	readonly scope: symbol;
 	readonly status: WorkflowExitStatus;
 	readonly reason?: string;
+	readonly resumable?: boolean;
 	readonly outputSnapshot?: WorkflowExitOutputSnapshot;
 	readonly validationError?: Error;
 }
@@ -32,6 +34,7 @@ export function makeWorkflowExitSignal(input: {
 	readonly scope: symbol;
 	readonly status: WorkflowExitStatus;
 	readonly reason?: string;
+	readonly resumable?: boolean;
 	readonly outputSnapshot?: WorkflowExitOutputSnapshot;
 	readonly validationError?: Error;
 }): WorkflowExitSignal {
@@ -40,6 +43,7 @@ export function makeWorkflowExitSignal(input: {
 		scope: input.scope,
 		status: input.status,
 		...(input.reason !== undefined ? { reason: input.reason } : {}),
+		...(input.resumable !== undefined ? { resumable: input.resumable } : {}),
 		...(input.outputSnapshot !== undefined ? { outputSnapshot: input.outputSnapshot } : {}),
 		...(input.validationError !== undefined ? { validationError: input.validationError } : {}),
 	};
@@ -81,13 +85,13 @@ function workflowExitSnapshotError(message: string, cause: unknown): Error {
 	return new Error(`${message}: ${unknownErrorMessage(cause)}`, { cause });
 }
 
-function workflowExitOptionReadError(key: "status" | "reason" | "outputs", cause: unknown): Error {
+function workflowExitOptionReadError(key: "status" | "reason" | "resumable" | "outputs", cause: unknown): Error {
 	return workflowExitSnapshotError(`atomic-workflows: ctx.exit() ${key} option could not be read`, cause);
 }
 
 export function readWorkflowExitOption(
-	options: Pick<WorkflowExitOptions, "status" | "reason" | "outputs"> | null | undefined,
-	key: "status" | "reason" | "outputs",
+	options: Pick<WorkflowExitOptions, "status" | "reason" | "resumable" | "outputs"> | null | undefined,
+	key: "status" | "reason" | "resumable" | "outputs",
 ): { readonly ok: true; readonly value: unknown } | { readonly ok: false; readonly error: Error } {
 	try {
 		return { ok: true, value: options?.[key] };
@@ -339,6 +343,9 @@ function readWorkflowExitSignalCandidate(value: object, scope: symbol): Workflow
 	const reason = safeGetProperty(value, "reason");
 	if (!reason.ok || (reason.value !== undefined && typeof reason.value !== "string")) return undefined;
 
+	const resumable = safeGetProperty(value, "resumable");
+	if (!resumable.ok || (resumable.value !== undefined && typeof resumable.value !== "boolean")) return undefined;
+
 	const outputSnapshotValue = safeGetProperty(value, "outputSnapshot");
 	if (!outputSnapshotValue.ok) return undefined;
 	const outputSnapshot = readWorkflowExitOutputSnapshot(outputSnapshotValue.value);
@@ -352,6 +359,7 @@ function readWorkflowExitSignalCandidate(value: object, scope: symbol): Workflow
 		scope,
 		status: status.value,
 		...(reason.value !== undefined ? { reason: reason.value } : {}),
+		...(resumable.value !== undefined ? { resumable: resumable.value } : {}),
 		...(outputSnapshot !== undefined ? { outputSnapshot } : {}),
 		...(validationError.value !== undefined ? { validationError: safeErrorValue(validationError.value) } : {}),
 	};

package/dist/builtin/workflows/src/runs/foreground/executor-child-boundary.ts

@@ -41,11 +41,12 @@ export interface WorkflowBoundaryStage {
 }
 
 function workflowChildResultFromReplay(snapshot: WorkflowChildReplaySnapshot): WorkflowChildResult {
+	const exited = snapshot.exited ?? (snapshot.status === "completed" ? false : undefined);
 	const candidate = {
 		workflow: snapshot.workflow,
 		runId: snapshot.runId,
 		status: snapshot.status,
-		exited: snapshot.exited,
+		exited,
 		outputs: cloneWorkflowChildValue(snapshot.outputs),
 		...(snapshot.exitReason !== undefined ? { exitReason: snapshot.exitReason } : {}),
 	} as WorkflowSerializableValue;

package/dist/builtin/workflows/src/runs/foreground/executor-exit-manager.ts

@@ -127,7 +127,10 @@ export function createWorkflowExitManager(input: {
 			runWorkflowExitCleanups(selectedExit.reason);
 			throw selectedExit;
 		};
-		const rawOptions = options as Pick<WorkflowExitOptions, "status" | "reason" | "outputs"> | null | undefined;
+		const rawOptions = options as
+			| Pick<WorkflowExitOptions, "status" | "reason" | "resumable" | "outputs">
+			| null
+			| undefined;
 		let validationError: Error | undefined;
 		const captureValidationError = (error: Error): void => {
 			validationError ??= error;
@@ -141,7 +144,7 @@ export function createWorkflowExitManager(input: {
 		} else if (!isWorkflowExitStatus(rawStatus)) {
 			captureValidationError(
 				new TypeError(
-					`atomic-workflows: ctx.exit() status must be one of completed, skipped, cancelled, blocked; got ${describeWorkflowExitOptionValue(rawStatus)}`,
+					`atomic-workflows: ctx.exit() status must be one of completed, skipped, cancelled, blocked, failed; got ${describeWorkflowExitOptionValue(rawStatus)}`,
 				),
 			);
 		}
@@ -161,6 +164,26 @@ export function createWorkflowExitManager(input: {
 		}
 		const reason = typeof rawReason === "string" ? rawReason : undefined;
 
+		const resumableRead = readWorkflowExitOption(rawOptions, "resumable");
+		throwNestedSelectedExit();
+		const rawResumable = resumableRead.ok ? resumableRead.value : undefined;
+		if (!resumableRead.ok) {
+			captureValidationError(resumableRead.error);
+		} else if (rawResumable !== undefined && typeof rawResumable !== "boolean") {
+			captureValidationError(
+				new TypeError(
+					`atomic-workflows: ctx.exit() resumable must be a boolean when provided; got ${workflowSerializableTypeName(rawResumable)}`,
+				),
+			);
+		} else if (rawResumable !== undefined && rawStatus !== "failed") {
+			captureValidationError(
+				new TypeError(
+					`atomic-workflows: ctx.exit() resumable is only valid with status failed; got ${describeWorkflowExitOptionValue(rawStatus)}`,
+				),
+			);
+		}
+		const resumable = status === "failed" && rawResumable === true;
+
 		const outputsRead = readWorkflowExitOption(rawOptions, "outputs");
 		throwNestedSelectedExit();
 		const outputSnapshot = !outputsRead.ok
@@ -175,6 +198,7 @@ export function createWorkflowExitManager(input: {
 				scope: input.exitScope,
 				status,
 				...(reason !== undefined ? { reason } : {}),
+				...(status === "failed" ? { resumable } : {}),
 				...(outputSnapshot !== undefined ? { outputSnapshot } : {}),
 				...(validationError !== undefined ? { validationError } : {}),
 			}),

package/dist/builtin/workflows/src/runs/foreground/executor-run-finalizers.ts

@@ -81,8 +81,9 @@ export function createRunFinalizers(input: {
 			return finalizeWorkflowExitValidationFailure(err, signal.reason);
 		}
 
+		const resumable = signal.status === "failed" && signal.resumable === true;
 		const metadata = {
-			resumable: false,
+			resumable,
 			exited: true,
 			...(signal.reason !== undefined ? { exitReason: signal.reason } : {}),
 		} as const;
@@ -93,7 +94,7 @@ export function createRunFinalizers(input: {
 			result: outputs,
 			exited: true,
 			...(signal.reason !== undefined ? { exitReason: signal.reason } : {}),
-			resumable: false,
+			resumable,
 			ts: Date.now(),
 		});
 		return reconcileTerminalRunResult(