@chrischall/gemini-mcp 1.3.0 → 1.5.0

package/dist/bundle.js

@@ -32783,6 +32783,15 @@ var init_clipboard = __esm({
   }
 });
 
+// src/media-url.ts
+var MEDIA_URL_TTL_MS;
+var init_media_url = __esm({
+  "src/media-url.ts"() {
+    "use strict";
+    MEDIA_URL_TTL_MS = 48 * 60 * 60 * 1e3;
+  }
+});
+
 // src/index.ts
 init_dist();
 
@@ -32796,7 +32805,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.3.0";
+var VERSION = "1.5.0";
 
 // src/tools/models.ts
 init_dist();
@@ -33093,7 +33102,7 @@ async function fetchRemoteImage(requestedUrl, opts = {}) {
 // src/inputs.ts
 function hasImageInput(args) {
   return Boolean(
-    args.images?.length || args.images_base64?.length || args.images_url?.length || args.images_file_uris?.length || args.from_clipboard
+    args.images?.length || args.images_base64?.length || args.images_url?.length || args.images_file_uris?.length || args.images_r2_keys?.length || args.from_clipboard
   );
 }
 var ASSUMED_TTL_MS = 47 * 60 * 60 * 1e3;
@@ -33142,6 +33151,32 @@ async function resolveImageInputs(args, client2) {
     (report.file_uris ??= []).push(file2.name);
     inputs.push(input);
   }
+  const seenKeys = /* @__PURE__ */ new Map();
+  for (const key of args.images_r2_keys ?? []) {
+    const hit = seenKeys.get(key);
+    if (hit) {
+      inputs.push(hit);
+      continue;
+    }
+    const stored = await client2.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 client2.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 : void 0 };
 }
 async function resolveLocalPath(path, client2, onDisk, report) {
@@ -33196,7 +33231,7 @@ async function resolveUrl(url2, client2, report) {
 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`."
+    "Provide at least one input image via `images_url` (an https URL the server fetches), `images_file_uris` (from gemini_upload_file), `images_r2_keys` (a hosted-connector upload or earlier generation), `images` (a local path), `images_base64`, or `from_clipboard`."
   );
 }
 
@@ -33221,6 +33256,104 @@ function createDiskSink() {
   };
 }
 
+// src/media-endpoint.ts
+init_media_url();
+function downloadFilename(key) {
+  const last = key.split("/").pop() || "media";
+  const stripped = last.replace(/^[0-9a-f]{6,12}-/i, "");
+  return stripped || last;
+}
+
+// src/zip.ts
+var CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+function crc32(bytes) {
+  let crc = 4294967295;
+  for (let i = 0; i < bytes.length; i++) {
+    crc = CRC_TABLE[(crc ^ bytes[i]) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function dosDateTime(at) {
+  const year = Math.max(1980, at.getUTCFullYear());
+  return {
+    time: at.getUTCHours() << 11 | at.getUTCMinutes() << 5 | at.getUTCSeconds() >> 1,
+    date: year - 1980 << 9 | at.getUTCMonth() + 1 << 5 | at.getUTCDate()
+  };
+}
+var LOCAL_HEADER = 67324752;
+var CENTRAL_HEADER = 33639248;
+var EOCD = 101010256;
+var VERSION2 = 20;
+var FLAG_UTF8 = 2048;
+function buildZip(entries, modifiedAt = new Date(Date.UTC(1980, 0, 1))) {
+  const { time: time3, date: date5 } = dosDateTime(modifiedAt);
+  const encoder = new TextEncoder();
+  const parts = [];
+  const central = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = encoder.encode(entry.name);
+    const crc = crc32(entry.bytes);
+    const size = entry.bytes.byteLength;
+    const local = new Uint8Array(30 + name.byteLength);
+    const lv = new DataView(local.buffer);
+    lv.setUint32(0, LOCAL_HEADER, true);
+    lv.setUint16(4, VERSION2, true);
+    lv.setUint16(6, FLAG_UTF8, true);
+    lv.setUint16(8, 0, true);
+    lv.setUint16(10, time3, true);
+    lv.setUint16(12, date5, true);
+    lv.setUint32(14, crc, true);
+    lv.setUint32(18, size, true);
+    lv.setUint32(22, size, true);
+    lv.setUint16(26, name.byteLength, true);
+    lv.setUint16(28, 0, true);
+    local.set(name, 30);
+    const dir = new Uint8Array(46 + name.byteLength);
+    const dv = new DataView(dir.buffer);
+    dv.setUint32(0, CENTRAL_HEADER, true);
+    dv.setUint16(4, VERSION2, true);
+    dv.setUint16(6, VERSION2, true);
+    dv.setUint16(8, FLAG_UTF8, true);
+    dv.setUint16(10, 0, true);
+    dv.setUint16(12, time3, true);
+    dv.setUint16(14, date5, true);
+    dv.setUint32(16, crc, true);
+    dv.setUint32(20, size, true);
+    dv.setUint32(24, size, true);
+    dv.setUint16(28, name.byteLength, true);
+    dv.setUint32(42, offset, true);
+    dir.set(name, 46);
+    parts.push(local, entry.bytes);
+    central.push(dir);
+    offset += local.byteLength + size;
+  }
+  const centralSize = central.reduce((n, c) => n + c.byteLength, 0);
+  const eocd = new Uint8Array(22);
+  const ev = new DataView(eocd.buffer);
+  ev.setUint32(0, EOCD, true);
+  ev.setUint16(8, entries.length, true);
+  ev.setUint16(10, entries.length, true);
+  ev.setUint32(12, centralSize, true);
+  ev.setUint32(16, offset, true);
+  const total = offset + centralSize + eocd.byteLength;
+  const out = new Uint8Array(total);
+  let cursor = 0;
+  for (const part of [...parts, ...central, eocd]) {
+    out.set(part, cursor);
+    cursor += part.byteLength;
+  }
+  return out;
+}
+
 // src/tools/shared.ts
 var DEFAULT_SINK = createDiskSink();
 var ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:4", "4:1", "1:8", "8:1"];
@@ -33235,6 +33368,77 @@ var idempotencyKeySchema = external_exports.string().min(1).optional().describe(
 var asyncSchema = external_exports.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)."
 );
+var maxWaitMsSchema = external_exports.number().int().positive().max(6e5).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) \u2014 e.g. 20000 for multi-image sets. Ignored when async is set.'
+);
+function imagesR2KeysSchema(label = "Reference images") {
+  return external_exports.array(external_exports.string().min(1)).optional().describe(
+    `${label} by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url \u2192 curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly \u2014 no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only.`
+  );
+}
+var charactersSchema = external_exports.array(external_exports.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."
+);
+var styleSchema = external_exports.string().min(1).optional().describe(
+  "Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment \u2014 and reference image, if it has one \u2014 is applied to the request automatically. Hosted connector only."
+);
+async function resolveCharacterRefs(client2, names, styleName) {
+  if (!names?.length && !styleName) return { inputs: [] };
+  const library = client2.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 = [];
+  const toInput = async (image, displayName) => {
+    if (image.bytes.byteLength <= IMAGE_INLINE_MAX_BYTES) {
+      return { base64: bytesToBase64(image.bytes), mimeType: image.mimeType };
+    }
+    const uploaded = await client2.uploadBytes(image.bytes, image.mimeType, displayName);
+    return { uri: uploaded.uri, mimeType: uploaded.mimeType };
+  };
+  for (const name of names ?? []) {
+    const record2 = await library.getCharacter(name);
+    const image = record2 && await library.readCharacterImage(name);
+    if (!record2 || !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(`${record2.name} \u2014 ${record2.description}`);
+  }
+  let styleFragment;
+  let styleImageAttached = false;
+  if (styleName) {
+    const record2 = await library.getStyle(styleName);
+    if (!record2) {
+      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 = record2.prompt_fragment;
+    if (record2.image_key) {
+      const image = await library.readStyleImage(styleName);
+      if (image) {
+        inputs.push(await toInput(image, styleName));
+        styleImageAttached = true;
+      }
+    }
+  }
+  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." : void 0;
+  const meta3 = {};
+  if (names?.length) meta3.characters = names;
+  if (styleName) meta3.style = styleName;
+  return { inputs, characterLine, styleFragment, meta: Object.keys(meta3).length ? meta3 : void 0 };
+}
+function composePrompt(prompt, refs) {
+  return [refs.characterLine, prompt, refs.styleFragment ? `Style: ${refs.styleFragment}` : void 0].filter(Boolean).join("\n\n");
+}
 function imagesUrlSchema(label = "Reference images") {
   return external_exports.array(external_exports.string().url()).optional().describe(
     `${label} as public https URLs \u2014 the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each; must be a directly-linked image (Content-Type image/*).`
@@ -33260,7 +33464,8 @@ var sharedImageSchema = {
   from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
   timeout_ms: timeoutMsSchema,
   idempotency_key: idempotencyKeySchema,
-  async: asyncSchema
+  async: asyncSchema,
+  max_wait_ms: maxWaitMsSchema
 };
 async function resolveVideoInput(args, client2) {
   if (args.video_url && args.video_path) {
@@ -33347,7 +33552,8 @@ async function emitMedia(named, kind, opts, meta3, 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
+    output_dir: opts.output_dir,
+    urlTtlMs: opts.urlTtlMs
   });
   const refs = persisted.map((p) => p.ref);
   if (sink.persistsFiles) await onWritten?.(refs);
@@ -33361,7 +33567,13 @@ async function emitMedia(named, kind, opts, meta3, onWritten) {
     media: persisted.map((p) => ({
       url: p.ref,
       ...p.key ? { r2_key: p.key } : {},
-      ...p.expiresAt ? { expires_at: p.expiresAt } : {}
+      ...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}"` } : {}
     }))
   } : {};
   const storage = sink.persistsFiles ? {} : { storage: sink.kind, storage_note: storageNote };
@@ -33370,6 +33582,40 @@ async function emitMedia(named, kind, opts, meta3, onWritten) {
 async function emit(named, opts, meta3, onWritten) {
   return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), "image", opts, meta3, onWritten);
 }
+var SET_URL_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+var BUNDLE_MAX_TOTAL_BYTES = 24 * 1024 * 1024;
+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: mediaExt2 } = await Promise.resolve().then(() => (init_images(), images_exports));
+    const zip = buildZip(named.map((n) => ({ name: `${n.base}.${mediaExt2(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 \u2014 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 \u2014 download them individually via their media urls / curl_hints." };
+  }
+}
 function assertLocalInputsAvailable(sink, args) {
   if ((sink ?? DEFAULT_SINK).persistsFiles) return;
   const unavailable = [];
@@ -33396,6 +33642,64 @@ function isExpired(entry, now) {
 function fingerprintRequest(toolName, parts) {
   return createHash("sha256").update(`${toolName}\0${JSON.stringify(parts)}`).digest("hex");
 }
+async function refreshMedia(result, sink) {
+  const first = result.content?.[0];
+  if (!sink?.resign || !first || first.type !== "text") return result;
+  let body;
+  try {
+    body = JSON.parse(first.text);
+  } catch {
+    return result;
+  }
+  const entries = Array.isArray(body.media) ? body.media : [];
+  if (!entries.some((e) => typeof e.r2_key === "string")) return result;
+  const refreshed = await Promise.all(entries.map(async (e) => {
+    if (typeof e.r2_key !== "string") return void 0;
+    try {
+      return await sink.resign(e.r2_key);
+    } catch {
+      return void 0;
+    }
+  }));
+  if (refreshed.every((r) => r === void 0)) return result;
+  const mediaKeyName = ["images", "videos", "audios"].find((k) => Array.isArray(body[k]));
+  const refs = [];
+  refreshed.forEach((fresh, i) => {
+    if (!fresh) {
+      refs.push(String(entries[i]?.url ?? ""));
+      return;
+    }
+    const { expires_at: _stale, ...rest } = entries[i];
+    entries[i] = {
+      ...rest,
+      url: fresh.ref,
+      ...fresh.expiresAt ? { expires_at: fresh.expiresAt } : {},
+      curl_hint: `curl -sS -o ${downloadFilename(fresh.key ?? "media")} "${fresh.ref}"`
+    };
+    refs.push(fresh.ref);
+  });
+  body.media = entries;
+  if (mediaKeyName) body[mediaKeyName] = refs;
+  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 {
+    }
+  }
+  body.media_urls_refreshed = true;
+  return { ...result, content: [{ ...first, text: JSON.stringify(body, null, 2) }, ...(result.content ?? []).slice(1)] };
+}
 function annotateReused(result, jobId) {
   const content = result.content ?? [];
   const first = content[0];
@@ -33422,7 +33726,29 @@ 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).`
   });
 }
+function awaitWithBudget(promise2, waitMs) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => resolve2(void 0), waitMs);
+    timer.unref?.();
+    promise2.then(
+      (result) => {
+        clearTimeout(timer);
+        resolve2(result);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}
 var JobRegistry = class {
+  /**
+   * Lets a replayed result have its media URLs re-minted. Set by the session
+   * that owns this registry; absent on stdio, where refs are file paths that
+   * never expire.
+   */
+  resigner;
   jobs = /* @__PURE__ */ new Map();
   byKey = /* @__PURE__ */ new Map();
   // idempotencyKey -> jobId
@@ -33468,7 +33794,7 @@ var JobRegistry = class {
    * 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 !== void 0) {
@@ -33482,7 +33808,9 @@ var JobRegistry = class {
     }
     if (hit) {
       if (async) return jobHandle(hit.jobId, hit.status);
-      return annotateReused(await hit.promise, hit.jobId);
+      const settled = waitMs !== void 0 && hit.status === "running" ? await awaitWithBudget(hit.promise, waitMs) : await hit.promise;
+      if (settled === void 0) return jobHandle(hit.jobId, "running");
+      return annotateReused(await refreshMedia(settled, this.resigner), hit.jobId);
     }
     const jobId = randomUUID();
     this.evict(now);
@@ -33506,6 +33834,10 @@ var JobRegistry = class {
       if (this.runningByFingerprint.get(fingerprint) === jobId) this.runningByFingerprint.delete(fingerprint);
     });
     if (async) return jobHandle(jobId, "running");
+    if (waitMs !== void 0) {
+      const settled = await awaitWithBudget(promise2, waitMs);
+      return settled ?? jobHandle(jobId, "running");
+    }
     return promise2;
   }
   /**
@@ -33573,7 +33905,10 @@ function registerGenerateTools(server, client2) {
         images: external_exports.array(external_exports.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: external_exports.array(external_exports.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: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
         video_path: videoPathSchema,
         confirm: schemaConfirm,
@@ -33599,42 +33934,61 @@ function registerGenerateTools(server, client2) {
         from_clipboard: args.from_clipboard,
         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 client2.session.jobs.dispatch({ toolName: "gemini_image_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.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) : slugify2(args.prompt);
-        const { inputs: refInputs, report } = await withProgressHeartbeat(extra, "Resolving reference images", () => resolveImageInputs(args, client2));
+        const charRefs = await resolveCharacterRefs(client2, args.characters, args.style);
+        const prompt = composePrompt(args.prompt, charRefs);
+        const { inputs: directInputs, report } = await withProgressHeartbeat(extra, "Resolving reference images", () => resolveImageInputs(args, client2));
+        const refInputs = [...charRefs.inputs, ...directInputs];
         const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args, client2));
         const named = [];
         let capturedText;
         let capturedGrounding;
+        const failed = [];
+        let firstError;
         await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : "image"} (${model})`, async () => {
           for (let i = 0; i < count; i++) {
-            const result = await client2.generate({
-              prompt: args.prompt,
-              images: refInputs.length > 0 ? refInputs : void 0,
-              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 {
+              const result = await client2.generate({
+                prompt,
+                images: refInputs.length > 0 ? refInputs : void 0,
+                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 meta3 = buildMeta(model, seed, args);
         if (capturedText) meta3.text = capturedText;
         if (capturedGrounding) meta3.grounding = capturedGrounding;
         if (report) meta3.image_inputs = report;
+        if (charRefs.meta) Object.assign(meta3, charRefs.meta);
+        if (failed.length) {
+          meta3.failed_images = failed;
+          meta3.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 \u2014 each failure message is in failed_images.`;
+        }
         if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
         meta3.hint = REFINE_HINT;
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, count, persistsFiles: client2.mediaSink?.persistsFiles });
@@ -33653,7 +34007,10 @@ function registerGenerateTools(server, client2) {
         images: external_exports.array(external_exports.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: external_exports.array(external_exports.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: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
         confirm: schemaConfirm,
         ...sharedImageSchema
@@ -33661,7 +34018,7 @@ function registerGenerateTools(server, client2) {
     },
     async (args, extra) => {
       assertLocalInputsAvailable(client2.mediaSink, args);
-      requireImageInput(args);
+      if (!args.characters?.length) requireImageInput(args);
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images);
       if (gate) return gate;
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
@@ -33676,14 +34033,20 @@ function registerGenerateTools(server, client2) {
         images_base64: args.images_base64,
         from_clipboard: args.from_clipboard,
         images_url: args.images_url,
-        images_file_uris: args.images_file_uris
+        images_file_uris: args.images_file_uris,
+        images_r2_keys: args.images_r2_keys,
+        characters: args.characters,
+        style: args.style
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_image_edit", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.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) : slugify2(args.prompt);
-        const { inputs, report } = await withProgressHeartbeat(extra, "Resolving input images", () => resolveImageInputs(args, client2));
+        const charRefs = await resolveCharacterRefs(client2, args.characters, args.style);
+        const prompt = composePrompt(args.prompt, charRefs);
+        const { inputs: directInputs, report } = await withProgressHeartbeat(extra, "Resolving input images", () => resolveImageInputs(args, client2));
+        const inputs = [...charRefs.inputs, ...directInputs];
         const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client2.generate({
-          prompt: args.prompt,
+          prompt,
           images: inputs,
           model: args.model,
           aspectRatio: args.aspect_ratio,
@@ -33698,6 +34061,7 @@ function registerGenerateTools(server, client2) {
         if (text) meta3.text = text;
         if (result.grounding) meta3.grounding = result.grounding;
         if (report) meta3.image_inputs = report;
+        if (charRefs.meta) Object.assign(meta3, charRefs.meta);
         meta3.hint = REFINE_HINT;
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: client2.mediaSink?.persistsFiles });
         if (risk) meta3.timeout_risk = risk;
@@ -33715,7 +34079,7 @@ function registerSetTools(server, client2) {
   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: external_exports.string().min(1).describe("Prompt for the master/reference image"),
@@ -33726,6 +34090,9 @@ function registerSetTools(server, client2) {
         master_images: external_exports.array(external_exports.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: external_exports.array(external_exports.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
@@ -33753,26 +34120,34 @@ function registerSetTools(server, client2) {
         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_file_uris: args.master_images_file_uris,
+        master_images_r2_keys: args.master_images_r2_keys,
+        characters: args.characters,
+        style: args.style
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_image_set", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.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) : slugify2(args.master_prompt);
+        const charRefs = await resolveCharacterRefs(client2, args.characters, args.style);
+        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_url: args.master_images_url, images_file_uris: args.master_images_file_uris, images_r2_keys: args.master_images_r2_keys },
           client2
         );
+        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 },
           client2
         );
-        const masterRefInputs = [...masterOnly.inputs, ...carried.inputs];
+        const masterRefInputs = [...charRefs.inputs, ...masterOnly.inputs, ...carried.inputs];
+        const failed = [];
         const report = carried.report || masterOnly.report ? { ...masterOnly.report, ...carried.report } : void 0;
         const named = [];
         const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
           const result = await client2.generate({
-            prompt: args.master_prompt,
+            prompt: masterPrompt,
             images: masterRefInputs.length > 0 ? masterRefInputs : void 0,
             seed,
             ...cfg
@@ -33781,18 +34156,33 @@ function registerSetTools(server, client2) {
           named.push({ image: master, base: `${slug}-master` });
           const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
           const mode = args.reference_mode ?? "master";
+          const sceneName = (i) => `${slug}-${String(i + 1).padStart(2, "0")}`;
+          const record2 = (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 client2.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 client2.generate({ prompt: composePrompt(scenePrompts[i], styleOnly), images: [ref, ...carriedRefs], seed: seed + i + 1, ...cfg });
+                named.push({ image: img, base: sceneName(i) });
+                ref = img;
+              } catch (err) {
+                record2(err, i);
+              }
             }
           } else {
-            const scenes = await Promise.all(
-              scenePrompts.map((p, i) => client2.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
+            const settled = await Promise.allSettled(
+              scenePrompts.map((p, i) => client2.generate({ prompt: composePrompt(p, styleOnly), images: [master, ...carriedRefs], 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")}` }));
+            settled.forEach((outcome, i) => {
+              if (outcome.status === "fulfilled") named.push({ image: outcome.value, base: sceneName(i) });
+              else record2(outcome.reason, i);
+            });
           }
           return result;
         });
@@ -33801,9 +34191,15 @@ function registerSetTools(server, client2) {
         if (masterText) meta3.text = masterText;
         if (masterResult.grounding) meta3.grounding = masterResult.grounding;
         if (report) meta3.image_inputs = report;
+        if (charRefs.meta) Object.assign(meta3, charRefs.meta);
+        if (failed.length) {
+          meta3.failed_scenes = failed;
+          meta3.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 \u2014 each failure message is in failed_scenes.`;
+        }
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client2.mediaSink?.persistsFiles });
         if (risk) meta3.timeout_risk = risk;
-        return emit(named, { ...args, sink: client2.mediaSink }, meta3);
+        if (!args.inline) Object.assign(meta3, await persistBundle(named, client2.mediaSink, slug));
+        return emit(named, { ...args, sink: client2.mediaSink, urlTtlMs: SET_URL_TTL_MS }, meta3);
       });
     }
   );
@@ -33968,8 +34364,15 @@ var GeminiClient = class {
    * server is single-user, so its one singleton client is one session.
    */
   session = new SessionState();
+  /** Per-account character/style library — hosted connector only (see options). */
+  library;
+  /** Signed upload-URL minter — hosted connector only (see options). */
+  uploadUrls;
   constructor(opts = {}) {
     this.mediaSink = opts.mediaSink ?? createDiskSink();
+    this.library = opts.library;
+    this.uploadUrls = opts.uploadUrls;
+    this.session.jobs.resigner = this.mediaSink;
     this.explicitApiKey = opts.apiKey?.trim() || void 0;
     this.fetchImpl = opts.fetchImpl ?? fetch;
     this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -34039,6 +34442,22 @@ var GeminiClient = class {
   async fetchRemoteImage(url2, opts = {}) {
     return fetchRemoteImage(url2, { ...opts, fetchImpl: this.fetchImpl, timeoutMs: resolveTimeoutMs(opts.timeoutMs) });
   }
+  /**
+   * Read back media this connector generated, straight out of its own store.
+   *
+   * The alternative — fetching our own `/media` URL — needs a signature the
+   * caller cannot mint and returns 403, which is the loop this exists to close.
+   */
+  async readStoredMedia(key) {
+    const stored = await this.mediaSink.read?.(key.trim());
+    if (!stored) {
+      throw new McpToolError(
+        `No stored media for r2_key "${key}" \u2014 objects are removed on a retention schedule, so an old key may be gone. Re-run the generation, or upload the bytes with \`url\` / \`data_base64\`.`,
+        { hint: "Use the exact media[].r2_key from a generation result." }
+      );
+    }
+    return stored;
+  }
   /** The default model after env override (no per-call arg). */
   defaultModel() {
     return resolveModel(void 0, readEnvVar("GEMINI_IMAGE_MODEL"));
@@ -34552,6 +34971,7 @@ function registerInteractTools(server, client2) {
         timeout_ms: timeoutMsSchema,
         idempotency_key: idempotencyKeySchema,
         async: asyncSchema,
+        max_wait_ms: maxWaitMsSchema,
         from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
         confirm: schemaConfirm
       }
@@ -34598,7 +35018,7 @@ function registerInteractTools(server, client2) {
         video_url: args.video_url,
         video_path: args.video_path
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_interact", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.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 }, client2);
         const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args, client2));
         const callOpts = {
@@ -34702,6 +35122,7 @@ function registerVideoTools(server, client2) {
         timeout_ms: timeoutMsSchema,
         idempotency_key: idempotencyKeySchema,
         async: asyncSchema,
+        max_wait_ms: maxWaitMsSchema,
         confirm: schemaConfirm
       }
     },
@@ -34731,7 +35152,7 @@ function registerVideoTools(server, client2) {
         images_file_uris: args.images_file_uris,
         previous_interaction_id: previousInteractionId
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_video_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_video_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
         const { inputs, report } = await resolveImageInputs(args, client2);
         const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client2.generateVideo({
           input: args.prompt,
@@ -34791,6 +35212,7 @@ function registerMusicTools(server, client2) {
         timeout_ms: timeoutMsSchema,
         idempotency_key: idempotencyKeySchema,
         async: asyncSchema,
+        max_wait_ms: maxWaitMsSchema,
         confirm: schemaConfirm
       }
     },
@@ -34824,7 +35246,7 @@ function registerMusicTools(server, client2) {
         images_file_uris: args.images_file_uris,
         previous_interaction_id: previousInteractionId
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_music_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.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, client2);
         const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client2.generateMusic({
           input: args.prompt,
@@ -34894,13 +35316,16 @@ function registerFileTools(server, client2) {
   server.registerTool(
     "gemini_upload_file",
     {
-      description: "Upload a file \u2014 an image, reference photo, picture, screenshot, video or audio clip \u2014 to the Gemini Files API ONCE, and get back a reusable `file_uri` (`files/<id>`) to attach to later image, video or music generations. Keywords: upload, upload file, upload image, upload photo, attach, reference image, reference photo, file_uri, files api, image reference, reuse across calls. 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 ? "" : " This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header and a Content-Type of image/*, which avoids base64 entirely."),
+      description: "Upload a file \u2014 an image, reference photo, picture, screenshot, video or audio clip \u2014 to the Gemini Files API ONCE, and get back a reusable `file_uri` (`files/<id>`) to attach to later image, video or music generations. Keywords: upload, upload file, upload image, upload photo, attach, reference image, reference photo, file_uri, files api, image reference, reuse across calls. 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)." : ", 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 and a Content-Type of image/*, which avoids base64 entirely."),
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         url: external_exports.string().url().optional().describe(
           `Public https URL the SERVER downloads and uploads (image/video/audio, up to ${wholeMb(urlMaxBytes)}MB). No bytes pass through the conversation.` + (onDisk ? "" : " Larger files: POST the raw bytes to /upload, which streams instead of buffering.")
         ),
         data_base64: external_exports.string().min(1).optional().describe("Raw base64 or a data: URI. Last resort \u2014 this is the one form that costs model context (~14k tokens for a modest JPEG)."),
+        r2_key: external_exports.string().min(1).optional().describe(
+          onDisk ? "Unavailable on this server (media is written to local disk) \u2014 pass the file path via `path` instead." : "An `r2_key` from a previous generation result (media[].r2_key) \u2014 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 \u2014 that would be the connector fetching itself and needs a signature."
+        ),
         path: external_exports.string().min(1).optional().describe(
           onDisk ? "Path to a local file (absolute, or resolved against $GEMINI_INPUT_DIR). Confirm-gated like every other local-file input." : "Unavailable on this hosted connector (no filesystem) \u2014 use `url`, `data_base64`, or POST /upload."
         ),
@@ -34910,10 +35335,10 @@ function registerFileTools(server, client2) {
       }
     },
     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 source, not ${sources.length} (${sources.join(", ")}).`
+          sources.length === 0 ? "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) {
@@ -34942,6 +35367,19 @@ function registerFileTools(server, client2) {
             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 \u2014 this server writes media to local disk, so pass the generated file via `path` instead."
+            );
+          }
+          const stored = await client2.readStoredMedia(args.r2_key);
+          return client2.uploadBytes(
+            stored.bytes,
+            args.mime_type ?? stored.mimeType,
+            args.display_name ?? downloadFilename(args.r2_key)
+          );
+        }
         if (args.data_base64) {
           const { decodeImageInput: decodeImageInput2 } = await Promise.resolve().then(() => (init_images(), images_exports));
           const decoded = decodeImageInput2(args.data_base64);
@@ -34988,6 +35426,40 @@ function registerFileTools(server, client2) {
       });
     }
   );
+  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 \u2014 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: external_exports.string().min(1).describe("The `media[].r2_key` from an earlier generation result")
+        }
+      },
+      async (args) => {
+        const sink = client2.mediaSink;
+        if (!sink?.resign) {
+          throw new McpToolError("This server does not serve media URLs \u2014 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) {
+          throw new McpToolError(
+            `No stored media for r2_key "${args.r2_key}" \u2014 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 \u2014 inline image blocks and markdown embeds do not render for the end user."
+        });
+      }
+    );
+  }
   server.registerTool(
     "gemini_delete_file",
     {