@warlock.js/ai 4.2.11 → 4.3.0

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 {  };

package/esm/mock/mock-router.d.mts

@@ -0,0 +1,63 @@
+import { RouteContext } from "../contracts/supervisor/route-context.type.mjs";
+import { Next } from "../contracts/supervisor/next.type.mjs";
+
+//#region ../@warlock.js/ai/src/mock/mock-router.d.ts
+/**
+ * A canned routing decision for {@link mockRouter}. Either a literal
+ * {@link Next} value (intent key, fan-out array, or the `END`
+ * sentinel) or a predicate that derives the decision from the live
+ * {@link RouteContext} — the latter lets a test branch on accumulated
+ * state without scripting an exact per-iteration sequence.
+ */
+type MockRouterDecision<TState = Record<string, unknown>> = Next | ((context: RouteContext<TState>) => Next);
+/**
+ * Behavior when the canned decision queue is exhausted before the
+ * supervisor terminates on its own.
+ *
+ * - `"end"` (default) — return `END`, terminating the run cleanly. The
+ *   common case: script the interesting turns, let the run stop.
+ * - `"throw"` — throw, surfacing the over-run as a test failure. Use
+ *   when every iteration must be accounted for.
+ * - `"repeat"` — replay the last decision for every further iteration.
+ *   Useful for "keep routing to the same intent until evaluate is
+ *   satisfied" scenarios.
+ */
+type MockRouterExhaustion = "end" | "throw" | "repeat";
+/**
+ * Options for {@link mockRouter}.
+ */
+type MockRouterOptions = {
+  /** What to do once the decision queue is exhausted. Default `"end"`. */onExhausted?: MockRouterExhaustion;
+};
+/**
+ * Build a deterministic `route` callback that replays a canned
+ * sequence of routing decisions — one per supervisor iteration — for
+ * testing supervisors without an LLM router.
+ *
+ * Drop the returned callback into `ai.supervisor({ route: mockRouter([...]) })`
+ * in place of an LLM `router`. The Nth iteration consumes the Nth
+ * decision; a function decision is evaluated against the live
+ * `RouteContext`. When the queue runs out, behavior follows
+ * `options.onExhausted` (default: terminate with `END`).
+ *
+ * Pairs with the `toRouteTo` / `toConverge` matchers to assert the
+ * resulting report tree.
+ *
+ * @example
+ * const supervisor = ai.supervisor({
+ *   name: "draft-then-review",
+ *   intents: { writer, critic },
+ *   route: mockRouter(["writer", "critic", END]),
+ * });
+ *
+ * @example
+ * // Branch on accumulated state, repeat the last decision until done.
+ * route: mockRouter(
+ *   ["research", (ctx) => (ctx.state.summary ? END : "research")],
+ *   { onExhausted: "repeat" },
+ * );
+ */
+declare function mockRouter<TState = Record<string, unknown>>(decisions: MockRouterDecision<TState>[], options?: MockRouterOptions): (context: RouteContext<TState>) => Next;
+//#endregion
+export { MockRouterDecision, MockRouterExhaustion, MockRouterOptions, mockRouter };
+//# sourceMappingURL=mock-router.d.mts.map

package/esm/mock/mock-router.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-router.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-router.ts"],"mappings":";;;;;;AAWA;;;;;KAAY,kBAAA,UAA4B,MAAA,qBACpC,IAAA,KACE,OAAA,EAAS,YAAA,CAAa,MAAA,MAAY,IAAA;;;;;;;;;;;;;KAc5B,oBAAA;AAAZ;;;AAAA,KAKY,iBAAA;EALoB,wEAO9B,WAAA,GAAc,oBAAoB;AAAA;;;AAAA;AA+BpC;;;;;;;;;;;;;;;;;;;;;;;;AAG0C;iBAH1B,UAAA,UAAoB,MAAA,mBAClC,SAAA,EAAW,kBAAA,CAAmB,MAAA,KAC9B,OAAA,GAAS,iBAAA,IACP,OAAA,EAAS,YAAA,CAAa,MAAA,MAAY,IAAA"}

package/esm/mock/mock-router.mjs

@@ -0,0 +1,58 @@
+import { END } from "../contracts/end.type.mjs";
+
+//#region ../@warlock.js/ai/src/mock/mock-router.ts
+/**
+* Build a deterministic `route` callback that replays a canned
+* sequence of routing decisions — one per supervisor iteration — for
+* testing supervisors without an LLM router.
+*
+* Drop the returned callback into `ai.supervisor({ route: mockRouter([...]) })`
+* in place of an LLM `router`. The Nth iteration consumes the Nth
+* decision; a function decision is evaluated against the live
+* `RouteContext`. When the queue runs out, behavior follows
+* `options.onExhausted` (default: terminate with `END`).
+*
+* Pairs with the `toRouteTo` / `toConverge` matchers to assert the
+* resulting report tree.
+*
+* @example
+* const supervisor = ai.supervisor({
+*   name: "draft-then-review",
+*   intents: { writer, critic },
+*   route: mockRouter(["writer", "critic", END]),
+* });
+*
+* @example
+* // Branch on accumulated state, repeat the last decision until done.
+* route: mockRouter(
+*   ["research", (ctx) => (ctx.state.summary ? END : "research")],
+*   { onExhausted: "repeat" },
+* );
+*/
+function mockRouter(decisions, options = {}) {
+	const onExhausted = options.onExhausted ?? "end";
+	let cursor = 0;
+	return (context) => {
+		if (cursor < decisions.length) {
+			const decision = decisions[cursor];
+			cursor++;
+			return resolveDecision(decision, context);
+		}
+		if (onExhausted === "throw") throw new Error(`mockRouter exhausted after ${decisions.length} decision(s) at iteration ${context.iteration}`);
+		if (onExhausted === "repeat" && decisions.length > 0) return resolveDecision(decisions[decisions.length - 1], context);
+		return END;
+	};
+}
+/**
+* Resolve a single decision entry into a concrete {@link Next} —
+* invoking the predicate form against the live context, or returning
+* the literal form verbatim.
+*/
+function resolveDecision(decision, context) {
+	if (typeof decision === "function") return decision(context);
+	return decision;
+}
+
+//#endregion
+export { mockRouter };
+//# sourceMappingURL=mock-router.mjs.map

package/esm/mock/mock-router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-router.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-router.ts"],"sourcesContent":["import { END } from \"../contracts/end.type\";\nimport type { Next } from \"../contracts/supervisor/next.type\";\nimport type { RouteContext } from \"../contracts/supervisor/route-context.type\";\n\n/**\n * A canned routing decision for {@link mockRouter}. Either a literal\n * {@link Next} value (intent key, fan-out array, or the `END`\n * sentinel) or a predicate that derives the decision from the live\n * {@link RouteContext} — the latter lets a test branch on accumulated\n * state without scripting an exact per-iteration sequence.\n */\nexport type MockRouterDecision<TState = Record<string, unknown>> =\n  | Next\n  | ((context: RouteContext<TState>) => Next);\n\n/**\n * Behavior when the canned decision queue is exhausted before the\n * supervisor terminates on its own.\n *\n * - `\"end\"` (default) — return `END`, terminating the run cleanly. The\n *   common case: script the interesting turns, let the run stop.\n * - `\"throw\"` — throw, surfacing the over-run as a test failure. Use\n *   when every iteration must be accounted for.\n * - `\"repeat\"` — replay the last decision for every further iteration.\n *   Useful for \"keep routing to the same intent until evaluate is\n *   satisfied\" scenarios.\n */\nexport type MockRouterExhaustion = \"end\" | \"throw\" | \"repeat\";\n\n/**\n * Options for {@link mockRouter}.\n */\nexport type MockRouterOptions = {\n  /** What to do once the decision queue is exhausted. Default `\"end\"`. */\n  onExhausted?: MockRouterExhaustion;\n};\n\n/**\n * Build a deterministic `route` callback that replays a canned\n * sequence of routing decisions — one per supervisor iteration — for\n * testing supervisors without an LLM router.\n *\n * Drop the returned callback into `ai.supervisor({ route: mockRouter([...]) })`\n * in place of an LLM `router`. The Nth iteration consumes the Nth\n * decision; a function decision is evaluated against the live\n * `RouteContext`. When the queue runs out, behavior follows\n * `options.onExhausted` (default: terminate with `END`).\n *\n * Pairs with the `toRouteTo` / `toConverge` matchers to assert the\n * resulting report tree.\n *\n * @example\n * const supervisor = ai.supervisor({\n *   name: \"draft-then-review\",\n *   intents: { writer, critic },\n *   route: mockRouter([\"writer\", \"critic\", END]),\n * });\n *\n * @example\n * // Branch on accumulated state, repeat the last decision until done.\n * route: mockRouter(\n *   [\"research\", (ctx) => (ctx.state.summary ? END : \"research\")],\n *   { onExhausted: \"repeat\" },\n * );\n */\nexport function mockRouter<TState = Record<string, unknown>>(\n  decisions: MockRouterDecision<TState>[],\n  options: MockRouterOptions = {},\n): (context: RouteContext<TState>) => Next {\n  const onExhausted = options.onExhausted ?? \"end\";\n  let cursor = 0;\n\n  return (context: RouteContext<TState>): Next => {\n    if (cursor < decisions.length) {\n      const decision = decisions[cursor];\n      cursor++;\n\n      return resolveDecision(decision, context);\n    }\n\n    if (onExhausted === \"throw\") {\n      throw new Error(\n        `mockRouter exhausted after ${decisions.length} decision(s) at iteration ${context.iteration}`,\n      );\n    }\n\n    if (onExhausted === \"repeat\" && decisions.length > 0) {\n      return resolveDecision(decisions[decisions.length - 1], context);\n    }\n\n    return END;\n  };\n}\n\n/**\n * Resolve a single decision entry into a concrete {@link Next} —\n * invoking the predicate form against the live context, or returning\n * the literal form verbatim.\n */\nfunction resolveDecision<TState>(\n  decision: MockRouterDecision<TState>,\n  context: RouteContext<TState>,\n): Next {\n  if (typeof decision === \"function\") {\n    return decision(context);\n  }\n\n  return decision;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAiEA,SAAgB,WACd,WACA,UAA6B,CAAC,GACW;CACzC,MAAM,cAAc,QAAQ,eAAe;CAC3C,IAAI,SAAS;CAEb,QAAQ,YAAwC;EAC9C,IAAI,SAAS,UAAU,QAAQ;GAC7B,MAAM,WAAW,UAAU;GAC3B;GAEA,OAAO,gBAAgB,UAAU,OAAO;EAC1C;EAEA,IAAI,gBAAgB,SAClB,MAAM,IAAI,MACR,8BAA8B,UAAU,OAAO,4BAA4B,QAAQ,WACrF;EAGF,IAAI,gBAAgB,YAAY,UAAU,SAAS,GACjD,OAAO,gBAAgB,UAAU,UAAU,SAAS,IAAI,OAAO;EAGjE,OAAO;CACT;AACF;;;;;;AAOA,SAAS,gBACP,UACA,SACM;CACN,IAAI,OAAO,aAAa,YACtB,OAAO,SAAS,OAAO;CAGzB,OAAO;AACT"}

package/esm/model/fallback-model.d.mts

@@ -0,0 +1,45 @@
+import { ModelContract } from "../contracts/model.contract.mjs";
+import { FallbackModelContract, FallbackModelOptions } from "../contracts/fallback-model.contract.mjs";
+
+//#region ../@warlock.js/ai/src/model/fallback-model.d.ts
+/**
+ * A `ModelContract` that wraps an ordered list of models and tries each
+ * in turn, advancing to the next only when the current one fails with a
+ * matching (transient) provider error.
+ *
+ * **Role.** A drop-in `ModelContract` for resilience: hand it to any
+ * agent / workflow / supervisor in place of a single model and provider
+ * outages, rate-limits, and timeouts transparently fail over to a
+ * backup. Non-transient failures (bad key, oversized prompt, blocked
+ * content) re-throw immediately rather than wastefully retrying.
+ *
+ * **What it owns / doesn't own.** Owns the ordered model list, the
+ * retry decision, and per-call usage aggregation across attempted
+ * models. Does NOT own retry/backoff timing (it advances instantly to
+ * the next model — pair it with a backoff middleware if you want delay)
+ * nor any provider I/O of its own; every call is delegated to a wrapped
+ * model.
+ *
+ * **Streaming fall-over caveat.** `stream()` can only fail over while no
+ * chunk has been emitted yet. Once the first `delta` / `tool-call`
+ * reaches the consumer, the partial output cannot be un-sent, so a
+ * mid-stream failure propagates instead of restarting on the next
+ * model.
+ *
+ * @example
+ * const model = fallbackModel([
+ *   ai.openai.model({ name: "gpt-4o" }),
+ *   ai.anthropic.model({ name: "claude-3-5-sonnet" }),
+ * ]);
+ * const agent = ai.agent({ model });
+ *
+ * @example
+ * // custom retry predicate
+ * const model = fallbackModel([primary, backup], {
+ *   retryOn: (error) => error instanceof ProviderError,
+ * });
+ */
+declare function fallbackModel(models: ModelContract[], options?: FallbackModelOptions): FallbackModelContract;
+//#endregion
+export { fallbackModel };
+//# sourceMappingURL=fallback-model.d.mts.map