@chrischall/gemini-mcp 1.3.0 → 1.5.0

package/dist/put-endpoint.js

@@ -0,0 +1,122 @@
+import { loadSigningKey } from './media-url.js';
+import { verifyUploadSignature, UPLOAD_MAX_BYTES, UPLOAD_KEY_PREFIX, acceptableUploadType } from './upload-url.js';
+import { wholeMb } from './bytes.js';
+function json(body, status) {
+    return new Response(JSON.stringify(body, null, 2), {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+    });
+}
+/** Every error names the fix — the caller here is a shell, not a model. */
+function fail(status, error, hint) {
+    return json({ error, hint }, status);
+}
+/** A key this endpoint is willing to even verify a signature for: the upload
+ * prefix, safe segment charset, no dot-segments, no empty segments. */
+export function wellFormedUploadKey(key) {
+    if (!key.startsWith(`${UPLOAD_KEY_PREFIX}/`))
+        return false;
+    const segments = key.split('/');
+    if (segments.length < 2)
+        return false;
+    return segments.every((s) => s.length > 0 && s !== '.' && s !== '..' && /^[A-Za-z0-9._-]+$/.test(s));
+}
+/**
+ * Build the `/put` handler. `basePath` is stripped from the pathname to get the
+ * R2 key, mirroring the `/media` handler so the two never drift.
+ */
+export function createSignedPutHandler(env, basePath = '/put/') {
+    const maxBytes = env.maxBytes ?? UPLOAD_MAX_BYTES;
+    return async function handleSignedPut(request) {
+        if (request.method === 'OPTIONS') {
+            return new Response(null, { status: 204, headers: { allow: 'PUT, OPTIONS' } });
+        }
+        if (request.method !== 'PUT') {
+            return fail(405, `Method ${request.method} not allowed; signed upload URLs are PUT-only.`, 'Send the file bytes with: curl -sS -X PUT -H "Content-Type: <the signed type>" --data-binary @photo.jpg "<upload_url>"');
+        }
+        const url = new URL(request.url);
+        if (!url.pathname.startsWith(basePath))
+            return fail(404, 'Not found.', 'Use the exact upload_url returned by gemini_get_upload_url.');
+        const key = url.pathname
+            .slice(basePath.length)
+            .split('/')
+            .map((segment) => {
+            try {
+                return decodeURIComponent(segment);
+            }
+            catch {
+                return segment;
+            }
+        })
+            .join('/');
+        // Charset-checked BEFORE signature verification: the cross-protocol safety
+        // argument in upload-url.ts rests on keys never containing control chars.
+        if (!wellFormedUploadKey(key)) {
+            return fail(404, 'Not a valid upload key.', 'Use the exact upload_url returned by gemini_get_upload_url — the key path cannot be altered.');
+        }
+        const ct = url.searchParams.get('ct');
+        if (ct && !acceptableUploadType(ct)) {
+            return fail(415, `Unsupported content type "${ct}" — signed uploads accept raster image types only ` +
+                '(jpeg/png/webp/gif/avif/heic/heif/bmp/tiff; not SVG, which can carry scripts).', 'Mint the URL with a raster image content_type (e.g. image/jpeg).');
+        }
+        const now = env.now?.() ?? Date.now();
+        // Read-only key load: verification must never CREATE a signing secret (see
+        // loadSigningKey — a stale KV read would clobber the secret every
+        // outstanding media link was signed with).
+        const signingKey = await loadSigningKey(env.secret, env.store);
+        const check = signingKey
+            ? await verifyUploadSignature(signingKey, key, ct, url.searchParams.get('exp'), url.searchParams.get('sig'), now)
+            : { ok: false, reason: 'invalid' };
+        if (!check.ok) {
+            if (check.reason === 'expired') {
+                return fail(410, 'This upload URL has expired (they are valid for ~10 minutes).', 'Mint a fresh one with gemini_get_upload_url and retry.');
+            }
+            return fail(403, 'Invalid or missing upload signature.', 'Use the upload_url exactly as returned by gemini_get_upload_url, including the ct, exp and sig query parameters.');
+        }
+        const sentType = (request.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+        if (sentType !== ct) {
+            return fail(415, `Content-Type "${sentType || '(none)'}" does not match the type this URL was minted for ("${ct}").`, `Send -H "Content-Type: ${ct}", or mint a new URL with the right content_type.`);
+        }
+        const declared = Number(request.headers.get('content-length'));
+        if (!request.headers.get('content-length') || !Number.isFinite(declared) || declared <= 0) {
+            return fail(411, 'Content-Length is required (and must be > 0).', 'curl sets it automatically with --data-binary @file.');
+        }
+        if (declared > maxBytes) {
+            return fail(413, `Upload is ${wholeMb(declared)}MB; the cap is ${wholeMb(maxBytes)}MB.`, 'Downscale the image before uploading — a reference photo does not need to be full-resolution.');
+        }
+        if (!request.body) {
+            return fail(400, 'Request had no body.', 'Send the file bytes as the request body, e.g. --data-binary @photo.jpg.');
+        }
+        // Enforce the cap on bytes actually READ, not the declared length — a
+        // hostile client can under-declare and stream more.
+        const chunks = [];
+        let total = 0;
+        const reader = request.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => { });
+                return fail(413, `Upload exceeded the ${wholeMb(maxBytes)}MB cap while being read.`, 'Downscale the image before uploading.');
+            }
+            chunks.push(value);
+        }
+        const body = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        await env.bucket.put(key, body, { httpMetadata: { contentType: ct ?? 'application/octet-stream' } });
+        return json({
+            r2_key: key,
+            size_bytes: total,
+            content_type: ct,
+            hint: `Uploaded. Reference it by r2_key: pass it in images_r2_keys on a generation tool (master_images_r2_keys on gemini_image_set), ` +
+                `save it permanently with gemini_save_character, or convert it to a ~48h Gemini Files API reference with gemini_upload_file({ r2_key }). ` +
+                `Uploads follow the connector's media retention schedule (MEDIA_TTL_DAYS, default 7 days); saved characters are kept indefinitely.`,
+        }, 201);
+    };
+}

package/dist/storage/media.js

@@ -36,11 +36,16 @@ export function createDiskSink() {
         note: () => undefined,
     };
 }
+/** Stable, non-reversible short tenant id from a per-session secret. */
+export async function tenantIdFor(secret) {
+    const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(secret));
+    return [...new Uint8Array(digest).slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
 // `gen`, not `media`: the objects are served at `/media/<key>`, and a `media`
 // prefix would make every URL read `/media/media/…`.
 const KEY_PREFIX_DEFAULT = 'gen';
 /** Object-key-safe name: no slashes, no dot-segments, never empty. */
-function safeKeySegment(base) {
+export function safeKeySegment(base) {
     const cleaned = base
         .replace(/[^A-Za-z0-9._-]+/g, '-')
         .replace(/\.{2,}/g, '-')
@@ -62,19 +67,63 @@ export function createR2Sink(bucket, opts) {
     const publicBase = opts.publicBaseUrl?.replace(/\/+$/, '');
     const signedBase = opts.signedBaseUrl?.replace(/\/+$/, '');
     const ttlMs = opts.urlTtlMs ?? 0;
+    const readPrefixes = [prefix, ...(opts.readPrefixes ?? [])];
+    let tenantCache;
+    const tenantId = () => (tenantCache ??= Promise.resolve(typeof opts.tenant === 'function' ? opts.tenant() : opts.tenant));
+    /** `<prefix>/` or `<prefix>/<tenant>/` — where every WRITE goes. */
+    const ownPrefix = async () => {
+        const tenant = await tenantId();
+        return tenant ? `${prefix}/${tenant}/` : `${prefix}/`;
+    };
+    /**
+     * Ownership gate for caller-supplied keys: this session's own namespace
+     * under any readable prefix (`gen/<tenant>/…`, plus e.g. `up/`/`lib/` on the
+     * Worker). A foreign key is refused without touching storage, so the refusal
+     * is indistinguishable from a swept object. With no tenant configured there
+     * is nothing to enforce (single-user shapes).
+     */
+    const owned = async (key) => {
+        if (!opts.tenant)
+            return true;
+        const tenant = await tenantId();
+        return readPrefixes.some((p) => key.startsWith(`${p}/${tenant}/`));
+    };
     return {
         kind: 'r2',
         persistsFiles: false,
-        async persist(items, _opts) {
+        async read(key) {
+            if (!bucket.get || !(await owned(key)))
+                return undefined;
+            const object = await bucket.get(key);
+            if (!object)
+                return undefined;
+            return {
+                bytes: new Uint8Array(await object.arrayBuffer()),
+                mimeType: object.httpMetadata?.contentType ?? 'application/octet-stream',
+            };
+        },
+        async resign(key) {
+            if (!(await owned(key)))
+                return undefined;
+            // Only for objects that still exist — re-signing a swept key would hand
+            // back a link that 404s, which is no better than the expired one.
+            if (bucket.get && !(await bucket.get(key)))
+                return undefined;
+            return describe(key, now().getTime() + ttlMs);
+        },
+        async persist(items, persistOpts) {
             // `mediaExt` is pure string work but lives in images.ts next to node:fs
             // imports; the dynamic import keeps that module off a Worker's eager
             // module graph.
             const { mediaExt } = await import('../images.js');
+            const keyBase = await ownPrefix();
             const day = now().toISOString().slice(0, 10);
-            const expiresAtMs = now().getTime() + ttlMs;
+            // Per-persist TTL override, clamped so a link never outlives its object.
+            const effectiveTtlMs = Math.min(persistOpts.urlTtlMs ?? ttlMs, opts.maxUrlTtlMs ?? Infinity);
+            const expiresAtMs = now().getTime() + effectiveTtlMs;
             const refs = [];
             for (const it of items) {
-                const key = `${prefix}/${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;
+                const key = `${keyBase}${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;
                 await bucket.put(key, base64ToBytes(it.base64), { httpMetadata: { contentType: it.mimeType } });
                 refs.push(await describe(key, expiresAtMs));
             }

package/dist/tools/files.js

@@ -3,6 +3,7 @@ import { McpToolError, textResult } from '@chrischall/mcp-utils';
 import { withProgressHeartbeat } from './shared.js';
 import { base64ToBytes, wholeMb } from '../bytes.js';
 import { fileNameFromUrl } from '../fetch-image.js';
+import { downloadFilename } from '../media-endpoint.js';
 import { previewUnlessConfirmed, previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 /**
  * First-class Gemini Files API access.
@@ -70,7 +71,9 @@ export function registerFileTools(server, client) {
             'Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever ' +
             'enter the conversation, and it can be reused across many generations until it expires (~48h). ' +
             'Provide exactly one of `url` (the server downloads it), `data_base64`' +
-            (onDisk ? ', or `path` (a local file).' : '.') +
+            (onDisk
+                ? ', or `path` (a local file).'
+                : ', or `r2_key` (re-upload media this connector generated, from media[].r2_key in an earlier result).') +
             (onDisk
                 ? ''
                 : ' This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header ' +
@@ -89,6 +92,16 @@ export function registerFileTools(server, client) {
                 .min(1)
                 .optional()
                 .describe('Raw base64 or a data: URI. Last resort — this is the one form that costs model context (~14k tokens for a modest JPEG).'),
+            r2_key: z
+                .string()
+                .min(1)
+                .optional()
+                .describe(onDisk
+                ? 'Unavailable on this server (media is written to local disk) — pass the file path via `path` instead.'
+                : 'An `r2_key` from a previous generation result (media[].r2_key) — re-uploads media THIS connector generated, ' +
+                    'so a generated image can become a reference image in one cheap call. The server reads its own bucket directly: ' +
+                    'no HTTP request, no signed URL, and no expiry to worry about. Do NOT pass a /media URL as `url` for this — ' +
+                    'that would be the connector fetching itself and needs a signature.'),
             path: z
                 .string()
                 .min(1)
@@ -105,10 +118,10 @@ export function registerFileTools(server, client) {
             confirm: schemaConfirm,
         },
     }, async (args, extra) => {
-        const sources = [args.url && 'url', args.data_base64 && 'data_base64', args.path && 'path'].filter(Boolean);
+        const sources = [args.url && 'url', args.data_base64 && 'data_base64', args.r2_key && 'r2_key', args.path && 'path'].filter(Boolean);
         if (sources.length !== 1) {
             throw new McpToolError(sources.length === 0
-                ? 'Provide exactly one of `url`, `data_base64`' + (onDisk ? ' or `path`.' : '.')
+                ? 'Provide exactly one of `url`, `data_base64`' + (onDisk ? ' or `path`.' : ' or `r2_key`.')
                 : `Provide exactly one source, not ${sources.length} (${sources.join(', ')}).`);
         }
         if (args.path) {
@@ -131,6 +144,17 @@ export function registerFileTools(server, client) {
                 // this tool takes video and audio too, so 'image' would be a lie.
                 args.display_name ?? fileNameFromUrl(args.url, 'upload'));
             }
+            if (args.r2_key) {
+                if (onDisk) {
+                    throw new McpToolError('`r2_key` is only available on the hosted connector — this server writes media to local disk, ' +
+                        'so pass the generated file via `path` instead.');
+                }
+                // Reading our own bucket rather than fetching our own /media URL. A
+                // self-fetch would need a signature the caller cannot mint, which is
+                // exactly the 403 loop this parameter exists to remove.
+                const stored = await client.readStoredMedia(args.r2_key);
+                return client.uploadBytes(stored.bytes, args.mime_type ?? stored.mimeType, args.display_name ?? downloadFilename(args.r2_key));
+            }
             if (args.data_base64) {
                 const { decodeImageInput } = await import('../images.js');
                 const decoded = decodeImageInput(args.data_base64);
@@ -171,6 +195,40 @@ export function registerFileTools(server, client) {
                 : 'No files uploaded (or all have expired — retention is ~48h). Upload one with gemini_upload_file.',
         });
     });
+    // Hosted connector only. On a disk-backed server the result carries a path
+    // that never expires, so a "refresh my link" tool would only ever error —
+    // don't advertise it there (mirrors the Worker not registering video).
+    if (!onDisk) {
+        server.registerTool('gemini_sign_media', {
+            description: 'Mint a FRESH signed URL for media this connector generated, from its `r2_key`. ' +
+                'Signed media links expire well before the object behind them is cleaned up, so an expired link is not a dead ' +
+                'end — re-sign it instead of re-generating (and re-paying for) the image. Keywords: expired link, refresh url, ' +
+                're-sign, media url, download again.',
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            inputSchema: {
+                r2_key: z.string().min(1).describe('The `media[].r2_key` from an earlier generation result'),
+            },
+        }, async (args) => {
+            const sink = client.mediaSink;
+            if (!sink?.resign) {
+                throw new McpToolError('This server does not serve media URLs — generated files are written to disk and the path in the result is already usable.', {
+                    hint: 'gemini_sign_media applies to the hosted connector only.',
+                });
+            }
+            const fresh = await sink.resign(args.r2_key.trim());
+            if (!fresh) {
+                // Remediation goes in the MESSAGE: MCP serialization drops hints.
+                throw new McpToolError(`No stored media for r2_key "${args.r2_key}" — it has probably passed its retention window. Re-run the generation to get a new one.`, { hint: 'Objects are swept on a retention schedule (MEDIA_TTL_DAYS, default 7 days).' });
+            }
+            return textResult({
+                url: fresh.ref,
+                r2_key: fresh.key,
+                ...(fresh.expiresAt ? { expires_at: fresh.expiresAt } : {}),
+                curl_hint: `curl -sS -o ${downloadFilename(fresh.key ?? 'media')} "${fresh.ref}"`,
+                hint: 'In a Claude chat client, download this URL into your sandbox and present it as an output file — inline image blocks and markdown embeds do not render for the end user.',
+            });
+        });
+    }
     server.registerTool('gemini_delete_file', {
         description: 'Delete an uploaded file, image or photo (by file_uri) from the Gemini Files API before its ~48h expiry. Any tool call still referencing it ' +
             'will then fail with a generic 404, so delete only references you are finished with.',

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));
@@ -66,31 +76,46 @@ export function registerGenerateTools(server, client) {
             // For count>1, surface the FIRST call's grounding (each call grounds
             // independently; one representative set of sources beats concatenating N).
             let capturedGrounding;
+            // count>1 is N billed generations in one tools/call, and any one can
+            // fail (a safety filter, a transient 5xx). Failures are collected per
+            // image so one bad draw cannot lose the ones that succeeded — same
+            // contract as gemini_image_set's failed_scenes. Zero successes still
+            // throws: an empty success is worse than an error.
+            const failed = [];
+            let firstError;
             await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : 'image'} (${model})`, async () => {
                 for (let i = 0; i < count; i++) {
-                    // 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,
-                        images: refInputs.length > 0 ? refInputs : undefined,
-                        model: args.model,
-                        aspectRatio: args.aspect_ratio,
-                        imageSize: args.image_size,
-                        seed: seed + i,
-                        thinkingLevel: args.thinking_level,
-                        googleSearch: args.google_search,
-                        videoUrl: video.videoUrl,
-                        videoMimeType: video.videoMimeType,
-                        timeoutMs: args.timeout_ms,
-                    });
-                    const { images: [img], text } = result;
-                    if (text && !capturedText)
-                        capturedText = text;
-                    if (result.grounding && !capturedGrounding)
-                        capturedGrounding = result.grounding;
-                    named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, '0')}` });
+                    try {
+                        // 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,
+                            images: refInputs.length > 0 ? refInputs : undefined,
+                            model: args.model,
+                            aspectRatio: args.aspect_ratio,
+                            imageSize: args.image_size,
+                            seed: seed + i,
+                            thinkingLevel: args.thinking_level,
+                            googleSearch: args.google_search,
+                            videoUrl: video.videoUrl,
+                            videoMimeType: video.videoMimeType,
+                            timeoutMs: args.timeout_ms,
+                        });
+                        const { images: [img], text } = result;
+                        if (text && !capturedText)
+                            capturedText = text;
+                        if (result.grounding && !capturedGrounding)
+                            capturedGrounding = result.grounding;
+                        named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, '0')}` });
+                    }
+                    catch (err) {
+                        firstError ??= err;
+                        failed.push({ image: i + 1, error: err instanceof Error ? err.message : String(err) });
+                    }
                 }
             });
+            if (named.length === 0)
+                throw firstError;
             const meta = buildMeta(model, seed, args);
             if (capturedText)
                 meta.text = capturedText;
@@ -98,6 +123,14 @@ 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 =
+                    `${failed.length} of ${count} image(s) failed; the ${named.length} that succeeded are returned above. ` +
+                        'Re-run with count set to the shortfall rather than the whole batch — each failure message is in failed_images.';
+            }
             if (video.videoFileMeta)
                 meta.video_file = video.videoFileMeta;
             meta.hint = REFINE_HINT;
@@ -118,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);
@@ -136,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,
@@ -161,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 = {