@rudderjs/ai 1.5.0 → 1.6.1

package/dist/budget/pricing.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Model pricing catalog — USD per 1k tokens, snapshot-dated per entry.
+ *
+ * Used by:
+ * - `@rudderjs/ai/eval` to populate the cost column on eval reports
+ * - `@rudderjs/ai`'s budget enforcement middleware (A6 phase 3) to debit
+ *   per-user spend against caps
+ *
+ * # Pricing drift
+ *
+ * Provider list pricing changes monthly. Each entry carries `_snapshotDate`
+ * indicating when the rate was captured. Apps with negotiated rates should
+ * pass an override map:
+ *
+ * ```ts
+ * import { ModelPricing, withBudget } from '@rudderjs/ai'
+ *
+ * withBudget({
+ *   pricing: {
+ *     ...ModelPricing,
+ *     'anthropic/claude-opus-4-7': {
+ *       inputPer1k:  0.012,
+ *       outputPer1k: 0.060,
+ *       _snapshotDate: '2026-01-15',
+ *     },
+ *   },
+ *   // ...
+ * })
+ * ```
+ *
+ * # Cache rates
+ *
+ * Anthropic, OpenAI, and Google all offer reduced rates for cache reads
+ * (and Anthropic charges a small premium for cache writes). The optional
+ * `cacheReadPer1k` / `cacheWritePer1k` fields capture those. The budget
+ * middleware uses them when `TokenUsage` carries cache deltas; when absent
+ * (today's `TokenUsage` shape), input rate applies to all input tokens.
+ */
+/** Pricing for a single `<provider>/<model>` id, USD per 1k tokens. */
+export interface ModelPriceEntry {
+    /** Cost per 1k input (prompt) tokens, USD. */
+    inputPer1k: number;
+    /** Cost per 1k output (completion) tokens, USD. */
+    outputPer1k: number;
+    /**
+     * Optional cost per 1k cached-read input tokens, USD. Set when the
+     * provider exposes a discounted rate for cache hits (Anthropic ephemeral
+     * cache, OpenAI prefix cache, Google cachedContent). When omitted,
+     * `inputPer1k` applies to all input tokens.
+     */
+    cacheReadPer1k?: number;
+    /**
+     * Optional cost per 1k cache-write input tokens, USD. Anthropic charges
+     * a small premium on the first write that primes an ephemeral cache;
+     * other providers don't. When omitted, `inputPer1k` applies.
+     */
+    cacheWritePer1k?: number;
+    /**
+     * ISO date string indicating when this rate was captured from the
+     * provider's published pricing. Surfaced in
+     * {@link UnknownModelPricingError} messages and useful when auditing
+     * stale catalogs.
+     */
+    _snapshotDate: string;
+}
+/**
+ * `<provider>/<model>` → {@link ModelPriceEntry}. Override entries by
+ * spreading: `{ ...ModelPricing, 'anthropic/claude-opus-4-7': {...} }`.
+ *
+ * Snapshot date: 2026-05-11.
+ */
+export declare const ModelPricing: Record<string, ModelPriceEntry>;
+/**
+ * Compute USD cost for an agent call given prompt + completion token
+ * counts and a pricing catalog.
+ *
+ * Returns `0` when the model id isn't in `pricing` — eval cost columns
+ * shouldn't crash on a fresh model. The budget middleware (A6 phase 3)
+ * uses {@link assertKnownModelPricing} to fail loud at config time
+ * instead.
+ *
+ * @param model     `<provider>/<model>` id
+ * @param promptTokens  Input tokens charged at `inputPer1k`
+ * @param completionTokens  Output tokens charged at `outputPer1k`
+ * @param pricing   Catalog override (defaults to {@link ModelPricing})
+ */
+export declare function estimateCost(model: string, promptTokens: number, completionTokens: number, pricing?: Record<string, ModelPriceEntry>): number;
+/**
+ * Budget enforcement uses this — fail loud at agent-construction time
+ * if the configured model isn't priced. Call from `withBudget(...)` in
+ * phase 3.
+ *
+ * @throws {UnknownModelPricingError} when `pricing[model]` is missing
+ */
+export declare function assertKnownModelPricing(model: string, pricing?: Record<string, ModelPriceEntry>): ModelPriceEntry;
+/**
+ * Thrown by `assertKnownModelPricing` when a model id has no pricing
+ * entry. The budget middleware throws this at construction so apps
+ * fail at boot, not on first prompt.
+ */
+export declare class UnknownModelPricingError extends Error {
+    readonly model: string;
+    readonly snapshotDate: string | null;
+    constructor(model: string, pricing: Record<string, ModelPriceEntry>);
+}
+/**
+ * Thrown by the budget middleware (A6 phase 3) when a request would
+ * exceed a user's daily or monthly cap. Apps that want a different
+ * error type can intercept via `withBudget({ onExceeded })` and throw
+ * their own.
+ */
+export declare class BudgetExceededError extends Error {
+    readonly userId: string;
+    readonly period: 'daily' | 'monthly';
+    readonly spent: number;
+    readonly cap: number;
+    constructor(opts: {
+        userId: string;
+        period: 'daily' | 'monthly';
+        spent: number;
+        cap: number;
+    });
+}
+//# sourceMappingURL=pricing.d.ts.map

package/dist/budget/pricing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.d.ts","sourceRoot":"","sources":["../../src/budget/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,8CAA8C;IAC9C,UAAU,EAAE,MAAM,CAAA;IAClB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAA;CACtB;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CA+DxD,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,YAAY,EAAE,MAAM,EACpB,gBAAgB,EAAE,MAAM,EACxB,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAgB,GACtD,MAAM,CAIR;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAgB,GACtD,eAAe,CAIjB;AAED;;;;GAIG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;gBAExB,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC;CAapE;AAED;;;;;GAKG;AACH,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAA;IACpC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;gBAER,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE;CAW9F"}

package/dist/budget/pricing.js

@@ -0,0 +1,175 @@
+/**
+ * Model pricing catalog — USD per 1k tokens, snapshot-dated per entry.
+ *
+ * Used by:
+ * - `@rudderjs/ai/eval` to populate the cost column on eval reports
+ * - `@rudderjs/ai`'s budget enforcement middleware (A6 phase 3) to debit
+ *   per-user spend against caps
+ *
+ * # Pricing drift
+ *
+ * Provider list pricing changes monthly. Each entry carries `_snapshotDate`
+ * indicating when the rate was captured. Apps with negotiated rates should
+ * pass an override map:
+ *
+ * ```ts
+ * import { ModelPricing, withBudget } from '@rudderjs/ai'
+ *
+ * withBudget({
+ *   pricing: {
+ *     ...ModelPricing,
+ *     'anthropic/claude-opus-4-7': {
+ *       inputPer1k:  0.012,
+ *       outputPer1k: 0.060,
+ *       _snapshotDate: '2026-01-15',
+ *     },
+ *   },
+ *   // ...
+ * })
+ * ```
+ *
+ * # Cache rates
+ *
+ * Anthropic, OpenAI, and Google all offer reduced rates for cache reads
+ * (and Anthropic charges a small premium for cache writes). The optional
+ * `cacheReadPer1k` / `cacheWritePer1k` fields capture those. The budget
+ * middleware uses them when `TokenUsage` carries cache deltas; when absent
+ * (today's `TokenUsage` shape), input rate applies to all input tokens.
+ */
+/**
+ * `<provider>/<model>` → {@link ModelPriceEntry}. Override entries by
+ * spreading: `{ ...ModelPricing, 'anthropic/claude-opus-4-7': {...} }`.
+ *
+ * Snapshot date: 2026-05-11.
+ */
+export const ModelPricing = {
+    // ─── Anthropic ──────────────────────────────────────────
+    // Cache write = 1.25× input, cache read = 0.1× input (Anthropic ephemeral)
+    'anthropic/claude-opus-4-7': { inputPer1k: 0.015, outputPer1k: 0.075, cacheWritePer1k: 0.01875, cacheReadPer1k: 0.0015, _snapshotDate: '2026-05-11' },
+    'anthropic/claude-opus-4-6': { inputPer1k: 0.015, outputPer1k: 0.075, cacheWritePer1k: 0.01875, cacheReadPer1k: 0.0015, _snapshotDate: '2026-05-11' },
+    'anthropic/claude-sonnet-4-6': { inputPer1k: 0.003, outputPer1k: 0.015, cacheWritePer1k: 0.00375, cacheReadPer1k: 0.0003, _snapshotDate: '2026-05-11' },
+    'anthropic/claude-sonnet-4-5': { inputPer1k: 0.003, outputPer1k: 0.015, cacheWritePer1k: 0.00375, cacheReadPer1k: 0.0003, _snapshotDate: '2026-05-11' },
+    'anthropic/claude-haiku-4-5': { inputPer1k: 0.0008, outputPer1k: 0.004, cacheWritePer1k: 0.001, cacheReadPer1k: 0.00008, _snapshotDate: '2026-05-11' },
+    'anthropic/claude-3-7-sonnet': { inputPer1k: 0.003, outputPer1k: 0.015, cacheWritePer1k: 0.00375, cacheReadPer1k: 0.0003, _snapshotDate: '2026-05-11' },
+    'anthropic/claude-3-5-sonnet': { inputPer1k: 0.003, outputPer1k: 0.015, cacheWritePer1k: 0.00375, cacheReadPer1k: 0.0003, _snapshotDate: '2026-05-11' },
+    'anthropic/claude-3-5-haiku': { inputPer1k: 0.0008, outputPer1k: 0.004, cacheWritePer1k: 0.001, cacheReadPer1k: 0.00008, _snapshotDate: '2026-05-11' },
+    // ─── OpenAI ─────────────────────────────────────────────
+    // Cache read = 0.5× input (OpenAI prefix cache); no cache write surcharge
+    'openai/gpt-4-1': { inputPer1k: 0.002, outputPer1k: 0.008, cacheReadPer1k: 0.0005, _snapshotDate: '2026-05-11' },
+    'openai/gpt-4-1-mini': { inputPer1k: 0.0004, outputPer1k: 0.0016, cacheReadPer1k: 0.0001, _snapshotDate: '2026-05-11' },
+    'openai/gpt-4-1-nano': { inputPer1k: 0.0001, outputPer1k: 0.0004, cacheReadPer1k: 0.000025, _snapshotDate: '2026-05-11' },
+    'openai/gpt-4o': { inputPer1k: 0.0025, outputPer1k: 0.01, cacheReadPer1k: 0.00125, _snapshotDate: '2026-05-11' },
+    'openai/gpt-4o-mini': { inputPer1k: 0.00015, outputPer1k: 0.0006, cacheReadPer1k: 0.000075, _snapshotDate: '2026-05-11' },
+    'openai/o1': { inputPer1k: 0.015, outputPer1k: 0.06, cacheReadPer1k: 0.0075, _snapshotDate: '2026-05-11' },
+    'openai/o1-mini': { inputPer1k: 0.0011, outputPer1k: 0.0044, cacheReadPer1k: 0.00055, _snapshotDate: '2026-05-11' },
+    'openai/o3': { inputPer1k: 0.002, outputPer1k: 0.008, cacheReadPer1k: 0.0005, _snapshotDate: '2026-05-11' },
+    'openai/o3-mini': { inputPer1k: 0.0011, outputPer1k: 0.0044, cacheReadPer1k: 0.00055, _snapshotDate: '2026-05-11' },
+    'openai/o4-mini': { inputPer1k: 0.0011, outputPer1k: 0.0044, cacheReadPer1k: 0.000275, _snapshotDate: '2026-05-11' },
+    // ─── Google (Gemini) ────────────────────────────────────
+    // Cache read = 0.25× input (Google cachedContent); no cache write surcharge
+    'google/gemini-2.5-pro': { inputPer1k: 0.00125, outputPer1k: 0.005, cacheReadPer1k: 0.0003125, _snapshotDate: '2026-05-11' },
+    'google/gemini-2.5-flash': { inputPer1k: 0.000075, outputPer1k: 0.0003, cacheReadPer1k: 0.00001875, _snapshotDate: '2026-05-11' },
+    'google/gemini-2.5-flash-lite': { inputPer1k: 0.00004, outputPer1k: 0.00015, cacheReadPer1k: 0.00001, _snapshotDate: '2026-05-11' },
+    'google/gemini-2.0-flash': { inputPer1k: 0.0001, outputPer1k: 0.0004, cacheReadPer1k: 0.000025, _snapshotDate: '2026-05-11' },
+    'google/gemini-2.0-flash-lite': { inputPer1k: 0.000075, outputPer1k: 0.0003, cacheReadPer1k: 0.00001875, _snapshotDate: '2026-05-11' },
+    // ─── Bedrock (Anthropic models on AWS Bedrock) ──────────
+    // Bedrock matches Anthropic list pricing for Claude family.
+    'bedrock/anthropic.claude-opus-4-7': { inputPer1k: 0.015, outputPer1k: 0.075, cacheWritePer1k: 0.01875, cacheReadPer1k: 0.0015, _snapshotDate: '2026-05-11' },
+    'bedrock/anthropic.claude-sonnet-4-6': { inputPer1k: 0.003, outputPer1k: 0.015, cacheWritePer1k: 0.00375, cacheReadPer1k: 0.0003, _snapshotDate: '2026-05-11' },
+    'bedrock/anthropic.claude-haiku-4-5': { inputPer1k: 0.0008, outputPer1k: 0.004, cacheWritePer1k: 0.001, cacheReadPer1k: 0.00008, _snapshotDate: '2026-05-11' },
+    'bedrock/anthropic.claude-3-5-sonnet': { inputPer1k: 0.003, outputPer1k: 0.015, cacheWritePer1k: 0.00375, cacheReadPer1k: 0.0003, _snapshotDate: '2026-05-11' },
+    'bedrock/anthropic.claude-3-5-haiku': { inputPer1k: 0.0008, outputPer1k: 0.004, cacheWritePer1k: 0.001, cacheReadPer1k: 0.00008, _snapshotDate: '2026-05-11' },
+    // ─── xAI (Grok) ─────────────────────────────────────────
+    'xai/grok-4': { inputPer1k: 0.003, outputPer1k: 0.015, _snapshotDate: '2026-05-11' },
+    'xai/grok-3': { inputPer1k: 0.003, outputPer1k: 0.015, _snapshotDate: '2026-05-11' },
+    'xai/grok-3-mini': { inputPer1k: 0.0003, outputPer1k: 0.0005, _snapshotDate: '2026-05-11' },
+    // ─── DeepSeek ───────────────────────────────────────────
+    'deepseek/deepseek-chat': { inputPer1k: 0.00027, outputPer1k: 0.0011, cacheReadPer1k: 0.00007, _snapshotDate: '2026-05-11' },
+    'deepseek/deepseek-reasoner': { inputPer1k: 0.00055, outputPer1k: 0.00219, cacheReadPer1k: 0.00014, _snapshotDate: '2026-05-11' },
+    // ─── Mistral ────────────────────────────────────────────
+    'mistral/mistral-large': { inputPer1k: 0.002, outputPer1k: 0.006, _snapshotDate: '2026-05-11' },
+    'mistral/mistral-medium': { inputPer1k: 0.0004, outputPer1k: 0.002, _snapshotDate: '2026-05-11' },
+    'mistral/mistral-small': { inputPer1k: 0.0001, outputPer1k: 0.0003, _snapshotDate: '2026-05-11' },
+    // ─── Groq ───────────────────────────────────────────────
+    'groq/llama-3.3-70b-versatile': { inputPer1k: 0.00059, outputPer1k: 0.00079, _snapshotDate: '2026-05-11' },
+    'groq/llama-3.1-8b-instant': { inputPer1k: 0.00005, outputPer1k: 0.00008, _snapshotDate: '2026-05-11' },
+    // ─── Cohere ─────────────────────────────────────────────
+    'cohere/command-a': { inputPer1k: 0.0025, outputPer1k: 0.01, _snapshotDate: '2026-05-11' },
+    'cohere/command-r-plus': { inputPer1k: 0.0025, outputPer1k: 0.01, _snapshotDate: '2026-05-11' },
+    'cohere/command-r': { inputPer1k: 0.00015, outputPer1k: 0.0006, _snapshotDate: '2026-05-11' },
+};
+/**
+ * Compute USD cost for an agent call given prompt + completion token
+ * counts and a pricing catalog.
+ *
+ * Returns `0` when the model id isn't in `pricing` — eval cost columns
+ * shouldn't crash on a fresh model. The budget middleware (A6 phase 3)
+ * uses {@link assertKnownModelPricing} to fail loud at config time
+ * instead.
+ *
+ * @param model     `<provider>/<model>` id
+ * @param promptTokens  Input tokens charged at `inputPer1k`
+ * @param completionTokens  Output tokens charged at `outputPer1k`
+ * @param pricing   Catalog override (defaults to {@link ModelPricing})
+ */
+export function estimateCost(model, promptTokens, completionTokens, pricing = ModelPricing) {
+    const rate = pricing[model];
+    if (!rate)
+        return 0;
+    return (promptTokens * rate.inputPer1k + completionTokens * rate.outputPer1k) / 1000;
+}
+/**
+ * Budget enforcement uses this — fail loud at agent-construction time
+ * if the configured model isn't priced. Call from `withBudget(...)` in
+ * phase 3.
+ *
+ * @throws {UnknownModelPricingError} when `pricing[model]` is missing
+ */
+export function assertKnownModelPricing(model, pricing = ModelPricing) {
+    const rate = pricing[model];
+    if (!rate)
+        throw new UnknownModelPricingError(model, pricing);
+    return rate;
+}
+/**
+ * Thrown by `assertKnownModelPricing` when a model id has no pricing
+ * entry. The budget middleware throws this at construction so apps
+ * fail at boot, not on first prompt.
+ */
+export class UnknownModelPricingError extends Error {
+    model;
+    snapshotDate;
+    constructor(model, pricing) {
+        const sample = Object.keys(pricing)[0];
+        const snapshotDate = sample ? (pricing[sample]?._snapshotDate ?? null) : null;
+        const sampleSuffix = snapshotDate ? ` (catalog snapshot ${snapshotDate})` : '';
+        super(`[RudderJS AI] No pricing entry for model "${model}"${sampleSuffix}. ` +
+            `Either the model id is misspelled, or the catalog is stale — ` +
+            `add an override entry: \`pricing: { ...ModelPricing, "${model}": { inputPer1k, outputPer1k, _snapshotDate } }\`.`);
+        this.name = 'UnknownModelPricingError';
+        this.model = model;
+        this.snapshotDate = snapshotDate;
+    }
+}
+/**
+ * Thrown by the budget middleware (A6 phase 3) when a request would
+ * exceed a user's daily or monthly cap. Apps that want a different
+ * error type can intercept via `withBudget({ onExceeded })` and throw
+ * their own.
+ */
+export class BudgetExceededError extends Error {
+    userId;
+    period;
+    spent;
+    cap;
+    constructor(opts) {
+        super(`[RudderJS AI] ${opts.period} budget of $${opts.cap.toFixed(2)} exceeded for user ${opts.userId} ` +
+            `(spent $${opts.spent.toFixed(4)}).`);
+        this.name = 'BudgetExceededError';
+        this.userId = opts.userId;
+        this.period = opts.period;
+        this.spent = opts.spent;
+        this.cap = opts.cap;
+    }
+}
+//# sourceMappingURL=pricing.js.map

package/dist/budget/pricing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pricing.js","sourceRoot":"","sources":["../../src/budget/pricing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AA8BH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,YAAY,GAAoC;IAC3D,2DAA2D;IAC3D,2EAA2E;IAC3E,2BAA2B,EAAQ,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,eAAe,EAAE,OAAO,EAAI,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACrK,2BAA2B,EAAQ,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,eAAe,EAAE,OAAO,EAAI,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACrK,6BAA6B,EAAM,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,eAAe,EAAE,OAAO,EAAI,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACrK,6BAA6B,EAAM,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,eAAe,EAAE,OAAO,EAAI,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACrK,4BAA4B,EAAO,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,KAAK,EAAI,eAAe,EAAE,KAAK,EAAM,cAAc,EAAE,OAAO,EAAI,aAAa,EAAE,YAAY,EAAE;IACrK,6BAA6B,EAAM,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,eAAe,EAAE,OAAO,EAAI,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACrK,6BAA6B,EAAM,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,eAAe,EAAE,OAAO,EAAI,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACrK,4BAA4B,EAAO,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,KAAK,EAAI,eAAe,EAAE,KAAK,EAAM,cAAc,EAAE,OAAO,EAAI,aAAa,EAAE,YAAY,EAAE;IAErK,2DAA2D;IAC3D,0EAA0E;IAC1E,gBAAgB,EAAmB,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACzI,qBAAqB,EAAc,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACzI,qBAAqB,EAAc,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,QAAQ,EAAG,aAAa,EAAE,YAAY,EAAE;IACzI,eAAe,EAAoB,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,IAAI,EAAK,cAAc,EAAE,OAAO,EAAI,aAAa,EAAE,YAAY,EAAE;IACzI,oBAAoB,EAAe,EAAE,UAAU,EAAE,OAAO,EAAG,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,QAAQ,EAAG,aAAa,EAAE,YAAY,EAAE;IACzI,WAAW,EAAwB,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,IAAI,EAAK,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACzI,gBAAgB,EAAmB,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,OAAO,EAAI,aAAa,EAAE,YAAY,EAAE;IACzI,WAAW,EAAwB,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,cAAc,EAAE,MAAM,EAAK,aAAa,EAAE,YAAY,EAAE;IACzI,gBAAgB,EAAmB,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,OAAO,EAAI,aAAa,EAAE,YAAY,EAAE;IACzI,gBAAgB,EAAmB,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,QAAQ,EAAG,aAAa,EAAE,YAAY,EAAE;IAEzI,2DAA2D;IAC3D,4EAA4E;IAC5E,uBAAuB,EAAY,EAAE,UAAU,EAAE,OAAO,EAAG,WAAW,EAAE,KAAK,EAAI,cAAc,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE;IACzI,yBAAyB,EAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,UAAU,EAAC,aAAa,EAAE,YAAY,EAAE;IACzI,8BAA8B,EAAK,EAAE,UAAU,EAAE,OAAO,EAAG,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAI,aAAa,EAAE,YAAY,EAAE;IACzI,yBAAyB,EAAU,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,QAAQ,EAAG,aAAa,EAAE,YAAY,EAAE;IACzI,8BAA8B,EAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,UAAU,EAAC,aAAa,EAAE,YAAY,EAAE;IAEzI,2DAA2D;IAC3D,4DAA4D;IAC5D,mCAAmC,EAAQ,EAAE,UAAU,EAAE,KAAK,EAAG,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAG,aAAa,EAAE,YAAY,EAAE;IACrK,qCAAqC,EAAM,EAAE,UAAU,EAAE,KAAK,EAAG,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAG,aAAa,EAAE,YAAY,EAAE;IACrK,oCAAoC,EAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAI,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE;IACrK,qCAAqC,EAAM,EAAE,UAAU,EAAE,KAAK,EAAG,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,EAAG,aAAa,EAAE,YAAY,EAAE;IACrK,oCAAoC,EAAO,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,KAAK,EAAE,eAAe,EAAE,KAAK,EAAI,cAAc,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE;IAErK,2DAA2D;IAC3D,YAAY,EAAuB,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,aAAa,EAAE,YAAY,EAAE;IAC9G,YAAY,EAAuB,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,aAAa,EAAE,YAAY,EAAE;IAC9G,iBAAiB,EAAkB,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,MAAM,EAAG,aAAa,EAAE,YAAY,EAAE;IAE9G,2DAA2D;IAC3D,wBAAwB,EAAW,EAAE,UAAU,EAAE,OAAO,EAAG,WAAW,EAAE,MAAM,EAAG,cAAc,EAAE,OAAO,EAAI,aAAa,EAAE,YAAY,EAAE;IACzI,4BAA4B,EAAO,EAAE,UAAU,EAAE,OAAO,EAAG,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,EAAI,aAAa,EAAE,YAAY,EAAE;IAEzI,2DAA2D;IAC3D,uBAAuB,EAAY,EAAE,UAAU,EAAE,KAAK,EAAK,WAAW,EAAE,KAAK,EAAI,aAAa,EAAE,YAAY,EAAE;IAC9G,wBAAwB,EAAW,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,KAAK,EAAI,aAAa,EAAE,YAAY,EAAE;IAC9G,uBAAuB,EAAY,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,MAAM,EAAG,aAAa,EAAE,YAAY,EAAE;IAE9G,2DAA2D;IAC3D,8BAA8B,EAAK,EAAE,UAAU,EAAE,OAAO,EAAG,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE;IAC9G,2BAA2B,EAAQ,EAAE,UAAU,EAAE,OAAO,EAAG,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,YAAY,EAAE;IAE9G,2DAA2D;IAC3D,kBAAkB,EAAiB,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,IAAI,EAAK,aAAa,EAAE,YAAY,EAAE;IAC9G,uBAAuB,EAAY,EAAE,UAAU,EAAE,MAAM,EAAI,WAAW,EAAE,IAAI,EAAK,aAAa,EAAE,YAAY,EAAE;IAC9G,kBAAkB,EAAiB,EAAE,UAAU,EAAE,OAAO,EAAG,WAAW,EAAE,MAAM,EAAG,aAAa,EAAE,YAAY,EAAE;CAC/G,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,YAAY,CAC1B,KAAa,EACb,YAAoB,EACpB,gBAAwB,EACxB,UAA2C,YAAY;IAEvD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,IAAI,CAAC,IAAI;QAAE,OAAO,CAAC,CAAA;IACnB,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,UAAU,GAAG,gBAAgB,GAAG,IAAI,CAAC,WAAW,CAAC,GAAG,IAAI,CAAA;AACtF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CACrC,KAAa,EACb,UAA2C,YAAY;IAEvD,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IAC3B,IAAI,CAAC,IAAI;QAAE,MAAM,IAAI,wBAAwB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;IAC7D,OAAO,IAAI,CAAA;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,wBAAyB,SAAQ,KAAK;IACxC,KAAK,CAAQ;IACb,YAAY,CAAe;IAEpC,YAAY,KAAa,EAAE,OAAwC;QACjE,MAAM,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAA;QACtC,MAAM,YAAY,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,aAAa,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;QAC7E,MAAM,YAAY,GAAG,YAAY,CAAC,CAAC,CAAC,sBAAsB,YAAY,GAAG,CAAC,CAAC,CAAC,EAAE,CAAA;QAC9E,KAAK,CACH,6CAA6C,KAAK,IAAI,YAAY,IAAI;YACtE,+DAA+D;YAC/D,yDAAyD,KAAK,oDAAoD,CACnH,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAA;QACtC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAClB,IAAI,CAAC,YAAY,GAAG,YAAY,CAAA;IAClC,CAAC;CACF;AAED;;;;;GAKG;AACH,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACnC,MAAM,CAAQ;IACd,MAAM,CAAqB;IAC3B,KAAK,CAAQ;IACb,GAAG,CAAQ;IAEpB,YAAY,IAAiF;QAC3F,KAAK,CACH,iBAAiB,IAAI,CAAC,MAAM,eAAe,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,sBAAsB,IAAI,CAAC,MAAM,GAAG;YAClG,WAAW,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CACrC,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QACzB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAA;QACvB,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,GAAG,CAAA;IACrB,CAAC;CACF"}

package/dist/budget/storage.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Persistence contract for `withBudget(...)` middleware (#A6 Phase 3).
+ *
+ * Apps configure a `BudgetStorage` instance — the middleware calls
+ * `checkAndDebit()` once before each request (estimated input cost) and
+ * once per `usage` chunk (actual output cost). The storage is responsible
+ * for atomic increment + cap enforcement.
+ *
+ * # Atomicity
+ *
+ * `checkAndDebit` MUST be atomic: a concurrent caller cannot observe a
+ * stale `spent` value between the read and the write. Otherwise two
+ * requests both pass the check before either debits, and a user can
+ * exceed their cap by `costUsd × concurrency`.
+ *
+ * Implementations:
+ * - `memoryBudgetStorage()` — single-process Map; atomic because we never
+ *   `await` between the read and the write.
+ * - `ormBudgetStorage()` (Phase 4) — uses `UPDATE … RETURNING` (Postgres)
+ *   or row-level `SELECT … FOR UPDATE` (MySQL/SQLite) to keep the read +
+ *   write in a single transaction.
+ * - Redis / Cache impls — would use `INCRBY` + a `EXPIRE`, treating the
+ *   counter as authoritative.
+ *
+ * # Period semantics
+ *
+ * `daily` rolls at the user's local midnight when `timezone` is provided
+ * (IANA name, e.g. `'America/New_York'`); UTC otherwise. `monthly` rolls
+ * on the calendar-month boundary in the same TZ. Phase 2 does not
+ * implement rolling-30-days windows — adds storage complexity for marginal
+ * value.
+ */
+export type BudgetPeriod = 'daily' | 'monthly';
+export interface BudgetCheckOptions {
+    /** Identifier for the budget owner (typically a user id). */
+    userId: string;
+    /** Which cap to check against. */
+    period: BudgetPeriod;
+    /** Cap in USD. Caller resolves `budget()` once per request. */
+    cap: number;
+    /** Cost to debit in USD. Pass `0` to read the current spent value without mutating. */
+    costUsd: number;
+    /** Override the clock — useful for tests + period-rollover assertions. */
+    now?: Date;
+    /** IANA timezone for period boundaries. Defaults to UTC. */
+    timezone?: string;
+}
+export interface BudgetCheckResult {
+    /** True when the debit was applied; false when it would have exceeded `cap`. */
+    allowed: boolean;
+    /**
+     * Current spend for the period.
+     *
+     * - When `allowed: true`, this is the value AFTER the debit (i.e.
+     *   includes `costUsd`).
+     * - When `allowed: false`, this is the value BEFORE the rejected debit
+     *   (i.e. the prior `spent`). This matches the value `BudgetExceededError`
+     *   should report — the user spent `spent`, the cap was `cap`, the
+     *   request would have pushed past.
+     */
+    spent: number;
+    /** The cap passed in `BudgetCheckOptions.cap`, echoed for caller convenience. */
+    cap: number;
+}
+export interface BudgetStorage {
+    /**
+     * Atomically read the current `spent` value, add `costUsd` if the result
+     * stays within `cap`, and return the outcome.
+     *
+     * Pass `costUsd: 0` for a pure read (e.g. for a "you've spent $X today"
+     * status display) — the result reflects current spend without mutating.
+     */
+    checkAndDebit(opts: BudgetCheckOptions): Promise<BudgetCheckResult>;
+    /**
+     * Reset the budget counter for `(userId, period)` at the period
+     * containing `now` (or "now" by clock). Useful for tests and admin
+     * overrides; not required by the middleware.
+     */
+    reset?(userId: string, period: BudgetPeriod, now?: Date, timezone?: string): Promise<void>;
+}
+/**
+ * Format a `Date` as the bucket key for a billing period.
+ *
+ * - `daily`   → `YYYY-MM-DD` in the given timezone (or UTC)
+ * - `monthly` → `YYYY-MM` in the given timezone (or UTC)
+ *
+ * Used by `memoryBudgetStorage` and `ormBudgetStorage` (Phase 4) to
+ * partition the counter by billing window. Exposed publicly so apps
+ * computing per-period totals outside the middleware (admin dashboards,
+ * tests) get the same bucketing.
+ */
+export declare function periodKey(period: BudgetPeriod, now: Date, timezone?: string): string;
+/**
+ * In-process `BudgetStorage` backed by a `Map`. Suitable for tests and
+ * single-process dev servers.
+ *
+ * **Cross-process caveat:** counters live in process-local memory, so
+ * queue workers (or any second process) see their own copy. For any app
+ * with workers or horizontal scaling, use `ormBudgetStorage()` (Phase 4)
+ * or a Redis-backed storage. Use `memoryBudgetStorage()` only when you're
+ * sure all budget-relevant code paths run in the same Node process.
+ */
+export declare function memoryBudgetStorage(): BudgetStorage;
+//# sourceMappingURL=storage.d.ts.map

package/dist/budget/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../src/budget/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,GAAG,SAAS,CAAA;AAE9C,MAAM,WAAW,kBAAkB;IACjC,6DAA6D;IAC7D,MAAM,EAAK,MAAM,CAAA;IACjB,kCAAkC;IAClC,MAAM,EAAK,YAAY,CAAA;IACvB,+DAA+D;IAC/D,GAAG,EAAQ,MAAM,CAAA;IACjB,uFAAuF;IACvF,OAAO,EAAI,MAAM,CAAA;IACjB,0EAA0E;IAC1E,GAAG,CAAC,EAAO,IAAI,CAAA;IACf,4DAA4D;IAC5D,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,gFAAgF;IAChF,OAAO,EAAE,OAAO,CAAA;IAChB;;;;;;;;;OASG;IACH,KAAK,EAAE,MAAM,CAAA;IACb,iFAAiF;IACjF,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,aAAa;IAC5B;;;;;;OAMG;IACH,aAAa,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAEnE;;;;OAIG;IACH,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,YAAY,EAAE,GAAG,CAAC,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC3F;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,IAAI,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAUpF;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,IAAI,aAAa,CAgCnD"}

package/dist/budget/storage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.js","sourceRoot":"","sources":["../../src/budget/storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAuDH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS,CAAC,MAAoB,EAAE,GAAS,EAAE,QAAiB;IAC1E,kEAAkE;IAClE,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,cAAc,CAAC,OAAO,EAAE;QAC3C,QAAQ,EAAE,QAAQ,IAAI,KAAK;QAC3B,IAAI,EAAG,SAAS;QAChB,KAAK,EAAE,SAAS;QAChB,GAAG,EAAI,SAAS;KACjB,CAAC,CAAA;IACF,MAAM,GAAG,GAAG,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAA,CAAC,eAAe;IAC3C,OAAO,MAAM,KAAK,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAA,CAAC,YAAY;AAChE,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB;IACjC,kEAAkE;IAClE,8DAA8D;IAC9D,MAAM,IAAI,GAAG,IAAI,GAAG,EAAkB,CAAA;IACtC,MAAM,GAAG,GAAG,CAAC,MAAc,EAAE,MAAoB,EAAE,GAAS,EAAE,EAAW,EAAU,EAAE,CACnF,GAAG,MAAM,IAAI,MAAM,IAAI,SAAS,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,CAAC,EAAE,CAAA;IAErD,OAAO;QACL,sEAAsE;QACtE,sEAAsE;QACtE,yEAAyE;QACzE,sEAAsE;QACtE,gEAAgE;QAChE,aAAa;QACb,KAAK,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE,EAAE,QAAQ,EAAE;YAC9E,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,GAAG,GAAG,CAAC;gBAAU,MAAM,IAAI,KAAK,CAAC,8EAA8E,GAAG,EAAE,CAAC,CAAA;YAClJ,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,IAAI,OAAO,GAAG,CAAC;gBAAE,MAAM,IAAI,KAAK,CAAC,kFAAkF,OAAO,EAAE,CAAC,CAAA;YAE1J,MAAM,CAAC,GAAG,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAA;YAC5C,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;YAChC,MAAM,SAAS,GAAG,OAAO,GAAG,OAAO,CAAA;YACnC,IAAI,SAAS,GAAG,GAAG,EAAE,CAAC;gBACpB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,CAAA;YAChD,CAAC;YACD,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,SAAS,CAAC,CAAA;YACtB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,CAAA;QACjD,CAAC;QAED,KAAK,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,GAAG,IAAI,IAAI,EAAE,EAAE,QAAQ;YACpD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAA;QACjD,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/budget/with-budget.d.ts

@@ -0,0 +1,119 @@
+import type { AiMiddleware, MiddlewareContext } from '../types.js';
+import { type ModelPriceEntry } from './pricing.js';
+import type { BudgetPeriod, BudgetStorage } from './storage.js';
+/**
+ * Per-period caps in USD. Either or both can be set; periods with `null`
+ * / `undefined` are not enforced.
+ */
+export interface BudgetCaps {
+    daily?: number | null;
+    monthly?: number | null;
+}
+export interface BudgetExceededArgs {
+    userId: string;
+    period: BudgetPeriod;
+    /** Spend recorded BEFORE the rejected debit. */
+    spent: number;
+    cap: number;
+    ctx: MiddlewareContext;
+}
+export interface WithBudgetOptions {
+    /**
+     * Resolves the user identifier for a given request. Return `null` (or
+     * `undefined`) to bypass budget enforcement entirely — useful for
+     * unauthenticated paths or admin tooling.
+     *
+     * Async return supported.
+     */
+    user(ctx: MiddlewareContext): string | null | undefined | Promise<string | null | undefined>;
+    /**
+     * USD caps for the resolved user. Called once per request (per agent
+     * step, more precisely). Caps may be set per-tier / per-plan by reading
+     * the user from your DB inside the callback.
+     */
+    budget(args: {
+        userId: string;
+        ctx: MiddlewareContext;
+    }): BudgetCaps | Promise<BudgetCaps>;
+    /**
+     * Where counters persist. Use {@link memoryBudgetStorage} for tests +
+     * single-process dev; `ormBudgetStorage` (#A6 Phase 4) for production.
+     */
+    storage: BudgetStorage;
+    /**
+     * Pricing catalog. Defaults to the shipped {@link ModelPricing}; spread
+     * to override entries for negotiated rates:
+     *
+     * ```ts
+     * pricing: { ...ModelPricing, 'anthropic/claude-opus-4-7': { ... } }
+     * ```
+     */
+    pricing?: Record<string, ModelPriceEntry>;
+    /**
+     * Called when a debit would exceed a cap. Default throws
+     * {@link BudgetExceededError}; supply your own to log/alert before
+     * throwing, or to throw a different error class. Must throw — return
+     * value is ignored. The throw aborts the agent run before the model
+     * call.
+     */
+    onExceeded?(args: BudgetExceededArgs): never | Promise<never>;
+    /**
+     * IANA timezone for daily / monthly period rollover. Defaults to UTC.
+     * Use the user's tz to roll caps at user-local midnight (matches
+     * billing dashboards).
+     */
+    timezone?: string;
+    /**
+     * Approximate-tokens estimator used for the pre-debit. Defaults to
+     * `Math.ceil(text.length / 4)` — fine for English-heavy prompts. Pass
+     * a tiktoken-backed estimator for accuracy.
+     */
+    estimateTokens?: (text: string) => number;
+}
+/**
+ * Per-user spend cap middleware (#A6 Phase 3).
+ *
+ * Pre-debits an input-cost estimate before each provider call (refusing
+ * with {@link BudgetExceededError} if the user would exceed any
+ * configured cap), then debits the actual cost difference once the
+ * `usage` chunk arrives.
+ *
+ * The pre-debit reserves budget so two concurrent requests can't both
+ * pass the check before either is billed — the `BudgetStorage` contract
+ * (#A6 Phase 2) requires `checkAndDebit` to be atomic.
+ *
+ * # Example
+ *
+ * ```ts
+ * import { withBudget, memoryBudgetStorage, ModelPricing } from '@rudderjs/ai'
+ *
+ * const budgeted = withBudget({
+ *   user:    (ctx) => ctx.context as string,        // your app's user-id source
+ *   budget:  () => ({ daily: 0.50, monthly: 10 }),  // USD
+ *   storage: memoryBudgetStorage(),
+ *   pricing: ModelPricing,
+ * })
+ *
+ * class MyAgent extends Agent {
+ *   middleware() { return [budgeted] }
+ * }
+ * ```
+ *
+ * # Caveats
+ *
+ * - **Refunds on errors are not issued.** If the provider call fails
+ *   after the pre-debit, the estimate stays debited. This avoids the
+ *   complexity of distinguishing partial-credit cases (the model may
+ *   have produced output before erroring). Apps that need refund-on-error
+ *   should subscribe via `onError` and call `storage` directly.
+ * - **Cache token deltas not counted.** `TokenUsage` does not yet expose
+ *   `cacheReadInputTokens` / `cacheWriteInputTokens`; cached requests are
+ *   billed at the full `inputPer1k` rate today. Refining this is a phase
+ *   3.x follow-up that needs a `TokenUsage` widening.
+ * - **Tokenizer differences.** The default token estimator is
+ *   `text.length / 4`. Provider-reported `usage.promptTokens` may differ
+ *   by a few percent. Pass `estimateTokens: …` for a tiktoken-accurate
+ *   pre-debit if your caps are tight.
+ */
+export declare function withBudget(opts: WithBudgetOptions): AiMiddleware;
+//# sourceMappingURL=with-budget.d.ts.map

package/dist/budget/with-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"with-budget.d.ts","sourceRoot":"","sources":["../../src/budget/with-budget.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAEV,YAAY,EAEZ,iBAAiB,EAClB,MAAM,aAAa,CAAA;AACpB,OAAO,EAIL,KAAK,eAAe,EACrB,MAAM,cAAc,CAAA;AACrB,OAAO,KAAK,EACV,YAAY,EACZ,aAAa,EACd,MAAM,cAAc,CAAA;AAErB;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAI,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CACxB;AAED,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,YAAY,CAAA;IACpB,gDAAgD;IAChD,KAAK,EAAG,MAAM,CAAA;IACd,GAAG,EAAK,MAAM,CAAA;IACd,GAAG,EAAK,iBAAiB,CAAA;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,IAAI,CAAC,GAAG,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAA;IAE5F;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,iBAAiB,CAAA;KAAE,GAAG,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAAA;IAE1F;;;OAGG;IACH,OAAO,EAAE,aAAa,CAAA;IAEtB;;;;;;;OAOG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IAEzC;;;;;;OAMG;IACH,UAAU,CAAC,CAAC,IAAI,EAAE,kBAAkB,GAAG,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,CAAA;IAE7D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;OAIG;IACH,cAAc,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAA;CAC1C;AAgBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,YAAY,CAmGhE"}