@chrischall/gemini-mcp 1.4.0 → 1.5.1

package/dist/tools/generate.js

@@ -3,7 +3,7 @@ import { readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs, requireImageInput } from '../inputs.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const GENERATE_ENDPOINT = '/v1beta/models/{model}:generateContent';
@@ -24,7 +24,10 @@ export function registerGenerateTools(server, client) {
             images: z.array(z.string().min(1)).optional().describe('Paths to reference input images (image-conditioned generation)'),
             images_url: imagesUrlSchema(),
             images_file_uris: imagesFileUrisSchema(),
+            images_r2_keys: imagesR2KeysSchema(),
             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'),
+            characters: charactersSchema,
+            style: styleSchema,
             video_url: z.string().url().optional().describe('Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
             video_path: videoPathSchema,
             confirm: schemaConfirm,
@@ -49,15 +52,22 @@ export function registerGenerateTools(server, client) {
             model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search, count,
             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,
+            images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
+            characters: args.characters, style: args.style,
             video_url: args.video_url, video_path: args.video_path,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_image_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_image_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
             const seed = pickSeed(args.seed);
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
+            // Saved characters/style resolve first (and fail fast on an unknown
+            // name — before anything billable), so their reference images lead the
+            // input order the prompt preamble describes.
+            const charRefs = await resolveCharacterRefs(client, args.characters, args.style);
+            const prompt = composePrompt(args.prompt, charRefs);
             // Resolved ONCE, before the count loop: a URL is fetched (and a large
             // one uploaded) a single time no matter how many images are generated.
-            const { inputs: refInputs, report } = await withProgressHeartbeat(extra, 'Resolving reference images', () => resolveImageInputs(args, client));
+            const { inputs: directInputs, report } = await withProgressHeartbeat(extra, 'Resolving reference images', () => resolveImageInputs(args, client));
+            const refInputs = [...charRefs.inputs, ...directInputs];
             // Upload ONCE (before the count loop) — every generate call references
             // the same files/… uri.
             const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args, client));
@@ -79,7 +89,7 @@ export function registerGenerateTools(server, client) {
                         // Distinct seed per image (seed+0 for the single-image case == echoed seed)
                         // so count>1 yields N *different* images, not N duplicates.
                         const result = await client.generate({
-                            prompt: args.prompt,
+                            prompt,
                             images: refInputs.length > 0 ? refInputs : undefined,
                             model: args.model,
                             aspectRatio: args.aspect_ratio,
@@ -113,6 +123,8 @@ export function registerGenerateTools(server, client) {
                 meta.grounding = capturedGrounding;
             if (report)
                 meta.image_inputs = report;
+            if (charRefs.meta)
+                Object.assign(meta, charRefs.meta);
             if (failed.length) {
                 meta.failed_images = failed;
                 meta.partial =
@@ -139,14 +151,20 @@ export function registerGenerateTools(server, client) {
             images: z.array(z.string().min(1)).optional().describe('Paths to input image file(s) (1 = edit, 2+ = compose)'),
             images_url: imagesUrlSchema('Input images'),
             images_file_uris: imagesFileUrisSchema('Input images'),
+            images_r2_keys: imagesR2KeysSchema('Input images'),
             images_base64: z.array(z.string().min(1)).optional().describe('Input images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
+            characters: charactersSchema,
+            style: styleSchema,
             filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
             confirm: schemaConfirm,
             ...sharedImageSchema,
         },
     }, async (args, extra) => {
         assertLocalInputsAvailable(client.mediaSink, args);
-        requireImageInput(args);
+        // Saved characters count as input images for the required-input check —
+        // the library attaches their references inside the handler.
+        if (!args.characters?.length)
+            requireImageInput(args);
         // Confirm-gate local file inputs (see gemini_image_generate). base64 /
         // clipboard inputs are not local-path reads and pass through ungated.
         const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images);
@@ -157,14 +175,18 @@ export function registerGenerateTools(server, client) {
             model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
             thinking_level: args.thinking_level, google_search: args.google_search,
             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,
+            images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
+            characters: args.characters, style: args.style,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_image_edit', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_image_edit', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
             const seed = pickSeed(args.seed);
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
-            const { inputs, report } = await withProgressHeartbeat(extra, 'Resolving input images', () => resolveImageInputs(args, client));
+            const charRefs = await resolveCharacterRefs(client, args.characters, args.style);
+            const prompt = composePrompt(args.prompt, charRefs);
+            const { inputs: directInputs, report } = await withProgressHeartbeat(extra, 'Resolving input images', () => resolveImageInputs(args, client));
+            const inputs = [...charRefs.inputs, ...directInputs];
             const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client.generate({
-                prompt: args.prompt,
+                prompt,
                 images: inputs,
                 model: args.model,
                 aspectRatio: args.aspect_ratio,
@@ -182,6 +204,8 @@ export function registerGenerateTools(server, client) {
                 meta.grounding = result.grounding;
             if (report)
                 meta.image_inputs = report;
+            if (charRefs.meta)
+                Object.assign(meta, charRefs.meta);
             meta.hint = REFINE_HINT;
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: client.mediaSink?.persistsFiles });
             if (risk)

package/dist/tools/interact.js

@@ -5,7 +5,7 @@ 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, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emit, 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 { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 // The last-interaction id and the written-outputs set used to live here, at
@@ -126,6 +126,7 @@ export function registerInteractTools(server, client) {
             timeout_ms: timeoutMsSchema,
             idempotency_key: idempotencyKeySchema,
             async: asyncSchema,
+            max_wait_ms: maxWaitMsSchema,
             from_clipboard: z
                 .boolean()
                 .optional()
@@ -180,7 +181,7 @@ export function registerInteractTools(server, client) {
             images_url: args.images_url, images_file_uris: args.images_file_uris,
             video_url: args.video_url, video_path: args.video_path,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_interact', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_interact', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
             const { inputs, report } = await resolveImageInputs({ ...args, images }, client);
             const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args, client));
             const callOpts = {

package/dist/tools/library.js

@@ -0,0 +1,186 @@
+import { z } from 'zod';
+import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { LIBRARY_NAME_PATTERN } from '../library.js';
+import { acceptableUploadType } from '../upload-url.js';
+import { withProgressHeartbeat } from './shared.js';
+import { previewUnlessConfirmed, schemaConfirm } from './_confirm.js';
+/**
+ * Tools over the per-account reference library (src/library.ts): named
+ * characters and styles that persist across sessions with NO expiry.
+ *
+ * Hosted connector only — the library lives in the connector's R2 bucket, so
+ * on stdio (no bucket) none of these register, mirroring how
+ * `gemini_sign_media` is absent on disk sinks.
+ */
+const NAME_FIELD = z
+    .string()
+    .regex(LIBRARY_NAME_PATTERN, 'must be 1-40 lowercase letters, digits, "-" or "_"')
+    .describe('Library name (slug): 1-40 lowercase letters, digits, "-" or "_", e.g. "finn" or "bold-cartoon-sports"');
+const USE_CHARACTERS_HINT = 'Pass characters: ["<name>", …] on gemini_image_generate / gemini_image_edit / gemini_image_set and the saved ' +
+    'reference image + description are attached to the request automatically — nothing to re-upload and no bytes in the conversation.';
+const USE_STYLE_HINT = 'Pass style: "<name>" on gemini_image_generate / gemini_image_edit / gemini_image_set and the saved prompt fragment ' +
+    '(and reference image, if any) are applied automatically.';
+/**
+ * Resolve the one image source a save call may carry. `image_r2_key` reads the
+ * connector's own store (a signed upload or an earlier generation — tenant
+ * gated); `image_url` is fetched by the server with the same SSRF guards as
+ * `images_url`.
+ */
+async function resolveLibraryImage(client, args, required) {
+    if (args.image_r2_key && args.image_url) {
+        throw new McpToolError('Provide `image_r2_key` OR `image_url`, not both.');
+    }
+    // Raster only, on BOTH sources: library images can be re-signed and served
+    // from /media (the connector's own origin), so a scriptable SVG saved here
+    // would be stored XSS — the same gate the signed-upload path enforces.
+    const rasterOnly = (image) => {
+        if (!acceptableUploadType(image.mimeType)) {
+            throw new McpToolError(`The reference image is "${image.mimeType}", but the library accepts raster images only ` +
+                '(jpeg/png/webp/gif/avif/heic/heif/bmp/tiff — not SVG, which can carry scripts). Convert it to PNG or JPEG first.');
+        }
+        return image;
+    };
+    if (args.image_r2_key) {
+        return rasterOnly(await client.readStoredMedia(args.image_r2_key));
+    }
+    if (args.image_url) {
+        const fetched = await client.fetchRemoteImage(args.image_url);
+        return rasterOnly({ bytes: fetched.bytes, mimeType: fetched.mimeType });
+    }
+    if (required) {
+        throw new McpToolError('Provide the reference image via `image_r2_key` (from gemini_get_upload_url + PUT, or a generation result\'s media[].r2_key) ' +
+            'or `image_url` (a public https URL the server fetches).');
+    }
+    return undefined;
+}
+export function registerLibraryTools(server, client) {
+    const library = client.library;
+    if (!library)
+        return;
+    server.registerTool('gemini_save_character', {
+        description: 'Save a named character to this account\'s persistent reference library: one reference image plus a short ' +
+            'description. Saved characters have NO expiry — unlike uploads (~retention window) and Files API references (~48h) ' +
+            '— so a name saved once keeps working in every later session. Re-saving a name replaces it. ' +
+            USE_CHARACTERS_HINT,
+        annotations: { readOnlyHint: false, openWorldHint: false },
+        inputSchema: {
+            name: NAME_FIELD,
+            description: z
+                .string()
+                .min(1)
+                .describe('Short prose description woven into generation prompts (age, look, defining features, species…)'),
+            image_r2_key: z
+                .string()
+                .min(1)
+                .optional()
+                .describe('Reference image already in this connector\'s store: an `r2_key` from gemini_get_upload_url + PUT, or from a generation result\'s media[].r2_key'),
+            image_url: z.string().url().optional().describe('Reference image as a public https URL the SERVER fetches'),
+        },
+    }, 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({
+            saved: 'character',
+            name: record.name,
+            description: record.description,
+            mime_type: record.mime_type,
+            created_at: record.created_at,
+            updated_at: record.updated_at,
+            hint: USE_CHARACTERS_HINT,
+        });
+    });
+    server.registerTool('gemini_list_characters', {
+        description: 'List this account\'s saved characters (persistent reference library): names, descriptions and timestamps. ' +
+            USE_CHARACTERS_HINT,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: {},
+    }, async () => {
+        const characters = await library.listCharacters();
+        return textResult({
+            count: characters.length,
+            characters: characters.map((c) => ({
+                name: c.name,
+                description: c.description,
+                mime_type: c.mime_type,
+                created_at: c.created_at,
+                updated_at: c.updated_at,
+            })),
+            hint: characters.length
+                ? USE_CHARACTERS_HINT
+                : 'No saved characters yet. Save one with gemini_save_character (image via image_r2_key or image_url).',
+        });
+    });
+    server.registerTool('gemini_delete_character', {
+        description: 'Delete a saved character from this account\'s reference library. Generation calls naming it will then fail until it is re-saved.',
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+        inputSchema: { name: NAME_FIELD, confirm: schemaConfirm },
+    }, async (args) => {
+        const gate = previewUnlessConfirmed(args.confirm, 'Delete a saved character (its reference image and description)', 'DELETE', `characters/${args.name}`);
+        if (gate)
+            return gate;
+        const existed = await library.deleteCharacter(args.name);
+        if (!existed) {
+            throw new McpToolError(`No saved character "${args.name}". List what exists with gemini_list_characters.`);
+        }
+        return textResult({ 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 ' +
+            'optionally a reference image) that a single word then applies to any generation. No expiry; re-saving a name replaces it. ' +
+            USE_STYLE_HINT,
+        annotations: { readOnlyHint: false, openWorldHint: false },
+        inputSchema: {
+            name: NAME_FIELD,
+            prompt_fragment: z
+                .string()
+                .min(1)
+                .describe('The style text appended to generation prompts, e.g. "bold cartoon style, thick outlines, saturated colors"'),
+            image_r2_key: z.string().min(1).optional().describe('Optional style reference image already in this connector\'s store (an r2_key)'),
+            image_url: z.string().url().optional().describe('Optional style reference image as a public https URL the SERVER fetches'),
+        },
+    }, 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({
+            saved: 'style',
+            name: record.name,
+            prompt_fragment: record.prompt_fragment,
+            ...(record.image_key ? { has_reference_image: true } : {}),
+            created_at: record.created_at,
+            updated_at: record.updated_at,
+            hint: USE_STYLE_HINT,
+        });
+    });
+    server.registerTool('gemini_list_styles', {
+        description: 'List this account\'s saved style presets (persistent reference library). ' + USE_STYLE_HINT,
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: {},
+    }, async () => {
+        const styles = await library.listStyles();
+        return textResult({
+            count: styles.length,
+            styles: styles.map((s) => ({
+                name: s.name,
+                prompt_fragment: s.prompt_fragment,
+                ...(s.image_key ? { has_reference_image: true } : {}),
+                created_at: s.created_at,
+                updated_at: s.updated_at,
+            })),
+            hint: styles.length ? USE_STYLE_HINT : 'No saved styles yet. Save one with gemini_save_style.',
+        });
+    });
+    server.registerTool('gemini_delete_style', {
+        description: 'Delete a saved style preset from this account\'s reference library.',
+        annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },
+        inputSchema: { name: NAME_FIELD, confirm: schemaConfirm },
+    }, async (args) => {
+        const gate = previewUnlessConfirmed(args.confirm, 'Delete a saved style preset', 'DELETE', `styles/${args.name}`);
+        if (gate)
+            return gate;
+        const existed = await library.deleteStyle(args.name);
+        if (!existed) {
+            throw new McpToolError(`No saved style "${args.name}". List what exists with gemini_list_styles.`);
+        }
+        return textResult({ deleted: 'style', name: args.name });
+    });
+}

package/dist/tools/music.js

@@ -3,7 +3,7 @@ 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, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const MUSIC_MODELS = ['lyria-3-clip-preview', 'lyria-3-pro-preview'];
@@ -39,6 +39,7 @@ export function registerMusicTools(server, client) {
             timeout_ms: timeoutMsSchema,
             idempotency_key: idempotencyKeySchema,
             async: asyncSchema,
+            max_wait_ms: maxWaitMsSchema,
             confirm: schemaConfirm,
         },
     }, async (args, extra) => {
@@ -67,7 +68,7 @@ export function registerMusicTools(server, client) {
             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 }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
             const { inputs, report } = await resolveImageInputs(args, client);
             const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client.generateMusic({
                 input: args.prompt,

package/dist/tools/set.js

@@ -3,12 +3,13 @@ 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, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emit, 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 { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerSetTools(server, client) {
     server.registerTool('gemini_image_set', {
-        description: 'Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master).',
+        description: 'Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master). ' +
+            'Scene generations run in parallel (reference_mode "master", the default). On the hosted connector: saved `characters` and a saved `style` can seed the whole set by name, multi-image results include a `bundle_url` zip of every image (one curl instead of N), and `max_wait_ms` returns a pollable job handle if the batch runs long.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             master_prompt: z.string().min(1).describe('Prompt for the master/reference image'),
@@ -19,6 +20,9 @@ export function registerSetTools(server, client) {
             master_images: z.array(z.string().min(1)).optional().describe('Reference image paths passed to the master generation call'),
             master_images_url: imagesUrlSchema('Reference images passed to the master AND to every scene call (fetched once)'),
             master_images_file_uris: imagesFileUrisSchema('Reference images passed to the master AND to every scene call'),
+            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'),
             confirm: schemaConfirm,
             ...sharedImageSchema,
@@ -41,8 +45,9 @@ export function registerSetTools(server, client) {
             thinking_level: args.thinking_level, google_search: args.google_search,
             master_images: args.master_images, master_images_base64: args.master_images_base64, from_clipboard: args.from_clipboard,
             master_images_url: args.master_images_url, master_images_file_uris: args.master_images_file_uris,
+            master_images_r2_keys: args.master_images_r2_keys, characters: args.characters, style: args.style,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_image_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_image_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
             const seed = pickSeed(args.seed);
             const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
             const slug = args.basename ? baseName(args.basename) : slugify(args.master_prompt);
@@ -58,9 +63,22 @@ export function registerSetTools(server, client) {
             //  - `masterOnly` — path / base64 / clipboard references. Master-only,
             //    exactly as before these parameters existed, so pre-existing calls
             //    still build byte-identical requests.
-            const carried = await resolveImageInputs({ images_url: args.master_images_url, images_file_uris: args.master_images_file_uris }, client);
+            // Saved characters/style resolve first and fail fast on an unknown
+            // name, before anything billable. Their reference images join the
+            // CARRIED group — consistency references belong on every scene call.
+            const charRefs = await resolveCharacterRefs(client, args.characters, args.style);
+            // The master prompt gets the full library treatment (character
+            // preamble + style fragment). Scene prompts get only the style
+            // fragment: their first attached image is the master output, so the
+            // preamble's "attached in order" claim would be off by one there —
+            // the master image itself is what anchors identity scene to scene.
+            const masterPrompt = composePrompt(args.master_prompt, charRefs);
+            const styleOnly = { styleFragment: charRefs.styleFragment };
+            const carried = await resolveImageInputs({ images_url: args.master_images_url, images_file_uris: args.master_images_file_uris, images_r2_keys: args.master_images_r2_keys }, client);
+            /** What every SCENE call attaches (after its master/previous image). */
+            const carriedRefs = [...charRefs.inputs, ...carried.inputs];
             const masterOnly = await resolveImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard }, client);
-            const masterRefInputs = [...masterOnly.inputs, ...carried.inputs];
+            const masterRefInputs = [...charRefs.inputs, ...masterOnly.inputs, ...carried.inputs];
             /** Scenes that failed, so one bad scene cannot lose the whole batch. */
             const failed = [];
             const report = carried.report || masterOnly.report
@@ -69,7 +87,7 @@ export function registerSetTools(server, client) {
             const named = [];
             const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
                 const result = await client.generate({
-                    prompt: args.master_prompt,
+                    prompt: masterPrompt,
                     images: masterRefInputs.length > 0 ? masterRefInputs : undefined,
                     seed,
                     ...cfg,
@@ -99,7 +117,7 @@ export function registerSetTools(server, client) {
                     let ref = master;
                     for (let i = 0; i < scenePrompts.length; i++) {
                         try {
-                            const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
+                            const { images: [img] } = await client.generate({ prompt: composePrompt(scenePrompts[i], styleOnly), images: [ref, ...carriedRefs], seed: seed + i + 1, ...cfg });
                             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
@@ -112,7 +130,7 @@ export function registerSetTools(server, client) {
                     }
                 }
                 else {
-                    const settled = await Promise.allSettled(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master, ...carried.inputs], 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) => r.images[0])));
                     settled.forEach((outcome, i) => {
                         if (outcome.status === 'fulfilled')
                             named.push({ image: outcome.value, base: sceneName(i) });
@@ -130,6 +148,8 @@ export function registerSetTools(server, client) {
                 meta.grounding = masterResult.grounding;
             if (report)
                 meta.image_inputs = report;
+            if (charRefs.meta)
+                Object.assign(meta, charRefs.meta);
             if (failed.length) {
                 meta.failed_scenes = failed;
                 meta.partial =
@@ -142,7 +162,15 @@ export function registerSetTools(server, client) {
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client.mediaSink?.persistsFiles });
             if (risk)
                 meta.timeout_risk = risk;
-            return emit(named, { ...args, sink: client.mediaSink }, meta);
+            // One zip of the whole set (object-storage sinks, >1 image) — the
+            // consumer runs ONE curl instead of N. Best-effort; per-image URLs and
+            // curl_hints below are unaffected.
+            if (!args.inline)
+                Object.assign(meta, await persistBundle(named, client.mediaSink, slug));
+            // 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);
         });
     });
 }