@chrischall/gemini-mcp 1.6.2 → 1.7.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.6.2"
+    "version": "1.7.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.6.2",
+      "version": "1.7.0",
       "author": {
         "name": "Chris Hall"
       },

package/.claude-plugin/plugin.json

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

package/dist/bundle.js

@@ -32838,7 +32838,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.6.2";
+var VERSION = "1.7.0";
 
 // src/errors.ts
 init_dist();
@@ -33367,6 +33367,14 @@ async function tenantIdFor(secret) {
   return [...new Uint8Array(digest).slice(0, 6)].map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 var KEY_PREFIX_DEFAULT = "gen";
+var MAX_LIST_PAGES = 10;
+function parseMediaKey(key, prefix) {
+  const rest = key.slice(prefix.length);
+  const match = /^(\d{4}-\d{2}-\d{2})\/(.+)$/.exec(rest);
+  if (!match) return void 0;
+  const name = match[2].replace(/^[0-9a-f]{4,}-/i, "").replace(/\.[A-Za-z0-9]+$/, "");
+  return { day: match[1], name: name || match[2] };
+}
 function safeKeySegment(base) {
   const cleaned = base.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/\.{2,}/g, "-").replace(/-+/g, "-").replace(/^[-.]+|[-.]+$/g, "");
   return cleaned || "media";
@@ -33402,6 +33410,40 @@ function createR2Sink(bucket, opts) {
         mimeType: object3.httpMetadata?.contentType ?? "application/octet-stream"
       };
     },
+    async listRecent(opts2 = {}) {
+      return (await this.listRecentPage(opts2)).media;
+    },
+    async listRecentPage({ limit = 20, sinceDay } = {}) {
+      if (!bucket.list) return { media: [], truncated: false, scannedPages: 0 };
+      const prefix2 = await ownPrefix();
+      const found = [];
+      let cursor;
+      let truncated = false;
+      let scannedPages = 0;
+      for (let page2 = 0; page2 < MAX_LIST_PAGES; page2++) {
+        scannedPages = page2 + 1;
+        const listed = await bucket.list({ prefix: prefix2, cursor, limit: 1e3 });
+        for (const obj of listed.objects) {
+          const parsed = parseMediaKey(obj.key, prefix2);
+          if (!parsed) continue;
+          if (sinceDay && parsed.day < sinceDay) continue;
+          found.push({ ...parsed, key: obj.key, ...obj.size !== void 0 ? { sizeBytes: obj.size } : {} });
+        }
+        if (!listed.truncated || !listed.cursor) break;
+        cursor = listed.cursor;
+        if (page2 === MAX_LIST_PAGES - 1) truncated = true;
+      }
+      found.sort((a, b) => a.day < b.day ? 1 : a.day > b.day ? -1 : a.key < b.key ? 1 : -1);
+      const page = found.slice(0, limit);
+      const expiresAtMs2 = now().getTime() + ttlMs;
+      const media = await Promise.all(
+        page.map(async (entry) => {
+          const link = await describe3(entry.key, expiresAtMs2);
+          return { ...entry, ...link.unavailable ? {} : { url: link.ref, expiresAt: link.expiresAt } };
+        })
+      );
+      return { media, truncated: truncated || found.length > limit, scannedPages };
+    },
     async resign(key) {
       if (!await owned(key)) return void 0;
       if (bucket.get && !await bucket.get(key)) return void 0;
@@ -33543,7 +33585,7 @@ var idempotencyKeySchema = external_exports.string().min(1).optional().describe(
   "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."
 );
 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)."
+  "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. PREFER `max_wait_ms` on the hosted connector: it runs where the executor is only guaranteed to stay alive while the request is open, so this option is served there as a bounded wait rather than an immediate hand-off."
 );
 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.'
@@ -33708,7 +33750,7 @@ function timeoutRiskHint(opts) {
   const why = [proModel && "Pro model", fourK && "4K output", multi && `count=${opts.count}`].filter(Boolean).join(" + ");
   const lead = `Slow config (${why}) can exceed a host's tools/call timeout (e.g. Claude Desktop ~30s, error -32001). `;
   if (opts.persistsFiles === false) {
-    return lead + `This connector has no filesystem, so a lost response cannot be recovered from disk \u2014 there is no output dir and no <image>.json sidecar. Use \`async: true\` to get a job_id immediately and poll gemini_get_result, or use a Flash model / drop image_size to 1K/2K for a faster in-band result.`;
+    return lead + `This connector has no filesystem, so a lost response cannot be recovered from disk \u2014 there is no output dir and no <image>.json sidecar. Set \`max_wait_ms\` (e.g. 240000): keeping the request open is also what keeps the generation running here, and a batch that outlives the budget hands back a job_id to poll with gemini_get_result. For a faster in-band result use a Flash model or drop image_size to 1K/2K. If a result is ever lost, list what was already generated with gemini_list_recent_media before paying for it again.`;
   }
   return lead + `If the host gives up mid-generation the image is still written to disk (and gemini_interact leaves an <image>.json sidecar with the interaction id) \u2014 no rerun needed, just look in the output dir. For a faster in-band result use a Flash model, drop image_size to 1K/2K, or \u2014 in Claude Code \u2014 set MCP_TOOL_TIMEOUT.`;
 }
@@ -33810,14 +33852,73 @@ function assertLocalInputsAvailable(sink, args) {
 
 // src/jobs.ts
 init_dist();
-import { randomUUID, createHash } from "node:crypto";
+import { randomUUID, createHash as createHash2 } from "node:crypto";
+
+// src/job-store.ts
+import { createHash } from "node:crypto";
+var HEARTBEAT_MS = 6e4;
+var EXECUTOR_LOST_AFTER_MS = 3 * HEARTBEAT_MS;
+var PREFIX = "jobs";
+function keyHash(idempotencyKey) {
+  return createHash("sha256").update(idempotencyKey).digest("hex").slice(0, 32);
+}
+function createBlobJobStore(bucket, opts) {
+  const now = opts.now ?? (() => Date.now());
+  const tenantOf = async () => typeof opts.tenant === "function" ? opts.tenant() : opts.tenant;
+  const recordKey = async (jobId) => `${PREFIX}/${await tenantOf()}/${encodeURIComponent(jobId)}.json`;
+  const pointerKey = async (k) => `${PREFIX}/${await tenantOf()}/keys/${keyHash(k)}.json`;
+  async function writeJson(key, value) {
+    try {
+      await bucket.put(key, JSON.stringify(value), { httpMetadata: { contentType: "application/json" } });
+    } catch {
+    }
+  }
+  async function readJson(key) {
+    try {
+      const obj = await bucket.get(key);
+      if (!obj) return void 0;
+      return JSON.parse(new TextDecoder().decode(await obj.arrayBuffer()));
+    } catch {
+      return void 0;
+    }
+  }
+  return {
+    async put(record2) {
+      await writeJson(await recordKey(record2.jobId), record2);
+    },
+    async get(jobId) {
+      const record2 = await readJson(await recordKey(jobId));
+      if (!record2 || typeof record2.status !== "string") return void 0;
+      if (record2.status !== "running") return record2;
+      if (now() - record2.updatedAt <= EXECUTOR_LOST_AFTER_MS) return record2;
+      return {
+        ...record2,
+        status: "failed",
+        error: {
+          message: `Job "${jobId}" was lost: its executor stopped reporting ${Math.round((now() - record2.updatedAt) / 1e3)}s ago, before the generation finished. This connector runs on a machine that stops when no request is in flight, so background work started with \`async: true\` does not reliably survive.`,
+          hint: "Re-run with `max_wait_ms` (e.g. 240000) instead of `async: true` \u2014 holding the request open keeps the executor alive. Any images the lost run did finish are still stored: list them with gemini_list_recent_media before paying for a regeneration."
+        }
+      };
+    },
+    async putKey(idempotencyKey, jobId) {
+      await writeJson(await pointerKey(idempotencyKey), { jobId });
+    },
+    async jobIdForKey(idempotencyKey) {
+      const pointer = await readJson(await pointerKey(idempotencyKey));
+      return typeof pointer?.jobId === "string" ? pointer.jobId : void 0;
+    }
+  };
+}
+
+// src/jobs.ts
 var JOB_TTL_MS = 6e5;
+var DURABLE_JOB_REUSE_MS = 24 * 60 * 60 * 1e3;
 var JOB_MAX = 64;
 function isExpired(entry, now) {
   return entry.settledAt !== void 0 && now - entry.settledAt > JOB_TTL_MS;
 }
 function fingerprintRequest(toolName, parts) {
-  return createHash("sha256").update(`${toolName}\0${JSON.stringify(parts)}`).digest("hex");
+  return createHash2("sha256").update(`${toolName}\0${JSON.stringify(parts)}`).digest("hex");
 }
 async function refreshMedia(result, sink) {
   const first = result.content?.[0];
@@ -33896,13 +33997,23 @@ function annotateReused(result, jobId) {
     content: [{ type: "text", text: JSON.stringify({ reused: true, reused_job_id: jobId }, null, 2) }, ...content]
   };
 }
-function jobHandle(jobId, status) {
+function jobHandle(jobId, status, durable = false) {
   return textResult({
     job_id: 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).`
+    hint: durable ? `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done". The job record is stored durably, so a poll still works if this connector restarts \u2014 but background work is NOT restarted, so a long generation is safer with max_wait_ms than with async.` : `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).`
   });
 }
+var MAX_PERSISTED_RESULT_BYTES = 64 * 1024;
+function persistableResult(result) {
+  if ((result.content ?? []).some((block) => block.type !== "text")) return { resultOmitted: "inline" };
+  try {
+    if (JSON.stringify(result).length > MAX_PERSISTED_RESULT_BYTES) return { resultOmitted: "too_large" };
+  } catch {
+    return { resultOmitted: "too_large" };
+  }
+  return { result };
+}
 function awaitWithBudget(promise2, waitMs) {
   return new Promise((resolve2, reject) => {
     const timer = setTimeout(() => resolve2(void 0), waitMs);
@@ -33926,16 +34037,112 @@ var JobRegistry = class {
    * never expire.
    */
   resigner;
+  /**
+   * Durable backing for this registry, when the deployment has somewhere to put
+   * it. Absent on a local stdio install, where the process that starts a
+   * generation is the process that finishes it and a `Map` is the whole truth.
+   *
+   * Present on the hosted connector, where it is load-bearing: see the header of
+   * `src/job-store.ts` for why an in-memory-only registry cannot work on a
+   * machine that stops whenever no request is in flight.
+   */
+  store;
+  /**
+   * When set, `async: true` is served as a bounded in-band wait instead of an
+   * immediate hand-off.
+   *
+   * Set by the hosted client, because there the two are not the trade-off they
+   * look like. Returning immediately releases the request, and the released
+   * request is the thing keeping the executor alive — so `async: true` is
+   * precisely the way to get a generation killed. Waiting holds the machine up
+   * until the work is done. If the budget still expires the caller gets the same
+   * job handle it asked for, now backed by a durable record.
+   */
+  asyncWaitFallbackMs;
+  /** Injectable clock (tests). */
+  now = () => Date.now();
   jobs = /* @__PURE__ */ new Map();
   byKey = /* @__PURE__ */ new Map();
   // idempotencyKey -> jobId
   runningByFingerprint = /* @__PURE__ */ new Map();
   // fingerprint -> jobId (only while running)
+  /** Durable bookkeeping still in flight — awaited by `drain()` in tests. */
+  pending = /* @__PURE__ */ new Set();
+  heartbeatTimer;
   /** Drop every job. Used by `SessionState.reset()` (tests) — not by handlers. */
   reset() {
     this.jobs.clear();
     this.byKey.clear();
     this.runningByFingerprint.clear();
+    this.stopHeartbeat();
+  }
+  /** Await outstanding durable writes. Tests only — handlers never need it. */
+  async drain() {
+    for (let round = 0; round < 50; round++) {
+      await new Promise((resolve2) => setTimeout(resolve2, 0));
+      if (!this.pending.size) return;
+      await Promise.allSettled([...this.pending]);
+    }
+  }
+  /**
+   * Re-stamp every running job's durable record.
+   *
+   * This is what separates "still working" from "the machine went away": a
+   * reader compares the stamp against `EXECUTOR_LOST_AFTER_MS`, so a 12-scene
+   * set that legitimately runs for ten minutes stays `running` while a job whose
+   * child was killed goes terminal within three missed beats.
+   */
+  async beat() {
+    if (!this.store) return;
+    await Promise.allSettled(
+      [...this.jobs.values()].filter((e) => e.status === "running").map((e) => this.writeRecord(e, { onlyWhileRunning: true }))
+    );
+  }
+  /**
+   * Queue one durable write for `entry`, after any write already in flight for
+   * it. `onlyWhileRunning` drops the write if the job settled in the meantime —
+   * which is what makes a late heartbeat a no-op rather than a resurrection.
+   */
+  writeRecord(entry, opts = {}) {
+    const next = (entry.writeChain ?? Promise.resolve()).then(async () => {
+      if (opts.onlyWhileRunning && entry.status !== "running") return;
+      await this.store.put(this.recordFor(entry, this.now()));
+    }, () => void 0);
+    entry.writeChain = next;
+    return next;
+  }
+  recordFor(entry, updatedAt) {
+    return {
+      jobId: entry.jobId,
+      toolName: entry.toolName,
+      fingerprint: entry.fingerprint,
+      ...entry.idempotencyKey !== void 0 ? { idempotencyKey: entry.idempotencyKey } : {},
+      status: entry.status,
+      createdAt: entry.createdAt,
+      updatedAt,
+      ...entry.error ? { error: entry.error } : {},
+      ...entry.status === "done" && entry.result ? persistableResult(entry.result) : {}
+    };
+  }
+  /** Run `p` as durable bookkeeping: tracked for `drain()`, never thrown from. */
+  track(p) {
+    const wrapped = p.catch(() => void 0).finally(() => this.pending.delete(wrapped));
+    this.pending.add(wrapped);
+  }
+  startHeartbeat() {
+    if (this.heartbeatTimer || !this.store) return;
+    this.heartbeatTimer = setInterval(() => {
+      if (![...this.jobs.values()].some((e) => e.status === "running")) {
+        this.stopHeartbeat();
+        return;
+      }
+      this.track(this.beat());
+    }, HEARTBEAT_MS);
+    this.heartbeatTimer.unref?.();
+  }
+  stopHeartbeat() {
+    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
+    this.heartbeatTimer = void 0;
   }
   /** Drop expired entries, then enforce JOB_MAX by evicting oldest-settled first. */
   evict(now) {
@@ -33971,8 +34178,11 @@ var JobRegistry = class {
    * different registry and therefore a genuinely separate generation.
    */
   async dispatch(opts, work) {
-    const { toolName, fingerprint, idempotencyKey, async, waitMs } = opts;
-    const now = Date.now();
+    const { toolName, fingerprint, idempotencyKey } = opts;
+    const degrade = opts.async === true && this.asyncWaitFallbackMs !== void 0;
+    const async = degrade ? false : opts.async;
+    const waitMs = degrade ? opts.waitMs ?? this.asyncWaitFallbackMs : opts.waitMs;
+    const now = this.now();
     let hit;
     if (idempotencyKey !== void 0) {
       const id = this.byKey.get(idempotencyKey);
@@ -33983,6 +34193,10 @@ var JobRegistry = class {
       const entry2 = id ? this.jobs.get(id) : void 0;
       if (entry2 && entry2.status === "running") hit = entry2;
     }
+    if (!hit && idempotencyKey !== void 0 && this.store) {
+      const durable = await this.durableByKey(idempotencyKey, fingerprint);
+      if (durable) return durable;
+    }
     if (hit) {
       if (async) return jobHandle(hit.jobId, hit.status);
       const settled = waitMs !== void 0 && hit.status === "running" ? await awaitWithBudget(hit.promise, waitMs) : await hit.promise;
@@ -33996,27 +34210,53 @@ var JobRegistry = class {
     this.jobs.set(jobId, entry);
     if (idempotencyKey !== void 0) this.byKey.set(idempotencyKey, jobId);
     this.runningByFingerprint.set(fingerprint, jobId);
-    promise2.then(
+    if (this.store) {
+      this.track(this.writeRecord(entry));
+      if (idempotencyKey !== void 0) this.track(this.store.putKey(idempotencyKey, jobId));
+      this.startHeartbeat();
+    }
+    const settle = promise2.then(
       (res) => {
         entry.status = "done";
         entry.result = res;
-        entry.settledAt = Date.now();
+        entry.settledAt = this.now();
       },
       (err) => {
         entry.status = "failed";
         entry.error = { message: err instanceof Error ? err.message : String(err), hint: err?.hint };
-        entry.settledAt = Date.now();
+        entry.settledAt = this.now();
       }
     ).finally(() => {
       if (this.runningByFingerprint.get(fingerprint) === jobId) this.runningByFingerprint.delete(fingerprint);
     });
-    if (async) return jobHandle(jobId, "running");
+    if (this.store) void settle.then(() => this.track(this.writeRecord(entry)));
+    if (async) return jobHandle(jobId, "running", this.store !== void 0);
     if (waitMs !== void 0) {
       const settled = await awaitWithBudget(promise2, waitMs);
-      return settled ?? jobHandle(jobId, "running");
+      return settled ?? jobHandle(jobId, "running", this.store !== void 0);
     }
     return promise2;
   }
+  /**
+   * Resolve an idempotency key against the durable store — the path a retry
+   * takes when the child that ran the original job is gone.
+   *
+   * `undefined` means "nothing durable to reuse", which includes a job that
+   * FAILED: a retry after an error must really retry. A job still recorded as
+   * running belongs to an executor this process cannot await, so the caller gets
+   * the handle back rather than a promise that would never settle.
+   */
+  async durableByKey(idempotencyKey, fingerprint) {
+    const id = await this.store.jobIdForKey(idempotencyKey);
+    if (!id) return void 0;
+    const record2 = await this.store.get(id);
+    if (!record2) return void 0;
+    if (record2.fingerprint !== fingerprint) return void 0;
+    if (this.now() - record2.updatedAt > DURABLE_JOB_REUSE_MS) return void 0;
+    if (record2.status === "running") return jobHandle(id, "running", true);
+    if (record2.status !== "done" || !record2.result) return void 0;
+    return annotateReused(await refreshMedia(record2.result, this.resigner), id);
+  }
   /**
    * Retrieve an async job by id (backs the `gemini_get_result` tool):
    * `running` → a status handle; `done` → the recorded result payload;
@@ -34026,21 +34266,52 @@ var JobRegistry = class {
    * the unknown-id path — the poll tool cannot be used to read another user's
    * result even if they know the uuid.
    */
-  getResult(jobId) {
+  async getResult(jobId) {
     const entry = this.jobs.get(jobId);
     if (!entry) {
-      throw new McpToolError(`No job "${jobId}" \u2014 unknown or expired.`, {
-        hint: "Jobs live with your session and are evicted ~10 min after completion (or on server restart). If the generation likely finished, check the output dir / <image>.json sidecar instead of polling."
-      });
+      const durable = this.store ? await this.store.get(jobId) : void 0;
+      if (durable) return this.fromRecord(durable);
+      throw new McpToolError(
+        this.store ? `No job "${jobId}" \u2014 no record of it exists. Either the id is wrong, or the job is older than the ${JOB_RECORD_RETENTION_LABEL} job records are kept.` : `No job "${jobId}" \u2014 unknown or expired.`,
+        {
+          hint: this.store ? "Job records are stored durably here, so a restart alone does not lose one \u2014 an id with no record was never started under this account. Images from a completed run are listed by gemini_list_recent_media." : "Jobs live with your session and are evicted ~10 min after completion (or on server restart). If the generation likely finished, check the output dir / <image>.json sidecar instead of polling."
+        }
+      );
     }
-    if (entry.status === "running") return jobHandle(jobId, "running");
+    if (entry.status === "running") return jobHandle(jobId, "running", this.store !== void 0);
     if (entry.status === "failed") {
       throw new McpToolError(entry.error?.message ?? "Job failed.", entry.error?.hint ? { hint: entry.error.hint } : void 0);
     }
     if (!entry.result) throw new McpToolError(`Job "${jobId}" completed without a recorded result.`);
     return entry.result;
   }
+  /**
+   * Render a durable record as a poll answer — the path taken when the child
+   * that ran the job is gone.
+   *
+   * The three outcomes are kept distinct on purpose. Collapsing "your job
+   * failed", "your job was killed" and "no such job" into one message is what
+   * made the original bug read as an expiry problem when it was a machine
+   * lifecycle problem.
+   */
+  async fromRecord(record2) {
+    if (record2.status === "running") return jobHandle(record2.jobId, "running", true);
+    if (record2.status === "failed") {
+      throw new McpToolError(record2.error?.message ?? "Job failed.", record2.error?.hint ? { hint: record2.error.hint } : void 0);
+    }
+    if (record2.resultOmitted) {
+      throw new McpToolError(
+        record2.resultOmitted === "inline" ? `Job "${record2.jobId}" finished, but its result was returned inline (base64 image data) and inline results are not stored, so there is nothing to replay. Re-run without \`inline: true\` so the media is stored and returned as URLs, which a poll can replay.` : `Job "${record2.jobId}" finished, but its result was too large to store (over ${Math.round(MAX_PERSISTED_RESULT_BYTES / 1024)} KB), so there is nothing to replay.`,
+        {
+          hint: "The generation itself completed \u2014 list what it produced with gemini_list_recent_media rather than paying for it again."
+        }
+      );
+    }
+    if (!record2.result) throw new McpToolError(`Job "${record2.jobId}" completed without a recorded result.`);
+    return refreshMedia(record2.result, this.resigner);
+  }
 };
+var JOB_RECORD_RETENTION_LABEL = "30 days";
 
 // src/tools/_confirm.ts
 init_dist();
@@ -34810,6 +35081,8 @@ var GeminiClient = class {
     this.library = opts.library;
     this.uploadUrls = opts.uploadUrls;
     this.session.jobs.resigner = this.mediaSink;
+    this.session.jobs.store = opts.jobStore;
+    if (opts.jobStore) this.session.jobs.asyncWaitFallbackMs = HOSTED_ASYNC_WAIT_MS;
     this.explicitApiKey = opts.apiKey?.trim() || void 0;
     this.fetchImpl = opts.fetchImpl ?? ((...args) => fetch(...args));
     this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
@@ -35339,9 +35612,14 @@ function hostedStorage() {
       tenant
     }),
     library: createR2Library(blob.bucket, { tenant }),
-    uploadUrls: createUploadUrlMinter({ links: blob.links, sign: blob.signWrite, tenant })
+    uploadUrls: createUploadUrlMinter({ links: blob.links, sign: blob.signWrite, tenant }),
+    // Job records go in the same store as the media, for the same reason: this
+    // runtime's machine stops whenever no request is in flight, taking the
+    // child — and an in-memory registry — with it (src/job-store.ts).
+    jobStore: createBlobJobStore(blob.bucket, { tenant })
   };
 }
+var HOSTED_ASYNC_WAIT_MS = 24e4;
 var BLOB_URL_TTL_MS = 24 * 60 * 60 * 1e3;
 var BLOB_MAX_TTL_MS = 24 * 60 * 60 * 1e3;
 var client = new GeminiClient(hostedStorage());
@@ -35748,7 +36026,7 @@ function registerJobTools(server, client2) {
   server.registerTool(
     "gemini_get_result",
     {
-      description: 'Retrieve an async generation started with `async: true`. Pass the returned `job_id`: while running it reports status "running"; on completion it returns the normal result (image paths / inline images + meta); on failure it raises the recorded error. Jobs belong to your session and expire ~10 min after completion \u2014 if a job id is unknown, check the output dir / <image>.json sidecar.',
+      description: 'Retrieve a generation started with `async: true` or handed off by `max_wait_ms`. Pass the returned `job_id`: while running it reports status "running"; on completion it returns the normal result (image URLs/paths + meta); on failure it raises the recorded error, including the case where the generation was killed before it finished. On the hosted connector job records are stored durably and survive a restart; on a local stdio server they live with the process and expire ~10 min after completion, where the output dir / <image>.json sidecar is the fallback.',
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: {
         job_id: external_exports.string().min(1).describe("The job_id returned by a generation tool called with async: true")
@@ -35928,6 +36206,43 @@ function registerFileTools(server, client2) {
         });
       }
     );
+    server.registerTool(
+      "gemini_list_recent_media",
+      {
+        description: "List images/video/audio this connector recently generated for your account, newest first, with fresh openable URLs. Use it when a result was lost \u2014 a generation whose response never arrived, or an async job whose id came back unknown \u2014 to find what already exists BEFORE re-running (and re-paying for) it. Keywords: lost result, orphaned job, missing image, what did I generate, recover, recent media.",
+        annotations: { readOnlyHint: true, openWorldHint: false },
+        inputSchema: {
+          limit: external_exports.number().int().positive().max(100).optional().describe("How many to return (default 20, newest first)"),
+          since_day: external_exports.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional().describe('Only media stored on or after this UTC day, e.g. "2026-08-18"')
+        }
+      },
+      async (args) => {
+        const sink = client2.mediaSink;
+        if (!sink?.listRecent) {
+          throw new McpToolError("This server writes generated files to disk \u2014 list the output directory instead.", {
+            hint: "gemini_list_recent_media applies to the hosted connector only."
+          });
+        }
+        const limit = args.limit ?? 20;
+        const page = sink.listRecentPage ? await sink.listRecentPage({ limit, sinceDay: args.since_day }) : { media: await sink.listRecent({ limit, sinceDay: args.since_day }), truncated: false };
+        const found = page.media;
+        return textResult({
+          count: found.length,
+          // Never let a bounded walk pass for the whole picture: concluding an
+          // image is gone is what makes someone pay to generate it twice.
+          ...page.truncated ? { truncated: true } : {},
+          media: found.map((m) => ({
+            r2_key: m.key,
+            day: m.day,
+            name: m.name,
+            ...m.sizeBytes !== void 0 ? { size_bytes: m.sizeBytes } : {},
+            ...m.url ? { url: m.url, curl_hint: `curl -sS -o ${downloadFilename(m.key)} "${m.url}"` } : {},
+            ...m.expiresAt ? { expires_at: m.expiresAt } : {}
+          })),
+          hint: found.length ? "Ordered by the day each object was stored (the store keeps no finer timestamp), newest first. Re-sign any expired link with gemini_sign_media." + (page.truncated ? " More media exists than is listed here \u2014 narrow with since_day, or raise limit, before concluding something is missing." : "") : "Nothing stored in that window. Media is swept on a retention schedule, so an older generation may already be gone."
+        });
+      }
+    );
   }
   server.registerTool(
     "gemini_delete_file",

package/dist/client.js

@@ -5,6 +5,7 @@ import { createDiskSink, createR2Sink, tenantIdFor } from './storage/media.js';
 import { createR2Library } from './library.js';
 import { createUploadUrlMinter } from './upload-url.js';
 import { blobStoreFromEnv } from './blob-store.js';
+import { createBlobJobStore } from './job-store.js';
 import { SessionState } from './session.js';
 import { fetchRemoteImage } from './fetch-image.js';
 // NOTE: this module must stay SIDE-EFFECT-FREE at module scope — no I/O, no
@@ -167,6 +168,14 @@ export class GeminiClient {
         // 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;
+        // Durable job records, where the deployment has somewhere to keep them.
+        // Without this the hosted connector loses a job the moment its machine
+        // stops — which it does as soon as no request is in flight (job-store.ts).
+        this.session.jobs.store = opts.jobStore;
+        // And on that runtime, `async: true` is served by HOLDING the request:
+        // releasing it is what lets the executor be reclaimed mid-generation.
+        if (opts.jobStore)
+            this.session.jobs.asyncWaitFallbackMs = HOSTED_ASYNC_WAIT_MS;
         this.explicitApiKey = opts.apiKey?.trim() || undefined;
         // Never store the global `fetch` raw on the instance: it would be invoked
         // as `this.fetchImpl(...)`, handing native fetch this GeminiClient as its
@@ -797,8 +806,24 @@ function hostedStorage() {
         }),
         library: createR2Library(blob.bucket, { tenant }),
         uploadUrls: createUploadUrlMinter({ links: blob.links, sign: blob.signWrite, tenant }),
+        // Job records go in the same store as the media, for the same reason: this
+        // runtime's machine stops whenever no request is in flight, taking the
+        // child — and an in-memory registry — with it (src/job-store.ts).
+        jobStore: createBlobJobStore(blob.bucket, { tenant }),
     };
 }
+/**
+ * How long a hosted `async: true` call holds the request open before handing
+ * back a job id.
+ *
+ * Not a tuning knob so much as the shape of the platform: holding the request
+ * is what keeps the executor alive, so this is "how long we are willing to keep
+ * the machine up for one generation". Four minutes is the value observed to
+ * work in practice against claude.ai, and comfortably covers a Pro/4K image or
+ * a modest set; anything slower hands back a durable job id rather than
+ * silently dying, which is the behaviour this whole change is for.
+ */
+const HOSTED_ASYNC_WAIT_MS = 240_000;
 /**
  * How long a freshly-minted media link lives.
  *