@chrischall/gemini-mcp 1.12.0 → 1.14.0

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/jobs.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
 import { TERMINAL_INTERACTION_STATUSES } from '../client.js';
 import { emitMedia } from './shared.js';
 import { slugify } from '../images.js';
@@ -128,7 +128,7 @@ function recoveryNote(recordedError) {
 }
 /** The generation outlived its executor and is not finished yet. */
 function stillRunning(jobId, interactionId) {
-    return textResult({
+    return minifiedResult({
         job_id: jobId,
         status: 'running',
         interaction_id: interactionId,

package/dist/tools/library.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
 import { LIBRARY_NAME_PATTERN } from '../library.js';
 import { acceptableUploadType } from '../upload-url.js';
 import { withProgressHeartbeat } from './shared.js';
@@ -79,7 +79,7 @@ export function registerLibraryTools(server, client) {
     }, async (args, extra) => {
         const image = (await withProgressHeartbeat(extra, 'Loading the reference image', () => resolveLibraryImage(client, args, true)));
         const record = await library.saveCharacter({ name: args.name, description: args.description, image });
-        return textResult({
+        return minifiedResult({
             saved: 'character',
             name: record.name,
             description: record.description,
@@ -96,7 +96,7 @@ export function registerLibraryTools(server, client) {
         inputSchema: {},
     }, async () => {
         const characters = await library.listCharacters();
-        return textResult({
+        return minifiedResult({
             count: characters.length,
             characters: characters.map((c) => ({
                 name: c.name,
@@ -122,7 +122,7 @@ export function registerLibraryTools(server, client) {
         if (!existed) {
             throw new McpToolError(`No saved character "${args.name}". List what exists with gemini_list_characters.`);
         }
-        return textResult({ deleted: 'character', name: args.name });
+        return minifiedResult({ deleted: 'character', name: args.name });
     });
     server.registerTool('gemini_save_style', {
         description: 'Save a named style preset to this account\'s persistent reference library: a reusable prompt fragment (and ' +
@@ -141,7 +141,7 @@ export function registerLibraryTools(server, client) {
     }, async (args, extra) => {
         const image = await withProgressHeartbeat(extra, 'Loading the style reference image', () => resolveLibraryImage(client, args, false));
         const record = await library.saveStyle({ name: args.name, promptFragment: args.prompt_fragment, image });
-        return textResult({
+        return minifiedResult({
             saved: 'style',
             name: record.name,
             prompt_fragment: record.prompt_fragment,
@@ -157,7 +157,7 @@ export function registerLibraryTools(server, client) {
         inputSchema: {},
     }, async () => {
         const styles = await library.listStyles();
-        return textResult({
+        return minifiedResult({
             count: styles.length,
             styles: styles.map((s) => ({
                 name: s.name,
@@ -181,6 +181,6 @@ export function registerLibraryTools(server, client) {
         if (!existed) {
             throw new McpToolError(`No saved style "${args.name}". List what exists with gemini_list_styles.`);
         }
-        return textResult({ deleted: 'style', name: args.name });
+        return minifiedResult({ deleted: 'style', name: args.name });
     });
 }

package/dist/tools/models.js

@@ -1,10 +1,10 @@
-import { textResult } from '@chrischall/mcp-utils';
+import { minifiedResult } from '@chrischall/mcp-utils';
 export function registerModelTools(server, client) {
     server.registerTool('gemini_list_models', {
         description: 'List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.',
         annotations: { readOnlyHint: true },
     }, async () => {
         const models = await client.listModels();
-        return textResult({ default: client.defaultModel(), models });
+        return minifiedResult({ default: client.defaultModel(), models });
     });
 }

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);
         });
     });
 }