@warlock.js/ai 4.1.15 → 4.2.1

package/esm/errors/workflow-drift-error.d.mts

@@ -2,7 +2,7 @@ import { ErrorCategory } from "./error-category.type.mjs";
 import { AIErrorOptions } from "./ai-error.mjs";
 import { WorkflowError } from "./workflow-error.mjs";
 
-//#region ../../@warlock.js/ai/src/errors/workflow-drift-error.d.ts
+//#region ../@warlock.js/ai/src/errors/workflow-drift-error.d.ts
 type WorkflowDriftErrorOptions = AIErrorOptions & {
   savedSignature: string;
   currentSignature: string;

package/esm/errors/workflow-drift-error.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-drift-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/workflow-drift-error.ts"],"mappings":";;;;;KAIY,yBAAA,GAA4B,cAAc;EACpD,cAAA;EACA,gBAAA;EACA,KAAA;AAAA;;;;;;cAQW,kBAAA,SAA2B,aAAA;EAAA,gBACf,eAAA,EAAiB,aAAA;EAAA,SAExB,cAAA;EAAA,SACA,gBAAA;EAAA,SACA,KAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,yBAAA;AAAA"}
+{"version":3,"file":"workflow-drift-error.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/workflow-drift-error.ts"],"mappings":";;;;;KAIY,yBAAA,GAA4B,cAAc;EACpD,cAAA;EACA,gBAAA;EACA,KAAA;AAAA;;;;;;cAQW,kBAAA,SAA2B,aAAA;EAAA,gBACf,eAAA,EAAiB,aAAA;EAAA,SAExB,cAAA;EAAA,SACA,gBAAA;EAAA,SACA,KAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,yBAAA;AAAA"}

package/esm/errors/workflow-drift-error.mjs

@@ -1,6 +1,6 @@
 import { WorkflowError } from "./workflow-error.mjs";
 
-//#region ../../@warlock.js/ai/src/errors/workflow-drift-error.ts
+//#region ../@warlock.js/ai/src/errors/workflow-drift-error.ts
 /**
 * `workflow.resume(runId)` found a snapshot whose structural signature
 * doesn't match the current workflow definition. Thrown without

package/esm/errors/workflow-drift-error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-drift-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/workflow-drift-error.ts"],"sourcesContent":["import type { AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\nimport { WorkflowError } from \"./workflow-error\";\n\nexport type WorkflowDriftErrorOptions = AIErrorOptions & {\n  savedSignature: string;\n  currentSignature: string;\n  runId: string;\n};\n\n/**\n * `workflow.resume(runId)` found a snapshot whose structural signature\n * doesn't match the current workflow definition. Thrown without\n * executing anything. User must discard, force, or migrate manually.\n */\nexport class WorkflowDriftError extends WorkflowError {\n  public static readonly defaultCategory: ErrorCategory = \"drift\";\n\n  public readonly savedSignature: string;\n  public readonly currentSignature: string;\n  public readonly runId: string;\n\n  public constructor(message: string, options: WorkflowDriftErrorOptions) {\n    super(message, options, \"WORKFLOW_DRIFT\");\n    this.name = \"WorkflowDriftError\";\n    this.savedSignature = options.savedSignature;\n    this.currentSignature = options.currentSignature;\n    this.runId = options.runId;\n  }\n}\n"],"mappings":";;;;;;;;AAeA,IAAa,qBAAb,cAAwC,cAAc;;yBACI;;CAMxD,AAAO,YAAY,SAAiB,SAAoC;EACtE,MAAM,SAAS,SAAS,gBAAgB;EACxC,KAAK,OAAO;EACZ,KAAK,iBAAiB,QAAQ;EAC9B,KAAK,mBAAmB,QAAQ;EAChC,KAAK,QAAQ,QAAQ;CACvB;AACF"}
+{"version":3,"file":"workflow-drift-error.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/workflow-drift-error.ts"],"sourcesContent":["import type { AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\nimport { WorkflowError } from \"./workflow-error\";\n\nexport type WorkflowDriftErrorOptions = AIErrorOptions & {\n  savedSignature: string;\n  currentSignature: string;\n  runId: string;\n};\n\n/**\n * `workflow.resume(runId)` found a snapshot whose structural signature\n * doesn't match the current workflow definition. Thrown without\n * executing anything. User must discard, force, or migrate manually.\n */\nexport class WorkflowDriftError extends WorkflowError {\n  public static readonly defaultCategory: ErrorCategory = \"drift\";\n\n  public readonly savedSignature: string;\n  public readonly currentSignature: string;\n  public readonly runId: string;\n\n  public constructor(message: string, options: WorkflowDriftErrorOptions) {\n    super(message, options, \"WORKFLOW_DRIFT\");\n    this.name = \"WorkflowDriftError\";\n    this.savedSignature = options.savedSignature;\n    this.currentSignature = options.currentSignature;\n    this.runId = options.runId;\n  }\n}\n"],"mappings":";;;;;;;;AAeA,IAAa,qBAAb,cAAwC,cAAc;;yBACI;;CAMxD,AAAO,YAAY,SAAiB,SAAoC;EACtE,MAAM,SAAS,SAAS,gBAAgB;EACxC,KAAK,OAAO;EACZ,KAAK,iBAAiB,QAAQ;EAC9B,KAAK,mBAAmB,QAAQ;EAChC,KAAK,QAAQ,QAAQ;CACvB;AACF"}

package/esm/errors/workflow-error.d.mts

@@ -1,7 +1,7 @@
 import { AIErrorCode } from "./error-code.type.mjs";
 import { AIError, AIErrorOptions } from "./ai-error.mjs";
 
-//#region ../../@warlock.js/ai/src/errors/workflow-error.d.ts
+//#region ../@warlock.js/ai/src/errors/workflow-error.d.ts
 /**
  * Base class for all workflow-specific failures. Subclasses carry
  * precise codes; this base catches everything `workflow.execute()`

package/esm/errors/workflow-error.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/workflow-error.ts"],"mappings":";;;;;;AAQA;;;cAAa,aAAA,SAAsB,OAAA;cAE/B,OAAA,UACA,OAAA,GAAU,cAAA,EACV,IAAA,GAAM,WAAA;AAAA"}
+{"version":3,"file":"workflow-error.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/workflow-error.ts"],"mappings":";;;;;;AAQA;;;cAAa,aAAA,SAAsB,OAAA;cAE/B,OAAA,UACA,OAAA,GAAU,cAAA,EACV,IAAA,GAAM,WAAA;AAAA"}

package/esm/errors/workflow-error.mjs

@@ -1,6 +1,6 @@
 import { AIError } from "./ai-error.mjs";
 
-//#region ../../@warlock.js/ai/src/errors/workflow-error.ts
+//#region ../@warlock.js/ai/src/errors/workflow-error.ts
 /**
 * Base class for all workflow-specific failures. Subclasses carry
 * precise codes; this base catches everything `workflow.execute()`

package/esm/errors/workflow-error.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/workflow-error.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"./ai-error\";\nimport type { AIErrorCode } from \"./error-code.type\";\n\n/**\n * Base class for all workflow-specific failures. Subclasses carry\n * precise codes; this base catches everything `workflow.execute()`\n * can produce beyond agent/tool/provider errors.\n */\nexport class WorkflowError extends AIError {\n  public constructor(\n    message: string,\n    options?: AIErrorOptions,\n    code: AIErrorCode = \"WORKFLOW_ERROR\",\n  ) {\n    super(code, message, options);\n    this.name = \"WorkflowError\";\n  }\n}\n"],"mappings":";;;;;;;;AAQA,IAAa,gBAAb,cAAmC,QAAQ;CACzC,AAAO,YACL,SACA,SACA,OAAoB,kBACpB;EACA,MAAM,MAAM,SAAS,OAAO;EAC5B,KAAK,OAAO;CACd;AACF"}
+{"version":3,"file":"workflow-error.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/errors/workflow-error.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"./ai-error\";\nimport type { AIErrorCode } from \"./error-code.type\";\n\n/**\n * Base class for all workflow-specific failures. Subclasses carry\n * precise codes; this base catches everything `workflow.execute()`\n * can produce beyond agent/tool/provider errors.\n */\nexport class WorkflowError extends AIError {\n  public constructor(\n    message: string,\n    options?: AIErrorOptions,\n    code: AIErrorCode = \"WORKFLOW_ERROR\",\n  ) {\n    super(code, message, options);\n    this.name = \"WorkflowError\";\n  }\n}\n"],"mappings":";;;;;;;;AAQA,IAAa,gBAAb,cAAmC,QAAQ;CACzC,AAAO,YACL,SACA,SACA,OAAoB,kBACpB;EACA,MAAM,MAAM,SAAS,OAAO;EAC5B,KAAK,OAAO;CACd;AACF"}

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

@@ -1,5 +1,5 @@
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
-//#region ../../@warlock.js/ai/src/middleware/builtins/budget.d.ts
+//#region ../@warlock.js/ai/src/middleware/builtins/budget.d.ts
 /**
  * Per-model pricing used to compute USD cost from token counts.
  * Caller-supplied — no bundled table. Keys are model names (the

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":";;;;;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"}

package/esm/middleware/builtins/budget.mjs

@@ -2,7 +2,7 @@ import { BudgetExceededError } from "../../errors/budget-exceeded-error.mjs";
 import "../../errors/index.mjs";
 import { namespacedState } from "../utils/namespaced-state.mjs";
 
-//#region ../../@warlock.js/ai/src/middleware/builtins/budget.ts
+//#region ../@warlock.js/ai/src/middleware/builtins/budget.ts
 function breach(limit, actual, unit, name) {
 	throw new BudgetExceededError(`budget "${name}" exceeded — ${actual} ${unit} (cap: ${limit})`, {
 		limit,

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,EAAE,IAAI;IAAE,QAAQ;IAAG,SAAS;IAAG,QAAQ;GAAM,CAAC;EACvD,EACF;EACA,MAAM,EACJ,MAAM,SAAS,UAAU;GACvB,MAAM,WAAW,gBAAgC,SAAS,IAAI,EAAE,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 { 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"}

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

@@ -1,6 +1,6 @@
 import { MiddlewareTripContext } from "../../contracts/middleware/middleware-context.type.mjs";
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
-//#region ../../@warlock.js/ai/src/middleware/builtins/guardrail.d.ts
+//#region ../@warlock.js/ai/src/middleware/builtins/guardrail.d.ts
 /**
  * Decision returned by a guardrail check function. `ok: true`
  * permits the call; `ok: false` rejects with a human-readable

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

@@ -1 +1 @@
-{"version":3,"file":"guardrail.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/builtins/guardrail.ts"],"mappings":";;;;;;;AAaA;KAAY,oBAAA;EAAyB,EAAA;AAAA;EAAe,EAAA;EAAW,MAAA;AAAA;;AAAM;AASrE;;;;;KAAY,cAAA,IACV,IAAA,UACA,OAAA,EAAS,qBAAA,KACN,oBAAA,GAAuB,OAAA,CAAQ,oBAAA;;;;;;KAOxB,gBAAA;EAPP;;;;AAAmD;AAOxD;EAOE,UAAA,GAAa,cAAA;;;;;;;;;EASb,WAAA,GAAc,cAAc;EA8Cd;;;;;EAxCd,IAAA;AAAA;;AAwCmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAArD,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,eAAe"}
+{"version":3,"file":"guardrail.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/guardrail.ts"],"mappings":";;;;;;;AAaA;KAAY,oBAAA;EAAyB,EAAA;AAAA;EAAe,EAAA;EAAW,MAAA;AAAA;;AAAM;AASrE;;;;;KAAY,cAAA,IACV,IAAA,UACA,OAAA,EAAS,qBAAA,KACN,oBAAA,GAAuB,OAAA,CAAQ,oBAAA;;;;;;KAOxB,gBAAA;EAPP;;;;AAAmD;AAOxD;EAOE,UAAA,GAAa,cAAA;;;;;;;;;EASb,WAAA,GAAc,cAAc;EA8Cd;;;;;EAxCd,IAAA;AAAA;;AAwCmE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAArD,SAAA,CAAU,OAAA,EAAS,gBAAA,GAAmB,eAAe"}

package/esm/middleware/builtins/guardrail.mjs

@@ -2,7 +2,7 @@ import { GuardrailViolationError } from "../../errors/guardrail-violation-error.
 import "../../errors/index.mjs";
 import { extractUserText } from "../utils/extract-user-text.mjs";
 
-//#region ../../@warlock.js/ai/src/middleware/builtins/guardrail.ts
+//#region ../@warlock.js/ai/src/middleware/builtins/guardrail.ts
 /**
 * Pre/post content guardrail for an agent run.
 *

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

@@ -1 +1 @@
-{"version":3,"file":"guardrail.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/builtins/guardrail.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareTripContext,\n} from \"../../contracts/middleware\";\nimport type { ModelResponse } from \"../../contracts/model.contract\";\nimport { GuardrailViolationError } from \"../../errors\";\nimport { extractUserText } from \"../utils\";\n\n/**\n * Decision returned by a guardrail check function. `ok: true`\n * permits the call; `ok: false` rejects with a human-readable\n * `reason` surfaced on `GuardrailViolationError`.\n */\nexport type GuardrailCheckResult = { ok: true } | { ok: false; reason: string };\n\n/**\n * Synchronous or asynchronous check invoked against the outbound\n * prompt (`inputCheck`) or the inbound response (`outputCheck`).\n * Receives the raw text and the surrounding trip context so\n * consumers can classify, route to an external moderation API, or\n * branch on tripIndex / messages history.\n */\nexport type GuardrailCheck = (\n  text: string,\n  context: MiddlewareTripContext,\n) => GuardrailCheckResult | Promise<GuardrailCheckResult>;\n\n/**\n * Configuration for `guardrail()`.  At least one of `inputCheck` or\n * `outputCheck` must be supplied — a guardrail with no checks is a\n * no-op.\n */\nexport type GuardrailOptions = {\n  /**\n   * Run against the outbound prompt just before the model sees it.\n   * Fires every trip with the concatenated last user-message text.\n   * Rejection aborts the trip with a `GuardrailViolationError` whose\n   * `phase === \"input\"`.\n   */\n  inputCheck?: GuardrailCheck;\n  /**\n   * Run against the model's response text after the trip completes.\n   * Fires every trip with `response.content`. Rejection aborts with\n   * a `GuardrailViolationError` whose `phase === \"output\"`.\n   *\n   * Output checks run BEFORE any tool dispatch — a rejected response\n   * means the tool calls it requested are never invoked.\n   */\n  outputCheck?: GuardrailCheck;\n  /**\n   * Override the middleware name — surfaces on\n   * `GuardrailViolationError.guardrail` so operators can tell two\n   * guardrails apart in logs. Default `\"guardrail\"`.\n   */\n  name?: string;\n};\n\n/**\n * Pre/post content guardrail for an agent run.\n *\n * **Role.** Inspects outbound prompts and inbound responses against\n * caller-supplied policies, aborting the trip with a typed\n * `GuardrailViolationError` when either trips a check. Consumers\n * distinguish `\"input\"` vs `\"output\"` violations off `error.phase`\n * — the two failure modes have very different product responses\n * (block the user vs re-prompt the model).\n *\n * **Scope.** Per-trip. Fires on every round-trip the agent makes,\n * including repair attempts and tool-follow-up trips. Input checks\n * evaluate the last user-role message; output checks evaluate the\n * raw model response text before any tool call is dispatched.\n *\n * **Composition.** A single middleware instance can carry both\n * `inputCheck` and `outputCheck`, or two separate instances can be\n * registered (useful when input and output policies come from\n * different teams / services). Registration order determines which\n * guardrail's violation surfaces first — the short-circuit throws\n * from the innermost offending hook, and outer guardrails never run\n * after an abort.\n *\n * **Not a sanitizer.** The guardrail either passes a trip unchanged\n * or aborts it. Mutating the prompt / response in-place is out of\n * scope — use a bespoke middleware for content rewriting.\n *\n * @example\n * const policy = guardrail({\n *   inputCheck: async (text) =>\n *     text.includes(\"SSN\") ? { ok: false, reason: \"pii\" } : { ok: true },\n *   outputCheck: async (text) =>\n *     text.length > 10_000 ? { ok: false, reason: \"too-long\" } : { ok: true },\n * });\n *\n * const myAgent = agent({ model, middleware: [policy] });\n */\nexport function guardrail(options: GuardrailOptions): AgentMiddleware {\n  const name = options.name ?? \"guardrail\";\n  const { inputCheck, outputCheck } = options;\n\n  return {\n    name,\n    trip: {\n      async before(context) {\n        if (!inputCheck) {\n          return;\n        }\n\n        const prompt = extractUserText(context.messages);\n\n        if (!prompt) {\n          return;\n        }\n\n        const verdict = await inputCheck(prompt, context);\n\n        if (!verdict.ok) {\n          throw new GuardrailViolationError(\n            `guardrail \"${name}\" rejected input — ${verdict.reason}`,\n            { phase: \"input\", reason: verdict.reason, guardrail: name },\n          );\n        }\n      },\n      async after(context, response: ModelResponse) {\n        if (!outputCheck) {\n          return;\n        }\n\n        if (!response.content) {\n          return;\n        }\n\n        const verdict = await outputCheck(response.content, context);\n\n        if (!verdict.ok) {\n          throw new GuardrailViolationError(\n            `guardrail \"${name}\" rejected output — ${verdict.reason}`,\n            { phase: \"output\", reason: verdict.reason, guardrail: name },\n          );\n        }\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,SAAgB,UAAU,SAA4C;CACpE,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,EAAE,YAAY,gBAAgB;CAEpC,OAAO;EACL;EACA,MAAM;GACJ,MAAM,OAAO,SAAS;IACpB,IAAI,CAAC,YACH;IAGF,MAAM,SAAS,gBAAgB,QAAQ,QAAQ;IAE/C,IAAI,CAAC,QACH;IAGF,MAAM,UAAU,MAAM,WAAW,QAAQ,OAAO;IAEhD,IAAI,CAAC,QAAQ,IACX,MAAM,IAAI,wBACR,cAAc,KAAK,qBAAqB,QAAQ,UAChD;KAAE,OAAO;KAAS,QAAQ,QAAQ;KAAQ,WAAW;IAAK,CAC5D;GAEJ;GACA,MAAM,MAAM,SAAS,UAAyB;IAC5C,IAAI,CAAC,aACH;IAGF,IAAI,CAAC,SAAS,SACZ;IAGF,MAAM,UAAU,MAAM,YAAY,SAAS,SAAS,OAAO;IAE3D,IAAI,CAAC,QAAQ,IACX,MAAM,IAAI,wBACR,cAAc,KAAK,sBAAsB,QAAQ,UACjD;KAAE,OAAO;KAAU,QAAQ,QAAQ;KAAQ,WAAW;IAAK,CAC7D;GAEJ;EACF;CACF;AACF"}
+{"version":3,"file":"guardrail.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/guardrail.ts"],"sourcesContent":["import type {\n  AgentMiddleware,\n  MiddlewareTripContext,\n} from \"../../contracts/middleware\";\nimport type { ModelResponse } from \"../../contracts/model.contract\";\nimport { GuardrailViolationError } from \"../../errors\";\nimport { extractUserText } from \"../utils\";\n\n/**\n * Decision returned by a guardrail check function. `ok: true`\n * permits the call; `ok: false` rejects with a human-readable\n * `reason` surfaced on `GuardrailViolationError`.\n */\nexport type GuardrailCheckResult = { ok: true } | { ok: false; reason: string };\n\n/**\n * Synchronous or asynchronous check invoked against the outbound\n * prompt (`inputCheck`) or the inbound response (`outputCheck`).\n * Receives the raw text and the surrounding trip context so\n * consumers can classify, route to an external moderation API, or\n * branch on tripIndex / messages history.\n */\nexport type GuardrailCheck = (\n  text: string,\n  context: MiddlewareTripContext,\n) => GuardrailCheckResult | Promise<GuardrailCheckResult>;\n\n/**\n * Configuration for `guardrail()`.  At least one of `inputCheck` or\n * `outputCheck` must be supplied — a guardrail with no checks is a\n * no-op.\n */\nexport type GuardrailOptions = {\n  /**\n   * Run against the outbound prompt just before the model sees it.\n   * Fires every trip with the concatenated last user-message text.\n   * Rejection aborts the trip with a `GuardrailViolationError` whose\n   * `phase === \"input\"`.\n   */\n  inputCheck?: GuardrailCheck;\n  /**\n   * Run against the model's response text after the trip completes.\n   * Fires every trip with `response.content`. Rejection aborts with\n   * a `GuardrailViolationError` whose `phase === \"output\"`.\n   *\n   * Output checks run BEFORE any tool dispatch — a rejected response\n   * means the tool calls it requested are never invoked.\n   */\n  outputCheck?: GuardrailCheck;\n  /**\n   * Override the middleware name — surfaces on\n   * `GuardrailViolationError.guardrail` so operators can tell two\n   * guardrails apart in logs. Default `\"guardrail\"`.\n   */\n  name?: string;\n};\n\n/**\n * Pre/post content guardrail for an agent run.\n *\n * **Role.** Inspects outbound prompts and inbound responses against\n * caller-supplied policies, aborting the trip with a typed\n * `GuardrailViolationError` when either trips a check. Consumers\n * distinguish `\"input\"` vs `\"output\"` violations off `error.phase`\n * — the two failure modes have very different product responses\n * (block the user vs re-prompt the model).\n *\n * **Scope.** Per-trip. Fires on every round-trip the agent makes,\n * including repair attempts and tool-follow-up trips. Input checks\n * evaluate the last user-role message; output checks evaluate the\n * raw model response text before any tool call is dispatched.\n *\n * **Composition.** A single middleware instance can carry both\n * `inputCheck` and `outputCheck`, or two separate instances can be\n * registered (useful when input and output policies come from\n * different teams / services). Registration order determines which\n * guardrail's violation surfaces first — the short-circuit throws\n * from the innermost offending hook, and outer guardrails never run\n * after an abort.\n *\n * **Not a sanitizer.** The guardrail either passes a trip unchanged\n * or aborts it. Mutating the prompt / response in-place is out of\n * scope — use a bespoke middleware for content rewriting.\n *\n * @example\n * const policy = guardrail({\n *   inputCheck: async (text) =>\n *     text.includes(\"SSN\") ? { ok: false, reason: \"pii\" } : { ok: true },\n *   outputCheck: async (text) =>\n *     text.length > 10_000 ? { ok: false, reason: \"too-long\" } : { ok: true },\n * });\n *\n * const myAgent = agent({ model, middleware: [policy] });\n */\nexport function guardrail(options: GuardrailOptions): AgentMiddleware {\n  const name = options.name ?? \"guardrail\";\n  const { inputCheck, outputCheck } = options;\n\n  return {\n    name,\n    trip: {\n      async before(context) {\n        if (!inputCheck) {\n          return;\n        }\n\n        const prompt = extractUserText(context.messages);\n\n        if (!prompt) {\n          return;\n        }\n\n        const verdict = await inputCheck(prompt, context);\n\n        if (!verdict.ok) {\n          throw new GuardrailViolationError(\n            `guardrail \"${name}\" rejected input — ${verdict.reason}`,\n            { phase: \"input\", reason: verdict.reason, guardrail: name },\n          );\n        }\n      },\n      async after(context, response: ModelResponse) {\n        if (!outputCheck) {\n          return;\n        }\n\n        if (!response.content) {\n          return;\n        }\n\n        const verdict = await outputCheck(response.content, context);\n\n        if (!verdict.ok) {\n          throw new GuardrailViolationError(\n            `guardrail \"${name}\" rejected output — ${verdict.reason}`,\n            { phase: \"output\", reason: verdict.reason, guardrail: name },\n          );\n        }\n      },\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA8FA,SAAgB,UAAU,SAA4C;CACpE,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,EAAE,YAAY,gBAAgB;CAEpC,OAAO;EACL;EACA,MAAM;GACJ,MAAM,OAAO,SAAS;IACpB,IAAI,CAAC,YACH;IAGF,MAAM,SAAS,gBAAgB,QAAQ,QAAQ;IAE/C,IAAI,CAAC,QACH;IAGF,MAAM,UAAU,MAAM,WAAW,QAAQ,OAAO;IAEhD,IAAI,CAAC,QAAQ,IACX,MAAM,IAAI,wBACR,cAAc,KAAK,qBAAqB,QAAQ,UAChD;KAAE,OAAO;KAAS,QAAQ,QAAQ;KAAQ,WAAW;IAAK,CAC5D;GAEJ;GACA,MAAM,MAAM,SAAS,UAAyB;IAC5C,IAAI,CAAC,aACH;IAGF,IAAI,CAAC,SAAS,SACZ;IAGF,MAAM,UAAU,MAAM,YAAY,SAAS,SAAS,OAAO;IAE3D,IAAI,CAAC,QAAQ,IACX,MAAM,IAAI,wBACR,cAAc,KAAK,sBAAsB,QAAQ,UACjD;KAAE,OAAO;KAAU,QAAQ,QAAQ;KAAQ,WAAW;IAAK,CAC7D;GAEJ;EACF;CACF;AACF"}

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

@@ -2,7 +2,7 @@ import { EmbedderContract } from "../../contracts/embedder.contract.mjs";
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
 import { CacheDriver } from "@warlock.js/cache";
 
-//#region ../../@warlock.js/ai/src/middleware/builtins/semantic-cache.d.ts
+//#region ../@warlock.js/ai/src/middleware/builtins/semantic-cache.d.ts
 /**
  * Configuration for `semanticCache()`.
  */

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

@@ -1 +1 @@
-{"version":3,"file":"semantic-cache.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts"],"mappings":";;;;;;;;KAWY,oBAAA;EAAoB,sEAE9B,QAAA,EAAU,gBAAA;EAaS;;;;;;;;;;AAuBf;AAkHN;EAzIE,KAAA,GAAQ,WAAW;;;;;EAKnB,SAAA;EAoI2E;AAAA;;;;;EA7H3E,KAAA;;;;;;EAMA,SAAA;;;;;EAKA,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkHc,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,eAAe"}
+{"version":3,"file":"semantic-cache.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts"],"mappings":";;;;;;;;KAWY,oBAAA;EAAoB,sEAE9B,QAAA,EAAU,gBAAA;EAaS;;;;;;;;;;AAuBf;AAkHN;EAzIE,KAAA,GAAQ,WAAW;;;;;EAKnB,SAAA;EAoI2E;AAAA;;;;;EA7H3E,KAAA;;;;;;EAMA,SAAA;;;;;EAKA,IAAA;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAkHc,aAAA,CAAc,OAAA,EAAS,oBAAA,GAAuB,eAAe"}

package/esm/middleware/builtins/semantic-cache.mjs

@@ -1,7 +1,7 @@
 import { extractUserText } from "../utils/extract-user-text.mjs";
 import { resolveDefaultStore } from "../../config.mjs";
 
-//#region ../../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts
+//#region ../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts
 const DEFAULT_NAMESPACE = "ai.cache";
 /**
 * Build a stable fingerprint for a prompt covering the full message

package/esm/middleware/builtins/semantic-cache.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"semantic-cache.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport { resolveDefaultStore } from \"../../config\";\nimport type { Message } from \"../../contracts/conversation-message.type\";\nimport type { EmbedderContract } from \"../../contracts/embedder.contract\";\nimport type { AgentMiddleware } from \"../../contracts/middleware\";\nimport type { ModelResponse } from \"../../contracts/model.contract\";\nimport { extractUserText } from \"../utils\";\n\n/**\n * Configuration for `semanticCache()`.\n */\nexport type SemanticCacheOptions = {\n  /** Embedder used to produce the query vector from the prompt text. */\n  embedder: EmbedderContract;\n  /**\n   * Vector-capable cache driver from `@warlock.js/cache`. Production\n   * deployments pick a driver with a real ANN index (`pg` with\n   * pgvector, `redis` with RediSearch). Dev / test environments use\n   * `new MemoryCacheDriver()` — zero config, correct, but O(N) per\n   * query. Drivers without similarity support throw\n   * `CacheUnsupportedError` from `set({ vector })` / `similar()`.\n   *\n   * Falls back to `ai.config({ defaultStore })` when omitted. When\n   * neither is set, the factory throws at construction time —\n   * semantic cache cannot operate without a store.\n   */\n  store?: CacheDriver<any, any>;\n  /**\n   * Minimum cosine similarity for a vector hit. Between 0 and 1 —\n   * 0.95 is a solid default for question-answering caches.\n   */\n  threshold: number;\n  /**\n   * Optional TTL in milliseconds. Entries whose `storedAt` is older\n   * than this are treated as misses on read and overwritten on the\n   * next write. Default: no expiry — entries live until the store\n   * evicts them (per its own TTL/eviction policy).\n   */\n  ttlMs?: number;\n  /**\n   * Namespace prefix applied to every key the cache writes. Lets\n   * multiple agents share one driver without collision. Default\n   * `\"ai.cache\"`.\n   */\n  namespace?: string;\n  /**\n   * Middleware name — also the state-bag key prefix inside a single\n   * execution. Default `\"semantic-cache\"`.\n   */\n  name?: string;\n};\n\ntype CachedEntry = {\n  response: ModelResponse;\n  storedAt: number;\n};\n\ntype PendingWrite = {\n  promptKey: string;\n  vector: number[];\n};\n\nconst DEFAULT_NAMESPACE = \"ai.cache\";\n\n/**\n * Build a stable fingerprint for a prompt covering the full message\n * list (system + history + user turn). Ensures two prompts sharing\n * the user text but differing in prior context do not collide on\n * the exact-match fast path.\n *\n * FNV-1a variant — cheap, collision-resistant enough for a cache,\n * dependency-free. NOT a cryptographic hash: collisions would\n * surface as wrong cache hits, not a security issue in the current\n * trust model.\n */\nfunction hashPrompt(messages: ReadonlyArray<Message>): string {\n  const serialized = messages\n    .map((message) => {\n      const role = message.role;\n      const content = Array.isArray(message.content)\n        ? message.content\n            .filter((part) => part.type === \"text\")\n            .map((part) => (part as { text: string }).text)\n            .join(\"|\")\n        : message.content;\n\n      return `${role}:${content}`;\n    })\n    .join(\"||\");\n\n  let hash = 0x811c9dc5;\n\n  for (let index = 0; index < serialized.length; index++) {\n    hash ^= serialized.charCodeAt(index);\n    hash = Math.imul(hash, 0x01000193);\n  }\n\n  return (hash >>> 0).toString(16);\n}\n\nfunction isFresh(entry: CachedEntry, ttlMs: number | undefined): boolean {\n  if (ttlMs === undefined) {\n    return true;\n  }\n\n  return Date.now() - entry.storedAt <= ttlMs;\n}\n\n/**\n * Semantic-similarity response cache for an agent run.\n *\n * **Role.** Skips LLM round-trips when the current prompt is\n * semantically close to one the agent has already answered. For\n * FAQ / support-style traffic this often eliminates 60–80% of\n * model calls — the production win is massive for cost and\n * latency.\n *\n * **Delegation to `@warlock.js/cache`.** This middleware does NOT\n * implement similarity search itself. It delegates to the supplied\n * `CacheDriver`. Production deployments pick a driver with an ANN\n * index (`pg` + pgvector, `redis` + RediSearch). Dev / test\n * environments pass `new MemoryCacheDriver()` — zero config, correct,\n * but O(N) per query. Drivers without similarity support throw\n * `CacheUnsupportedError` from `set({ vector })` / `similar()`.\n *\n * **Two-tier lookup.**\n * 1. *Exact-match key* — a cheap FNV hash over the entire message\n *    list. `store.get(hash)` returns the entry without an embedding\n *    round trip when the prompt hasn't changed at all.\n * 2. *Vector-match* — on exact-match miss, embed the prompt and\n *    call `store.similar(vector, { topK: 1, threshold })`. The\n *    driver uses its native similarity index; anything clearing\n *    `threshold` is returned as a hit.\n *\n * **Write-on-miss.** When both tiers miss, `trip.before` stashes\n * the prompt hash + vector in `ctx.state`; `trip.after` reads back\n * the pending entry and calls\n * `store.set(hash, entry, { vector })`. If an outer middleware\n * (guardrail) throws in `trip.after` before the cache's `trip.after`\n * runs, the pending entry is never written — bad responses stay out\n * of the cache **as long as the canonical install order is followed**\n * (cache outermost).\n *\n * **Synthetic-response on hit.** Returns a `ModelResponse` with\n * `usage: { input: 0, output: 0, total: 0 }` so budget /\n * observability correctly exclude the saved trip.\n *\n * @example\n * import { semanticCache } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const cache = semanticCache({\n *   embedder: openai.embedder({ name: \"text-embedding-3-small\" }),\n *   store,\n *   threshold: 0.95,\n *   ttlMs: 60 * 60 * 1000,\n * });\n *\n * const myAgent = agent({ model, middleware: [cache] });\n */\nexport function semanticCache(options: SemanticCacheOptions): AgentMiddleware {\n  const name = options.name ?? \"semantic-cache\";\n  const namespace = options.namespace ?? DEFAULT_NAMESPACE;\n  const pendingKey = `${name}.pending`;\n\n  // Resolve the effective store at factory time, not per-call. Every\n  // subsequent hook closes over `store` so the resolution happens once.\n  // Throws now (loud, at construction) instead of later during the\n  // first trip (silent until the agent actually runs).\n  const store = options.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `semanticCache: no store supplied — pass \\`store\\` in options or call \\`ai.config({ defaultStore })\\` at app boot before constructing the middleware`,\n    );\n  }\n\n  // Cache's parseKey replaces \":\" with \".\" so the namespace boundary\n  // matches what `similar()` actually returns in `hit.key`. Using a\n  // dot here keeps prefix checks aligned with stored keys.\n  const keyFor = (hash: string): string => `${namespace}.${hash}`;\n\n  return {\n    name,\n    log: true,\n    trip: {\n      async before(context) {\n        // Only cache the first trip's response. Subsequent trips\n        // happen because the previous trip requested tool calls — the\n        // message list now carries tool results the original prompt\n        // never saw, so a semantic match on the unchanged user text\n        // would serve back the prior `tool_calls` response and loop\n        // the agent forever. The first turn is also the only one\n        // where a \"same question → same final answer\" caching story\n        // is sound.\n        if (context.tripIndex !== 0) {\n          return;\n        }\n\n        const promptText = extractUserText(context.messages);\n\n        if (!promptText) {\n          return;\n        }\n\n        const promptKey = hashPrompt(context.messages);\n        const scopedKey = keyFor(promptKey);\n\n        const exact = await store.get<CachedEntry>(scopedKey);\n\n        if (exact && isFresh(exact, options.ttlMs)) {\n          return toSyntheticResponse(exact.response);\n        }\n\n        const query = await options.embedder.embed(promptText);\n\n        const [hit] = await store.similar<CachedEntry>(query.vector, {\n          topK: 1,\n          threshold: options.threshold,\n        });\n\n        if (hit && isFresh(hit.value, options.ttlMs)) {\n          // Only return hits whose stored key is within this cache's\n          // namespace. Drivers shared across namespaces would otherwise\n          // leak foreign entries into queries.\n          if (hit.key.startsWith(`${namespace}.`)) {\n            return toSyntheticResponse(hit.value.response);\n          }\n        }\n\n        const pending: PendingWrite = { promptKey, vector: query.vector };\n        context.state.set(pendingKey, pending);\n\n        return;\n      },\n      async after(context, response) {\n        const pending = context.state.get(pendingKey) as PendingWrite | undefined;\n\n        if (!pending) {\n          return;\n        }\n\n        // Mid-stream tool-call responses must not be cached — the\n        // useful answer comes from the trip *after* the tool returns.\n        // Crucially, leave the pending entry in place so a later trip\n        // (the one that actually finishes with `stop`) can read it\n        // and write the final response under the *original* trip-0\n        // prompt key. Deleting here would orphan the pending and the\n        // post-tool answer would never make it into the store.\n        if (response.finishReason === \"tool_calls\") {\n          return;\n        }\n\n        context.state.delete(pendingKey);\n\n        const entry: CachedEntry = { response, storedAt: Date.now() };\n\n        await store.set(keyFor(pending.promptKey), entry, {\n          vector: pending.vector,\n        });\n\n        return;\n      },\n    },\n  };\n}\n\nfunction toSyntheticResponse(response: ModelResponse): ModelResponse {\n  return {\n    content: response.content,\n    finishReason: response.finishReason,\n    usage: { input: 0, output: 0, total: 0 },\n    toolCalls: response.toolCalls,\n  };\n}\n"],"mappings":";;;;AA8DA,MAAM,oBAAoB;;;;;;;;;;;;AAa1B,SAAS,WAAW,UAA0C;CAC5D,MAAM,aAAa,SAChB,KAAK,YAAY;EAShB,OAAO,GARM,QAAQ,KAQN,GAPC,MAAM,QAAQ,QAAQ,OAAO,IACzC,QAAQ,QACL,QAAQ,SAAS,KAAK,SAAS,MAAM,EACrC,KAAK,SAAU,KAA0B,IAAI,EAC7C,KAAK,GAAG,IACX,QAAQ;CAGd,CAAC,EACA,KAAK,IAAI;CAEZ,IAAI,OAAO;CAEX,KAAK,IAAI,QAAQ,GAAG,QAAQ,WAAW,QAAQ,SAAS;EACtD,QAAQ,WAAW,WAAW,KAAK;EACnC,OAAO,KAAK,KAAK,MAAM,QAAU;CACnC;CAEA,QAAQ,SAAS,GAAG,SAAS,EAAE;AACjC;AAEA,SAAS,QAAQ,OAAoB,OAAoC;CACvE,IAAI,UAAU,QACZ,OAAO;CAGT,OAAO,KAAK,IAAI,IAAI,MAAM,YAAY;AACxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,cAAc,SAAgD;CAC5E,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,aAAa,GAAG,KAAK;CAM3B,MAAM,QAAQ,QAAQ,SAAS,oBAAoB;CAEnD,IAAI,CAAC,OACH,MAAM,IAAI,MACR,qJACF;CAMF,MAAM,UAAU,SAAyB,GAAG,UAAU,GAAG;CAEzD,OAAO;EACL;EACA,KAAK;EACL,MAAM;GACJ,MAAM,OAAO,SAAS;IASpB,IAAI,QAAQ,cAAc,GACxB;IAGF,MAAM,aAAa,gBAAgB,QAAQ,QAAQ;IAEnD,IAAI,CAAC,YACH;IAGF,MAAM,YAAY,WAAW,QAAQ,QAAQ;IAC7C,MAAM,YAAY,OAAO,SAAS;IAElC,MAAM,QAAQ,MAAM,MAAM,IAAiB,SAAS;IAEpD,IAAI,SAAS,QAAQ,OAAO,QAAQ,KAAK,GACvC,OAAO,oBAAoB,MAAM,QAAQ;IAG3C,MAAM,QAAQ,MAAM,QAAQ,SAAS,MAAM,UAAU;IAErD,MAAM,CAAC,OAAO,MAAM,MAAM,QAAqB,MAAM,QAAQ;KAC3D,MAAM;KACN,WAAW,QAAQ;IACrB,CAAC;IAED,IAAI,OAAO,QAAQ,IAAI,OAAO,QAAQ,KAAK,GAIzC;SAAI,IAAI,IAAI,WAAW,GAAG,UAAU,EAAE,GACpC,OAAO,oBAAoB,IAAI,MAAM,QAAQ;IAC/C;IAGF,MAAM,UAAwB;KAAE;KAAW,QAAQ,MAAM;IAAO;IAChE,QAAQ,MAAM,IAAI,YAAY,OAAO;GAGvC;GACA,MAAM,MAAM,SAAS,UAAU;IAC7B,MAAM,UAAU,QAAQ,MAAM,IAAI,UAAU;IAE5C,IAAI,CAAC,SACH;IAUF,IAAI,SAAS,iBAAiB,cAC5B;IAGF,QAAQ,MAAM,OAAO,UAAU;IAE/B,MAAM,QAAqB;KAAE;KAAU,UAAU,KAAK,IAAI;IAAE;IAE5D,MAAM,MAAM,IAAI,OAAO,QAAQ,SAAS,GAAG,OAAO,EAChD,QAAQ,QAAQ,OAClB,CAAC;GAGH;EACF;CACF;AACF;AAEA,SAAS,oBAAoB,UAAwC;CACnE,OAAO;EACL,SAAS,SAAS;EAClB,cAAc,SAAS;EACvB,OAAO;GAAE,OAAO;GAAG,QAAQ;GAAG,OAAO;EAAE;EACvC,WAAW,SAAS;CACtB;AACF"}
+{"version":3,"file":"semantic-cache.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/builtins/semantic-cache.ts"],"sourcesContent":["import type { CacheDriver } from \"@warlock.js/cache\";\nimport { resolveDefaultStore } from \"../../config\";\nimport type { Message } from \"../../contracts/conversation-message.type\";\nimport type { EmbedderContract } from \"../../contracts/embedder.contract\";\nimport type { AgentMiddleware } from \"../../contracts/middleware\";\nimport type { ModelResponse } from \"../../contracts/model.contract\";\nimport { extractUserText } from \"../utils\";\n\n/**\n * Configuration for `semanticCache()`.\n */\nexport type SemanticCacheOptions = {\n  /** Embedder used to produce the query vector from the prompt text. */\n  embedder: EmbedderContract;\n  /**\n   * Vector-capable cache driver from `@warlock.js/cache`. Production\n   * deployments pick a driver with a real ANN index (`pg` with\n   * pgvector, `redis` with RediSearch). Dev / test environments use\n   * `new MemoryCacheDriver()` — zero config, correct, but O(N) per\n   * query. Drivers without similarity support throw\n   * `CacheUnsupportedError` from `set({ vector })` / `similar()`.\n   *\n   * Falls back to `ai.config({ defaultStore })` when omitted. When\n   * neither is set, the factory throws at construction time —\n   * semantic cache cannot operate without a store.\n   */\n  store?: CacheDriver<any, any>;\n  /**\n   * Minimum cosine similarity for a vector hit. Between 0 and 1 —\n   * 0.95 is a solid default for question-answering caches.\n   */\n  threshold: number;\n  /**\n   * Optional TTL in milliseconds. Entries whose `storedAt` is older\n   * than this are treated as misses on read and overwritten on the\n   * next write. Default: no expiry — entries live until the store\n   * evicts them (per its own TTL/eviction policy).\n   */\n  ttlMs?: number;\n  /**\n   * Namespace prefix applied to every key the cache writes. Lets\n   * multiple agents share one driver without collision. Default\n   * `\"ai.cache\"`.\n   */\n  namespace?: string;\n  /**\n   * Middleware name — also the state-bag key prefix inside a single\n   * execution. Default `\"semantic-cache\"`.\n   */\n  name?: string;\n};\n\ntype CachedEntry = {\n  response: ModelResponse;\n  storedAt: number;\n};\n\ntype PendingWrite = {\n  promptKey: string;\n  vector: number[];\n};\n\nconst DEFAULT_NAMESPACE = \"ai.cache\";\n\n/**\n * Build a stable fingerprint for a prompt covering the full message\n * list (system + history + user turn). Ensures two prompts sharing\n * the user text but differing in prior context do not collide on\n * the exact-match fast path.\n *\n * FNV-1a variant — cheap, collision-resistant enough for a cache,\n * dependency-free. NOT a cryptographic hash: collisions would\n * surface as wrong cache hits, not a security issue in the current\n * trust model.\n */\nfunction hashPrompt(messages: ReadonlyArray<Message>): string {\n  const serialized = messages\n    .map((message) => {\n      const role = message.role;\n      const content = Array.isArray(message.content)\n        ? message.content\n            .filter((part) => part.type === \"text\")\n            .map((part) => (part as { text: string }).text)\n            .join(\"|\")\n        : message.content;\n\n      return `${role}:${content}`;\n    })\n    .join(\"||\");\n\n  let hash = 0x811c9dc5;\n\n  for (let index = 0; index < serialized.length; index++) {\n    hash ^= serialized.charCodeAt(index);\n    hash = Math.imul(hash, 0x01000193);\n  }\n\n  return (hash >>> 0).toString(16);\n}\n\nfunction isFresh(entry: CachedEntry, ttlMs: number | undefined): boolean {\n  if (ttlMs === undefined) {\n    return true;\n  }\n\n  return Date.now() - entry.storedAt <= ttlMs;\n}\n\n/**\n * Semantic-similarity response cache for an agent run.\n *\n * **Role.** Skips LLM round-trips when the current prompt is\n * semantically close to one the agent has already answered. For\n * FAQ / support-style traffic this often eliminates 60–80% of\n * model calls — the production win is massive for cost and\n * latency.\n *\n * **Delegation to `@warlock.js/cache`.** This middleware does NOT\n * implement similarity search itself. It delegates to the supplied\n * `CacheDriver`. Production deployments pick a driver with an ANN\n * index (`pg` + pgvector, `redis` + RediSearch). Dev / test\n * environments pass `new MemoryCacheDriver()` — zero config, correct,\n * but O(N) per query. Drivers without similarity support throw\n * `CacheUnsupportedError` from `set({ vector })` / `similar()`.\n *\n * **Two-tier lookup.**\n * 1. *Exact-match key* — a cheap FNV hash over the entire message\n *    list. `store.get(hash)` returns the entry without an embedding\n *    round trip when the prompt hasn't changed at all.\n * 2. *Vector-match* — on exact-match miss, embed the prompt and\n *    call `store.similar(vector, { topK: 1, threshold })`. The\n *    driver uses its native similarity index; anything clearing\n *    `threshold` is returned as a hit.\n *\n * **Write-on-miss.** When both tiers miss, `trip.before` stashes\n * the prompt hash + vector in `ctx.state`; `trip.after` reads back\n * the pending entry and calls\n * `store.set(hash, entry, { vector })`. If an outer middleware\n * (guardrail) throws in `trip.after` before the cache's `trip.after`\n * runs, the pending entry is never written — bad responses stay out\n * of the cache **as long as the canonical install order is followed**\n * (cache outermost).\n *\n * **Synthetic-response on hit.** Returns a `ModelResponse` with\n * `usage: { input: 0, output: 0, total: 0 }` so budget /\n * observability correctly exclude the saved trip.\n *\n * @example\n * import { semanticCache } from \"@warlock.js/ai\";\n * import { MemoryCacheDriver } from \"@warlock.js/cache\";\n *\n * const store = new MemoryCacheDriver();\n * store.setOptions({});\n *\n * const cache = semanticCache({\n *   embedder: openai.embedder({ name: \"text-embedding-3-small\" }),\n *   store,\n *   threshold: 0.95,\n *   ttlMs: 60 * 60 * 1000,\n * });\n *\n * const myAgent = agent({ model, middleware: [cache] });\n */\nexport function semanticCache(options: SemanticCacheOptions): AgentMiddleware {\n  const name = options.name ?? \"semantic-cache\";\n  const namespace = options.namespace ?? DEFAULT_NAMESPACE;\n  const pendingKey = `${name}.pending`;\n\n  // Resolve the effective store at factory time, not per-call. Every\n  // subsequent hook closes over `store` so the resolution happens once.\n  // Throws now (loud, at construction) instead of later during the\n  // first trip (silent until the agent actually runs).\n  const store = options.store ?? resolveDefaultStore();\n\n  if (!store) {\n    throw new Error(\n      `semanticCache: no store supplied — pass \\`store\\` in options or call \\`ai.config({ defaultStore })\\` at app boot before constructing the middleware`,\n    );\n  }\n\n  // Cache's parseKey replaces \":\" with \".\" so the namespace boundary\n  // matches what `similar()` actually returns in `hit.key`. Using a\n  // dot here keeps prefix checks aligned with stored keys.\n  const keyFor = (hash: string): string => `${namespace}.${hash}`;\n\n  return {\n    name,\n    log: true,\n    trip: {\n      async before(context) {\n        // Only cache the first trip's response. Subsequent trips\n        // happen because the previous trip requested tool calls — the\n        // message list now carries tool results the original prompt\n        // never saw, so a semantic match on the unchanged user text\n        // would serve back the prior `tool_calls` response and loop\n        // the agent forever. The first turn is also the only one\n        // where a \"same question → same final answer\" caching story\n        // is sound.\n        if (context.tripIndex !== 0) {\n          return;\n        }\n\n        const promptText = extractUserText(context.messages);\n\n        if (!promptText) {\n          return;\n        }\n\n        const promptKey = hashPrompt(context.messages);\n        const scopedKey = keyFor(promptKey);\n\n        const exact = await store.get<CachedEntry>(scopedKey);\n\n        if (exact && isFresh(exact, options.ttlMs)) {\n          return toSyntheticResponse(exact.response);\n        }\n\n        const query = await options.embedder.embed(promptText);\n\n        const [hit] = await store.similar<CachedEntry>(query.vector, {\n          topK: 1,\n          threshold: options.threshold,\n        });\n\n        if (hit && isFresh(hit.value, options.ttlMs)) {\n          // Only return hits whose stored key is within this cache's\n          // namespace. Drivers shared across namespaces would otherwise\n          // leak foreign entries into queries.\n          if (hit.key.startsWith(`${namespace}.`)) {\n            return toSyntheticResponse(hit.value.response);\n          }\n        }\n\n        const pending: PendingWrite = { promptKey, vector: query.vector };\n        context.state.set(pendingKey, pending);\n\n        return;\n      },\n      async after(context, response) {\n        const pending = context.state.get(pendingKey) as PendingWrite | undefined;\n\n        if (!pending) {\n          return;\n        }\n\n        // Mid-stream tool-call responses must not be cached — the\n        // useful answer comes from the trip *after* the tool returns.\n        // Crucially, leave the pending entry in place so a later trip\n        // (the one that actually finishes with `stop`) can read it\n        // and write the final response under the *original* trip-0\n        // prompt key. Deleting here would orphan the pending and the\n        // post-tool answer would never make it into the store.\n        if (response.finishReason === \"tool_calls\") {\n          return;\n        }\n\n        context.state.delete(pendingKey);\n\n        const entry: CachedEntry = { response, storedAt: Date.now() };\n\n        await store.set(keyFor(pending.promptKey), entry, {\n          vector: pending.vector,\n        });\n\n        return;\n      },\n    },\n  };\n}\n\nfunction toSyntheticResponse(response: ModelResponse): ModelResponse {\n  return {\n    content: response.content,\n    finishReason: response.finishReason,\n    usage: { input: 0, output: 0, total: 0 },\n    toolCalls: response.toolCalls,\n  };\n}\n"],"mappings":";;;;AA8DA,MAAM,oBAAoB;;;;;;;;;;;;AAa1B,SAAS,WAAW,UAA0C;CAC5D,MAAM,aAAa,SAChB,KAAK,YAAY;EAShB,OAAO,GARM,QAAQ,KAQN,GAPC,MAAM,QAAQ,QAAQ,OAAO,IACzC,QAAQ,QACL,QAAQ,SAAS,KAAK,SAAS,MAAM,CAAC,CACtC,KAAK,SAAU,KAA0B,IAAI,CAAC,CAC9C,KAAK,GAAG,IACX,QAAQ;CAGd,CAAC,CAAC,CACD,KAAK,IAAI;CAEZ,IAAI,OAAO;CAEX,KAAK,IAAI,QAAQ,GAAG,QAAQ,WAAW,QAAQ,SAAS;EACtD,QAAQ,WAAW,WAAW,KAAK;EACnC,OAAO,KAAK,KAAK,MAAM,QAAU;CACnC;CAEA,QAAQ,SAAS,EAAC,CAAE,SAAS,EAAE;AACjC;AAEA,SAAS,QAAQ,OAAoB,OAAoC;CACvE,IAAI,UAAU,QACZ,OAAO;CAGT,OAAO,KAAK,IAAI,IAAI,MAAM,YAAY;AACxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,SAAgB,cAAc,SAAgD;CAC5E,MAAM,OAAO,QAAQ,QAAQ;CAC7B,MAAM,YAAY,QAAQ,aAAa;CACvC,MAAM,aAAa,GAAG,KAAK;CAM3B,MAAM,QAAQ,QAAQ,SAAS,oBAAoB;CAEnD,IAAI,CAAC,OACH,MAAM,IAAI,MACR,qJACF;CAMF,MAAM,UAAU,SAAyB,GAAG,UAAU,GAAG;CAEzD,OAAO;EACL;EACA,KAAK;EACL,MAAM;GACJ,MAAM,OAAO,SAAS;IASpB,IAAI,QAAQ,cAAc,GACxB;IAGF,MAAM,aAAa,gBAAgB,QAAQ,QAAQ;IAEnD,IAAI,CAAC,YACH;IAGF,MAAM,YAAY,WAAW,QAAQ,QAAQ;IAC7C,MAAM,YAAY,OAAO,SAAS;IAElC,MAAM,QAAQ,MAAM,MAAM,IAAiB,SAAS;IAEpD,IAAI,SAAS,QAAQ,OAAO,QAAQ,KAAK,GACvC,OAAO,oBAAoB,MAAM,QAAQ;IAG3C,MAAM,QAAQ,MAAM,QAAQ,SAAS,MAAM,UAAU;IAErD,MAAM,CAAC,OAAO,MAAM,MAAM,QAAqB,MAAM,QAAQ;KAC3D,MAAM;KACN,WAAW,QAAQ;IACrB,CAAC;IAED,IAAI,OAAO,QAAQ,IAAI,OAAO,QAAQ,KAAK,GAIzC;SAAI,IAAI,IAAI,WAAW,GAAG,UAAU,EAAE,GACpC,OAAO,oBAAoB,IAAI,MAAM,QAAQ;IAC/C;IAGF,MAAM,UAAwB;KAAE;KAAW,QAAQ,MAAM;IAAO;IAChE,QAAQ,MAAM,IAAI,YAAY,OAAO;GAGvC;GACA,MAAM,MAAM,SAAS,UAAU;IAC7B,MAAM,UAAU,QAAQ,MAAM,IAAI,UAAU;IAE5C,IAAI,CAAC,SACH;IAUF,IAAI,SAAS,iBAAiB,cAC5B;IAGF,QAAQ,MAAM,OAAO,UAAU;IAE/B,MAAM,QAAqB;KAAE;KAAU,UAAU,KAAK,IAAI;IAAE;IAE5D,MAAM,MAAM,IAAI,OAAO,QAAQ,SAAS,GAAG,OAAO,EAChD,QAAQ,QAAQ,OAClB,CAAC;GAGH;EACF;CACF;AACF;AAEA,SAAS,oBAAoB,UAAwC;CACnE,OAAO;EACL,SAAS,SAAS;EAClB,cAAc,SAAS;EACvB,OAAO;GAAE,OAAO;GAAG,QAAQ;GAAG,OAAO;EAAE;EACvC,WAAW,SAAS;CACtB;AACF"}

package/esm/middleware/helpers/compose.d.mts

@@ -1,5 +1,5 @@
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
-//#region ../../@warlock.js/ai/src/middleware/helpers/compose.d.ts
+//#region ../@warlock.js/ai/src/middleware/helpers/compose.d.ts
 /**
  * Flatten one or more middleware sources into a single ordered
  * array suitable for `agent({ middleware: [...] })`.

package/esm/middleware/helpers/compose.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"compose.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/helpers/compose.ts"],"mappings":";;;;;AAsCA;;;;;;;;;;;;;;;;;AAEkB;;;;;;;;;;;;;;;;iBAFF,iBAAA,CAAA,GACX,OAAA,EAAS,aAAA,CAAc,eAAA,GAAkB,aAAA,CAAc,eAAA,KACzD,eAAA"}
+{"version":3,"file":"compose.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/helpers/compose.ts"],"mappings":";;;;;AAsCA;;;;;;;;;;;;;;;;;AAEkB;;;;;;;;;;;;;;;;iBAFF,iBAAA,IACX,OAAA,EAAS,aAAA,CAAc,eAAA,GAAkB,aAAA,CAAc,eAAA,KACzD,eAAA"}

package/esm/middleware/helpers/compose.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/ai/src/middleware/helpers/compose.ts
+//#region ../@warlock.js/ai/src/middleware/helpers/compose.ts
 /**
 * Flatten one or more middleware sources into a single ordered
 * array suitable for `agent({ middleware: [...] })`.

package/esm/middleware/helpers/compose.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"compose.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/helpers/compose.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../../contracts/middleware\";\n\n/**\n * Flatten one or more middleware sources into a single ordered\n * array suitable for `agent({ middleware: [...] })`.\n *\n * **Role.** As middleware catalogs grow, agent configs accumulate\n * long arrays that mix \"always-on\" stacks (cache + budget + guardrail)\n * with per-concern extras (per-tool rate-limits, audit hooks). A\n * single `compose` call lets callers keep those sources as named\n * variables and flatten at the registration site.\n *\n * **Semantics.** Registration order is preserved across sources —\n * `compose(a, b, c)` produces `[...a, ...b, ...c]`. Because the\n * pipeline's onion is strictly registration-ordered, the flattened\n * order is the execution order. No de-duplication, no sorting, no\n * priority logic — that would hide bugs, not fix them.\n *\n * **Accepts arrays OR individual middlewares.** Both forms are\n * common in callsite code; the helper flattens either.\n *\n * @example\n * const standardStack = [\n *   ai.middleware.semanticCache({ ... }),\n *   ai.middleware.budget({ maxTokens: 20_000 }),\n *   ai.middleware.guardrail({ ... }),\n * ];\n *\n * const toolRateLimits = [\n *   toolRateLimit({ tool: \"search_web\", maxCalls: 3 }),\n *   toolRateLimit({ tool: \"expensive_api\", maxCalls: 1 }),\n * ];\n *\n * const myAgent = ai.agent({\n *   model,\n *   middleware: ai.middleware.compose(standardStack, toolRateLimits, auditMiddleware),\n * });\n */\nexport function composeMiddleware(\n  ...sources: ReadonlyArray<AgentMiddleware | ReadonlyArray<AgentMiddleware>>\n): AgentMiddleware[] {\n  const out: AgentMiddleware[] = [];\n\n  for (const source of sources) {\n    if (Array.isArray(source)) {\n      out.push(...source);\n      continue;\n    }\n\n    out.push(source as AgentMiddleware);\n  }\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,kBACd,GAAG,SACgB;CACnB,MAAM,MAAyB,CAAC;CAEhC,KAAK,MAAM,UAAU,SAAS;EAC5B,IAAI,MAAM,QAAQ,MAAM,GAAG;GACzB,IAAI,KAAK,GAAG,MAAM;GAClB;EACF;EAEA,IAAI,KAAK,MAAyB;CACpC;CAEA,OAAO;AACT"}
+{"version":3,"file":"compose.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/helpers/compose.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../../contracts/middleware\";\n\n/**\n * Flatten one or more middleware sources into a single ordered\n * array suitable for `agent({ middleware: [...] })`.\n *\n * **Role.** As middleware catalogs grow, agent configs accumulate\n * long arrays that mix \"always-on\" stacks (cache + budget + guardrail)\n * with per-concern extras (per-tool rate-limits, audit hooks). A\n * single `compose` call lets callers keep those sources as named\n * variables and flatten at the registration site.\n *\n * **Semantics.** Registration order is preserved across sources —\n * `compose(a, b, c)` produces `[...a, ...b, ...c]`. Because the\n * pipeline's onion is strictly registration-ordered, the flattened\n * order is the execution order. No de-duplication, no sorting, no\n * priority logic — that would hide bugs, not fix them.\n *\n * **Accepts arrays OR individual middlewares.** Both forms are\n * common in callsite code; the helper flattens either.\n *\n * @example\n * const standardStack = [\n *   ai.middleware.semanticCache({ ... }),\n *   ai.middleware.budget({ maxTokens: 20_000 }),\n *   ai.middleware.guardrail({ ... }),\n * ];\n *\n * const toolRateLimits = [\n *   toolRateLimit({ tool: \"search_web\", maxCalls: 3 }),\n *   toolRateLimit({ tool: \"expensive_api\", maxCalls: 1 }),\n * ];\n *\n * const myAgent = ai.agent({\n *   model,\n *   middleware: ai.middleware.compose(standardStack, toolRateLimits, auditMiddleware),\n * });\n */\nexport function composeMiddleware(\n  ...sources: ReadonlyArray<AgentMiddleware | ReadonlyArray<AgentMiddleware>>\n): AgentMiddleware[] {\n  const out: AgentMiddleware[] = [];\n\n  for (const source of sources) {\n    if (Array.isArray(source)) {\n      out.push(...source);\n      continue;\n    }\n\n    out.push(source as AgentMiddleware);\n  }\n\n  return out;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAsCA,SAAgB,kBACd,GAAG,SACgB;CACnB,MAAM,MAAyB,CAAC;CAEhC,KAAK,MAAM,UAAU,SAAS;EAC5B,IAAI,MAAM,QAAQ,MAAM,GAAG;GACzB,IAAI,KAAK,GAAG,MAAM;GAClB;EACF;EAEA,IAAI,KAAK,MAAyB;CACpC;CAEA,OAAO;AACT"}

package/esm/middleware/helpers/for-tool.d.mts

@@ -1,5 +1,5 @@
 import { AgentMiddleware } from "../../contracts/middleware/middleware.contract.mjs";
-//#region ../../@warlock.js/ai/src/middleware/helpers/for-tool.d.ts
+//#region ../@warlock.js/ai/src/middleware/helpers/for-tool.d.ts
 /**
  * Scope a middleware's `tool`-level hooks to only fire for a
  * specific tool name (or a set of names). `execute` and `trip`

package/esm/middleware/helpers/for-tool.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"for-tool.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/helpers/for-tool.ts"],"mappings":";;;;;AAmDA;;;;;;;;;;;;;;AAGkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAHF,OAAA,CACd,SAAA,WAAoB,aAAA,UACpB,UAAA,EAAY,eAAA,GACX,eAAA"}
+{"version":3,"file":"for-tool.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/helpers/for-tool.ts"],"mappings":";;;;;AAmDA;;;;;;;;;;;;;;AAGkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAHF,OAAA,CACd,SAAA,WAAoB,aAAA,UACpB,UAAA,EAAY,eAAA,GACX,eAAA"}

package/esm/middleware/helpers/for-tool.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/ai/src/middleware/helpers/for-tool.ts
+//#region ../@warlock.js/ai/src/middleware/helpers/for-tool.ts
 /**
 * Scope a middleware's `tool`-level hooks to only fire for a
 * specific tool name (or a set of names). `execute` and `trip`

package/esm/middleware/helpers/for-tool.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"for-tool.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/helpers/for-tool.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../../contracts/middleware\";\n\n/**\n * Scope a middleware's `tool`-level hooks to only fire for a\n * specific tool name (or a set of names). `execute` and `trip`\n * hooks pass through unchanged.\n *\n * **Role.** Tool-specific concerns — \"rate-limit `search_web`\",\n * \"cache results for `fetch_faq`\" — are common. Rather than adding\n * a `middleware` field to `ai.tool()` (see decisions §27), the\n * framework keeps one contract (`AgentMiddleware`) and offers this\n * helper for the locality problem. The middleware body stays agnostic\n * of the tool name; `forTool` handles the filtering.\n *\n * **What gets filtered.** Only `tool.before` / `tool.after` /\n * `tool.onError`. Each hook is wrapped so that `ctx.tool.name`\n * must be in the allowed set or the wrapped hook is a no-op.\n * `execute` and `trip` hooks are NOT touched — they run normally.\n *\n * **Why not filter execute/trip too?** Because a middleware that\n * reaches across levels (a tool-specific budget that initializes a\n * counter in `execute.before` and checks it in `tool.before`) still\n * needs `execute.before` to fire unconditionally. Scoping all hooks\n * would break cross-level middleware; scoping only `tool` hooks\n * matches the mental model of \"this middleware cares about these\n * tools.\"\n *\n * **Single-name vs multi-name.** A string matches one tool; a string\n * array matches any of the listed tools. No wildcards, no regex —\n * keep it boring.\n *\n * @example\n * // Single tool\n * const scoped = ai.middleware.forTool(\n *   \"search_web\",\n *   toolRateLimit({ maxCalls: 3 }),\n * );\n *\n * @example\n * // Multiple tools sharing a rule\n * const scoped = ai.middleware.forTool(\n *   [\"paid_api\", \"expensive_db\"],\n *   toolRateLimit({ maxCalls: 5 }),\n * );\n *\n * ai.agent({\n *   model,\n *   tools: [webTool, paidApiTool, expensiveDbTool],\n *   middleware: [scoped],\n * });\n */\nexport function forTool(\n  toolNames: string | ReadonlyArray<string>,\n  middleware: AgentMiddleware,\n): AgentMiddleware {\n  const allowed = new Set(\n    typeof toolNames === \"string\" ? [toolNames] : toolNames,\n  );\n  const scope =\n    allowed.size === 1 ? Array.from(allowed)[0] : Array.from(allowed).join(\"+\");\n\n  if (!middleware.tool) {\n    return middleware;\n  }\n\n  const innerBefore = middleware.tool.before;\n  const innerAfter = middleware.tool.after;\n  const innerOnError = middleware.tool.onError;\n\n  return {\n    ...middleware,\n    name: `${middleware.name}[for:${scope}]`,\n    tool: {\n      before: innerBefore\n        ? async ctx => {\n            if (!allowed.has(ctx.tool.name)) {\n              return;\n            }\n\n            return innerBefore(ctx);\n          }\n        : undefined,\n      after: innerAfter\n        ? async (ctx, result) => {\n            if (!allowed.has(ctx.tool.name)) {\n              return;\n            }\n\n            return innerAfter(ctx, result);\n          }\n        : undefined,\n      onError: innerOnError\n        ? async (ctx, error) => {\n            if (!allowed.has(ctx.tool.name)) {\n              return;\n            }\n\n            return innerOnError(ctx, error);\n          }\n        : undefined,\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,QACd,WACA,YACiB;CACjB,MAAM,UAAU,IAAI,IAClB,OAAO,cAAc,WAAW,CAAC,SAAS,IAAI,SAChD;CACA,MAAM,QACJ,QAAQ,SAAS,IAAI,MAAM,KAAK,OAAO,EAAE,KAAK,MAAM,KAAK,OAAO,EAAE,KAAK,GAAG;CAE5E,IAAI,CAAC,WAAW,MACd,OAAO;CAGT,MAAM,cAAc,WAAW,KAAK;CACpC,MAAM,aAAa,WAAW,KAAK;CACnC,MAAM,eAAe,WAAW,KAAK;CAErC,OAAO;EACL,GAAG;EACH,MAAM,GAAG,WAAW,KAAK,OAAO,MAAM;EACtC,MAAM;GACJ,QAAQ,cACJ,OAAM,QAAO;IACX,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,IAAI,GAC5B;IAGF,OAAO,YAAY,GAAG;GACxB,IACA;GACJ,OAAO,aACH,OAAO,KAAK,WAAW;IACrB,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,IAAI,GAC5B;IAGF,OAAO,WAAW,KAAK,MAAM;GAC/B,IACA;GACJ,SAAS,eACL,OAAO,KAAK,UAAU;IACpB,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,IAAI,GAC5B;IAGF,OAAO,aAAa,KAAK,KAAK;GAChC,IACA;EACN;CACF;AACF"}
+{"version":3,"file":"for-tool.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/helpers/for-tool.ts"],"sourcesContent":["import type { AgentMiddleware } from \"../../contracts/middleware\";\n\n/**\n * Scope a middleware's `tool`-level hooks to only fire for a\n * specific tool name (or a set of names). `execute` and `trip`\n * hooks pass through unchanged.\n *\n * **Role.** Tool-specific concerns — \"rate-limit `search_web`\",\n * \"cache results for `fetch_faq`\" — are common. Rather than adding\n * a `middleware` field to `ai.tool()` (see decisions §27), the\n * framework keeps one contract (`AgentMiddleware`) and offers this\n * helper for the locality problem. The middleware body stays agnostic\n * of the tool name; `forTool` handles the filtering.\n *\n * **What gets filtered.** Only `tool.before` / `tool.after` /\n * `tool.onError`. Each hook is wrapped so that `ctx.tool.name`\n * must be in the allowed set or the wrapped hook is a no-op.\n * `execute` and `trip` hooks are NOT touched — they run normally.\n *\n * **Why not filter execute/trip too?** Because a middleware that\n * reaches across levels (a tool-specific budget that initializes a\n * counter in `execute.before` and checks it in `tool.before`) still\n * needs `execute.before` to fire unconditionally. Scoping all hooks\n * would break cross-level middleware; scoping only `tool` hooks\n * matches the mental model of \"this middleware cares about these\n * tools.\"\n *\n * **Single-name vs multi-name.** A string matches one tool; a string\n * array matches any of the listed tools. No wildcards, no regex —\n * keep it boring.\n *\n * @example\n * // Single tool\n * const scoped = ai.middleware.forTool(\n *   \"search_web\",\n *   toolRateLimit({ maxCalls: 3 }),\n * );\n *\n * @example\n * // Multiple tools sharing a rule\n * const scoped = ai.middleware.forTool(\n *   [\"paid_api\", \"expensive_db\"],\n *   toolRateLimit({ maxCalls: 5 }),\n * );\n *\n * ai.agent({\n *   model,\n *   tools: [webTool, paidApiTool, expensiveDbTool],\n *   middleware: [scoped],\n * });\n */\nexport function forTool(\n  toolNames: string | ReadonlyArray<string>,\n  middleware: AgentMiddleware,\n): AgentMiddleware {\n  const allowed = new Set(\n    typeof toolNames === \"string\" ? [toolNames] : toolNames,\n  );\n  const scope =\n    allowed.size === 1 ? Array.from(allowed)[0] : Array.from(allowed).join(\"+\");\n\n  if (!middleware.tool) {\n    return middleware;\n  }\n\n  const innerBefore = middleware.tool.before;\n  const innerAfter = middleware.tool.after;\n  const innerOnError = middleware.tool.onError;\n\n  return {\n    ...middleware,\n    name: `${middleware.name}[for:${scope}]`,\n    tool: {\n      before: innerBefore\n        ? async ctx => {\n            if (!allowed.has(ctx.tool.name)) {\n              return;\n            }\n\n            return innerBefore(ctx);\n          }\n        : undefined,\n      after: innerAfter\n        ? async (ctx, result) => {\n            if (!allowed.has(ctx.tool.name)) {\n              return;\n            }\n\n            return innerAfter(ctx, result);\n          }\n        : undefined,\n      onError: innerOnError\n        ? async (ctx, error) => {\n            if (!allowed.has(ctx.tool.name)) {\n              return;\n            }\n\n            return innerOnError(ctx, error);\n          }\n        : undefined,\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,SAAgB,QACd,WACA,YACiB;CACjB,MAAM,UAAU,IAAI,IAClB,OAAO,cAAc,WAAW,CAAC,SAAS,IAAI,SAChD;CACA,MAAM,QACJ,QAAQ,SAAS,IAAI,MAAM,KAAK,OAAO,CAAC,CAAC,KAAK,MAAM,KAAK,OAAO,CAAC,CAAC,KAAK,GAAG;CAE5E,IAAI,CAAC,WAAW,MACd,OAAO;CAGT,MAAM,cAAc,WAAW,KAAK;CACpC,MAAM,aAAa,WAAW,KAAK;CACnC,MAAM,eAAe,WAAW,KAAK;CAErC,OAAO;EACL,GAAG;EACH,MAAM,GAAG,WAAW,KAAK,OAAO,MAAM;EACtC,MAAM;GACJ,QAAQ,cACJ,OAAM,QAAO;IACX,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,IAAI,GAC5B;IAGF,OAAO,YAAY,GAAG;GACxB,IACA;GACJ,OAAO,aACH,OAAO,KAAK,WAAW;IACrB,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,IAAI,GAC5B;IAGF,OAAO,WAAW,KAAK,MAAM;GAC/B,IACA;GACJ,SAAS,eACL,OAAO,KAAK,UAAU;IACpB,IAAI,CAAC,QAAQ,IAAI,IAAI,KAAK,IAAI,GAC5B;IAGF,OAAO,aAAa,KAAK,KAAK;GAChC,IACA;EACN;CACF;AACF"}

package/esm/middleware/pipeline.d.mts

@@ -2,7 +2,7 @@ import { MiddlewareExecuteContext, MiddlewareToolContext, MiddlewareTripContext
 import { AgentMiddleware } from "../contracts/middleware/middleware.contract.mjs";
 import { Logger } from "@warlock.js/logger";
 
-//#region ../../@warlock.js/ai/src/middleware/pipeline.d.ts
+//#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.

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,UAAA,CAC9C,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":";;;;;;;;;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"}

package/esm/middleware/pipeline.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/ai/src/middleware/pipeline.ts
+//#region ../@warlock.js/ai/src/middleware/pipeline.ts
 const LOG_MODULE = "ai.middleware";
 /**
 * Run an inner async operation through a stack of agent middlewares

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  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"}

package/esm/middleware/utils/extract-user-text.d.mts

@@ -1,6 +1,6 @@
 import { Message } from "../../contracts/conversation-message.type.mjs";
 
-//#region ../../@warlock.js/ai/src/middleware/utils/extract-user-text.d.ts
+//#region ../@warlock.js/ai/src/middleware/utils/extract-user-text.d.ts
 /**
  * Pull the text a content-inspection middleware should care about
  * from the outbound message list.

package/esm/middleware/utils/extract-user-text.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"extract-user-text.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts"],"mappings":";;;;;AA4BA;;;;;;;;AAAgE;;;;;;;;;;;;;;;;iBAAhD,eAAA,CAAgB,QAAA,EAAU,aAAa,CAAC,OAAA"}
+{"version":3,"file":"extract-user-text.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts"],"mappings":";;;;;AA4BA;;;;;;;;AAAgE;;;;;;;;;;;;;;;;iBAAhD,eAAA,CAAgB,QAAA,EAAU,aAAa,CAAC,OAAA"}

package/esm/middleware/utils/extract-user-text.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts
+//#region ../@warlock.js/ai/src/middleware/utils/extract-user-text.ts
 /**
 * Pull the text a content-inspection middleware should care about
 * from the outbound message list.

package/esm/middleware/utils/extract-user-text.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"extract-user-text.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts"],"sourcesContent":["import type { Message } from \"../../contracts/conversation-message.type\";\n\n/**\n * Pull the text a content-inspection middleware should care about\n * from the outbound message list.\n *\n * **Role.** Built-ins that inspect \"what the user just said\" — the\n * guardrail on `trip.before`, the semantic cache on `trip.before`,\n * future consumers like PII redactors — all need the same string:\n * the most recent `user`-role message's text content. This helper\n * is the single authority on how that string is resolved.\n *\n * **Behavior.**\n * - Walks `messages` from the end backwards so the LAST user turn\n *   wins (correct when the agent has history + a fresh prompt).\n * - Returns a plain string directly when `content` is a string.\n * - Joins `text` parts with `\"\\n\"` when `content` is a multipart\n *   `ContentPart[]`. Non-text parts (images, audio) are skipped —\n *   callers concerned with multimodal content inspect `request`\n *   / attachments separately.\n * - Returns `\"\"` when there is no user message at all (e.g. a trip\n *   composed entirely of tool results).\n *\n * @example\n * const prompt = extractUserText(context.messages);\n * if (!prompt) return;\n * const verdict = await inputCheck(prompt);\n */\nexport function extractUserText(messages: ReadonlyArray<Message>): string {\n  for (let index = messages.length - 1; index >= 0; index--) {\n    const message = messages[index];\n\n    if (message.role !== \"user\") {\n      continue;\n    }\n\n    if (typeof message.content === \"string\") {\n      return message.content;\n    }\n\n    if (Array.isArray(message.content)) {\n      return message.content\n        .filter((part) => part.type === \"text\")\n        .map((part) => (part as { text: string }).text)\n        .join(\"\\n\");\n    }\n  }\n\n  return \"\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,gBAAgB,UAA0C;CACxE,KAAK,IAAI,QAAQ,SAAS,SAAS,GAAG,SAAS,GAAG,SAAS;EACzD,MAAM,UAAU,SAAS;EAEzB,IAAI,QAAQ,SAAS,QACnB;EAGF,IAAI,OAAO,QAAQ,YAAY,UAC7B,OAAO,QAAQ;EAGjB,IAAI,MAAM,QAAQ,QAAQ,OAAO,GAC/B,OAAO,QAAQ,QACZ,QAAQ,SAAS,KAAK,SAAS,MAAM,EACrC,KAAK,SAAU,KAA0B,IAAI,EAC7C,KAAK,IAAI;CAEhB;CAEA,OAAO;AACT"}
+{"version":3,"file":"extract-user-text.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/utils/extract-user-text.ts"],"sourcesContent":["import type { Message } from \"../../contracts/conversation-message.type\";\n\n/**\n * Pull the text a content-inspection middleware should care about\n * from the outbound message list.\n *\n * **Role.** Built-ins that inspect \"what the user just said\" — the\n * guardrail on `trip.before`, the semantic cache on `trip.before`,\n * future consumers like PII redactors — all need the same string:\n * the most recent `user`-role message's text content. This helper\n * is the single authority on how that string is resolved.\n *\n * **Behavior.**\n * - Walks `messages` from the end backwards so the LAST user turn\n *   wins (correct when the agent has history + a fresh prompt).\n * - Returns a plain string directly when `content` is a string.\n * - Joins `text` parts with `\"\\n\"` when `content` is a multipart\n *   `ContentPart[]`. Non-text parts (images, audio) are skipped —\n *   callers concerned with multimodal content inspect `request`\n *   / attachments separately.\n * - Returns `\"\"` when there is no user message at all (e.g. a trip\n *   composed entirely of tool results).\n *\n * @example\n * const prompt = extractUserText(context.messages);\n * if (!prompt) return;\n * const verdict = await inputCheck(prompt);\n */\nexport function extractUserText(messages: ReadonlyArray<Message>): string {\n  for (let index = messages.length - 1; index >= 0; index--) {\n    const message = messages[index];\n\n    if (message.role !== \"user\") {\n      continue;\n    }\n\n    if (typeof message.content === \"string\") {\n      return message.content;\n    }\n\n    if (Array.isArray(message.content)) {\n      return message.content\n        .filter((part) => part.type === \"text\")\n        .map((part) => (part as { text: string }).text)\n        .join(\"\\n\");\n    }\n  }\n\n  return \"\";\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AA4BA,SAAgB,gBAAgB,UAA0C;CACxE,KAAK,IAAI,QAAQ,SAAS,SAAS,GAAG,SAAS,GAAG,SAAS;EACzD,MAAM,UAAU,SAAS;EAEzB,IAAI,QAAQ,SAAS,QACnB;EAGF,IAAI,OAAO,QAAQ,YAAY,UAC7B,OAAO,QAAQ;EAGjB,IAAI,MAAM,QAAQ,QAAQ,OAAO,GAC/B,OAAO,QAAQ,QACZ,QAAQ,SAAS,KAAK,SAAS,MAAM,CAAC,CACtC,KAAK,SAAU,KAA0B,IAAI,CAAC,CAC9C,KAAK,IAAI;CAEhB;CAEA,OAAO;AACT"}

package/esm/middleware/utils/namespaced-state.d.mts

@@ -1,5 +1,5 @@
 import { MiddlewareState } from "../../contracts/middleware/middleware-state.type.mjs";
-//#region ../../@warlock.js/ai/src/middleware/utils/namespaced-state.d.ts
+//#region ../@warlock.js/ai/src/middleware/utils/namespaced-state.d.ts
 /**
  * Typed accessor over `ctx.state` for a single namespace key. Wraps
  * the raw `Map<string, unknown>` so middleware authors stop typing

package/esm/middleware/utils/namespaced-state.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"namespaced-state.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/utils/namespaced-state.ts"],"mappings":";;;;;AAyCA;;;;;;;;;;;;;;;;AAG4B;AAwB5B;;;;;;;;;;;;;AAIK;;;;;;iBA/BW,eAAA,GAAA,CACd,GAAA;EAAA,SAAgB,KAAA,EAAO,eAAA;AAAA,GACvB,SAAA,WACC,uBAAA,CAAwB,CAAA;;;;;;;;KAwBf,uBAAA;EACV,GAAA,IAAO,CAAA;EACP,GAAA,CAAI,KAAA,EAAO,CAAC;EACZ,MAAA;EACA,GAAA;AAAA"}
+{"version":3,"file":"namespaced-state.d.mts","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/utils/namespaced-state.ts"],"mappings":";;;;;AAyCA;;;;;;;;;;;;;;;;AAG4B;AAwB5B;;;;;;;;;;;;;AAIK;;;;;;iBA/BW,eAAA,IACd,GAAA;EAAA,SAAgB,KAAA,EAAO,eAAA;AAAA,GACvB,SAAA,WACC,uBAAA,CAAwB,CAAA;;;;;;;;KAwBf,uBAAA;EACV,GAAA,IAAO,CAAA;EACP,GAAA,CAAI,KAAA,EAAO,CAAC;EACZ,MAAA;EACA,GAAA;AAAA"}

package/esm/middleware/utils/namespaced-state.mjs

@@ -1,4 +1,4 @@
-//#region ../../@warlock.js/ai/src/middleware/utils/namespaced-state.ts
+//#region ../@warlock.js/ai/src/middleware/utils/namespaced-state.ts
 /**
 * Typed accessor over `ctx.state` for a single namespace key. Wraps
 * the raw `Map<string, unknown>` so middleware authors stop typing

package/esm/middleware/utils/namespaced-state.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"namespaced-state.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/middleware/utils/namespaced-state.ts"],"sourcesContent":["import type { MiddlewareState } from \"../../contracts/middleware\";\n\n/**\n * Typed accessor over `ctx.state` for a single namespace key. Wraps\n * the raw `Map<string, unknown>` so middleware authors stop typing\n * `as Counters | undefined` on every read.\n *\n * **Role.** Every built-in middleware reads and writes one or two\n * entries in `ctx.state` under its own name. Without a helper,\n * every call-site looks like:\n *\n * ```ts\n * const counters = context.state.get(\"budget.counters\") as Counters | undefined;\n * if (!counters) { ... }\n * counters.tokens += n;\n * ```\n *\n * — cast noise, no type narrowing on `set`, no protection against\n * key typos. `namespacedState<T>` eliminates all three.\n *\n * **Scope.** Deliberately narrow: one key, typed value, four methods\n * (`get` / `set` / `delete` / `has`). Does NOT try to model compound\n * or nested keys — if you need those, use the raw `ctx.state` Map\n * directly, or create a second namespaced accessor for the second key.\n *\n * **Namespace convention.** Use the middleware's `name` as the key\n * (or a `name.<field>` prefix when a middleware needs multiple\n * entries). The pipeline does not enforce this — it is a convention\n * the built-ins follow to avoid collisions between middlewares.\n *\n * @example\n * // Inside a budget middleware:\n * const counters = namespacedState<Counters>(ctx, \"budget\");\n *\n * if (!counters.has()) {\n *   counters.set({ tokens: 0, costUSD: 0 });\n * }\n *\n * const current = counters.get()!;\n * current.tokens += response.usage.total;\n */\nexport function namespacedState<T>(\n  ctx: { readonly state: MiddlewareState },\n  namespace: string,\n): NamespacedStateAccessor<T> {\n  return {\n    get(): T | undefined {\n      return ctx.state.get(namespace) as T | undefined;\n    },\n    set(value: T): void {\n      ctx.state.set(namespace, value);\n    },\n    delete(): void {\n      ctx.state.delete(namespace);\n    },\n    has(): boolean {\n      return ctx.state.has(namespace);\n    },\n  };\n}\n\n/**\n * Four-method accessor returned by `namespacedState`. Callers hold\n * it for the lifetime of a hook body — it is a thin typed view over\n * `ctx.state`, not a detached snapshot. Reads are live; writes hit\n * the underlying Map immediately and are visible to every other\n * hook that uses the same namespace.\n */\nexport type NamespacedStateAccessor<T> = {\n  get(): T | undefined;\n  set(value: T): void;\n  delete(): void;\n  has(): boolean;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,gBACd,KACA,WAC4B;CAC5B,OAAO;EACL,MAAqB;GACnB,OAAO,IAAI,MAAM,IAAI,SAAS;EAChC;EACA,IAAI,OAAgB;GAClB,IAAI,MAAM,IAAI,WAAW,KAAK;EAChC;EACA,SAAe;GACb,IAAI,MAAM,OAAO,SAAS;EAC5B;EACA,MAAe;GACb,OAAO,IAAI,MAAM,IAAI,SAAS;EAChC;CACF;AACF"}
+{"version":3,"file":"namespaced-state.mjs","names":[],"sources":["../../../../../../../../@warlock.js/ai/src/middleware/utils/namespaced-state.ts"],"sourcesContent":["import type { MiddlewareState } from \"../../contracts/middleware\";\n\n/**\n * Typed accessor over `ctx.state` for a single namespace key. Wraps\n * the raw `Map<string, unknown>` so middleware authors stop typing\n * `as Counters | undefined` on every read.\n *\n * **Role.** Every built-in middleware reads and writes one or two\n * entries in `ctx.state` under its own name. Without a helper,\n * every call-site looks like:\n *\n * ```ts\n * const counters = context.state.get(\"budget.counters\") as Counters | undefined;\n * if (!counters) { ... }\n * counters.tokens += n;\n * ```\n *\n * — cast noise, no type narrowing on `set`, no protection against\n * key typos. `namespacedState<T>` eliminates all three.\n *\n * **Scope.** Deliberately narrow: one key, typed value, four methods\n * (`get` / `set` / `delete` / `has`). Does NOT try to model compound\n * or nested keys — if you need those, use the raw `ctx.state` Map\n * directly, or create a second namespaced accessor for the second key.\n *\n * **Namespace convention.** Use the middleware's `name` as the key\n * (or a `name.<field>` prefix when a middleware needs multiple\n * entries). The pipeline does not enforce this — it is a convention\n * the built-ins follow to avoid collisions between middlewares.\n *\n * @example\n * // Inside a budget middleware:\n * const counters = namespacedState<Counters>(ctx, \"budget\");\n *\n * if (!counters.has()) {\n *   counters.set({ tokens: 0, costUSD: 0 });\n * }\n *\n * const current = counters.get()!;\n * current.tokens += response.usage.total;\n */\nexport function namespacedState<T>(\n  ctx: { readonly state: MiddlewareState },\n  namespace: string,\n): NamespacedStateAccessor<T> {\n  return {\n    get(): T | undefined {\n      return ctx.state.get(namespace) as T | undefined;\n    },\n    set(value: T): void {\n      ctx.state.set(namespace, value);\n    },\n    delete(): void {\n      ctx.state.delete(namespace);\n    },\n    has(): boolean {\n      return ctx.state.has(namespace);\n    },\n  };\n}\n\n/**\n * Four-method accessor returned by `namespacedState`. Callers hold\n * it for the lifetime of a hook body — it is a thin typed view over\n * `ctx.state`, not a detached snapshot. Reads are live; writes hit\n * the underlying Map immediately and are visible to every other\n * hook that uses the same namespace.\n */\nexport type NamespacedStateAccessor<T> = {\n  get(): T | undefined;\n  set(value: T): void;\n  delete(): void;\n  has(): boolean;\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyCA,SAAgB,gBACd,KACA,WAC4B;CAC5B,OAAO;EACL,MAAqB;GACnB,OAAO,IAAI,MAAM,IAAI,SAAS;EAChC;EACA,IAAI,OAAgB;GAClB,IAAI,MAAM,IAAI,WAAW,KAAK;EAChC;EACA,SAAe;GACb,IAAI,MAAM,OAAO,SAAS;EAC5B;EACA,MAAe;GACb,OAAO,IAAI,MAAM,IAAI,SAAS;EAChC;CACF;AACF"}

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

@@ -2,7 +2,7 @@ import { AgentContract } from "../contracts/agent/agent.contract.mjs";
 import { ToolContract } from "../tool/tool.mjs";
 import { MockModelResponse } from "./mock-config.type.mjs";
 
-//#region ../../@warlock.js/ai/src/mock/mock-agent.d.ts
+//#region ../@warlock.js/ai/src/mock/mock-agent.d.ts
 /**
  * Test helper that wires `MockSDK` → mock model → `agent()` in one call.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"mock-agent.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/mock/mock-agent.ts"],"mappings":";;;;;;;AA6BA;;;;;;;;;;;;;;;;;;;;iBAAgB,SAAA,mBAAA,CACd,OAAA;EACE,IAAA;EACA,SAAA,GAAY,iBAAA;EACZ,KAAA,GAAQ,YAAA;;;;;;EAMR,SAAA;AAAA,IAED,aAAA,CAAc,OAAA"}
+{"version":3,"file":"mock-agent.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-agent.ts"],"mappings":";;;;;;;AA6BA;;;;;;;;;;;;;;;;;;;;iBAAgB,SAAA,oBACd,OAAA;EACE,IAAA;EACA,SAAA,GAAY,iBAAA;EACZ,KAAA,GAAQ,YAAA;;;;;;EAMR,SAAA;AAAA,IAED,aAAA,CAAc,OAAA"}

package/esm/mock/mock-agent.mjs

@@ -1,7 +1,7 @@
 import { agent } from "../agent/agent.mjs";
 import { MockSDK } from "./mock-sdk.mjs";
 
-//#region ../../@warlock.js/ai/src/mock/mock-agent.ts
+//#region ../@warlock.js/ai/src/mock/mock-agent.ts
 /**
 * Test helper that wires `MockSDK` → mock model → `agent()` in one call.
 *

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

@@ -1 +1 @@
-{"version":3,"file":"mock-agent.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/mock/mock-agent.ts"],"sourcesContent":["import { agent } from \"../agent/agent\";\nimport type { AgentConfig } from \"../agent/agent-config.type\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { ToolContract } from \"../tool/tool\";\nimport type { MockModelResponse } from \"./mock-config.type\";\nimport { MockSDK } from \"./mock-sdk\";\n\n/**\n * Test helper that wires `MockSDK` → mock model → `agent()` in one call.\n *\n * Replaces the 4-line ritual specs typically write:\n * ```ts\n * const mock = MockSDK({ responses: [...] });\n * const myAgent = agent({ name: \"x\", model: mock.model({ name: \"m\" }) });\n * ```\n *\n * Defaults to a single empty `\"stop\"` response — enough to exercise an\n * agent that doesn't need a scripted reply (composition wiring,\n * anonymous-name tests, etc.). Pass `responses` to script outputs.\n *\n * `name` is optional — when omitted the resulting agent runs through\n * the normal anonymous-name fingerprint\n * (`anon_<provider>_<model>[_<tool1>+<tool2>...]`), which is the\n * default for `agent({ model })`.\n *\n * @example\n * const a = mockAgent({ name: \"writer\", responses: [{ content: \"hi\", finishReason: \"stop\" }] });\n * const result = await a.execute(\"anything\");\n */\nexport function mockAgent<TOutput = unknown>(\n  options: {\n    name?: string;\n    responses?: MockModelResponse[];\n    tools?: ToolContract<unknown, unknown>[];\n    /**\n     * Override the model name reported by the mock model. Defaults to\n     * `\"mock-model\"` (the MockSDK default). Useful when a test needs\n     * deterministic provider/model fingerprinting.\n     */\n    modelName?: string;\n  } = {},\n): AgentContract<TOutput> {\n  const responses = options.responses ?? [{ content: \"\", finishReason: \"stop\" as const }];\n  const sdk = MockSDK({ responses });\n  const model = sdk.model({ name: options.modelName ?? \"mock-model\" });\n\n  const config: AgentConfig<TOutput> = { model };\n\n  if (options.name !== undefined) {\n    config.name = options.name;\n  }\n\n  if (options.tools !== undefined) {\n    config.tools = options.tools;\n  }\n\n  return agent<TOutput>(config);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,UACd,UAUI,CAAC,GACmB;CAKxB,MAAM,SAA+B,EAAE,OAH3B,QAAQ,EAAE,WADJ,QAAQ,aAAa,CAAC;EAAE,SAAS;EAAI,cAAc;CAAgB,CAAC,EACtD,CAChB,EAAE,MAAM,EAAE,MAAM,QAAQ,aAAa,aAAa,CAEvB,EAAE;CAE7C,IAAI,QAAQ,SAAS,QACnB,OAAO,OAAO,QAAQ;CAGxB,IAAI,QAAQ,UAAU,QACpB,OAAO,QAAQ,QAAQ;CAGzB,OAAO,MAAe,MAAM;AAC9B"}
+{"version":3,"file":"mock-agent.mjs","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-agent.ts"],"sourcesContent":["import { agent } from \"../agent/agent\";\nimport type { AgentConfig } from \"../agent/agent-config.type\";\nimport type { AgentContract } from \"../contracts/agent/agent.contract\";\nimport type { ToolContract } from \"../tool/tool\";\nimport type { MockModelResponse } from \"./mock-config.type\";\nimport { MockSDK } from \"./mock-sdk\";\n\n/**\n * Test helper that wires `MockSDK` → mock model → `agent()` in one call.\n *\n * Replaces the 4-line ritual specs typically write:\n * ```ts\n * const mock = MockSDK({ responses: [...] });\n * const myAgent = agent({ name: \"x\", model: mock.model({ name: \"m\" }) });\n * ```\n *\n * Defaults to a single empty `\"stop\"` response — enough to exercise an\n * agent that doesn't need a scripted reply (composition wiring,\n * anonymous-name tests, etc.). Pass `responses` to script outputs.\n *\n * `name` is optional — when omitted the resulting agent runs through\n * the normal anonymous-name fingerprint\n * (`anon_<provider>_<model>[_<tool1>+<tool2>...]`), which is the\n * default for `agent({ model })`.\n *\n * @example\n * const a = mockAgent({ name: \"writer\", responses: [{ content: \"hi\", finishReason: \"stop\" }] });\n * const result = await a.execute(\"anything\");\n */\nexport function mockAgent<TOutput = unknown>(\n  options: {\n    name?: string;\n    responses?: MockModelResponse[];\n    tools?: ToolContract<unknown, unknown>[];\n    /**\n     * Override the model name reported by the mock model. Defaults to\n     * `\"mock-model\"` (the MockSDK default). Useful when a test needs\n     * deterministic provider/model fingerprinting.\n     */\n    modelName?: string;\n  } = {},\n): AgentContract<TOutput> {\n  const responses = options.responses ?? [{ content: \"\", finishReason: \"stop\" as const }];\n  const sdk = MockSDK({ responses });\n  const model = sdk.model({ name: options.modelName ?? \"mock-model\" });\n\n  const config: AgentConfig<TOutput> = { model };\n\n  if (options.name !== undefined) {\n    config.name = options.name;\n  }\n\n  if (options.tools !== undefined) {\n    config.tools = options.tools;\n  }\n\n  return agent<TOutput>(config);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AA6BA,SAAgB,UACd,UAUI,CAAC,GACmB;CAKxB,MAAM,SAA+B,EAAE,OAH3B,QAAQ,EAAE,WADJ,QAAQ,aAAa,CAAC;EAAE,SAAS;EAAI,cAAc;CAAgB,CAAC,EACtD,CAChB,CAAC,CAAC,MAAM,EAAE,MAAM,QAAQ,aAAa,aAAa,CAEvB,EAAE;CAE7C,IAAI,QAAQ,SAAS,QACnB,OAAO,OAAO,QAAQ;CAGxB,IAAI,QAAQ,UAAU,QACpB,OAAO,QAAQ,QAAQ;CAGzB,OAAO,MAAe,MAAM;AAC9B"}

package/esm/mock/mock-config.type.d.mts

@@ -2,7 +2,7 @@ import { ModelToolCallRequest } from "../contracts/model-tool-call-request.type.
 import { Usage } from "../contracts/result/usage.type.mjs";
 import { FinishReason } from "../contracts/finish-reason.type.mjs";
 import { ModelCapabilities } from "../contracts/model.contract.mjs";
-//#region ../../@warlock.js/ai/src/mock/mock-config.type.d.ts
+//#region ../@warlock.js/ai/src/mock/mock-config.type.d.ts
 /**
  * Configuration for a single mock model response.
  * Responses are consumed in order — last one repeats if list is exhausted.

package/esm/mock/mock-config.type.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"mock-config.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/mock/mock-config.type.ts"],"mappings":";;;;;;;;AASA;KAAY,iBAAA;EACV,OAAA;EACA,YAAA,GAAe,YAAA;EACf,KAAA,GAAQ,KAAA;EACR,SAAA,GAAY,oBAAA,IAIJ;EAFR,KAAA,WAEa;EAAb,KAAA,GAAQ,KAAA;AAAA;AAAA,KAGE,aAAA;EARV,wEAUA,SAAA,GAAY,iBAAA,IATZ;EAWA,gBAAA;EATA;;;;AAEa;AAGf;EAWE,YAAA,GAAe,iBAAiB;AAAA"}
+{"version":3,"file":"mock-config.type.d.mts","names":[],"sources":["../../../../../../../@warlock.js/ai/src/mock/mock-config.type.ts"],"mappings":";;;;;;;;AASA;KAAY,iBAAA;EACV,OAAA;EACA,YAAA,GAAe,YAAA;EACf,KAAA,GAAQ,KAAA;EACR,SAAA,GAAY,oBAAA,IAIJ;EAFR,KAAA,WAEa;EAAb,KAAA,GAAQ,KAAA;AAAA;AAAA,KAGE,aAAA;EARV,wEAUA,SAAA,GAAY,iBAAA,IATZ;EAWA,gBAAA;EATA;;;;AAEa;AAGf;EAWE,YAAA,GAAe,iBAAiB;AAAA"}

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

@@ -2,7 +2,7 @@ import { Message } from "../contracts/conversation-message.type.mjs";
 import { ModelCallOptions, ModelCapabilities, ModelContract, ModelResponse, ModelStreamChunk } from "../contracts/model.contract.mjs";
 import { MockModelResponse } from "./mock-config.type.mjs";
 
-//#region ../../@warlock.js/ai/src/mock/mock-model.d.ts
+//#region ../@warlock.js/ai/src/mock/mock-model.d.ts
 type RecordedCall = {
   messages: Message[];
   options?: ModelCallOptions;