@warlock.js/ai 4.1.1

package/esm/errors/agent-max-trips-error.d.mts

@@ -0,0 +1,45 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorOptions } from "./ai-error.mjs";
+import { AgentExecutionError } from "./agent-execution-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/agent-max-trips-error.d.ts
+/**
+ * Payload for {@link AgentMaxTripsError}. `maxTrips` is the cap the
+ * agent hit — useful for log/metric attribution and for retry-with-
+ * higher-cap recovery strategies.
+ */
+type AgentMaxTripsErrorOptions = AIErrorOptions & {
+  maxTrips: number;
+};
+/**
+ * Runaway-loop hard guard: the agent's trip loop ran `maxTrips` round
+ * trips to the model without the model issuing a natural stop. The
+ * loop terminates with this typed error on `result.error` and the
+ * full trip history preserved in `result.report.trips` so consumers
+ * can see where the loop got stuck.
+ *
+ * **Not retryable by default.** A run that hit the cap usually
+ * indicates either a tool the agent can't satisfy (causing infinite
+ * re-asks) or a model that won't commit to an answer. Bumping
+ * `maxTrips` and retrying without root-causing the underlying issue
+ * just burns more tokens.
+ *
+ * **Why split from `AgentExecutionError`.** The catch-all base wears
+ * too many hats — cancellation vs. max-trips vs. generic crashes had
+ * to be disambiguated from `context` flags or message regex. Split
+ * subclasses let category dispatch (`"max-trips"`) and consumer
+ * branching (`instanceof`) work without inference.
+ *
+ * @example
+ * if (result.error instanceof AgentMaxTripsError) {
+ *   logger.warn("agent hit trip cap", { max: result.error.maxTrips });
+ * }
+ */
+declare class AgentMaxTripsError extends AgentExecutionError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly maxTrips: number;
+  constructor(message: string, options: AgentMaxTripsErrorOptions);
+}
+//#endregion
+export { AgentMaxTripsError, AgentMaxTripsErrorOptions };
+//# sourceMappingURL=agent-max-trips-error.d.mts.map

package/esm/errors/agent-max-trips-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-max-trips-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/agent-max-trips-error.ts"],"mappings":";;;;;;;AASA;;;KAAY,yBAAA,GAA4B,cAAc;EACpD,QAAQ;AAAA;;;;;;;;;;;;;;;;;AAgC8D;;;;;;;;cAL3D,kBAAA,SAA2B,mBAAA;EAAA,gBACf,eAAA,EAAiB,aAAA;EAAA,SAExB,QAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,yBAAA;AAAA"}

package/esm/errors/agent-max-trips-error.mjs

@@ -0,0 +1,41 @@
+import { AgentExecutionError } from "./agent-execution-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/agent-max-trips-error.ts
+/**
+* Runaway-loop hard guard: the agent's trip loop ran `maxTrips` round
+* trips to the model without the model issuing a natural stop. The
+* loop terminates with this typed error on `result.error` and the
+* full trip history preserved in `result.report.trips` so consumers
+* can see where the loop got stuck.
+*
+* **Not retryable by default.** A run that hit the cap usually
+* indicates either a tool the agent can't satisfy (causing infinite
+* re-asks) or a model that won't commit to an answer. Bumping
+* `maxTrips` and retrying without root-causing the underlying issue
+* just burns more tokens.
+*
+* **Why split from `AgentExecutionError`.** The catch-all base wears
+* too many hats — cancellation vs. max-trips vs. generic crashes had
+* to be disambiguated from `context` flags or message regex. Split
+* subclasses let category dispatch (`"max-trips"`) and consumer
+* branching (`instanceof`) work without inference.
+*
+* @example
+* if (result.error instanceof AgentMaxTripsError) {
+*   logger.warn("agent hit trip cap", { max: result.error.maxTrips });
+* }
+*/
+var AgentMaxTripsError = class extends AgentExecutionError {
+	static {
+		this.defaultCategory = "max-trips";
+	}
+	constructor(message, options) {
+		super(message, options, "AGENT_MAX_TRIPS");
+		this.name = "AgentMaxTripsError";
+		this.maxTrips = options.maxTrips;
+	}
+};
+
+//#endregion
+export { AgentMaxTripsError };
+//# sourceMappingURL=agent-max-trips-error.mjs.map

package/esm/errors/agent-max-trips-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-max-trips-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/agent-max-trips-error.ts"],"sourcesContent":["import { AgentExecutionError } from \"./agent-execution-error\";\nimport type { AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\n\n/**\n * Payload for {@link AgentMaxTripsError}. `maxTrips` is the cap the\n * agent hit — useful for log/metric attribution and for retry-with-\n * higher-cap recovery strategies.\n */\nexport type AgentMaxTripsErrorOptions = AIErrorOptions & {\n  maxTrips: number;\n};\n\n/**\n * Runaway-loop hard guard: the agent's trip loop ran `maxTrips` round\n * trips to the model without the model issuing a natural stop. The\n * loop terminates with this typed error on `result.error` and the\n * full trip history preserved in `result.report.trips` so consumers\n * can see where the loop got stuck.\n *\n * **Not retryable by default.** A run that hit the cap usually\n * indicates either a tool the agent can't satisfy (causing infinite\n * re-asks) or a model that won't commit to an answer. Bumping\n * `maxTrips` and retrying without root-causing the underlying issue\n * just burns more tokens.\n *\n * **Why split from `AgentExecutionError`.** The catch-all base wears\n * too many hats — cancellation vs. max-trips vs. generic crashes had\n * to be disambiguated from `context` flags or message regex. Split\n * subclasses let category dispatch (`\"max-trips\"`) and consumer\n * branching (`instanceof`) work without inference.\n *\n * @example\n * if (result.error instanceof AgentMaxTripsError) {\n *   logger.warn(\"agent hit trip cap\", { max: result.error.maxTrips });\n * }\n */\nexport class AgentMaxTripsError extends AgentExecutionError {\n  public static readonly defaultCategory: ErrorCategory = \"max-trips\";\n\n  public readonly maxTrips: number;\n\n  public constructor(message: string, options: AgentMaxTripsErrorOptions) {\n    super(message, options, \"AGENT_MAX_TRIPS\");\n    this.name = \"AgentMaxTripsError\";\n    this.maxTrips = options.maxTrips;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAqCA,IAAa,qBAAb,cAAwC,oBAAoB;;yBACF;;CAIxD,AAAO,YAAY,SAAiB,SAAoC;EACtE,MAAM,SAAS,SAAS,iBAAiB;EACzC,KAAK,OAAO;EACZ,KAAK,WAAW,QAAQ;CAC1B;AACF"}

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

@@ -0,0 +1,94 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorCode } from "./error-code.type.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/ai-error.d.ts
+/**
+ * Optional constructor payload shared by every `AIError` subclass.
+ *
+ * `cause` carries the original thrown value (SDK error, runtime crash,
+ * validation failure) so downstream logging and debuggers can still
+ * reach it. `context` is a free-form diagnostic bag for provider-raw
+ * metadata (status codes, request ids, response headers) that shouldn't
+ * be promoted to typed fields but is useful in logs and telemetry.
+ *
+ * **No `category` here.** Category is fixed per subclass via the
+ * class-level `static defaultCategory`. Subclasses ARE their
+ * category — `RateLimitError` is always `"rate-limit"`, never
+ * something else at runtime. Direct `new AIError(...)` callers (the
+ * one legitimate override case, since the base catch-all has no
+ * specific class) receive a separate 4th constructor argument
+ * instead, so the override is structurally unreachable from subclass
+ * call sites.
+ */
+type AIErrorOptions = {
+  cause?: unknown;
+  context?: Record<string, unknown>;
+};
+/**
+ * Base class for every error thrown (or surfaced via `result.error`) by
+ * `@warlock.js/ai` and its provider adapter packages.
+ *
+ * **Role.** The single typed error contract across the AI framework.
+ * Every thrown error anywhere in `@warlock.js/ai*` is either an
+ * `AIError` itself or one of its subclasses — plain `Error` must never
+ * leak out. Consumers branch either on the narrow `error.code` (stable
+ * string), on `error.category` (coarse dashboard grouping), or on
+ * `instanceof` a specific subclass.
+ *
+ * **Independence.** Deliberately extends the platform `Error` directly
+ * — never `HttpError` from `@warlock.js/core`. The AI framework is a
+ * standalone product; coupling its error base to a web framework would
+ * force every consumer to pull in the HTTP layer even when they only
+ * use AI in a CLI, worker, or test.
+ *
+ * **Fields.**
+ * - `code` — stable machine-readable identifier (see `AIErrorCode`).
+ * - `category` — coarse `ErrorCategory` for dashboards / retry policy.
+ *   Resolved at construction from the subclass's `static defaultCategory`
+ *   (or, for direct `new AIError(...)` calls, from the explicit 4th
+ *   constructor argument).
+ * - `cause` — optional original thrown value (SDK error, nested error,
+ *   raw value). Preserves root cause through re-wrapping.
+ * - `context` — optional free-form diagnostic bag (status, requestId,
+ *   headers). Consumers treat it as opaque; logs and telemetry read it.
+ *
+ * **Category override — direct AIError usage only.** Subclasses ARE
+ * their category by type; there's no legitimate runtime override at
+ * the subclass level. The 4th constructor argument exists ONLY for
+ * direct `new AIError(...)` callers, who would otherwise be stuck with
+ * the `"unknown"` default. Subclasses construct via `super(code,
+ * message, options)` and physically cannot reach the override slot
+ * through their own typed signatures.
+ *
+ * @example
+ * try {
+ *   await agent.execute("hello");
+ * } catch (error) {
+ *   if (error instanceof AIError) {
+ *     console.error(`[${error.code}] (${error.category}) ${error.message}`);
+ *   }
+ * }
+ *
+ * @example
+ * // Direct AIError construction with explicit category — escape hatch
+ * // for call sites that lack a specific subclass.
+ * throw new AIError("UNEXPECTED", "transient glitch", undefined, "provider");
+ */
+declare class AIError extends Error {
+  /**
+   * Class-level category for every instance of this error type.
+   * Subclasses redeclare with their own concrete `ErrorCategory` so
+   * `error.category` is correct without per-call wiring. The base
+   * class keeps `"unknown"` so untyped direct throws of `AIError`
+   * itself remain honest about their lack of dispatch information
+   * (and can override via the 4th constructor argument).
+   */
+  static readonly defaultCategory: ErrorCategory;
+  readonly code: AIErrorCode;
+  readonly category: ErrorCategory;
+  readonly context?: Record<string, unknown>;
+  constructor(code: AIErrorCode, message: string, options?: AIErrorOptions, category?: ErrorCategory);
+}
+//#endregion
+export { AIError, AIErrorOptions };
+//# sourceMappingURL=ai-error.d.mts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ai-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/ai-error.ts"],"mappings":";;;;;;AAqBA;;;;;;;;AAEkB;AAqDlB;;;;;;;KAvDY,cAAA;EACV,KAAA;EACA,OAAA,GAAU,MAAM;AAAA;;;;;;;;;;;;;;;;;;;;;AAwEU;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;cAnBf,OAAA,SAAgB,KAAA;;;;;;;;;kBASJ,eAAA,EAAiB,aAAA;EAAA,SAExB,IAAA,EAAM,WAAA;EAAA,SACN,QAAA,EAAU,aAAA;EAAA,SACV,OAAA,GAAU,MAAA;cAGxB,IAAA,EAAM,WAAA,EACN,OAAA,UACA,OAAA,GAAU,cAAA,EACV,QAAA,GAAW,aAAA;AAAA"}

package/esm/errors/ai-error.mjs

@@ -0,0 +1,68 @@
+//#region ../../@warlock.js/ai/src/errors/ai-error.ts
+/**
+* Base class for every error thrown (or surfaced via `result.error`) by
+* `@warlock.js/ai` and its provider adapter packages.
+*
+* **Role.** The single typed error contract across the AI framework.
+* Every thrown error anywhere in `@warlock.js/ai*` is either an
+* `AIError` itself or one of its subclasses — plain `Error` must never
+* leak out. Consumers branch either on the narrow `error.code` (stable
+* string), on `error.category` (coarse dashboard grouping), or on
+* `instanceof` a specific subclass.
+*
+* **Independence.** Deliberately extends the platform `Error` directly
+* — never `HttpError` from `@warlock.js/core`. The AI framework is a
+* standalone product; coupling its error base to a web framework would
+* force every consumer to pull in the HTTP layer even when they only
+* use AI in a CLI, worker, or test.
+*
+* **Fields.**
+* - `code` — stable machine-readable identifier (see `AIErrorCode`).
+* - `category` — coarse `ErrorCategory` for dashboards / retry policy.
+*   Resolved at construction from the subclass's `static defaultCategory`
+*   (or, for direct `new AIError(...)` calls, from the explicit 4th
+*   constructor argument).
+* - `cause` — optional original thrown value (SDK error, nested error,
+*   raw value). Preserves root cause through re-wrapping.
+* - `context` — optional free-form diagnostic bag (status, requestId,
+*   headers). Consumers treat it as opaque; logs and telemetry read it.
+*
+* **Category override — direct AIError usage only.** Subclasses ARE
+* their category by type; there's no legitimate runtime override at
+* the subclass level. The 4th constructor argument exists ONLY for
+* direct `new AIError(...)` callers, who would otherwise be stuck with
+* the `"unknown"` default. Subclasses construct via `super(code,
+* message, options)` and physically cannot reach the override slot
+* through their own typed signatures.
+*
+* @example
+* try {
+*   await agent.execute("hello");
+* } catch (error) {
+*   if (error instanceof AIError) {
+*     console.error(`[${error.code}] (${error.category}) ${error.message}`);
+*   }
+* }
+*
+* @example
+* // Direct AIError construction with explicit category — escape hatch
+* // for call sites that lack a specific subclass.
+* throw new AIError("UNEXPECTED", "transient glitch", undefined, "provider");
+*/
+var AIError = class extends Error {
+	static {
+		this.defaultCategory = "unknown";
+	}
+	constructor(code, message, options, category) {
+		super(message);
+		this.name = "AIError";
+		this.code = code;
+		this.context = options?.context;
+		this.category = category ?? this.constructor.defaultCategory;
+		if (options?.cause !== void 0) this.cause = options.cause;
+	}
+};
+
+//#endregion
+export { AIError };
+//# sourceMappingURL=ai-error.mjs.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ai-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/ai-error.ts"],"sourcesContent":["import type { ErrorCategory } from \"./error-category.type\";\nimport type { AIErrorCode } from \"./error-code.type\";\n\n/**\n * Optional constructor payload shared by every `AIError` subclass.\n *\n * `cause` carries the original thrown value (SDK error, runtime crash,\n * validation failure) so downstream logging and debuggers can still\n * reach it. `context` is a free-form diagnostic bag for provider-raw\n * metadata (status codes, request ids, response headers) that shouldn't\n * be promoted to typed fields but is useful in logs and telemetry.\n *\n * **No `category` here.** Category is fixed per subclass via the\n * class-level `static defaultCategory`. Subclasses ARE their\n * category — `RateLimitError` is always `\"rate-limit\"`, never\n * something else at runtime. Direct `new AIError(...)` callers (the\n * one legitimate override case, since the base catch-all has no\n * specific class) receive a separate 4th constructor argument\n * instead, so the override is structurally unreachable from subclass\n * call sites.\n */\nexport type AIErrorOptions = {\n  cause?: unknown;\n  context?: Record<string, unknown>;\n};\n\n/**\n * Base class for every error thrown (or surfaced via `result.error`) by\n * `@warlock.js/ai` and its provider adapter packages.\n *\n * **Role.** The single typed error contract across the AI framework.\n * Every thrown error anywhere in `@warlock.js/ai*` is either an\n * `AIError` itself or one of its subclasses — plain `Error` must never\n * leak out. Consumers branch either on the narrow `error.code` (stable\n * string), on `error.category` (coarse dashboard grouping), or on\n * `instanceof` a specific subclass.\n *\n * **Independence.** Deliberately extends the platform `Error` directly\n * — never `HttpError` from `@warlock.js/core`. The AI framework is a\n * standalone product; coupling its error base to a web framework would\n * force every consumer to pull in the HTTP layer even when they only\n * use AI in a CLI, worker, or test.\n *\n * **Fields.**\n * - `code` — stable machine-readable identifier (see `AIErrorCode`).\n * - `category` — coarse `ErrorCategory` for dashboards / retry policy.\n *   Resolved at construction from the subclass's `static defaultCategory`\n *   (or, for direct `new AIError(...)` calls, from the explicit 4th\n *   constructor argument).\n * - `cause` — optional original thrown value (SDK error, nested error,\n *   raw value). Preserves root cause through re-wrapping.\n * - `context` — optional free-form diagnostic bag (status, requestId,\n *   headers). Consumers treat it as opaque; logs and telemetry read it.\n *\n * **Category override — direct AIError usage only.** Subclasses ARE\n * their category by type; there's no legitimate runtime override at\n * the subclass level. The 4th constructor argument exists ONLY for\n * direct `new AIError(...)` callers, who would otherwise be stuck with\n * the `\"unknown\"` default. Subclasses construct via `super(code,\n * message, options)` and physically cannot reach the override slot\n * through their own typed signatures.\n *\n * @example\n * try {\n *   await agent.execute(\"hello\");\n * } catch (error) {\n *   if (error instanceof AIError) {\n *     console.error(`[${error.code}] (${error.category}) ${error.message}`);\n *   }\n * }\n *\n * @example\n * // Direct AIError construction with explicit category — escape hatch\n * // for call sites that lack a specific subclass.\n * throw new AIError(\"UNEXPECTED\", \"transient glitch\", undefined, \"provider\");\n */\nexport class AIError extends Error {\n  /**\n   * Class-level category for every instance of this error type.\n   * Subclasses redeclare with their own concrete `ErrorCategory` so\n   * `error.category` is correct without per-call wiring. The base\n   * class keeps `\"unknown\"` so untyped direct throws of `AIError`\n   * itself remain honest about their lack of dispatch information\n   * (and can override via the 4th constructor argument).\n   */\n  public static readonly defaultCategory: ErrorCategory = \"unknown\";\n\n  public readonly code: AIErrorCode;\n  public readonly category: ErrorCategory;\n  public readonly context?: Record<string, unknown>;\n\n  public constructor(\n    code: AIErrorCode,\n    message: string,\n    options?: AIErrorOptions,\n    category?: ErrorCategory,\n  ) {\n    super(message);\n\n    this.name = \"AIError\";\n    this.code = code;\n    this.context = options?.context;\n    this.category = category ?? (this.constructor as typeof AIError).defaultCategory;\n\n    if (options?.cause !== undefined) {\n      (this as { cause?: unknown }).cause = options.cause;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4EA,IAAa,UAAb,cAA6B,MAAM;;yBASuB;;CAMxD,AAAO,YACL,MACA,SACA,SACA,UACA;EACA,MAAM,OAAO;EAEb,KAAK,OAAO;EACZ,KAAK,OAAO;EACZ,KAAK,UAAU,SAAS;EACxB,KAAK,WAAW,YAAa,KAAK,YAA+B;EAEjE,IAAI,SAAS,UAAU,QACrB,AAAC,KAA6B,QAAQ,QAAQ;CAElD;AACF"}

package/esm/errors/budget-exceeded-error.d.mts

@@ -0,0 +1,41 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIError, AIErrorOptions } from "./ai-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/budget-exceeded-error.d.ts
+/**
+ * Unit of the budget being enforced. `tokens` for context/output
+ * caps, `usd` for monetary caps, `requests` for call-count caps.
+ */
+type BudgetUnit = "tokens" | "usd" | "requests";
+/**
+ * Payload for `BudgetExceededError`. All three fields are required so
+ * consumers can present the breach numerically without having to
+ * reparse the message.
+ */
+type BudgetExceededErrorOptions = AIErrorOptions & {
+  limit: number;
+  actual: number;
+  unit: BudgetUnit;
+};
+/**
+ * A user- or framework-configured budget was exceeded mid-execution.
+ *
+ * **Not thrown yet.** The class is defined here so v2's budget
+ * middleware can throw it without a breaking release of the error
+ * hierarchy. Shape is locked: `{ limit, actual, unit }`.
+ *
+ * @example
+ * if (error instanceof BudgetExceededError && error.unit === "usd") {
+ *   alertFinance(error.actual, error.limit);
+ * }
+ */
+declare class BudgetExceededError extends AIError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly limit: number;
+  readonly actual: number;
+  readonly unit: BudgetUnit;
+  constructor(message: string, options: BudgetExceededErrorOptions);
+}
+//#endregion
+export { BudgetExceededError, BudgetExceededErrorOptions, BudgetUnit };
+//# sourceMappingURL=budget-exceeded-error.d.mts.map

package/esm/errors/budget-exceeded-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-exceeded-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/budget-exceeded-error.ts"],"mappings":";;;;;;AAOA;;KAAY,UAAA;;AAAU;AAOtB;;;KAAY,0BAAA,GAA6B,cAAA;EACvC,KAAA;EACA,MAAA;EACA,IAAA,EAAM,UAAU;AAAA;;;AAAA;AAelB;;;;;;;;;cAAa,mBAAA,SAA4B,OAAA;EAAA,gBAChB,eAAA,EAAiB,aAAA;EAAA,SAExB,KAAA;EAAA,SACA,MAAA;EAAA,SACA,IAAA,EAAM,UAAA;cAEH,OAAA,UAAiB,OAAA,EAAS,0BAAA;AAAA"}

package/esm/errors/budget-exceeded-error.mjs

@@ -0,0 +1,31 @@
+import { AIError } from "./ai-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/budget-exceeded-error.ts
+/**
+* A user- or framework-configured budget was exceeded mid-execution.
+*
+* **Not thrown yet.** The class is defined here so v2's budget
+* middleware can throw it without a breaking release of the error
+* hierarchy. Shape is locked: `{ limit, actual, unit }`.
+*
+* @example
+* if (error instanceof BudgetExceededError && error.unit === "usd") {
+*   alertFinance(error.actual, error.limit);
+* }
+*/
+var BudgetExceededError = class extends AIError {
+	static {
+		this.defaultCategory = "budget";
+	}
+	constructor(message, options) {
+		super("BUDGET_EXCEEDED", message, options);
+		this.name = "BudgetExceededError";
+		this.limit = options.limit;
+		this.actual = options.actual;
+		this.unit = options.unit;
+	}
+};
+
+//#endregion
+export { BudgetExceededError };
+//# sourceMappingURL=budget-exceeded-error.mjs.map

package/esm/errors/budget-exceeded-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"budget-exceeded-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/budget-exceeded-error.ts"],"sourcesContent":["import { AIError, type AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\n\n/**\n * Unit of the budget being enforced. `tokens` for context/output\n * caps, `usd` for monetary caps, `requests` for call-count caps.\n */\nexport type BudgetUnit = \"tokens\" | \"usd\" | \"requests\";\n\n/**\n * Payload for `BudgetExceededError`. All three fields are required so\n * consumers can present the breach numerically without having to\n * reparse the message.\n */\nexport type BudgetExceededErrorOptions = AIErrorOptions & {\n  limit: number;\n  actual: number;\n  unit: BudgetUnit;\n};\n\n/**\n * A user- or framework-configured budget was exceeded mid-execution.\n *\n * **Not thrown yet.** The class is defined here so v2's budget\n * middleware can throw it without a breaking release of the error\n * hierarchy. Shape is locked: `{ limit, actual, unit }`.\n *\n * @example\n * if (error instanceof BudgetExceededError && error.unit === \"usd\") {\n *   alertFinance(error.actual, error.limit);\n * }\n */\nexport class BudgetExceededError extends AIError {\n  public static readonly defaultCategory: ErrorCategory = \"budget\";\n\n  public readonly limit: number;\n  public readonly actual: number;\n  public readonly unit: BudgetUnit;\n\n  public constructor(message: string, options: BudgetExceededErrorOptions) {\n    super(\"BUDGET_EXCEEDED\", message, options);\n    this.name = \"BudgetExceededError\";\n    this.limit = options.limit;\n    this.actual = options.actual;\n    this.unit = options.unit;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AAgCA,IAAa,sBAAb,cAAyC,QAAQ;;yBACS;;CAMxD,AAAO,YAAY,SAAiB,SAAqC;EACvE,MAAM,mBAAmB,SAAS,OAAO;EACzC,KAAK,OAAO;EACZ,KAAK,QAAQ,QAAQ;EACrB,KAAK,SAAS,QAAQ;EACtB,KAAK,OAAO,QAAQ;CACtB;AACF"}

package/esm/errors/content-filter-error.d.mts

@@ -0,0 +1,33 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorOptions } from "./ai-error.mjs";
+import { ProviderError } from "./provider-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/content-filter-error.d.ts
+/**
+ * Payload for `ContentFilterError`. Both fields optional — providers
+ * don't consistently disclose the specific filter reason or
+ * categories, especially when the block is pre-generation.
+ */
+type ContentFilterErrorOptions = AIErrorOptions & {
+  reason?: string;
+  categories?: string[];
+};
+/**
+ * Response (or request) was blocked by the provider's safety filter.
+ * Not retryable with the same input — reshape the prompt or lean on
+ * a less-restrictive model.
+ *
+ * @example
+ * if (result.error instanceof ContentFilterError) {
+ *   return respondWithPolicyMessage(result.error.reason);
+ * }
+ */
+declare class ContentFilterError extends ProviderError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly reason?: string;
+  readonly categories?: string[];
+  constructor(message: string, options?: ContentFilterErrorOptions);
+}
+//#endregion
+export { ContentFilterError, ContentFilterErrorOptions };
+//# sourceMappingURL=content-filter-error.d.mts.map

package/esm/errors/content-filter-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-filter-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/content-filter-error.ts"],"mappings":";;;;;;;AASA;;;KAAY,yBAAA,GAA4B,cAAc;EACpD,MAAA;EACA,UAAA;AAAA;;AAAU;AAaZ;;;;;;;;cAAa,kBAAA,SAA2B,aAAA;EAAA,gBACf,eAAA,EAAiB,aAAA;EAAA,SAExB,MAAA;EAAA,SACA,UAAA;cAEG,OAAA,UAAiB,OAAA,GAAU,yBAAA;AAAA"}

package/esm/errors/content-filter-error.mjs

@@ -0,0 +1,28 @@
+import { ProviderError } from "./provider-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/content-filter-error.ts
+/**
+* Response (or request) was blocked by the provider's safety filter.
+* Not retryable with the same input — reshape the prompt or lean on
+* a less-restrictive model.
+*
+* @example
+* if (result.error instanceof ContentFilterError) {
+*   return respondWithPolicyMessage(result.error.reason);
+* }
+*/
+var ContentFilterError = class extends ProviderError {
+	static {
+		this.defaultCategory = "content-filter";
+	}
+	constructor(message, options) {
+		super(message, options, "CONTENT_FILTER");
+		this.name = "ContentFilterError";
+		this.reason = options?.reason;
+		this.categories = options?.categories;
+	}
+};
+
+//#endregion
+export { ContentFilterError };
+//# sourceMappingURL=content-filter-error.mjs.map

package/esm/errors/content-filter-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-filter-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/content-filter-error.ts"],"sourcesContent":["import type { AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\nimport { ProviderError } from \"./provider-error\";\n\n/**\n * Payload for `ContentFilterError`. Both fields optional — providers\n * don't consistently disclose the specific filter reason or\n * categories, especially when the block is pre-generation.\n */\nexport type ContentFilterErrorOptions = AIErrorOptions & {\n  reason?: string;\n  categories?: string[];\n};\n\n/**\n * Response (or request) was blocked by the provider's safety filter.\n * Not retryable with the same input — reshape the prompt or lean on\n * a less-restrictive model.\n *\n * @example\n * if (result.error instanceof ContentFilterError) {\n *   return respondWithPolicyMessage(result.error.reason);\n * }\n */\nexport class ContentFilterError extends ProviderError {\n  public static readonly defaultCategory: ErrorCategory = \"content-filter\";\n\n  public readonly reason?: string;\n  public readonly categories?: string[];\n\n  public constructor(message: string, options?: ContentFilterErrorOptions) {\n    super(message, options, \"CONTENT_FILTER\");\n    this.name = \"ContentFilterError\";\n    this.reason = options?.reason;\n    this.categories = options?.categories;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;AAwBA,IAAa,qBAAb,cAAwC,cAAc;;yBACI;;CAKxD,AAAO,YAAY,SAAiB,SAAqC;EACvE,MAAM,SAAS,SAAS,gBAAgB;EACxC,KAAK,OAAO;EACZ,KAAK,SAAS,SAAS;EACvB,KAAK,aAAa,SAAS;CAC7B;AACF"}

package/esm/errors/context-length-exceeded-error.d.mts

@@ -0,0 +1,38 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIErrorOptions } from "./ai-error.mjs";
+import { ProviderError } from "./provider-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/context-length-exceeded-error.d.ts
+/**
+ * Payload for `ContextLengthExceededError`. All fields are optional —
+ * providers inconsistently surface exact token counts and the
+ * model's limit. When present, they let callers compute a trim
+ * target; when absent, the error still categorizes the failure.
+ */
+type ContextLengthExceededErrorOptions = AIErrorOptions & {
+  limit?: number;
+  actual?: number;
+  modelName?: string;
+};
+/**
+ * The request's prompt (messages + tools + schema) exceeded the
+ * model's context window. Not retryable without shortening the input.
+ *
+ * Typically surfaced as OpenAI 400 with `code: "context_length_exceeded"`.
+ *
+ * @example
+ * if (result.error instanceof ContextLengthExceededError) {
+ *   messages = truncateOldestTurns(messages);
+ *   return agent.execute(input, { history: messages });
+ * }
+ */
+declare class ContextLengthExceededError extends ProviderError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly limit?: number;
+  readonly actual?: number;
+  readonly modelName?: string;
+  constructor(message: string, options?: ContextLengthExceededErrorOptions);
+}
+//#endregion
+export { ContextLengthExceededError, ContextLengthExceededErrorOptions };
+//# sourceMappingURL=context-length-exceeded-error.d.mts.map

package/esm/errors/context-length-exceeded-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-length-exceeded-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/context-length-exceeded-error.ts"],"mappings":";;;;;;;AAUA;;;;KAAY,iCAAA,GAAoC,cAAc;EAC5D,KAAA;EACA,MAAA;EACA,SAAA;AAAA;AAAS;AAeX;;;;;;;;;;;AAfW,cAeE,0BAAA,SAAmC,aAAA;EAAA,gBACvB,eAAA,EAAiB,aAAA;EAAA,SAExB,KAAA;EAAA,SACA,MAAA;EAAA,SACA,SAAA;cAGd,OAAA,UACA,OAAA,GAAU,iCAAA;AAAA"}

package/esm/errors/context-length-exceeded-error.mjs

@@ -0,0 +1,31 @@
+import { ProviderError } from "./provider-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/context-length-exceeded-error.ts
+/**
+* The request's prompt (messages + tools + schema) exceeded the
+* model's context window. Not retryable without shortening the input.
+*
+* Typically surfaced as OpenAI 400 with `code: "context_length_exceeded"`.
+*
+* @example
+* if (result.error instanceof ContextLengthExceededError) {
+*   messages = truncateOldestTurns(messages);
+*   return agent.execute(input, { history: messages });
+* }
+*/
+var ContextLengthExceededError = class extends ProviderError {
+	static {
+		this.defaultCategory = "context-length";
+	}
+	constructor(message, options) {
+		super(message, options, "CONTEXT_LENGTH_EXCEEDED");
+		this.name = "ContextLengthExceededError";
+		this.limit = options?.limit;
+		this.actual = options?.actual;
+		this.modelName = options?.modelName;
+	}
+};
+
+//#endregion
+export { ContextLengthExceededError };
+//# sourceMappingURL=context-length-exceeded-error.mjs.map

package/esm/errors/context-length-exceeded-error.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-length-exceeded-error.mjs","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/context-length-exceeded-error.ts"],"sourcesContent":["import type { AIErrorOptions } from \"./ai-error\";\nimport type { ErrorCategory } from \"./error-category.type\";\nimport { ProviderError } from \"./provider-error\";\n\n/**\n * Payload for `ContextLengthExceededError`. All fields are optional —\n * providers inconsistently surface exact token counts and the\n * model's limit. When present, they let callers compute a trim\n * target; when absent, the error still categorizes the failure.\n */\nexport type ContextLengthExceededErrorOptions = AIErrorOptions & {\n  limit?: number;\n  actual?: number;\n  modelName?: string;\n};\n\n/**\n * The request's prompt (messages + tools + schema) exceeded the\n * model's context window. Not retryable without shortening the input.\n *\n * Typically surfaced as OpenAI 400 with `code: \"context_length_exceeded\"`.\n *\n * @example\n * if (result.error instanceof ContextLengthExceededError) {\n *   messages = truncateOldestTurns(messages);\n *   return agent.execute(input, { history: messages });\n * }\n */\nexport class ContextLengthExceededError extends ProviderError {\n  public static readonly defaultCategory: ErrorCategory = \"context-length\";\n\n  public readonly limit?: number;\n  public readonly actual?: number;\n  public readonly modelName?: string;\n\n  public constructor(\n    message: string,\n    options?: ContextLengthExceededErrorOptions,\n  ) {\n    super(message, options, \"CONTEXT_LENGTH_EXCEEDED\");\n    this.name = \"ContextLengthExceededError\";\n    this.limit = options?.limit;\n    this.actual = options?.actual;\n    this.modelName = options?.modelName;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;AA4BA,IAAa,6BAAb,cAAgD,cAAc;;yBACJ;;CAMxD,AAAO,YACL,SACA,SACA;EACA,MAAM,SAAS,SAAS,yBAAyB;EACjD,KAAK,OAAO;EACZ,KAAK,QAAQ,SAAS;EACtB,KAAK,SAAS,SAAS;EACvB,KAAK,YAAY,SAAS;CAC5B;AACF"}

package/esm/errors/error-category.type.d.mts

@@ -0,0 +1,30 @@
+//#region ../../@warlock.js/ai/src/errors/error-category.type.d.ts
+/**
+ * Coarse error grouping for dashboards and routing logic. `code` is too
+ * granular for "what's failing this week" charts — the category union
+ * is the dispatch key that drives:
+ *
+ * - Panoptic / dashboard aggregations (pie chart of failures by
+ *   category)
+ * - Retry policy (`rate-limit` → retry with backoff; `auth` → don't
+ *   retry, escalate)
+ * - User-facing error mapping (`content-filter` → soft message;
+ *   `provider` → "we're having issues, try again")
+ *
+ * Each `AIError` subclass declares its category via a `static
+ * defaultCategory` field, so the value is inherent to the error type
+ * rather than constructor-supplied — bugs that forget to set a
+ * category are caught at class-definition time, not at runtime. Direct
+ * `new AIError(...)` usages may pass `category` in options as an
+ * escape hatch.
+ *
+ * @example
+ * if (error.category === "rate-limit") {
+ *   await sleep(error.context?.retryAfterMs ?? 1000);
+ *   return retry();
+ * }
+ */
+type ErrorCategory = "auth" | "rate-limit" | "timeout" | "validation" | "content-filter" | "provider" | "tool" | "cancelled" | "max-trips" | "max-iterations" | "max-steps" | "schema" | "drift" | "routing" | "guardrail" | "budget" | "quota" | "context-length" | "unknown";
+//#endregion
+export { ErrorCategory };
+//# sourceMappingURL=error-category.type.d.mts.map

package/esm/errors/error-category.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-category.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/error-category.type.ts"],"mappings":";;AAyBA;;;;AAAyB;;;;;;;;;;;;;;;;;;;;KAAb,aAAA"}

package/esm/errors/error-code.type.d.mts

@@ -0,0 +1,19 @@
+//#region ../../@warlock.js/ai/src/errors/error-code.type.d.ts
+/**
+ * Stable machine-readable identifier for every `AIError` subclass.
+ *
+ * Consumers switch on `error.code` rather than `instanceof` whenever the
+ * logic is "what went wrong in terms the user needs to handle" (retryable,
+ * wrong API key, too long, etc.). The strings are part of the public API —
+ * never rename an existing code; add a new one.
+ *
+ * @example
+ * if (result.error?.code === "PROVIDER_RATE_LIMIT") {
+ *   await sleep(result.error.retryAfter ?? 1000);
+ *   return agent.execute(input);
+ * }
+ */
+type AIErrorCode = "AGENT_EXEC_FAILED" | "AGENT_CANCELLED" | "AGENT_MAX_TRIPS" | "SCHEMA_VALIDATION_FAILED" | "TOOL_EXEC_FAILED" | "PROVIDER_ERROR" | "PROVIDER_RATE_LIMIT" | "PROVIDER_QUOTA_EXCEEDED" | "PROVIDER_TIMEOUT" | "CONTEXT_LENGTH_EXCEEDED" | "CONTENT_FILTER" | "PROVIDER_INVALID_REQUEST" | "PROVIDER_AUTH" | "BUDGET_EXCEEDED" | "GUARDRAIL_VIOLATION" | "WORKFLOW_ERROR" | "STEP_FAILED" | "WORKFLOW_DRIFT" | "WORKFLOW_CANCELLED" | "WORKFLOW_MAX_STEPS" | "WORKFLOW_INVALID_GOTO" | "SUPERVISOR_FAILED" | "SUPERVISOR_MAX_ITERATIONS" | "SUPERVISOR_INVALID_ROUTE" | "SUPERVISOR_CANCELLED" | "SUPERVISOR_DRIFT" | "SUPERVISOR_INTENT_DESCRIPTION_REQUIRED" | "SUPERVISOR_INTENT_MIXED_DISPATCH" | "SUPERVISOR_INTENT_STREAM_AND_OUTPUT" | "SUPERVISOR_INTENT_STREAM_TO_REQUIRED" | "SUPERVISOR_INTENT_STREAM_ON_WORKFLOW" | "SUPERVISOR_DISPATCH_CYCLE";
+//#endregion
+export { AIErrorCode };
+//# sourceMappingURL=error-code.type.d.mts.map

package/esm/errors/error-code.type.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-code.type.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/error-code.type.ts"],"mappings":";;AAcA;;;;AAAuB;;;;;;;;;KAAX,WAAA"}

package/esm/errors/guardrail-violation-error.d.mts

@@ -0,0 +1,55 @@
+import { ErrorCategory } from "./error-category.type.mjs";
+import { AIError, AIErrorOptions } from "./ai-error.mjs";
+
+//#region ../../@warlock.js/ai/src/errors/guardrail-violation-error.d.ts
+/**
+ * Phase at which a guardrail rejected the content — `"input"` when the
+ * violation was detected on the outbound prompt (before the model saw
+ * it), `"output"` when it was detected on the model's response (before
+ * the caller saw it).
+ */
+type GuardrailPhase = "input" | "output";
+/**
+ * Payload for `GuardrailViolationError`. `phase` tells the caller
+ * whether the prompt or the response tripped the check; `reason` is
+ * the free-form explanation the guardrail middleware produced;
+ * `guardrail` names the offending middleware so operators can tune a
+ * specific rule without hunting through logs.
+ */
+type GuardrailViolationErrorOptions = AIErrorOptions & {
+  phase: GuardrailPhase;
+  reason: string;
+  guardrail?: string;
+};
+/**
+ * A guardrail middleware rejected the prompt or response mid-execution.
+ *
+ * **Role.** The typed abort surface for `ai.middleware.guardrail`.
+ * Consumers branch on `error.phase` to distinguish "the user asked
+ * something disallowed" (`"input"`) from "the model produced something
+ * disallowed" (`"output"`) — the two failure modes have very different
+ * product responses (block vs. retry, or surface a policy message vs.
+ * re-prompt the model).
+ *
+ * Thrown from inside the middleware pipeline's `trip.before` / `trip.after`
+ * hooks; surfaced to the caller via `result.error` like every other
+ * `AIError`.
+ *
+ * @example
+ * if (result.error instanceof GuardrailViolationError) {
+ *   if (result.error.phase === "input") {
+ *     return respondWithPolicyMessage(result.error.reason);
+ *   }
+ *   return retryWithSanitizedPrompt();
+ * }
+ */
+declare class GuardrailViolationError extends AIError {
+  static readonly defaultCategory: ErrorCategory;
+  readonly phase: GuardrailPhase;
+  readonly reason: string;
+  readonly guardrail?: string;
+  constructor(message: string, options: GuardrailViolationErrorOptions);
+}
+//#endregion
+export { GuardrailPhase, GuardrailViolationError, GuardrailViolationErrorOptions };
+//# sourceMappingURL=guardrail-violation-error.d.mts.map

package/esm/errors/guardrail-violation-error.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"guardrail-violation-error.d.mts","names":[],"sources":["../../../../../../@warlock.js/ai/src/errors/guardrail-violation-error.ts"],"mappings":";;;;;;AASA;;;;KAAY,cAAA;AASZ;;;;;;;AAAA,KAAY,8BAAA,GAAiC,cAAA;EAC3C,KAAA,EAAO,cAAc;EACrB,MAAA;EACA,SAAA;AAAA;;;;;;;;;;;;;;;;;;;;;AAgC2E;;cAPhE,uBAAA,SAAgC,OAAA;EAAA,gBACpB,eAAA,EAAiB,aAAA;EAAA,SAExB,KAAA,EAAO,cAAA;EAAA,SACP,MAAA;EAAA,SACA,SAAA;cAEG,OAAA,UAAiB,OAAA,EAAS,8BAAA;AAAA"}