@warlock.js/core 4.4.0 → 4.6.0

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

@@ -0,0 +1,80 @@
+//#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`
+* hooks pass through unchanged.
+*
+* **Role.** Tool-specific concerns — "rate-limit `search_web`",
+* "cache results for `fetch_faq`" — are common. Rather than adding
+* a `middleware` field to `ai.tool()` (see decisions §27), the
+* framework keeps one contract (`AgentMiddleware`) and offers this
+* helper for the locality problem. The middleware body stays agnostic
+* of the tool name; `forTool` handles the filtering.
+*
+* **What gets filtered.** Only `tool.before` / `tool.after` /
+* `tool.onError`. Each hook is wrapped so that `ctx.tool.name`
+* must be in the allowed set or the wrapped hook is a no-op.
+* `execute` and `trip` hooks are NOT touched — they run normally.
+*
+* **Why not filter execute/trip too?** Because a middleware that
+* reaches across levels (a tool-specific budget that initializes a
+* counter in `execute.before` and checks it in `tool.before`) still
+* needs `execute.before` to fire unconditionally. Scoping all hooks
+* would break cross-level middleware; scoping only `tool` hooks
+* matches the mental model of "this middleware cares about these
+* tools."
+*
+* **Single-name vs multi-name.** A string matches one tool; a string
+* array matches any of the listed tools. No wildcards, no regex —
+* keep it boring.
+*
+* @example
+* // Single tool
+* const scoped = ai.middleware.forTool(
+*   "search_web",
+*   toolRateLimit({ maxCalls: 3 }),
+* );
+*
+* @example
+* // Multiple tools sharing a rule
+* const scoped = ai.middleware.forTool(
+*   ["paid_api", "expensive_db"],
+*   toolRateLimit({ maxCalls: 5 }),
+* );
+*
+* ai.agent({
+*   model,
+*   tools: [webTool, paidApiTool, expensiveDbTool],
+*   middleware: [scoped],
+* });
+*/
+function forTool(toolNames, middleware) {
+	const allowed = new Set(typeof toolNames === "string" ? [toolNames] : toolNames);
+	const scope = allowed.size === 1 ? Array.from(allowed)[0] : Array.from(allowed).join("+");
+	if (!middleware.tool) return middleware;
+	const innerBefore = middleware.tool.before;
+	const innerAfter = middleware.tool.after;
+	const innerOnError = middleware.tool.onError;
+	return {
+		...middleware,
+		name: `${middleware.name}[for:${scope}]`,
+		tool: {
+			before: innerBefore ? async (ctx) => {
+				if (!allowed.has(ctx.tool.name)) return;
+				return innerBefore(ctx);
+			} : void 0,
+			after: innerAfter ? async (ctx, result) => {
+				if (!allowed.has(ctx.tool.name)) return;
+				return innerAfter(ctx, result);
+			} : void 0,
+			onError: innerOnError ? async (ctx, error) => {
+				if (!allowed.has(ctx.tool.name)) return;
+				return innerOnError(ctx, error);
+			} : void 0
+		}
+	};
+}
+
+//#endregion
+export { forTool };
+//# sourceMappingURL=for-tool.mjs.map

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

@@ -0,0 +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,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/ai/src/middleware/index.mjs

@@ -0,0 +1,10 @@
+import { extractUserText } from "./utils/extract-user-text.mjs";
+import { namespacedState } from "./utils/namespaced-state.mjs";
+import { budget, readBudgetFallbackSignal } from "./builtins/budget.mjs";
+import { guardrail } from "./builtins/guardrail.mjs";
+import { semanticCache } from "./builtins/semantic-cache.mjs";
+import { composeMiddleware } from "./helpers/compose.mjs";
+import { forTool } from "./helpers/for-tool.mjs";
+import { runPipeline } from "./pipeline.mjs";
+
+export {  };

package/esm/ai/src/middleware/pipeline.mjs

@@ -0,0 +1,100 @@
+//#region ../@warlock.js/ai/src/middleware/pipeline.ts
+const LOG_MODULE = "ai.middleware";
+/**
+* Run an inner async operation through a stack of agent middlewares
+* at a single level, applying the onion-model before/after/onError
+* semantics documented on `AgentMiddleware`.
+*
+* **Semantics.**
+* - `before` hooks run in registration order (top-down).
+*   Returning a defined value from a `before` hook short-circuits the
+*   pipeline with that value as the result, skipping `inner()` and
+*   all deeper `before` / `after` hooks — but outer middleware
+*   `after` hooks (registered earlier) still run on the synthetic
+*   value.
+* - `after` hooks run in reverse registration order (bottom-up).
+*   Returning a defined value replaces the result before it
+*   propagates further out. Returning `void` / `undefined` keeps the
+*   existing result.
+* - `onError` hooks also run in reverse (bottom-up) — any error
+*   thrown by `inner()`, by a `before` hook, or by an `after` hook
+*   unwinds through each frame's `onError` in turn. Returning a
+*   defined value from `onError` recovers: the error is cleared and
+*   the returned value becomes the new result (which then flows
+*   through outer `after` hooks). Returning `void` propagates the
+*   error to the next outer frame.
+*
+* **Implementation.** Built by folding the middleware array from the
+* end inward: each middleware produces a closure that wraps the
+* previous closure (the deeper pipeline). The outermost wrap is
+* middleware index 0 — so registration order matches onion order
+* without any reverse iteration at call time.
+*
+* **No magic.** The pipeline does not swallow, retry, or translate
+* errors. Hooks that throw propagate unchanged (subject to `onError`
+* recovery). Pipeline-level logging is debug-only and respects each
+* middleware's `log: false` kill-switch.
+*
+* @example
+* const response = await runPipeline(
+*   middlewares,
+*   "trip",
+*   tripContext,
+*   () => model.complete(messages, callOptions),
+*   logger,
+* );
+*/
+async function runPipeline(middlewares, level, context, inner, logger) {
+	if (middlewares.length === 0) return inner();
+	let next = inner;
+	for (let index = middlewares.length - 1; index >= 0; index--) {
+		const middleware = middlewares[index];
+		const hooks = middleware[level];
+		if (!hooks) continue;
+		const previous = next;
+		next = async () => {
+			const logEnabled = middleware.log !== false && logger !== void 0;
+			if (hooks.before) {
+				if (logEnabled) logger.debug(LOG_MODULE, `${level}.before`, middleware.name, {
+					middleware: middleware.name,
+					level
+				});
+				const shortCircuit = await hooks.before(context);
+				if (shortCircuit !== void 0) {
+					if (logEnabled) logger.debug(LOG_MODULE, `${level}.short-circuit`, middleware.name, {
+						middleware: middleware.name,
+						level
+					});
+					return shortCircuit;
+				}
+			}
+			let result;
+			try {
+				result = await previous();
+			} catch (thrown) {
+				if (!hooks.onError) throw thrown;
+				const recovered = await hooks.onError(context, thrown);
+				if (recovered === void 0) throw thrown;
+				if (logEnabled) logger.debug(LOG_MODULE, `${level}.recovered`, middleware.name, {
+					middleware: middleware.name,
+					level
+				});
+				result = recovered;
+			}
+			if (hooks.after) {
+				const replacement = await hooks.after(context, result);
+				if (replacement !== void 0) result = replacement;
+				if (logEnabled) logger.debug(LOG_MODULE, `${level}.after`, middleware.name, {
+					middleware: middleware.name,
+					level
+				});
+			}
+			return result;
+		};
+	}
+	return next();
+}
+
+//#endregion
+export { runPipeline };
+//# sourceMappingURL=pipeline.mjs.map

package/esm/ai/src/middleware/pipeline.mjs.map

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

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

@@ -0,0 +1,47 @@
+//#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.
+*
+* **Role.** Built-ins that inspect "what the user just said" — the
+* guardrail on `trip.before`, the semantic cache on `trip.before`,
+* future consumers like PII redactors — all need the same string:
+* the most recent `user`-role message's text content. This helper
+* is the single authority on how that string is resolved.
+*
+* **Behavior.**
+* - Walks `messages` from the end backwards so the LAST user turn
+*   wins (correct when the agent has history + a fresh prompt).
+* - Returns a plain string directly when `content` is a string.
+* - Joins `text` parts with `"\n"` when `content` is a multipart
+*   `ContentPart[]`. Non-text parts (images, audio, pdf) are skipped —
+*   callers concerned with multimodal content inspect `request`
+*   / attachments separately.
+* - Returns `""` when there is no user message at all (e.g. a trip
+*   composed entirely of tool results).
+*
+* **Coverage limit (D3).** Because only `text` parts are extracted, any
+* guardrail / PII detector built on this helper inspects **text only** —
+* image / PDF / audio attachment content is NOT scanned. A guardrail is
+* therefore not a multimodal safety control: for non-text inputs add an
+* attachment-level policy (e.g. an OCR / moderation pass before the call)
+* rather than relying on input detectors.
+*
+* @example
+* const prompt = extractUserText(context.messages);
+* if (!prompt) return;
+* const verdict = await inputCheck(prompt);
+*/
+function extractUserText(messages) {
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const message = messages[index];
+		if (message.role !== "user") continue;
+		if (typeof message.content === "string") return message.content;
+		if (Array.isArray(message.content)) return message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n");
+	}
+	return "";
+}
+
+//#endregion
+export { extractUserText };
+//# sourceMappingURL=extract-user-text.mjs.map

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

@@ -0,0 +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, pdf) 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 * **Coverage limit (D3).** Because only `text` parts are extracted, any\n * guardrail / PII detector built on this helper inspects **text only** —\n * image / PDF / audio attachment content is NOT scanned. A guardrail is\n * therefore not a multimodal safety control: for non-text inputs add an\n * attachment-level policy (e.g. an OCR / moderation pass before the call)\n * rather than relying on input detectors.\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":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAmCA,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/ai/src/middleware/utils/namespaced-state.mjs

@@ -0,0 +1,60 @@
+//#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
+* `as Counters | undefined` on every read.
+*
+* **Role.** Every built-in middleware reads and writes one or two
+* entries in `ctx.state` under its own name. Without a helper,
+* every call-site looks like:
+*
+* ```ts
+* const counters = context.state.get("budget.counters") as Counters | undefined;
+* if (!counters) { ... }
+* counters.tokens += n;
+* ```
+*
+* — cast noise, no type narrowing on `set`, no protection against
+* key typos. `namespacedState<T>` eliminates all three.
+*
+* **Scope.** Deliberately narrow: one key, typed value, four methods
+* (`get` / `set` / `delete` / `has`). Does NOT try to model compound
+* or nested keys — if you need those, use the raw `ctx.state` Map
+* directly, or create a second namespaced accessor for the second key.
+*
+* **Namespace convention.** Use the middleware's `name` as the key
+* (or a `name.<field>` prefix when a middleware needs multiple
+* entries). The pipeline does not enforce this — it is a convention
+* the built-ins follow to avoid collisions between middlewares.
+*
+* @example
+* // Inside a budget middleware:
+* const counters = namespacedState<Counters>(ctx, "budget");
+*
+* if (!counters.has()) {
+*   counters.set({ tokens: 0, costUSD: 0 });
+* }
+*
+* const current = counters.get()!;
+* current.tokens += response.usage.total;
+*/
+function namespacedState(ctx, namespace) {
+	return {
+		get() {
+			return ctx.state.get(namespace);
+		},
+		set(value) {
+			ctx.state.set(namespace, value);
+		},
+		delete() {
+			ctx.state.delete(namespace);
+		},
+		has() {
+			return ctx.state.has(namespace);
+		}
+	};
+}
+
+//#endregion
+export { namespacedState };
+//# sourceMappingURL=namespaced-state.mjs.map

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

@@ -0,0 +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"}

package/esm/ai/src/mock/index.mjs

@@ -0,0 +1,4 @@
+import "./mock-agent.mjs";
+import { mockRouter } from "./mock-router.mjs";
+
+export {  };

package/esm/ai/src/mock/mock-agent.mjs

@@ -0,0 +1,3 @@
+import "../agent/agent.mjs";
+
+export {  };

package/esm/ai/src/mock/mock-router.mjs

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

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

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

package/esm/ai/src/model/fallback-model.mjs

@@ -0,0 +1,218 @@
+import { AIError } from "../errors/ai-error.mjs";
+import { accumulateCost } from "../utils/compute-cost.mjs";
+
+//#region ../@warlock.js/ai/src/model/fallback-model.ts
+/**
+* Error codes treated as transient — and therefore worth falling over
+* to the next model — when the caller does not supply an explicit
+* `retryOn`. Covers provider rate-limits, timeouts, and the generic
+* `PROVIDER_ERROR` catch-all that adapters throw for 5xx / unknown
+* network failures. Deliberately omits auth, invalid-request,
+* context-length, and content-filter: those fail identically on every
+* downstream model, so retrying only burns budget.
+*/
+const DEFAULT_RETRYABLE_CODES = [
+	"PROVIDER_RATE_LIMIT",
+	"PROVIDER_TIMEOUT",
+	"PROVIDER_ERROR"
+];
+/**
+* A `ModelContract` that wraps an ordered list of models and tries each
+* in turn, advancing to the next only when the current one fails with a
+* matching (transient) provider error.
+*
+* **Role.** A drop-in `ModelContract` for resilience: hand it to any
+* agent / workflow / supervisor in place of a single model and provider
+* outages, rate-limits, and timeouts transparently fail over to a
+* backup. Non-transient failures (bad key, oversized prompt, blocked
+* content) re-throw immediately rather than wastefully retrying.
+*
+* **What it owns / doesn't own.** Owns the ordered model list, the
+* retry decision, and per-call usage aggregation across attempted
+* models. Does NOT own retry/backoff timing (it advances instantly to
+* the next model — pair it with a backoff middleware if you want delay)
+* nor any provider I/O of its own; every call is delegated to a wrapped
+* model.
+*
+* **Streaming fall-over caveat.** `stream()` can only fail over while no
+* chunk has been emitted yet. Once the first `delta` / `tool-call`
+* reaches the consumer, the partial output cannot be un-sent, so a
+* mid-stream failure propagates instead of restarting on the next
+* model.
+*
+* @example
+* const model = fallbackModel([
+*   ai.openai.model({ name: "gpt-4o" }),
+*   ai.anthropic.model({ name: "claude-3-5-sonnet" }),
+* ]);
+* const agent = ai.agent({ model });
+*
+* @example
+* // custom retry predicate
+* const model = fallbackModel([primary, backup], {
+*   retryOn: (error) => error instanceof ProviderError,
+* });
+*/
+function fallbackModel(models, options) {
+	if (models.length === 0) throw new AIError("PROVIDER_INVALID_REQUEST", "fallbackModel() requires at least one model in the chain.", void 0, "validation");
+	return new FallbackModel(models, resolveShouldRetry(options?.retryOn));
+}
+/**
+* Build the chain-advancement predicate from the caller's `retryOn`.
+* An array becomes a code membership test against an `AIError.code`; a
+* function is used verbatim; absence falls back to the transient
+* default set.
+*/
+function resolveShouldRetry(retryOn) {
+	if (typeof retryOn === "function") return retryOn;
+	const codes = retryOn ?? DEFAULT_RETRYABLE_CODES;
+	return (error) => {
+		return error instanceof AIError && codes.includes(error.code);
+	};
+}
+/**
+* Add a successful call's usage into a running aggregate, mirroring the
+* agent's trip accumulation: scalar token counts sum, optional channels
+* sum only when present, and cost merges via `accumulateCost` so an
+* unpriced model never erases a priced sibling's cost.
+*/
+function aggregateUsage(total, next) {
+	total.input += next.input;
+	total.output += next.output;
+	total.total += next.total;
+	if (next.cachedTokens !== void 0) total.cachedTokens = (total.cachedTokens ?? 0) + next.cachedTokens;
+	if (next.reasoningTokens !== void 0) total.reasoningTokens = (total.reasoningTokens ?? 0) + next.reasoningTokens;
+	if (next.cacheWriteTokens !== void 0) total.cacheWriteTokens = (total.cacheWriteTokens ?? 0) + next.cacheWriteTokens;
+	total.cost = accumulateCost(total.cost, next.cost);
+}
+/**
+* Internal `ModelContract` implementation backing {@link fallbackModel}.
+*
+* Long-lived (its identity, capabilities, and pricing front the primary
+* model for the wrapper's whole lifetime) so it is a class rather than a
+* closure. Per-call mutable state (the usage aggregate, the attempt log)
+* lives in {@link FallbackRun}, instantiated fresh on every
+* `complete()` / `stream()` so concurrent calls never share bookkeeping.
+*/
+var FallbackModel = class {
+	constructor(models, shouldRetry) {
+		this.models = models;
+		this.shouldRetry = shouldRetry;
+		this.latestAttempts = [];
+		const primary = models[0];
+		this.name = primary.name;
+		this.provider = primary.provider;
+		this.capabilities = primary.capabilities;
+		this.pricing = primary.pricing;
+	}
+	/**
+	* Models that failed with a chain-advancing error during the most
+	* recent `complete()` / `stream()` call, in attempt order. Empty when
+	* the primary model succeeded outright. Overwritten on each call.
+	*/
+	get lastAttempts() {
+		return this.latestAttempts;
+	}
+	async complete(messages, options) {
+		const run = new FallbackRun(this.models, this.shouldRetry);
+		const response = await run.complete(messages, options);
+		this.latestAttempts = run.attempts;
+		return response;
+	}
+	stream(messages, options) {
+		return new FallbackRun(this.models, this.shouldRetry).stream(messages, options, (attempts) => {
+			this.latestAttempts = attempts;
+		});
+	}
+};
+/**
+* Per-call execution of the fallback chain. Holds the usage aggregate
+* and the attempt log for a single `complete()` / `stream()` invocation
+* so the long-lived {@link FallbackModel} stays free of shared mutable
+* state across concurrent calls.
+*/
+var FallbackRun = class {
+	constructor(models, shouldRetry) {
+		this.models = models;
+		this.shouldRetry = shouldRetry;
+		this.attempts = [];
+		this.usage = {
+			input: 0,
+			output: 0,
+			total: 0
+		};
+	}
+	/**
+	* Try each model's `complete()` in order. On a chain-advancing error,
+	* record the attempt and move to the next; on the last model (or a
+	* non-retryable error) re-throw the underlying error verbatim so the
+	* caller still sees a typed `AIError` with its original code.
+	*/
+	async complete(messages, options) {
+		for (let index = 0; index < this.models.length; index++) {
+			const model = this.models[index];
+			const isLast = index === this.models.length - 1;
+			try {
+				const response = await model.complete(messages, options);
+				aggregateUsage(this.usage, response.usage);
+				return {
+					...response,
+					usage: this.usage
+				};
+			} catch (error) {
+				if (isLast || !this.shouldRetry(error)) throw error;
+				this.recordAttempt(model, error);
+			}
+		}
+		throw new AIError("PROVIDER_ERROR", "fallbackModel() exhausted its chain without producing a response.", void 0, "provider");
+	}
+	/**
+	* Try each model's `stream()` in order. Fall-over is only attempted
+	* while no chunk has been emitted yet for the current model — once the
+	* consumer has seen a `delta` / `tool-call`, a mid-stream failure
+	* propagates instead of restarting (partial output cannot be un-sent).
+	* The aggregated usage replaces the `done` chunk's usage so the caller
+	* sees the chain total.
+	*/
+	async *stream(messages, options, onSettle) {
+		try {
+			for (let index = 0; index < this.models.length; index++) {
+				const model = this.models[index];
+				const isLast = index === this.models.length - 1;
+				let emitted = false;
+				try {
+					for await (const chunk of model.stream(messages, options)) {
+						if (chunk.type === "done") {
+							aggregateUsage(this.usage, chunk.usage);
+							yield {
+								...chunk,
+								usage: this.usage
+							};
+							return;
+						}
+						emitted = true;
+						yield chunk;
+					}
+					return;
+				} catch (error) {
+					if (emitted || isLast || !this.shouldRetry(error)) throw error;
+					this.recordAttempt(model, error);
+				}
+			}
+			throw new AIError("PROVIDER_ERROR", "fallbackModel() exhausted its chain without producing a response.", void 0, "provider");
+		} finally {
+			onSettle(this.attempts);
+		}
+	}
+	recordAttempt(model, error) {
+		this.attempts.push({
+			modelName: model.name,
+			provider: model.provider,
+			error
+		});
+	}
+};
+
+//#endregion
+export { fallbackModel };
+//# sourceMappingURL=fallback-model.mjs.map