@bastani/atomic 0.9.14-alpha.4 → 0.9.14-alpha.6

package/dist/builtin/workflows/src/shared/persistence-restore-helpers.ts

@@ -1,8 +1,11 @@
 import { Value } from "typebox/value";
+import { isModelAttempts } from "../durable/dbos-envelope.js";
 import type { NormalizedSessionEntry as SessionEntry } from "./persistence-restore.js";
 import { workflowSerializableObjectSchema } from "./serializable.js";
 import type { Store } from "./store.js";
 import type {
+	RunBudgetSnapshot,
+	RunBudgetState,
 	RunStatus,
 	StageSnapshot,
 	StageStatus,
@@ -21,7 +24,7 @@ import {
 } from "./workflow-failures.js";
 
 interface RestoredRunBlockedMetadata {
-	readonly failedStageId: string;
+	readonly failedStageId?: string;
 	readonly error: string;
 	readonly failureKind: WorkflowFailureKind;
 	readonly failureCode?: WorkflowFailureCode;
@@ -30,6 +33,9 @@ interface RestoredRunBlockedMetadata {
 	readonly failureMessage?: string;
 	readonly retryAfterMs?: number;
 	readonly resumable: true;
+	readonly endedAt?: number;
+	readonly result?: WorkflowOutputValues;
+	readonly budgetState?: RunBudgetState;
 	readonly ts: number;
 }
 
@@ -78,6 +84,7 @@ export function _buildStageSnapshots(
 			const skippedReason = entry.payload.skippedReason;
 			const sessionId = entry.payload.sessionId;
 			const sessionFile = entry.payload.sessionFile;
+			const modelAttempts = entry.payload.modelAttempts;
 			if (typeof stageId !== "string") continue;
 			endedStages.add(stageId);
 			const snap = stageMap.get(stageId);
@@ -97,6 +104,7 @@ export function _buildStageSnapshots(
 				if (typeof skippedReason === "string") snap.skippedReason = skippedReason;
 				if (typeof sessionId === "string") snap.sessionId = sessionId;
 				if (typeof sessionFile === "string") snap.sessionFile = sessionFile;
+				if (isModelAttempts(modelAttempts)) snap.modelAttempts = modelAttempts as StageSnapshot["modelAttempts"];
 				Object.assign(snap, replayMetadata(entry.payload), workflowChildMetadata(entry.payload));
 			}
 		}
@@ -145,12 +153,12 @@ function markRestoredBlockedFailureStage(snap: StageSnapshot, blockedMeta: Resto
 	snap.failureMessage = blockedMeta.failureMessage;
 	snap.retryAfterMs = blockedMeta.retryAfterMs;
 }
-
 function restoreBlockedStageState(
 	stageMap: Map<string, StageSnapshot>,
 	endedStages: ReadonlySet<string>,
 	blockedMeta: RestoredRunBlockedMetadata,
 ): void {
+	if (blockedMeta.failedStageId === undefined) return;
 	for (const [stageId, snap] of stageMap) {
 		if (endedStages.has(stageId)) continue;
 		if (stageId === blockedMeta.failedStageId) {
@@ -189,6 +197,70 @@ export function serializableObjectOrEmpty(value: unknown): WorkflowOutputValues
 	return serializableObject(value) ?? {};
 }
 
+function restoreBudgetSnapshot(value: unknown): RunBudgetSnapshot | undefined {
+	if (!isRecord(value)) return undefined;
+	const maxDurationMs = numericDuration(value.maxDurationMs);
+	const maxTokens = numericDuration(value.maxTokens),
+		maxCost = numericDuration(value.maxCost);
+	const warnAtPercent = numericDuration(value.warnAtPercent);
+	if (maxDurationMs === undefined || warnAtPercent === undefined) return undefined;
+	return {
+		maxDurationMs,
+		...(maxTokens !== undefined ? { maxTokens } : {}),
+		...(maxCost !== undefined ? { maxCost } : {}),
+		warnAtPercent,
+	};
+}
+export function restoreBudgetState(value: unknown): RunBudgetState | undefined {
+	if (!isRecord(value)) return undefined;
+	const report = (candidate: unknown, dimension: "duration" | "tokens" | "cost") => {
+		if (!isRecord(candidate) || (dimension !== "duration" && dimension !== "tokens" && dimension !== "cost"))
+			return undefined;
+		const reading = numericDuration(candidate.reading);
+		const ceiling = numericDuration(candidate.ceiling);
+		const percent = numericDuration(candidate.percent);
+		return reading === undefined || ceiling === undefined || percent === undefined
+			? undefined
+			: { dimension, reading, ceiling, percent };
+	};
+	const duration = report(value.duration, "duration") as RunBudgetState["duration"];
+	const tokens = report(value.tokens, "tokens") as RunBudgetState["tokens"];
+	const cost = report(value.cost, "cost") as RunBudgetState["cost"];
+	const warning = isRecord(value.warning)
+		? report(value.warning, value.warning.dimension as "duration" | "tokens" | "cost")
+		: undefined;
+	const warnings: Partial<Record<"duration" | "tokens" | "cost", RunBudgetState["warning"]>> = {};
+	const warningValues = isRecord(value.warnings) ? value.warnings : undefined;
+	for (const dimension of ["duration", "tokens", "cost"] as const) {
+		const restored = report(warningValues?.[dimension], dimension);
+		if (restored !== undefined) warnings[dimension] = restored;
+	}
+	const requiredNumbers = (candidate: unknown, fields: readonly string[]): boolean =>
+		isRecord(candidate) && fields.every((field) => numericDuration(candidate[field]) !== undefined);
+	const accountingValue = value.accounting;
+	const accounting =
+		isRecord(accountingValue) &&
+		requiredNumbers(accountingValue, ["tokens", "cost"]) &&
+		requiredNumbers(accountingValue.baseline, ["input", "output", "cacheRead", "cacheWrite", "cost"]) &&
+		requiredNumbers(accountingValue.perCounter, ["input", "output", "cacheRead", "cacheWrite"])
+			? (accountingValue as RunBudgetState["accounting"])
+			: undefined;
+	const state = {
+		...(duration !== undefined ? { duration } : {}),
+		...(tokens !== undefined ? { tokens } : {}),
+		...(cost !== undefined ? { cost } : {}),
+		...(warning !== undefined ? { warning } : {}),
+		...(Object.keys(warnings).length > 0 ? { warnings } : {}),
+		...(accounting !== undefined ? { accounting } : {}),
+		...(value.warned === true ? { warned: true } : {}),
+		...(value.wrapUpDelivered === true ? { wrapUpDelivered: true } : {}),
+		...(value.wrapUpCompleted === true ? { wrapUpCompleted: true } : {}),
+		...(value.systemOwnedStop === true ? { systemOwnedStop: true } : {}),
+		...(typeof value.wrapUpSummary === "string" ? { wrapUpSummary: value.wrapUpSummary } : {}),
+		...(isRecord(value.wrapUpUsage) ? { wrapUpUsage: value.wrapUpUsage as RunBudgetState["wrapUpUsage"] } : {}),
+	};
+	return Object.keys(state).length > 0 ? state : undefined;
+}
 function isWorkflowChildReplayStatus(status: unknown): status is WorkflowExitStatus {
 	return (
 		status === "completed" ||
@@ -327,19 +399,21 @@ export function findRunBlockedMetadata(
 		const retryAfterMs = numericRetryAfterMs(entry.payload.retryAfterMs);
 		const resumable = entry.payload.resumable;
 		const ts = entry.payload.ts;
+		const result = serializableObject(entry.payload.result);
+		const budgetState = restoreBudgetState(entry.payload.budgetState);
+		const isBudgetStop = budgetState?.systemOwnedStop === true && result?.status === "budget_exceeded";
 		if (
-			typeof failedStageId !== "string" ||
 			typeof error !== "string" ||
 			typeof failureKind !== "string" ||
 			!isWorkflowFailureKind(failureKind) ||
 			failureRecoverability !== "recoverable" ||
 			resumable !== true ||
-			typeof ts !== "number"
-		) {
+			typeof ts !== "number" ||
+			(!isBudgetStop && typeof failedStageId !== "string")
+		)
 			continue;
-		}
 		latest = {
-			failedStageId,
+			...(typeof failedStageId === "string" ? { failedStageId } : {}),
 			error,
 			failureKind,
 			...(typeof failureCode === "string" && isWorkflowFailureCode(failureCode) ? { failureCode } : {}),
@@ -350,12 +424,14 @@ export function findRunBlockedMetadata(
 			...(typeof failureMessage === "string" ? { failureMessage } : {}),
 			...(retryAfterMs !== undefined ? { retryAfterMs } : {}),
 			resumable: true,
+			...(typeof entry.payload.endedAt === "number" ? { endedAt: entry.payload.endedAt } : {}),
+			...(result !== undefined ? { result } : {}),
+			...(budgetState !== undefined ? { budgetState } : {}),
 			ts,
 		};
 	}
 	return latest;
 }
-
 export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Store): void {
 	const started = new Map<
 		string,
@@ -422,6 +498,8 @@ export function restoreTerminalRuns(entries: readonly SessionEntry[], store: Sto
 			...(runMeta.accumulatedDurationMs !== undefined
 				? { accumulatedDurationMs: runMeta.accumulatedDurationMs }
 				: {}),
+			...(runMeta.budget !== undefined ? { budget: runMeta.budget } : {}),
+			...(runMeta.budgetState !== undefined ? { budgetState: runMeta.budgetState } : {}),
 		});
 
 		const error = end.error;
@@ -501,6 +579,8 @@ export function findRunStartMetadata(
 	readonly resumeFromStageId?: string;
 	readonly accumulatedDurationMs?: number;
 	readonly origin?: WorkflowActor;
+	readonly budget?: RunBudgetSnapshot;
+	readonly budgetState?: RunBudgetState;
 } {
 	for (const entry of entries) {
 		if (entry.type !== "workflow.run.start" || entry.payload.runId !== runId) continue;
@@ -510,6 +590,8 @@ export function findRunStartMetadata(
 		const resumedFromRunId = entry.payload.resumedFromRunId;
 		const resumeFromStageId = entry.payload.resumeFromStageId;
 		const accumulatedDurationMs = entry.payload.accumulatedDurationMs;
+		const budget = restoreBudgetSnapshot(entry.payload.budget);
+		const budgetState = restoreBudgetState(entry.payload.budgetState);
 		const origin = entry.payload.origin;
 		return {
 			...(typeof parentRunId === "string" ? { parentRunId } : {}),
@@ -523,6 +605,8 @@ export function findRunStartMetadata(
 				? { accumulatedDurationMs }
 				: {}),
 			...(origin === "user" || origin === "agent" ? { origin } : {}),
+			...(budget !== undefined ? { budget } : {}),
+			...(budgetState !== undefined ? { budgetState } : {}),
 		};
 	}
 	return {};

package/dist/builtin/workflows/src/shared/persistence-restore.ts

@@ -217,6 +217,7 @@ export function restoreOnSessionStart(
 				status: "running",
 				stages,
 				startedAt: run.startTs,
+				...(blockedMeta.endedAt !== undefined ? { endedAt: blockedMeta.endedAt } : {}),
 				...(runMeta.parentRunId !== undefined ? { parentRunId: runMeta.parentRunId } : {}),
 				...(runMeta.parentStageId !== undefined ? { parentStageId: runMeta.parentStageId } : {}),
 				...(runMeta.rootRunId !== undefined ? { rootRunId: runMeta.rootRunId } : {}),
@@ -226,6 +227,8 @@ export function restoreOnSessionStart(
 				...(runMeta.accumulatedDurationMs !== undefined
 					? { accumulatedDurationMs: runMeta.accumulatedDurationMs }
 					: {}),
+				...(runMeta.budget !== undefined ? { budget: runMeta.budget } : {}),
+				...(blockedMeta.budgetState !== undefined ? { budgetState: blockedMeta.budgetState } : {}),
 			};
 			store.recordRunStart(runSnapshot);
 			store.recordRunBlocked(run.runId, blockedMeta.error, {
@@ -236,9 +239,12 @@ export function restoreOnSessionStart(
 					? { failureDisposition: blockedMeta.failureDisposition }
 					: {}),
 				...(blockedMeta.failureMessage !== undefined ? { failureMessage: blockedMeta.failureMessage } : {}),
-				failedStageId: blockedMeta.failedStageId,
+				...(blockedMeta.failedStageId !== undefined ? { failedStageId: blockedMeta.failedStageId } : {}),
 				resumable: true,
 				...(blockedMeta.retryAfterMs !== undefined ? { retryAfterMs: blockedMeta.retryAfterMs } : {}),
+				...(blockedMeta.endedAt !== undefined ? { endedAt: blockedMeta.endedAt } : {}),
+				...(blockedMeta.result !== undefined ? { result: blockedMeta.result } : {}),
+				...(blockedMeta.budgetState !== undefined ? { budgetState: blockedMeta.budgetState } : {}),
 				blockedAt: blockedMeta.ts,
 			});
 			continue;
@@ -259,6 +265,8 @@ export function restoreOnSessionStart(
 				...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
 				...(runMeta.origin !== undefined ? { origin: runMeta.origin } : {}),
 				...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
+				...(runMeta.budget !== undefined ? { budget: runMeta.budget } : {}),
+				...(runMeta.budgetState !== undefined ? { budgetState: runMeta.budgetState } : {}),
 				...(runMeta.accumulatedDurationMs !== undefined
 					? { accumulatedDurationMs: runMeta.accumulatedDurationMs }
 					: {}),
@@ -284,6 +292,8 @@ export function restoreOnSessionStart(
 				...(runMeta.resumedFromRunId !== undefined ? { resumedFromRunId: runMeta.resumedFromRunId } : {}),
 				...(runMeta.origin !== undefined ? { origin: runMeta.origin } : {}),
 				...(runMeta.resumeFromStageId !== undefined ? { resumeFromStageId: runMeta.resumeFromStageId } : {}),
+				...(runMeta.budget !== undefined ? { budget: runMeta.budget } : {}),
+				...(runMeta.budgetState !== undefined ? { budgetState: runMeta.budgetState } : {}),
 				...(runMeta.accumulatedDurationMs !== undefined
 					? { accumulatedDurationMs: runMeta.accumulatedDurationMs }
 					: {}),

package/dist/builtin/workflows/src/shared/persistence-session-entries.ts

@@ -13,7 +13,7 @@ import type {
 	WorkflowFailureDisposition,
 	WorkflowFailureKind,
 } from "./store-types.js";
-import type { WorkflowExitStatus, WorkflowInputValues, WorkflowOutputValues } from "./types.js";
+import type { WorkflowExitStatus, WorkflowInputValues, WorkflowModelAttempt, WorkflowOutputValues } from "./types.js";
 
 // ---------------------------------------------------------------------------
 // Structural API type (subset of ExtensionAPI needed here)
@@ -46,6 +46,8 @@ export interface RunStartPayload {
 	readonly resumeFromStageId?: string;
 	/** Elapsed ms inherited from prior sessions of a resumed run. */
 	readonly accumulatedDurationMs?: number;
+	readonly budget?: import("./store-types.js").RunBudgetSnapshot;
+	readonly budgetState?: import("./store-types.js").RunBudgetState;
 	readonly ts: number;
 }
 
@@ -94,6 +96,7 @@ export interface StageEndPayload {
 	readonly skippedReason?: string;
 	readonly sessionId?: string;
 	readonly sessionFile?: string;
+	readonly modelAttempts?: readonly WorkflowModelAttempt[];
 	readonly replayKey?: string;
 	readonly replayedFromStageId?: string;
 	readonly replayed?: boolean;
@@ -124,7 +127,7 @@ export interface RunEndPayload {
 
 export interface RunBlockedPayload {
 	readonly runId: string;
-	readonly failedStageId: string;
+	readonly failedStageId?: string;
 	readonly error: string;
 	readonly failureKind: WorkflowFailureKind;
 	readonly failureCode?: WorkflowFailureCode;
@@ -133,6 +136,9 @@ export interface RunBlockedPayload {
 	readonly failureDisposition?: WorkflowFailureDisposition;
 	readonly retryAfterMs?: number;
 	readonly resumable: true;
+	readonly endedAt?: number;
+	readonly result?: WorkflowOutputValues;
+	readonly budgetState?: import("./store-types.js").RunBudgetState;
 	readonly ts: number;
 }
 
@@ -157,6 +163,8 @@ export function appendRunStart(api: PersistenceAPI, payload: RunStartPayload): v
 		...(payload.origin !== undefined ? { origin: payload.origin } : {}),
 		...(payload.resumeFromStageId !== undefined ? { resumeFromStageId: payload.resumeFromStageId } : {}),
 		...(payload.accumulatedDurationMs !== undefined ? { accumulatedDurationMs: payload.accumulatedDurationMs } : {}),
+		...(payload.budget !== undefined ? { budget: payload.budget } : {}),
+		...(payload.budgetState !== undefined ? { budgetState: payload.budgetState } : {}),
 		ts: payload.ts,
 	});
 	if (entryId && typeof api.setLabel === "function") {
@@ -210,6 +218,7 @@ export function appendStageEnd(api: PersistenceAPI, payload: StageEndPayload, op
 		...(payload.skippedReason !== undefined ? { skippedReason: payload.skippedReason } : {}),
 		...(payload.sessionId !== undefined ? { sessionId: payload.sessionId } : {}),
 		...(payload.sessionFile !== undefined ? { sessionFile: payload.sessionFile } : {}),
+		...(payload.modelAttempts !== undefined ? { modelAttempts: payload.modelAttempts } : {}),
 		...(payload.replayKey !== undefined ? { replayKey: payload.replayKey } : {}),
 		...(payload.replayedFromStageId !== undefined ? { replayedFromStageId: payload.replayedFromStageId } : {}),
 		...(payload.replayed !== undefined ? { replayed: payload.replayed } : {}),
@@ -277,7 +286,7 @@ export function appendRunBlocked(api: PersistenceAPI, payload: RunBlockedPayload
 	if (typeof api.appendEntry !== "function") return;
 	api.appendEntry("workflow.run.blocked", {
 		runId: payload.runId,
-		failedStageId: payload.failedStageId,
+		...(payload.failedStageId !== undefined ? { failedStageId: payload.failedStageId } : {}),
 		error: payload.error,
 		failureKind: payload.failureKind,
 		...(payload.failureCode !== undefined ? { failureCode: payload.failureCode } : {}),
@@ -286,6 +295,9 @@ export function appendRunBlocked(api: PersistenceAPI, payload: RunBlockedPayload
 		...(payload.failureDisposition !== undefined ? { failureDisposition: payload.failureDisposition } : {}),
 		...(payload.retryAfterMs !== undefined ? { retryAfterMs: payload.retryAfterMs } : {}),
 		resumable: payload.resumable,
+		...(payload.endedAt !== undefined ? { endedAt: payload.endedAt } : {}),
+		...(payload.result !== undefined ? { result: payload.result } : {}),
+		...(payload.budgetState !== undefined ? { budgetState: payload.budgetState } : {}),
 		ts: payload.ts,
 	});
 }

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

@@ -2,7 +2,14 @@ import type { RunEndMetadata } from "./store-public-types.js";
 import type { RunSnapshot, RunStatus, StageSnapshot, WorkflowFailureKind } from "./store-types.js";
 import type { WorkflowOutputValues } from "./types.js";
 
-const RETURNED_BLOCKED_STATUSES = new Set(["blocked", "needs_human", "incomplete", "auth_blocked", "active"]);
+const RETURNED_BLOCKED_STATUSES = new Set([
+	"blocked",
+	"needs_human",
+	"incomplete",
+	"auth_blocked",
+	"budget_exceeded",
+	"active",
+]);
 
 export interface StructuredRecoverableWorkflowFailure {
 	readonly error: string;
@@ -47,8 +54,31 @@ export function structuredRecoverableWorkflowFailure(
 		| "failedStageId"
 		| "retryAfterMs"
 		| "stages"
+		| "result"
+		| "budgetState"
 	>,
 ): StructuredRecoverableWorkflowFailure | undefined {
+	const returnedStatus = normalizeReturnedWorkflowStatus(run.result?.status);
+	if (
+		returnedStatus === "budget_exceeded" &&
+		run.budgetState?.systemOwnedStop === true &&
+		run.failureDisposition === "active_blocked" &&
+		run.failureRecoverability === "recoverable"
+	) {
+		const error = run.error ?? run.failureMessage ?? "Workflow budget exceeded.";
+		return {
+			error,
+			metadata: {
+				...(run.failureCode !== undefined ? { failureCode: run.failureCode } : {}),
+				failureRecoverability: "recoverable",
+				failureDisposition: "active_blocked",
+				failureMessage: run.failureMessage ?? error,
+				...(run.failedStageId !== undefined ? { failedStageId: run.failedStageId } : {}),
+				resumable: true,
+				...(run.retryAfterMs !== undefined ? { retryAfterMs: run.retryAfterMs } : {}),
+			},
+		};
+	}
 	const runFailure = structuredRecoverableFailureFromSnapshot(run);
 	if (runFailure !== undefined) return runFailure;
 	if (run.failedStageId === undefined) return undefined;
@@ -69,19 +99,22 @@ export function structuredRecoverableWorkflowFailureText(
 		| "failedStageId"
 		| "retryAfterMs"
 		| "stages"
+		| "result"
+		| "budgetState"
 	>,
 ): string | undefined {
 	return structuredRecoverableWorkflowFailure(run)?.error;
 }
 
 export function effectiveRunStatus(run: RunSnapshot): RunStatus {
+	const returnedStatus = normalizeReturnedWorkflowStatus(run.result?.status);
 	if (
 		(run.status === "running" || run.status === "completed") &&
 		structuredRecoverableWorkflowFailure(run) !== undefined
 	)
 		return "blocked";
+	if (returnedStatus === "budget_exceeded") return run.status;
 	if (run.status !== "completed") return run.status;
-	const returnedStatus = normalizeReturnedWorkflowStatus(run.result?.status);
 	if (returnedStatus === "failed") return "failed";
 	if (returnedStatus !== undefined && isReturnedBlockedWorkflowStatus(returnedStatus)) return "blocked";
 	return run.status;

package/dist/builtin/workflows/src/shared/store-public-types.ts

@@ -61,9 +61,12 @@ export interface StageControlMetadata {
 
 export interface RunBlockedMetadata extends RunEndMetadata {
 	readonly failureRecoverability: "recoverable";
-	readonly failedStageId: string;
+	readonly failedStageId?: string;
 	readonly resumable: true;
 	readonly blockedAt?: number;
+	readonly endedAt?: number;
+	readonly result?: WorkflowOutputValues;
+	readonly budgetState?: import("./store-types.js").RunBudgetState;
 }
 
 export type StagePromptAnswerSource = "workflow_ui" | "workflow_tool";

package/dist/builtin/workflows/src/shared/store-run-methods.ts

@@ -141,10 +141,17 @@ export function createRunStoreMethods(context: StoreContext): RunStoreMethods {
 			run.failureRecoverability = metadata.failureRecoverability;
 			run.failureDisposition = metadata.failureDisposition;
 			run.failureMessage = metadata.failureMessage;
-			run.failedStageId = metadata.failedStageId;
+			if (metadata.failedStageId === undefined) delete run.failedStageId;
+			else run.failedStageId = metadata.failedStageId;
 			run.resumable = metadata.resumable;
 			run.blockedAt = metadata.blockedAt ?? Date.now();
+			if (metadata.endedAt !== undefined) {
+				run.endedAt = metadata.endedAt;
+				run.durationMs = elapsedRunMs(run, metadata.endedAt);
+			}
 			if (metadata.retryAfterMs !== undefined) run.retryAfterMs = metadata.retryAfterMs;
+			if (metadata.result !== undefined) run.result = metadata.result;
+			if (metadata.budgetState !== undefined) run.budgetState = metadata.budgetState;
 			context.bumpAndNotify();
 			return true;
 		},

package/dist/builtin/workflows/src/shared/store-stage-methods.ts

@@ -104,6 +104,7 @@ export function createStageStoreMethods(context: StoreContext): StageStoreMethod
 			existing.error = stage.error;
 			if (stage.sessionId !== undefined) existing.sessionId = stage.sessionId;
 			if (stage.sessionFile !== undefined) existing.sessionFile = stage.sessionFile;
+			if (stage.modelAttempts !== undefined) existing.modelAttempts = stage.modelAttempts;
 			existing.failureKind = stage.failureKind;
 			existing.failureCode = stage.failureCode;
 			existing.failureRecoverability = stage.failureRecoverability;

package/dist/builtin/workflows/src/shared/store-types.ts

@@ -3,6 +3,8 @@
  * cross-ref: spec §5.5
  */
 
+import type { BudgetDimension, BudgetReport, DurationBudgetReport, UsageBudgetReport } from "./budget.js";
+import type { RunMeterCounters } from "./budget-meter.js";
 import type {
 	WorkflowExitStatus,
 	WorkflowInputValues,
@@ -21,6 +23,25 @@ export type StageStatus =
 	| "failed"
 	| "skipped";
 
+export type RunBudgetSnapshot = Readonly<Record<"maxDurationMs" | "warnAtPercent", number>> &
+	Readonly<Partial<Record<"maxTokens" | "maxCost", number>>>;
+export type RunBudgetUsageBaseline = RunMeterCounters & { readonly cost: number };
+export type RunBudgetAccountingState = Readonly<Record<"tokens" | "cost", number>> & {
+	readonly baseline: RunBudgetUsageBaseline;
+	readonly perCounter: RunMeterCounters;
+};
+export interface RunBudgetState
+	extends Partial<Record<"warned" | "wrapUpDelivered" | "wrapUpCompleted" | "systemOwnedStop", boolean>> {
+	readonly duration?: DurationBudgetReport;
+	readonly tokens?: UsageBudgetReport & { readonly dimension: "tokens" };
+	readonly cost?: UsageBudgetReport & { readonly dimension: "cost" };
+	/** Latest warning retained for legacy consumers; `warnings` keeps each dimension. */
+	readonly warning?: BudgetReport;
+	readonly warnings?: Partial<Record<BudgetDimension, BudgetReport>>;
+	readonly accounting?: RunBudgetAccountingState;
+	readonly wrapUpSummary?: string;
+	readonly wrapUpUsage?: import("./types.js").WorkflowModelUsage;
+}
 export type ToolNodeStatus = "pending" | "running" | "completed" | "failed" | "cached" | "cancelled";
 
 /** First-class, durable graph node created for each ctx.tool invocation. */
@@ -307,6 +328,9 @@ export interface RunSnapshot {
 	readonly stages: StageSnapshot[];
 	/** Durable ctx.tool execution nodes. Optional only for legacy/restored snapshots. */
 	readonly toolNodes?: ToolNodeSnapshot[];
+	/** Resolved duration budget and persisted wrap-up state; omitted when unbudgeted. */
+	budget?: RunBudgetSnapshot;
+	budgetState?: RunBudgetState;
 	startedAt: number;
 	endedAt?: number;
 	durationMs?: number;

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

@@ -18,6 +18,7 @@ import type { TSchema } from "typebox";
 import type * as AuthoringContract from "./authoring-contract.js";
 import type { ToolNodeSnapshot } from "./store-types.js";
 
+export type { EffectiveBudget, ResolveBudgetLayers, WorkflowBudget } from "./budget.js";
 export type { AgentSessionEvent, ModelCycleResult, PromptOptions, TSchema, VerbatimCompactionResult };
 
 export type StageUserMessageContent = Parameters<AgentSession["sendUserMessage"]>[0];
@@ -108,6 +109,8 @@ export interface WorkflowRunChildOptions<TInputs extends WorkflowInputValues = W
 	readonly inputs?: TInputs;
 	/** Parent boundary stage display name. Defaults to workflow:<workflow-name>. */
 	readonly stageName?: string;
+	/** Additional subtree-scoped duration budget; parent run overrides do not flow here. */
+	readonly budget?: import("./budget.js").WorkflowBudget;
 }
 
 type WorkflowRequiredKeys<T extends object> = {

package/dist/builtin/workflows/src/shared/workflow-artifacts.ts

@@ -72,6 +72,7 @@ export function workflowRunResumeCandidate(run: RunSnapshot): WorkflowRunResumeC
 	return {
 		...run,
 		hasPausedState: workflowRunHasPausedState(run),
+		budgetSystemOwnedStop: run.budgetState?.systemOwnedStop === true,
 		...(hasDurableCheckpoint === undefined ? {} : { hasDurableCheckpoint }),
 		...(artifactsIntact === undefined ? {} : { artifactsIntact }),
 	};

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

@@ -1,5 +1,6 @@
 import type { Static, TOptional, TSchema } from "typebox";
 import type { WorkflowInputSchemaMap, WorkflowInputValues, WorkflowOutputSchemaMap, WorkflowOutputValues, WorkflowSerializableValue, WorkflowWorktreeInputBinding } from "./authoring-contract.js";
+import type { WorkflowBudget } from "./budget.js";
 type SchemaKeys<TSchemas> = keyof TSchemas & string;
 type Simplify<T> = {
     [K in keyof T]: T[K];
@@ -48,6 +49,8 @@ export interface AuthoredWorkflowSpec<TInputs extends WorkflowInputSchemaMap = R
     readonly name?: string;
     readonly autoAttach?: boolean;
     readonly heartbeatIntervalMinutes?: number;
+    /** Optional run budget for this workflow definition. */
+    readonly budget?: WorkflowBudget;
     readonly description: string;
     readonly inputs?: TInputs;
     readonly outputs: TOutputs;

package/dist/builtin/workflows/src/shared/workflow-authoring-types.ts

@@ -8,6 +8,7 @@ import type {
 	WorkflowSerializableValue,
 	WorkflowWorktreeInputBinding,
 } from "./authoring-contract.js";
+import type { WorkflowBudget } from "./budget.js";
 
 type SchemaKeys<TSchemas> = keyof TSchemas & string;
 type Simplify<T> = { [K in keyof T]: T[K] } & {};
@@ -98,6 +99,8 @@ export interface AuthoredWorkflowSpec<
 	readonly name?: string;
 	readonly autoAttach?: boolean;
 	readonly heartbeatIntervalMinutes?: number;
+	/** Optional run budget for this workflow definition. */
+	readonly budget?: WorkflowBudget;
 	readonly description: string;
 	readonly inputs?: TInputs;
 	readonly outputs: TOutputs;

package/dist/core/atomic-guide-command.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"atomic-guide-command.d.ts","sourceRoot":"","sources":["../../src/core/atomic-guide-command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AA4NnF,QAAA,MAAM,cAAc;mBAEZ,UAAU;;oBAET,UAAU;0BACJ,oBAAoB;;;mBAI3B,WAAW;;oBAEV,WAAW;0BACL,iBAAiB;;;mBAIxB,SAAS;;oBAER,SAAS;0BACH,0BAA0B;;;mBAIjC,WAAW;;oBAEV,YAAY;0BACN,sBAAsB;;EASlC,CAAC;AAEJ,KAAK,kBAAkB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,KAAK,sBAAsB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE9D,eAAO,MAAM,yBAAyB,EAAE,SAAS,qBAAqB,EAErE,CAAC;AAcF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAEvF;AA6BD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAKtE;AAED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,GAAG,IAAI,CAW3F;AAED,iBAAS,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CActD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAEvF"}
+{"version":3,"file":"atomic-guide-command.d.ts","sourceRoot":"","sources":["../../src/core/atomic-guide-command.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAG/D,eAAO,MAAM,yBAAyB,WAAW,CAAC;AAClD,eAAO,MAAM,gCAAgC,qCAAqC,CAAC;AA6NnF,QAAA,MAAM,cAAc;mBAEZ,UAAU;;oBAET,UAAU;0BACJ,oBAAoB;;;mBAI3B,WAAW;;oBAEV,WAAW;0BACL,iBAAiB;;;mBAIxB,SAAS;;oBAER,SAAS;0BACH,0BAA0B;;;mBAIjC,WAAW;;oBAEV,YAAY;0BACN,sBAAsB;;EASlC,CAAC;AAEJ,KAAK,kBAAkB,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAC1D,KAAK,sBAAsB,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;AAEzD,MAAM,MAAM,qBAAqB,GAAG,kBAAkB,CAAC,OAAO,CAAC,CAAC;AAEhE,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,sBAAsB,CAAC;AAE9D,eAAO,MAAM,yBAAyB,EAAE,SAAS,qBAAqB,EAErE,CAAC;AAcF,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,IAAI,qBAAqB,CAEvF;AA6BD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAKtE;AAED,wBAAgB,iCAAiC,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE,GAAG,IAAI,CAW3F;AAED,iBAAS,yBAAyB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CActD;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,eAAe,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAGhF;AAED,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,eAAe,CAEvF"}

package/dist/core/atomic-guide-command.js

@@ -54,6 +54,7 @@ Use \`/workflow list\` to see what is available and \`/workflow inputs <name>\`
 | \`prompt-engineer\` | tighten a vague prompt before a long run | \`/skill:prompt-engineer Draft a sharper implementation prompt for ...\` |
 | \`subagent\` | learn delegation patterns and exact \`/run\` and \`/parallel\` usage | \`/skill:subagent\` |
 | \`impeccable\` | critique or refine frontend and product UI | \`/skill:impeccable\` |
+| \`show-me\` | explain a topic visually with concise diagrams, code-shape sketches, or focused HTML artifacts (HumanLayer, MIT) | \`/skill:show-me\` |
 
 ## Subagents