@chrischall/gemini-mcp 1.13.0 → 1.14.1

package/dist/tools/interact.js

@@ -5,7 +5,8 @@ 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, 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 { emit, reportShape, resolveAspectRatio, orientationSchema, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema } from './shared.js';
+import { bytesToBase64 } from '../bytes.js';
 import { fingerprintRequest } from '../jobs.js';
 import { attachCost } from '../pricing.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
@@ -36,6 +37,35 @@ function splitReattachedOutputs(images, writtenOutputs) {
     }
     return { kept, dropped };
 }
+/**
+ * The image a given interaction produced, off disk, as inline input.
+ *
+ * `refs` is what the result reports as `reanchored_on`, so it is the caller's
+ * own vocabulary in each deployment: absolute paths here, object keys below.
+ */
+async function reanchorFromDisk(outputDir, interactionId) {
+    const refs = await findInteractionImages(outputDir, interactionId);
+    return { refs, carried: await Promise.all(refs.map((p) => readImageAsInline(p))) };
+}
+/** The same, from the object store, for a deployment with no filesystem. */
+async function reanchorFromStore(client, interactionId) {
+    try {
+        const found = await client.mediaSink?.findByInteraction?.(interactionId);
+        if (!found)
+            return { refs: [], carried: [] };
+        const stored = await client.readStoredMedia(found.key);
+        return {
+            refs: [found.key],
+            carried: [{ base64: bytesToBase64(stored.bytes), mimeType: stored.mimeType }],
+        };
+    }
+    catch {
+        // Recovery is best-effort: a store that cannot answer leaves the caller
+        // with the original 404, which is the honest outcome — never a re-anchor
+        // onto something else.
+        return { refs: [], carried: [] };
+    }
+}
 export function registerInteractTools(server, client) {
     // The sidecar/re-anchor half of this description is only true where there is
     // a filesystem. Describing it anyway on the hosted connector would tell the
@@ -43,23 +73,21 @@ export function registerInteractTools(server, client) {
     // description is built from the sink's capability, not hardcoded.
     const onDiskRuntime = client.mediaSink?.persistsFiles ?? true;
     const recoveryDescription = onDiskRuntime
-        ? 'If a call times out on the client side, the generation usually still completes: the image plus a ' +
-            '`<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` ' +
-            'still resumes that interaction — check the output dir before re-issuing (a re-issue is a second billable generation). ' +
-            'If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: ' +
-            'success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); ' +
-            'a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). '
-        : 'On this connector each result returns an image URL you can open or share directly (see `media[].url`) — show it ' +
-            'to the user rather than assuming they can see the image. There is no filesystem, so no output dir and no ' +
-            '`<image>.json` sidecar: a lost response cannot be recovered from disk and a 404 on a chained call cannot be ' +
-            're-anchored automatically. Capture the returned `interaction_id` from every result, and use `async: true` + ' +
-            'gemini_get_result for long generations. ';
+        ? 'If a call times out client-side the generation usually still completes: the image and an `<image>.json` sidecar ' +
+            'holding its interaction id land in the output dir, and `continue_last: true` still resumes it — look there before ' +
+            're-issuing, which bills a second generation. A chained 404 is re-anchored on the prior output and re-issued ' +
+            'un-chained (`chain_recovered`); a second 404 means the interaction id was not the cause — check the model id / ' +
+            'files uri. '
+        : 'Each result returns an image URL to open or share (`media[].url`) — show it to the user rather than assuming they ' +
+            'can see the image. There is no output dir here, but a lost response is still recoverable: the interaction id is ' +
+            'stored beside each image, so `continue_last: true` survives a restart and a chained 404 is re-anchored on the ' +
+            'image that interaction produced (reported as `chain_recovered`). gemini_list_recent_media shows what each stored ' +
+            'image was. Give long generations a `max_wait_ms` budget. ';
     server.registerTool('gemini_interact', {
-        description: 'Preferred tool for iterative or multi-step refinement of a single image — ' +
-            "multi-turn generation/editing via Gemini's Interactions API. " +
-            'To refine, capture the returned interaction `id` and pass it as `previous_interaction_id` ' +
-            'on the next call — do NOT start a new interaction or re-upload the image for each tweak. ' +
-            '`continue_last: true` chains from this session\'s most recent interaction without threading the id. ' +
+        description: 'Preferred tool for iterative refinement of a single image — multi-turn generation and editing via the ' +
+            'Interactions API. To refine, pass the returned interaction `id` as `previous_interaction_id` on the next call; ' +
+            'do NOT start a new interaction or re-send the image for each tweak. `continue_last: true` chains from this ' +
+            "session's most recent interaction without threading the id. " +
             recoveryDescription +
             'Output is JPEG.',
         annotations: { readOnlyHint: false, openWorldHint: true },
@@ -79,11 +107,7 @@ export function registerInteractTools(server, client) {
                 .describe(`Paths to reference input images. ${NEW_REFERENCES_ONLY}`),
             images_url: imagesUrlSchema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
             images_file_uris: imagesFileUrisSchema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
-            images_base64: z
-                .array(z.string().min(1))
-                .optional()
-                .describe(`Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, ` +
-                `which keep image bytes out of the conversation. ${NEW_REFERENCES_ONLY}`),
+            images_base64: imagesBase64Schema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
             model: z
                 .string()
                 .optional()
@@ -153,15 +177,23 @@ export function registerInteractTools(server, client) {
         let continuedFromSidecar = false;
         if (!previousInteractionId && args.continue_last) {
             previousInteractionId = client.session.lastInteractionId;
-            if (!previousInteractionId && onDisk) {
-                previousInteractionId = await latestInteractionId(resolveOutputDir(args.output_dir));
+            if (!previousInteractionId) {
+                // Both branches answer the same question from the same kind of
+                // record — an `<image>.json` on disk, an object beside the media in
+                // the store — so a restart no longer ends a chain on either.
+                previousInteractionId = onDisk
+                    ? await latestInteractionId(resolveOutputDir(args.output_dir))
+                    // 'image' explicitly: video and music write records too, and a
+                    // chained Lyria call is a documented 400. Resuming the wrong
+                    // medium's chain is worse than not resuming.
+                    : await client.mediaSink?.latestInteractionId?.('image');
                 continuedFromSidecar = previousInteractionId !== undefined;
             }
             if (!previousInteractionId) {
                 throw new McpToolError('No previous interaction to continue in this session.', {
                     hint: onDisk
                         ? 'Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id.'
-                        : 'Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id. (This hosted connector has no filesystem, so there are no <image>.json sidecars to recover an id from across restarts.)',
+                        : 'Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id. (Nothing this connector has stored carries an interaction id to resume from.)',
                 });
             }
         }
@@ -231,14 +263,15 @@ export function registerInteractTools(server, client) {
                     // probe itself could not be completed.
                     if (err.chainExists === true)
                         throw err;
-                    // Re-anchoring needs the prior output image, which only the sidecar
-                    // index can locate — and that index lives on disk.
-                    if (!onDisk)
-                        throw err;
-                    const reanchorOn = await findInteractionImages(resolveOutputDir(args.output_dir), err.previousInteractionId);
+                    // Re-anchoring needs the image that interaction produced, located
+                    // by ID — never "the newest image". On disk that index is the
+                    // `<image>.json` sidecars; hosted it is the record beside each
+                    // stored object. Same rule either way: no match, no guess.
+                    const { refs: reanchorOn, carried } = onDisk
+                        ? await reanchorFromDisk(resolveOutputDir(args.output_dir), err.previousInteractionId)
+                        : await reanchorFromStore(client, err.previousInteractionId);
                     if (!reanchorOn.length)
                         throw err;
-                    const carried = await Promise.all(reanchorOn.map((p) => readImageAsInline(p)));
                     try {
                         const probe = await client.interact({ ...callOpts, images: [...carried, ...inputs], previousInteractionId: undefined });
                         chainRecovered = { expired_interaction_id: err.previousInteractionId, reanchored_on: reanchorOn };
@@ -298,7 +331,7 @@ export function registerInteractTools(server, client) {
             // writeImage returns already-resolved absolute paths. `emit` only
             // invokes this callback for a filesystem-backed sink, so there is no
             // branch here claiming a sidecar the hosted connector cannot write.
-            return emit(named, { ...args, sink: client.mediaSink }, meta, async (paths) => {
+            return emit(named, { ...args, sink: client.mediaSink, sidecar: { prompt: args.input } }, meta, async (paths) => {
                 for (const p of paths)
                     client.session.writtenOutputs.add(p);
                 // Sidecar per image so the interaction id survives a lost MCP response

package/dist/tools/music.js

@@ -1,42 +1,46 @@
 import { z } from 'zod';
-import { McpToolError } from '@chrischall/mcp-utils';
 import { slugify, baseName } from '../images.js';
 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 { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema } 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'];
-/** WAV is Lyria-3-Pro-only (docs); reject it on the clip model up front. */
-function isProModel(model) { return /pro/i.test(model); }
-// The most-recent music interaction id (for continue_last) lives on
-// `client.session`, NOT at module scope: one Cloudflare isolate serves many
-// authenticated connector sessions, so a module-level id would let one user's
-// continue_last resume another user's interaction under their own key.
-// See src/session.ts.
+const MUSIC_MODELS = ['lyria-3-clip-preview', 'lyria-3.5', 'lyria-3-pro-preview'];
+/**
+ * There is no output-format parameter, and there is no chaining.
+ *
+ * Both were docs-derived and both were wrong (probed live 2026-09-09):
+ * `response_format.audio_format` is not a field — every Lyria model answers
+ * `400 Unknown parameter 'audio_format' at 'response_format'` — and its real
+ * name, `mime_type`, currently refuses every value but MP3 per-model
+ * (`Audio MIME type AUDIO_WAV is not supported for models/lyria-3.5`). A
+ * chained call dies inside the model, on the track it is handed back:
+ * `400 Unsupported input mime type for this model: audio/s16le`.
+ *
+ * So neither is exposed. A parameter whose every non-default value is a 400 is
+ * worse than an absent one: it costs schema tokens on every request and spends
+ * a caller's turn discovering it does not work.
+ */
 export function registerMusicTools(server, client) {
     server.registerTool('gemini_music_generate', {
-        description: 'Generate music from a text prompt (mood, genre, instruments, structure, or lyrics inline) via a Lyria model ' +
-            '(preview): lyria-3-clip-preview (~30s clips, default) or lyria-3-pro-preview (longer, WAV-capable). Written to ' +
-            'disk as MP3/WAV (or returned inline). Runs long — use `async: true` + gemini_get_result, or raise `timeout_ms`. ' +
-            'Preview model: needs a funded account.',
+        description: 'Generate music from a text prompt (mood, genre, instruments, structure, or lyrics inline) via a Lyria model: ' +
+            'lyria-3-clip-preview (30s instrumental clip, default, cheapest), lyria-3.5 (full-length song with vocals) or ' +
+            'lyria-3-pro-preview (longer-form). Output is MP3, written to disk (or returned inline). Single-turn: a track ' +
+            'cannot be refined by a follow-up call, so put the whole brief in the prompt. Runs long — give it a `max_wait_ms` ' +
+            'budget (or `async: true` + gemini_get_result on a local install), or raise `timeout_ms`. Needs a funded account.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             prompt: z.string().min(1).describe('Description of the music: mood, genre, instruments, tempo, structure, or lyrics'),
-            model: z.enum(MUSIC_MODELS).optional().describe(`Lyria model (default: ${DEFAULT_MUSIC_MODEL}). Pro is longer-form and supports WAV.`),
-            audio_format: z.enum(AUDIO_FORMATS).optional().describe('Output format (default mp3). wav is lyria-3-pro-preview-only.'),
+            model: z.enum(MUSIC_MODELS).optional().describe(`Lyria model (default: ${DEFAULT_MUSIC_MODEL} — 30s, $0.04). lyria-3.5 and lyria-3-pro-preview run minutes-long at $0.08.`),
             images: z.array(z.string().min(1)).optional().describe('Optional reference image path(s) to condition the music'),
             images_url: imagesUrlSchema('Reference images'),
             images_file_uris: imagesFileUrisSchema('Reference images'),
-            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
+            images_base64: imagesBase64Schema(),
             from_clipboard: z.boolean().optional().describe('Use the image currently on the macOS clipboard as a reference'),
             filename: z.string().optional().describe('Base filename for the output audio (extension stripped; default: slugified prompt)'),
             output_dir: z.string().optional().describe('Directory to write audio to (default: $GEMINI_OUTPUT_DIR or cwd)'),
-            inline: z.boolean().optional().describe('Return base64 audio inline instead of writing to disk'),
-            previous_interaction_id: z.string().optional().describe('Interaction id to continue from'),
-            continue_last: z.boolean().optional().describe('Continue from the most recent music interaction this server created (explicit previous_interaction_id wins)'),
+            inline: z.boolean().optional().describe('Return base64 audio inline instead of writing to disk. A 30s track is ~1.9MB of base64 — the default hands back a path instead'),
             background: z.boolean().optional().describe('Run the generation on Google\'s side and poll it, so a killed job can be recovered by gemini_get_result. Off by default — see gemini_video_generate'),
             timeout_ms: timeoutMsSchema,
             idempotency_key: idempotencyKeySchema,
@@ -47,28 +51,13 @@ export function registerMusicTools(server, client) {
     }, async (args, extra) => {
         assertLocalInputsAvailable(client.mediaSink, args);
         const model = args.model ?? DEFAULT_MUSIC_MODEL;
-        if (args.audio_format === 'wav' && !isProModel(model)) {
-            throw new McpToolError(`WAV output requires a Pro model; ${model} only produces MP3.`, {
-                hint: 'Use model: "lyria-3-pro-preview" for WAV, or drop audio_format to get MP3.',
-            });
-        }
-        let previousInteractionId = args.previous_interaction_id;
-        if (!previousInteractionId && args.continue_last) {
-            if (!client.session.lastMusicInteractionId) {
-                throw new McpToolError('No previous music interaction to continue in this session.', {
-                    hint: 'Generate music first, or pass an explicit previous_interaction_id.',
-                });
-            }
-            previousInteractionId = client.session.lastMusicInteractionId;
-        }
         const gate = await previewLocalInputsUnlessConfirmed(args.confirm, 'Send local image input(s) to the Gemini Lyria API', '/v1beta/interactions', args.images);
         if (gate)
             return gate;
         const fingerprint = fingerprintRequest('gemini_music_generate', {
-            model, prompt: args.prompt, audio_format: args.audio_format,
+            model, prompt: args.prompt,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             images_url: args.images_url, images_file_uris: args.images_file_uris,
-            previous_interaction_id: previousInteractionId,
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {
             const { inputs, report } = await resolveImageInputs(args, client);
@@ -76,17 +65,15 @@ export function registerMusicTools(server, client) {
                 input: args.prompt,
                 images: inputs.length ? inputs : undefined,
                 model: args.model,
-                audioFormat: args.audio_format,
-                previousInteractionId,
                 timeoutMs: args.timeout_ms,
                 background: args.background,
                 // See gemini_video_generate: the id is what survives the executor.
                 onInteractionStarted: ctx.reportInteraction,
             }));
-            client.session.lastMusicInteractionId = r.id;
+            // The interaction id is still reported — it is the handle
+            // gemini_get_result recovers a killed job's output with — but it is not
+            // a conversation handle: Lyria has no second turn.
             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);
@@ -94,13 +81,13 @@ export function registerMusicTools(server, client) {
                 meta.text = r.text;
             if (report)
                 meta.image_inputs = report;
-            meta.hint = `To continue this track, call gemini_music_generate again with previous_interaction_id: "${r.id}" (or continue_last: true).`;
+            meta.hint = 'Lyria is single-turn: to change this track, call gemini_music_generate again with a fuller prompt rather than a follow-up instruction.';
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
             const named = r.audios.map((media, i) => ({
                 media,
                 base: r.audios.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
             }));
-            return emitMedia(named, 'audio', { inline: args.inline, output_dir: args.output_dir, sink: client.mediaSink }, meta);
+            return emitMedia(named, 'audio', { inline: args.inline, output_dir: args.output_dir, sink: client.mediaSink, sidecar: { prompt: args.prompt } }, meta);
         });
     });
 }

package/dist/tools/set.js

@@ -3,7 +3,7 @@ import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 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 { emit, resolveAspectRatio, ASPECT_RATIOS, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesBase64Schema, 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';
@@ -25,7 +25,7 @@ export function registerSetTools(server, client) {
             master_images_r2_keys: imagesR2KeysSchema('Reference images passed to the master AND to every scene call'),
             characters: charactersSchema,
             style: styleSchema,
-            master_images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs for master generation. Last resort: prefer master_images_url or master_images_file_uris, which keep image bytes out of the conversation'),
+            master_images_base64: imagesBase64Schema('Reference images for the master generation', 'master_images'),
             confirm: schemaConfirm,
             ...sharedImageSchema,
         },
@@ -190,7 +190,7 @@ export function registerSetTools(server, client) {
             // A set is a batch someone comes back to: sign its links (and the
             // bundle's) for ~7 days rather than the default ~48h. The sink clamps
             // to the retention window; the disk sink ignores it entirely.
-            return emit(named, { ...args, sink: client.mediaSink, urlTtlMs: SET_URL_TTL_MS }, meta);
+            return emit(named, { ...args, sink: client.mediaSink, urlTtlMs: SET_URL_TTL_MS, sidecar: { prompt: args.master_prompt } }, meta);
         });
     });
 }

package/dist/tools/shared.js

@@ -71,19 +71,15 @@ export function resolveAspectRatio(opts, supported) {
 export const orientationSchema = z
     .enum(ORIENTATIONS)
     .optional()
-    .describe('Shape of the output, in plain terms: "landscape" (wide, 16:9), "portrait" (tall, 9:16) or "square" (1:1). ' +
-    'Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — ' +
-    '35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, ' +
-    'which overrides this when both are given.');
+    .describe('Output shape in plain terms: landscape (16:9), portrait (9:16) or square (1:1). For any other proportion — ' +
+    '3:2, 4:3, 4:5, 21:9 — use aspect_ratio, which wins if both are given.');
 /**
  * When to pick which Nano Banana model — shared by every tool's `model` param
  * so the guidance can't drift between them.
  */
-export const MODEL_CHOICE_GUIDE = 'gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse — balances speed with ' +
-    'state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image ' +
-    'processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex ' +
-    'visual tasks — highest world knowledge, advanced localization, accurate brand consistency, precision creative control. ' +
-    'gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).';
+export const MODEL_CHOICE_GUIDE = 'gemini-3.1-flash-image (Nano Banana 2, the default) is the generalist: fast, 4K, reliable text, strong ' +
+    'multi-reference consistency. gemini-3-pro-image (Pro) is for the hardest work — best world knowledge, brand ' +
+    'precision. gemini-3.1-flash-lite-image (Lite) is cheapest: 1K only, no search grounding.';
 /**
  * Per-call upstream timeout override, shared by every generation tool
  * (spread via {@link sharedImageSchema}; `gemini_interact` imports it directly
@@ -94,7 +90,7 @@ export const timeoutMsSchema = z
     .int()
     .positive()
     .optional()
-    .describe('Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 — or 120000 when image_size is 4K, which routinely runs past 60s)');
+    .describe('Upstream timeout in ms for this call (default $GEMINI_TIMEOUT_MS, else 60000 — 120000 at 4K, which runs past 60s)');
 /**
  * Idempotency key shared by every generation tool. A repeat call carrying the
  * same key returns the recorded result (`reused: true`) instead of billing a
@@ -105,7 +101,7 @@ export const idempotencyKeySchema = z
     .string()
     .min(1)
     .optional()
-    .describe('Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge.');
+    .describe('Repeat calls with this key return the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001).');
 /**
  * Async escape hatch shared by every generation tool: return a `job_id`
  * immediately so a long (Pro/4K) generation can't hit a host's fixed tools/call
@@ -114,10 +110,9 @@ export const idempotencyKeySchema = z
 export const asyncSchema = z
     .boolean()
     .optional()
-    .describe('Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit ' +
-    'the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result. ' +
-    'PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the ' +
-    'request is open, so this option is served there as a bounded wait rather than an immediate hand-off.');
+    .describe('Return a job_id immediately instead of the result, so a long generation cannot hit the host tools/call timeout ' +
+    '(-32001); poll gemini_get_result. On the hosted connector prefer max_wait_ms — the executor only lives while a ' +
+    'request is open, so async is served there as a bounded wait.');
 /**
  * Wait-then-hand-off budget shared by every generation tool: wait up to the
  * budget for the in-band result, and past it return a `{ job_id }` handle
@@ -130,9 +125,9 @@ export const maxWaitMsSchema = z
     .positive()
     .max(600_000)
     .optional()
-    .describe('Wait up to this many ms for the result; if generation is still running when the budget expires, return ' +
-    '{ job_id, status: "running" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a ' +
-    'slow batch can never trip the host tools/call timeout (-32001) — e.g. 20000 for multi-image sets. Ignored when async is set.');
+    .describe('Wait up to this many ms in-band, then hand back { job_id, status: "running" } to poll with gemini_get_result ' +
+    '(e.g. 20000 for multi-image sets). Keeps fast results inline and slow ones off the host timeout (-32001). ' +
+    'Ignored when async is set.');
 /**
  * Reference images already in THIS connector's object store, by `r2_key`.
  * Hosted connector only — the server reads its own bucket (tenant-gated), so
@@ -142,25 +137,24 @@ export function imagesR2KeysSchema(label = 'Reference images') {
     return z
         .array(z.string().min(1))
         .optional()
-        .describe(`${label} by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier ` +
-        "generation's media[].r2_key. The server reads its own bucket directly — no bytes in the conversation, no signed URL, " +
-        'no ~48h Files API expiry. Hosted connector only.');
+        .describe(`${label} by r2_key from this connector's store: a signed upload (gemini_get_upload_url → curl PUT) or an earlier ` +
+        "generation's media[].r2_key. The server reads its own bucket — no bytes in the conversation, no ~48h expiry. " +
+        'Hosted connector only.');
 }
 /** Saved-character names attached to a generation (hosted connector only). */
 export const charactersSchema = z
     .array(z.string().min(1))
     .max(8)
     .optional()
-    .describe('Names of saved characters (see gemini_list_characters / gemini_save_character): each one\'s reference image and ' +
-    'description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. ' +
-    'Hosted connector only.');
+    .describe('Names of saved characters (gemini_list_characters): each one\'s reference image and description are attached ' +
+    'automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only.');
 /** Saved-style name applied to a generation (hosted connector only). */
 export const styleSchema = z
     .string()
     .min(1)
     .optional()
-    .describe('Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment — and reference image, ' +
-    'if it has one — is applied to the request automatically. Hosted connector only.');
+    .describe('Name of a saved style preset (gemini_list_styles): its prompt fragment, and reference image if it has one, are ' +
+    'applied automatically. Hosted connector only.');
 /**
  * Turn `characters: ["finn", …]` / `style: "…"` into reference-image inputs
  * plus prompt text, from the account's saved library.
@@ -257,9 +251,23 @@ export function imagesUrlSchema(label = 'Reference images') {
     return z
         .array(z.string().url())
         .optional()
-        .describe(`${label} as public https URLs — the SERVER downloads them, so no image bytes travel through the conversation. ` +
-        'Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. ' +
-        `Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each; must be a directly-linked image (Content-Type image/*).`);
+        .describe(`${label} as public https URLs — the server downloads them, so no image bytes cross the conversation. Preferred ` +
+        `over images_base64, which costs ~14k tokens per photo. Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each, Content-Type image/*.`);
+}
+/**
+ * Raw base64 / data URIs — the last-resort input form, and the only one whose
+ * bytes have already crossed the conversation by the time the server sees
+ * them. The description says so, and says what to do instead NEXT time: the
+ * funnel uploads each entry once and reports the `files/<id>` back, so the
+ * repeat reference costs a short string rather than another photo.
+ */
+export function imagesBase64Schema(label = 'Reference images', prefix = 'images') {
+    return z
+        .array(z.string().min(1))
+        .optional()
+        .describe(`${label} as base64 strings or data URIs. Last resort — about 14k tokens per photo; prefer ${prefix}_url or ` +
+        `${prefix}_file_uris. The server uploads each one and reports a file_uri under image_inputs: pass that to ` +
+        `${prefix}_file_uris next time instead of re-sending the bytes.`);
 }
 /**
  * Reference images already in the Gemini Files API. The cheapest form there is:
@@ -269,9 +277,8 @@ export function imagesFileUrisSchema(label = 'Reference images') {
     return z
         .array(z.string().min(1))
         .optional()
-        .describe(`${label} by Gemini Files API reference ("files/<id>", or the full uri) from gemini_upload_file or POST /upload. ` +
-        'Upload once, then reference it across as many calls as you like — no bytes are re-sent and none enter the conversation. ' +
-        'Files are retained ~48h, after which the reference stops resolving.');
+        .describe(`${label} as Files API references ("files/<id>" or the full uri) from gemini_upload_file. Upload once and reuse ` +
+        'across calls with no bytes in the conversation; retained ~48h, after which the reference stops resolving.');
 }
 /**
  * The model/aspect/size/output fields every generation tool shares. Defined once
@@ -294,7 +301,7 @@ export const sharedImageSchema = {
     orientation: orientationSchema,
     image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution (512 = 0.5K, Flash-only)'),
     output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
-    inline: z.boolean().optional().describe('Return base64 images inline instead of writing to disk'),
+    inline: z.boolean().optional().describe('Return the image as an inline image block you can SEE, instead of a path (stdio) or link (hosted). The default costs nothing to carry and hands back a reference you can reuse; use this when you need to check the result yourself. On the hosted connector gemini_view_media does the same for an image you already have'),
     seed: z.number().int().optional().describe('Seed for reproducible generation; random if omitted'),
     thinking_level: z.enum(['minimal', 'high']).optional().describe('Reasoning depth (Gemini 3 models); higher can help complex/structural edits'),
     google_search: z.boolean().optional().describe('Ground the image in live Google Search results (current events, weather, data)'),
@@ -499,6 +506,28 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
     // next to, so it is skipped rather than handed URLs it would misinterpret.
     if (sink.persistsFiles)
         await onWritten?.(refs);
+    // The hosted twin of the `<image>.json` sidecar `onWritten` writes on disk.
+    // Same purpose: the interaction id has to outlive the response, or a dropped
+    // turn ends the chain and a 404 has nothing to re-anchor on. Written for
+    // EVERY stored object, since a set's scenes are as worth identifying later
+    // as its master. Best-effort inside the sink, which never throws.
+    const record = {
+        ...opts.sidecar,
+        // The kind is what keeps the three chains apart. `gemini_interact`'s
+        // continue_last reads the newest recorded id, and video and music write
+        // records too — without this it could resume an omni interaction, or a
+        // Lyria one, where a chained call is a documented 400.
+        kind,
+        ...(typeof meta?.interaction_id === 'string' ? { interaction_id: meta.interaction_id } : {}),
+        ...(typeof meta?.model === 'string' ? { model: meta.model } : {}),
+    };
+    // `kind` alone is not worth an object — a record earns its place by carrying
+    // something a later caller can act on or recognise.
+    if (!sink.persistsFiles && sink.writeSidecar && (record.interaction_id || record.prompt)) {
+        for (const p of persisted)
+            if (p.key)
+                await sink.writeSidecar(p.key, record);
+    }
     // Note a downgraded inline-video request so the caller isn't left wondering.
     const note = opts.inline && kind === 'video' ? { inline_unsupported: 'video has no MCP inline content type — written to disk instead' } : {};
     // Say where the bytes actually went whenever they are NOT local paths — the
@@ -605,8 +634,9 @@ export async function persistBundle(named, sink, base) {
     }
 }
 /**
- * Inputs that can only come off a local filesystem. On the hosted connector
- * (a Cloudflare Worker) none of them exist:
+ * Inputs that can only come off a local filesystem. The hosted deployment runs
+ * as a child process on mcp-host with no access to the CALLER's machine, so
+ * none of them exist there:
  *
  *  - `images` / `master_images` — file paths read with `node:fs`.
  *  - `from_clipboard` — shells out to `osascript`/`sips` via `child_process`.
@@ -642,12 +672,13 @@ export function assertLocalInputsAvailable(sink, args) {
     // exactly when it is needed.
     const fix = 'Reference images WITHOUT putting bytes in the conversation, in order of preference: ' +
         '(1) `images_url` — public https URLs the server fetches itself; ' +
-        '(2) `images_file_uris` — upload once with `gemini_upload_file` (it takes a `url` or `data_base64`) and reuse the returned files/… uri; ' +
-        '(3) `POST /upload` on this connector with the raw bytes as the body ' +
-        "(`curl -X POST <connector-url>/upload -H 'Authorization: Bearer <token>' -H 'Content-Type: image/jpeg' --data-binary @photo.jpg`), " +
-        'then pass the returned file_uri. ' +
-        'As a last resort `images_base64` still works, but it costs ~14k tokens per photo and breaks on a truncated read. ' +
+        '(2) `images_r2_keys` — mint a signed upload URL with `gemini_get_upload_url`, PUT the file to it, then pass the r2_key back ' +
+        '(the server reads its own store; nothing crosses the conversation); ' +
+        '(3) `images_file_uris` — upload once with `gemini_upload_file` (it takes a `url` or `data_base64`) and reuse the returned files/… uri. ' +
+        'If you CANNOT make HTTP requests at all, routes (1) and (2) are closed to you and the only way to reference a local file ' +
+        'is `images_base64`, which costs ~14k tokens per photo and breaks on a truncated read — the server uploads it once and ' +
+        'returns a files/… uri under image_inputs to reuse on later calls. ' +
         'Reference video by `video_url` (a public YouTube URL, or a files/… uri uploaded elsewhere) instead of `video_path`.';
     throw new McpToolError(`${unavailable.join(', ')} ${unavailable.length > 1 ? 'are' : 'is'} unavailable on the hosted connector: ` +
-        `it runs on a Cloudflare Worker, which has no filesystem and no local clipboard. ${fix}`, { hint: fix });
+        `it runs on a remote machine with no access to your filesystem or clipboard. ${fix}`, { hint: fix });
 }

package/dist/tools/uploads.js

@@ -9,12 +9,12 @@ import { step } from '../errors.js';
  *
  *   curl -sS -X PUT -H "Content-Type: image/jpeg" --data-binary @photo.jpg "<upload_url>"
  *
- * This closes the last gap in the no-bytes-in-the-conversation story. The two
- * existing byte routes each exclude a common caller: `images_base64` costs
- * ~14k tokens per photo and corrupts silently on a truncated read, and
- * `POST /upload` needs the MCP session's OAuth bearer token, which a sandboxed
- * shell doesn't have. A signed URL is mintable by the session and usable by
- * the shell.
+ * This closes the last gap in the no-bytes-in-the-conversation story. The
+ * alternatives each exclude a common caller: `images_base64` costs ~14k tokens
+ * per photo and corrupts silently on a truncated read, and the Worker's old
+ * `POST /upload` (retired with the Worker) needed the MCP session's OAuth
+ * bearer token, which a sandboxed shell does not have. A signed URL is mintable
+ * by the session and usable by the shell.
  *
  * Hosted only — stdio has no HTTP surface to PUT against (and no need: it reads
  * local paths directly). Gated on `client.uploadUrls`, the same pattern as