@chrischall/gemini-mcp 1.10.0 → 1.11.1

package/dist/jobs.js

@@ -2,6 +2,7 @@ import { randomUUID, createHash } from 'node:crypto';
 import { textResult, McpToolError } from '@chrischall/mcp-utils';
 import { downloadFilename } from './media-name.js';
 import { HEARTBEAT_MS } from './job-store.js';
+import { annotateReusedUsage } from './usage.js';
 /** Recently-completed jobs are reusable by key for this long, then evicted. */
 const JOB_TTL_MS = 600_000; // 10 min
 /**
@@ -137,6 +138,9 @@ function annotateReused(result, jobId) {
         }
         obj.reused = true;
         obj.reused_job_id = jobId;
+        // The recorded usage describes the generation being handed back, but this
+        // call did not pay for it — mark it so a workflow total can exclude it.
+        annotateReusedUsage(obj);
         return { ...result, content: [{ ...first, text: JSON.stringify(obj, null, 2) }, ...content.slice(1)] };
     }
     // No text meta block (e.g. inline mode with empty meta) — prepend one.

package/dist/pricing.js

@@ -0,0 +1,201 @@
+/**
+ * Turning tokens into money.
+ *
+ * This is possible — and only just — because image output is billed per token
+ * like everything else, at a rate 20-40x the text-output rate. Google's
+ * published per-image prices ARE that arithmetic: 1120 image tokens at
+ * $30/1M is the $0.0336 quoted for a 1K flash-lite image, and 2000 at $120/1M
+ * is the $0.24 quoted for a 4K pro image. `tests/pricing.test.ts` reconciles
+ * every rate for which Google publishes a cross-check — the per-image prices,
+ * and omni's per-second video figure — so a typo in those fails as an equality
+ * rather than becoming a plausible wrong number.
+ *
+ * The rates with no published cross-check (an input rate, a text-output rate)
+ * are only as good as the transcription, which is why they are quoted verbatim
+ * in the entries below and dated. That gap is not academic: omni's entry
+ * originally carried an input and text rate a third of the real ones, and an
+ * image-output rate invented by copying another model, precisely because only
+ * the figure with a cross-check had been looked up.
+ *
+ * The consequence for the caller: output tokens MUST be split into image and
+ * text before pricing. Billing an image model's text tokens at the image rate
+ * overstates them twentyfold.
+ *
+ * ## Why a shipped default, and why it is dated
+ *
+ * A hardcoded rate card goes stale silently, and a confident wrong cost is
+ * worse than no cost because people act on it. Two things keep that honest
+ * here: every estimate carries {@link PRICED_AT}, the date these rates were
+ * read from Google's pricing page, so a caller can see the card's age; and
+ * `GEMINI_RATE_CARD` overrides or extends it without editing the package, so
+ * a stale number is the operator's to fix in their own environment rather
+ * than something they must wait on a release for.
+ *
+ * Everything not in the card prices as `undefined` rather than zero.
+ *
+ * Video and music ARE in the card, contrary to the first version of this
+ * module. `gemini-omni-flash` — the model this server's video tool uses — is
+ * token-billed at $17.50/1M (~5,792 tokens per second of 720p, which is the
+ * ~$0.10/second Google quotes); it is Veo that bills per second, and this
+ * server does not use Veo. Lyria genuinely is not token-billed: it charges per
+ * song, which {@link ModelRates.per_generation} exists for.
+ *
+ * These are the STANDARD paid-tier rates. Google also publishes a Batch tier
+ * at roughly half price, which this server cannot reach — every call it makes
+ * is synchronous `generateContent` or `interactions`, never the Batch API — so
+ * an estimate here is the standard price and is not silently optimistic.
+ *
+ * Source: https://ai.google.dev/gemini-api/docs/pricing (paid tier, USD).
+ */
+import { readEnvVar } from '@chrischall/mcp-utils';
+/** The date the shipped rates were read from Google's pricing page. */
+export const PRICED_AT = '2026-08-28';
+/**
+ * Paid-tier rates, USD per 1M tokens. Image generation has no free tier.
+ * `-preview` ids are priced as their GA twin (see {@link normalizeModel}).
+ */
+export const RATE_CARD = Object.freeze({
+    'gemini-3-pro-image': { input: 2.0, text_output: 12.0, image_output: 120.0 },
+    'gemini-3.1-flash-image': { input: 0.5, text_output: 3.0, image_output: 60.0 },
+    'gemini-3.1-flash-lite-image': { input: 0.25, text_output: 1.5, image_output: 30.0 },
+    // Google publishes 2.5-flash-image's output as $0.039 PER IMAGE at 1290
+    // tokens, not as a per-1M rate. 0.039 / 1290 * 1e6 = 30.23 — a back-derived
+    // figure, unlike the four above which are published per-1M directly. The
+    // test reconciles it against the $0.039 it came from.
+    'gemini-2.5-flash-image': { input: 0.3, text_output: 3.0, image_output: 30.2326 },
+    // Omni is token-billed for video: $17.50/1M at ~5,792 tokens per second of
+    // 720p, which is the ~$0.10/second Google quotes. Veo is the per-second
+    // family; this server does not use it.
+    //
+    // No image-output price is published for omni, so there is no image_output
+    // here. An absent rate prices that modality at zero rather than inventing
+    // one — and the first version of this entry DID invent one ($60, copied
+    // from flash-image), along with a $0.50 input and $3.00 text rate that were
+    // both a third of the real figures. Every number here is now quoted.
+    'gemini-omni-flash': { input: 1.5, text_output: 9.0, video_output: 17.5 },
+    // Lyria bills per song, so tokens describe the work and not the bill.
+    'lyria-3-clip': { input: 0, text_output: 0, per_generation: 0.04 },
+    'lyria-3-pro': { input: 0, text_output: 0, per_generation: 0.08 },
+});
+/** `foo-preview` prices as `foo` — the fleet uses both spellings. */
+function normalizeModel(model) {
+    return model.replace(/-preview$/, '');
+}
+/**
+ * The effective rate card: the shipped one, with `GEMINI_RATE_CARD` merged
+ * over it. A malformed override is ignored rather than thrown — the cost
+ * figure is a convenience and the generation is the job, so a bad rate card
+ * must not fail every call.
+ */
+export function loadRateCard(env = process.env) {
+    const raw = readEnvVar('GEMINI_RATE_CARD', { env });
+    if (!raw)
+        return { ...RATE_CARD };
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return { ...RATE_CARD };
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        return { ...RATE_CARD };
+    // Merge PER FIELD, not per model. A shallow per-model merge let a partial
+    // override — `{"gemini-3-pro-image": {"image_output": 100}}`, the obvious
+    // thing to write when one rate moves — drop `input` and `text_output`
+    // entirely, and an undefined rate multiplied by a token count is NaN. That
+    // NaN then flowed into the session accumulator, where it is absorbing: one
+    // bad call and every later total reads NaN for the rest of the session.
+    const out = { ...RATE_CARD };
+    for (const [model, override] of Object.entries(parsed)) {
+        if (!override || typeof override !== 'object' || Array.isArray(override))
+            continue;
+        // Store under the SAME key `estimateCost` looks up. Writing the raw key
+        // meant an override for `lyria-3-clip-preview` — the id a caller actually
+        // holds, since the video and music models are preview-only — landed under
+        // that key while lookup normalized to `lyria-3-clip`, so it was silently
+        // ignored: the operator's rate was accepted, stored, and never used.
+        const key = normalizeModel(model);
+        const merged = { ...(RATE_CARD[key] ?? {}), ...(out[key] ?? {}) };
+        for (const [field, value] of Object.entries(override)) {
+            // Only finite numbers get in. A string, null or NaN in the override is
+            // dropped rather than propagated into arithmetic.
+            if (typeof value === 'number' && Number.isFinite(value))
+                merged[field] = value;
+        }
+        // A model still lacking the two mandatory rates cannot be priced at all,
+        // and half a rate card is worse than none.
+        if (typeof merged.input === 'number' && typeof merged.text_output === 'number') {
+            out[key] = merged;
+        }
+    }
+    return out;
+}
+/**
+ * Estimate what a call cost, or `undefined` when there is no rate for the
+ * model — never a zero, which would read as "this was free".
+ */
+export function estimateCost(model, usage, env = process.env) {
+    const card = loadRateCard(env);
+    const key = normalizeModel(model);
+    const rates = card[key];
+    if (!rates)
+        return undefined;
+    const per = (tokens, rate) => 
+    // An absent rate prices as zero, never NaN. A modality with no published
+    // rate is not evidence of spend, and NaN is absorbing — it would poison
+    // every later total in the session.
+    typeof rate === 'number' && Number.isFinite(rate) ? (tokens * rate) / 1_000_000 : 0;
+    // Billed per call, not per token: the tokens describe the work and say
+    // nothing about the bill, so pricing them would double-count.
+    if (typeof rates.per_generation === 'number') {
+        return {
+            usd: rates.per_generation,
+            breakdown: {
+                input_usd: 0, text_output_usd: 0, image_usd: 0, video_usd: 0, audio_usd: 0,
+                per_generation_usd: rates.per_generation,
+            },
+            priced_at: PRICED_AT,
+            ...(overriddenFor(key, rates) ? { overridden: true } : {}),
+        };
+    }
+    const imageTokens = usage.image_tokens ?? 0;
+    const videoTokens = usage.video_tokens ?? 0;
+    const audioTokens = usage.audio_tokens ?? 0;
+    // Whatever the API attributed to no modality is text/thinking output — the
+    // cheap end, so an unrecognised modality understates rather than inflates.
+    const textTokens = Math.max(0, usage.output_tokens - imageTokens - videoTokens - audioTokens);
+    const input_usd = per(usage.input_tokens, rates.input);
+    const text_output_usd = per(textTokens, rates.text_output);
+    const image_usd = per(imageTokens, rates.image_output);
+    const video_usd = per(videoTokens, rates.video_output);
+    const audio_usd = per(audioTokens, rates.audio_output);
+    return {
+        usd: input_usd + text_output_usd + image_usd + video_usd + audio_usd,
+        breakdown: { input_usd, text_output_usd, image_usd, video_usd, audio_usd },
+        priced_at: PRICED_AT,
+        ...(overriddenFor(key, rates) ? { overridden: true } : {}),
+    };
+}
+/** Did any rate for this model come from the operator rather than the shipped card? */
+function overriddenFor(key, rates) {
+    const shipped = RATE_CARD[key];
+    if (!shipped)
+        return true;
+    return Object.keys(rates).some((f) => rates[f] !== shipped[f]);
+}
+/**
+ * Attach a cost estimate to a result's meta, when the model has a rate.
+ *
+ * Silent when it does not — a model absent from the rate card. An absent
+ * `cost_estimate` beside a present `usage` means "no rate for this model",
+ * which is the honest answer rather than a zero.
+ */
+export function attachCost(meta, model, usage) {
+    if (!usage)
+        return meta;
+    const cost = estimateCost(model, usage);
+    if (cost)
+        meta.cost_estimate = cost;
+    return meta;
+}

package/dist/registrars.js

@@ -17,6 +17,7 @@ import { registerInteractTools } from './tools/interact.js';
 import { registerVideoTools } from './tools/video.js';
 import { registerMusicTools } from './tools/music.js';
 import { registerJobTools } from './tools/jobs.js';
+import { registerUsageTools } from './tools/usage.js';
 import { registerFileTools } from './tools/files.js';
 import { registerUploadUrlTools } from './tools/uploads.js';
 import { registerLibraryTools } from './tools/library.js';
@@ -44,6 +45,7 @@ export const TOOL_REGISTRARS = [
     registerVideoTools,
     registerMusicTools,
     registerJobTools,
+    registerUsageTools,
     registerFileTools,
     registerUploadUrlTools,
     registerLibraryTools,

package/dist/session.js

@@ -1,4 +1,6 @@
 import { JobRegistry } from './jobs.js';
+import { sumUsage } from './usage.js';
+import { estimateCost } from './pricing.js';
 /**
  * Everything the server remembers *between tool calls on behalf of one user*.
  *
@@ -82,9 +84,59 @@ export class SessionState {
         }
         return hit;
     }
+    /**
+     * Everything this session has spent, in tokens, across every upstream call.
+     *
+     * Accumulated in the CLIENT rather than in the tools, so a call that was
+     * billed and then failed (a safety filter returning no image, say) still
+     * counts — it cost money regardless of whether a tool could use the result.
+     * Per session, never module scope: one hosted process serves many tenants,
+     * and a shared total would report other people's spend as yours.
+     */
+    usageTotal;
+    /** How many upstream calls contributed to {@link usageTotal}. */
+    billedCalls = 0;
+    /**
+     * What this session has spent in USD, priced per call.
+     *
+     * Accumulated as calls happen rather than derived from {@link usageTotal} at
+     * the end, because the total spans models: summing a Pro call's tokens with
+     * a Lite call's and pricing the result at one rate would be wrong by up to
+     * 4x. Each call is priced against ITS model and only the money is added up.
+     *
+     * `undefined` while nothing priceable has run — a model absent from the rate
+     * card contributes usage but no cost, so a total of `undefined` beside a
+     * non-zero usage is meaningful rather than a bug. (Video and music DO price:
+     * omni is token-billed and Lyria bills per song. It is an unknown or
+     * newly-released model id that goes unpriced.)
+     */
+    costUsd;
+    /** How many of {@link billedCalls} could actually be priced. */
+    pricedCalls = 0;
+    /**
+     * Fold one upstream call's usage into the running totals. `model` is what
+     * makes the cost side possible; without it the tokens still count.
+     */
+    recordUsage(usage, model) {
+        if (!usage)
+            return;
+        this.usageTotal = sumUsage([this.usageTotal, usage]);
+        this.billedCalls += 1;
+        if (!model)
+            return;
+        const cost = estimateCost(model, usage);
+        if (!cost)
+            return;
+        this.costUsd = (this.costUsd ?? 0) + cost.usd;
+        this.pricedCalls += 1;
+    }
     /** Forget everything. Tests use this; nothing in `src/` calls it. */
     reset() {
         this.jobs.reset();
+        this.usageTotal = undefined;
+        this.billedCalls = 0;
+        this.costUsd = undefined;
+        this.pricedCalls = 0;
         this.lastInteractionId = undefined;
         this.lastMusicInteractionId = undefined;
         this.lastVideoInteractionId = undefined;

package/dist/tools/generate.js

@@ -5,6 +5,8 @@ import { slugify, baseName } from '../images.js';
 import { resolveImageInputs, requireImageInput } from '../inputs.js';
 import { emit, resolveAspectRatio, ASPECT_RATIOS, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
+import { sumUsage } from '../usage.js';
+import { attachCost } from '../pricing.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const GENERATE_ENDPOINT = '/v1beta/models/{model}:generateContent';
 const SEND_LOCAL_ACTION = 'Send local file input(s) to the Gemini API';
@@ -88,6 +90,9 @@ export function registerGenerateTools(server, client) {
             // throws: an empty success is worse than an error.
             const failed = [];
             let firstError;
+            // One entry per SUCCESSFUL upstream call. `count: N` is N billable
+            // requests, so reporting the first would understate the tool by N-1.
+            const usages = [];
             await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : 'image'} (${model})`, async () => {
                 for (let i = 0; i < count; i++) {
                     try {
@@ -107,6 +112,7 @@ export function registerGenerateTools(server, client) {
                             timeoutMs: args.timeout_ms,
                         });
                         const { images: [img], text } = result;
+                        usages.push(result.usage);
                         if (text && !capturedText)
                             capturedText = text;
                         if (result.grounding && !capturedGrounding)
@@ -122,6 +128,10 @@ export function registerGenerateTools(server, client) {
             if (named.length === 0)
                 throw firstError;
             const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
+            const usage = sumUsage(usages);
+            if (usage)
+                meta.usage = usage;
+            attachCost(meta, model, usage);
             if (capturedText)
                 meta.text = capturedText;
             if (capturedGrounding)
@@ -208,6 +218,9 @@ export function registerGenerateTools(server, client) {
             }));
             const { images: [img], text } = result;
             const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
+            if (result.usage)
+                meta.usage = result.usage;
+            attachCost(meta, model, result.usage);
             if (text)
                 meta.text = text;
             if (result.grounding)

package/dist/tools/interact.js

@@ -7,6 +7,7 @@ import { resolveImageInputs } from '../inputs.js';
 import { findInteractionImages, latestInteractionId } from '../sidecar.js';
 import { emit, reportShape, resolveAspectRatio, orientationSchema, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
+import { attachCost } from '../pricing.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 // The last-interaction id and the written-outputs set used to live here, at
 // module scope. On the hosted connector that leaks across tenants — one
@@ -275,6 +276,9 @@ export function registerInteractTools(server, client) {
             meta.hint =
                 `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) — ` +
                     'do NOT re-attach the returned image as an input; the interaction already contains it.';
+            if (r.usage)
+                meta.usage = r.usage;
+            attachCost(meta, model, r.usage);
             if (r.text)
                 meta.text = r.text;
             if (r.grounding)

package/dist/tools/music.js

@@ -5,6 +5,7 @@ import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_MUSIC_MODEL } from '../models.js';
 import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
+import { attachCost } from '../pricing.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const MUSIC_MODELS = ['lyria-3-clip-preview', 'lyria-3-pro-preview'];
 const AUDIO_FORMATS = ['mp3', 'wav'];
@@ -86,6 +87,9 @@ export function registerMusicTools(server, client) {
             const meta = { model, interaction_id: r.id };
             if (previousInteractionId)
                 meta.previous_interaction_id = previousInteractionId;
+            if (r.usage)
+                meta.usage = r.usage;
+            attachCost(meta, model, r.usage);
             if (r.text)
                 meta.text = r.text;
             if (report)

package/dist/tools/set.js

@@ -5,6 +5,8 @@ import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { emit, resolveAspectRatio, ASPECT_RATIOS, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt, persistBundle, SET_URL_TTL_MS } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
+import { sumUsage } from '../usage.js';
+import { attachCost } from '../pricing.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerSetTools(server, client) {
     server.registerTool('gemini_image_set', {
@@ -90,6 +92,11 @@ export function registerSetTools(server, client) {
                 ? { ...masterOnly.report, ...carried.report }
                 : undefined;
             const named = [];
+            // A set is the most expensive tool here — master plus one call per
+            // scene — so omitting its usage understates spend more than anywhere
+            // else. Collected from every call that RETURNED, including scenes
+            // whose image was later discarded: they were billed regardless.
+            const usages = [];
             const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
                 const result = await client.generate({
                     prompt: masterPrompt,
@@ -97,6 +104,7 @@ export function registerSetTools(server, client) {
                     seed,
                     ...cfg,
                 });
+                usages.push(result.usage);
                 const master = result.images[0];
                 named.push({ image: master, base: `${slug}-master` });
                 // Only the master's text is surfaced (below). Per-scene text is intentionally
@@ -122,7 +130,9 @@ export function registerSetTools(server, client) {
                     let ref = master;
                     for (let i = 0; i < scenePrompts.length; i++) {
                         try {
-                            const { images: [img] } = await client.generate({ prompt: composePrompt(scenePrompts[i], styleOnly), images: [ref, ...carriedRefs], seed: seed + i + 1, ...cfg });
+                            const scene = await client.generate({ prompt: composePrompt(scenePrompts[i], styleOnly), images: [ref, ...carriedRefs], seed: seed + i + 1, ...cfg });
+                            usages.push(scene.usage);
+                            const img = scene.images[0];
                             named.push({ image: img, base: sceneName(i) });
                             // Chain mode anchors each scene on the previous OUTPUT, so a
                             // failure must not advance the reference — the next scene
@@ -135,7 +145,8 @@ export function registerSetTools(server, client) {
                     }
                 }
                 else {
-                    const settled = await Promise.allSettled(scenePrompts.map((p, i) => client.generate({ prompt: composePrompt(p, styleOnly), images: [master, ...carriedRefs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
+                    const settled = await Promise.allSettled(scenePrompts.map((p, i) => client.generate({ prompt: composePrompt(p, styleOnly), images: [master, ...carriedRefs], seed: seed + i + 1, ...cfg })
+                        .then((r) => { usages.push(r.usage); return r.images[0]; })));
                     settled.forEach((outcome, i) => {
                         if (outcome.status === 'fulfilled')
                             named.push({ image: outcome.value, base: sceneName(i) });
@@ -147,6 +158,10 @@ export function registerSetTools(server, client) {
             });
             const masterText = masterResult.text;
             const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
+            const usage = sumUsage(usages);
+            if (usage)
+                meta.usage = usage;
+            attachCost(meta, model, usage);
             if (masterText)
                 meta.text = masterText;
             if (masterResult.grounding)

package/dist/tools/usage.js

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { textResult, toolAnnotations } from '@chrischall/mcp-utils';
+import { PRICED_AT } from '../pricing.js';
+/**
+ * What this session has spent, in tokens.
+ *
+ * This exists because the obvious thing — read the account balance before and
+ * after — cannot be built. The Generative Language API's discovery document
+ * has no billing, quota, usage, account or credit resource at all, and Cloud
+ * Billing v1 has no notion of a balance either (its schema never mentions the
+ * word): Google Cloud is post-paid, so there is no wallet to read. Even with a
+ * service account and the Cloud Billing scopes, actual spend arrives through
+ * BigQuery export hours later — far too late to attribute to one call.
+ *
+ * Tokens do the job better anyway. They are exact, they are per-call, they
+ * arrive with the response, and they attribute: a before/after balance diff
+ * cannot separate your generation from anything else billing the account in
+ * the same window, and this can.
+ *
+ * Money IS reported, with two safeguards. Image output turned out to be billed
+ * per token like everything else — just at 20-40x the text-output rate — so
+ * the published per-image prices are exactly the token arithmetic, and an
+ * estimate is arithmetic rather than guesswork (see src/pricing.ts). The
+ * safeguards are that every figure carries the date its rates were read, and
+ * `GEMINI_RATE_CARD` overrides them without waiting on a release.
+ *
+ * The session's cost is accumulated PER CALL, not derived from the token total
+ * at the end: the total spans models, and pricing a Pro call's tokens at a
+ * Lite rate would be wrong by 4x.
+ */
+export function registerUsageTools(server, client) {
+    server.registerTool('gemini_token_usage', {
+        description: 'Token usage for this session so far — what every generation has cost in tokens, added up. ' +
+            'Call it before and after a workflow and subtract to get that workflow\'s cost; call it after a ' +
+            'single generation for that call\'s. Reports tokens AND an estimated USD cost, priced per call against each call\'s own model and stamped with the date its rates were read (override with GEMINI_RATE_CARD). Note there is no account-balance endpoint to query — Google Cloud is post-paid and its billing data lags by hours — so this is the accurate way to attribute spend to a call.',
+        annotations: toolAnnotations({ readOnly: true }),
+        inputSchema: {
+            reset: z
+                .boolean()
+                .optional()
+                .describe('Zero the running total after reporting it, so the next call measures from here. Use it to bracket a workflow without arithmetic.'),
+        },
+    }, async (args) => {
+        const usage = client.session.usageTotal;
+        const calls = client.session.billedCalls;
+        const costUsd = client.session.costUsd;
+        const priced = client.session.pricedCalls;
+        if (args.reset) {
+            client.session.usageTotal = undefined;
+            client.session.billedCalls = 0;
+            client.session.costUsd = undefined;
+            client.session.pricedCalls = 0;
+        }
+        return textResult({
+            usage: usage ?? null,
+            billed_calls: calls,
+            estimated_cost_usd: costUsd ?? null,
+            priced_calls: priced,
+            rates_published: PRICED_AT,
+            ...(args.reset ? { reset: true } : {}),
+            note: usage === undefined
+                ? 'No generation has run in this session yet, so nothing has been billed through it.'
+                : priced < calls
+                    ? `Estimate covers ${priced} of ${calls} billed calls — the rest used a model that is not in the rate card. Add it with GEMINI_RATE_CARD to include it.`
+                    : 'Estimate priced per call against each call\'s own model, then added up.',
+            rates: `Published rates read on ${PRICED_AT} (paid tier, USD). Override or extend with GEMINI_RATE_CARD ` +
+                'if they have moved — an estimate is only as current as its card.',
+            scope: 'This session only. A restart starts from zero, and a hosted deployment counts each authenticated session separately — these are your tokens, not the account\'s.',
+        });
+    });
+}

package/dist/tools/video.js

@@ -5,6 +5,7 @@ import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_VIDEO_MODEL } from '../models.js';
 import { emitMedia, reportShape, resolveAspectRatio, orientationSchema, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
+import { attachCost } from '../pricing.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 /** omni's own aspect-ratio enum — NOT the image tools' ASPECT_RATIOS. */
 const VIDEO_ASPECT_RATIOS = ['16:9', '9:16'];
@@ -105,6 +106,9 @@ export function registerVideoTools(server, client) {
             const meta = reportShape({ model, interaction_id: r.id }, { ...args, aspect_ratio: aspectRatio });
             if (previousInteractionId)
                 meta.previous_interaction_id = previousInteractionId;
+            if (r.usage)
+                meta.usage = r.usage;
+            attachCost(meta, model, r.usage);
             if (r.text)
                 meta.text = r.text;
             if (report)