@chrischall/gemini-mcp 1.3.0 → 1.5.0

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,16 +63,31 @@ 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
                 ? { ...masterOnly.report, ...carried.report }
                 : undefined;
             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,
@@ -79,17 +99,44 @@ export function registerSetTools(server, client) {
                 // 2. scene prompts (explicit, or N repeats of master_prompt for variations)
                 const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
                 const mode = args.reference_mode ?? 'master';
+                // A set is N+1 billed generations in one tools/call, and any one of
+                // them can fail — a safety filter on a single scene, a transient 5xx.
+                // `Promise.all` rejected the whole batch on the first failure, losing
+                // the master and every scene that HAD succeeded, and surfaced as an
+                // opaque "Error occurred during tool execution" with no indication of
+                // which scene or why. Failures are collected per scene instead.
+                const sceneName = (i) => `${slug}-${String(i + 1).padStart(2, '0')}`;
+                const record = (err, i) => {
+                    failed.push({
+                        scene: i + 1,
+                        prompt: scenePrompts[i],
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                };
                 if (mode === 'chain') {
                     let ref = master;
                     for (let i = 0; i < scenePrompts.length; i++) {
-                        const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
-                        named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` });
-                        ref = img;
+                        try {
+                            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
+                            // continues from the last image that actually exists.
+                            ref = img;
+                        }
+                        catch (err) {
+                            record(err, i);
+                        }
                     }
                 }
                 else {
-                    const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
-                    scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '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) });
+                        else
+                            record(outcome.reason, i);
+                    });
                 }
                 return result;
             });
@@ -101,12 +148,29 @@ 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 =
+                    `${failed.length} of ${failed.length + named.length - 1} scene(s) failed; the master and the ` +
+                        `${named.length - 1} scene(s) that succeeded are returned above. Re-run just the failed prompts rather than the whole set — ` +
+                        'each failure message is in failed_scenes.';
+            }
             // A set is master + N scenes in one tools/call — the most timeout-prone
             // tool. Effective image count drives the risk hint.
             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);
         });
     });
 }

package/dist/tools/shared.js

@@ -1,9 +1,11 @@
 import { z } from 'zod';
 import { textResult, McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveVideoPath, videoMimeType } from '../images.js';
-import { IMAGE_URL_MAX_BYTES } from '../fetch-image.js';
-import { wholeMb } from '../bytes.js';
+import { IMAGE_URL_MAX_BYTES, IMAGE_INLINE_MAX_BYTES } from '../fetch-image.js';
+import { bytesToBase64, base64ToBytes, wholeMb } from '../bytes.js';
 import { createDiskSink } from '../storage/media.js';
+import { downloadFilename } from '../media-endpoint.js';
+import { buildZip } from '../zip.js';
 /**
  * Fallback sink for call sites that pass no explicit one (every pre-existing
  * test, and any caller constructed before the sink seam existed). The stdio
@@ -54,6 +56,136 @@ 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 (jobs are per-process and expire ~10 min after completion).');
+/**
+ * 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
+ * (the work continues; the caller polls `gemini_get_result`). The middle
+ * ground between fully synchronous and `async: true`.
+ */
+export const maxWaitMsSchema = z
+    .number()
+    .int()
+    .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.');
+/**
+ * Reference images already in THIS connector's object store, by `r2_key`.
+ * Hosted connector only — the server reads its own bucket (tenant-gated), so
+ * no bytes enter the conversation and no signed URL is needed.
+ */
+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.');
+}
+/** 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.');
+/** 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.');
+/**
+ * Turn `characters: ["finn", …]` / `style: "…"` into reference-image inputs
+ * plus prompt text, from the account's saved library.
+ *
+ * A name that is not saved fails BEFORE any billable call, and names what IS
+ * saved — a generation silently missing its reference is a wasted charge that
+ * looks like a model failure.
+ */
+export async function resolveCharacterRefs(client, names, styleName) {
+    if (!names?.length && !styleName)
+        return { inputs: [] };
+    const library = client.library;
+    if (!library) {
+        throw new McpToolError('`characters` / `style` reference this account\'s saved library, which exists on the hosted connector only. ' +
+            'On this server pass the reference images directly (images / images_url / images_file_uris) and put the style text in the prompt.');
+    }
+    const inputs = [];
+    const described = [];
+    // Same size rule as every other funnel: a large reference is promoted to a
+    // Files API reference rather than inlined — generateContent caps a whole
+    // request near 20MB, and a crew of full-resolution characters would hit it.
+    const toInput = async (image, displayName) => {
+        if (image.bytes.byteLength <= IMAGE_INLINE_MAX_BYTES) {
+            return { base64: bytesToBase64(image.bytes), mimeType: image.mimeType };
+        }
+        const uploaded = await client.uploadBytes(image.bytes, image.mimeType, displayName);
+        return { uri: uploaded.uri, mimeType: uploaded.mimeType };
+    };
+    for (const name of names ?? []) {
+        const record = await library.getCharacter(name);
+        const image = record && (await library.readCharacterImage(name));
+        if (!record || !image) {
+            const available = (await library.listCharacters()).map((c) => c.name);
+            throw new McpToolError(`No saved character "${name}". ` +
+                (available.length ? `Saved characters: ${available.join(', ')}. ` : 'None are saved yet. ') +
+                'Save one with gemini_save_character.');
+        }
+        inputs.push(await toInput(image, name));
+        described.push(`${record.name} — ${record.description}`);
+    }
+    let styleFragment;
+    let styleImageAttached = false;
+    if (styleName) {
+        const record = await library.getStyle(styleName);
+        if (!record) {
+            const available = (await library.listStyles()).map((s) => s.name);
+            throw new McpToolError(`No saved style "${styleName}". ` +
+                (available.length ? `Saved styles: ${available.join(', ')}. ` : 'None are saved yet. ') +
+                'Save one with gemini_save_style.');
+        }
+        styleFragment = record.prompt_fragment;
+        if (record.image_key) {
+            const image = await library.readStyleImage(styleName);
+            if (image) {
+                inputs.push(await toInput(image, styleName));
+                styleImageAttached = true;
+            }
+        }
+    }
+    // The style note is POSITIONAL, never "the final attached image": every
+    // caller appends the caller's own reference images (images / images_url /
+    // images_file_uris / images_r2_keys) AFTER these inputs, so a "final image"
+    // claim would point the model at the caller's last subject photo whenever
+    // characters/style are combined with direct references. These inputs always
+    // lead the attachment order, so index-based wording stays true regardless
+    // of what follows.
+    const characterLine = described.length
+        ? `Use the attached reference images for these characters, in order: ${described
+            .map((d, i) => `(${i + 1}) ${d}`)
+            .join('; ')}. Keep each character visually consistent with their reference image.` +
+            (styleImageAttached ? ` Attached image (${described.length + 1}) is a style reference, not a character.` : '')
+        : styleImageAttached
+            ? 'The first attached image is a style reference.'
+            : undefined;
+    const meta = {};
+    if (names?.length)
+        meta.characters = names;
+    if (styleName)
+        meta.style = styleName;
+    return { inputs, characterLine, styleFragment, meta: Object.keys(meta).length ? meta : undefined };
+}
+/** Compose the effective prompt from the caller's text + library lines. */
+export function composePrompt(prompt, refs) {
+    return [refs.characterLine, prompt, refs.styleFragment ? `Style: ${refs.styleFragment}` : undefined]
+        .filter(Boolean)
+        .join('\n\n');
+}
 /**
  * Reference images the SERVER fetches, so the bytes never pass through the
  * model's context window. Defined once and reused under both the `images_url`
@@ -104,6 +236,7 @@ export const sharedImageSchema = {
     timeout_ms: timeoutMsSchema,
     idempotency_key: idempotencyKeySchema,
     async: asyncSchema,
+    max_wait_ms: maxWaitMsSchema,
 };
 /**
  * Turn the `video_url` / `video_path` tool args into the client's video opts.
@@ -267,6 +400,7 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
     const sink = opts.sink ?? DEFAULT_SINK;
     const persisted = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
         output_dir: opts.output_dir,
+        urlTtlMs: opts.urlTtlMs,
     });
     const refs = persisted.map((p) => p.ref);
     // `onWritten` (sidecars, the written-outputs set) is meaningful only when the
@@ -300,6 +434,12 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
                 url: p.ref,
                 ...(p.key ? { r2_key: p.key } : {}),
                 ...(p.expiresAt ? { expires_at: p.expiresAt } : {}),
+                // A ready-to-run command, not a description of one. Models copy an
+                // exact string far more reliably than they compose one — and in a
+                // chat client this download-then-attach flow is the ONLY way the end
+                // user actually sees the image (inline MCP blocks and markdown embeds
+                // both render for the model and not for them).
+                ...(p.key ? { curl_hint: `curl -sS -o ${downloadFilename(p.key)} "${p.ref}"` } : {}),
             })),
         }
         : {};
@@ -313,6 +453,66 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
 export async function emit(named, opts, meta, onWritten) {
     return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), 'image', opts, meta, onWritten);
 }
+/**
+ * Signed-URL lifetime for MULTI-image results (and their bundle zip) on
+ * object-storage sinks: ~7 days rather than the default ~48h, clamped by the
+ * sink to the retention window. A set is a batch someone comes back to; its
+ * links dying in two days while the objects live seven served nobody.
+ */
+export const SET_URL_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/**
+ * Total DECODED size cap for bundling a set into a zip. Zipping holds roughly
+ * 4× the set's bytes at peak (the decoded copies, the STORE zip, and the
+ * zip's own base64) on top of the base64 strings the result already carries —
+ * and a Cloudflare isolate gets ~128MB, where an OOM kill is uncatchable, so
+ * the try/catch in {@link persistBundle} cannot honor its best-effort promise
+ * against it. The guard runs on sizes ESTIMATED from base64 length, before a
+ * single byte is decoded.
+ */
+export const BUNDLE_MAX_TOTAL_BYTES = 24 * 1024 * 1024;
+/**
+ * Bundle a multi-image result into ONE downloadable zip and return the meta
+ * fields to merge into the result (`bundle_url` + a detailed `bundle` object).
+ *
+ * Object-storage sinks only, and only when there is more than one image — the
+ * point is turning N downloads into one `curl`, which a single image already
+ * is. Best-effort: a result that cost N billable generations must never fail
+ * because zipping or storing the bundle did — but a skipped bundle is SAID
+ * (`bundle_skipped`), never silently absent, so the caller falls back to the
+ * per-image URLs instead of hunting for a field that will never appear.
+ */
+export async function persistBundle(named, sink, base) {
+    if (!sink || sink.persistsFiles || named.length < 2)
+        return {};
+    const totalBytes = named.reduce((sum, n) => sum + Math.floor((n.image.base64.length * 3) / 4), 0);
+    if (totalBytes > BUNDLE_MAX_TOTAL_BYTES) {
+        return {
+            bundle_skipped: `The set totals ~${wholeMb(totalBytes)}MB decoded, over the ${wholeMb(BUNDLE_MAX_TOTAL_BYTES)}MB bundling cap ` +
+                '(zipping peaks at ~4x that in Worker memory). Download the images individually via their media urls / curl_hints.',
+        };
+    }
+    try {
+        const { mediaExt } = await import('../images.js');
+        const zip = buildZip(named.map((n) => ({ name: `${n.base}.${mediaExt(n.image.mimeType)}`, bytes: base64ToBytes(n.image.base64) })));
+        const [persisted] = await sink.persist([{ base: `${base}-bundle`, base64: bytesToBase64(zip), mimeType: 'application/zip' }], { urlTtlMs: SET_URL_TTL_MS });
+        if (!persisted || persisted.unavailable) {
+            return { bundle_skipped: 'The bundle zip could not be stored; the images themselves are unaffected — download them individually via their media urls / curl_hints.' };
+        }
+        return {
+            bundle_url: persisted.ref,
+            bundle: {
+                url: persisted.ref,
+                ...(persisted.key ? { r2_key: persisted.key } : {}),
+                ...(persisted.expiresAt ? { expires_at: persisted.expiresAt } : {}),
+                files: named.map((n) => n.base),
+                ...(persisted.key ? { curl_hint: `curl -sS -o ${downloadFilename(persisted.key)} "${persisted.ref}"` } : {}),
+            },
+        };
+    }
+    catch {
+        return { bundle_skipped: 'Bundling failed; the images themselves are unaffected — download them individually via their media urls / curl_hints.' };
+    }
+}
 /**
  * Inputs that can only come off a local filesystem. On the hosted connector
  * (a Cloudflare Worker) none of them exist: