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

package/dist/builtin/workflows/src/durable/targeted-inspection.ts

@@ -0,0 +1,110 @@
+import { inspectRun, type RunDetail } from "../runs/background/run-inspect.js";
+import { createStore, type Store } from "../shared/store.js";
+import type { RunSnapshot } from "../shared/store-types.js";
+import type { DurableWorkflowBackend } from "./backend.js";
+import { durableWorkflowRunSnapshots } from "./completed-catalog.js";
+import { getAtomicExecutorId } from "./dbos-sdk-handle.js";
+import { isForeignLiveWorkflow, isLiveRunningWorkflow } from "./resume-eligibility.js";
+
+export type TargetedDurableInspection =
+	| {
+			readonly kind: "found";
+			readonly detail: RunDetail;
+			readonly runs: readonly RunSnapshot[];
+			readonly store: Store;
+	  }
+	| { readonly kind: "absent" | "deleted" | "malformed"; readonly message: string };
+
+/**
+ * Hydrate and reconstruct one exact durable root for inspection only.
+ *
+ * This path never claims ownership, changes durable status, starts execution,
+ * or restores snapshots into the current session store.
+ */
+export async function inspectTargetedDurableWorkflow(
+	backend: DurableWorkflowBackend,
+	workflowId: string,
+	now: number = Date.now(),
+): Promise<TargetedDurableInspection> {
+	const hydrated = backend.hydrateWorkflowForInspection
+		? await backend.hydrateWorkflowForInspection(workflowId)
+		: await hydrateWithoutClassification(backend, workflowId);
+	if (hydrated.kind !== "current") return hydrationFailure(workflowId, hydrated.kind);
+	const handle = hydrated.handle;
+	if (handle.rootWorkflowId !== undefined && handle.rootWorkflowId !== handle.workflowId) {
+		return malformed(workflowId, "the requested id belongs to a nested workflow rather than a durable root");
+	}
+	const reconstructed = durableWorkflowRunSnapshots(backend, handle);
+	if (reconstructed.length === 0)
+		return malformed(workflowId, "durable checkpoint topology is malformed or incomplete");
+	const runs = structuredClone(reconstructed);
+
+	const inspectionStore = createStore();
+	for (const run of runs) inspectionStore.recordRunStart(structuredClone(run));
+	const inspected = inspectRun(workflowId, { store: inspectionStore });
+	if (!inspected.ok) return malformed(workflowId, "the durable checkpoint graph has no reciprocal root");
+
+	const foreignLive = isForeignLiveWorkflow(handle, getAtomicExecutorId(), now);
+	const live = isLiveRunningWorkflow(handle, now);
+	const crashed = handle.status === "running" && !live;
+	const resumeGuidance = crashed
+		? inspected.detail.resumable === true
+			? `This workflow appears to have crashed and is resumable. Resume it explicitly with /workflow resume ${workflowId}.`
+			: "This workflow appears to have crashed, but its retained state is not resumable."
+		: foreignLive
+			? "This workflow is actively running in another Atomic session. Inspect it here, but control it from its owner session."
+			: live
+				? "This workflow still has a fresh durable heartbeat. Inspect it here without starting another executor."
+				: terminalGuidance(handle.status, workflowId, inspected.detail.resumable === true);
+	return {
+		kind: "found",
+		runs,
+		store: inspectionStore,
+		detail: {
+			...inspected.detail,
+			...(crashed ? { status: "crashed" as const } : {}),
+			...(live ? { resumable: false } : {}),
+			...(foreignLive ? { ownerActiveElsewhere: true } : {}),
+			resumeGuidance,
+		},
+	};
+}
+
+function terminalGuidance(status: string, workflowId: string, resumable: boolean): string {
+	if (resumable)
+		return `This retained workflow is ${status} and resumable. Resume it explicitly with /workflow resume ${workflowId}.`;
+	return `This retained workflow is ${status} and available for read-only inspection.`;
+}
+
+async function hydrateWithoutClassification(
+	backend: DurableWorkflowBackend,
+	workflowId: string,
+): Promise<import("./backend.js").DurableWorkflowHydrationResult> {
+	await backend.hydrateWorkflow(workflowId);
+	const handle = backend.getLoadableWorkflow(workflowId);
+	return handle === undefined ? { kind: "absent" } : { kind: "current", handle };
+}
+
+function hydrationFailure(
+	workflowId: string,
+	kind: Exclude<TargetedDurableInspection["kind"], "found">,
+): TargetedDurableInspection {
+	switch (kind) {
+		case "absent":
+			return {
+				kind,
+				message: `Run not found: ${workflowId} (not present in the current session or durable store).`,
+			};
+		case "deleted":
+			return { kind, message: `Durable workflow was deleted: ${workflowId}` };
+		case "malformed":
+			return malformed(workflowId, "current DBOS metadata or checkpoints are malformed");
+	}
+}
+
+function malformed(workflowId: string, reason: string): TargetedDurableInspection {
+	return {
+		kind: "malformed",
+		message: `Durable workflow ${workflowId} cannot be inspected safely: ${reason}.`,
+	};
+}

package/dist/builtin/workflows/src/durable/types.ts

@@ -61,6 +61,10 @@ export interface DurableWorkflowHandle {
 	readonly rootWorkflowId?: string;
 	/** Explicit resumability flag for failed/blocked runs. */
 	readonly resumable?: boolean;
+	/** True when the terminal status came from an author-selected ctx.exit(). */
+	readonly exited?: boolean;
+	/** Author-supplied reason from ctx.exit(), when present. */
+	readonly exitReason?: string;
 	readonly error?: string;
 	readonly failureKind?: WorkflowFailureKind;
 	readonly failureCode?: WorkflowFailureCode;
@@ -278,6 +282,10 @@ export interface DurableWorkflowMetadata {
 	readonly failedToolNodeId?: string;
 	readonly rootWorkflowId?: string;
 	readonly resumable?: boolean;
+	/** True when the terminal status came from an author-selected ctx.exit(). */
+	readonly exited?: boolean;
+	/** Author-supplied reason from ctx.exit(), when present. */
+	readonly exitReason?: string;
 	readonly invocationCwd?: string;
 	readonly origin?: WorkflowActor;
 	readonly workflowCwd?: string;
@@ -304,6 +312,10 @@ export interface ResumableWorkflowEntry {
 	readonly failedToolNodeId?: string;
 	readonly rootWorkflowId?: string;
 	readonly resumable?: boolean;
+	/** True when the terminal status came from an author-selected ctx.exit(). */
+	readonly exited?: boolean;
+	/** Author-supplied reason from ctx.exit(), when present. */
+	readonly exitReason?: string;
 	readonly invocationCwd?: string;
 	readonly origin?: WorkflowActor;
 	readonly workflowCwd?: string;
@@ -314,7 +326,11 @@ export interface ResumableWorkflowEntry {
 }
 
 export interface DurableWorkflowFailureMetadata {
-	readonly error: string;
+	readonly error?: string;
+	/** True when the terminal status came from an author-selected ctx.exit(). */
+	readonly exited?: boolean;
+	/** Author-supplied reason from ctx.exit(), when present. */
+	readonly exitReason?: string;
 	readonly failureKind?: WorkflowFailureKind;
 	readonly failureCode?: WorkflowFailureCode;
 	readonly failureRecoverability?: WorkflowFailureRecoverability;

package/dist/builtin/workflows/src/durable/workflow-child-result.ts

@@ -49,7 +49,9 @@ export function isWorkflowChildResult(
 }
 
 function isWorkflowExitStatus(value: WorkflowSerializableValue | undefined): value is WorkflowExitStatus {
-	return value === "completed" || value === "skipped" || value === "cancelled" || value === "blocked";
+	return (
+		value === "completed" || value === "skipped" || value === "cancelled" || value === "blocked" || value === "failed"
+	);
 }
 
 function isOrdinaryObject(

package/dist/builtin/workflows/src/engine/primitives/workflow.ts

@@ -143,7 +143,7 @@ export function createChildWorkflowRunner(input: {
 			) {
 				throw new WorkflowGracefulQuitError(childRunId, `child workflow "${childName}" (${child.name})`);
 			}
-			if (!isWorkflowExitStatus(childRun.status)) {
+			if (!isWorkflowExitStatus(childRun.status) || (childRun.status === "failed" && childRun.exited !== true)) {
 				const failedChildStage = childRun.stages.find((stage) => stage.failureKind !== undefined);
 				throw new Error(
 					`atomic-workflows: child workflow "${childName}" (${child.name}) failed with status ${childRun.status}${childRun.error !== undefined ? `: ${childRun.error}` : ""}`,

package/dist/builtin/workflows/src/engine/run-durable-finalize.ts

@@ -40,9 +40,17 @@ export async function finalizeDurableTerminalStatus(input: DurableTerminalFinali
 			recordRunTimingCheckpoint(input.durableBackend, input.runSnapshot);
 		}
 		const failure =
-			durableStatus === "failed" && input.runSnapshot.error !== undefined
+			durableStatus === "failed"
 				? {
-						error: input.runSnapshot.error,
+						...(input.runSnapshot.error !== undefined ? { error: input.runSnapshot.error } : {}),
+						...(input.runSnapshot.exited === true
+							? {
+									exited: true,
+									...(input.runSnapshot.exitReason !== undefined
+										? { exitReason: input.runSnapshot.exitReason }
+										: {}),
+								}
+							: {}),
 						...(input.runSnapshot.failureKind !== undefined
 							? { failureKind: input.runSnapshot.failureKind }
 							: {}),

package/dist/builtin/workflows/src/engine/run-durable-stage-session.ts

@@ -1,4 +1,4 @@
-import { recordRunTimingCheckpoint } from "../durable/run-timing.js";
+import { recordRunTimingCheckpointAsync } from "../durable/run-timing.js";
 import { type DurableStageDeps, recordStageSessionCheckpoint } from "../durable/stage-primitive.js";
 import type { StageSessionCheckpointOptions } from "../runs/foreground/executor-types.js";
 import type { RunSnapshot, StageSnapshot } from "../shared/store-types.js";
@@ -27,7 +27,7 @@ export function createDurableStageSessionRecorder(
 		if (stageRunId === input.runId) {
 			await recordStageSessionCheckpoint(input.deps, snapshot, { force: options?.forceDurable === true });
 			if (input.runSnapshot !== undefined) {
-				recordRunTimingCheckpoint(input.deps.backend, input.runSnapshot, {
+				await recordRunTimingCheckpointAsync(input.deps.backend, input.runSnapshot, {
 					debounce: options?.forceDurable !== true,
 				});
 			}

package/dist/builtin/workflows/src/engine/run-durable-topology.ts

@@ -238,6 +238,7 @@ export function reconcileCachedDirectChildParentStage(input: {
 	readonly boundary: StageSnapshot;
 }): boolean {
 	const existingRun = input.store.runs().find((run) => run.id === input.checkpointChildRunId);
+	if (existingRun === undefined) return false;
 	const runById = new Map(input.store.runs().map((run) => [run.id, run]));
 	const storedParentRun = runById.get(input.parentRun.id);
 	if (
@@ -250,6 +251,13 @@ export function reconcileCachedDirectChildParentStage(input: {
 	const expectedRootRunId = reciprocalWorkflowRootRunId(runById, input.parentRun.id);
 	if (expectedRootRunId === undefined) return false;
 	const storedBoundary = storedParentRun?.stages.find((stage) => stage.id === input.boundary.id);
+	const cachedChildStatusMatches =
+		(existingRun?.status === "completed" && input.catalogRun.status === "completed") ||
+		(input.boundary.workflowChild?.exited === true &&
+			input.boundary.workflowChild.runId === input.checkpointChildRunId &&
+			existingRun?.status === input.catalogRun.status &&
+			input.boundary.workflowChild.status === input.catalogRun.status);
+
 	if (
 		!rootMatches(input.parentRun.rootRunId, expectedRootRunId) ||
 		!rootMatches(storedParentRun?.rootRunId, expectedRootRunId) ||
@@ -257,8 +265,7 @@ export function reconcileCachedDirectChildParentStage(input: {
 		(storedParentRun !== undefined &&
 			authoritativeWorkflowChildRunId(storedBoundary) !== input.checkpointChildRunId) ||
 		input.catalogRun.id !== input.checkpointChildRunId ||
-		existingRun?.status !== "completed" ||
-		input.catalogRun.status !== "completed" ||
+		!cachedChildStatusMatches ||
 		existingRun.parentRunId !== input.parentRun.id ||
 		input.catalogRun.parentRunId !== input.parentRun.id ||
 		input.catalogRun.parentStageId === undefined ||

package/dist/builtin/workflows/src/engine/runtime.ts

@@ -180,8 +180,25 @@ export class EngineRuntime {
 		return {
 			apply: () => {
 				if (!this.childRunOptions.mcp || !hasScope) return;
-				if (depth === 0) this.childRunOptions.mcp.setScope(stageId, allow, deny);
-				depth += 1;
+				if (depth > 0) {
+					depth += 1;
+					return;
+				}
+				depth = 1;
+				try {
+					this.childRunOptions.mcp.setScope(stageId, allow, deny);
+				} catch (error) {
+					depth = 0;
+					try {
+						this.childRunOptions.mcp.clearScope(stageId);
+					} catch (cleanupError) {
+						throw new AggregateError(
+							[error, cleanupError],
+							"MCP scope setup failed and compensating cleanup failed",
+						);
+					}
+					throw error;
+				}
 			},
 			clear: () => {
 				if (!this.childRunOptions.mcp || !hasScope) return;

package/dist/builtin/workflows/src/extension/atomic-stage-session.ts

@@ -49,9 +49,15 @@ export interface PrepareAtomicStageSessionOptions {
 	resourceLoaderInheritanceSnapshot?: DefaultResourceLoaderInheritanceSnapshot;
 	onSettingsManager?: (settingsManager: PiSdkSettingsManager) => void;
 }
+/**
+ * Workflow stages are top-level sessions that carry a policy object; they are
+ * not subagent children. They keep full management and are authorized to
+ * delegate, as `packages/coding-agent/docs/workflows.md` documents. Nesting
+ * stays bounded by the depth guard in the subagent executor.
+ */
 const WORKFLOW_STAGE_SUBAGENT_POLICY: SubagentChildPolicy = {
 	managementActions: "full",
-	fanoutAuthorized: false,
+	fanoutAuthorized: true,
 	inheritProjectContext: true,
 	inheritSkills: true,
 };

package/dist/builtin/workflows/src/extension/companions.ts

@@ -65,7 +65,7 @@ export const COMPANIONS: readonly CompanionSpec[] = [
 		installSpec: "npm:pi-subagents",
 		purpose: "delegate stages to focused child agents",
 		pathHints: ["/pi-subagents/", "/pi-subagents-", "/pi-subagents."],
-		commandHints: ["subagents-doctor", "run", "chain", "parallel", "run-chain"],
+		commandHints: ["subagents-doctor", "run", "parallel"],
 		toolHints: ["subagent"],
 	},
 	{

package/dist/builtin/workflows/src/extension/extension-runtime-state.ts

@@ -159,6 +159,9 @@ export function createWorkflowExtensionRuntimeState(
 		resumeDurableWorkflow(workflowId, options) {
 			return runtimeRef.current.resumeDurableWorkflow(workflowId, options);
 		},
+		inspectDurableWorkflow(workflowId) {
+			return runtimeRef.current.inspectDurableWorkflow(workflowId);
+		},
 		listDurableResumable() {
 			return runtimeRef.current.listDurableResumable();
 		},