@chrischall/gemini-mcp 1.4.0 → 1.5.0

package/dist/inputs.js

@@ -7,6 +7,7 @@ export function hasImageInput(args) {
         args.images_base64?.length ||
         args.images_url?.length ||
         args.images_file_uris?.length ||
+        args.images_r2_keys?.length ||
         args.from_clipboard);
 }
 /** Conservative TTL when the API doesn't tell us: documented retention is ~48h. */
@@ -75,6 +76,40 @@ export async function resolveImageInputs(args, client) {
         (report.file_uris ??= []).push(file.name);
         inputs.push(input);
     }
+    // 6. r2_keys — the connector reads its OWN store (tenant-gated), so a signed
+    // upload or an earlier generation becomes a reference without a fetch, a
+    // signature, or a byte in the conversation. Deduped within the call, same as
+    // URLs, and — also same as URLs — a large object is promoted to a Files API
+    // reference rather than inlined, because `generateContent` caps a whole
+    // request near 20MB and two large inline references would fail it.
+    // `readStoredMedia` throws an actionable error for a swept/foreign key.
+    const seenKeys = new Map();
+    for (const key of args.images_r2_keys ?? []) {
+        const hit = seenKeys.get(key);
+        if (hit) {
+            inputs.push(hit);
+            continue;
+        }
+        const stored = await client.readStoredMedia(key);
+        const entry = {
+            r2_key: key.trim(),
+            mime_type: stored.mimeType,
+            bytes: stored.bytes.byteLength,
+        };
+        (report.r2_keys ??= []).push(entry);
+        let input;
+        if (stored.bytes.byteLength <= IMAGE_INLINE_MAX_BYTES) {
+            input = { base64: bytesToBase64(stored.bytes), mimeType: stored.mimeType };
+        }
+        else {
+            const displayName = key.trim().split('/').pop() || 'image';
+            const uploaded = await client.uploadBytes(stored.bytes, stored.mimeType, displayName);
+            entry.file_uri = uploaded.name;
+            input = { uri: uploaded.uri, mimeType: uploaded.mimeType };
+        }
+        seenKeys.set(key, input);
+        inputs.push(input);
+    }
     return { inputs, report: Object.keys(report).length > 0 ? report : undefined };
 }
 /**
@@ -161,5 +196,6 @@ export function requireImageInput(args) {
     if (hasImageInput(args))
         return;
     throw new McpToolError('Provide at least one input image via `images_url` (an https URL the server fetches), `images_file_uris` ' +
-        '(from gemini_upload_file), `images` (a local path), `images_base64`, or `from_clipboard`.');
+        '(from gemini_upload_file), `images_r2_keys` (a hosted-connector upload or earlier generation), ' +
+        '`images` (a local path), `images_base64`, or `from_clipboard`.');
 }

package/dist/jobs.js

@@ -86,6 +86,25 @@ async function refreshMedia(result, sink) {
     body.media = entries;
     if (mediaKeyName)
         body[mediaKeyName] = refs;
+    // A multi-image set also carries a bundle zip; its link expires like any
+    // other and re-signs from its own r2_key. Best-effort, like the rest.
+    const bundle = body.bundle;
+    if (bundle && typeof bundle.r2_key === 'string') {
+        try {
+            const fresh = await sink.resign(bundle.r2_key);
+            if (fresh) {
+                const { expires_at: _staleBundle, ...rest } = bundle;
+                body.bundle = {
+                    ...rest,
+                    url: fresh.ref,
+                    ...(fresh.expiresAt ? { expires_at: fresh.expiresAt } : {}),
+                    curl_hint: `curl -sS -o ${downloadFilename(fresh.key ?? 'media')} "${fresh.ref}"`,
+                };
+                body.bundle_url = fresh.ref;
+            }
+        }
+        catch { /* an un-refreshed bundle link is still a valid replay */ }
+    }
     body.media_urls_refreshed = true;
     return { ...result, content: [{ ...first, text: JSON.stringify(body, null, 2) }, ...(result.content ?? []).slice(1)] };
 }
@@ -119,6 +138,19 @@ function jobHandle(jobId, status) {
         hint: `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done" (results are per-process and expire ~10 min after completion).`,
     });
 }
+/**
+ * Await `promise` for at most `waitMs`; `undefined` means the budget expired
+ * with the work still pending (rejections propagate as usual). The timer never
+ * holds the process open, and a late rejection after the budget expired is
+ * already handled by the registry's own settle handlers.
+ */
+function awaitWithBudget(promise, waitMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(undefined), waitMs);
+        timer.unref?.();
+        promise.then((result) => { clearTimeout(timer); resolve(result); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
 /**
  * One session's jobs. Construct one per session and never share it — see the
  * cross-tenant note at the top of this file. Reachable as
@@ -181,7 +213,7 @@ export class JobRegistry {
      * different registry and therefore a genuinely separate generation.
      */
     async dispatch(opts, work) {
-        const { toolName, fingerprint, idempotencyKey, async } = opts;
+        const { toolName, fingerprint, idempotencyKey, async, waitMs } = opts;
         const now = Date.now();
         let hit;
         if (idempotencyKey !== undefined) {
@@ -199,10 +231,15 @@ export class JobRegistry {
         if (hit) {
             if (async)
                 return jobHandle(hit.jobId, hit.status);
+            const settled = waitMs !== undefined && hit.status === 'running'
+                ? await awaitWithBudget(hit.promise, waitMs)
+                : await hit.promise;
+            if (settled === undefined)
+                return jobHandle(hit.jobId, 'running');
             // Refresh before annotating: a recorded result can outlive the signed
             // URLs inside it, and replaying an expired link is its own kind of wrong
             // answer — it looks like success.
-            return annotateReused(await refreshMedia(await hit.promise, this.resigner), hit.jobId);
+            return annotateReused(await refreshMedia(settled, this.resigner), hit.jobId);
         }
         const jobId = randomUUID();
         this.evict(now);
@@ -222,6 +259,13 @@ export class JobRegistry {
         });
         if (async)
             return jobHandle(jobId, 'running');
+        if (waitMs !== undefined) {
+            const settled = await awaitWithBudget(promise, waitMs);
+            // Budget expired with the work still running: hand back the job id — the
+            // work continues and the caller polls, exactly as with `async: true`,
+            // except a fast result would have been returned in-band.
+            return settled ?? jobHandle(jobId, 'running');
+        }
         return promise;
     }
     /**

package/dist/library.js

@@ -0,0 +1,151 @@
+/**
+ * The per-account reference library: named characters (a reference image + a
+ * description) and named styles (a reusable prompt fragment, optionally with a
+ * reference image of its own).
+ *
+ * Why it exists: keeping a recurring subject consistent across generations
+ * means re-supplying the same reference image and the same description every
+ * session — re-uploading the photo, re-typing the description, re-explaining
+ * the style. The library makes each of those a NAME: save once, then pass
+ * `characters: ["finn"]` / `style: "bold-cartoon-sports"` on any generation.
+ *
+ * Storage is the connector's R2 bucket under `lib/<tenant>/…`:
+ *
+ *  - `lib/<tenant>/characters/<name>.json` — the record
+ *  - `lib/<tenant>/characters/<name>.img`  — the reference image bytes
+ *  - `lib/<tenant>/styles/<name>.json` (+ `.img` when a reference was given)
+ *
+ * Two properties are load-bearing:
+ *
+ *  - **No expiry.** The retention cron sweeps `gen/`, `media/` and `up/` but
+ *    deliberately never `lib/` (media-cleanup.ts) — a saved character outlives
+ *    every signed URL and every upload. That is why saving COPIES the image
+ *    bytes into `lib/` rather than storing an `r2_key` pointer: a pointer into
+ *    `gen/` or `up/` would dangle after the next sweep.
+ *  - **Tenant scoping by construction.** Every key this module touches is
+ *    derived from the session's own tenant id; caller-supplied names are
+ *    validated against a strict slug charset, so no name can address another
+ *    account's namespace (or escape `lib/` at all).
+ *
+ * Worker-safe: no node imports, no module-scope state, structural bucket type.
+ */
+/** Key prefix for the library — the one prefix the retention sweep must skip. */
+export const LIBRARY_KEY_PREFIX = 'lib';
+/**
+ * Library names are slugs: 1–40 chars, lowercase alphanumerics plus `-`/`_`,
+ * starting alphanumeric. Doubles as key-safety (no `/`, `.`, whitespace).
+ */
+export const LIBRARY_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,39}$/;
+export function isValidLibraryName(name) {
+    return LIBRARY_NAME_PATTERN.test(name);
+}
+/** Build the R2-backed library for one session. */
+export function createR2Library(bucket, opts) {
+    const now = opts.now ?? (() => new Date());
+    let tenantCache;
+    const tenantId = () => (tenantCache ??= Promise.resolve(typeof opts.tenant === 'function' ? opts.tenant() : opts.tenant));
+    const assertName = (name) => {
+        if (!isValidLibraryName(name)) {
+            throw new Error(`Invalid library name "${name}" — use 1-40 lowercase letters, digits, "-" or "_" (e.g. "finn", "bold-cartoon-sports").`);
+        }
+        return name;
+    };
+    const keyFor = async (kind, name, ext) => `${LIBRARY_KEY_PREFIX}/${await tenantId()}/${kind}/${assertName(name)}.${ext}`;
+    async function readJson(key) {
+        const object = await bucket.get(key);
+        if (!object)
+            return undefined;
+        try {
+            return JSON.parse(new TextDecoder().decode(await object.arrayBuffer()));
+        }
+        catch {
+            // A malformed record is unreadable, not fatal — callers treat it as absent.
+            return undefined;
+        }
+    }
+    async function readImage(kind, name) {
+        const object = await bucket.get(await keyFor(kind, name, 'img'));
+        if (!object)
+            return undefined;
+        return {
+            bytes: new Uint8Array(await object.arrayBuffer()),
+            mimeType: object.httpMetadata?.contentType ?? 'application/octet-stream',
+        };
+    }
+    async function listRecords(kind) {
+        const prefix = `${LIBRARY_KEY_PREFIX}/${await tenantId()}/${kind}/`;
+        const keys = [];
+        let cursor;
+        for (;;) {
+            const page = await bucket.list({ prefix, cursor, limit: 1000 });
+            keys.push(...page.objects.map((o) => o.key).filter((k) => k.endsWith('.json')));
+            if (!page.truncated)
+                break;
+            cursor = page.cursor;
+        }
+        const records = await Promise.all(keys.map((k) => readJson(k)));
+        return records
+            .filter((r) => r !== undefined)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async function deleteEntry(kind, name) {
+        const jsonKey = await keyFor(kind, name, 'json');
+        const existed = (await bucket.get(jsonKey)) !== null;
+        await bucket.delete([jsonKey, await keyFor(kind, name, 'img')]);
+        return existed;
+    }
+    return {
+        async saveCharacter({ name, description, image }) {
+            const jsonKey = await keyFor('characters', name, 'json');
+            const imageKey = await keyFor('characters', name, 'img');
+            const at = now().toISOString();
+            const existing = await readJson(jsonKey);
+            const record = {
+                name,
+                description,
+                image_key: imageKey,
+                mime_type: image.mimeType,
+                created_at: existing?.created_at ?? at,
+                updated_at: at,
+            };
+            await bucket.put(imageKey, image.bytes, { httpMetadata: { contentType: image.mimeType } });
+            await bucket.put(jsonKey, JSON.stringify(record, null, 2), { httpMetadata: { contentType: 'application/json' } });
+            return record;
+        },
+        async getCharacter(name) {
+            return readJson(await keyFor('characters', name, 'json'));
+        },
+        readCharacterImage: (name) => readImage('characters', name),
+        listCharacters: () => listRecords('characters'),
+        deleteCharacter: (name) => deleteEntry('characters', name),
+        async saveStyle({ name, promptFragment, image }) {
+            const jsonKey = await keyFor('styles', name, 'json');
+            const imageKey = await keyFor('styles', name, 'img');
+            const at = now().toISOString();
+            const existing = await readJson(jsonKey);
+            const record = {
+                name,
+                prompt_fragment: promptFragment,
+                ...(image ? { image_key: imageKey, mime_type: image.mimeType } : {}),
+                created_at: existing?.created_at ?? at,
+                updated_at: at,
+            };
+            if (image) {
+                await bucket.put(imageKey, image.bytes, { httpMetadata: { contentType: image.mimeType } });
+            }
+            else if (existing?.image_key) {
+                // Re-saving without an image REPLACES the style — a stale reference
+                // image left behind would silently keep steering generations.
+                await bucket.delete(imageKey);
+            }
+            await bucket.put(jsonKey, JSON.stringify(record, null, 2), { httpMetadata: { contentType: 'application/json' } });
+            return record;
+        },
+        async getStyle(name) {
+            return readJson(await keyFor('styles', name, 'json'));
+        },
+        readStyleImage: (name) => readImage('styles', name),
+        listStyles: () => listRecords('styles'),
+        deleteStyle: (name) => deleteEntry('styles', name),
+    };
+}

package/dist/media-cleanup.js

@@ -17,8 +17,11 @@ const DEFAULT_MAX_OBJECTS = 5_000;
  * `gen/` is where media is written now; `media/` is where it was written before
  * the rename that made URLs read `/media/gen/…` instead of `/media/media/…`.
  * Both are swept — retention that ignores the existing backlog is not retention.
+ * `up/` (signed uploads) is swept on the same schedule: a reference photo worth
+ * keeping gets copied into the character library (`lib/`), which is the ONE
+ * prefix deliberately absent here — saved characters and styles have no expiry.
  */
-const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/'];
+const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/', 'up/'];
 /** R2 accepts bulk deletes in batches; 1000 is the documented ceiling. */
 const DELETE_BATCH = 1_000;
 /** Days → ms, defaulting to 7 for anything missing or nonsensical. */

package/dist/media-endpoint.js

@@ -59,6 +59,12 @@ function baseHeaders(key, object, size) {
         // The bytes are model output being handed to a browser — never let a
         // sniffed content type turn an image response into something executable.
         'x-content-type-options': 'nosniff',
+        // Defense in depth against stored XSS: this route serves user-influenced
+        // bytes from the SAME ORIGIN as the connector's OAuth pages, so if a
+        // scriptable document type (SVG, HTML) ever slipped past the raster-only
+        // upload gates, this neutralizes it — no script, no fetch, and a unique
+        // opaque origin via sandbox. Pixels don't need any of what this disables.
+        'content-security-policy': "default-src 'none'; sandbox",
         // Range support is cheap on R2 and is what makes a resumable `curl -C -`
         // work against a large video.
         'accept-ranges': 'bytes',

package/dist/media-url.js

@@ -19,14 +19,14 @@
 export const MEDIA_URL_TTL_MS = 48 * 60 * 60 * 1000;
 /** KV key holding the lazily-generated signing secret (zero-config path). */
 export const SIGNING_SECRET_KV_KEY = 'media:url-signing-secret';
-function base64UrlEncode(bytes) {
+export function base64UrlEncode(bytes) {
     const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
     let binary = '';
     for (let i = 0; i < view.length; i++)
         binary += String.fromCharCode(view[i]);
     return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
-function base64UrlDecode(text) {
+export function base64UrlDecode(text) {
     const padded = text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '=');
     const binary = atob(padded);
     const out = new Uint8Array(binary.length);

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

@@ -45,7 +45,7 @@ export async function tenantIdFor(secret) {
 // 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, '-')
@@ -67,18 +67,27 @@ export function createR2Sink(bucket, opts) {
     const publicBase = opts.publicBaseUrl?.replace(/\/+$/, '');
     const signedBase = opts.signedBaseUrl?.replace(/\/+$/, '');
     const ttlMs = opts.urlTtlMs ?? 0;
-    /** `<prefix>/` or `<prefix>/<tenant>/` — every key this sink may touch. */
-    let ownPrefixCache;
-    const ownPrefix = () => (ownPrefixCache ??= (async () => {
-        const tenant = typeof opts.tenant === 'function' ? await opts.tenant() : opts.tenant;
+    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. 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).
+     * 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) => !opts.tenant || key.startsWith(await ownPrefix());
+    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,
@@ -102,14 +111,16 @@ export function createR2Sink(bucket, opts) {
                 return undefined;
             return describe(key, now().getTime() + ttlMs);
         },
-        async persist(items, _opts) {
+        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 = `${keyBase}${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;

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)