@convex-dev/ai-budget 0.0.2-alpha.0 → 0.0.2-alpha.12

package/dist/client/index.d.ts

@@ -1,4 +1,4 @@
-import type { Expand, FunctionReference } from "convex/server";
+import { type Expand, type FunctionReference, type HttpRouter } from "convex/server";
 import { type GenericId } from "convex/values";
 import { type LanguageModel } from "ai";
 import type { api } from "../component/_generated/api";
@@ -11,21 +11,44 @@ type UseApi<API> = Expand<{
 export type AIBudgetApi = UseApi<typeof api>;
 /** @deprecated use AIBudgetApi */
 export type AIGatewayApi = AIBudgetApi;
-/** Fired when a request is admitted over a *soft* limit. */
-export type SoftLimitInfo = {
+/**
+ * One attribution tag: a (dimension, value) pair, e.g. {dimension:"customer",
+ * value:"acme"}. `user` and `action` are built-in dimensions (set via
+ * userId/action); use tags for anything else — team, project, tenant, env, ….
+ * Any tagged bucket can carry its own budget (see `ai.tag(dimension)`).
+ */
+export type Tag = {
+    dimension: string;
+    value: string;
+};
+/** Common shape for budget-event callbacks. */
+export type BudgetEventInfo = {
     userId: string;
     action?: string;
-    requestId: string;
+    tags?: Tag[];
+    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"]>;
@@ -56,16 +79,69 @@ 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;
+    /**
+     * Meter ANY LLM call — gateway, a provider SDK, a raw fetch — with the same
+     * budgets, audit log, and cost tracking. Reserves before your `run` (throwing
+     * a ConvexError over a hard cap), runs it, then records the actual usage/cost.
+     * This is the provider-agnostic core; `chat` is sugar over it for the gateway.
+     *
+     * `run` returns what happened. Pass a raw provider `usage` object (auto-
+     * normalized) OR explicit `promptTokens`/`completionTokens`/`cachedTokens`,
+     * plus optional `serverToolUses` (e.g. `{ web_search: 3 }`, priced on top of
+     * tokens) and an authoritative `costNanos` (used verbatim if present).
+     */
+    meter(ctx: RunMutationCtx, opts: {
+        model: string;
+        messages: Message[];
+        userId?: string;
+        action?: string;
+        tags?: Tag[];
+        rerunOf?: string;
+    }, run: () => Promise<{
+        text?: string;
+        usage?: any;
+        promptTokens?: number;
+        completionTokens?: number;
+        cachedTokens?: number;
+        serverToolUses?: Record<string, number>;
+        costNanos?: number;
+    }>): Promise<ChatResult>;
     /**
-     * One-shot chat through the AI Gateway with tracking + limits.
-     * Call from an action. `userId` defaults to the authenticated caller.
+     * One-shot chat through the AI Gateway with tracking + limits — sugar over
+     * `meter`. Call from an action. `userId` defaults to the authenticated caller.
      */
     chat(ctx: RunMutationCtx, args?: {
         /** Whom to bill. Defaults to the authenticated user (ctx.auth). */
@@ -76,6 +152,8 @@ export declare class AIBudget {
         rerunOf?: string;
         /** Attribute spend to this action name. Defaults to the calling Convex action. */
         action?: string;
+        /** Extra attribution dimensions to bill/limit (team, customer, env, …). */
+        tags?: Tag[];
     }): Promise<ChatResult>;
     /**
      * An AI SDK LanguageModel that enforces limits and records usage/cost for
@@ -87,17 +165,26 @@ export declare class AIBudget {
         userId?: string;
         model?: string;
         action?: string;
+        /** Extra attribution dimensions to bill/limit (team, customer, env, …). */
+        tags?: Tag[];
     }): LanguageModel;
     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;
             _creationTime: number;
             actionName?: string | undefined;
+            tags?: {
+                dimension: string;
+                value: string;
+            }[] | undefined;
             estimatedNanos?: number | undefined;
             estimatedTokens?: number | undefined;
             unpricedModel?: boolean | undefined;
@@ -108,6 +195,9 @@ export declare class AIBudget {
             promptTokens?: number | undefined;
             completionTokens?: number | undefined;
             cachedTokens?: number | undefined;
+            serverToolUses?: {
+                [x: string]: number;
+            } | undefined;
             costNanos?: number | undefined;
             latencyMs?: number | undefined;
             rerunOf?: string | undefined;
@@ -119,6 +209,41 @@ export declare class AIBudget {
             }[];
             status: "blocked" | "pending" | "success" | "error";
         }[]>;
+        /** One request, including its stored prompt and response. */
+        get: (ctx: RunQueryCtx, args: {
+            requestId: string;
+        }) => Promise<{
+            _id: string;
+            _creationTime: number;
+            actionName?: string | undefined;
+            tags?: {
+                dimension: string;
+                value: string;
+            }[] | undefined;
+            estimatedNanos?: number | undefined;
+            estimatedTokens?: number | undefined;
+            unpricedModel?: boolean | undefined;
+            overBudget?: boolean | undefined;
+            settled?: boolean | undefined;
+            error?: string | undefined;
+            responseText?: string | undefined;
+            promptTokens?: number | undefined;
+            completionTokens?: number | undefined;
+            cachedTokens?: number | undefined;
+            serverToolUses?: {
+                [x: string]: number;
+            } | undefined;
+            costNanos?: number | undefined;
+            latencyMs?: number | undefined;
+            rerunOf?: string | undefined;
+            userId: string;
+            model: string;
+            messages: {
+                role: string;
+                content: string;
+            }[];
+            status: "blocked" | "pending" | "success" | "error";
+        } | null>;
         /** Ancestors up to the original, plus direct re-runs. */
         lineage: (ctx: RunQueryCtx, args: {
             requestId: string;
@@ -127,6 +252,10 @@ export declare class AIBudget {
                 _id: string;
                 _creationTime: number;
                 actionName?: string | undefined;
+                tags?: {
+                    dimension: string;
+                    value: string;
+                }[] | undefined;
                 estimatedNanos?: number | undefined;
                 estimatedTokens?: number | undefined;
                 unpricedModel?: boolean | undefined;
@@ -137,6 +266,9 @@ export declare class AIBudget {
                 promptTokens?: number | undefined;
                 completionTokens?: number | undefined;
                 cachedTokens?: number | undefined;
+                serverToolUses?: {
+                    [x: string]: number;
+                } | undefined;
                 costNanos?: number | undefined;
                 latencyMs?: number | undefined;
                 rerunOf?: string | undefined;
@@ -152,6 +284,10 @@ export declare class AIBudget {
                 _id: string;
                 _creationTime: number;
                 actionName?: string | undefined;
+                tags?: {
+                    dimension: string;
+                    value: string;
+                }[] | undefined;
                 estimatedNanos?: number | undefined;
                 estimatedTokens?: number | undefined;
                 unpricedModel?: boolean | undefined;
@@ -162,6 +298,9 @@ export declare class AIBudget {
                 promptTokens?: number | undefined;
                 completionTokens?: number | undefined;
                 cachedTokens?: number | undefined;
+                serverToolUses?: {
+                    [x: string]: number;
+                } | undefined;
                 costNanos?: number | undefined;
                 latencyMs?: number | undefined;
                 rerunOf?: string | undefined;
@@ -181,51 +320,281 @@ export declare class AIBudget {
             model?: string;
         }) => Promise<ChatResult>;
     };
-    /** Per-user budgets and controls. */
+    /**
+     * Budgets and controls for an arbitrary attribution dimension — the
+     * 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", monthlySpendLimitNanos });
+     *   ai.tag("customer").history(ctx, { value: "acme", period: "day" });
+     *
+     * Attribute a call to it by passing `tags` to `chat`/`languageModel`.
+     */
+    tag(dimension: string): {
+        /** 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;
+            value: string;
+            totalSpendNanos: number;
+            totalRequests: number;
+            totalTokens: number;
+            dayStamp: string;
+        }[]>;
+        /** One bucket's limits + spend (null if it has none yet). */
+        get: (ctx: RunQueryCtx, args: {
+            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;
+            value: string;
+            totalSpendNanos: number;
+            totalRequests: number;
+            totalTokens: number;
+            dayStamp: string;
+        } | null>;
+        setLimits: (ctx: RunMutationCtx, args: {
+            value: string;
+        } & BucketLimits) => Promise<null>;
+        /** One-time "approve another $X" bump (daily/monthly reset with the window). */
+        bump: (ctx: RunMutationCtx, args: {
+            value: string;
+        } & 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;
+        }) => Promise<{
+            deletedThisBatch: number;
+            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;
-            userId: string;
+            dimension: string;
+            value: string;
             totalSpendNanos: number;
             totalRequests: number;
             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<{
@@ -233,49 +602,143 @@ export declare class AIBudget {
             done: boolean;
         }>;
     };
-    /** Per-action (per-feature) budgets. */
+    /** 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;
-            disabled?: boolean | undefined;
+            dimension: string;
+            value: string;
             totalSpendNanos: number;
             totalRequests: number;
             totalTokens: number;
             dayStamp: string;
-            name: 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";
-            disabled?: 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<{
@@ -284,6 +747,8 @@ export declare class AIBudget {
             enforcement: "hard" | "soft";
             spentTodayNanos: number;
             spentTotalNanos: number;
+            retentionMs: number | null;
+            defaultWarnAtPct: number | null;
         }>;
         /** A killswitch spend cap across all users/actions (enforced approximately). */
         setLimits: (ctx: RunMutationCtx, args: {
@@ -295,6 +760,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;
@@ -312,12 +781,13 @@ export declare class AIBudget {
             models: string[];
         }) => Promise<null>;
     };
-    /** Per-model prices (cents per million tokens). */
+    /** Per-model prices (nanodollars per million tokens) + server-tool fees. */
     get prices(): {
         list: (ctx: RunQueryCtx) => Promise<{
             [x: string]: {
                 input: number;
                 output: number;
+                cached?: number | undefined;
                 overridden: boolean;
             };
         }>;
@@ -325,8 +795,45 @@ 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>;
+        /** Per-call fees for provider server tools (web search, etc.). */
+        listServerTools: (ctx: RunQueryCtx) => Promise<{
+            [x: string]: number;
+        }>;
+        /** Set a server-tool's per-call price, e.g. { tool: "web_search", nanosPerCall }. */
+        setServerTool: (ctx: RunMutationCtx, args: {
+            tool: string;
+            nanosPerCall: number;
         }) => Promise<null>;
     };
+    /**
+     * Mount the built-in admin dashboard on your app's HTTP router with one call.
+     * Serves a self-contained HTML dashboard (buckets, requests, usage history,
+     * settings) plus a small JSON API, all backed by the component — no extra
+     * queries to write.
+     *
+     *   // convex/http.ts
+     *   import { httpRouter } from "convex/server";
+     *   const http = httpRouter();
+     *   ai.registerRoutes(http, { authorize: async (ctx) =>
+     *     (await ctx.auth.getUserIdentity())?.role === "admin" });
+     *   export default http;
+     *
+     * It then lives at `https://<deployment>.convex.site/aibudget`.
+     *
+     * SECURITY: the endpoint is public on the internet. You MUST gate it — either
+     * pass `authorize` (recommended: check the caller is a deployment admin) or
+     * set the `AI_BUDGET_DASHBOARD_TOKEN` env var (a bearer token / `?token=`).
+     * With neither, every route returns 401.
+     */
+    registerRoutes(http: HttpRouter, opts?: {
+        /** Mount path (default "/aibudget"). */
+        path?: string;
+        /** Return true to allow the request. Runs on the HTML page and every API call. */
+        authorize?: (ctx: any, request: Request) => boolean | Promise<boolean>;
+    }): void;
 }
 /** @deprecated Renamed to `AIBudget`. */
 export declare const WorryFreeAI: typeof AIBudget;