@convex-dev/ai-budget 0.0.2-alpha.4 → 0.0.2-alpha.5

package/README.md

@@ -26,7 +26,11 @@ full audit log you can replay later.
 | **Usage & cost tracking** | Every request stored with messages, response, tokens, latency, and per-request cost. |
 | **Attribution** | Each call is attributed to a `userId` **and** to the Convex action that made it — auto-detected via `ctx.meta`, no manual tagging. Running totals per user and per action. |
 | **Tagged budgets** | `user` and `action` are just built-in *dimensions* — add your own (team, project, customer, env, feature…) by passing `tags`, and cap any of them with `ai.tag("customer").setLimits(...)`. One request can be billed to several buckets at once. |
-| **Spend & token limits** | Per-user daily / lifetime **spend** and **token** budgets, plus a requests-per-minute rate limit and a block switch. |
+| **Spend & token limits** | Per-bucket **daily / monthly / lifetime** spend and token budgets, plus a requests-per-minute rate limit, a max-concurrent cap, and a block switch. |
+| **Spend history** | Durable per-bucket **daily & monthly** rollups that survive request retention — real spend-over-time, "what did we spend last month," per user / action / tag. |
+| **Approaching-limit alerts** | Set `warnAtPct` (e.g. 0.8) and get an `onThreshold` callback before a cap is hit; `onLimitReached` fires when one blocks. |
+| **Manual credits/debits** | Comp a user or correct an overcharge with a signed adjustment; the change hits the live windows, the history, and an audit log. |
+| **Cache-aware cost** | Cached (prompt-cache-read) tokens are billed at a discount using the gateway's real cached-token count — not the full input rate. |
 | **Concurrency-safe caps** | A reserve-then-settle design makes admission a true atomic check — concurrent in-flight requests can't blow past the cap (a naive implementation overshoots ~40×). |
 | **Hard or soft** | Each limit either **blocks** (`hard`) or **allows-with-a-warning** (`soft`). |
 | **Per-feature budgets** | Cap or block a whole action (e.g. `summarize`) independently of any user. |
@@ -186,16 +190,21 @@ to the original. `lineage` walks the re-run chain in both directions.
 ai.users.setLimits(ctx, {
   userId,
   requestsPerMinute?,
+  maxConcurrent?,            // max in-flight requests at once
   dailySpendLimitNanos?,
+  monthlySpendLimitNanos?,   // calendar-month budget (UTC)
   lifetimeSpendLimitNanos?,
   dailyTokenLimit?,
+  monthlyTokenLimit?,
   lifetimeTokenLimit?,
-  enforcement?,       // "hard" (block, default) | "soft" (warn but allow)
-  blocked?,           // hard block on/off
+  warnAtPct?,                // e.g. 0.8 → fire onThreshold at 80% of a cap
+  enforcement?,             // "hard" (block, default) | "soft" (warn but allow)
+  blocked?,                 // hard block on/off
 })
 ai.users.delete(ctx, { userId })   // remove a user and all their request rows
 ```
 
+The same limit fields apply to `ai.actions.setLimits` and `ai.tag(d).setLimits`.
 Pass a field as `undefined` to clear that limit (unlimited).
 
 ### Per-action budgets
@@ -246,6 +255,48 @@ Uncapped buckets never serialize, so adding tags you don't cap is free at
 admission; their running totals still accrue for reporting. `ai.users.*` and
 `ai.actions.*` are simply sugar over `ai.tag("user")` / `ai.tag("action")`.
 
+Every dimension namespace (`users`, `actions`, `tag(d)`) shares the same methods:
+`list`, `get`, `setLimits`, `bump`, `adjust`, `history`, `adjustments`, `delete`.
+
+### Spend history (survives retention)
+
+Request rows are retained only briefly (see retention), but **durable per-bucket
+day/month rollups are not** — so charts and "what did we spend last month" keep
+working:
+
+```ts
+await ai.users.history(ctx, { userId, period: "month" });  // [{ stamp, spendNanos, tokens, requests }]
+await ai.tag("customer").history(ctx, { value: "acme", period: "day", limit: 30 });
+```
+
+### Approaching-limit alerts
+
+Set a threshold (per bucket via `warnAtPct`, or a deployment default) and get a
+callback before a cap is hit — plus one when a hard cap blocks:
+
+```ts
+await ai.global.setAlertDefaults(ctx, { warnAtPct: 0.8 });   // 80%, all buckets
+await ai.users.setLimits(ctx, { userId, warnAtPct: 0.9 });   // override per bucket
+
+new AIBudget(components.aiBudget, {
+  onThreshold:    ({ userId, messages }) => notify(userId, messages),  // approaching
+  onLimitReached: ({ userId, reason })   => notify(userId, reason),    // blocked
+  onSoftLimit:    ({ userId, messages }) => notify(userId, messages),  // soft-cap exceeded
+});
+```
+
+`chat()` also returns `notices` (approaching) alongside `warnings` (soft-exceeded).
+
+### Manual credits & debits
+
+Comp a user or correct an overcharge. Negative = credit, positive = extra charge;
+it adjusts the live day/month/lifetime windows, the history, and an audit log:
+
+```ts
+await ai.users.adjust(ctx, { userId, deltaNanos: -5 * 1_000_000_000, reason: "goodwill" });
+await ai.users.adjustments(ctx, { userId });   // the audit log
+```
+
 ### Global (deployment-wide) budget
 
 ```ts
@@ -283,10 +334,18 @@ common models (validated against OpenRouter's public pricing); override or add
 any model:
 
 ```ts
-ai.prices.set(ctx, { model, inputNanosPerMTok, outputNanosPerMTok })  // must be ≥ 0
+ai.prices.set(ctx, { model, inputNanosPerMTok, outputNanosPerMTok, cachedNanosPerMTok? })  // ≥ 0
 ai.prices.list(ctx)
 ```
 
+**Cached tokens & actual cost.** The gateway reports a real cached-token count
+(`usage.inputTokenDetails.cacheReadTokens`), so the cached slice of a prompt is
+billed at `cachedNanosPerMTok` (or a default 10%-of-input discount) instead of
+the full input rate. The gateway does **not** currently return a dollar cost, so
+cost is computed from tokens — but `finishRequest` accepts an authoritative
+`costNanos` and prefers it whenever present, so adopting a real gateway cost is a
+one-line change the day it's available.
+
 **Real prices from an API.** The gateway's `provider/model` ids match
 OpenRouter's, whose public models endpoint returns per-token pricing — so you can
 keep prices current from your own action (this is app code; the component just
@@ -311,10 +370,12 @@ flagged `unpricedModel: true` so you know to add a real price.
 ### Observability
 
 ```ts
-ai.users.list(ctx)                      // per-user spend today / total / tokens / limits
+ai.users.list(ctx)                      // per-user spend today / month / total / limits
 ai.actions.list(ctx)                    // per-action spend & totals
 ai.tag("customer").list(ctx)            // spend & caps for any custom dimension
-ai.requests.list(ctx, { userId?, limit? })  // the audit log (blocked attempts included)
+ai.users.history(ctx, { userId, period: "month" })   // durable spend-over-time
+ai.requests.list(ctx, { userId?, limit? })           // the audit log (blocked included)
+ai.requests.list(ctx, { dimension: "customer", value: "acme" })  // filter the log by any tag
 ```
 
 ---

package/dist/client/index.d.ts

@@ -21,22 +21,34 @@ export type Tag = {
     dimension: string;
     value: string;
 };
-/** Fired when a request is admitted over a *soft* limit. */
-export type SoftLimitInfo = {
+/** Common shape for budget-event callbacks. */
+export type BudgetEventInfo = {
     userId: string;
     action?: string;
     tags?: Tag[];
-    requestId: string;
+    requestId?: string;
+    /** soft-cap warnings (onSoftLimit) or approaching-cap notices (onThreshold). */
+    messages: string[];
+    /** rejection code/reason (onLimitReached only). */
+    code?: string;
+    reason?: string;
+};
+/** @deprecated use BudgetEventInfo */
+export type SoftLimitInfo = BudgetEventInfo & {
     warnings: string[];
 };
 export type AIBudgetOptions = {
     defaultModel?: string;
     /**
-     * Called when a soft limit is exceeded (the request is still allowed). Lets
-     * you surface budget warnings even on the languageModel/Agent path, where
-     * they can't be returned. Errors thrown here are swallowed.
+     * A *soft* limit was exceeded (request still allowed). Lets you surface budget
+     * warnings even on the languageModel/Agent path where they can't be returned.
+     * Errors thrown in any of these callbacks are swallowed.
      */
     onSoftLimit?: (info: SoftLimitInfo) => void | Promise<void>;
+    /** Usage crossed a bucket's warnAtPct threshold (approaching a cap). */
+    onThreshold?: (info: BudgetEventInfo) => void | Promise<void>;
+    /** A *hard* limit blocked the request (fires just before chat/model throws). */
+    onLimitReached?: (info: BudgetEventInfo) => void | Promise<void>;
 };
 type RunQueryCtx = {
     runQuery: <Query extends FunctionReference<"query", "internal">>(query: Query, args: Query["_args"]) => Promise<Query["_returnType"]>;
@@ -67,13 +79,39 @@ export type ChatResult = {
     cachedTokens: number;
     /** Soft-limit warnings raised at admission (empty unless a soft cap was hit). */
     warnings: string[];
+    /** Approaching-cap notices (empty unless a warnAtPct threshold was crossed). */
+    notices: string[];
+};
+/** Limits/controls settable on any budget bucket (user, action, or tag). */
+export type BucketLimits = {
+    requestsPerMinute?: number;
+    maxConcurrent?: number;
+    dailySpendLimitNanos?: number;
+    monthlySpendLimitNanos?: number;
+    lifetimeSpendLimitNanos?: number;
+    dailyTokenLimit?: number;
+    monthlyTokenLimit?: number;
+    lifetimeTokenLimit?: number;
+    /** Fire an approaching-limit alert at this fraction of a cap (e.g. 0.8). */
+    warnAtPct?: number;
+    enforcement?: "hard" | "soft";
+    blocked?: boolean;
+};
+/** One-time bump amounts, added on top of a standing cap. */
+export type BumpArgs = {
+    dailyNanos?: number;
+    monthlyNanos?: number;
+    lifetimeNanos?: number;
 };
 export declare class AIBudget {
     component: AIBudgetApi;
     defaultModel: string;
     private onSoftLimit?;
+    private onThreshold?;
+    private onLimitReached?;
     constructor(component: AIBudgetApi, options?: AIBudgetOptions);
-    private fireSoftLimit;
+    private fireBudgetEvents;
+    private fireLimitReached;
     /**
      * One-shot chat through the AI Gateway with tracking + limits.
      * Call from an action. `userId` defaults to the authenticated caller.
@@ -106,8 +144,11 @@ export declare class AIBudget {
     private rerunImpl;
     /** The request audit log, replay, and re-run lineage. */
     get requests(): {
+        /** Filter by userId, or by any {dimension, value} (incl. custom tags). */
         list: (ctx: RunQueryCtx, args?: {
             userId?: string;
+            dimension?: string;
+            value?: string;
             limit?: number;
         }) => Promise<{
             _id: string;
@@ -213,8 +254,8 @@ export declare class AIBudget {
      * generalization of `users`/`actions`. Give it any dimension name (team,
      * project, tenant, customer, env, feature, …) and set caps per value:
      *
-     *   ai.tag("customer").setLimits(ctx, { value: "acme", dailySpendLimitNanos });
-     *   ai.tag("customer").list(ctx);
+     *   ai.tag("customer").setLimits(ctx, { value: "acme", monthlySpendLimitNanos });
+     *   ai.tag("customer").history(ctx, { value: "acme", period: "day" });
      *
      * Attribute a call to it by passing `tags` to `chat`/`languageModel`.
      */
@@ -222,22 +263,33 @@ export declare class AIBudget {
         /** All buckets in this dimension. */
         list: (ctx: RunQueryCtx) => Promise<{
             spendTodayNanos: number;
+            spendThisMonthNanos: number;
             _id: string;
             _creationTime: number;
             requestsPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
             dailySpendLimitNanos?: number | undefined;
+            monthlySpendLimitNanos?: number | undefined;
             lifetimeSpendLimitNanos?: number | undefined;
             dailyTokenLimit?: number | undefined;
+            monthlyTokenLimit?: number | undefined;
             lifetimeTokenLimit?: number | undefined;
             blocked?: boolean | undefined;
+            warnAtPct?: number | undefined;
             enforcement?: "hard" | "soft" | undefined;
             dailyBumpNanos?: number | undefined;
+            monthlyBumpNanos?: number | undefined;
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
+            bumpMonthStamp?: string | undefined;
             tokensToday?: number | undefined;
+            monthStamp?: string | undefined;
+            tokensThisMonth?: number | undefined;
             reservedTodayNanos?: number | undefined;
+            reservedMonthNanos?: number | undefined;
             reservedTotalNanos?: number | undefined;
             reservedTodayTokens?: number | undefined;
+            reservedMonthTokens?: number | undefined;
             reservedTotalTokens?: number | undefined;
             pendingCount?: number | undefined;
             dimension: string;
@@ -252,22 +304,33 @@ export declare class AIBudget {
             value: string;
         }) => Promise<{
             spendTodayNanos: number;
+            spendThisMonthNanos: number;
             _id: string;
             _creationTime: number;
             requestsPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
             dailySpendLimitNanos?: number | undefined;
+            monthlySpendLimitNanos?: number | undefined;
             lifetimeSpendLimitNanos?: number | undefined;
             dailyTokenLimit?: number | undefined;
+            monthlyTokenLimit?: number | undefined;
             lifetimeTokenLimit?: number | undefined;
             blocked?: boolean | undefined;
+            warnAtPct?: number | undefined;
             enforcement?: "hard" | "soft" | undefined;
             dailyBumpNanos?: number | undefined;
+            monthlyBumpNanos?: number | undefined;
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
+            bumpMonthStamp?: string | undefined;
             tokensToday?: number | undefined;
+            monthStamp?: string | undefined;
+            tokensThisMonth?: number | undefined;
             reservedTodayNanos?: number | undefined;
+            reservedMonthNanos?: number | undefined;
             reservedTotalNanos?: number | undefined;
             reservedTodayTokens?: number | undefined;
+            reservedMonthTokens?: number | undefined;
             reservedTotalTokens?: number | undefined;
             pendingCount?: number | undefined;
             dimension: string;
@@ -279,20 +342,50 @@ export declare class AIBudget {
         } | null>;
         setLimits: (ctx: RunMutationCtx, args: {
             value: string;
-            requestsPerMinute?: number;
-            dailySpendLimitNanos?: number;
-            lifetimeSpendLimitNanos?: number;
-            dailyTokenLimit?: number;
-            lifetimeTokenLimit?: number;
-            enforcement?: "hard" | "soft";
-            blocked?: boolean;
-        }) => Promise<null>;
-        /** One-time "approve another $X" bump (daily is today-only). */
+        } & BucketLimits) => Promise<null>;
+        /** One-time "approve another $X" bump (daily/monthly reset with the window). */
         bump: (ctx: RunMutationCtx, args: {
             value: string;
-            dailyNanos?: number;
-            lifetimeNanos?: number;
+        } & BumpArgs) => Promise<null>;
+        /** Manually credit (negative) or debit (positive) this bucket. */
+        adjust: (ctx: RunMutationCtx, args: {
+            value: string;
+        } & {
+            deltaNanos: number;
+            tokens?: number;
+            reason?: string;
         }) => Promise<null>;
+        /** Durable spend history for this bucket (per day or per month). */
+        history: (ctx: RunQueryCtx, args: {
+            value: string;
+        } & {
+            period?: "day" | "month";
+            limit?: number;
+        }) => Promise<{
+            _id: string;
+            _creationTime: number;
+            dimension: string;
+            value: string;
+            period: "day" | "month";
+            stamp: string;
+            spendNanos: number;
+            tokens: number;
+            requests: number;
+        }[]>;
+        /** Manual-adjustment audit log for this bucket. */
+        adjustments: (ctx: RunQueryCtx, args: {
+            value: string;
+        } & {
+            limit?: number;
+        }) => Promise<{
+            _id: string;
+            _creationTime: number;
+            tokens?: number | undefined;
+            reason?: string | undefined;
+            dimension: string;
+            value: string;
+            deltaNanos: number;
+        }[]>;
         /** Delete the bucket (for "user", also its request rows). */
         delete: (ctx: RunMutationCtx, args: {
             value: string;
@@ -301,26 +394,39 @@ export declare class AIBudget {
             done: boolean;
         }>;
     };
+    private dimensionApi;
     /** Per-user budgets and controls — sugar over the "user" dimension. */
     get users(): {
+        /** All buckets in this dimension. */
         list: (ctx: RunQueryCtx) => Promise<{
             spendTodayNanos: number;
+            spendThisMonthNanos: number;
             _id: string;
             _creationTime: number;
             requestsPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
             dailySpendLimitNanos?: number | undefined;
+            monthlySpendLimitNanos?: number | undefined;
             lifetimeSpendLimitNanos?: number | undefined;
             dailyTokenLimit?: number | undefined;
+            monthlyTokenLimit?: number | undefined;
             lifetimeTokenLimit?: number | undefined;
             blocked?: boolean | undefined;
+            warnAtPct?: number | undefined;
             enforcement?: "hard" | "soft" | undefined;
             dailyBumpNanos?: number | undefined;
+            monthlyBumpNanos?: number | undefined;
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
+            bumpMonthStamp?: string | undefined;
             tokensToday?: number | undefined;
+            monthStamp?: string | undefined;
+            tokensThisMonth?: number | undefined;
             reservedTodayNanos?: number | undefined;
+            reservedMonthNanos?: number | undefined;
             reservedTotalNanos?: number | undefined;
             reservedTodayTokens?: number | undefined;
+            reservedMonthTokens?: number | undefined;
             reservedTotalTokens?: number | undefined;
             pendingCount?: number | undefined;
             dimension: string;
@@ -330,23 +436,94 @@ export declare class AIBudget {
             totalTokens: number;
             dayStamp: string;
         }[]>;
+        /** One bucket's limits + spend (null if it has none yet). */
+        get: (ctx: RunQueryCtx, args: {
+            userId: string;
+        }) => Promise<{
+            spendTodayNanos: number;
+            spendThisMonthNanos: number;
+            _id: string;
+            _creationTime: number;
+            requestsPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
+            dailySpendLimitNanos?: number | undefined;
+            monthlySpendLimitNanos?: number | undefined;
+            lifetimeSpendLimitNanos?: number | undefined;
+            dailyTokenLimit?: number | undefined;
+            monthlyTokenLimit?: number | undefined;
+            lifetimeTokenLimit?: number | undefined;
+            blocked?: boolean | undefined;
+            warnAtPct?: number | undefined;
+            enforcement?: "hard" | "soft" | undefined;
+            dailyBumpNanos?: number | undefined;
+            monthlyBumpNanos?: number | undefined;
+            lifetimeBumpNanos?: number | undefined;
+            bumpDayStamp?: string | undefined;
+            bumpMonthStamp?: string | undefined;
+            tokensToday?: number | undefined;
+            monthStamp?: string | undefined;
+            tokensThisMonth?: number | undefined;
+            reservedTodayNanos?: number | undefined;
+            reservedMonthNanos?: number | undefined;
+            reservedTotalNanos?: number | undefined;
+            reservedTodayTokens?: number | undefined;
+            reservedMonthTokens?: number | undefined;
+            reservedTotalTokens?: number | undefined;
+            pendingCount?: number | undefined;
+            dimension: string;
+            value: string;
+            totalSpendNanos: number;
+            totalRequests: number;
+            totalTokens: number;
+            dayStamp: string;
+        } | null>;
         setLimits: (ctx: RunMutationCtx, args: {
             userId: string;
-            requestsPerMinute?: number;
-            dailySpendLimitNanos?: number;
-            lifetimeSpendLimitNanos?: number;
-            dailyTokenLimit?: number;
-            lifetimeTokenLimit?: number;
-            enforcement?: "hard" | "soft";
-            blocked?: boolean;
-        }) => Promise<null>;
-        /** One-time "approve another $X" bump (daily is today-only). */
+        } & BucketLimits) => Promise<null>;
+        /** One-time "approve another $X" bump (daily/monthly reset with the window). */
         bump: (ctx: RunMutationCtx, args: {
             userId: string;
-            dailyNanos?: number;
-            lifetimeNanos?: number;
+        } & BumpArgs) => Promise<null>;
+        /** Manually credit (negative) or debit (positive) this bucket. */
+        adjust: (ctx: RunMutationCtx, args: {
+            userId: string;
+        } & {
+            deltaNanos: number;
+            tokens?: number;
+            reason?: string;
         }) => Promise<null>;
-        /** Delete a user and all their request rows. */
+        /** Durable spend history for this bucket (per day or per month). */
+        history: (ctx: RunQueryCtx, args: {
+            userId: string;
+        } & {
+            period?: "day" | "month";
+            limit?: number;
+        }) => Promise<{
+            _id: string;
+            _creationTime: number;
+            dimension: string;
+            value: string;
+            period: "day" | "month";
+            stamp: string;
+            spendNanos: number;
+            tokens: number;
+            requests: number;
+        }[]>;
+        /** Manual-adjustment audit log for this bucket. */
+        adjustments: (ctx: RunQueryCtx, args: {
+            userId: string;
+        } & {
+            limit?: number;
+        }) => Promise<{
+            _id: string;
+            _creationTime: number;
+            tokens?: number | undefined;
+            reason?: string | undefined;
+            dimension: string;
+            value: string;
+            deltaNanos: number;
+        }[]>;
+        /** Delete the bucket (for "user", also its request rows). */
         delete: (ctx: RunMutationCtx, args: {
             userId: string;
         }) => Promise<{
@@ -356,24 +533,36 @@ export declare class AIBudget {
     };
     /** Per-action (per-feature) budgets — sugar over the "action" dimension. */
     get actions(): {
+        /** All buckets in this dimension. */
         list: (ctx: RunQueryCtx) => Promise<{
             spendTodayNanos: number;
+            spendThisMonthNanos: number;
             _id: string;
             _creationTime: number;
             requestsPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
             dailySpendLimitNanos?: number | undefined;
+            monthlySpendLimitNanos?: number | undefined;
             lifetimeSpendLimitNanos?: number | undefined;
             dailyTokenLimit?: number | undefined;
+            monthlyTokenLimit?: number | undefined;
             lifetimeTokenLimit?: number | undefined;
             blocked?: boolean | undefined;
+            warnAtPct?: number | undefined;
             enforcement?: "hard" | "soft" | undefined;
             dailyBumpNanos?: number | undefined;
+            monthlyBumpNanos?: number | undefined;
             lifetimeBumpNanos?: number | undefined;
             bumpDayStamp?: string | undefined;
+            bumpMonthStamp?: string | undefined;
             tokensToday?: number | undefined;
+            monthStamp?: string | undefined;
+            tokensThisMonth?: number | undefined;
             reservedTodayNanos?: number | undefined;
+            reservedMonthNanos?: number | undefined;
             reservedTotalNanos?: number | undefined;
             reservedTodayTokens?: number | undefined;
+            reservedMonthTokens?: number | undefined;
             reservedTotalTokens?: number | undefined;
             pendingCount?: number | undefined;
             dimension: string;
@@ -383,23 +572,102 @@ export declare class AIBudget {
             totalTokens: number;
             dayStamp: string;
         }[]>;
+        /** One bucket's limits + spend (null if it has none yet). */
+        get: (ctx: RunQueryCtx, args: {
+            name: string;
+        }) => Promise<{
+            spendTodayNanos: number;
+            spendThisMonthNanos: number;
+            _id: string;
+            _creationTime: number;
+            requestsPerMinute?: number | undefined;
+            maxConcurrent?: number | undefined;
+            dailySpendLimitNanos?: number | undefined;
+            monthlySpendLimitNanos?: number | undefined;
+            lifetimeSpendLimitNanos?: number | undefined;
+            dailyTokenLimit?: number | undefined;
+            monthlyTokenLimit?: number | undefined;
+            lifetimeTokenLimit?: number | undefined;
+            blocked?: boolean | undefined;
+            warnAtPct?: number | undefined;
+            enforcement?: "hard" | "soft" | undefined;
+            dailyBumpNanos?: number | undefined;
+            monthlyBumpNanos?: number | undefined;
+            lifetimeBumpNanos?: number | undefined;
+            bumpDayStamp?: string | undefined;
+            bumpMonthStamp?: string | undefined;
+            tokensToday?: number | undefined;
+            monthStamp?: string | undefined;
+            tokensThisMonth?: number | undefined;
+            reservedTodayNanos?: number | undefined;
+            reservedMonthNanos?: number | undefined;
+            reservedTotalNanos?: number | undefined;
+            reservedTodayTokens?: number | undefined;
+            reservedMonthTokens?: number | undefined;
+            reservedTotalTokens?: number | undefined;
+            pendingCount?: number | undefined;
+            dimension: string;
+            value: string;
+            totalSpendNanos: number;
+            totalRequests: number;
+            totalTokens: number;
+            dayStamp: string;
+        } | null>;
         setLimits: (ctx: RunMutationCtx, args: {
             name: string;
-            dailySpendLimitNanos?: number;
-            lifetimeSpendLimitNanos?: number;
-            dailyTokenLimit?: number;
-            lifetimeTokenLimit?: number;
-            enforcement?: "hard" | "soft";
-            /** Hard-block this action (was `disabled`). */
-            blocked?: boolean;
-        }) => Promise<null>;
+        } & BucketLimits) => Promise<null>;
+        /** One-time "approve another $X" bump (daily/monthly reset with the window). */
         bump: (ctx: RunMutationCtx, args: {
             name: string;
-            dailyNanos?: number;
-            lifetimeNanos?: number;
+        } & BumpArgs) => Promise<null>;
+        /** Manually credit (negative) or debit (positive) this bucket. */
+        adjust: (ctx: RunMutationCtx, args: {
+            name: string;
+        } & {
+            deltaNanos: number;
+            tokens?: number;
+            reason?: string;
         }) => Promise<null>;
+        /** Durable spend history for this bucket (per day or per month). */
+        history: (ctx: RunQueryCtx, args: {
+            name: string;
+        } & {
+            period?: "day" | "month";
+            limit?: number;
+        }) => Promise<{
+            _id: string;
+            _creationTime: number;
+            dimension: string;
+            value: string;
+            period: "day" | "month";
+            stamp: string;
+            spendNanos: number;
+            tokens: number;
+            requests: number;
+        }[]>;
+        /** Manual-adjustment audit log for this bucket. */
+        adjustments: (ctx: RunQueryCtx, args: {
+            name: string;
+        } & {
+            limit?: number;
+        }) => Promise<{
+            _id: string;
+            _creationTime: number;
+            tokens?: number | undefined;
+            reason?: string | undefined;
+            dimension: string;
+            value: string;
+            deltaNanos: number;
+        }[]>;
+        /** Delete the bucket (for "user", also its request rows). */
+        delete: (ctx: RunMutationCtx, args: {
+            name: string;
+        }) => Promise<{
+            deletedThisBatch: number;
+            done: boolean;
+        }>;
     };
-    /** The deployment-wide budget and retention config. */
+    /** The deployment-wide budget, alerts, and retention config. */
     get global(): {
         /** Limits + spend today/total. */
         status: (ctx: RunQueryCtx) => Promise<{
@@ -419,6 +687,10 @@ export declare class AIBudget {
             dailyNanos?: number;
             lifetimeNanos?: number;
         }) => Promise<null>;
+        /** Default approaching-limit alert threshold (fraction of a cap, e.g. 0.8). */
+        setAlertDefaults: (ctx: RunMutationCtx, args: {
+            warnAtPct?: number;
+        }) => Promise<null>;
         /** Request-row retention window in ms (default 1h; 0 disables). */
         setRetention: (ctx: RunMutationCtx, args: {
             retentionMs: number;
@@ -442,6 +714,7 @@ export declare class AIBudget {
             [x: string]: {
                 input: number;
                 output: number;
+                cached?: number | undefined;
                 overridden: boolean;
             };
         }>;
@@ -449,6 +722,8 @@ export declare class AIBudget {
             model: string;
             inputNanosPerMTok: number;
             outputNanosPerMTok: number;
+            /** Cache-read rate; defaults to a discount off input if omitted. */
+            cachedNanosPerMTok?: number;
         }) => Promise<null>;
     };
 }