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

package/src/client/index.ts

@@ -1,8 +1,14 @@
-import type { Expand, FunctionReference } from "convex/server";
+import {
+  httpActionGeneric,
+  type Expand,
+  type FunctionReference,
+  type HttpRouter,
+} from "convex/server";
 import { ConvexError, type GenericId } from "convex/values";
 import { generateText, wrapLanguageModel, type LanguageModel } from "ai";
 import { convexGateway } from "@convex-dev/ai-sdk-provider";
 import type { api } from "../component/_generated/api";
+import { DASHBOARD_HTML } from "./dashboard";
 
 // ---------- types ----------
 
@@ -41,21 +47,40 @@ 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;
-  warnings: 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 = {
@@ -114,6 +139,8 @@ 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[];
 };
 
 // ---------- helpers ----------
@@ -134,10 +161,12 @@ function extractUsage(usage: any): {
   return {
     promptTokens: toTokenCount(usage?.inputTokens ?? usage?.promptTokens),
     completionTokens: toTokenCount(usage?.outputTokens ?? usage?.completionTokens),
-    // cached prompt tokens: AI SDK v5 `cachedInputTokens`, OpenAI-compat
-    // `prompt_tokens_details.cached_tokens` / `cached_tokens`.
+    // cached prompt tokens. The Convex gateway reports these at
+    // `usage.inputTokenDetails.cacheReadTokens`; the other paths cover AI SDK v5
+    // (`cachedInputTokens`) and raw OpenAI-compatible shapes.
     cachedTokens: toTokenCount(
-      usage?.cachedInputTokens ??
+      usage?.inputTokenDetails?.cacheReadTokens ??
+        usage?.cachedInputTokens ??
         usage?.promptTokensDetails?.cachedTokens ??
         usage?.prompt_tokens_details?.cached_tokens ??
         usage?.cached_tokens
@@ -145,6 +174,27 @@ function extractUsage(usage: any): {
   };
 }
 
+// The AI Gateway reports the authoritative dollar cost of each request.
+// @convex-dev/ai-sdk-provider surfaces it at
+// `providerMetadata.convexGateway.cost` (USD); convert to nanodollars and pass
+// it through as authoritative (finishRequest prefers it over the token-based
+// estimate). No-op on older provider versions that don't surface it.
+function extractGatewayCostNanos(result: any): number | undefined {
+  const meta = result?.providerMetadata?.convexGateway;
+  const costUsd = meta?.cost;
+  if (typeof costUsd === "number" && Number.isFinite(costUsd) && costUsd >= 0) {
+    return Math.round(costUsd * NANOS_PER_DOLLAR);
+  }
+  // Back-compat: honor an explicitly nano-denominated field if ever present.
+  const costNanos = meta?.costNanos ?? result?.usage?.costNanos;
+  if (typeof costNanos === "number" && Number.isFinite(costNanos) && costNanos >= 0) {
+    return Math.round(costNanos);
+  }
+  return undefined;
+}
+
+const NANOS_PER_DOLLAR = 1e9;
+
 // Flatten an AI SDK prompt (roles + content parts) into simple storable messages.
 function simplifyPrompt(prompt: any): Message[] {
   if (!Array.isArray(prompt)) return [];
@@ -178,56 +228,133 @@ function extractText(result: any): string {
 
 // ---------- client ----------
 
+// Length-independent-branch string compare, so the dashboard token check
+// doesn't leak the token via response timing. (Length itself is not secret.)
+function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let r = 0;
+  for (let i = 0; i < a.length; i++) r |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return r === 0;
+}
+
+/** 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 class AIBudget {
   public defaultModel: string;
   private onSoftLimit?: AIBudgetOptions["onSoftLimit"];
+  private onThreshold?: AIBudgetOptions["onThreshold"];
+  private onLimitReached?: AIBudgetOptions["onLimitReached"];
   constructor(
     public component: AIBudgetApi,
     options?: AIBudgetOptions
   ) {
     this.defaultModel = options?.defaultModel ?? "openai/gpt-4o-mini";
     this.onSoftLimit = options?.onSoftLimit;
+    this.onThreshold = options?.onThreshold;
+    this.onLimitReached = options?.onLimitReached;
   }
 
-  private async fireSoftLimit(info: SoftLimitInfo) {
-    if (info.warnings.length === 0 || !this.onSoftLimit) return;
+  // Fire the soft-limit + threshold callbacks from a startRequest result.
+  private async fireBudgetEvents(
+    base: Omit<BudgetEventInfo, "messages">,
+    warnings: string[],
+    notices: string[]
+  ) {
+    if (warnings.length > 0 && this.onSoftLimit) {
+      try {
+        await this.onSoftLimit({ ...base, messages: warnings, warnings });
+      } catch {
+        /* never let a callback error break a request */
+      }
+    }
+    if (notices.length > 0 && this.onThreshold) {
+      try {
+        await this.onThreshold({ ...base, messages: notices });
+      } catch {
+        /* swallow */
+      }
+    }
+  }
+
+  private async fireLimitReached(info: BudgetEventInfo) {
+    if (!this.onLimitReached) return;
     try {
-      await this.onSoftLimit(info);
+      await this.onLimitReached(info);
     } catch {
-      // never let a callback error break a request
+      /* swallow */
     }
   }
 
   /**
-   * One-shot chat through the AI Gateway with tracking + limits.
-   * Call from an action. `userId` defaults to the authenticated caller.
+   * 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).
    */
-  async chat(
+  async meter(
     ctx: RunMutationCtx,
-    args: {
-      /** Whom to bill. Defaults to the authenticated user (ctx.auth). */
+    opts: {
+      model: string;
+      messages: Message[];
       userId?: string;
-      prompt?: string;
-      messages?: Message[];
-      model?: string;
-      rerunOf?: string;
-      /** Attribute spend to this action name. Defaults to the calling Convex action. */
       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> {
-    const model = args.model ?? this.defaultModel;
-    const userId = await resolveUserId(ctx, args.userId);
-    const actionName = await resolveActionName(ctx, args.action);
-    const messages: Message[] =
-      args.messages ?? [{ role: "user", content: args.prompt ?? "" }];
+    const userId = await resolveUserId(ctx, opts.userId);
+    const actionName = await resolveActionName(ctx, opts.action);
     const started = await ctx.runMutation(this.component.lib.startRequest, {
       userId,
       actionName,
-      model,
-      messages,
-      rerunOf: args.rerunOf as any,
+      tags: opts.tags,
+      model: opts.model,
+      messages: opts.messages,
+      rerunOf: opts.rerunOf as any,
     });
     if (!started.allowed) {
+      await this.fireLimitReached({
+        userId,
+        action: actionName,
+        tags: opts.tags,
+        messages: [started.reason],
+        code: started.code,
+        reason: started.reason,
+      });
       throw new ConvexError({
         kind: "AIBudgetLimit",
         code: started.code,
@@ -235,34 +362,38 @@ export class AIBudget {
       });
     }
     const requestId = started.requestId;
-    const warnings = started.warnings;
-    await this.fireSoftLimit({ userId, action: actionName, requestId, warnings });
+    const { warnings, notices } = started;
+    await this.fireBudgetEvents(
+      { userId, action: actionName, tags: opts.tags, requestId },
+      warnings,
+      notices
+    );
     const start = Date.now();
     try {
-      // The full chain (incl. system) is stored on the request for audit/replay,
-      // but the AI SDK wants system prompts in the `system` option, not messages.
-      const system =
-        messages
-          .filter((m) => m.role === "system")
-          .map((m) => m.content)
-          .join("\n\n") || undefined;
-      const convo = messages.filter((m) => m.role !== "system");
-      const result = await generateText({
-        model: convexGateway(model),
-        ...(system ? { system } : {}),
-        messages: convo as any,
-      });
-      const usage = extractUsage(result.usage);
+      const out = await run();
+      // Explicit token fields win; otherwise normalize a raw provider usage.
+      const usage =
+        out.promptTokens !== undefined ||
+        out.completionTokens !== undefined ||
+        out.cachedTokens !== undefined
+          ? {
+              promptTokens: out.promptTokens ?? 0,
+              completionTokens: out.completionTokens ?? 0,
+              cachedTokens: out.cachedTokens ?? 0,
+            }
+          : extractUsage(out.usage);
       const { costNanos } = await ctx.runMutation(
         this.component.lib.finishRequest,
         {
           requestId,
-          responseText: result.text,
+          responseText: out.text,
           ...usage,
+          serverToolUses: out.serverToolUses,
+          costNanos: out.costNanos,
           latencyMs: Date.now() - start,
         }
       );
-      return { text: result.text, requestId, costNanos, warnings, ...usage };
+      return { text: out.text ?? "", requestId, costNanos, warnings, notices, ...usage };
     } catch (e) {
       await ctx.runMutation(this.component.lib.finishRequest, {
         requestId,
@@ -273,6 +404,61 @@ export class AIBudget {
     }
   }
 
+  /**
+   * One-shot chat through the AI Gateway with tracking + limits — sugar over
+   * `meter`. Call from an action. `userId` defaults to the authenticated caller.
+   */
+  async chat(
+    ctx: RunMutationCtx,
+    args: {
+      /** Whom to bill. Defaults to the authenticated user (ctx.auth). */
+      userId?: string;
+      prompt?: string;
+      messages?: Message[];
+      model?: string;
+      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> {
+    const model = args.model ?? this.defaultModel;
+    const messages: Message[] =
+      args.messages ?? [{ role: "user", content: args.prompt ?? "" }];
+    return this.meter(
+      ctx,
+      {
+        model,
+        messages,
+        userId: args.userId,
+        action: args.action,
+        tags: args.tags,
+        rerunOf: args.rerunOf,
+      },
+      async () => {
+        // The full chain (incl. system) is stored for audit/replay, but the AI
+        // SDK wants system prompts in the `system` option, not messages.
+        const system =
+          messages
+            .filter((m) => m.role === "system")
+            .map((m) => m.content)
+            .join("\n\n") || undefined;
+        const convo = messages.filter((m) => m.role !== "system");
+        const result = await generateText({
+          model: convexGateway(model),
+          ...(system ? { system } : {}),
+          messages: convo as any,
+        });
+        return {
+          text: result.text,
+          usage: result.usage,
+          costNanos: extractGatewayCostNanos(result),
+        };
+      }
+    );
+  }
+
   /**
    * An AI SDK LanguageModel that enforces limits and records usage/cost for
    * `userId` on every call. Drop it into `generateText`, `streamText`, or the
@@ -281,34 +467,48 @@ export class AIBudget {
    */
   languageModel(
     ctx: RunMutationCtx,
-    opts: { userId?: string; model?: string; action?: string } = {}
+    opts: {
+      userId?: string;
+      model?: string;
+      action?: string;
+      /** Extra attribution dimensions to bill/limit (team, customer, env, …). */
+      tags?: Tag[];
+    } = {}
   ): LanguageModel {
     const modelId = opts.model ?? this.defaultModel;
     const component = this.component;
-    const fireSoftLimit = this.fireSoftLimit.bind(this);
+    const fireBudgetEvents = this.fireBudgetEvents.bind(this);
+    const fireLimitReached = this.fireLimitReached.bind(this);
 
     const begin = async (params: any) => {
       const userId = await resolveUserId(ctx, opts.userId);
       const actionName = await resolveActionName(ctx, opts.action);
+      const base = { userId, action: actionName, tags: opts.tags };
       const started = await ctx.runMutation(component.lib.startRequest, {
         userId,
         actionName,
+        tags: opts.tags,
         model: modelId,
         messages: simplifyPrompt(params.prompt),
       });
       if (!started.allowed) {
+        await fireLimitReached({
+          ...base,
+          messages: [started.reason],
+          code: started.code,
+          reason: started.reason,
+        });
         throw new ConvexError({
           kind: "AIBudgetLimit",
           code: started.code,
           reason: started.reason,
         });
       }
-      await fireSoftLimit({
-        userId,
-        action: actionName,
-        requestId: started.requestId,
-        warnings: started.warnings,
-      });
+      await fireBudgetEvents(
+        { ...base, requestId: started.requestId },
+        started.warnings,
+        started.notices
+      );
       return started.requestId;
     };
     const finish = async (
@@ -318,6 +518,8 @@ export class AIBudget {
         error?: string;
         promptTokens?: number;
         completionTokens?: number;
+        cachedTokens?: number;
+        costNanos?: number;
         latencyMs?: number;
       }
     ) => ctx.runMutation(component.lib.finishRequest, { requestId, ...fields });
@@ -333,6 +535,7 @@ export class AIBudget {
             await finish(requestId, {
               responseText: extractText(result),
               ...extractUsage(result.usage),
+              costNanos: extractGatewayCostNanos(result),
               latencyMs: Date.now() - start,
             });
             return result;
@@ -349,6 +552,7 @@ export class AIBudget {
           const start = Date.now();
           let text = "";
           let usage: any = undefined;
+          let providerMetadata: any = undefined;
           try {
             const result = await doStream();
             // finishRequest is idempotent (terminal-guarded server-side), so
@@ -364,6 +568,7 @@ export class AIBudget {
                 responseText: text,
                 error,
                 ...extractUsage(usage),
+                costNanos: extractGatewayCostNanos({ providerMetadata }),
                 latencyMs: Date.now() - start,
               });
             };
@@ -373,7 +578,10 @@ export class AIBudget {
                   if (chunk?.type === "text-delta") {
                     text += chunk.delta ?? chunk.textDelta ?? "";
                   }
-                  if (chunk?.type === "finish") usage = chunk.usage;
+                  if (chunk?.type === "finish") {
+                    usage = chunk.usage;
+                    providerMetadata = chunk.providerMetadata ?? providerMetadata;
+                  }
                   if (chunk?.type === "error") void settle(String(chunk.error));
                   controller.enqueue(chunk);
                 },
@@ -409,6 +617,7 @@ export class AIBudget {
       messages: args.messages ?? original.messages,
       rerunOf: args.requestId,
       action: original.actionName,
+      tags: original.tags,
     });
   }
 
@@ -418,8 +627,19 @@ export class AIBudget {
   get requests() {
     const c = this.component;
     return {
-      list: (ctx: RunQueryCtx, args: { userId?: string; limit?: number } = {}) =>
-        ctx.runQuery(c.lib.listRequests, args),
+      /** Filter by userId, or by any {dimension, value} (incl. custom tags). */
+      list: (
+        ctx: RunQueryCtx,
+        args: {
+          userId?: string;
+          dimension?: string;
+          value?: string;
+          limit?: number;
+        } = {}
+      ) => ctx.runQuery(c.lib.listRequests, args),
+      /** One request, including its stored prompt and response. */
+      get: (ctx: RunQueryCtx, args: { requestId: string }) =>
+        ctx.runQuery(c.lib.getRequest, { requestId: args.requestId as any }),
       /** Ancestors up to the original, plus direct re-runs. */
       lineage: (ctx: RunQueryCtx, args: { requestId: string }) =>
         ctx.runQuery(c.lib.lineage, { requestId: args.requestId as any }),
@@ -431,60 +651,97 @@ export class AIBudget {
     };
   }
 
-  /** Per-user budgets and controls. */
-  get users() {
+  /**
+   * 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) {
+    return this.dimensionApi(dimension, (a: { value: string }) => a.value);
+  }
+
+  // Shared implementation behind tag()/users/actions. `key` maps the namespace's
+  // id field (value/userId/name) to the bucket value.
+  private dimensionApi<A extends Record<string, any>>(
+    dimension: string,
+    key: (a: A) => string
+  ) {
     const c = this.component;
     return {
-      list: (ctx: RunQueryCtx) => ctx.runQuery(c.lib.listUsers, {}),
-      setLimits: (
-        ctx: RunMutationCtx,
-        args: {
-          userId: string;
-          requestsPerMinute?: number;
-          dailySpendLimitNanos?: number;
-          lifetimeSpendLimitNanos?: number;
-          dailyTokenLimit?: number;
-          lifetimeTokenLimit?: number;
-          enforcement?: "hard" | "soft";
-          blocked?: boolean;
-        }
-      ) => ctx.runMutation(c.lib.setLimits, args),
-      /** One-time "approve another $X" bump (daily is today-only). */
-      bump: (
+      /** All buckets in this dimension. */
+      list: (ctx: RunQueryCtx) => ctx.runQuery(c.lib.listBuckets, { dimension }),
+      /** One bucket's limits + spend (null if it has none yet). */
+      get: (ctx: RunQueryCtx, args: A) =>
+        ctx.runQuery(c.lib.getBucket, { dimension, value: key(args) }),
+      setLimits: (ctx: RunMutationCtx, args: A & BucketLimits) => {
+        const { value, userId, name, ...limits } = args as any;
+        return ctx.runMutation(c.lib.setBucketLimits, {
+          dimension,
+          value: key(args),
+          ...limits,
+        });
+      },
+      /** One-time "approve another $X" bump (daily/monthly reset with the window). */
+      bump: (ctx: RunMutationCtx, args: A & BumpArgs) =>
+        ctx.runMutation(c.lib.bumpBucket, {
+          dimension,
+          value: key(args),
+          dailyNanos: args.dailyNanos,
+          monthlyNanos: args.monthlyNanos,
+          lifetimeNanos: args.lifetimeNanos,
+        }),
+      /** Manually credit (negative) or debit (positive) this bucket. */
+      adjust: (
         ctx: RunMutationCtx,
-        args: { userId: string; dailyNanos?: number; lifetimeNanos?: number }
-      ) => ctx.runMutation(c.lib.bumpUser, args),
-      /** Delete a user and all their request rows. */
-      delete: (ctx: RunMutationCtx, args: { userId: string }) =>
-        ctx.runMutation(c.lib.deleteUser, args),
+        args: A & { deltaNanos: number; tokens?: number; reason?: string }
+      ) =>
+        ctx.runMutation(c.lib.adjustBucket, {
+          dimension,
+          value: key(args),
+          deltaNanos: args.deltaNanos,
+          tokens: args.tokens,
+          reason: args.reason,
+        }),
+      /** Durable spend history for this bucket (per day or per month). */
+      history: (
+        ctx: RunQueryCtx,
+        args: A & { period?: "day" | "month"; limit?: number }
+      ) =>
+        ctx.runQuery(c.lib.usageHistory, {
+          dimension,
+          value: key(args),
+          period: args.period ?? "day",
+          limit: args.limit,
+        }),
+      /** Manual-adjustment audit log for this bucket. */
+      adjustments: (ctx: RunQueryCtx, args: A & { limit?: number }) =>
+        ctx.runQuery(c.lib.listAdjustments, {
+          dimension,
+          value: key(args),
+          limit: args.limit,
+        }),
+      /** Delete the bucket (for "user", also its request rows). */
+      delete: (ctx: RunMutationCtx, args: A) =>
+        ctx.runMutation(c.lib.deleteBucket, { dimension, value: key(args) }),
     };
   }
 
-  /** Per-action (per-feature) budgets. */
+  /** Per-user budgets and controls — sugar over the "user" dimension. */
+  get users() {
+    return this.dimensionApi<{ userId: string }>("user", (a) => a.userId);
+  }
+
+  /** Per-action (per-feature) budgets — sugar over the "action" dimension. */
   get actions() {
-    const c = this.component;
-    return {
-      list: (ctx: RunQueryCtx) => ctx.runQuery(c.lib.listActions, {}),
-      setLimits: (
-        ctx: RunMutationCtx,
-        args: {
-          name: string;
-          dailySpendLimitNanos?: number;
-          lifetimeSpendLimitNanos?: number;
-          dailyTokenLimit?: number;
-          lifetimeTokenLimit?: number;
-          enforcement?: "hard" | "soft";
-          disabled?: boolean;
-        }
-      ) => ctx.runMutation(c.lib.setActionLimits, args),
-      bump: (
-        ctx: RunMutationCtx,
-        args: { name: string; dailyNanos?: number; lifetimeNanos?: number }
-      ) => ctx.runMutation(c.lib.bumpAction, args),
-    };
+    return this.dimensionApi<{ name: string }>("action", (a) => a.name);
   }
 
-  /** The deployment-wide budget and retention config. */
+  /** The deployment-wide budget, alerts, and retention config. */
   get global() {
     const c = this.component;
     return {
@@ -503,6 +760,9 @@ export class AIBudget {
         ctx: RunMutationCtx,
         args: { dailyNanos?: number; lifetimeNanos?: number }
       ) => ctx.runMutation(c.lib.bumpGlobal, args),
+      /** Default approaching-limit alert threshold (fraction of a cap, e.g. 0.8). */
+      setAlertDefaults: (ctx: RunMutationCtx, args: { warnAtPct?: number }) =>
+        ctx.runMutation(c.lib.setAlertDefaults, args),
       /** Request-row retention window in ms (default 1h; 0 disables). */
       setRetention: (ctx: RunMutationCtx, args: { retentionMs: number }) =>
         ctx.runMutation(c.lib.setRetention, args),
@@ -522,7 +782,7 @@ export class AIBudget {
     };
   }
 
-  /** Per-model prices (cents per million tokens). */
+  /** Per-model prices (nanodollars per million tokens) + server-tool fees. */
   get prices() {
     const c = this.component;
     return {
@@ -533,10 +793,154 @@ export class AIBudget {
           model: string;
           inputNanosPerMTok: number;
           outputNanosPerMTok: number;
+          /** Cache-read rate; defaults to a discount off input if omitted. */
+          cachedNanosPerMTok?: number;
         }
       ) => ctx.runMutation(c.lib.setPrice, args),
+      /** Per-call fees for provider server tools (web search, etc.). */
+      listServerTools: (ctx: RunQueryCtx) =>
+        ctx.runQuery(c.lib.listServerToolPrices, {}),
+      /** Set a server-tool's per-call price, e.g. { tool: "web_search", nanosPerCall }. */
+      setServerTool: (
+        ctx: RunMutationCtx,
+        args: { tool: string; nanosPerCall: number }
+      ) => ctx.runMutation(c.lib.setServerToolPrice, args),
     };
   }
+
+  /**
+   * 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>;
+    } = {}
+  ) {
+    const prefix = (opts.path ?? "/aibudget").replace(/\/+$/, "");
+    const c = this.component.lib;
+    const authorize = opts.authorize;
+
+    const guard = async (
+      ctx: any,
+      request: Request
+    ): Promise<{ ok: boolean; token: string }> => {
+      if (authorize) return { ok: await authorize(ctx, request), token: "" };
+      const token = (globalThis as any).process?.env?.AI_BUDGET_DASHBOARD_TOKEN;
+      if (!token) return { ok: false, token: "" };
+      const url = new URL(request.url);
+      const bearer = (request.headers.get("authorization") ?? "").replace(/^Bearer\s+/i, "");
+      // `?token=` is accepted only for the initial page navigation (a browser
+      // GET can't set headers); the page strips it from the URL on load and the
+      // JSON API is called with the bearer header. Compared in constant time.
+      const provided = bearer || url.searchParams.get("token") || "";
+      return { ok: timingSafeEqual(provided, token), token };
+    };
+    const json = (data: unknown, status = 200) =>
+      new Response(JSON.stringify(data ?? null), {
+        status,
+        headers: { "content-type": "application/json" },
+      });
+
+    const handle = async (ctx: any, request: Request): Promise<Response> => {
+      const url = new URL(request.url);
+      const sub = url.pathname.slice(prefix.length) || "/";
+      const { ok, token } = await guard(ctx, request);
+      if (!ok) {
+        return new Response(
+          "Unauthorized. Pass `authorize` to registerRoutes or set AI_BUDGET_DASHBOARD_TOKEN.",
+          { status: 401 }
+        );
+      }
+
+      if (sub.startsWith("/api/")) {
+        const route = request.method + " " + sub.slice(4); // strip "/api"
+        const p: Record<string, string> = {};
+        url.searchParams.forEach((v, k) => {
+          p[k] = v;
+        });
+        const body =
+          request.method === "POST"
+            ? await request.json().catch(() => ({}))
+            : {};
+        switch (route) {
+          case "GET /buckets":
+            return json(await ctx.runQuery(c.listBuckets, { dimension: p.dimension || undefined }));
+          case "GET /requests":
+            return json(await ctx.runQuery(c.listRequests, {
+              userId: p.userId || undefined,
+              dimension: p.dimension || undefined,
+              value: p.value || undefined,
+              limit: 100,
+            }));
+          case "GET /usage":
+            return json(await ctx.runQuery(c.usageHistory, {
+              dimension: p.dimension,
+              value: p.value,
+              period: p.period === "month" ? "month" : "day",
+            }));
+          case "GET /global":
+            return json(await ctx.runQuery(c.getGlobalStatus, {}));
+          case "GET /prices":
+            return json(await ctx.runQuery(c.listPrices, {}));
+          case "POST /setLimits":
+            return json(await ctx.runMutation(c.setBucketLimits, body));
+          case "POST /bump":
+            return json(await ctx.runMutation(c.bumpBucket, body));
+          case "POST /adjust":
+            return json(await ctx.runMutation(c.adjustBucket, body));
+          case "POST /delete":
+            return json(await ctx.runMutation(c.deleteBucket, body));
+          case "POST /global/setLimits":
+            return json(await ctx.runMutation(c.setGlobalLimits, body));
+          case "POST /global/setAlertDefaults":
+            return json(await ctx.runMutation(c.setAlertDefaults, body));
+          case "POST /global/setRetention":
+            return json(await ctx.runMutation(c.setRetention, body));
+          case "POST /setPrice":
+            return json(await ctx.runMutation(c.setPrice, body));
+          default:
+            return json({ error: "not found" }, 404);
+        }
+      }
+
+      // Inject as JSON literals (function replacers so `$` in the value isn't
+      // treated as a replacement pattern). This keeps a token/prefix containing
+      // quotes, backslashes, or `</script>` from breaking out of the JS string.
+      const html = DASHBOARD_HTML.replace(
+        /__API_BASE__/g,
+        () => JSON.stringify(`${prefix}/api`)
+      ).replace(/__TOKEN__/g, () => JSON.stringify(token));
+      return new Response(html, {
+        headers: { "content-type": "text/html; charset=utf-8" },
+      });
+    };
+
+    const handler = httpActionGeneric(handle);
+    http.route({ path: prefix, method: "GET", handler });
+    http.route({ pathPrefix: `${prefix}/`, method: "GET", handler });
+    http.route({ pathPrefix: `${prefix}/`, method: "POST", handler });
+  }
 }
 
 /** @deprecated Renamed to `AIBudget`. */