@warlock.js/ai 4.2.11 → 4.4.0

package/esm/middleware/builtins/budget-contract.type.d.mts

@@ -0,0 +1,126 @@
+import { MiddlewareExecuteContext } from "../../contracts/middleware/middleware-context.type.mjs";
+//#region ../@warlock.js/ai/src/middleware/builtins/budget-contract.type.d.ts
+/**
+ * Which SLO dimension of a {@link BudgetContract} a breach belongs to.
+ *
+ * Distinct from `BudgetUnit` (`"tokens" | "usd" | "requests"`) on the
+ * error: `BudgetUnit` is the measurement unit, `BudgetContractDimension`
+ * is the *contract clause* that tripped. They line up for tokens / cost
+ * but diverge for latency — which has no `BudgetUnit` of its own, so a
+ * latency breach surfaces its authoritative detail through the error's
+ * `context.dimension` rather than `error.unit`.
+ */
+type BudgetContractDimension = "tokens" | "cost" | "latency";
+/**
+ * What the middleware does when a {@link BudgetContract} clause is
+ * breached.
+ *
+ * - `"abort"` — throw `BudgetExceededError`, stopping the run at the
+ *   next trip boundary (`result.error` is populated; `execute()` itself
+ *   still never throws). The same hard-stop semantics as the legacy
+ *   `onExceeded: "abort"` path.
+ * - `"fallback"` — do NOT abort. Record a typed {@link BudgetContractViolation}
+ *   signal in the middleware state bag (read it back with
+ *   `readBudgetFallbackSignal`) and invoke the optional `fallback`
+ *   callback, then let the run continue. The middleware cannot itself
+ *   swap models, so a fallback orchestrator / outer layer reads the
+ *   signal and decides how to degrade (cheaper model, cached answer,
+ *   truncated context).
+ */
+type BudgetContractViolationMode = "abort" | "fallback";
+/**
+ * A single recorded breach of a {@link BudgetContract} clause. Captured
+ * verbatim so a fallback layer can branch on the exact dimension and the
+ * numbers that tripped it without re-parsing a message string.
+ *
+ * `limit` and `actual` share the dimension's natural unit: tokens for
+ * `"tokens"`, USD for `"cost"`, milliseconds for `"latency"`.
+ */
+type BudgetContractViolation = {
+  /** Which contract clause tripped. */dimension: BudgetContractDimension; /** The configured cap for the breached dimension. */
+  limit: number; /** The cumulative actual value at the moment of breach. */
+  actual: number; /** Resolved behavior for this breach — mirrors the contract's `onViolation`. */
+  mode: BudgetContractViolationMode;
+};
+/**
+ * Callback fired once when a {@link BudgetContract} clause is breached
+ * under `onViolation: "fallback"`. Receives the recorded violation plus
+ * the run's `execute`-level context so the consumer can read agent /
+ * model identity and the shared state bag.
+ *
+ * Purely a notification hook — its return value is ignored and it cannot
+ * abort the run (throw a typed `AIError` from a guardrail / custom
+ * middleware if a hard stop is required instead). Errors thrown here are
+ * swallowed by the budget middleware so a misbehaving callback cannot
+ * crash the run.
+ */
+type BudgetContractFallback = (violation: BudgetContractViolation, context: MiddlewareExecuteContext) => void | Promise<void>;
+/**
+ * Declarative service-level objective for a single agent run, enforced
+ * by the budget middleware on top of (and independently of) the legacy
+ * `maxTokens` / `maxCostUSD` caps.
+ *
+ * **Role.** Lets a team express a run-level SLO — "this run must cost
+ * under $0.05, finish under 8s, and burn under 40k tokens" — as data,
+ * then pick one global reaction (`abort` hard, or `fallback` soft) for
+ * any clause that trips. The contract is the cost/latency budget the
+ * caller is willing to spend; breaching it is an operational event, not
+ * a user error.
+ *
+ * **Clauses.** Every cap is optional; supply only the dimensions you
+ * care about. A contract with no caps is inert. `maxCostUSD` still needs
+ * a `pricing` entry on `budget()` for the running model — without one,
+ * the cost clause silently degrades (tokens / latency clauses keep
+ * enforcing).
+ *
+ * **Latency.** Wall-clock milliseconds measured from the first
+ * `execute.before` to each `trip.after`. Has no `BudgetUnit`, so a
+ * latency abort surfaces its numbers through the thrown error's
+ * `context` (`{ dimension: "latency", limit, actual }`) rather than
+ * `error.unit`.
+ *
+ * @example
+ * const guard = budget({
+ *   pricing: { "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 } },
+ *   contract: {
+ *     maxCostUSD: 0.05,
+ *     maxLatencyMs: 8_000,
+ *     maxTokens: 40_000,
+ *     onViolation: "fallback",
+ *     fallback: (violation) => routeToCheaperModel(violation.dimension),
+ *   },
+ * });
+ */
+type BudgetContract = {
+  /**
+   * Cumulative total-token cap for the run. Independent of the
+   * top-level `BudgetOptions.maxTokens`; whichever trips first wins.
+   */
+  maxTokens?: number;
+  /**
+   * Cumulative USD-cost cap for the run. Requires `BudgetOptions.pricing`
+   * for the running model — degrades silently without it, same as the
+   * legacy cost cap.
+   */
+  maxCostUSD?: number;
+  /**
+   * Wall-clock latency cap in milliseconds, measured from the run start
+   * to each completed trip. Breached when cumulative elapsed time
+   * exceeds the cap at a trip boundary.
+   */
+  maxLatencyMs?: number;
+  /**
+   * Reaction applied to every clause of this contract. Default
+   * `"abort"`. `"fallback"` records a signal + fires `fallback` and
+   * lets the run continue.
+   */
+  onViolation?: BudgetContractViolationMode;
+  /**
+   * Notification callback fired on the first breach under
+   * `onViolation: "fallback"`. Ignored when `onViolation` is `"abort"`.
+   */
+  fallback?: BudgetContractFallback;
+};
+//#endregion
+export { BudgetContract, BudgetContractDimension, BudgetContractFallback, BudgetContractViolation, BudgetContractViolationMode };
+//# sourceMappingURL=budget-contract.type.d.mts.map

package/esm/middleware/builtins/budget-contract.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-contract.type.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget-contract.type.ts"],"mappings":";;;;;AAYA;;;;AAAmC;AAkBnC;;KAlBY,uBAAA;;AAkB2B;AAUvC;;;;;;;;;;;AAQmC;AAenC;;KAjCY,2BAAA;;;;;;;;;KAUA,uBAAA;EA0BA,qCAxBV,SAAA,EAAW,uBAAA,EAwBM;EAtBjB,KAAA,UA4DwB;EA1DxB,MAAA,UAsFiC;EApFjC,IAAA,EAAM,2BAA2B;AAAA;;;;;;;AAoFA;;;;;;KArEvB,sBAAA,IACV,SAAA,EAAW,uBAAA,EACX,OAAA,EAAS,wBAAA,YACC,OAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KAsCA,cAAA;;;;;EAKV,SAAA;;;;;;EAMA,UAAA;;;;;;EAMA,YAAA;;;;;;EAMA,WAAA,GAAc,2BAAA;;;;;EAKd,QAAA,GAAW,sBAAsB;AAAA"}

package/esm/middleware/builtins/budget.d.mts

@@ -1,4 +1,7 @@
+import { MiddlewareExecuteContext } from "../../contracts/middleware/middleware-context.type.mjs";
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
+import { BudgetContract, BudgetContractDimension, BudgetContractFallback, BudgetContractViolation, BudgetContractViolationMode } from "./budget-contract.type.mjs";
+
 //#region ../@warlock.js/ai/src/middleware/builtins/budget.d.ts
 /**
  * Per-model pricing used to compute USD cost from token counts.
@@ -48,7 +51,51 @@ type BudgetOptions = {
    * instances). Default `"budget"`.
    */
   name?: string;
+  /**
+   * Declarative SLO / cost contract enforced on top of (and
+   * independently of) the legacy `maxTokens` / `maxCostUSD` caps.
+   * Adds a wall-clock `maxLatencyMs` dimension and a per-contract
+   * `onViolation` reaction (`"abort"` hard-stops, `"fallback"` records
+   * a signal + fires `fallback` and lets the run continue). Omit to
+   * keep the classic budget behavior unchanged.
+   *
+   * Read a recorded fallback signal back with
+   * {@link readBudgetFallbackSignal}.
+   */
+  contract?: BudgetContract;
 };
+/**
+ * Recorded contract fallback signal, stashed under the `<name>.fallback`
+ * state key when a `"fallback"` clause trips. A fallback orchestrator
+ * reads it via {@link readBudgetFallbackSignal} to decide how to degrade.
+ */
+type BudgetFallbackSignal = BudgetContractViolation;
+/**
+ * Read the contract fallback signal recorded by a `budget()` middleware
+ * running under `contract.onViolation: "fallback"`. Returns `undefined`
+ * when no clause was breached.
+ *
+ * **Role.** The middleware cannot itself switch models on a soft breach,
+ * so it records a typed {@link BudgetFallbackSignal} in the shared state
+ * bag and lets the run continue. A fallback orchestrator (or the
+ * `execute.after` hook of an outer middleware) reads it back here and
+ * decides how to degrade the next run — cheaper model, cached answer,
+ * truncated context.
+ *
+ * @param state - The middleware state bag (`ctx.state`).
+ * @param name - The budget middleware's name. Default `"budget"`,
+ *   matching `BudgetOptions.name`'s default.
+ *
+ * @example
+ * const guard = budget({ contract: { maxCostUSD: 0.05, onViolation: "fallback" } });
+ *
+ * // In an outer middleware's execute.after, after the run:
+ * const signal = readBudgetFallbackSignal(ctx.state);
+ * if (signal?.dimension === "cost") {
+ *   await rerunOnCheaperModel();
+ * }
+ */
+declare function readBudgetFallbackSignal(state: MiddlewareExecuteContext["state"], name?: string): BudgetFallbackSignal | undefined;
 /**
  * Enforced token and / or USD budget for an agent run.
  *
@@ -80,6 +127,16 @@ type BudgetOptions = {
  * measuring real-world traffic against a proposed cap before flipping
  * to `"abort"` in production.
  *
+ * **Contract / SLO mode.** Pass `contract` to enforce a declarative
+ * service-level objective — `maxCostUSD`, `maxLatencyMs`, `maxTokens` —
+ * on top of the legacy caps, with a single `onViolation` reaction:
+ * `"abort"` hard-stops with `BudgetExceededError`; `"fallback"` records
+ * a typed signal (read it via {@link readBudgetFallbackSignal}), fires
+ * the optional `fallback` callback, and lets the run continue so an
+ * outer layer can degrade gracefully. The contract's clauses are
+ * evaluated independently of — and after — the top-level caps; the
+ * top-level caps stay fully functional with or without a contract.
+ *
  * @example
  * const budgetMiddleware = budget({ maxTokens: 50_000 });
  *
@@ -96,8 +153,21 @@ type BudgetOptions = {
  *     "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 },
  *   },
  * });
+ *
+ * @example
+ * // SLO contract — soft-fallback on any breach
+ * const sloGuard = budget({
+ *   pricing: { "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 } },
+ *   contract: {
+ *     maxCostUSD: 0.05,
+ *     maxLatencyMs: 8_000,
+ *     maxTokens: 40_000,
+ *     onViolation: "fallback",
+ *     fallback: (violation) => routeToCheaperModel(violation.dimension),
+ *   },
+ * });
  */
 declare function budget(options: BudgetOptions): AgentMiddleware;
 //#endregion
-export { BudgetOptions, BudgetPricing, budget };
+export { BudgetFallbackSignal, BudgetOptions, BudgetPricing, budget, readBudgetFallbackSignal };
 //# sourceMappingURL=budget.d.mts.map

package/esm/middleware/builtins/budget.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"budget.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget.ts"],"mappings":";;;;;AAWA;;;;KAAY,aAAA,GAAgB,MAAM;EAI9B,kCAAA,UAAA,UAEW;EAAX,WAAA;AAAA;;;;;KAQQ,aAAA;EAkBV;;;;;EAZA,SAAA;EA+Fc;;;;;EAzFd,UAAA;EAyF8C;;AAAe;;;EAnF7D,OAAA,GAAU,aAAa;;;;;;;;EAQvB,UAAA;;;;;;EAMA,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAqEc,MAAA,CAAO,OAAA,EAAS,aAAA,GAAgB,eAAe"}
+{"version":3,"file":"budget.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget.ts"],"mappings":";;;;;;;;AA2BA;;;;KAAY,aAAA,GAAgB,MAAM;EAI9B,kCAAA,UAAA,UAEW;EAAX,WAAA;AAAA;;;;;KAQQ,aAAA;EAkBV;;;;;EAZA,SAAA;EAsCyB;AAAA;AAyB3B;;;EAzDE,UAAA;EAyDwD;AAoE1D;;;;EAvHE,OAAA,GAAU,aAAA;EAwHV;;;;AAEqB;AA8EvB;;EAhME,UAAA;EAgM6D;;;;;EA1L7D,IAAA;;;;;;;;;;;;EAYA,QAAA,GAAW,cAAc;AAAA;;;;;;KAyBf,oBAAA,GAAuB,uBAAuB;;;;;;;;;;;;;;;;;;;;;;;;;;iBAoE1C,wBAAA,CACd,KAAA,EAAO,wBAAA,WACP,IAAA,YACC,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBA8EP,MAAA,CAAO,OAAA,EAAS,aAAA,GAAgB,eAAe"}

package/esm/middleware/builtins/budget.mjs

@@ -3,6 +3,17 @@ import "../../errors/index.mjs";
 import { namespacedState } from "../utils/namespaced-state.mjs";
 
 //#region ../@warlock.js/ai/src/middleware/builtins/budget.ts
+/**
+* The `BudgetUnit` to stamp on the thrown error per contract dimension.
+* Latency has no native unit — it borrows `"requests"` as the least-wrong
+* operational measure, while the authoritative detail rides on the
+* error's `context.dimension`.
+*/
+const DIMENSION_UNIT = {
+	tokens: "tokens",
+	cost: "usd",
+	latency: "requests"
+};
 function breach(limit, actual, unit, name) {
 	throw new BudgetExceededError(`budget "${name}" exceeded — ${actual} ${unit} (cap: ${limit})`, {
 		limit,
@@ -10,6 +21,47 @@ function breach(limit, actual, unit, name) {
 		unit
 	});
 }
+function breachContract(name, dimension, limit, actual) {
+	throw new BudgetExceededError(`budget "${name}" contract exceeded — ${dimension} ${actual} (cap: ${limit})`, {
+		limit,
+		actual,
+		unit: DIMENSION_UNIT[dimension],
+		context: {
+			dimension,
+			limit,
+			actual,
+			source: "contract"
+		}
+	});
+}
+/**
+* Read the contract fallback signal recorded by a `budget()` middleware
+* running under `contract.onViolation: "fallback"`. Returns `undefined`
+* when no clause was breached.
+*
+* **Role.** The middleware cannot itself switch models on a soft breach,
+* so it records a typed {@link BudgetFallbackSignal} in the shared state
+* bag and lets the run continue. A fallback orchestrator (or the
+* `execute.after` hook of an outer middleware) reads it back here and
+* decides how to degrade the next run — cheaper model, cached answer,
+* truncated context.
+*
+* @param state - The middleware state bag (`ctx.state`).
+* @param name - The budget middleware's name. Default `"budget"`,
+*   matching `BudgetOptions.name`'s default.
+*
+* @example
+* const guard = budget({ contract: { maxCostUSD: 0.05, onViolation: "fallback" } });
+*
+* // In an outer middleware's execute.after, after the run:
+* const signal = readBudgetFallbackSignal(ctx.state);
+* if (signal?.dimension === "cost") {
+*   await rerunOnCheaperModel();
+* }
+*/
+function readBudgetFallbackSignal(state, name = "budget") {
+	return namespacedState({ state }, `${name}.fallback`).get();
+}
 /**
 * Enforced token and / or USD budget for an agent run.
 *
@@ -41,6 +93,16 @@ function breach(limit, actual, unit, name) {
 * measuring real-world traffic against a proposed cap before flipping
 * to `"abort"` in production.
 *
+* **Contract / SLO mode.** Pass `contract` to enforce a declarative
+* service-level objective — `maxCostUSD`, `maxLatencyMs`, `maxTokens` —
+* on top of the legacy caps, with a single `onViolation` reaction:
+* `"abort"` hard-stops with `BudgetExceededError`; `"fallback"` records
+* a typed signal (read it via {@link readBudgetFallbackSignal}), fires
+* the optional `fallback` callback, and lets the run continue so an
+* outer layer can degrade gracefully. The contract's clauses are
+* evaluated independently of — and after — the top-level caps; the
+* top-level caps stay fully functional with or without a contract.
+*
 * @example
 * const budgetMiddleware = budget({ maxTokens: 50_000 });
 *
@@ -57,26 +119,47 @@ function breach(limit, actual, unit, name) {
 *     "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 },
 *   },
 * });
+*
+* @example
+* // SLO contract — soft-fallback on any breach
+* const sloGuard = budget({
+*   pricing: { "gpt-4o": { inputPer1K: 0.005, outputPer1K: 0.015 } },
+*   contract: {
+*     maxCostUSD: 0.05,
+*     maxLatencyMs: 8_000,
+*     maxTokens: 40_000,
+*     onViolation: "fallback",
+*     fallback: (violation) => routeToCheaperModel(violation.dimension),
+*   },
+* });
 */
 function budget(options) {
 	const name = options.name ?? "budget";
 	const onExceeded = options.onExceeded ?? "abort";
 	const hasTokenCap = typeof options.maxTokens === "number";
 	const hasCostCap = typeof options.maxCostUSD === "number";
+	const contract = options.contract;
+	const contractMode = contract?.onViolation ?? "abort";
+	const hasContractTokenCap = typeof contract?.maxTokens === "number";
+	const hasContractCostCap = typeof contract?.maxCostUSD === "number";
+	const hasContractLatencyCap = typeof contract?.maxLatencyMs === "number";
+	const contractNeedsCost = hasCostCap || hasContractCostCap;
 	return {
 		name,
 		execute: { before(context) {
 			namespacedState(context, name).set({
 				tokens: 0,
 				costUSD: 0,
-				warned: false
+				warned: false,
+				startedAt: Date.now(),
+				fallbackFired: false
 			});
 		} },
-		trip: { after(context, response) {
+		trip: { async after(context, response) {
 			const counters = namespacedState(context, name).get();
 			if (!counters) return;
 			counters.tokens += response.usage.total;
-			if (hasCostCap && options.pricing) {
+			if (contractNeedsCost && options.pricing) {
 				const pricing = options.pricing[context.model.name];
 				if (pricing) {
 					const tripCost = response.usage.input / 1e3 * pricing.inputPer1K + response.usage.output / 1e3 * pricing.outputPer1K;
@@ -91,10 +174,42 @@ function budget(options) {
 				if (onExceeded === "abort") breach(options.maxCostUSD, counters.costUSD, "usd", name);
 				if (!counters.warned) counters.warned = true;
 			}
+			if (!contract) return;
+			if (hasContractTokenCap && counters.tokens > contract.maxTokens) await enforceContract(context, counters, name, contractMode, contract, "tokens", contract.maxTokens, counters.tokens);
+			if (hasContractCostCap && counters.costUSD > contract.maxCostUSD) await enforceContract(context, counters, name, contractMode, contract, "cost", contract.maxCostUSD, counters.costUSD);
+			if (hasContractLatencyCap) {
+				const elapsedMs = Date.now() - counters.startedAt;
+				if (elapsedMs > contract.maxLatencyMs) await enforceContract(context, counters, name, contractMode, contract, "latency", contract.maxLatencyMs, elapsedMs);
+			}
 		} }
 	};
 }
+/**
+* Apply the contract's reaction to a single breached clause. `"abort"`
+* throws `BudgetExceededError` (stops the run); `"fallback"` records the
+* signal once, fires the callback, and returns so the run continues.
+*
+* The callback is invoked at most once per run (guarded by
+* `counters.fallbackFired`) and its rejections are swallowed — a buggy
+* fallback hook must never crash the agent.
+*/
+async function enforceContract(context, counters, name, mode, contract, dimension, limit, actual) {
+	if (mode === "abort") breachContract(name, dimension, limit, actual);
+	if (counters.fallbackFired) return;
+	counters.fallbackFired = true;
+	const violation = {
+		dimension,
+		limit,
+		actual,
+		mode
+	};
+	namespacedState(context, `${name}.fallback`).set(violation);
+	if (!contract.fallback) return;
+	try {
+		await contract.fallback(violation, context);
+	} catch {}
+}
 
 //#endregion
-export { budget };
+export { budget, readBudgetFallbackSignal };
 //# sourceMappingURL=budget.mjs.map

package/esm/middleware/builtins/budget.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"budget.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../../contracts/middleware\";\nimport { BudgetExceededError, type BudgetUnit } from \"../../errors\";\nimport { namespacedState } from \"../utils\";\n\n/**\n * Per-model pricing used to compute USD cost from token counts.\n * Caller-supplied — no bundled table. Keys are model names (the\n * `ModelContract.name` value); values are input / output token\n * prices expressed as **USD per 1K tokens** to match every major\n * provider's published pricing sheet.\n */\nexport type BudgetPricing = Record<\n  string,\n  {\n    /** USD per 1,000 input tokens. */\n    inputPer1K: number;\n    /** USD per 1,000 output tokens. */\n    outputPer1K: number;\n  }\n>;\n\n/**\n * Configuration for `budget()`. At least one of `maxTokens` or\n * `maxCostUSD` must be supplied — a budget with no cap is a no-op.\n */\nexport type BudgetOptions = {\n  /**\n   * Hard cap on cumulative total tokens (input + output, summed\n   * across every trip of the run). Inclusive — exceeding triggers\n   * the configured `onExceeded`.\n   */\n  maxTokens?: number;\n  /**\n   * Hard cap on cumulative USD cost. Requires `pricing` for the\n   * agent's configured model — without a pricing entry the USD check\n   * silently skips (tokens-only enforcement still applies).\n   */\n  maxCostUSD?: number;\n  /**\n   * Per-model pricing table used to compute USD cost. Only consulted\n   * when `maxCostUSD` is set. Model names must match the running\n   * agent's `ModelContract.name` exactly.\n   */\n  pricing?: BudgetPricing;\n  /**\n   * Behavior when a cap is breached. `\"abort\"` throws\n   * `BudgetExceededError` — surfaces on `result.error`, stops the\n   * run at the next trip boundary. `\"warn\"` logs a warning and\n   * lets the run continue (useful for observability-first rollouts\n   * before flipping the switch to abort). Default `\"abort\"`.\n   */\n  onExceeded?: \"abort\" | \"warn\";\n  /**\n   * Override the middleware name. Useful when two budgets coexist\n   * (e.g. a per-request cap plus a session-wide cap via different\n   * instances). Default `\"budget\"`.\n   */\n  name?: string;\n};\n\ntype BudgetCounters = {\n  tokens: number;\n  costUSD: number;\n  warned: boolean;\n};\n\nfunction breach(\n  limit: number,\n  actual: number,\n  unit: BudgetUnit,\n  name: string,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" exceeded — ${actual} ${unit} (cap: ${limit})`,\n    { limit, actual, unit },\n  );\n}\n\n/**\n * Enforced token and / or USD budget for an agent run.\n *\n * **Role.** Guards against runaway tool loops, misconfigured\n * prompts, and unexpected provider price swings by capping\n * cumulative usage across every LLM trip of a single execution.\n * Aborts the run with a typed `BudgetExceededError` the moment a cap\n * is breached, rather than letting the damage grow trip by trip.\n *\n * **Scope.** Per-execution. A fresh counter is created at\n * `execute.before` and lives in the middleware state bag until the\n * run ends. Two concurrent `agent.execute()` calls on the same\n * agent therefore enforce the cap independently.\n *\n * **Token accounting.** After each successful trip, the middleware\n * adds `response.usage.total` to its running total and checks\n * against `maxTokens`. Synthetic trips (cache hits) contribute\n * `usage.total` as returned by the cache — cache middleware is\n * expected to surface zero usage on a hit, which naturally excludes\n * those trips from the budget.\n *\n * **USD accounting.** When `maxCostUSD` + `pricing[modelName]` are\n * both present, the middleware converts per-trip input / output\n * tokens to USD and accumulates. Missing pricing silently degrades\n * to tokens-only — explicit rather than guessing.\n *\n * **Warn mode.** `onExceeded: \"warn\"` logs a single warning the first\n * time a cap is breached and lets the run continue. Useful for\n * measuring real-world traffic against a proposed cap before flipping\n * to `\"abort\"` in production.\n *\n * @example\n * const budgetMiddleware = budget({ maxTokens: 50_000 });\n *\n * const myAgent = agent({\n *   model,\n *   middleware: [budgetMiddleware],\n * });\n *\n * @example\n * // With USD cap and custom pricing\n * const guard = budget({\n *   maxCostUSD: 0.5,\n *   pricing: {\n *     \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 },\n *   },\n * });\n */\nexport function budget(options: BudgetOptions): AgentMiddleware {\n  const name = options.name ?? \"budget\";\n  const onExceeded = options.onExceeded ?? \"abort\";\n  const hasTokenCap = typeof options.maxTokens === \"number\";\n  const hasCostCap = typeof options.maxCostUSD === \"number\";\n\n  return {\n    name,\n    execute: {\n      before(context) {\n        const counters = namespacedState<BudgetCounters>(context, name);\n        counters.set({ tokens: 0, costUSD: 0, warned: false });\n      },\n    },\n    trip: {\n      after(context, response) {\n        const counters = namespacedState<BudgetCounters>(context, name).get();\n\n        if (!counters) {\n          return;\n        }\n\n        counters.tokens += response.usage.total;\n\n        if (hasCostCap && options.pricing) {\n          const pricing = options.pricing[context.model.name];\n\n          if (pricing) {\n            const tripCost =\n              (response.usage.input / 1000) * pricing.inputPer1K +\n              (response.usage.output / 1000) * pricing.outputPer1K;\n            counters.costUSD += tripCost;\n          }\n        }\n\n        if (hasTokenCap && counters.tokens > options.maxTokens!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxTokens!, counters.tokens, \"tokens\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (hasCostCap && counters.costUSD > options.maxCostUSD!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxCostUSD!, counters.costUSD, \"usd\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n      },\n    },\n  };\n}\n"],"mappings":";;;;;AAkEA,SAAS,OACP,OACA,QACA,MACA,MACO;CACP,MAAM,IAAI,oBACR,WAAW,KAAK,eAAe,OAAO,GAAG,KAAK,SAAS,MAAM,IAC7D;EAAE;EAAO;EAAQ;CAAK,CACxB;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,SAAgB,OAAO,SAAyC;CAC9D,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,cAAc,OAAO,QAAQ,cAAc;CACjD,MAAM,aAAa,OAAO,QAAQ,eAAe;CAEjD,OAAO;EACL;EACA,SAAS,EACP,OAAO,SAAS;GAEd,AADiB,gBAAgC,SAAS,IACnD,CAAC,CAAC,IAAI;IAAE,QAAQ;IAAG,SAAS;IAAG,QAAQ;GAAM,CAAC;EACvD,EACF;EACA,MAAM,EACJ,MAAM,SAAS,UAAU;GACvB,MAAM,WAAW,gBAAgC,SAAS,IAAI,CAAC,CAAC,IAAI;GAEpE,IAAI,CAAC,UACH;GAGF,SAAS,UAAU,SAAS,MAAM;GAElC,IAAI,cAAc,QAAQ,SAAS;IACjC,MAAM,UAAU,QAAQ,QAAQ,QAAQ,MAAM;IAE9C,IAAI,SAAS;KACX,MAAM,WACH,SAAS,MAAM,QAAQ,MAAQ,QAAQ,aACvC,SAAS,MAAM,SAAS,MAAQ,QAAQ;KAC3C,SAAS,WAAW;IACtB;GACF;GAEA,IAAI,eAAe,SAAS,SAAS,QAAQ,WAAY;IACvD,IAAI,eAAe,SACjB,OAAO,QAAQ,WAAY,SAAS,QAAQ,UAAU,IAAI;IAG5D,IAAI,CAAC,SAAS,QACZ,SAAS,SAAS;GAEtB;GAEA,IAAI,cAAc,SAAS,UAAU,QAAQ,YAAa;IACxD,IAAI,eAAe,SACjB,OAAO,QAAQ,YAAa,SAAS,SAAS,OAAO,IAAI;IAG3D,IAAI,CAAC,SAAS,QACZ,SAAS,SAAS;GAEtB;EACF,EACF;CACF;AACF"}
+{"version":3,"file":"budget.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/budget.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareExecuteContext,\n} from \"../../contracts/middleware\";\nimport { BudgetExceededError, type BudgetUnit } from \"../../errors\";\nimport { namespacedState } from \"../utils\";\nimport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractViolation,\n} from \"./budget-contract.type\";\n\nexport type {\n  BudgetContract,\n  BudgetContractDimension,\n  BudgetContractFallback,\n  BudgetContractViolation,\n  BudgetContractViolationMode,\n} from \"./budget-contract.type\";\n\n/**\n * Per-model pricing used to compute USD cost from token counts.\n * Caller-supplied — no bundled table. Keys are model names (the\n * `ModelContract.name` value); values are input / output token\n * prices expressed as **USD per 1K tokens** to match every major\n * provider's published pricing sheet.\n */\nexport type BudgetPricing = Record<\n  string,\n  {\n    /** USD per 1,000 input tokens. */\n    inputPer1K: number;\n    /** USD per 1,000 output tokens. */\n    outputPer1K: number;\n  }\n>;\n\n/**\n * Configuration for `budget()`. At least one of `maxTokens` or\n * `maxCostUSD` must be supplied — a budget with no cap is a no-op.\n */\nexport type BudgetOptions = {\n  /**\n   * Hard cap on cumulative total tokens (input + output, summed\n   * across every trip of the run). Inclusive — exceeding triggers\n   * the configured `onExceeded`.\n   */\n  maxTokens?: number;\n  /**\n   * Hard cap on cumulative USD cost. Requires `pricing` for the\n   * agent's configured model — without a pricing entry the USD check\n   * silently skips (tokens-only enforcement still applies).\n   */\n  maxCostUSD?: number;\n  /**\n   * Per-model pricing table used to compute USD cost. Only consulted\n   * when `maxCostUSD` is set. Model names must match the running\n   * agent's `ModelContract.name` exactly.\n   */\n  pricing?: BudgetPricing;\n  /**\n   * Behavior when a cap is breached. `\"abort\"` throws\n   * `BudgetExceededError` — surfaces on `result.error`, stops the\n   * run at the next trip boundary. `\"warn\"` logs a warning and\n   * lets the run continue (useful for observability-first rollouts\n   * before flipping the switch to abort). Default `\"abort\"`.\n   */\n  onExceeded?: \"abort\" | \"warn\";\n  /**\n   * Override the middleware name. Useful when two budgets coexist\n   * (e.g. a per-request cap plus a session-wide cap via different\n   * instances). Default `\"budget\"`.\n   */\n  name?: string;\n  /**\n   * Declarative SLO / cost contract enforced on top of (and\n   * independently of) the legacy `maxTokens` / `maxCostUSD` caps.\n   * Adds a wall-clock `maxLatencyMs` dimension and a per-contract\n   * `onViolation` reaction (`\"abort\"` hard-stops, `\"fallback\"` records\n   * a signal + fires `fallback` and lets the run continue). Omit to\n   * keep the classic budget behavior unchanged.\n   *\n   * Read a recorded fallback signal back with\n   * {@link readBudgetFallbackSignal}.\n   */\n  contract?: BudgetContract;\n};\n\ntype BudgetCounters = {\n  tokens: number;\n  costUSD: number;\n  warned: boolean;\n  /**\n   * Wall-clock epoch ms captured at `execute.before`. Used to derive\n   * cumulative run latency for the contract's `maxLatencyMs` clause.\n   */\n  startedAt: number;\n  /**\n   * Set once a `\"fallback\"` contract clause has fired, so the signal +\n   * callback are emitted at most once per run even if later trips keep\n   * breaching.\n   */\n  fallbackFired: boolean;\n};\n\n/**\n * Recorded contract fallback signal, stashed under the `<name>.fallback`\n * state key when a `\"fallback\"` clause trips. A fallback orchestrator\n * reads it via {@link readBudgetFallbackSignal} to decide how to degrade.\n */\nexport type BudgetFallbackSignal = BudgetContractViolation;\n\n/**\n * The `BudgetUnit` to stamp on the thrown error per contract dimension.\n * Latency has no native unit — it borrows `\"requests\"` as the least-wrong\n * operational measure, while the authoritative detail rides on the\n * error's `context.dimension`.\n */\nconst DIMENSION_UNIT: Record<BudgetContractDimension, BudgetUnit> = {\n  tokens: \"tokens\",\n  cost: \"usd\",\n  latency: \"requests\",\n};\n\nfunction breach(\n  limit: number,\n  actual: number,\n  unit: BudgetUnit,\n  name: string,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" exceeded — ${actual} ${unit} (cap: ${limit})`,\n    { limit, actual, unit },\n  );\n}\n\nfunction breachContract(\n  name: string,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): never {\n  throw new BudgetExceededError(\n    `budget \"${name}\" contract exceeded — ${dimension} ${actual} (cap: ${limit})`,\n    {\n      limit,\n      actual,\n      unit: DIMENSION_UNIT[dimension],\n      context: { dimension, limit, actual, source: \"contract\" },\n    },\n  );\n}\n\n/**\n * Read the contract fallback signal recorded by a `budget()` middleware\n * running under `contract.onViolation: \"fallback\"`. Returns `undefined`\n * when no clause was breached.\n *\n * **Role.** The middleware cannot itself switch models on a soft breach,\n * so it records a typed {@link BudgetFallbackSignal} in the shared state\n * bag and lets the run continue. A fallback orchestrator (or the\n * `execute.after` hook of an outer middleware) reads it back here and\n * decides how to degrade the next run — cheaper model, cached answer,\n * truncated context.\n *\n * @param state - The middleware state bag (`ctx.state`).\n * @param name - The budget middleware's name. Default `\"budget\"`,\n *   matching `BudgetOptions.name`'s default.\n *\n * @example\n * const guard = budget({ contract: { maxCostUSD: 0.05, onViolation: \"fallback\" } });\n *\n * // In an outer middleware's execute.after, after the run:\n * const signal = readBudgetFallbackSignal(ctx.state);\n * if (signal?.dimension === \"cost\") {\n *   await rerunOnCheaperModel();\n * }\n */\nexport function readBudgetFallbackSignal(\n  state: MiddlewareExecuteContext[\"state\"],\n  name = \"budget\",\n): BudgetFallbackSignal | undefined {\n  return namespacedState<BudgetFallbackSignal>(\n    { state },\n    `${name}.fallback`,\n  ).get();\n}\n\n/**\n * Enforced token and / or USD budget for an agent run.\n *\n * **Role.** Guards against runaway tool loops, misconfigured\n * prompts, and unexpected provider price swings by capping\n * cumulative usage across every LLM trip of a single execution.\n * Aborts the run with a typed `BudgetExceededError` the moment a cap\n * is breached, rather than letting the damage grow trip by trip.\n *\n * **Scope.** Per-execution. A fresh counter is created at\n * `execute.before` and lives in the middleware state bag until the\n * run ends. Two concurrent `agent.execute()` calls on the same\n * agent therefore enforce the cap independently.\n *\n * **Token accounting.** After each successful trip, the middleware\n * adds `response.usage.total` to its running total and checks\n * against `maxTokens`. Synthetic trips (cache hits) contribute\n * `usage.total` as returned by the cache — cache middleware is\n * expected to surface zero usage on a hit, which naturally excludes\n * those trips from the budget.\n *\n * **USD accounting.** When `maxCostUSD` + `pricing[modelName]` are\n * both present, the middleware converts per-trip input / output\n * tokens to USD and accumulates. Missing pricing silently degrades\n * to tokens-only — explicit rather than guessing.\n *\n * **Warn mode.** `onExceeded: \"warn\"` logs a single warning the first\n * time a cap is breached and lets the run continue. Useful for\n * measuring real-world traffic against a proposed cap before flipping\n * to `\"abort\"` in production.\n *\n * **Contract / SLO mode.** Pass `contract` to enforce a declarative\n * service-level objective — `maxCostUSD`, `maxLatencyMs`, `maxTokens` —\n * on top of the legacy caps, with a single `onViolation` reaction:\n * `\"abort\"` hard-stops with `BudgetExceededError`; `\"fallback\"` records\n * a typed signal (read it via {@link readBudgetFallbackSignal}), fires\n * the optional `fallback` callback, and lets the run continue so an\n * outer layer can degrade gracefully. The contract's clauses are\n * evaluated independently of — and after — the top-level caps; the\n * top-level caps stay fully functional with or without a contract.\n *\n * @example\n * const budgetMiddleware = budget({ maxTokens: 50_000 });\n *\n * const myAgent = agent({\n *   model,\n *   middleware: [budgetMiddleware],\n * });\n *\n * @example\n * // With USD cap and custom pricing\n * const guard = budget({\n *   maxCostUSD: 0.5,\n *   pricing: {\n *     \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 },\n *   },\n * });\n *\n * @example\n * // SLO contract — soft-fallback on any breach\n * const sloGuard = budget({\n *   pricing: { \"gpt-4o\": { inputPer1K: 0.005, outputPer1K: 0.015 } },\n *   contract: {\n *     maxCostUSD: 0.05,\n *     maxLatencyMs: 8_000,\n *     maxTokens: 40_000,\n *     onViolation: \"fallback\",\n *     fallback: (violation) => routeToCheaperModel(violation.dimension),\n *   },\n * });\n */\nexport function budget(options: BudgetOptions): AgentMiddleware {\n  const name = options.name ?? \"budget\";\n  const onExceeded = options.onExceeded ?? \"abort\";\n  const hasTokenCap = typeof options.maxTokens === \"number\";\n  const hasCostCap = typeof options.maxCostUSD === \"number\";\n\n  const contract = options.contract;\n  const contractMode = contract?.onViolation ?? \"abort\";\n  const hasContractTokenCap = typeof contract?.maxTokens === \"number\";\n  const hasContractCostCap = typeof contract?.maxCostUSD === \"number\";\n  const hasContractLatencyCap = typeof contract?.maxLatencyMs === \"number\";\n  const contractNeedsCost = hasCostCap || hasContractCostCap;\n\n  return {\n    name,\n    execute: {\n      before(context) {\n        const counters = namespacedState<BudgetCounters>(context, name);\n        counters.set({\n          tokens: 0,\n          costUSD: 0,\n          warned: false,\n          startedAt: Date.now(),\n          fallbackFired: false,\n        });\n      },\n    },\n    trip: {\n      async after(context, response) {\n        const counters = namespacedState<BudgetCounters>(context, name).get();\n\n        if (!counters) {\n          return;\n        }\n\n        counters.tokens += response.usage.total;\n\n        if (contractNeedsCost && options.pricing) {\n          const pricing = options.pricing[context.model.name];\n\n          if (pricing) {\n            const tripCost =\n              (response.usage.input / 1000) * pricing.inputPer1K +\n              (response.usage.output / 1000) * pricing.outputPer1K;\n            counters.costUSD += tripCost;\n          }\n        }\n\n        if (hasTokenCap && counters.tokens > options.maxTokens!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxTokens!, counters.tokens, \"tokens\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (hasCostCap && counters.costUSD > options.maxCostUSD!) {\n          if (onExceeded === \"abort\") {\n            breach(options.maxCostUSD!, counters.costUSD, \"usd\", name);\n          }\n\n          if (!counters.warned) {\n            counters.warned = true;\n          }\n        }\n\n        if (!contract) {\n          return;\n        }\n\n        if (hasContractTokenCap && counters.tokens > contract.maxTokens!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"tokens\",\n            contract.maxTokens!,\n            counters.tokens,\n          );\n        }\n\n        if (hasContractCostCap && counters.costUSD > contract.maxCostUSD!) {\n          await enforceContract(\n            context,\n            counters,\n            name,\n            contractMode,\n            contract,\n            \"cost\",\n            contract.maxCostUSD!,\n            counters.costUSD,\n          );\n        }\n\n        if (hasContractLatencyCap) {\n          const elapsedMs = Date.now() - counters.startedAt;\n\n          if (elapsedMs > contract.maxLatencyMs!) {\n            await enforceContract(\n              context,\n              counters,\n              name,\n              contractMode,\n              contract,\n              \"latency\",\n              contract.maxLatencyMs!,\n              elapsedMs,\n            );\n          }\n        }\n      },\n    },\n  };\n}\n\n/**\n * Apply the contract's reaction to a single breached clause. `\"abort\"`\n * throws `BudgetExceededError` (stops the run); `\"fallback\"` records the\n * signal once, fires the callback, and returns so the run continues.\n *\n * The callback is invoked at most once per run (guarded by\n * `counters.fallbackFired`) and its rejections are swallowed — a buggy\n * fallback hook must never crash the agent.\n */\nasync function enforceContract(\n  context: MiddlewareExecuteContext,\n  counters: BudgetCounters,\n  name: string,\n  mode: NonNullable<BudgetContract[\"onViolation\"]>,\n  contract: BudgetContract,\n  dimension: BudgetContractDimension,\n  limit: number,\n  actual: number,\n): Promise<void> {\n  if (mode === \"abort\") {\n    breachContract(name, dimension, limit, actual);\n  }\n\n  if (counters.fallbackFired) {\n    return;\n  }\n\n  counters.fallbackFired = true;\n\n  const violation: BudgetContractViolation = {\n    dimension,\n    limit,\n    actual,\n    mode,\n  };\n\n  namespacedState<BudgetContractViolation>(context, `${name}.fallback`).set(\n    violation,\n  );\n\n  if (!contract.fallback) {\n    return;\n  }\n\n  try {\n    await contract.fallback(violation, context);\n  } catch {\n    // A fallback callback is a notification hook — its failure must\n    // never crash the run. Swallow deliberately.\n  }\n}\n"],"mappings":";;;;;;;;;;;AAsHA,MAAM,iBAA8D;CAClE,QAAQ;CACR,MAAM;CACN,SAAS;AACX;AAEA,SAAS,OACP,OACA,QACA,MACA,MACO;CACP,MAAM,IAAI,oBACR,WAAW,KAAK,eAAe,OAAO,GAAG,KAAK,SAAS,MAAM,IAC7D;EAAE;EAAO;EAAQ;CAAK,CACxB;AACF;AAEA,SAAS,eACP,MACA,WACA,OACA,QACO;CACP,MAAM,IAAI,oBACR,WAAW,KAAK,wBAAwB,UAAU,GAAG,OAAO,SAAS,MAAM,IAC3E;EACE;EACA;EACA,MAAM,eAAe;EACrB,SAAS;GAAE;GAAW;GAAO;GAAQ,QAAQ;EAAW;CAC1D,CACF;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,yBACd,OACA,OAAO,UAC2B;CAClC,OAAO,gBACL,EAAE,MAAM,GACR,GAAG,KAAK,UACV,CAAC,CAAC,IAAI;AACR;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyEA,SAAgB,OAAO,SAAyC;CAC9D,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,aAAa,QAAQ,cAAc;CACzC,MAAM,cAAc,OAAO,QAAQ,cAAc;CACjD,MAAM,aAAa,OAAO,QAAQ,eAAe;CAEjD,MAAM,WAAW,QAAQ;CACzB,MAAM,eAAe,UAAU,eAAe;CAC9C,MAAM,sBAAsB,OAAO,UAAU,cAAc;CAC3D,MAAM,qBAAqB,OAAO,UAAU,eAAe;CAC3D,MAAM,wBAAwB,OAAO,UAAU,iBAAiB;CAChE,MAAM,oBAAoB,cAAc;CAExC,OAAO;EACL;EACA,SAAS,EACP,OAAO,SAAS;GAEd,AADiB,gBAAgC,SAAS,IACnD,CAAC,CAAC,IAAI;IACX,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,WAAW,KAAK,IAAI;IACpB,eAAe;GACjB,CAAC;EACH,EACF;EACA,MAAM,EACJ,MAAM,MAAM,SAAS,UAAU;GAC7B,MAAM,WAAW,gBAAgC,SAAS,IAAI,CAAC,CAAC,IAAI;GAEpE,IAAI,CAAC,UACH;GAGF,SAAS,UAAU,SAAS,MAAM;GAElC,IAAI,qBAAqB,QAAQ,SAAS;IACxC,MAAM,UAAU,QAAQ,QAAQ,QAAQ,MAAM;IAE9C,IAAI,SAAS;KACX,MAAM,WACH,SAAS,MAAM,QAAQ,MAAQ,QAAQ,aACvC,SAAS,MAAM,SAAS,MAAQ,QAAQ;KAC3C,SAAS,WAAW;IACtB;GACF;GAEA,IAAI,eAAe,SAAS,SAAS,QAAQ,WAAY;IACvD,IAAI,eAAe,SACjB,OAAO,QAAQ,WAAY,SAAS,QAAQ,UAAU,IAAI;IAG5D,IAAI,CAAC,SAAS,QACZ,SAAS,SAAS;GAEtB;GAEA,IAAI,cAAc,SAAS,UAAU,QAAQ,YAAa;IACxD,IAAI,eAAe,SACjB,OAAO,QAAQ,YAAa,SAAS,SAAS,OAAO,IAAI;IAG3D,IAAI,CAAC,SAAS,QACZ,SAAS,SAAS;GAEtB;GAEA,IAAI,CAAC,UACH;GAGF,IAAI,uBAAuB,SAAS,SAAS,SAAS,WACpD,MAAM,gBACJ,SACA,UACA,MACA,cACA,UACA,UACA,SAAS,WACT,SAAS,MACX;GAGF,IAAI,sBAAsB,SAAS,UAAU,SAAS,YACpD,MAAM,gBACJ,SACA,UACA,MACA,cACA,UACA,QACA,SAAS,YACT,SAAS,OACX;GAGF,IAAI,uBAAuB;IACzB,MAAM,YAAY,KAAK,IAAI,IAAI,SAAS;IAExC,IAAI,YAAY,SAAS,cACvB,MAAM,gBACJ,SACA,UACA,MACA,cACA,UACA,WACA,SAAS,cACT,SACF;GAEJ;EACF,EACF;CACF;AACF;;;;;;;;;;AAWA,eAAe,gBACb,SACA,UACA,MACA,MACA,UACA,WACA,OACA,QACe;CACf,IAAI,SAAS,SACX,eAAe,MAAM,WAAW,OAAO,MAAM;CAG/C,IAAI,SAAS,eACX;CAGF,SAAS,gBAAgB;CAEzB,MAAM,YAAqC;EACzC;EACA;EACA;EACA;CACF;CAEA,gBAAyC,SAAS,GAAG,KAAK,UAAU,CAAC,CAAC,IACpE,SACF;CAEA,IAAI,CAAC,SAAS,UACZ;CAGF,IAAI;EACF,MAAM,SAAS,SAAS,WAAW,OAAO;CAC5C,QAAQ,CAGR;AACF"}

package/esm/middleware/builtins/semantic-cache.d.mts

@@ -1,5 +1,5 @@
-import { EmbedderContract } from "../../contracts/embedder.contract.mjs";
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
+import { EmbedderContract } from "../../contracts/embedder.contract.mjs";
 import { CacheDriver } from "@warlock.js/cache";
 
 //#region ../@warlock.js/ai/src/middleware/builtins/semantic-cache.d.ts

package/esm/middleware/index.d.mts

@@ -1,4 +1,5 @@
-import { BudgetOptions, BudgetPricing, budget } from "./builtins/budget.mjs";
+import { BudgetContract, BudgetContractDimension, BudgetContractFallback, BudgetContractViolation, BudgetContractViolationMode } from "./builtins/budget-contract.type.mjs";
+import { BudgetFallbackSignal, BudgetOptions, BudgetPricing, budget, readBudgetFallbackSignal } from "./builtins/budget.mjs";
 import { GuardrailCheck, GuardrailCheckResult, GuardrailOptions, guardrail } from "./builtins/guardrail.mjs";
 import { SemanticCacheOptions, semanticCache } from "./builtins/semantic-cache.mjs";
 import { composeMiddleware } from "./helpers/compose.mjs";

package/esm/middleware/index.mjs

@@ -1,6 +1,6 @@
 import { extractUserText } from "./utils/extract-user-text.mjs";
 import { namespacedState } from "./utils/namespaced-state.mjs";
-import { budget } from "./builtins/budget.mjs";
+import { budget, readBudgetFallbackSignal } from "./builtins/budget.mjs";
 import { guardrail } from "./builtins/guardrail.mjs";
 import { semanticCache } from "./builtins/semantic-cache.mjs";
 import { composeMiddleware } from "./helpers/compose.mjs";

package/esm/middleware/pipeline.d.mts

@@ -1,15 +1,17 @@
-import { MiddlewareExecuteContext, MiddlewareToolContext, MiddlewareTripContext } from "../contracts/middleware/middleware-context.type.mjs";
+import { MiddlewareExecuteContext, MiddlewareSupervisorContext, MiddlewareToolContext, MiddlewareTripContext } from "../contracts/middleware/middleware-context.type.mjs";
 import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
 import { Logger } from "@warlock.js/logger";
 
 //#region ../@warlock.js/ai/src/middleware/pipeline.d.ts
 /**
- * The three levels at which agent middleware can hook — mirrors
- * `AgentMiddleware`'s optional `execute` / `trip` / `tool` keys.
- * Kept as a single named union so callers can pass it around without
- * inline-duplicating the literals.
+ * The four levels at which middleware can hook — mirrors
+ * `AgentMiddleware`'s optional `execute` / `trip` / `tool` /
+ * `supervisor` keys. Kept as a single named union so callers can pass
+ * it around without inline-duplicating the literals. The first three
+ * fire on the agent pipeline; `supervisor` fires once around a whole
+ * `supervisor.execute()` run.
  */
-type MiddlewareLevel = "execute" | "trip" | "tool";
+type MiddlewareLevel = "execute" | "trip" | "tool" | "supervisor";
 /**
  * Shape of the context object for each level. The pipeline is
  * level-parameterized on the ctx type via this mapping so callers
@@ -19,6 +21,7 @@ type MiddlewareContextByLevel = {
   execute: MiddlewareExecuteContext;
   trip: MiddlewareTripContext;
   tool: MiddlewareToolContext;
+  supervisor: MiddlewareSupervisorContext;
 };
 /**
  * Run an inner async operation through a stack of agent middlewares

package/esm/middleware/pipeline.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/pipeline.ts"],"mappings":";;;;;;;;;AAgBA;;KAAY,eAAA;;AAAe;AAO3B;;;KAAY,wBAAA;EACV,OAAA,EAAS,wBAAA;EACT,IAAA,EAAM,qBAAA;EACN,IAAA,EAAM,qBAAA;AAAA;;;;;;;;AAAqB;AA+C7B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMkB;iBANI,WAAA,eAA0B,eAAA,WAC9C,WAAA,EAAa,aAAA,CAAc,eAAA,GAC3B,KAAA,EAAO,KAAA,EACP,OAAA,EAAS,wBAAA,CAAyB,KAAA,GAClC,KAAA,QAAa,OAAA,CAAQ,OAAA,GACrB,MAAA,GAAS,MAAA,GACR,OAAA,CAAQ,OAAA"}
+{"version":3,"file":"pipeline.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/pipeline.ts"],"mappings":";;;;;;;;;AAmBA;;;;KAAY,eAAA;AAOZ;;;;;AAAA,KAAY,wBAAA;EACV,OAAA,EAAS,wBAAA;EACT,IAAA,EAAM,qBAAA;EACN,IAAA,EAAM,qBAAA;EACN,UAAA,EAAY,2BAAA;AAAA;;;;;;;;AAA2B;AA+CzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAMkB;iBANI,WAAA,eAA0B,eAAA,WAC9C,WAAA,EAAa,aAAA,CAAc,eAAA,GAC3B,KAAA,EAAO,KAAA,EACP,OAAA,EAAS,wBAAA,CAAyB,KAAA,GAClC,KAAA,QAAa,OAAA,CAAQ,OAAA,GACrB,MAAA,GAAS,MAAA,GACR,OAAA,CAAQ,OAAA"}

package/esm/middleware/pipeline.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/pipeline.ts"],"sourcesContent":["import type { Logger } from \"@warlock.js/logger\";\nimport type {\n  AgentMiddleware,\n  MiddlewareExecuteContext,\n  MiddlewareToolContext,\n  MiddlewareTripContext,\n} from \"../contracts/middleware\";\n\nconst LOG_MODULE = \"ai.middleware\";\n\n/**\n * The three levels at which agent middleware can hook — mirrors\n * `AgentMiddleware`'s optional `execute` / `trip` / `tool` keys.\n * Kept as a single named union so callers can pass it around without\n * inline-duplicating the literals.\n */\nexport type MiddlewareLevel = \"execute\" | \"trip\" | \"tool\";\n\n/**\n * Shape of the context object for each level. The pipeline is\n * level-parameterized on the ctx type via this mapping so callers\n * get compile-time narrowing when they instantiate `runPipeline`.\n */\nexport type MiddlewareContextByLevel = {\n  execute: MiddlewareExecuteContext;\n  trip: MiddlewareTripContext;\n  tool: MiddlewareToolContext;\n};\n\n/**\n * Run an inner async operation through a stack of agent middlewares\n * at a single level, applying the onion-model before/after/onError\n * semantics documented on `AgentMiddleware`.\n *\n * **Semantics.**\n * - `before` hooks run in registration order (top-down).\n *   Returning a defined value from a `before` hook short-circuits the\n *   pipeline with that value as the result, skipping `inner()` and\n *   all deeper `before` / `after` hooks — but outer middleware\n *   `after` hooks (registered earlier) still run on the synthetic\n *   value.\n * - `after` hooks run in reverse registration order (bottom-up).\n *   Returning a defined value replaces the result before it\n *   propagates further out. Returning `void` / `undefined` keeps the\n *   existing result.\n * - `onError` hooks also run in reverse (bottom-up) — any error\n *   thrown by `inner()`, by a `before` hook, or by an `after` hook\n *   unwinds through each frame's `onError` in turn. Returning a\n *   defined value from `onError` recovers: the error is cleared and\n *   the returned value becomes the new result (which then flows\n *   through outer `after` hooks). Returning `void` propagates the\n *   error to the next outer frame.\n *\n * **Implementation.** Built by folding the middleware array from the\n * end inward: each middleware produces a closure that wraps the\n * previous closure (the deeper pipeline). The outermost wrap is\n * middleware index 0 — so registration order matches onion order\n * without any reverse iteration at call time.\n *\n * **No magic.** The pipeline does not swallow, retry, or translate\n * errors. Hooks that throw propagate unchanged (subject to `onError`\n * recovery). Pipeline-level logging is debug-only and respects each\n * middleware's `log: false` kill-switch.\n *\n * @example\n * const response = await runPipeline(\n *   middlewares,\n *   \"trip\",\n *   tripContext,\n *   () => model.complete(messages, callOptions),\n *   logger,\n * );\n */\nexport async function runPipeline<Level extends MiddlewareLevel, TResult>(\n  middlewares: ReadonlyArray<AgentMiddleware>,\n  level: Level,\n  context: MiddlewareContextByLevel[Level],\n  inner: () => Promise<TResult>,\n  logger?: Logger,\n): Promise<TResult> {\n  if (middlewares.length === 0) {\n    return inner();\n  }\n\n  let next: () => Promise<TResult> = inner;\n\n  for (let index = middlewares.length - 1; index >= 0; index--) {\n    const middleware = middlewares[index];\n    const hooks = middleware[level];\n\n    if (!hooks) {\n      continue;\n    }\n\n    const previous = next;\n\n    next = async () => {\n      const logEnabled = middleware.log !== false && logger !== undefined;\n\n      if (hooks.before) {\n        if (logEnabled) {\n          logger!.debug(LOG_MODULE, `${level}.before`, middleware.name, {\n            middleware: middleware.name,\n            level,\n          });\n        }\n\n        const shortCircuit = await (\n          hooks.before as (ctx: unknown) => Promise<unknown> | unknown\n        )(context);\n\n        if (shortCircuit !== undefined) {\n          if (logEnabled) {\n            logger!.debug(\n              LOG_MODULE,\n              `${level}.short-circuit`,\n              middleware.name,\n              {\n                middleware: middleware.name,\n                level,\n              },\n            );\n          }\n\n          return shortCircuit as TResult;\n        }\n      }\n\n      let result: TResult;\n\n      try {\n        result = await previous();\n      } catch (thrown) {\n        if (!hooks.onError) {\n          throw thrown;\n        }\n\n        const recovered = await (\n          hooks.onError as (\n            ctx: unknown,\n            error: unknown,\n          ) => Promise<unknown> | unknown\n        )(context, thrown);\n\n        if (recovered === undefined) {\n          throw thrown;\n        }\n\n        if (logEnabled) {\n          logger!.debug(LOG_MODULE, `${level}.recovered`, middleware.name, {\n            middleware: middleware.name,\n            level,\n          });\n        }\n\n        result = recovered as TResult;\n      }\n\n      if (hooks.after) {\n        const replacement = await (\n          hooks.after as (\n            ctx: unknown,\n            value: unknown,\n          ) => Promise<unknown> | unknown\n        )(context, result);\n\n        if (replacement !== undefined) {\n          result = replacement as TResult;\n        }\n\n        if (logEnabled) {\n          logger!.debug(LOG_MODULE, `${level}.after`, middleware.name, {\n            middleware: middleware.name,\n            level,\n          });\n        }\n      }\n\n      return result;\n    };\n  }\n\n  return next();\n}\n"],"mappings":";AAQA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEnB,eAAsB,YACpB,aACA,OACA,SACA,OACA,QACkB;CAClB,IAAI,YAAY,WAAW,GACzB,OAAO,MAAM;CAGf,IAAI,OAA+B;CAEnC,KAAK,IAAI,QAAQ,YAAY,SAAS,GAAG,SAAS,GAAG,SAAS;EAC5D,MAAM,aAAa,YAAY;EAC/B,MAAM,QAAQ,WAAW;EAEzB,IAAI,CAAC,OACH;EAGF,MAAM,WAAW;EAEjB,OAAO,YAAY;GACjB,MAAM,aAAa,WAAW,QAAQ,SAAS,WAAW;GAE1D,IAAI,MAAM,QAAQ;IAChB,IAAI,YACF,OAAQ,MAAM,YAAY,GAAG,MAAM,UAAU,WAAW,MAAM;KAC5D,YAAY,WAAW;KACvB;IACF,CAAC;IAGH,MAAM,eAAe,MACnB,MAAM,OACN,OAAO;IAET,IAAI,iBAAiB,QAAW;KAC9B,IAAI,YACF,OAAQ,MACN,YACA,GAAG,MAAM,iBACT,WAAW,MACX;MACE,YAAY,WAAW;MACvB;KACF,CACF;KAGF,OAAO;IACT;GACF;GAEA,IAAI;GAEJ,IAAI;IACF,SAAS,MAAM,SAAS;GAC1B,SAAS,QAAQ;IACf,IAAI,CAAC,MAAM,SACT,MAAM;IAGR,MAAM,YAAY,MAChB,MAAM,QAIN,SAAS,MAAM;IAEjB,IAAI,cAAc,QAChB,MAAM;IAGR,IAAI,YACF,OAAQ,MAAM,YAAY,GAAG,MAAM,aAAa,WAAW,MAAM;KAC/D,YAAY,WAAW;KACvB;IACF,CAAC;IAGH,SAAS;GACX;GAEA,IAAI,MAAM,OAAO;IACf,MAAM,cAAc,MAClB,MAAM,MAIN,SAAS,MAAM;IAEjB,IAAI,gBAAgB,QAClB,SAAS;IAGX,IAAI,YACF,OAAQ,MAAM,YAAY,GAAG,MAAM,SAAS,WAAW,MAAM;KAC3D,YAAY,WAAW;KACvB;IACF,CAAC;GAEL;GAEA,OAAO;EACT;CACF;CAEA,OAAO,KAAK;AACd"}
+{"version":3,"file":"pipeline.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/pipeline.ts"],"sourcesContent":["import type { Logger } from \"@warlock.js/logger\";\nimport type {\n  AgentMiddleware,\n  MiddlewareExecuteContext,\n  MiddlewareSupervisorContext,\n  MiddlewareToolContext,\n  MiddlewareTripContext,\n} from \"../contracts/middleware\";\n\nconst LOG_MODULE = \"ai.middleware\";\n\n/**\n * The four levels at which middleware can hook — mirrors\n * `AgentMiddleware`'s optional `execute` / `trip` / `tool` /\n * `supervisor` keys. Kept as a single named union so callers can pass\n * it around without inline-duplicating the literals. The first three\n * fire on the agent pipeline; `supervisor` fires once around a whole\n * `supervisor.execute()` run.\n */\nexport type MiddlewareLevel = \"execute\" | \"trip\" | \"tool\" | \"supervisor\";\n\n/**\n * Shape of the context object for each level. The pipeline is\n * level-parameterized on the ctx type via this mapping so callers\n * get compile-time narrowing when they instantiate `runPipeline`.\n */\nexport type MiddlewareContextByLevel = {\n  execute: MiddlewareExecuteContext;\n  trip: MiddlewareTripContext;\n  tool: MiddlewareToolContext;\n  supervisor: MiddlewareSupervisorContext;\n};\n\n/**\n * Run an inner async operation through a stack of agent middlewares\n * at a single level, applying the onion-model before/after/onError\n * semantics documented on `AgentMiddleware`.\n *\n * **Semantics.**\n * - `before` hooks run in registration order (top-down).\n *   Returning a defined value from a `before` hook short-circuits the\n *   pipeline with that value as the result, skipping `inner()` and\n *   all deeper `before` / `after` hooks — but outer middleware\n *   `after` hooks (registered earlier) still run on the synthetic\n *   value.\n * - `after` hooks run in reverse registration order (bottom-up).\n *   Returning a defined value replaces the result before it\n *   propagates further out. Returning `void` / `undefined` keeps the\n *   existing result.\n * - `onError` hooks also run in reverse (bottom-up) — any error\n *   thrown by `inner()`, by a `before` hook, or by an `after` hook\n *   unwinds through each frame's `onError` in turn. Returning a\n *   defined value from `onError` recovers: the error is cleared and\n *   the returned value becomes the new result (which then flows\n *   through outer `after` hooks). Returning `void` propagates the\n *   error to the next outer frame.\n *\n * **Implementation.** Built by folding the middleware array from the\n * end inward: each middleware produces a closure that wraps the\n * previous closure (the deeper pipeline). The outermost wrap is\n * middleware index 0 — so registration order matches onion order\n * without any reverse iteration at call time.\n *\n * **No magic.** The pipeline does not swallow, retry, or translate\n * errors. Hooks that throw propagate unchanged (subject to `onError`\n * recovery). Pipeline-level logging is debug-only and respects each\n * middleware's `log: false` kill-switch.\n *\n * @example\n * const response = await runPipeline(\n *   middlewares,\n *   \"trip\",\n *   tripContext,\n *   () => model.complete(messages, callOptions),\n *   logger,\n * );\n */\nexport async function runPipeline<Level extends MiddlewareLevel, TResult>(\n  middlewares: ReadonlyArray<AgentMiddleware>,\n  level: Level,\n  context: MiddlewareContextByLevel[Level],\n  inner: () => Promise<TResult>,\n  logger?: Logger,\n): Promise<TResult> {\n  if (middlewares.length === 0) {\n    return inner();\n  }\n\n  let next: () => Promise<TResult> = inner;\n\n  for (let index = middlewares.length - 1; index >= 0; index--) {\n    const middleware = middlewares[index];\n    const hooks = middleware[level];\n\n    if (!hooks) {\n      continue;\n    }\n\n    const previous = next;\n\n    next = async () => {\n      const logEnabled = middleware.log !== false && logger !== undefined;\n\n      if (hooks.before) {\n        if (logEnabled) {\n          logger!.debug(LOG_MODULE, `${level}.before`, middleware.name, {\n            middleware: middleware.name,\n            level,\n          });\n        }\n\n        const shortCircuit = await (\n          hooks.before as (ctx: unknown) => Promise<unknown> | unknown\n        )(context);\n\n        if (shortCircuit !== undefined) {\n          if (logEnabled) {\n            logger!.debug(\n              LOG_MODULE,\n              `${level}.short-circuit`,\n              middleware.name,\n              {\n                middleware: middleware.name,\n                level,\n              },\n            );\n          }\n\n          return shortCircuit as TResult;\n        }\n      }\n\n      let result: TResult;\n\n      try {\n        result = await previous();\n      } catch (thrown) {\n        if (!hooks.onError) {\n          throw thrown;\n        }\n\n        const recovered = await (\n          hooks.onError as (\n            ctx: unknown,\n            error: unknown,\n          ) => Promise<unknown> | unknown\n        )(context, thrown);\n\n        if (recovered === undefined) {\n          throw thrown;\n        }\n\n        if (logEnabled) {\n          logger!.debug(LOG_MODULE, `${level}.recovered`, middleware.name, {\n            middleware: middleware.name,\n            level,\n          });\n        }\n\n        result = recovered as TResult;\n      }\n\n      if (hooks.after) {\n        const replacement = await (\n          hooks.after as (\n            ctx: unknown,\n            value: unknown,\n          ) => Promise<unknown> | unknown\n        )(context, result);\n\n        if (replacement !== undefined) {\n          result = replacement as TResult;\n        }\n\n        if (logEnabled) {\n          logger!.debug(LOG_MODULE, `${level}.after`, middleware.name, {\n            middleware: middleware.name,\n            level,\n          });\n        }\n      }\n\n      return result;\n    };\n  }\n\n  return next();\n}\n"],"mappings":";AASA,MAAM,aAAa;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAoEnB,eAAsB,YACpB,aACA,OACA,SACA,OACA,QACkB;CAClB,IAAI,YAAY,WAAW,GACzB,OAAO,MAAM;CAGf,IAAI,OAA+B;CAEnC,KAAK,IAAI,QAAQ,YAAY,SAAS,GAAG,SAAS,GAAG,SAAS;EAC5D,MAAM,aAAa,YAAY;EAC/B,MAAM,QAAQ,WAAW;EAEzB,IAAI,CAAC,OACH;EAGF,MAAM,WAAW;EAEjB,OAAO,YAAY;GACjB,MAAM,aAAa,WAAW,QAAQ,SAAS,WAAW;GAE1D,IAAI,MAAM,QAAQ;IAChB,IAAI,YACF,OAAQ,MAAM,YAAY,GAAG,MAAM,UAAU,WAAW,MAAM;KAC5D,YAAY,WAAW;KACvB;IACF,CAAC;IAGH,MAAM,eAAe,MACnB,MAAM,OACN,OAAO;IAET,IAAI,iBAAiB,QAAW;KAC9B,IAAI,YACF,OAAQ,MACN,YACA,GAAG,MAAM,iBACT,WAAW,MACX;MACE,YAAY,WAAW;MACvB;KACF,CACF;KAGF,OAAO;IACT;GACF;GAEA,IAAI;GAEJ,IAAI;IACF,SAAS,MAAM,SAAS;GAC1B,SAAS,QAAQ;IACf,IAAI,CAAC,MAAM,SACT,MAAM;IAGR,MAAM,YAAY,MAChB,MAAM,QAIN,SAAS,MAAM;IAEjB,IAAI,cAAc,QAChB,MAAM;IAGR,IAAI,YACF,OAAQ,MAAM,YAAY,GAAG,MAAM,aAAa,WAAW,MAAM;KAC/D,YAAY,WAAW;KACvB;IACF,CAAC;IAGH,SAAS;GACX;GAEA,IAAI,MAAM,OAAO;IACf,MAAM,cAAc,MAClB,MAAM,MAIN,SAAS,MAAM;IAEjB,IAAI,gBAAgB,QAClB,SAAS;IAGX,IAAI,YACF,OAAQ,MAAM,YAAY,GAAG,MAAM,SAAS,WAAW,MAAM;KAC3D,YAAY,WAAW;KACvB;IACF,CAAC;GAEL;GAEA,OAAO;EACT;CACF;CAEA,OAAO,KAAK;AACd"}

package/esm/mock/index.d.mts

@@ -1,4 +1,5 @@
 import { MockModelResponse, MockSDKConfig } from "./mock-config.type.mjs";
 import { mockAgent } from "./mock-agent.mjs";
 import { MockModel } from "./mock-model.mjs";
+import { MockRouterDecision, MockRouterExhaustion, MockRouterOptions, mockRouter } from "./mock-router.mjs";
 import { MockSDK } from "./mock-sdk.mjs";

package/esm/mock/index.mjs

@@ -1,5 +1,6 @@
 import { MockModel } from "./mock-model.mjs";
 import { MockSDK } from "./mock-sdk.mjs";
 import { mockAgent } from "./mock-agent.mjs";
+import { mockRouter } from "./mock-router.mjs";
 
 export {  };