@chrischall/gemini-mcp 1.3.0 → 1.4.0

package/.claude-plugin/marketplace.json

@@ -7,7 +7,7 @@
   },
   "metadata": {
     "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
-    "version": "1.3.0"
+    "version": "1.4.0"
   },
   "plugins": [
     {
@@ -15,7 +15,7 @@
       "displayName": "Gemini Images",
       "source": "./",
       "description": "Generate and edit images with Google Gemini image models (Nano Banana / Nano Banana Pro) via natural language prompts",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "gemini-mcp",
   "displayName": "Gemini Images",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "MCP server for Google Gemini image generation and editing — generate and edit images via the Gemini API",
   "author": {
     "name": "Chris Hall",

package/README.md

@@ -86,6 +86,7 @@ progress), two guards make re-issuing safe and unnecessary:
 | `gemini_upload_file` | Upload an image (or video/audio) to the Gemini Files API once — from a `url`, `data_base64`, or a local `path` — and get a reusable `files/<id>` reference |
 | `gemini_list_files` | List the files currently uploaded under this API key, with MIME types and expiry times |
 | `gemini_delete_file` | Delete an uploaded file before its ~48h expiry (confirm-gated) |
+| `gemini_sign_media` | *(hosted connector only)* Mint a fresh signed URL for generated media from its `r2_key` — an expired link is not a dead end |
 
 ## Seeing your images (hosted connector)
 
@@ -96,13 +97,22 @@ something you can *open*. It does: **every result includes a URL**, with no conf
 {
   "images": ["https://connector.example.com/media/gen/2026-07-29/ab12cd34-a-cat.png?exp=…&sig=…"],
   "media":  [{ "url": "https://…", "r2_key": "gen/2026-07-29/ab12cd34-a-cat.png",
-               "expires_at": "2026-07-31T12:00:00.000Z" }]
+               "expires_at": "2026-07-31T12:00:00.000Z",
+               "curl_hint": "curl -sS -o a-cat.png \"https://…\"" }]
 }
 ```
 
 Those links need no auth header — the signature is in the URL — so they work in a browser, in
 `curl`, and in a chat message. They expire (48h by default) and the objects behind them are
-swept on a retention schedule.
+swept on a retention schedule. The `r2_key` is the durable handle for that window:
+
+- **`gemini_sign_media`** (hosted connector only) mints a fresh signed URL from an `r2_key`,
+  so an expired link never forces you to re-generate — and re-pay for — the image.
+- **`gemini_upload_file` with `r2_key`** turns media the connector generated into a Files API
+  reference (the connector reads its own bucket — no HTTP round trip, no signature needed), so
+  a generated image can become the reference image for the next generation in one cheap call.
+- Idempotent replays (`idempotency_key`) re-mint the URLs inside the recorded result before
+  returning it, so a reused result never carries a dead link.
 
 **Why this matters:** MCP's inline image content blocks (`inline: true`) are visible to the
 *assistant* but many chat clients never render them to the user, and the assistant cannot

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.4.0";
 
 // src/tools/models.ts
 init_dist();
@@ -33221,6 +33230,14 @@ 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/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"];
@@ -33361,7 +33378,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 };
@@ -33396,6 +33419,47 @@ 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;
+  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];
@@ -33423,6 +33487,12 @@ function jobHandle(jobId, status) {
   });
 }
 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
@@ -33482,7 +33552,7 @@ var JobRegistry = class {
     }
     if (hit) {
       if (async) return jobHandle(hit.jobId, hit.status);
-      return annotateReused(await hit.promise, hit.jobId);
+      return annotateReused(await refreshMedia(await hit.promise, this.resigner), hit.jobId);
     }
     const jobId = randomUUID();
     this.evict(now);
@@ -33610,31 +33680,43 @@ function registerGenerateTools(server, 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: 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")}` });
+            } 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 (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 });
@@ -33768,6 +33850,7 @@ function registerSetTools(server, client2) {
           client2
         );
         const masterRefInputs = [...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 () => {
@@ -33781,18 +33864,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: scenePrompts[i], images: [ref, ...carried.inputs], 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(
+            const settled = await Promise.allSettled(
               scenePrompts.map((p, i) => client2.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
             );
-            scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, "0")}` }));
+            settled.forEach((outcome, i) => {
+              if (outcome.status === "fulfilled") named.push({ image: outcome.value, base: sceneName(i) });
+              else record2(outcome.reason, i);
+            });
           }
           return result;
         });
@@ -33801,6 +33899,10 @@ function registerSetTools(server, client2) {
         if (masterText) meta3.text = masterText;
         if (masterResult.grounding) meta3.grounding = masterResult.grounding;
         if (report) meta3.image_inputs = report;
+        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);
@@ -33970,6 +34072,7 @@ var GeminiClient = class {
   session = new SessionState();
   constructor(opts = {}) {
     this.mediaSink = opts.mediaSink ?? createDiskSink();
+    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 +34142,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"));
@@ -34894,13 +35013,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 +35032,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 +35064,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 +35123,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",
     {

package/dist/client.js

@@ -155,6 +155,9 @@ export class GeminiClient {
     session = new SessionState();
     constructor(opts = {}) {
         this.mediaSink = opts.mediaSink ?? createDiskSink();
+        // A replayed idempotent result must not hand back an expired media URL, so
+        // the job registry needs a way to re-sign from the stable r2_key.
+        this.session.jobs.resigner = this.mediaSink;
         this.explicitApiKey = opts.apiKey?.trim() || undefined;
         this.fetchImpl = opts.fetchImpl ?? fetch;
         this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -227,6 +230,21 @@ export class GeminiClient {
         // one unbounded network operation in the server.
         return fetchRemoteImage(url, { ...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) {
+            // Remediation goes in the MESSAGE: MCP serialization drops hints.
+            throw new McpToolError(`No stored media for r2_key "${key}" — 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(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));

package/dist/jobs.js

@@ -1,5 +1,6 @@
 import { randomUUID, createHash } from 'node:crypto';
 import { textResult, McpToolError } from '@chrischall/mcp-utils';
+import { downloadFilename } from './media-endpoint.js';
 /** Recently-completed jobs are reusable by key for this long, then evicted. */
 const JOB_TTL_MS = 600_000; // 10 min
 /** Hard cap on retained entries (oldest-settled evicted first). */
@@ -22,6 +23,72 @@ function isExpired(entry, now) {
 export function fingerprintRequest(toolName, parts) {
     return createHash('sha256').update(`${toolName}\u0000${JSON.stringify(parts)}`).digest('hex');
 }
+/**
+ * Re-mint any media URLs a recorded result carries, before it is replayed.
+ *
+ * A recorded result can outlive the signed URLs inside it — and after a change
+ * to the result shape it can even carry the OLD shape entirely. Either way the
+ * caller gets something that looks right and does not work. Re-signing from the
+ * `r2_key`, which is stable, fixes both: an expired link becomes a live one,
+ * and a legacy entry gains the `url`/`curl_hint` fields the current shape has.
+ *
+ * Best-effort by design. A replay that cannot be refreshed is still a valid
+ * replay — the point of idempotency is not billing twice, and failing here
+ * would trade a stale URL for no result at all.
+ */
+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;
+    // Per ENTRY, not per key: filtering first would shift every assignment after
+    // an entry without an r2_key and truncate the flat list below.
+    const refreshed = await Promise.all(entries.map(async (e) => {
+        if (typeof e.r2_key !== 'string')
+            return undefined;
+        try {
+            return await sink.resign(e.r2_key);
+        }
+        catch {
+            return undefined;
+        }
+    }));
+    if (refreshed.every((r) => r === undefined))
+        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;
+        }
+        // Drop the recorded expiry rather than carrying it over: a re-signed URL
+        // has its own deadline (or none, on a public-bucket sink), and the old one
+        // would mislabel a live link as expired.
+        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;
+    body.media_urls_refreshed = true;
+    return { ...result, content: [{ ...first, text: JSON.stringify(body, null, 2) }, ...(result.content ?? []).slice(1)] };
+}
 /** Clone `result`, adding `reused: true` + `reused_job_id` to its meta block. */
 function annotateReused(result, jobId) {
     const content = result.content ?? [];
@@ -58,6 +125,12 @@ function jobHandle(jobId, status) {
  * `client.session.jobs`.
  */
 export class JobRegistry {
+    /**
+     * 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 = new Map();
     byKey = new Map(); // idempotencyKey -> jobId
     runningByFingerprint = new Map(); // fingerprint -> jobId (only while running)
@@ -126,7 +199,10 @@ export class JobRegistry {
         if (hit) {
             if (async)
                 return jobHandle(hit.jobId, hit.status);
-            return annotateReused(await hit.promise, hit.jobId);
+            // 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);
         }
         const jobId = randomUUID();
         this.evict(now);

package/dist/media-endpoint.js

@@ -1,4 +1,75 @@
 import { loadSigningKey, verifyMediaSignature } from './media-url.js';
+/**
+ * Human-friendly download name from an object key.
+ *
+ * Keys look like `gen/<tenant>/2026-07-29/ab12cd34-a-cat.png`; the random component is
+ * there to make the key unique, not to be read. Stripping it turns a saved file
+ * into `a-cat.png`, which matters because the reliable way to show a user an
+ * image in a chat client is for the agent to download it and attach it — and an
+ * attachment called `ab12cd34-a-cat.png` looks like a machine artefact.
+ */
+export function downloadFilename(key) {
+    const last = key.split('/').pop() || 'media';
+    const stripped = last.replace(/^[0-9a-f]{6,12}-/i, '');
+    return stripped || last;
+}
+/**
+ * Parse a single-range `Range: bytes=a-b` header. Multi-range is unsupported,
+ * and an unknown object size means no range handling at all (Range is advisory
+ * — `undefined` degrades to a full 200, never an error).
+ */
+function parseRange(header, size) {
+    if (!header || size === undefined)
+        return undefined;
+    const match = /^bytes=(\d*)-(\d*)$/.exec(header.trim());
+    if (!match)
+        return undefined;
+    const [, startText, endText] = match;
+    if (startText === '' && endText === '')
+        return undefined;
+    if (startText === '') {
+        // Suffix range: the last N bytes.
+        const suffix = Number(endText);
+        if (!suffix)
+            return undefined;
+        const offset = Math.max(0, size - suffix);
+        return { offset, length: size - offset };
+    }
+    const offset = Number(startText);
+    if (offset >= size)
+        return 'unsatisfiable';
+    const end = endText === '' ? size - 1 : Number(endText);
+    if (end < offset)
+        return 'unsatisfiable';
+    return { offset, length: end - offset + 1 };
+}
+const MISSING = 'That media object no longer exists — it may have been cleaned up. Re-run the generation to get a fresh one.';
+/**
+ * Response headers shared by GET, HEAD and 206. `Content-Disposition` carries a
+ * readable filename because the reliable way to show a user an image in a chat
+ * client is for the agent to download it and attach it.
+ */
+function baseHeaders(key, object, size) {
+    const headers = new Headers({
+        'content-type': object.httpMetadata?.contentType ?? 'application/octet-stream',
+        // The URL is signed and expiring, so it is safe to cache for its lifetime;
+        // `private` keeps shared caches from serving it to anyone else.
+        'cache-control': 'private, max-age=3600',
+        'content-disposition': `inline; filename="${downloadFilename(key)}"`,
+        // 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',
+        // Range support is cheap on R2 and is what makes a resumable `curl -C -`
+        // work against a large video.
+        'accept-ranges': 'bytes',
+    });
+    const etag = object.httpEtag ?? object.etag;
+    if (etag)
+        headers.set('etag', etag);
+    if (size !== undefined)
+        headers.set('content-length', String(size));
+    return headers;
+}
 function problem(status, message) {
     return new Response(`${message}\n`, {
         status,
@@ -49,24 +120,41 @@ export function createMediaHandler(env, basePath = '/media/') {
             }
             return problem(403, 'Invalid or missing media signature. Media links must be used exactly as returned by the tool, including the exp and sig parameters.');
         }
+        const rangeHeader = request.headers.get('range');
+        // HEAD is what a link-preview fetcher and `curl -I` send first; serve it
+        // from a metadata read where the bucket offers one, rather than opening a
+        // body we are about to throw away.
+        if (request.method === 'HEAD' && env.bucket.head) {
+            const meta = await env.bucket.head(key);
+            if (!meta)
+                return problem(404, MISSING);
+            return new Response(null, { status: 200, headers: baseHeaders(key, meta, meta.size) });
+        }
+        // Fetch whole and slice on the way out rather than pushing the range into
+        // R2: the objects here are single images and short clips, and a typed
+        // range option is not expressible against both the real binding and a test
+        // fake without casting away the very types that make this safe.
         const object = await env.bucket.get(key);
-        if (!object) {
-            return problem(404, 'That media object no longer exists — it may have been cleaned up. Re-run the generation to get a fresh one.');
+        if (!object)
+            return problem(404, MISSING);
+        const totalSize = object.size;
+        const range = parseRange(rangeHeader, totalSize);
+        if (range === 'unsatisfiable') {
+            return new Response('Requested range not satisfiable\n', {
+                status: 416,
+                headers: { 'content-range': `bytes */${totalSize ?? 0}`, 'content-type': 'text/plain; charset=utf-8' },
+            });
         }
-        const headers = new Headers({
-            'content-type': object.httpMetadata?.contentType ?? 'application/octet-stream',
-            // The URL is signed and expiring, so it is safe to cache for its lifetime;
-            // `private` keeps shared caches from serving it to anyone else.
-            'cache-control': 'private, max-age=3600',
-            'content-disposition': `inline; filename="${key.split('/').pop() ?? 'media'}"`,
-            // 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',
-        });
-        if (object.size !== undefined)
-            headers.set('content-length', String(object.size));
+        const headers = baseHeaders(key, object, totalSize);
         if (request.method === 'HEAD')
             return new Response(null, { status: 200, headers });
-        return new Response(object.body, { status: 200, headers });
+        if (range && totalSize !== undefined && object.arrayBuffer) {
+            const length = Math.min(range.length, totalSize - range.offset);
+            const slice = (await object.arrayBuffer()).slice(range.offset, range.offset + length);
+            headers.set('content-length', String(slice.byteLength));
+            headers.set('content-range', `bytes ${range.offset}-${range.offset + slice.byteLength - 1}/${totalSize}`);
+            return new Response(slice, { status: 206, headers });
+        }
+        return new Response(object.body ?? null, { status: 200, headers });
     };
 }

package/dist/storage/media.js

@@ -36,6 +36,11 @@ 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';
@@ -62,19 +67,52 @@ 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;
+        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).
+     */
+    const owned = async (key) => !opts.tenant || key.startsWith(await ownPrefix());
     return {
         kind: 'r2',
         persistsFiles: false,
+        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, _opts) {
             // `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;
             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

@@ -66,31 +66,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: 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')}` });
+                    }
+                    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 +113,12 @@ export function registerGenerateTools(server, client) {
                 meta.grounding = capturedGrounding;
             if (report)
                 meta.image_inputs = report;
+            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;

package/dist/tools/set.js

@@ -61,6 +61,8 @@ export function registerSetTools(server, client) {
             const carried = await resolveImageInputs({ images_url: args.master_images_url, images_file_uris: args.master_images_file_uris }, client);
             const masterOnly = await resolveImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard }, client);
             const masterRefInputs = [...masterOnly.inputs, ...carried.inputs];
+            /** Scenes that failed, so one bad scene cannot lose the whole batch. */
+            const failed = [];
             const report = carried.report || masterOnly.report
                 ? { ...masterOnly.report, ...carried.report }
                 : undefined;
@@ -79,17 +81,44 @@ export function registerSetTools(server, client) {
                 // 2. scene prompts (explicit, or N repeats of master_prompt for variations)
                 const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
                 const mode = args.reference_mode ?? 'master';
+                // A set is N+1 billed generations in one tools/call, and any one of
+                // them can fail — a safety filter on a single scene, a transient 5xx.
+                // `Promise.all` rejected the whole batch on the first failure, losing
+                // the master and every scene that HAD succeeded, and surfaced as an
+                // opaque "Error occurred during tool execution" with no indication of
+                // which scene or why. Failures are collected per scene instead.
+                const sceneName = (i) => `${slug}-${String(i + 1).padStart(2, '0')}`;
+                const record = (err, i) => {
+                    failed.push({
+                        scene: i + 1,
+                        prompt: scenePrompts[i],
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                };
                 if (mode === 'chain') {
                     let ref = master;
                     for (let i = 0; i < scenePrompts.length; i++) {
-                        const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
-                        named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` });
-                        ref = img;
+                        try {
+                            const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
+                            named.push({ image: img, base: sceneName(i) });
+                            // Chain mode anchors each scene on the previous OUTPUT, so a
+                            // failure must not advance the reference — the next scene
+                            // continues from the last image that actually exists.
+                            ref = img;
+                        }
+                        catch (err) {
+                            record(err, i);
+                        }
                     }
                 }
                 else {
-                    const scenes = await Promise.all(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
-                    scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, '0')}` }));
+                    const settled = await Promise.allSettled(scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0])));
+                    settled.forEach((outcome, i) => {
+                        if (outcome.status === 'fulfilled')
+                            named.push({ image: outcome.value, base: sceneName(i) });
+                        else
+                            record(outcome.reason, i);
+                    });
                 }
                 return result;
             });
@@ -101,6 +130,13 @@ export function registerSetTools(server, client) {
                 meta.grounding = masterResult.grounding;
             if (report)
                 meta.image_inputs = report;
+            if (failed.length) {
+                meta.failed_scenes = failed;
+                meta.partial =
+                    `${failed.length} of ${failed.length + named.length - 1} scene(s) failed; the master and the ` +
+                        `${named.length - 1} scene(s) that succeeded are returned above. Re-run just the failed prompts rather than the whole set — ` +
+                        'each failure message is in failed_scenes.';
+            }
             // A set is master + N scenes in one tools/call — the most timeout-prone
             // tool. Effective image count drives the risk hint.
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client.mediaSink?.persistsFiles });

package/dist/tools/shared.js

@@ -4,6 +4,7 @@ import { resolveVideoPath, videoMimeType } from '../images.js';
 import { IMAGE_URL_MAX_BYTES } from '../fetch-image.js';
 import { wholeMb } from '../bytes.js';
 import { createDiskSink } from '../storage/media.js';
+import { downloadFilename } from '../media-endpoint.js';
 /**
  * Fallback sink for call sites that pass no explicit one (every pre-existing
  * test, and any caller constructed before the sink seam existed). The stdio
@@ -300,6 +301,12 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
                 url: p.ref,
                 ...(p.key ? { r2_key: p.key } : {}),
                 ...(p.expiresAt ? { expires_at: p.expiresAt } : {}),
+                // A ready-to-run command, not a description of one. Models copy an
+                // exact string far more reliably than they compose one — and in a
+                // chat client this download-then-attach flow is the ONLY way the end
+                // user actually sees the image (inline MCP blocks and markdown embeds
+                // both render for the model and not for them).
+                ...(p.key ? { curl_hint: `curl -sS -o ${downloadFilename(p.key)} "${p.ref}"` } : {}),
             })),
         }
         : {};

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '1.3.0'; // x-release-please-version
+export const VERSION = '1.4.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "mcpName": "io.github.chrischall/gemini-mcp",
   "description": "Gemini image-generation MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "1.3.0",
+  "version": "1.4.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.3.0",
+      "version": "1.4.0",
       "transport": {
         "type": "stdio"
       },