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

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

@@ -1,5 +1,6 @@
+import { BUDGET_WRAP_UP_PROMPT, WorkflowBudgetExceededError } from "../../engine/run-budget.js";
 import { rebasedStageStartedAt } from "../../shared/timing.js";
-import type { StageOptions } from "../../shared/types.js";
+import type { StageOptions, WorkflowModelUsage } from "../../shared/types.js";
 import type { ConcurrencyLimiter } from "../shared/concurrency.js";
 import { raceAbort } from "./executor-abort.js";
 import { hasExplicitFastModeCandidate } from "./executor-direct-helpers.js";
@@ -119,10 +120,26 @@ export function createTrackedStageCaller(input: {
 		captureChatAnswer();
 		return { result, chatAnswerObserved };
 	};
+	const deliverBudgetWrapUp = async (): Promise<never> => {
+		let summary: string | undefined;
+		let usage: WorkflowModelUsage | undefined;
+		try {
+			const response = await runtime.raceStageSessionHeartbeat(
+				raceAbort(runtime.innerCtx.prompt(BUDGET_WRAP_UP_PROMPT), runtime.signal),
+			);
+			summary = typeof response === "string" ? response : runtime.innerCtx.__getLastAssistantText();
+			usage = runtime.innerCtx.__modelFallbackMeta().modelAttempts?.at(-1)?.usage;
+		} catch {
+			// A failed or aborted wrap-up did not deliver a summary and must not
+			// consume the once-per-run delivery allowance.
+		}
+		throw runtime.budget.finishWrapUp(runtime.name, summary, usage, summary !== undefined);
+	};
 
 	return async <T>(call: () => Promise<T>, eagerSessionOrOptions?: boolean | TrackedStageCallOptions): Promise<T> => {
 		const callOptions = normalizeTrackedStageCallOptions(eagerSessionOrOptions);
 		runtime.exit.throwIfWorkflowExitSelected();
+		if (runtime.budget.enabled) await runtime.budget.stopAtBoundaryAsync(runtime.name);
 		await runtime.scheduler.waitForStageRelease(runtime.stageId, runtime.releaseLiveHandle);
 		if (runtime.state.stageFinalized && !callOptions.allowFinalized) throw runtime.parallelFailFastError();
 
@@ -142,6 +159,8 @@ export function createTrackedStageCaller(input: {
 		// final durable checkpoint can replace it without touching a real
 		// failure/skip classification recorded by the catch block.
 		let terminalStateIsSuccess = false;
+		let stageResultBeforeBudget: string | undefined;
+		const unregisterBudgetWrapUp = runtime.budget.registerWrapUp(runtime.name, deliverBudgetWrapUp);
 		try {
 			let refreshedParentIds: readonly string[] | undefined;
 			if (
@@ -210,8 +229,10 @@ export function createTrackedStageCaller(input: {
 				runtime.state.askUserQuestionObservedThisTurn = false;
 				runtime.state.chatAnswerObservedThisTurn = false;
 				result = await runtime.raceStageSessionHeartbeat(raceAbort(call(), runtime.signal));
+				if (runtime.budget.enabled && typeof result === "string") stageResultBeforeBudget = result;
 				const initialDrain = await drainResumeContinuations(result);
 				result = initialDrain.result;
+				if (runtime.budget.enabled && typeof result === "string") stageResultBeforeBudget = result;
 				let repeatReadinessAfterChatTurn = initialDrain.chatAnswerObserved;
 
 				if (
@@ -239,6 +260,7 @@ export function createTrackedStageCaller(input: {
 								result = (await runtime.raceStageSessionHeartbeat(
 									raceAbort(runtime.innerCtx.prompt(decision.message), runtime.signal),
 								)) as T;
+								if (runtime.budget.enabled && typeof result === "string") stageResultBeforeBudget = result;
 							} else {
 								runtime.state.waitingForStageChatTurn = true;
 								try {
@@ -256,10 +278,15 @@ export function createTrackedStageCaller(input: {
 									runtime.state.waitingForStageChatTurn = false;
 								}
 								if (runtime.signal.aborted) break;
-								result = (runtime.innerCtx.__getLastAssistantText() ?? result) as T;
+								const responseText = runtime.innerCtx.__getLastAssistantText();
+								if (responseText !== undefined) {
+									result = responseText as T;
+									if (runtime.budget.enabled) stageResultBeforeBudget = responseText;
+								}
 							}
 							const continuationDrain = await drainResumeContinuations(result);
 							result = continuationDrain.result;
+							if (runtime.budget.enabled && typeof result === "string") stageResultBeforeBudget = result;
 							repeatReadinessAfterChatTurn ||= continuationDrain.chatAnswerObserved;
 							if (runtime.innerCtx.__structuredOutputFinalized()) break;
 						}
@@ -272,9 +299,14 @@ export function createTrackedStageCaller(input: {
 			} finally {
 				runtime.signal.removeEventListener("abort", abortSession);
 			}
+			if (runtime.budget.enabled) stageResultBeforeBudget ??= runtime.innerCtx.__getLastAssistantText();
+			runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
+			const afterBudget = runtime.budget.checkpoint(runtime.name);
+			if (afterBudget.kind === "wrap_up") await runtime.budget.deliverWrapUp(runtime.name);
+			if (afterBudget.kind === "exhausted" && runtime.budget.enabled)
+				await runtime.budget.stopAtBoundaryAsync(runtime.name);
 			await runtime.innerCtx.__closeGeneration();
 			await runtime.captureStageSessionMeta({ awaitDurable: true });
-			runtime.applyModelFallbackMeta(runtime.innerCtx.__modelFallbackMeta());
 			if (
 				trackStageLifecycle &&
 				runtime.stageFailFastScope?.failed === true &&
@@ -285,7 +317,9 @@ export function createTrackedStageCaller(input: {
 			}
 			if (trackStageLifecycle && runtime.state.stageFinalized) throw runtime.parallelFailFastError();
 			if (trackStageLifecycle) {
-				const assistantText = runtime.innerCtx.__getLastAssistantText();
+				const assistantText = runtime.budget.enabled
+					? (stageResultBeforeBudget ?? runtime.innerCtx.__getLastAssistantText())
+					: runtime.innerCtx.__getLastAssistantText();
 				terminalStateIsSuccess = true;
 				applyTerminalStageState = () => {
 					runtime.stageSnapshot.status = "completed";
@@ -295,7 +329,29 @@ export function createTrackedStageCaller(input: {
 			return result;
 		} catch (err) {
 			const workflowExitAbort = runtime.signal.aborted ? runtime.exit.currentWorkflowExitAbortReason() : undefined;
-			if (workflowExitAbort !== undefined && !runtime.state.skippedForParallelFailFast) {
+			const budgetError = err instanceof WorkflowBudgetExceededError ? err : undefined;
+			if (budgetError !== undefined && trackStageLifecycle && !runtime.state.skippedForParallelFailFast) {
+				let selectedBudgetError = budgetError;
+				if (
+					runtime.activeStore.runs().find((run) => run.id === runtime.runId)?.budgetState?.wrapUpCompleted !== true
+				) {
+					try {
+						await runtime.budget.deliverWrapUp(runtime.name);
+					} catch (wrapUpError) {
+						if (wrapUpError instanceof WorkflowBudgetExceededError) selectedBudgetError = wrapUpError;
+					}
+				}
+				applyTerminalStageState = () => {
+					if (stageResultBeforeBudget !== undefined) {
+						runtime.stageSnapshot.status = "completed";
+						runtime.stageSnapshot.result = stageResultBeforeBudget;
+					} else {
+						runtime.stageSnapshot.status = "failed";
+						runtime.stageSnapshot.error = selectedBudgetError.message;
+					}
+				};
+				throw selectedBudgetError;
+			} else if (workflowExitAbort !== undefined && !runtime.state.skippedForParallelFailFast) {
 				runtime.state.stageClosedByWorkflowExit = true;
 				if (trackStageLifecycle && !isTerminalStage(runtime.stageSnapshot)) {
 					const skippedReason = runtime.exit.workflowExitSkippedReason(workflowExitAbort.reason);
@@ -310,6 +366,7 @@ export function createTrackedStageCaller(input: {
 			}
 			throw err;
 		} finally {
+			unregisterBudgetWrapUp();
 			// Finalization, handle release, and limiter release are each independent.
 			// If finalizeStageSnapshot() throws, the limiter must still be released
 			// so the concurrency semaphore is not leaked.

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

@@ -1,6 +1,7 @@
 import { runCallback, runSynchronousCallback } from "@bastani/atomic";
 import type { GraphFrontierTracker } from "../../engine/graph-inference.js";
 import type { EngineStageRuntimeOptions } from "../../engine/options.js";
+import type { RunBudgetController } from "../../engine/run-budget.js";
 import { appendStageEnd, appendStageStart } from "../../shared/persistence-session-entries.js";
 import { buildStagePromptAdapter } from "../../shared/stage-prompt.js";
 import { stageUiBroker } from "../../shared/stage-ui-broker.js";
@@ -58,6 +59,7 @@ export function createWorkflowStageFactory(input: {
 	readonly gitWorktreeSetupCache: GitWorktreeSetupCache;
 	readonly stageRegistry: StageControlRegistry;
 	readonly exit: WorkflowExitManager;
+	readonly budget: RunBudgetController;
 	readonly classifyExecutorFailure: (error: unknown) => WorkflowFailure;
 	readonly createMcpScope: (stageId: string, options: StageOptions | undefined) => StageMcpScope;
 }): (name: string, options?: StageOptions, stageFailFastScope?: ParallelFailFastScope) => StageContextWithMeta {
@@ -350,6 +352,7 @@ export function createWorkflowStageFactory(input: {
 					...(stageSnapshot.skippedReason !== undefined ? { skippedReason: stageSnapshot.skippedReason } : {}),
 					...(stageSnapshot.sessionId !== undefined ? { sessionId: stageSnapshot.sessionId } : {}),
 					...(stageSnapshot.sessionFile !== undefined ? { sessionFile: stageSnapshot.sessionFile } : {}),
+					...(stageSnapshot.modelAttempts !== undefined ? { modelAttempts: stageSnapshot.modelAttempts } : {}),
 					...(stageSnapshot.result !== undefined && stageSnapshot.status === "completed"
 						? { summary: stageSnapshot.result }
 						: {}),
@@ -381,6 +384,7 @@ export function createWorkflowStageFactory(input: {
 			scheduler: input.scheduler,
 			signal: input.signal,
 			exit: input.exit,
+			budget: input.budget,
 			classifyExecutorFailure: input.classifyExecutorFailure,
 			mcpScope: input.createMcpScope(stageId, options),
 			...(stageFailFastScope !== undefined ? { stageFailFastScope } : {}),

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

@@ -1,4 +1,5 @@
 import type { EngineStageRuntimeOptions } from "../../engine/options.js";
+import type { RunBudgetController } from "../../engine/run-budget.js";
 import type { Store } from "../../shared/store.js";
 import type { StageNotice, StageSnapshot } from "../../shared/store-types.js";
 import type { StageContext } from "../../shared/types.js";
@@ -44,6 +45,7 @@ export interface LiveStageRuntime {
 	readonly scheduler: StageScheduler;
 	readonly signal: AbortSignal;
 	readonly exit: WorkflowExitManager;
+	readonly budget: RunBudgetController;
 	readonly classifyExecutorFailure: (error: unknown) => WorkflowFailure;
 	readonly mcpScope: StageMcpScope;
 	readonly stageFailFastScope?: ParallelFailFastScope;

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

@@ -29,7 +29,7 @@ export interface ResolvedInputs extends WorkflowInputValues {}
 
 export interface RunContinuationOpts {
 	readonly source: RunSnapshot;
-	readonly resumeFromStageId: string;
+	readonly resumeFromStageId?: string;
 }
 
 export interface StageSessionCheckpointOptions {
@@ -140,6 +140,8 @@ export interface RunOpts
 		readonly stageId: string;
 		readonly rootRunId: string;
 	};
+	/** Internal root budget scope shared by nested workflow runs. */
+	rootBudget?: import("../../engine/run-budget.js").RunBudgetController;
 	onRunStart?: (snapshot: RunSnapshot) => void;
 	onStageStart?: (runId: string, snapshot: StageSnapshot) => void;
 	onStageEnd?: (runId: string, snapshot: StageSnapshot) => unknown;

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

@@ -424,7 +424,16 @@ export class StageSessionController {
 				const activeSession = await this.ensureSession(consumer);
 				const resumedText = this.pendingCreationResumeMessage;
 				this.pendingCreationResumeMessage = undefined;
-				await this.promptWithThrownErrorRetry(activeSession, resumedText ?? text, sdkOptions);
+				const value = activeSession.model ?? "default";
+				const candidate = { id: workflowModelId(value) ?? "default", value };
+				this.beginAttemptUsage(activeSession);
+				try {
+					await this.promptWithThrownErrorRetry(activeSession, resumedText ?? text, sdkOptions);
+				} catch (error) {
+					await this.handleCandidateFailure(error, candidate, [candidate], 0);
+					throw error;
+				}
+				this.recordSuccessfulAttempt(candidate);
 			} catch (error) {
 				if (error instanceof StageSessionCreationCancelled) return;
 				throw error;

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

@@ -372,6 +372,7 @@ export type WorkflowTaskSessionOptions = StageOptions & WorkflowTaskSessionField
 export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = WorkflowInputValues> {
     readonly inputs?: TInputs;
     readonly stageName?: string;
+    readonly budget?: import("./budget.js").WorkflowBudget;
 }
 type WorkflowRequiredKeys<T extends object> = {
     [K in keyof T]-?: Record<never, never> extends Pick<T, K> ? never : K;

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

@@ -446,6 +446,7 @@ export type WorkflowTaskSessionOptions = StageOptions & WorkflowTaskSessionField
 export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = WorkflowInputValues> {
 	readonly inputs?: TInputs;
 	readonly stageName?: string;
+	readonly budget?: import("./budget.js").WorkflowBudget;
 }
 
 type WorkflowRequiredKeys<T extends object> = {

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

@@ -3,6 +3,7 @@ import type { KeybindingsManager, Theme } from "@bastani/atomic";
 import type { Component, OverlayHandle, OverlayOptions, TUI } from "@earendil-works/pi-tui";
 import type { TSchema } from "typebox";
 import type { RunStatus, StageAdapters, StageContext, StageOptions, WorkflowAction, WorkflowActor, WorkflowArtifact, WorkflowChainOptions, WorkflowChildResult, WorkflowContextMode, WorkflowDetailsMode, WorkflowDetailsStatus, WorkflowExecutionMode, WorkflowExitOptions, WorkflowInputSchemaMap, WorkflowInputValues, WorkflowMcpPort, WorkflowModelCatalogPort, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowParallelOptions, WorkflowPersistencePort, WorkflowRunChildArgs, WorkflowSerializableObject, WorkflowSerializableValue, WorkflowTaskOptions, WorkflowTaskResult, WorkflowTaskStep } from "./authoring-contract-stage.js";
+import type { EffectiveBudget, WorkflowBudget } from "./budget.js";
 export type WorkflowCustomUiComponent = Component & {
     dispose?(): void;
 };
@@ -138,6 +139,8 @@ export interface WorkflowRuntimeConfig {
     readonly statusFile: boolean;
     readonly statusFilePath?: string;
     readonly resumeInFlight: "ask" | "auto" | "never";
+    /** Resolved default budget for workflow runs. */
+    readonly budget?: EffectiveBudget;
     readonly worktree?: {
         readonly symlinkDirectories: readonly string[];
     };
@@ -157,6 +160,8 @@ export interface WorkflowDefinition<TInputs extends WorkflowInputValues = Workfl
     readonly description: string;
     readonly autoAttach?: true;
     readonly heartbeatIntervalMinutes: number;
+    /** Optional budget declaration resolved when this workflow runs. */
+    readonly budget?: WorkflowBudget;
     readonly inputs: WorkflowInputSchemaMap;
     readonly outputs?: WorkflowOutputSchemaMap;
     readonly inputBindings?: WorkflowInputBindings;
@@ -208,6 +213,8 @@ export interface RunOpts {
     readonly signal?: AbortSignal;
     readonly deferWorkflowStart?: boolean;
     readonly config?: WorkflowRuntimeConfig;
+    /** Per-run budget override. Each field resolves over definition and config values. */
+    readonly budget?: WorkflowBudget;
     readonly models?: WorkflowModelCatalogPort;
     readonly registry?: object;
     readonly depth?: number;

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

@@ -33,6 +33,7 @@ import type {
 	WorkflowTaskResult,
 	WorkflowTaskStep,
 } from "./authoring-contract-stage.js";
+import type { EffectiveBudget, WorkflowBudget } from "./budget.js";
 
 export type WorkflowCustomUiComponent = Component & { dispose?(): void };
 export type WorkflowCustomUiTui = TUI;
@@ -216,6 +217,8 @@ export interface WorkflowRuntimeConfig {
 	readonly statusFile: boolean;
 	readonly statusFilePath?: string;
 	readonly resumeInFlight: "ask" | "auto" | "never";
+	/** Resolved default budget for workflow runs. */
+	readonly budget?: EffectiveBudget;
 	readonly worktree?: {
 		readonly symlinkDirectories: readonly string[];
 	};
@@ -243,6 +246,8 @@ export interface WorkflowDefinition<
 	readonly description: string;
 	readonly autoAttach?: true;
 	readonly heartbeatIntervalMinutes: number;
+	/** Optional budget declaration resolved when this workflow runs. */
+	readonly budget?: WorkflowBudget;
 	readonly inputs: WorkflowInputSchemaMap;
 	readonly outputs?: WorkflowOutputSchemaMap;
 	readonly inputBindings?: WorkflowInputBindings;
@@ -299,6 +304,8 @@ export interface RunOpts {
 	readonly signal?: AbortSignal;
 	readonly deferWorkflowStart?: boolean;
 	readonly config?: WorkflowRuntimeConfig;
+	/** Per-run budget override. Each field resolves over definition and config values. */
+	readonly budget?: WorkflowBudget;
 	readonly models?: WorkflowModelCatalogPort;
 	readonly registry?: object;
 	readonly depth?: number;

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

@@ -8,3 +8,4 @@
 export type { Static, TSchema } from "typebox";
 export * from "./authoring-contract-stage.js";
 export * from "./authoring-contract-ui.js";
+export type { EffectiveBudget, ResolveBudgetLayers, WorkflowBudget } from "./budget.js";

package/dist/builtin/workflows/src/shared/budget-meter.ts

@@ -0,0 +1,34 @@
+import { fold_usage } from "../../builtin/verification-usage.js";
+import type { RunSnapshot } from "./store-types.js";
+import { elapsedRunMs } from "./timing.js";
+export type RunMeterCounters = Readonly<Record<"input" | "output" | "cacheRead" | "cacheWrite", number>>;
+export type RunMeters = Readonly<{ durationMs: number; tokens: number; cost: number; perCounter: RunMeterCounters }>;
+/** A run and its nested child scopes, used by the tree-wide usage meter. */
+export type RunUsageTree =
+	| { readonly run: RunSnapshot; readonly children?: readonly RunUsageTree[] }
+	| (RunSnapshot & { readonly children?: readonly RunUsageTree[] });
+type UsageCounters = RunMeterCounters & { readonly cost: number };
+const usageFields = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const;
+const addUsage = (left: UsageCounters, right: UsageCounters): UsageCounters =>
+	Object.fromEntries(usageFields.map((field) => [field, left[field] + right[field]])) as unknown as UsageCounters;
+function foldTreeUsage(tree: RunUsageTree): UsageCounters {
+	const run = "run" in tree ? tree.run : tree;
+	const folded = fold_usage(
+		run.stages
+			.filter((stage) => stage.replayed !== true)
+			.map((stage) => ({ stageName: stage.name, text: stage.result ?? "", modelAttempts: stage.modelAttempts })),
+	);
+	return (tree.children ?? []).reduce<UsageCounters>((total, child) => addUsage(total, foldTreeUsage(child)), folded);
+}
+/** Measure one run scope without mutating it or charging a budget. */
+export function meter_run(tree: RunUsageTree, now: number): RunMeters {
+	const usage = foldTreeUsage(tree);
+	return {
+		durationMs: elapsedRunMs("run" in tree ? tree.run : tree, now),
+		tokens: usage.input + usage.output,
+		cost: usage.cost,
+		perCounter: Object.fromEntries(
+			usageFields.filter((field) => field !== "cost").map((field) => [field, usage[field]]),
+		) as RunMeterCounters,
+	};
+}

package/dist/builtin/workflows/src/shared/budget.d.ts

@@ -0,0 +1,67 @@
+/** Pure workflow run-budget declarations and resolution. */
+export type BudgetDimension = "duration" | "tokens" | "cost";
+export interface BudgetReport {
+    readonly dimension: BudgetDimension;
+    readonly reading: number;
+    readonly ceiling: number;
+    readonly percent: number;
+}
+export type DurationBudgetReport = BudgetReport & {
+    readonly dimension: "duration";
+};
+export type UsageBudgetReport = BudgetReport & {
+    readonly dimension: "tokens" | "cost";
+};
+export interface WorkflowBudget {
+    readonly maxDurationMs?: number;
+    readonly maxTokens?: number;
+    readonly maxCost?: number;
+    readonly warnAtPercent?: number;
+}
+export type DurationBudgetCheck = {
+    readonly kind: "continue";
+    readonly report: DurationBudgetReport;
+    readonly warning: boolean;
+} | {
+    readonly kind: "exhausted";
+    readonly report: DurationBudgetReport;
+};
+export declare function enforceDurationBudget(reading: number, budget: EffectiveBudget, options?: {
+    readonly warned?: boolean;
+}): DurationBudgetCheck;
+export type UsageBudgetCheck = {
+    readonly kind: "continue";
+    readonly report: UsageBudgetReport;
+    readonly warning: boolean;
+} | {
+    readonly kind: "exhausted";
+    readonly report: UsageBudgetReport;
+};
+export declare function enforceUsageBudget(dimension: "tokens" | "cost", reading: number, ceiling: number, warnAtPercent: number, options?: {
+    readonly warned?: boolean;
+}): UsageBudgetCheck;
+/** A fully resolved budget. Create one only with {@link resolve_budget}. */
+declare class ResolvedWorkflowBudget {
+    private readonly brand;
+    readonly maxDurationMs: number;
+    readonly maxTokens: number;
+    readonly maxCost: number;
+    readonly warnAtPercent: number;
+    private constructor();
+    static resolve(layers: ResolveBudgetLayers): ResolvedWorkflowBudget;
+}
+/** A validated, fully resolved workflow budget. */
+export type EffectiveBudget = ResolvedWorkflowBudget;
+/** Budget declarations in precedence order: run > definition > config. */
+export interface ResolveBudgetLayers {
+    readonly config?: WorkflowBudget;
+    readonly definition?: WorkflowBudget;
+    readonly run?: WorkflowBudget;
+}
+/** Return a reason when a budget declaration is invalid. */
+export declare function validateWorkflowBudget(value: unknown, label?: string): string | null;
+/** Reject an invalid optional budget declaration. */
+export declare function assertWorkflowBudget(value: WorkflowBudget | undefined, label?: string): void;
+/** Resolve budget declarations, with later layers winning independently per field. */
+export declare function resolve_budget(layers: ResolveBudgetLayers): EffectiveBudget;
+export {};

package/dist/builtin/workflows/src/shared/budget.ts

@@ -0,0 +1,127 @@
+/** Pure workflow run-budget declarations and resolution. */
+
+export type BudgetDimension = "duration" | "tokens" | "cost";
+export interface BudgetReport {
+	readonly dimension: BudgetDimension;
+	readonly reading: number;
+	readonly ceiling: number;
+	readonly percent: number;
+}
+export type DurationBudgetReport = BudgetReport & { readonly dimension: "duration" };
+export type UsageBudgetReport = BudgetReport & { readonly dimension: "tokens" | "cost" };
+export interface WorkflowBudget {
+	readonly maxDurationMs?: number;
+	readonly maxTokens?: number;
+	readonly maxCost?: number;
+	readonly warnAtPercent?: number;
+}
+
+export type DurationBudgetCheck =
+	| { readonly kind: "continue"; readonly report: DurationBudgetReport; readonly warning: boolean }
+	| { readonly kind: "exhausted"; readonly report: DurationBudgetReport };
+export function enforceDurationBudget(
+	reading: number,
+	budget: EffectiveBudget,
+	options: { readonly warned?: boolean } = {},
+): DurationBudgetCheck {
+	const ceiling = budget.maxDurationMs;
+	const report: DurationBudgetReport = {
+		dimension: "duration",
+		reading,
+		ceiling,
+		percent: ceiling === 0 ? 0 : (reading / ceiling) * 100,
+	};
+	if (ceiling > 0 && reading >= ceiling) return { kind: "exhausted", report };
+	const warning = options.warned !== true && budget.warnAtPercent > 0 && report.percent >= budget.warnAtPercent;
+	return { kind: "continue", report, warning };
+}
+export type UsageBudgetCheck =
+	| { readonly kind: "continue"; readonly report: UsageBudgetReport; readonly warning: boolean }
+	| { readonly kind: "exhausted"; readonly report: UsageBudgetReport };
+export function enforceUsageBudget(
+	dimension: "tokens" | "cost",
+	reading: number,
+	ceiling: number,
+	warnAtPercent: number,
+	options: { readonly warned?: boolean } = {},
+): UsageBudgetCheck {
+	const report: UsageBudgetReport = { dimension, reading, ceiling, percent: ceiling ? (reading / ceiling) * 100 : 0 };
+	if (ceiling > 0 && reading >= ceiling) return { kind: "exhausted", report };
+	const warning = options.warned !== true && warnAtPercent > 0 && report.percent >= warnAtPercent;
+	return { kind: "continue", report, warning };
+}
+/** A fully resolved budget. Create one only with {@link resolve_budget}. */
+class ResolvedWorkflowBudget {
+	private declare readonly brand: undefined;
+	readonly maxDurationMs: number;
+	readonly maxTokens: number;
+	readonly maxCost: number;
+	readonly warnAtPercent: number;
+
+	private constructor(maxDurationMs: number, maxTokens: number, maxCost: number, warnAtPercent: number) {
+		this.maxDurationMs = maxDurationMs;
+		this.maxTokens = maxTokens;
+		this.maxCost = maxCost;
+		this.warnAtPercent = warnAtPercent;
+	}
+
+	static resolve(layers: ResolveBudgetLayers): ResolvedWorkflowBudget {
+		assertWorkflowBudget(layers.config, "config budget");
+		assertWorkflowBudget(layers.definition, "definition budget");
+		assertWorkflowBudget(layers.run, "run budget");
+
+		return new ResolvedWorkflowBudget(
+			layers.run?.maxDurationMs ?? layers.definition?.maxDurationMs ?? layers.config?.maxDurationMs ?? 0,
+			layers.run?.maxTokens ?? layers.definition?.maxTokens ?? layers.config?.maxTokens ?? 0,
+			layers.run?.maxCost ?? layers.definition?.maxCost ?? layers.config?.maxCost ?? 0,
+			layers.run?.warnAtPercent ?? layers.definition?.warnAtPercent ?? layers.config?.warnAtPercent ?? 80,
+		);
+	}
+}
+
+/** A validated, fully resolved workflow budget. */
+export type EffectiveBudget = ResolvedWorkflowBudget;
+
+/** Budget declarations in precedence order: run > definition > config. */
+export interface ResolveBudgetLayers {
+	readonly config?: WorkflowBudget;
+	readonly definition?: WorkflowBudget;
+	readonly run?: WorkflowBudget;
+}
+
+/** Return a reason when a budget declaration is invalid. */
+export function validateWorkflowBudget(value: unknown, label = "budget"): string | null {
+	if (value === null || typeof value !== "object" || Array.isArray(value)) {
+		return `"${label}" must be a JSON object, got ${JSON.stringify(typeof value)}`;
+	}
+
+	const budget = value as Record<string, unknown>;
+	for (const field of ["maxDurationMs", "maxTokens"] as const) {
+		const limit = budget[field];
+		if (
+			field in budget &&
+			(typeof limit !== "number" || !Number.isFinite(limit) || !Number.isInteger(limit) || limit < 0)
+		) {
+			return `"${label}.${field}" must be a non-negative finite integer, got ${JSON.stringify(limit)}`;
+		}
+	}
+	for (const field of ["maxCost", "warnAtPercent"] as const) {
+		const limit = budget[field];
+		if (field in budget && (typeof limit !== "number" || !Number.isFinite(limit) || limit < 0)) {
+			return `"${label}.${field}" must be a non-negative finite number, got ${JSON.stringify(limit)}`;
+		}
+	}
+	return null;
+}
+
+/** Reject an invalid optional budget declaration. */
+export function assertWorkflowBudget(value: WorkflowBudget | undefined, label = "budget"): void {
+	if (value === undefined) return;
+	const reason = validateWorkflowBudget(value, label);
+	if (reason !== null) throw new TypeError(reason);
+}
+
+/** Resolve budget declarations, with later layers winning independently per field. */
+export function resolve_budget(layers: ResolveBudgetLayers): EffectiveBudget {
+	return ResolvedWorkflowBudget.resolve(layers);
+}