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

package/dist/component/lib.d.ts

@@ -4,7 +4,9 @@ export declare const startRequest: import("convex/server").RegisteredMutation<"p
         dimension: string;
         value: string;
     }[] | undefined;
+    reserveTtlMs?: number | undefined;
     rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
+    estimatedCostNanos?: number | undefined;
     userId: string;
     model: string;
     messages: {
@@ -27,6 +29,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 +68,8 @@ export declare const lineage: import("convex/server").RegisteredQuery<"public",
         promptTokens?: number | undefined;
         completionTokens?: number | undefined;
         cachedTokens?: number | undefined;
+        serverToolUses?: Record<string, number> | undefined;
+        reserveTtlMs?: number | undefined;
         costNanos?: number | undefined;
         latencyMs?: number | undefined;
         rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -94,6 +99,8 @@ export declare const lineage: import("convex/server").RegisteredQuery<"public",
         promptTokens?: number | undefined;
         completionTokens?: number | undefined;
         cachedTokens?: number | undefined;
+        serverToolUses?: Record<string, number> | undefined;
+        reserveTtlMs?: number | undefined;
         costNanos?: number | undefined;
         latencyMs?: number | undefined;
         rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -126,6 +133,8 @@ export declare const getRequest: import("convex/server").RegisteredQuery<"public
     promptTokens?: number | undefined;
     completionTokens?: number | undefined;
     cachedTokens?: number | undefined;
+    serverToolUses?: Record<string, number> | undefined;
+    reserveTtlMs?: number | undefined;
     costNanos?: number | undefined;
     latencyMs?: number | undefined;
     rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -160,6 +169,8 @@ export declare const listRequests: import("convex/server").RegisteredQuery<"publ
     promptTokens?: number | undefined;
     completionTokens?: number | undefined;
     cachedTokens?: number | undefined;
+    serverToolUses?: Record<string, number> | undefined;
+    reserveTtlMs?: number | undefined;
     costNanos?: number | undefined;
     latencyMs?: number | undefined;
     rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -359,3 +370,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) {
@@ -281,6 +303,15 @@ export const startRequest = mutation({
         tags: v.optional(v.array(vTag)),
         model: v.string(),
         messages: v.array(vMessage),
+        // Reserve this exact amount (nanodollars) instead of the token-based
+        // estimate. Use it whenever the cost is known up front — image generation
+        // (n × per-image), audio, per-call APIs — so a hard cap reserves the real
+        // amount rather than a meaningless token guess.
+        estimatedCostNanos: v.optional(v.number()),
+        // Hold the reservation this long (ms) before the reconciler may reap it —
+        // for long async jobs (video) that settle minutes later. Extends the 30-min
+        // default floor.
+        reserveTtlMs: v.optional(v.number()),
         rerunOf: v.optional(v.id("requests")),
     },
     returns: vStartResult,
@@ -310,6 +341,11 @@ export const startRequest = mutation({
         const month = monthStamp();
         const priceInfo = await getPrice(ctx, args.model);
         const est = estimateUsage(args.messages, priceInfo);
+        // A caller-supplied known cost (image gen, audio, per-call APIs) reserves
+        // the real amount up front; the token estimate stays as the token reserve.
+        if (args.estimatedCostNanos !== undefined && args.estimatedCostNanos >= 0) {
+            est.cost = Math.round(args.estimatedCostNanos);
+        }
         const warnings = [];
         const notices = [];
         // Model allow/deny policy (component-wide).
@@ -499,6 +535,7 @@ export const startRequest = mutation({
             model: args.model,
             messages: args.messages,
             rerunOf: args.rerunOf,
+            ...(args.reserveTtlMs !== undefined ? { reserveTtlMs: args.reserveTtlMs } : {}),
             status: "pending",
             estimatedNanos: est.cost,
             estimatedTokens: est.tokens,
@@ -525,9 +562,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 +592,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 +614,7 @@ export const finishRequest = mutation({
             promptTokens,
             completionTokens,
             ...(cachedTokens > 0 ? { cachedTokens } : {}),
+            ...(args.serverToolUses ? { serverToolUses: args.serverToolUses } : {}),
             costNanos,
             latencyMs: args.latencyMs,
             settled: false,
@@ -659,12 +708,19 @@ export const reconcile = internalMutation({
             .take(200);
         for (const req of toFold)
             await foldOne(ctx, req);
+        // Reap dead reservations: pending rows older than the default floor, but a
+        // per-request reserveTtlMs (set for long async jobs like video) holds the
+        // reservation until *its* deadline so a still-running job isn't reaped.
         const cutoff = Date.now() - STALE_PENDING_MS;
-        const stale = await ctx.db
+        const candidates = await ctx.db
             .query("requests")
             .withIndex("status", (q) => q.eq("status", "pending").lt("_creationTime", cutoff))
             .take(200);
-        for (const req of stale) {
+        let expired = 0;
+        for (const req of candidates) {
+            const ttl = req.reserveTtlMs ?? STALE_PENDING_MS;
+            if (Date.now() - req._creationTime <= ttl)
+                continue; // still within its window
             await ctx.db.patch(req._id, {
                 status: "error",
                 error: "Timed out before settling; reservation released",
@@ -672,6 +728,7 @@ export const reconcile = internalMutation({
                 settled: false,
             });
             await foldOne(ctx, await ctx.db.get(req._id));
+            expired++;
         }
         // Retention: delete terminal, fully-accounted request rows past the window.
         const settings = await getSettings(ctx);
@@ -693,7 +750,7 @@ export const reconcile = internalMutation({
                 }
             }
         }
-        return { folded: toFold.length, expired: stale.length, purged };
+        return { folded: toFold.length, expired, purged };
     },
 });
 export const setRetention = mutation({
@@ -1139,3 +1196,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,8 @@ declare const _default: import("convex/server").SchemaDefinition<{
         promptTokens?: number | undefined;
         completionTokens?: number | undefined;
         cachedTokens?: number | undefined;
+        serverToolUses?: Record<string, number> | undefined;
+        reserveTtlMs?: number | undefined;
         costNanos?: number | undefined;
         latencyMs?: number | undefined;
         rerunOf?: import("convex/values").GenericId<"requests"> | undefined;
@@ -195,10 +197,12 @@ 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>;
+        reserveTtlMs: import("convex/values").VFloat64<number | undefined, "optional">;
         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" | "reserveTtlMs" | "costNanos" | "latencyMs" | "rerunOf" | `serverToolUses.${string}`>, {
         userId: ["userId", "_creationTime"];
         status: ["status", "_creationTime"];
         rerunOf: ["rerunOf", "_creationTime"];
@@ -229,6 +233,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 +247,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,14 @@ 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())),
+        // How long the reservation may stay held before the reconciler reaps it as
+        // dead (ms). For long async jobs (video generation) set this to the job's
+        // max duration so the hold isn't released mid-flight. Extends the default
+        // 30-min floor; only stored while pending.
+        reserveTtlMs: v.optional(v.number()),
         costNanos: v.optional(v.number()),
         latencyMs: v.optional(v.number()),
         rerunOf: v.optional(v.id("requests")),
@@ -162,5 +170,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.13",
   "license": "Apache-2.0",
   "type": "module",
   "keywords": [