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

package/README.md

@@ -205,6 +205,35 @@ const result = await agent.generateText(ctx, { threadId }, { prompt });
 Every generation is now tracked and budgeted, attributed to `userId` and the
 calling action. See `example/convex/agentDemo.ts`.
 
+### `ai.meter` — budget *any* provider call
+
+`chat`/`languageModel` go through the gateway. When you need something the
+gateway can't serve (Anthropic web search, computer-use, a different provider,
+a raw `fetch`), `meter` brings that call under the *same* caps, audit log, and
+cost tracking. It reserves before your `run` (throwing over a hard cap), runs
+it, and records the actual usage:
+
+```ts
+await ai.meter(ctx, { userId, model: "anthropic/claude-…", messages }, async () => {
+  const res = await anthropic.messages.create({
+    messages,
+    tools: [{ type: "web_search_20250305", name: "web_search", max_uses: 3 }],
+  });
+  return {
+    text: extractText(res),
+    promptTokens: res.usage.input_tokens,
+    completionTokens: res.usage.output_tokens,
+    cachedTokens: res.usage.cache_read_input_tokens ?? 0,
+    serverToolUses: { web_search: res.usage.server_tool_use?.web_search_requests ?? 0 },
+    // costNanos? — pass an authoritative total to skip token/tool pricing
+  };
+});
+```
+
+`chat` is sugar over `meter`. Return either a raw provider `usage` (auto-
+normalized) or explicit `promptTokens`/`completionTokens`/`cachedTokens`, plus
+optional `serverToolUses` (see [pricing](#pricing--cost)) and `costNanos`.
+
 ### Replay
 
 ```ts
@@ -390,6 +419,17 @@ ai.prices.set(ctx, { model, inputNanosPerMTok, outputNanosPerMTok, cachedNanosPe
 ai.prices.list(ctx)
 ```
 
+**Server tools.** Provider server-side tools bill a per-call fee on top of
+tokens (e.g. Anthropic web search). Report them from `meter` as
+`serverToolUses: { web_search: 3 }` and they're priced per call (default
+$0.01/`web_search`) — unless you pass an authoritative `costNanos`, which already
+includes them. Override the rate:
+
+```ts
+ai.prices.setServerTool(ctx, { tool: "web_search", nanosPerCall: 12_000_000 })
+ai.prices.listServerTools(ctx)
+```
+
 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 (see `example/convex/ai.ts` → `syncPrices`):
@@ -529,22 +569,31 @@ npm run dev         # terminal 2 — Vite app
 
 ### What's in the component vs. the demo
 
-The component (`src/`) is **only** the metering/budget primitive — it knows
-nothing about chat or evaluation. Everything below lives in `example/` as
-**application code that uses the component**, not part of the published API:
-
-- The real features being metered — `sendMessage`, `summarize`, the agent.
-- An **eval playground** (🧪 Experiment tab): **Matrix** (one prompt across a
+The published AI Budget component (`src/`) is **only** the metering/budget
+primitive — it knows nothing about agents or evaluation. The example composes
+three isolated pieces:
+
+- The **Agent component** owns agent threads, messages, tools, and generation.
+- The local **Evaluation component** (`example/convex/evaluations/`) owns immutable
+  case snapshots, run lifecycle, and results. It does not call Agent or AI Budget.
+- App-level adapters in `example/convex/ai.ts` compose the siblings: they obtain
+  source traffic, run candidate/judge model calls through AI Budget, attach an
+  `evalRun` budget tag, and persist outcomes into Evaluation.
+- The **eval playground** (🧪 Experiment tab) exposes **Matrix** (one prompt across a
   system-prompt × model grid, ranked by an LLM judge on *your* criteria),
   **Backtest** (replay a candidate prompt against an action's real historical
   requests and judge each), and **Evolve** (an LLM iteratively improves a prompt
   toward a goal on real traffic, **stopping when it hits a spend budget**).
 
-These are built on two primitives — `ai.chat(...)` (every eval call is budgeted)
-and `ai.requests.list(...)` (the audit log *is* the eval dataset) — a "how to
-build on it" reference, not the component's surface. If you productize this it
-belongs in your app or a component that *composes* `@convex-dev/ai-budget`, never
-folded back into it.
+The demo currently snapshots AI Budget audit traffic as its corpus. An Agent-based
+product should instead make the app adapter snapshot cases through Agent's public
+API; Evaluation must never inspect Agent's private tables. The same Evaluation
+component works with either source because its inputs are explicit snapshots.
+
+This local component is a proof of the reusable boundary, not part of the
+`@convex-dev/ai-budget` package. If productized, it should ship independently
+(for example, `@convex-dev/evals`) and accept application adapters/function
+handles rather than taking a dependency on either sibling component.
 
 ---
 
@@ -566,7 +615,9 @@ npm run build       # emit dist/ (client + component) for publishing
 - `src/client/` — **the client** (published): the `AIBudget` class — `chat`,
   `languageModel`, `registerRoutes`, and the namespaced admin API.
 - `example/` — **the demo app** (not published): real features, the eval
-  playground, and the UI, all built on the two directories above.
+  playground, and the UI. `example/convex/evaluations/` is a separate local
+  component for datasets, runs, and results; `example/convex/ai.ts` is the
+  composition layer.
 
 ## License
 

package/dist/client/index.d.ts

@@ -113,8 +113,35 @@ export declare class AIBudget {
     private fireBudgetEvents;
     private fireLimitReached;
     /**
-     * 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).
+     */
+    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 — 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). */
@@ -168,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;
@@ -200,6 +230,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;
@@ -233,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;
@@ -262,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;
@@ -742,7 +781,7 @@ 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]: {
@@ -759,6 +798,15 @@ export declare class AIBudget {
             /** 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.

package/dist/client/index.js

@@ -155,27 +155,32 @@ export class AIBudget {
         }
     }
     /**
-     * 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(ctx, args = {}) {
-        const model = args.model ?? this.defaultModel;
-        const userId = await resolveUserId(ctx, args.userId);
-        const actionName = await resolveActionName(ctx, args.action);
-        const messages = args.messages ?? [{ role: "user", content: args.prompt ?? "" }];
+    async meter(ctx, opts, run) {
+        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,
-            tags: args.tags,
-            model,
-            messages,
-            rerunOf: args.rerunOf,
+            tags: opts.tags,
+            model: opts.model,
+            messages: opts.messages,
+            rerunOf: opts.rerunOf,
         });
         if (!started.allowed) {
             await this.fireLimitReached({
                 userId,
                 action: actionName,
-                tags: args.tags,
+                tags: opts.tags,
                 messages: [started.reason],
                 code: started.code,
                 reason: started.reason,
@@ -187,32 +192,30 @@ export class AIBudget {
             });
         }
         const requestId = started.requestId;
-        const warnings = started.warnings;
-        const notices = started.notices;
-        await this.fireBudgetEvents({ userId, action: actionName, tags: args.tags, requestId }, warnings, notices);
+        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,
-            });
-            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,
-                costNanos: extractGatewayCostNanos(result),
+                serverToolUses: out.serverToolUses,
+                costNanos: out.costNanos,
                 latencyMs: Date.now() - start,
             });
-            return { text: result.text, requestId, costNanos, warnings, notices, ...usage };
+            return { text: out.text ?? "", requestId, costNanos, warnings, notices, ...usage };
         }
         catch (e) {
             await ctx.runMutation(this.component.lib.finishRequest, {
@@ -223,6 +226,40 @@ export class AIBudget {
             throw e;
         }
     }
+    /**
+     * 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, args = {}) {
+        const model = args.model ?? this.defaultModel;
+        const messages = 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,
+            });
+            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
@@ -467,12 +504,16 @@ export class AIBudget {
             setPolicy: (ctx, args) => ctx.runMutation(c.lib.setModelPolicy, args),
         };
     }
-    /** Per-model prices (cents per million tokens). */
+    /** Per-model prices (nanodollars per million tokens) + server-tool fees. */
     get prices() {
         const c = this.component;
         return {
             list: (ctx) => ctx.runQuery(c.lib.listPrices, {}),
             set: (ctx, args) => ctx.runMutation(c.lib.setPrice, args),
+            /** Per-call fees for provider server tools (web search, etc.). */
+            listServerTools: (ctx) => ctx.runQuery(c.lib.listServerToolPrices, {}),
+            /** Set a server-tool's per-call price, e.g. { tool: "web_search", nanosPerCall }. */
+            setServerTool: (ctx, args) => ctx.runMutation(c.lib.setServerToolPrice, args),
         };
     }
     /**

package/dist/component/_generated/component.d.ts

@@ -55,6 +55,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             promptTokens?: number;
             requestId: string;
             responseText?: string;
+            serverToolUses?: Record<string, number>;
         }, {
             costNanos: number;
         }, Name>;
@@ -96,6 +97,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
             userId?: string;
             value?: string;
         }, any, Name>;
+        listServerToolPrices: FunctionReference<"query", "internal", {}, any, Name>;
         setAlertDefaults: FunctionReference<"mutation", "internal", {
             warnAtPct?: number;
         }, null, Name>;
@@ -132,6 +134,10 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         setRetention: FunctionReference<"mutation", "internal", {
             retentionMs: number;
         }, null, Name>;
+        setServerToolPrice: FunctionReference<"mutation", "internal", {
+            nanosPerCall: number;
+            tool: string;
+        }, null, Name>;
         startRequest: FunctionReference<"mutation", "internal", {
             actionName?: string;
             messages: Array<{

package/dist/component/lib.d.ts

@@ -27,6 +27,7 @@ export declare const finishRequest: import("convex/server").RegisteredMutation<"
     promptTokens?: number | undefined;
     completionTokens?: number | undefined;
     cachedTokens?: number | undefined;
+    serverToolUses?: Record<string, number> | undefined;
     costNanos?: number | undefined;
     latencyMs?: number | undefined;
     requestId: import("convex/values").GenericId<"requests">;
@@ -65,6 +66,7 @@ export declare const lineage: import("convex/server").RegisteredQuery<"public",
         promptTokens?: number | undefined;
         completionTokens?: number | undefined;
         cachedTokens?: number | undefined;
+        serverToolUses?: Record<string, number> | undefined;
         costNanos?: number | undefined;
         latencyMs?: number | undefined;
         rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -94,6 +96,7 @@ export declare const lineage: import("convex/server").RegisteredQuery<"public",
         promptTokens?: number | undefined;
         completionTokens?: number | undefined;
         cachedTokens?: number | undefined;
+        serverToolUses?: Record<string, number> | undefined;
         costNanos?: number | undefined;
         latencyMs?: number | undefined;
         rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -126,6 +129,7 @@ export declare const getRequest: import("convex/server").RegisteredQuery<"public
     promptTokens?: number | undefined;
     completionTokens?: number | undefined;
     cachedTokens?: number | undefined;
+    serverToolUses?: Record<string, number> | undefined;
     costNanos?: number | undefined;
     latencyMs?: number | undefined;
     rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -160,6 +164,7 @@ export declare const listRequests: import("convex/server").RegisteredQuery<"publ
     promptTokens?: number | undefined;
     completionTokens?: number | undefined;
     cachedTokens?: number | undefined;
+    serverToolUses?: Record<string, number> | undefined;
     costNanos?: number | undefined;
     latencyMs?: number | undefined;
     rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -359,3 +364,10 @@ export declare const listPrices: import("convex/server").RegisteredQuery<"public
     cached?: number;
     overridden: boolean;
 }>>>;
+export declare const listServerToolPrices: import("convex/server").RegisteredQuery<"public", {}, Promise<{
+    [x: string]: number;
+}>>;
+export declare const setServerToolPrice: import("convex/server").RegisteredMutation<"public", {
+    tool: string;
+    nanosPerCall: number;
+}, Promise<null>>;

package/dist/component/lib.js

@@ -32,6 +32,14 @@ const DEFAULT_PRICES = {
     "openai/gpt-5": { input: 1_250_000_000, output: 10_000_000_000 },
     "openai/gpt-5-mini": { input: 250_000_000, output: 2_000_000_000 },
 };
+// Per-call price (nanodollars) for provider server-side tools that bill a fee on
+// top of tokens — e.g. Anthropic web search at ~$0.01/call. Keyed by the tool
+// name the caller reports in `serverToolUses` (e.g. { web_search: 3 }). Used
+// only when a request settles WITHOUT an authoritative gateway cost; if you pass
+// `costNanos`, that already includes tool fees. Override via setServerToolPrice.
+const DEFAULT_SERVER_TOOL_PRICES = {
+    web_search: 10_000_000, // $0.01 per search
+};
 // Pessimistic assumed output length when reserving budget up front. This makes
 // concurrent admission atomic against the estimate; a response that exceeds the
 // estimate can still settle above the cap by the estimation delta.
@@ -99,6 +107,20 @@ const settleCost = (promptTokens, cachedTokens, completionTokens, price) => {
         (cached / 1e6) * cachedRate(price) +
         (completionTokens / 1e6) * price.output);
 };
+// Per-call fees for provider server tools (web search, etc.), merging the
+// defaults with any deployment overrides. Unknown tools price at 0 (recorded
+// but not charged) rather than guessing.
+const serverToolCost = (uses, overrides) => {
+    if (!uses)
+        return 0;
+    const prices = { ...DEFAULT_SERVER_TOOL_PRICES, ...(overrides ?? {}) };
+    let total = 0;
+    for (const [tool, count] of Object.entries(uses)) {
+        if (count > 0 && prices[tool] > 0)
+            total += Math.round(count * prices[tool]);
+    }
+    return total;
+};
 // Upsert-add a settled amount into the durable per-(bucket, period) usage row.
 // These rows are never swept by request retention, so spend history survives.
 async function addUsage(ctx, dimension, value, period, stamp, spendNanos, tokens, requests) {
@@ -525,9 +547,13 @@ export const finishRequest = mutation({
         promptTokens: v.optional(v.number()),
         completionTokens: v.optional(v.number()),
         cachedTokens: v.optional(v.number()),
-        // Authoritative cost from the gateway, if it ever reports one. When present
-        // it's recorded verbatim (no token-based estimate); when absent we price
-        // from tokens (cache-aware). Wired now so adopting a real cost is one line.
+        // Provider server-tool invocations that bill a per-call fee (e.g.
+        // { web_search: 3 }). Added to the token cost when no authoritative cost is
+        // supplied; recorded either way.
+        serverToolUses: v.optional(v.record(v.string(), v.number())),
+        // Authoritative cost from the gateway/provider, if reported. When present
+        // it's recorded verbatim (already includes any tool fees); when absent we
+        // price from tokens (cache-aware) plus server-tool fees.
         costNanos: v.optional(v.number()),
         latencyMs: v.optional(v.number()),
     },
@@ -551,11 +577,18 @@ export const finishRequest = mutation({
         const promptTokens = Math.max(0, args.promptTokens ?? 0);
         const completionTokens = Math.max(0, args.completionTokens ?? 0);
         const cachedTokens = Math.min(promptTokens, Math.max(0, args.cachedTokens ?? 0));
-        // Prefer an authoritative gateway cost when supplied; otherwise price from
-        // tokens, discounting the cached (prompt-cache-read) slice of the prompt.
-        const costNanos = args.costNanos !== undefined && args.costNanos >= 0
-            ? Math.round(args.costNanos)
-            : settleCost(promptTokens, cachedTokens, completionTokens, await getPrice(ctx, request.model));
+        // Prefer an authoritative gateway cost when supplied (it already includes
+        // tool fees); otherwise price from tokens — discounting the cached
+        // (prompt-cache-read) slice — plus any server-tool per-call fees.
+        let costNanos;
+        if (args.costNanos !== undefined && args.costNanos >= 0) {
+            costNanos = Math.round(args.costNanos);
+        }
+        else {
+            const settings = await getSettings(ctx);
+            costNanos =
+                settleCost(promptTokens, cachedTokens, completionTokens, await getPrice(ctx, request.model)) + serverToolCost(args.serverToolUses, settings?.serverToolPrices);
+        }
         // Durable write to the request's OWN row only — uncontended, so it always
         // lands. `settled: false` hands it to the fold step; the row is never left
         // orphaned in "pending" even if the totals update below fails and retries.
@@ -566,6 +599,7 @@ export const finishRequest = mutation({
             promptTokens,
             completionTokens,
             ...(cachedTokens > 0 ? { cachedTokens } : {}),
+            ...(args.serverToolUses ? { serverToolUses: args.serverToolUses } : {}),
             costNanos,
             latencyMs: args.latencyMs,
             settled: false,
@@ -1139,3 +1173,27 @@ export const listPrices = query({
         return merged;
     },
 });
+// Per-call fees for provider server tools (web search, etc.), defaults merged
+// with any deployment overrides.
+export const listServerToolPrices = query({
+    args: {},
+    handler: async (ctx) => {
+        const s = await getSettings(ctx);
+        return { ...DEFAULT_SERVER_TOOL_PRICES, ...(s?.serverToolPrices ?? {}) };
+    },
+});
+export const setServerToolPrice = mutation({
+    args: { tool: v.string(), nanosPerCall: v.number() },
+    returns: v.null(),
+    handler: async (ctx, { tool, nanosPerCall }) => {
+        if (nanosPerCall < 0)
+            throw new Error("Prices must be non-negative");
+        const s = await getSettings(ctx);
+        const serverToolPrices = { ...(s?.serverToolPrices ?? {}), [tool]: nanosPerCall };
+        if (s)
+            await ctx.db.patch(s._id, { serverToolPrices });
+        else
+            await ctx.db.insert("settings", { key: "singleton", serverToolPrices });
+        return null;
+    },
+});

package/dist/component/schema.d.ts

@@ -150,6 +150,7 @@ declare const _default: import("convex/server").SchemaDefinition<{
         promptTokens?: number | undefined;
         completionTokens?: number | undefined;
         cachedTokens?: number | undefined;
+        serverToolUses?: Record<string, number> | undefined;
         costNanos?: number | undefined;
         latencyMs?: number | undefined;
         rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -195,10 +196,11 @@ declare const _default: import("convex/server").SchemaDefinition<{
         promptTokens: import("convex/values").VFloat64<number | undefined, "optional">;
         completionTokens: import("convex/values").VFloat64<number | undefined, "optional">;
         cachedTokens: import("convex/values").VFloat64<number | undefined, "optional">;
+        serverToolUses: import("convex/values").VRecord<Record<string, number> | undefined, import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">, "optional", string>;
         costNanos: import("convex/values").VFloat64<number | undefined, "optional">;
         latencyMs: import("convex/values").VFloat64<number | undefined, "optional">;
         rerunOf: import("convex/values").VId<import("convex/values").GenericId<"requests"> | undefined, "optional">;
-    }, "required", "userId" | "actionName" | "tags" | "model" | "estimatedNanos" | "estimatedTokens" | "unpricedModel" | "overBudget" | "settled" | "messages" | "status" | "error" | "responseText" | "promptTokens" | "completionTokens" | "cachedTokens" | "costNanos" | "latencyMs" | "rerunOf">, {
+    }, "required", "userId" | "actionName" | "tags" | "model" | "estimatedNanos" | "estimatedTokens" | "unpricedModel" | "overBudget" | "settled" | "messages" | "status" | "error" | "responseText" | "promptTokens" | "completionTokens" | "cachedTokens" | "serverToolUses" | "costNanos" | "latencyMs" | "rerunOf" | `serverToolUses.${string}`>, {
         userId: ["userId", "_creationTime"];
         status: ["status", "_creationTime"];
         rerunOf: ["rerunOf", "_creationTime"];
@@ -229,6 +231,7 @@ declare const _default: import("convex/server").SchemaDefinition<{
         globalBumpDayStamp?: string | undefined;
         retentionMs?: number | undefined;
         defaultWarnAtPct?: number | undefined;
+        serverToolPrices?: Record<string, number> | undefined;
         key: string;
     }, {
         key: import("convex/values").VString<string, "required">;
@@ -242,7 +245,8 @@ declare const _default: import("convex/server").SchemaDefinition<{
         globalBumpDayStamp: import("convex/values").VString<string | undefined, "optional">;
         retentionMs: import("convex/values").VFloat64<number | undefined, "optional">;
         defaultWarnAtPct: import("convex/values").VFloat64<number | undefined, "optional">;
-    }, "required", "key" | "modelMode" | "models" | "globalDailySpendLimitNanos" | "globalLifetimeSpendLimitNanos" | "globalEnforcement" | "globalDailyBumpNanos" | "globalLifetimeBumpNanos" | "globalBumpDayStamp" | "retentionMs" | "defaultWarnAtPct">, {
+        serverToolPrices: import("convex/values").VRecord<Record<string, number> | undefined, import("convex/values").VString<string, "required">, import("convex/values").VFloat64<number, "required">, "optional", string>;
+    }, "required", "key" | "modelMode" | "models" | "globalDailySpendLimitNanos" | "globalLifetimeSpendLimitNanos" | "globalEnforcement" | "globalDailyBumpNanos" | "globalLifetimeBumpNanos" | "globalBumpDayStamp" | "retentionMs" | "defaultWarnAtPct" | "serverToolPrices" | `serverToolPrices.${string}`>, {
         key: ["key", "_creationTime"];
     }, {}, {}>;
 }, true>;

package/dist/component/schema.js

@@ -120,6 +120,9 @@ export default defineSchema({
         completionTokens: v.optional(v.number()),
         // subset of promptTokens served from the provider's prompt cache (cheaper).
         cachedTokens: v.optional(v.number()),
+        // server-side tool invocations that bill a per-call fee on top of tokens
+        // (e.g. { web_search: 3 }). Priced via serverToolPrices at settle.
+        serverToolUses: v.optional(v.record(v.string(), v.number())),
         costNanos: v.optional(v.number()),
         latencyMs: v.optional(v.number()),
         rerunOf: v.optional(v.id("requests")),
@@ -162,5 +165,8 @@ export default defineSchema({
         // default approaching-limit alert threshold (fraction of a cap) for buckets
         // that don't set their own warnAtPct. 0/unset disables threshold alerts.
         defaultWarnAtPct: v.optional(v.number()),
+        // per-call price (nanodollars) overrides for provider server tools, keyed by
+        // tool name (e.g. { web_search: 12_000_000 }). Merged over the defaults.
+        serverToolPrices: v.optional(v.record(v.string(), v.number())),
     }).index("key", ["key"]),
 });

package/package.json

@@ -7,7 +7,7 @@
     "email": "support@convex.dev",
     "url": "https://github.com/get-convex/ai-budget/issues"
   },
-  "version": "0.0.2-alpha.10",
+  "version": "0.0.2-alpha.12",
   "license": "Apache-2.0",
   "type": "module",
   "keywords": [

package/src/client/index.ts

@@ -306,42 +306,51 @@ export class AIBudget {
   }
 
   /**
-   * 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;
-      /** Extra attribution dimensions to bill/limit (team, customer, env, …). */
       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,
-      tags: args.tags,
-      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: args.tags,
+        tags: opts.tags,
         messages: [started.reason],
         code: started.code,
         reason: started.reason,
@@ -353,40 +362,38 @@ export class AIBudget {
       });
     }
     const requestId = started.requestId;
-    const warnings = started.warnings;
-    const notices = started.notices;
+    const { warnings, notices } = started;
     await this.fireBudgetEvents(
-      { userId, action: actionName, tags: args.tags, requestId },
+      { 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,
-          costNanos: extractGatewayCostNanos(result),
+          serverToolUses: out.serverToolUses,
+          costNanos: out.costNanos,
           latencyMs: Date.now() - start,
         }
       );
-      return { text: result.text, requestId, costNanos, warnings, notices, ...usage };
+      return { text: out.text ?? "", requestId, costNanos, warnings, notices, ...usage };
     } catch (e) {
       await ctx.runMutation(this.component.lib.finishRequest, {
         requestId,
@@ -397,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
@@ -720,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 {
@@ -735,6 +797,14 @@ export class AIBudget {
           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),
     };
   }
 

package/src/component/_generated/component.ts

@@ -76,6 +76,7 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
           promptTokens?: number;
           requestId: string;
           responseText?: string;
+          serverToolUses?: Record<string, number>;
         },
         { costNanos: number },
         Name
@@ -145,6 +146,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         any,
         Name
       >;
+      listServerToolPrices: FunctionReference<
+        "query",
+        "internal",
+        {},
+        any,
+        Name
+      >;
       setAlertDefaults: FunctionReference<
         "mutation",
         "internal",
@@ -210,6 +218,13 @@ export type ComponentApi<Name extends string | undefined = string | undefined> =
         null,
         Name
       >;
+      setServerToolPrice: FunctionReference<
+        "mutation",
+        "internal",
+        { nanosPerCall: number; tool: string },
+        null,
+        Name
+      >;
       startRequest: FunctionReference<
         "mutation",
         "internal",

package/src/component/lib.test.ts

@@ -116,6 +116,51 @@ describe("cache-aware pricing", () => {
   });
 });
 
+describe("server-tool pricing", () => {
+  test("server-tool uses add a per-call fee on top of tokens", async () => {
+    const t = convexTest(schema, modules);
+    const r = await start(t, { userId: "u" });
+    // 0 tokens; 3 web searches at the $0.01 default = 30_000_000 nano.
+    await settleWith(t, r.requestId, {
+      promptTokens: 0,
+      completionTokens: 0,
+      serverToolUses: { web_search: 3 },
+    });
+    const req = (await t.query(api.lib.getRequest, { requestId: r.requestId }))!;
+    expect(req.costNanos).toBe(30_000_000);
+    expect(req.serverToolUses).toEqual({ web_search: 3 });
+  });
+
+  test("an override price is applied", async () => {
+    const t = convexTest(schema, modules);
+    await t.mutation(api.lib.setServerToolPrice, {
+      tool: "web_search",
+      nanosPerCall: 12_000_000,
+    });
+    const r = await start(t, { userId: "u" });
+    await settleWith(t, r.requestId, {
+      promptTokens: 0,
+      completionTokens: 0,
+      serverToolUses: { web_search: 2 },
+    });
+    const req = (await t.query(api.lib.getRequest, { requestId: r.requestId }))!;
+    expect(req.costNanos).toBe(24_000_000);
+  });
+
+  test("an authoritative cost already includes tool fees (not double-charged)", async () => {
+    const t = convexTest(schema, modules);
+    const r = await start(t, { userId: "u" });
+    await settleWith(t, r.requestId, {
+      promptTokens: 1_000_000,
+      completionTokens: 0,
+      serverToolUses: { web_search: 5 },
+      costNanos: 999,
+    });
+    const req = (await t.query(api.lib.getRequest, { requestId: r.requestId }))!;
+    expect(req.costNanos).toBe(999);
+  });
+});
+
 describe("durable usage history", () => {
   test("settled spend lands in a per-day usage row", async () => {
     const t = convexTest(schema, modules);

package/src/component/lib.ts

@@ -43,6 +43,15 @@ const DEFAULT_PRICES: Record<string, { input: number; output: number }> = {
   "openai/gpt-5-mini": { input: 250_000_000, output: 2_000_000_000 },
 };
 
+// Per-call price (nanodollars) for provider server-side tools that bill a fee on
+// top of tokens — e.g. Anthropic web search at ~$0.01/call. Keyed by the tool
+// name the caller reports in `serverToolUses` (e.g. { web_search: 3 }). Used
+// only when a request settles WITHOUT an authoritative gateway cost; if you pass
+// `costNanos`, that already includes tool fees. Override via setServerToolPrice.
+const DEFAULT_SERVER_TOOL_PRICES: Record<string, number> = {
+  web_search: 10_000_000, // $0.01 per search
+};
+
 // Pessimistic assumed output length when reserving budget up front. This makes
 // concurrent admission atomic against the estimate; a response that exceeds the
 // estimate can still settle above the cap by the estimation delta.
@@ -136,6 +145,22 @@ const settleCost = (
   );
 };
 
+// Per-call fees for provider server tools (web search, etc.), merging the
+// defaults with any deployment overrides. Unknown tools price at 0 (recorded
+// but not charged) rather than guessing.
+const serverToolCost = (
+  uses: Record<string, number> | undefined,
+  overrides: Record<string, number> | undefined
+) => {
+  if (!uses) return 0;
+  const prices = { ...DEFAULT_SERVER_TOOL_PRICES, ...(overrides ?? {}) };
+  let total = 0;
+  for (const [tool, count] of Object.entries(uses)) {
+    if (count > 0 && prices[tool] > 0) total += Math.round(count * prices[tool]);
+  }
+  return total;
+};
+
 // Upsert-add a settled amount into the durable per-(bucket, period) usage row.
 // These rows are never swept by request retention, so spend history survives.
 async function addUsage(
@@ -684,9 +709,13 @@ export const finishRequest = mutation({
     promptTokens: v.optional(v.number()),
     completionTokens: v.optional(v.number()),
     cachedTokens: v.optional(v.number()),
-    // Authoritative cost from the gateway, if it ever reports one. When present
-    // it's recorded verbatim (no token-based estimate); when absent we price
-    // from tokens (cache-aware). Wired now so adopting a real cost is one line.
+    // Provider server-tool invocations that bill a per-call fee (e.g.
+    // { web_search: 3 }). Added to the token cost when no authoritative cost is
+    // supplied; recorded either way.
+    serverToolUses: v.optional(v.record(v.string(), v.number())),
+    // Authoritative cost from the gateway/provider, if reported. When present
+    // it's recorded verbatim (already includes any tool fees); when absent we
+    // price from tokens (cache-aware) plus server-tool fees.
     costNanos: v.optional(v.number()),
     latencyMs: v.optional(v.number()),
   },
@@ -711,17 +740,22 @@ export const finishRequest = mutation({
     const promptTokens = Math.max(0, args.promptTokens ?? 0);
     const completionTokens = Math.max(0, args.completionTokens ?? 0);
     const cachedTokens = Math.min(promptTokens, Math.max(0, args.cachedTokens ?? 0));
-    // Prefer an authoritative gateway cost when supplied; otherwise price from
-    // tokens, discounting the cached (prompt-cache-read) slice of the prompt.
-    const costNanos =
-      args.costNanos !== undefined && args.costNanos >= 0
-        ? Math.round(args.costNanos)
-        : settleCost(
-            promptTokens,
-            cachedTokens,
-            completionTokens,
-            await getPrice(ctx, request.model)
-          );
+    // Prefer an authoritative gateway cost when supplied (it already includes
+    // tool fees); otherwise price from tokens — discounting the cached
+    // (prompt-cache-read) slice — plus any server-tool per-call fees.
+    let costNanos: number;
+    if (args.costNanos !== undefined && args.costNanos >= 0) {
+      costNanos = Math.round(args.costNanos);
+    } else {
+      const settings = await getSettings(ctx);
+      costNanos =
+        settleCost(
+          promptTokens,
+          cachedTokens,
+          completionTokens,
+          await getPrice(ctx, request.model)
+        ) + serverToolCost(args.serverToolUses, settings?.serverToolPrices);
+    }
 
     // Durable write to the request's OWN row only — uncontended, so it always
     // lands. `settled: false` hands it to the fold step; the row is never left
@@ -733,6 +767,7 @@ export const finishRequest = mutation({
       promptTokens,
       completionTokens,
       ...(cachedTokens > 0 ? { cachedTokens } : {}),
+      ...(args.serverToolUses ? { serverToolUses: args.serverToolUses } : {}),
       costNanos,
       latencyMs: args.latencyMs,
       settled: false,
@@ -1347,3 +1382,26 @@ export const listPrices = query({
     return merged;
   },
 });
+
+// Per-call fees for provider server tools (web search, etc.), defaults merged
+// with any deployment overrides.
+export const listServerToolPrices = query({
+  args: {},
+  handler: async (ctx) => {
+    const s = await getSettings(ctx as any);
+    return { ...DEFAULT_SERVER_TOOL_PRICES, ...(s?.serverToolPrices ?? {}) };
+  },
+});
+
+export const setServerToolPrice = mutation({
+  args: { tool: v.string(), nanosPerCall: v.number() },
+  returns: v.null(),
+  handler: async (ctx, { tool, nanosPerCall }) => {
+    if (nanosPerCall < 0) throw new Error("Prices must be non-negative");
+    const s = await getSettings(ctx);
+    const serverToolPrices = { ...(s?.serverToolPrices ?? {}), [tool]: nanosPerCall };
+    if (s) await ctx.db.patch(s._id, { serverToolPrices });
+    else await ctx.db.insert("settings", { key: "singleton", serverToolPrices });
+    return null;
+  },
+});

package/src/component/schema.ts

@@ -132,6 +132,9 @@ export default defineSchema({
     completionTokens: v.optional(v.number()),
     // subset of promptTokens served from the provider's prompt cache (cheaper).
     cachedTokens: v.optional(v.number()),
+    // server-side tool invocations that bill a per-call fee on top of tokens
+    // (e.g. { web_search: 3 }). Priced via serverToolPrices at settle.
+    serverToolUses: v.optional(v.record(v.string(), v.number())),
     costNanos: v.optional(v.number()),
     latencyMs: v.optional(v.number()),
     rerunOf: v.optional(v.id("requests")),
@@ -184,5 +187,8 @@ export default defineSchema({
     // default approaching-limit alert threshold (fraction of a cap) for buckets
     // that don't set their own warnAtPct. 0/unset disables threshold alerts.
     defaultWarnAtPct: v.optional(v.number()),
+    // per-call price (nanodollars) overrides for provider server tools, keyed by
+    // tool name (e.g. { web_search: 12_000_000 }). Merged over the defaults.
+    serverToolPrices: v.optional(v.record(v.string(), v.number())),
   }).index("key", ["key"]),
 });