@bastani/atomic 0.9.14-alpha.3 → 0.9.14-alpha.5

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

@@ -62,6 +62,7 @@ export function createChildWorkflowRunner(input: {
 			throw new Error(workflowDefinitionRequirementMessage("ctx.workflow(definition)", child));
 		const childName = child.normalizedName;
 		const boundaryName = options.stageName ?? `workflow:${childName}`;
+		if (runtime.budget.enabled) await runtime.budget.stopAtBoundaryAsync(boundaryName);
 		const boundaryReplayKey = input.nextWorkflowBoundaryReplayKey(boundaryName);
 		const durableInvocation = input.consumeDurableInvocation?.();
 		const boundary = runtime.spawnStage(boundaryName, {
@@ -127,11 +128,14 @@ export function createChildWorkflowRunner(input: {
 					rootRunId: runtime.parentRootRunId ?? runtime.runId,
 				},
 				signal: childController.signal,
+				budget: options.budget,
+				rootBudget: runtime.rootBudget,
 				deferWorkflowStart: false,
 				...(durableInvocation !== undefined ? { durableScope: durableInvocation.scope } : {}),
 			});
 			boundary.observeChildRun(childRunPromise);
 			const childRun = await childRunPromise;
+			if (runtime.budget.enabled) await runtime.budget.stopAtBoundaryAsync(boundaryName);
 			runtime.exit.throwIfWorkflowExitSelected();
 
 			// A gracefully quit child is a suspension, not a child failure: carry the
@@ -143,7 +147,12 @@ export function createChildWorkflowRunner(input: {
 			) {
 				throw new WorkflowGracefulQuitError(childRunId, `child workflow "${childName}" (${child.name})`);
 			}
-			if (!isWorkflowExitStatus(childRun.status) || (childRun.status === "failed" && childRun.exited !== true)) {
+			const childBudgetExceeded = childRun.result?.status === "budget_exceeded";
+			const childExitStatus = isWorkflowExitStatus(childRun.status) ? childRun.status : "blocked";
+			if (
+				(!isWorkflowExitStatus(childRun.status) && !childBudgetExceeded) ||
+				(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}` : ""}`,
@@ -159,12 +168,12 @@ export function createChildWorkflowRunner(input: {
 			}
 
 			const outputs = selectWorkflowOutputs(child, childRun.result);
-			const childExited = childRun.exited === true || childRun.status !== "completed";
+			const childExited = childBudgetExceeded || childRun.exited === true || childRun.status !== "completed";
 			const childResult: WorkflowChildResult<TChildOutputs> = childExited
 				? {
 						workflow: child.normalizedName,
 						runId: childRun.runId,
-						status: childRun.status,
+						status: childBudgetExceeded ? "blocked" : childExitStatus,
 						exited: true,
 						outputs: outputs as Partial<TChildOutputs>,
 						...(childRun.exitReason !== undefined ? { exitReason: childRun.exitReason } : {}),

package/dist/builtin/workflows/src/engine/run-budget.ts

@@ -0,0 +1,308 @@
+import {
+	type BudgetReport,
+	type EffectiveBudget,
+	enforceDurationBudget,
+	enforceUsageBudget,
+} from "../shared/budget.js";
+import { meter_run, type RunMeters, type RunUsageTree } from "../shared/budget-meter.js";
+import type { RunBudgetAccountingState, RunBudgetState, RunSnapshot } from "../shared/store-types.js";
+import { elapsedRunMs } from "../shared/timing.js";
+import type { WorkflowModelUsage } from "../shared/types.js";
+export const BUDGET_WRAP_UP_PROMPT =
+	"The workflow budget is exhausted. Stop substantive work, summarize useful progress, identify remaining work or blockers, and leave a clear next step. Do not start any new stages.";
+export interface BudgetExceededReport extends BudgetReport {
+	readonly frontierStage: string;
+	readonly wrapUpSummary?: string;
+	readonly wrapUpUsage?: WorkflowModelUsage;
+}
+export class WorkflowBudgetExceededError extends Error {
+	readonly report: BudgetExceededReport;
+	constructor(report: BudgetExceededReport) {
+		const unit = report.dimension === "duration" ? "ms" : report.dimension;
+		super(
+			`atomic-workflows: ${report.dimension} budget exceeded (${report.reading}${unit} / ${report.ceiling}${unit}) at ${report.frontierStage}`,
+		);
+		this.name = "WorkflowBudgetExceededError";
+		this.report = report;
+	}
+}
+export interface BudgetCheckpointContinue {
+	readonly kind: "continue";
+}
+export interface BudgetCheckpointWarning {
+	readonly kind: "warn";
+	readonly report: BudgetReport;
+}
+export interface BudgetCheckpointWrapUp {
+	readonly kind: "wrap_up";
+	readonly report: BudgetReport;
+}
+export interface BudgetCheckpointExhausted {
+	readonly kind: "exhausted";
+	readonly report: BudgetExceededReport;
+}
+export type BudgetCheckpoint =
+	| BudgetCheckpointContinue
+	| BudgetCheckpointWarning
+	| BudgetCheckpointWrapUp
+	| BudgetCheckpointExhausted;
+export interface RunBudgetController {
+	readonly enabled: boolean;
+	readonly checkpoint: (frontierStage?: string) => BudgetCheckpoint;
+	readonly registerWrapUp: (frontierStage: string, handler: () => Promise<never>) => () => void;
+	readonly deliverWrapUp: (frontierStage: string) => Promise<never>;
+	readonly finishWrapUp: (
+		frontierStage: string | undefined,
+		summary?: string,
+		usage?: WorkflowModelUsage,
+		delivered?: boolean,
+	) => WorkflowBudgetExceededError;
+	readonly rethrowIfSystemOwnedStop: (frontierStage?: string) => void;
+	readonly stopAtBoundary: (frontierStage?: string) => void;
+	readonly stopAtBoundaryAsync: (frontierStage?: string) => Promise<void>;
+	readonly awaitPendingWrapUp: () => Promise<WorkflowBudgetExceededError | undefined>;
+}
+const withFrontier = (
+	report: BudgetReport,
+	frontierStage: string | undefined,
+	summary?: string,
+	usage?: WorkflowModelUsage,
+): BudgetExceededReport =>
+	Object.assign(
+		{ ...report, frontierStage: frontierStage ?? "workflow frontier" },
+		summary === undefined ? {} : { wrapUpSummary: summary },
+		usage === undefined ? {} : { wrapUpUsage: usage },
+	);
+const usageFields = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const,
+	counterFields = ["input", "output", "cacheRead", "cacheWrite"] as const;
+const mapFields = <F extends string>(fields: readonly F[], fn: (field: F) => number = () => 0): Record<F, number> =>
+	Object.fromEntries(fields.map((field) => [field, fn(field)])) as Record<F, number>;
+export function createRunBudgetController(input: {
+	readonly run: RunSnapshot;
+	readonly budget: EffectiveBudget;
+	readonly usageTree?: () => RunUsageTree;
+	readonly onWarning?: (report: BudgetReport) => void;
+	readonly rootBudget?: RunBudgetController;
+}) {
+	const { run, budget } = input;
+	const ownEnabled = budget.maxDurationMs > 0 || budget.maxTokens > 0 || budget.maxCost > 0;
+	const usageEnabled = budget.maxTokens > 0 || budget.maxCost > 0;
+	const root = input.rootBudget?.enabled === true ? input.rootBudget : undefined;
+	const enabled = ownEnabled || root !== undefined;
+	let state: RunBudgetState | undefined = run.budgetState === undefined ? undefined : { ...run.budgetState };
+	const previousAccounting = state?.accounting;
+	const initial =
+		previousAccounting && usageEnabled ? meter_run(input.usageTree?.() ?? { run }, Date.now()) : undefined;
+	const initialAccounting = initial === undefined ? undefined : { ...initial.perCounter, cost: initial.cost };
+	let baseline = mapFields(usageFields, (field) => initialAccounting?.[field] ?? 0);
+	let charged: RunBudgetAccountingState = {
+		baseline,
+		tokens: previousAccounting?.tokens ?? 0,
+		cost: previousAccounting?.cost ?? 0,
+		perCounter: { ...(previousAccounting?.perCounter ?? mapFields(counterFields)) },
+	};
+	let exhaustedReport: BudgetReport | undefined;
+	let lastReports: readonly BudgetReport[] = [];
+	let wrapUpPromise: Promise<never> | undefined;
+	let rootWrapUpPending = false;
+	const handlers: Array<{ readonly frontierStage: string; readonly handler: () => Promise<never> }> = [];
+	const updateState = (patch: Partial<RunBudgetState>): void => {
+		state = { ...(state ?? {}), ...patch };
+		run.budgetState = state;
+	};
+	const accountUsage = (meters: RunMeters): RunMeters => {
+		const current = { ...meters.perCounter, cost: meters.cost };
+		const delta = mapFields(usageFields, (field) => Math.max(0, current[field] - baseline[field]));
+		baseline = mapFields(usageFields, (field) => Math.max(baseline[field], current[field]));
+		charged = {
+			baseline,
+			tokens: charged.tokens + delta.input + delta.output,
+			cost: charged.cost + delta.cost,
+			perCounter: mapFields(counterFields, (field) => charged.perCounter[field] + delta[field]),
+		};
+		updateState({ accounting: charged });
+		return Object.assign(meters, { tokens: charged.tokens, cost: charged.cost, perCounter: charged.perCounter });
+	};
+	const measure = (): RunMeters => {
+		const durationMs = elapsedRunMs(run);
+		if (!usageEnabled) return { durationMs, tokens: 0, cost: 0, perCounter: mapFields(counterFields) };
+		return { ...accountUsage(meter_run(input.usageTree?.() ?? { run }, Date.now())), durationMs };
+	};
+	const warningWasSent = (report: BudgetReport): boolean =>
+		report.dimension === "duration" ? state?.warned === true : state?.warnings?.[report.dimension] !== undefined;
+	const recordWarning = (report: BudgetReport): void => {
+		updateState({
+			...(report.dimension === "duration" ? { warned: true } : {}),
+			warning: report,
+			warnings: { ...(state?.warnings ?? {}), [report.dimension]: report },
+		});
+		input.onWarning?.(report);
+	};
+	const ceilings = { duration: budget.maxDurationMs, tokens: budget.maxTokens, cost: budget.maxCost };
+	const setReports = (reports: readonly BudgetReport[]): void => {
+		for (const report of reports) {
+			if (ceilings[report.dimension] <= 0) continue;
+			updateState({ [report.dimension]: report } as Partial<RunBudgetState>);
+		}
+	};
+	const finishWrapUp = (
+		frontierStage: string | undefined,
+		summary?: string,
+		usage?: WorkflowModelUsage,
+		delivered = true,
+	): WorkflowBudgetExceededError => {
+		updateState({
+			systemOwnedStop: true,
+			...(delivered ? { wrapUpDelivered: true, wrapUpCompleted: true } : {}),
+			...(delivered && summary !== undefined ? { wrapUpSummary: summary } : {}),
+			...(delivered && usage !== undefined ? { wrapUpUsage: usage } : {}),
+		});
+		const report =
+			exhaustedReport ??
+			lastReports[0] ??
+			state?.duration ??
+			state?.tokens ??
+			state?.cost ??
+			enforceDurationBudget(elapsedRunMs(run), budget).report;
+		setReports([report]);
+		return new WorkflowBudgetExceededError(
+			withFrontier(report, frontierStage, state?.wrapUpSummary, state?.wrapUpUsage),
+		);
+	};
+	const ownCheckpoint = (frontierStage?: string): BudgetCheckpoint => {
+		const usageCheck = (dimension: "tokens" | "cost", reading: number, ceiling: number, warned: boolean) =>
+			ceiling > 0 ? enforceUsageBudget(dimension, reading, ceiling, budget.warnAtPercent, { warned }) : undefined;
+		if (!ownEnabled) return { kind: "continue" };
+		const meters = measure();
+		const checks = [
+			enforceDurationBudget(meters.durationMs, budget, { warned: state?.warned }),
+			usageCheck("tokens", meters.tokens, budget.maxTokens, state?.warnings?.tokens !== undefined),
+			usageCheck("cost", meters.cost, budget.maxCost, state?.warnings?.cost !== undefined),
+		].filter((check): check is Exclude<typeof check, undefined> => check !== undefined);
+		lastReports = checks.map((check) => check.report);
+		setReports(lastReports);
+		let warning: BudgetReport | undefined;
+		for (const check of checks)
+			if (check.kind === "continue" && check.warning && !warningWasSent(check.report)) {
+				warning ??= check.report;
+				recordWarning(check.report);
+			}
+		const exhausted = checks.find((check) => check.kind === "exhausted");
+		if (exhausted === undefined)
+			return warning === undefined ? { kind: "continue" } : { kind: "warn", report: warning };
+		exhaustedReport ??= exhausted.report;
+		if (state?.wrapUpCompleted !== true) return { kind: "wrap_up", report: exhausted.report };
+		return {
+			kind: "exhausted",
+			report: withFrontier(exhaustedReport, frontierStage, state.wrapUpSummary, state.wrapUpUsage),
+		};
+	};
+	const boundaryCheckpoint = (
+		frontierStage?: string,
+	): { readonly check: BudgetCheckpoint; readonly owner?: RunBudgetController } => {
+		const rootCheck = root?.checkpoint(frontierStage);
+		if (rootCheck?.kind === "wrap_up") rootWrapUpPending = true;
+		if (rootCheck?.kind === "wrap_up" || rootCheck?.kind === "exhausted") return { check: rootCheck, owner: root };
+		return { check: ownCheckpoint(frontierStage) };
+	};
+	const checkpoint = (frontierStage?: string): BudgetCheckpoint => boundaryCheckpoint(frontierStage).check;
+	const finishBoundary = (owner: RunBudgetController | undefined, frontierStage: string | undefined): never => {
+		throw (
+			owner?.finishWrapUp(frontierStage, undefined, undefined, false) ??
+			finishWrapUp(frontierStage, undefined, undefined, false)
+		);
+	};
+	const deliverBoundary = (owner: RunBudgetController | undefined, frontierStage: string): void => {
+		void (owner?.deliverWrapUp(frontierStage) ?? deliverWrapUp(frontierStage));
+	};
+	const stopAtBoundary = (frontierStage?: string): void => {
+		const resolvedFrontierStage = frontierStage ?? handlers.at(-1)?.frontierStage;
+		const { check, owner } = boundaryCheckpoint(resolvedFrontierStage);
+		if (check.kind === "wrap_up") {
+			deliverBoundary(owner, resolvedFrontierStage ?? "workflow frontier");
+			finishBoundary(owner, resolvedFrontierStage);
+		}
+		if (check.kind === "exhausted") finishBoundary(owner, resolvedFrontierStage);
+	};
+	const rethrowIfSystemOwnedStop = (frontierStage?: string): void => {
+		root?.rethrowIfSystemOwnedStop(frontierStage);
+		if (state?.systemOwnedStop === true)
+			throw finishWrapUp(frontierStage, state.wrapUpSummary, state.wrapUpUsage, state.wrapUpCompleted === true);
+	};
+	const registerLocalWrapUp = (registration: {
+		readonly frontierStage: string;
+		readonly handler: () => Promise<never>;
+	}): (() => void) => {
+		handlers.push(registration);
+		return () => {
+			const index = handlers.indexOf(registration);
+			if (index >= 0) handlers.splice(index, 1);
+		};
+	};
+	const registerWrapUp = (frontierStage: string, handler: () => Promise<never>): (() => void) => {
+		const registration = { frontierStage, handler };
+		const unregisterOwn = ownEnabled ? registerLocalWrapUp(registration) : undefined;
+		const unregisterRoot = root
+			? root.registerWrapUp(frontierStage, async () => {
+					try {
+						return await handler();
+					} catch (error) {
+						if (!(error instanceof WorkflowBudgetExceededError)) throw error;
+						throw root.finishWrapUp(
+							error.report.frontierStage,
+							error.report.wrapUpSummary,
+							error.report.wrapUpUsage,
+							error.report.wrapUpSummary !== undefined,
+						);
+					}
+				})
+			: undefined;
+		return () => {
+			unregisterOwn?.();
+			unregisterRoot?.();
+		};
+	};
+	const deliverWrapUp = (frontierStage: string): Promise<never> => {
+		if (wrapUpPromise !== undefined) return wrapUpPromise;
+		if (rootWrapUpPending && root !== undefined) return root.deliverWrapUp(frontierStage);
+		if (state?.systemOwnedStop === true && state.wrapUpCompleted !== true)
+			throw finishWrapUp(frontierStage, undefined, undefined, false);
+		const registration = handlers.findLast((entry) => entry.frontierStage === frontierStage) ?? handlers.at(-1);
+		if (registration === undefined) throw finishWrapUp(frontierStage, undefined, undefined, false);
+		wrapUpPromise = registration.handler();
+		return wrapUpPromise;
+	};
+	const stopAtBoundaryAsync = async (frontierStage?: string): Promise<void> => {
+		if (root !== undefined) await root.stopAtBoundaryAsync(frontierStage);
+		const check = ownCheckpoint(frontierStage);
+		if (check.kind === "continue" || check.kind === "warn") return;
+		if (check.kind === "wrap_up") {
+			await deliverWrapUp(frontierStage ?? "workflow frontier");
+			return;
+		}
+		throw finishWrapUp(frontierStage, state?.wrapUpSummary, state?.wrapUpUsage, state?.wrapUpCompleted === true);
+	};
+	const awaitPendingWrapUp = async (): Promise<WorkflowBudgetExceededError | undefined> => {
+		const rootError = await root?.awaitPendingWrapUp();
+		if (rootError !== undefined) return rootError;
+		if (wrapUpPromise === undefined) return undefined;
+		try {
+			await wrapUpPromise;
+		} catch (error) {
+			if (error instanceof WorkflowBudgetExceededError) return error;
+			throw error;
+		}
+		return undefined;
+	};
+	return {
+		enabled,
+		checkpoint,
+		registerWrapUp,
+		deliverWrapUp,
+		finishWrapUp,
+		rethrowIfSystemOwnedStop,
+		stopAtBoundary,
+		stopAtBoundaryAsync,
+		awaitPendingWrapUp,
+	};
+}

package/dist/builtin/workflows/src/engine/run-returned-status.ts

@@ -28,6 +28,14 @@ export function classifyReturnedRunStatus(
 		};
 	}
 	const returnedStatus = normalizeReturnedWorkflowStatus(result?.status);
+	if (
+		returnedStatus === "budget_exceeded" &&
+		(runSnapshot?.budgetState?.wrapUpCompleted !== true ||
+			runSnapshot.failureDisposition !== "active_blocked" ||
+			runSnapshot.failureRecoverability !== "recoverable")
+	)
+		// Only the system-owned budget door may produce this status.
+		return { status: "completed" };
 	if (returnedStatus === undefined || returnedStatus === "completed" || returnedStatus === "complete") {
 		return { status: "completed" };
 	}

package/dist/builtin/workflows/src/engine/run-tool-node-lifecycle.ts

@@ -5,6 +5,7 @@ import type { Store } from "../shared/store.js";
 import type { RunSnapshot, ToolNodeSnapshot } from "../shared/store-types.js";
 import type { WorkflowToolPrimitive } from "../shared/types.js";
 import type { GraphFrontierTracker } from "./graph-inference.js";
+import type { RunBudgetController } from "./run-budget.js";
 import { durableRunTopology } from "./run-durable-topology.js";
 import type { RunTerminalEventArbiter } from "./run-terminal-event.js";
 import type { ToolAdmissionBoundary } from "./run-tool-admission-boundary.js";
@@ -71,6 +72,7 @@ export function createTrackedToolPrimitive(input: {
 	readonly sourceToReplayedNodeIds: Map<string, string>;
 	readonly toolControls: ToolControlRegistry;
 	readonly toolAdmission: ToolAdmissionBoundary;
+	readonly budget: RunBudgetController;
 }): {
 	readonly tool: WorkflowToolPrimitive;
 	readonly admittedTools: AdmittedToolExecutionTracker;
@@ -96,6 +98,9 @@ export function createTrackedToolPrimitive(input: {
 		},
 	});
 	const lifecycle = createToolNodeLifecycle(input);
+	const budgetBoundary = input.budget.enabled
+		? (): Promise<void> => input.budget.stopAtBoundaryAsync(input.run.stages.at(-1)?.name)
+		: undefined;
 	const tool = createToolPrimitive({
 		workflowId: input.workflowId,
 		backend: input.backend,
@@ -128,6 +133,7 @@ export function createTrackedToolPrimitive(input: {
 			if (!admission.accepted) observedQuit ??= admission.error;
 			return admission;
 		},
+		...(budgetBoundary !== undefined ? { beforeToolCall: budgetBoundary, afterToolCall: budgetBoundary } : {}),
 		...lifecycle,
 	});
 	const abandonInFlightAsCancelled = (reason: unknown): readonly string[] => {

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

@@ -2,7 +2,7 @@ import type { DurableWorkflowBackend } from "../durable/backend.js";
 import type { DurableChildInvocation } from "../durable/boundary-topology.js";
 import { createDurableChildWorkflowPrimitive } from "../durable/child-primitive.js";
 import { getDurableBackend } from "../durable/factory.js";
-import { inheritedRunElapsedMs, recordRunTimingCheckpoint } from "../durable/run-timing.js";
+import { inheritedRunElapsedMs, priorRunAccounting, recordRunTimingCheckpoint } from "../durable/run-timing.js";
 import { ScopedDurableBackend } from "../durable/scoped-backend.js";
 import {
 	createDurableStagePrimitive,
@@ -47,6 +47,8 @@ import { createStageScheduler } from "../runs/foreground/executor-scheduler.js";
 import type { RunOpts, RunResult } from "../runs/foreground/executor-types.js";
 import { stageControlRegistry as defaultStageControlRegistry } from "../runs/foreground/stage-control-registry.js";
 import { createRunLimiter } from "../runs/shared/concurrency.js";
+import { resolve_budget, type WorkflowBudget } from "../shared/budget.js";
+import type { RunUsageTree } from "../shared/budget-meter.js";
 import { appendRunStart } from "../shared/persistence-session-entries.js";
 import { store as defaultStore } from "../shared/store.js";
 import type { RunSnapshot } from "../shared/store-types.js";
@@ -67,6 +69,7 @@ import { createWorkflowTaskRunners } from "./primitives/task.js";
 import { buildExitGatedUiContext } from "./primitives/ui.js";
 import { createChildWorkflowRunner } from "./primitives/workflow.js";
 import { createContinuationReplayIndex } from "./replay.js";
+import { createRunBudgetController, WorkflowBudgetExceededError } from "./run-budget.js";
 import { admitDurableRootRun, durableRootRegistrationForRun } from "./run-durable-admission.js";
 import { finalizeDurableTerminalStatus } from "./run-durable-finalize.js";
 import { createDurableStageSessionRecorder } from "./run-durable-stage-session.js";
@@ -130,6 +133,23 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 
 	const resolvedInputs = resolveAndValidateInputs(def.inputs, inputs, `workflow "${def.name}"`);
 	const runId = opts.runId ?? crypto.randomUUID();
+	// A budget OBJECT is always materialized by the shipped config defaults, so
+	// presence proves nothing. A positive limit on any dimension means this run
+	// is budgeted; otherwise take the unbudgeted path untouched (R10).
+	const declaresBudget = (budget: WorkflowBudget | undefined): boolean =>
+		(budget?.maxDurationMs ?? 0) > 0 || (budget?.maxTokens ?? 0) > 0 || (budget?.maxCost ?? 0) > 0;
+	const hasBudgetDeclaration =
+		declaresBudget(opts.budget) || declaresBudget(def.budget) || declaresBudget(opts.config?.budget);
+	const priorRun =
+		hasBudgetDeclaration &&
+		opts.rootBudget === undefined &&
+		opts.continuation === undefined &&
+		opts.runId !== undefined
+			? activeStore.runs().find((candidate) => candidate.id === runId)
+			: undefined;
+	const continuedBudget = opts.continuation?.source.budget ?? priorRun?.budget;
+	const runBudget = opts.budget === undefined ? continuedBudget : { ...(continuedBudget ?? {}), ...opts.budget };
+	const resolvedBudget = resolve_budget({ config: opts.config?.budget, definition: def.budget, run: runBudget });
 	const exitScope = Symbol(`workflow-exit:${runId}`);
 	const ownController = new AbortController();
 	const terminalEvents = createRunTerminalEventArbiter(runId);
@@ -165,6 +185,39 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 			? inheritedRunElapsedMs({ backend: durableBackend, runId, continuationSource: opts.continuation?.source })
 			: undefined;
 	const continuationOrigin = opts.continuation !== undefined ? opts.continuation.source.origin : opts.origin;
+	const snapshotField = (field: "maxTokens" | "maxCost"): number | undefined =>
+		resolvedBudget[field] > 0 || opts.budget?.[field] !== undefined || def.budget?.[field] !== undefined
+			? resolvedBudget[field]
+			: undefined;
+	const budgetSnapshot =
+		resolvedBudget.maxDurationMs > 0 || resolvedBudget.maxTokens > 0 || resolvedBudget.maxCost > 0
+			? {
+					maxDurationMs: resolvedBudget.maxDurationMs,
+					...(snapshotField("maxTokens") !== undefined ? { maxTokens: snapshotField("maxTokens") } : {}),
+					...(snapshotField("maxCost") !== undefined ? { maxCost: snapshotField("maxCost") } : {}),
+					warnAtPercent: resolvedBudget.warnAtPercent,
+				}
+			: undefined;
+	const durableAccounting =
+		hasBudgetDeclaration && opts.parentRun === undefined && opts.continuation === undefined && priorRun === undefined
+			? priorRunAccounting(durableBackend, runId)
+			: undefined;
+	const continuedBudgetState =
+		opts.continuation?.source.budgetState ??
+		priorRun?.budgetState ??
+		(durableAccounting === undefined ? undefined : { accounting: durableAccounting });
+	const sameBudget =
+		budgetSnapshot !== undefined &&
+		continuedBudget?.warnAtPercent === budgetSnapshot.warnAtPercent &&
+		(["maxDurationMs", "maxTokens", "maxCost"] as const).every(
+			(field) => (continuedBudget?.[field] ?? 0) === (budgetSnapshot[field] ?? 0),
+		);
+	const continuationBudgetState =
+		continuedBudgetState === undefined || (!sameBudget && continuedBudgetState.accounting === undefined)
+			? undefined
+			: sameBudget
+				? continuedBudgetState
+				: { accounting: continuedBudgetState.accounting };
 	const runSnapshot: RunSnapshot = {
 		id: runId,
 		name: def.name,
@@ -183,7 +236,9 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 		...(opts.continuation !== undefined
 			? {
 					resumedFromRunId: opts.continuation.source.id,
-					resumeFromStageId: opts.continuation.resumeFromStageId,
+					...(opts.continuation.resumeFromStageId !== undefined
+						? { resumeFromStageId: opts.continuation.resumeFromStageId }
+						: {}),
 				}
 			: {}),
 		// A continuation keeps the attribution of the run it continues rather than
@@ -196,7 +251,40 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 			? { resumeActor: opts.resumeActor, resumeSource: "run_control" as const }
 			: {}),
 		...(inheritedElapsedMs !== undefined ? { accumulatedDurationMs: inheritedElapsedMs } : {}),
+		...(budgetSnapshot !== undefined ? { budget: budgetSnapshot } : {}),
+		...(continuationBudgetState !== undefined ? { budgetState: continuationBudgetState } : {}),
+	};
+	const usageTree = (): RunUsageTree => {
+		const snapshots = activeStore.runs();
+		const childrenByParent = new Map<string, RunSnapshot[]>();
+		for (const snapshot of snapshots) {
+			if (snapshot.parentRunId === undefined) continue;
+			const children = childrenByParent.get(snapshot.parentRunId) ?? [];
+			children.push(snapshot);
+			childrenByParent.set(snapshot.parentRunId, children);
+		}
+		const build = (run: RunSnapshot): RunUsageTree => {
+			const children = (childrenByParent.get(run.id) ?? []).map(build);
+			return children.length === 0 ? { run } : { run, children };
+		};
+		return build(snapshots.find((snapshot) => snapshot.id === runSnapshot.id) ?? runSnapshot);
 	};
+	const budget = createRunBudgetController({
+		run: runSnapshot,
+		budget: resolvedBudget,
+		usageTree,
+		rootBudget: opts.rootBudget,
+		onWarning: (report) => {
+			activeStore.recordNotice({
+				id: `workflow-budget-warning:${runId}:${report.dimension}`,
+				runId,
+				level: "warning",
+				message: `Workflow "${def.name}" is at ${report.percent.toFixed(1)}% of its ${report.dimension} budget (${report.reading} / ${report.ceiling}).`,
+				createdAt: Date.now(),
+			});
+		},
+	});
+	const rootBudget = opts.rootBudget ?? budget;
 	const classifiedFailures = new Map<unknown, WorkflowFailure>();
 	const classifyExecutorFailure = (error: unknown): WorkflowFailure => {
 		const cached = classifiedFailures.get(error);
@@ -231,6 +319,8 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 			...(runSnapshot.accumulatedDurationMs !== undefined
 				? { accumulatedDurationMs: runSnapshot.accumulatedDurationMs }
 				: {}),
+			...(runSnapshot.budget !== undefined ? { budget: runSnapshot.budget } : {}),
+			...(runSnapshot.budgetState !== undefined ? { budgetState: runSnapshot.budgetState } : {}),
 			ts: runSnapshot.startedAt,
 		});
 	}
@@ -342,6 +432,7 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 		onStageStart: opts.onStageStart,
 		onStageEnd: opts.onStageEnd,
 		onStageSession: opts.onStageSession,
+		rootBudget,
 		durableBackend,
 		durableRootBackend: rootBackend,
 	};
@@ -367,6 +458,8 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 		worktreeSymlinkDirectories: opts.config?.worktree?.symlinkDirectories,
 		exit,
 		classifyExecutorFailure,
+		rootBudget,
+		budget,
 	});
 	const workflowBoundaryReplayCounts = new Map<string, number>();
 	const nextWorkflowBoundaryReplayKey = (name: string): string => {
@@ -422,6 +515,7 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 		sourceToReplayedNodeIds,
 		toolControls,
 		toolAdmission,
+		budget,
 	});
 	let selectedAdmittedToolFailure: ReturnType<typeof admittedTools.firstFailure>;
 	/**
@@ -571,8 +665,14 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 						},
 		});
 		if (opts.deferWorkflowStart === true) opts.onWorkflowStartReady?.();
+		const sourceFrontierStage = opts.continuation?.source;
+		const sourceFrontierId = sourceFrontierStage?.failedStageId ?? opts.continuation?.resumeFromStageId;
+		const startupFrontierStage =
+			sourceFrontierStage?.stages.find((stage) => stage.id === sourceFrontierId)?.name ?? "workflow frontier";
+		if (budget.enabled) await budget.stopAtBoundaryAsync(startupFrontierStage);
 		const rawResult = await runWorkflowDefinitionCallback(def.name, runId, () => def.run(ctx));
 		await admittedTools.closeAndDrain();
+		budget.rethrowIfSystemOwnedStop(runSnapshot.stages.at(-1)?.name ?? startupFrontierStage);
 		const normalTerminalEvent = terminalEvents.winner();
 		if (normalTerminalEvent?.kind === "cancellation") {
 			const selectedExit = findWorkflowExitSignal(normalTerminalEvent.reason, exitScope);
@@ -632,6 +732,28 @@ export async function run<TInputs extends WorkflowInputValues, TRunInputs extend
 			findWorkflowGracefulQuit(ownController.signal.reason);
 		if (gracefulQuit !== undefined) return suspendForGracefulQuit(gracefulQuit);
 		await admittedTools.closeAndDrain();
+		if (err instanceof WorkflowBudgetExceededError) {
+			const pendingBudgetError = await budget.awaitPendingWrapUp();
+			const selectedBudgetError = pendingBudgetError ?? err;
+			const report = selectedBudgetError.report;
+			const frontierStageId =
+				runSnapshot.stages.find((stage) => stage.name === report.frontierStage)?.id ??
+				runSnapshot.stages.at(-1)?.id;
+			for (const stage of runSnapshot.stages) scheduler.blockKnownNonTerminalDescendants(stage.id);
+			const result: WorkflowOutputValues = { status: "budget_exceeded", ...report };
+			return recordActiveBlockedFailure(runId, runSnapshot, activeStore, opts.persistence, {
+				errorMessage: selectedBudgetError.message,
+				failureKind: "unknown",
+				failureCode: "unknown",
+				failureRecoverability: "recoverable",
+				failureDisposition: "active_blocked",
+				failureMessage: selectedBudgetError.message,
+				...(frontierStageId !== undefined ? { failedStageId: frontierStageId } : {}),
+				resumable: true,
+				result,
+				budgetState: runSnapshot.budgetState,
+			});
+		}
 		const observedAdmittedToolFailure = selectedAdmittedToolFailure ?? admittedTools.uniqueFailureFor(err);
 		const selectedExit =
 			findWorkflowExitSignal(err, exitScope) ?? findWorkflowExitSignal(ownController.signal.reason, exitScope);

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

@@ -19,6 +19,7 @@ import type { RunSnapshot } from "../shared/store-types.js";
 import type { StageOptions } from "../shared/types.js";
 import type { GraphFrontierTracker } from "./graph-inference.js";
 import type { EngineChildRunOptions, EngineStageRuntimeOptions, EngineWorkflowBoundaryOptions } from "./options.js";
+import type { RunBudgetController } from "./run-budget.js";
 
 export interface EngineRuntimeInput {
 	readonly runId: string;
@@ -41,6 +42,8 @@ export interface EngineRuntimeInput {
 	readonly worktreeSymlinkDirectories?: readonly string[];
 	readonly stageRegistry: StageControlRegistry;
 	readonly exit: WorkflowExitManager;
+	readonly budget: RunBudgetController;
+	readonly rootBudget: RunBudgetController;
 	readonly classifyExecutorFailure: LiveStageRuntime["classifyExecutorFailure"];
 }
 
@@ -83,6 +86,8 @@ export class EngineRuntime {
 	readonly exit: WorkflowExitManager;
 	readonly inputRuntimeDefaults: Partial<StageOptions>;
 	readonly workflowInvocationCwd: string;
+	readonly budget: RunBudgetController;
+	readonly rootBudget: RunBudgetController;
 	readonly gitWorktreeSetupCache: GitWorktreeSetupCache;
 	readonly worktreeSymlinkDirectories?: readonly string[];
 
@@ -110,6 +115,8 @@ export class EngineRuntime {
 		this.exit = input.exit;
 		this.inputRuntimeDefaults = input.inputRuntimeDefaults;
 		this.workflowInvocationCwd = input.workflowInvocationCwd;
+		this.budget = input.budget;
+		this.rootBudget = input.rootBudget;
 		this.gitWorktreeSetupCache = input.gitWorktreeSetupCache;
 		this.worktreeSymlinkDirectories = input.worktreeSymlinkDirectories;
 
@@ -130,6 +137,7 @@ export class EngineRuntime {
 			workflowInvocationCwd: input.workflowInvocationCwd,
 			gitWorktreeSetupCache: input.gitWorktreeSetupCache,
 			stageRegistry: input.stageRegistry,
+			budget: input.budget,
 			exit: input.exit,
 			classifyExecutorFailure: input.classifyExecutorFailure,
 			createMcpScope: (stageId, options) => this.createMcpScope(stageId, options),
@@ -164,6 +172,7 @@ export class EngineRuntime {
 		options?: StageOptions,
 		failFastScope?: ParallelFailFastScope,
 	): StageContextWithMeta => {
+		if (this.budget.enabled) this.budget.stopAtBoundary();
 		const handle = this.spawnStage(name, {
 			kind: "agent",
 			...(options !== undefined ? { options } : {}),