@chrischall/gemini-mcp 1.9.0 → 1.11.0

package/dist/client.js

@@ -1,6 +1,7 @@
 import { basename } from 'node:path';
 import { readEnvVar, McpToolError, ApiError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
 import { resolveModel, filterImageModels, DEFAULT_VIDEO_MODEL, DEFAULT_MUSIC_MODEL } from './models.js';
+import { readUsage } from './usage.js';
 import { createDiskSink, createR2Sink, tenantIdFor } from './storage/media.js';
 import { createR2Library } from './library.js';
 import { createUploadUrlMinter } from './upload-url.js';
@@ -560,6 +561,16 @@ export class GeminiClient {
         const data = await this.call('GET', '/models?pageSize=200');
         return filterImageModels(data.models ?? []);
     }
+    /**
+     * Fold one call's usage into the session total and hand it straight back, so
+     * a call site reads `const usage = this.recordUsage(readUsage(data), model)` right
+     * where the response lands — before any "returned no media" throw, so a
+     * billed call that a safety filter emptied is still counted.
+     */
+    recordUsage(usage, model) {
+        this.session.recordUsage(usage, model);
+        return usage;
+    }
     async generate(opts) {
         const model = resolveModel(opts.model, readEnvVar('GEMINI_IMAGE_MODEL'));
         const parts = [{ text: opts.prompt }];
@@ -585,6 +596,11 @@ export class GeminiClient {
         if (opts.googleSearch)
             requestBody.tools = [{ google_search: {} }];
         const data = await this.call('POST', `/models/${model}:generateContent`, requestBody, resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
+        // Recorded HERE, not at the return: the call is already billed by the
+        // time the response lands, and the "no image" throw below is a real
+        // outcome of a PAID request (a safety filter). Recording at the return
+        // omitted exactly the calls this total exists to catch.
+        const usage = this.recordUsage(readUsage(data), model);
         const images = [];
         const textParts = [];
         let groundingMeta;
@@ -620,7 +636,7 @@ export class GeminiClient {
                     grounding.sources = sources;
             }
         }
-        return { images, text, grounding };
+        return { images, text, grounding, usage };
     }
     async interact(opts) {
         const model = resolveModel(opts.model, readEnvVar('GEMINI_IMAGE_MODEL'));
@@ -647,13 +663,14 @@ export class GeminiClient {
             body.tools = [searchTool];
         }
         const data = await this.postInteraction(body, opts);
+        const usage = this.recordUsage(readUsage(data), model);
         const { images, text, grounding } = this.extractInteraction(data, opts.searchTypes);
         if (images.length === 0) {
             throw new McpToolError('Gemini returned no image', {
                 hint: 'The request may have been blocked by safety filters — try rephrasing the prompt.',
             });
         }
-        return { id: data.id, images: await this.downloadAll(images), text, grounding };
+        return { id: data.id, images: await this.downloadAll(images), text, grounding, usage };
     }
     /**
      * Generate video via the omni model (Interactions API). Same plumbing as
@@ -709,13 +726,14 @@ export class GeminiClient {
             started = await this.startInteraction(body, opts, timeoutMs);
         }
         const data = await this.settleInteraction(started, body, timeoutMs);
+        const usage = this.recordUsage(readUsage(data), model);
         const { videos, text } = this.extractInteraction(data);
         if (videos.length === 0) {
             throw new McpToolError('Gemini returned no video', {
                 hint: 'The request may have been blocked by a safety filter — try a shorter/simpler prompt or a different aspect ratio.',
             });
         }
-        return { id: data.id, videos: await this.downloadAll(videos), text };
+        return { id: data.id, videos: await this.downloadAll(videos), text, usage };
     }
     /**
      * Generate music via a Lyria model (Interactions API, inline audio). Reuses
@@ -736,13 +754,14 @@ export class GeminiClient {
         if (opts.background === true)
             body.background = true;
         const data = await this.postInteraction(body, opts);
+        const usage = this.recordUsage(readUsage(data), model);
         const { audios, text } = this.extractInteraction(data);
         if (audios.length === 0) {
             throw new McpToolError('Gemini returned no audio', {
                 hint: 'The request may have been blocked by a safety filter — try rephrasing the prompt.',
             });
         }
-        return { id: data.id, audios: await this.downloadAll(audios), text };
+        return { id: data.id, audios: await this.downloadAll(audios), text, usage };
     }
     /**
      * POST `/interactions`, wait out the store lag on a chained 404, and — when

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

@@ -5,8 +5,9 @@ import { ChainedRequest404Error } from '../client.js';
 import { slugify, baseName, resolveImagePath, writeSidecar, resolveOutputDir, readImageAsInline } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { findInteractionImages, latestInteractionId } from '../sidecar.js';
-import { emit, resolveAspectRatio, orientationSchema, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.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
@@ -259,7 +260,9 @@ export function registerInteractTools(server, client) {
                 }
             });
             client.session.lastInteractionId = r.id;
-            const meta = { model, interaction_id: r.id };
+            // `aspectRatio` is the RESOLVED value (see resolveAspectRatio above), so
+            // an `orientation: 'portrait'` request can be seen to have become 9:16.
+            const meta = reportShape({ model, interaction_id: r.id }, { ...args, aspect_ratio: aspectRatio });
             // On recovery the prior id was NOT used — reporting it as
             // previous_interaction_id would misrepresent what the model saw.
             if (chainRecovered)
@@ -273,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/shared.js

@@ -446,15 +446,29 @@ export function timeoutRiskHint(opts) {
 }
 /** Build the result metadata echoed to the caller (omitting unset optionals). */
 export function buildMeta(model, seed, opts) {
-    const meta = { model, seed };
-    // The RESOLVED ratio, and the orientation only when one was asked for — so a
-    // caller who said "portrait" can see both what they asked and what it became.
+    const meta = reportShape({ model, seed }, opts);
+    if (opts.image_size)
+        meta.image_size = opts.image_size;
+    return meta;
+}
+/**
+ * Record the shape a generation produced, into any meta object.
+ *
+ * The RESOLVED ratio, and the `orientation` only when one was actually asked
+ * for — so a caller who said "portrait" sees both what they asked and what it
+ * became, while a bare `21:9` is not handed back a word nobody used.
+ *
+ * It lives apart from `buildMeta` because two tools cannot use that function:
+ * `gemini_interact` and `gemini_video_generate` build their metas around
+ * `interaction_id` and chain state rather than a seed, and so reported no shape
+ * at all until #166. Sharing the rule rather than copying it is what keeps
+ * those hand-rolled metas from drifting again.
+ */
+export function reportShape(meta, opts) {
     if (opts.aspect_ratio)
         meta.aspect_ratio = opts.aspect_ratio;
     if (opts.orientation)
         meta.orientation = opts.orientation;
-    if (opts.image_size)
-        meta.image_size = opts.image_size;
     return meta;
 }
 /**