@chrischall/gemini-mcp 1.6.2 → 1.8.0

package/dist/bundle.js

@@ -459,15 +459,15 @@ var init_parseUtil = __esm({
           message: issueData.message
         };
       }
-      let errorMessage = "";
+      let errorMessage2 = "";
       const maps = errorMaps.filter((m) => !!m).slice().reverse();
       for (const map2 of maps) {
-        errorMessage = map2(fullIssue, { data, defaultError: errorMessage }).message;
+        errorMessage2 = map2(fullIssue, { data, defaultError: errorMessage2 }).message;
       }
       return {
         ...issueData,
         path: fullPath,
-        message: errorMessage
+        message: errorMessage2
       };
     };
     ParseStatus = class _ParseStatus {
@@ -20948,19 +20948,19 @@ var init_Refs = __esm({
 });
 
 // node_modules/zod-to-json-schema/dist/esm/errorMessages.js
-function addErrorMessage(res, key, errorMessage, refs) {
+function addErrorMessage(res, key, errorMessage2, refs) {
   if (!refs?.errorMessages)
     return;
-  if (errorMessage) {
+  if (errorMessage2) {
     res.errorMessage = {
       ...res.errorMessage,
-      [key]: errorMessage
+      [key]: errorMessage2
     };
   }
 }
-function setResponseValueAndErrors(res, key, value, errorMessage, refs) {
+function setResponseValueAndErrors(res, key, value, errorMessage2, refs) {
   res[key] = value;
-  addErrorMessage(res, key, errorMessage, refs);
+  addErrorMessage(res, key, errorMessage2, refs);
 }
 var init_errorMessages = __esm({
   "node_modules/zod-to-json-schema/dist/esm/errorMessages.js"() {
@@ -22582,8 +22582,8 @@ var init_protocol = __esm({
                       if (queuedMessage.type === "response") {
                         resolver(message);
                       } else {
-                        const errorMessage = message;
-                        const error51 = new McpError(errorMessage.error.code, errorMessage.error.message, errorMessage.error.data);
+                        const errorMessage2 = message;
+                        const error51 = new McpError(errorMessage2.error.code, errorMessage2.error.message, errorMessage2.error.data);
                         resolver(error51);
                       }
                     } else {
@@ -30763,23 +30763,23 @@ var init_server2 = __esm({
           const wrappedHandler = async (request, extra) => {
             const validatedRequest = safeParse2(CallToolRequestSchema, request);
             if (!validatedRequest.success) {
-              const errorMessage = validatedRequest.error instanceof Error ? validatedRequest.error.message : String(validatedRequest.error);
-              throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call request: ${errorMessage}`);
+              const errorMessage2 = validatedRequest.error instanceof Error ? validatedRequest.error.message : String(validatedRequest.error);
+              throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call request: ${errorMessage2}`);
             }
             const { params } = validatedRequest.data;
             const result = await Promise.resolve(handler(request, extra));
             if (params.task) {
               const taskValidationResult = safeParse2(CreateTaskResultSchema, result);
               if (!taskValidationResult.success) {
-                const errorMessage = taskValidationResult.error instanceof Error ? taskValidationResult.error.message : String(taskValidationResult.error);
-                throw new McpError(ErrorCode.InvalidParams, `Invalid task creation result: ${errorMessage}`);
+                const errorMessage2 = taskValidationResult.error instanceof Error ? taskValidationResult.error.message : String(taskValidationResult.error);
+                throw new McpError(ErrorCode.InvalidParams, `Invalid task creation result: ${errorMessage2}`);
               }
               return taskValidationResult.data;
             }
             const validationResult = safeParse2(CallToolResultSchema, result);
             if (!validationResult.success) {
-              const errorMessage = validationResult.error instanceof Error ? validationResult.error.message : String(validationResult.error);
-              throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call result: ${errorMessage}`);
+              const errorMessage2 = validationResult.error instanceof Error ? validationResult.error.message : String(validationResult.error);
+              throw new McpError(ErrorCode.InvalidParams, `Invalid tools/call result: ${errorMessage2}`);
             }
             return validationResult.data;
           };
@@ -31380,12 +31380,12 @@ var init_mcp = __esm({
        * @param errorMessage - The error message.
        * @returns The tool error result.
        */
-      createToolError(errorMessage) {
+      createToolError(errorMessage2) {
         return {
           content: [
             {
               type: "text",
-              text: errorMessage
+              text: errorMessage2
             }
           ],
           isError: true
@@ -31403,8 +31403,8 @@ var init_mcp = __esm({
         const parseResult = await safeParseAsync2(schemaToParse, args);
         if (!parseResult.success) {
           const error51 = "error" in parseResult ? parseResult.error : "Unknown error";
-          const errorMessage = getParseErrorMessage(error51);
-          throw new McpError(ErrorCode.InvalidParams, `Input validation error: Invalid arguments for tool ${toolName}: ${errorMessage}`);
+          const errorMessage2 = getParseErrorMessage(error51);
+          throw new McpError(ErrorCode.InvalidParams, `Input validation error: Invalid arguments for tool ${toolName}: ${errorMessage2}`);
         }
         return parseResult.data;
       }
@@ -31428,8 +31428,8 @@ var init_mcp = __esm({
         const parseResult = await safeParseAsync2(outputObj, result.structuredContent);
         if (!parseResult.success) {
           const error51 = "error" in parseResult ? parseResult.error : "Unknown error";
-          const errorMessage = getParseErrorMessage(error51);
-          throw new McpError(ErrorCode.InvalidParams, `Output validation error: Invalid structured content for tool ${toolName}: ${errorMessage}`);
+          const errorMessage2 = getParseErrorMessage(error51);
+          throw new McpError(ErrorCode.InvalidParams, `Output validation error: Invalid structured content for tool ${toolName}: ${errorMessage2}`);
         }
       }
       /**
@@ -31641,8 +31641,8 @@ var init_mcp = __esm({
             const parseResult = await safeParseAsync2(argsObj, request.params.arguments);
             if (!parseResult.success) {
               const error51 = "error" in parseResult ? parseResult.error : "Unknown error";
-              const errorMessage = getParseErrorMessage(error51);
-              throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for prompt ${request.params.name}: ${errorMessage}`);
+              const errorMessage2 = getParseErrorMessage(error51);
+              throw new McpError(ErrorCode.InvalidParams, `Invalid arguments for prompt ${request.params.name}: ${errorMessage2}`);
             }
             const args = parseResult.data;
             const cb = prompt.callback;
@@ -32838,7 +32838,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.6.2";
+var VERSION = "1.8.0";
 
 // src/errors.ts
 init_dist();
@@ -33078,15 +33078,15 @@ function fileNameFromUrl(url2, fallback) {
 function describeUrl(current, requested) {
   return current === requested ? current : `${current} (redirected from ${requested})`;
 }
-async function readCapped(res, maxBytes, url2, requested) {
+async function readCapped(res, maxBytes, url2, requested, subject) {
   const declared = Number(res.headers.get("content-length"));
   if (Number.isFinite(declared) && declared > maxBytes) {
-    throw tooBig(url2, requested, declared, maxBytes);
+    throw tooBig(url2, requested, declared, maxBytes, false, subject);
   }
   const reader = res.body?.getReader();
   if (!reader) {
     const buf = new Uint8Array(await res.arrayBuffer());
-    if (buf.byteLength > maxBytes) throw tooBig(url2, requested, buf.byteLength, maxBytes);
+    if (buf.byteLength > maxBytes) throw tooBig(url2, requested, buf.byteLength, maxBytes, false, subject);
     return buf;
   }
   const chunks = [];
@@ -33100,7 +33100,7 @@ async function readCapped(res, maxBytes, url2, requested) {
       if (total > maxBytes) {
         await reader.cancel().catch(() => {
         });
-        throw tooBig(url2, requested, total, maxBytes, true);
+        throw tooBig(url2, requested, total, maxBytes, true, subject);
       }
       chunks.push(value);
     }
@@ -33127,12 +33127,18 @@ function fetchFailure(err, current, requested, timeoutMs) {
     { hint: "Check the URL is reachable from the server and serves the image without authentication." }
   );
 }
-function tooBig(url2, requested, size, max, partial2 = false) {
+function tooBig(url2, requested, size, max, partial2 = false, subject) {
+  const what = subject ?? IMAGE_CAP_SUBJECT;
   return new McpToolError(
-    `Image at ${describeUrl(url2, requested)} is ${partial2 ? "over" : ""} ${formatMb(size)}, above the ${formatMb(max)} limit for images_url.`,
-    { hint: "Resize or re-encode the image, or upload it yourself with gemini_upload_file and pass the returned file_uri." }
+    `${what.noun} at ${describeUrl(url2, requested)} is ${partial2 ? "over " : ""}${formatMb(size)}, above the ${formatMb(max)} limit${what.limitFor ? ` for ${what.limitFor}` : ""}.`,
+    { hint: what.hint }
   );
 }
+var IMAGE_CAP_SUBJECT = {
+  noun: "Image",
+  limitFor: "images_url",
+  hint: "Resize or re-encode the image, or upload it yourself with gemini_upload_file and pass the returned file_uri."
+};
 async function fetchRemoteImage(requestedUrl, opts = {}) {
   const doFetch = opts.fetchImpl ?? fetch;
   const maxBytes = opts.maxBytes ?? IMAGE_URL_MAX_BYTES;
@@ -33367,6 +33373,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 +33416,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 +33591,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 +33756,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 +33858,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 +34003,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 +34043,113 @@ 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.interactionId !== void 0 ? { interactionId: entry.interactionId } : {},
+      ...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 +34185,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 +34200,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;
@@ -33991,32 +34212,80 @@ var JobRegistry = class {
     }
     const jobId = randomUUID();
     this.evict(now);
-    const promise2 = work();
-    const entry = { jobId, toolName, fingerprint, idempotencyKey, status: "running", promise: promise2, createdAt: now };
+    let entry;
+    let earlyInteractionId;
+    const ctx = {
+      reportInteraction: (interactionId) => {
+        if (!entry) {
+          earlyInteractionId = interactionId;
+          return;
+        }
+        if (entry.interactionId === interactionId) return;
+        entry.interactionId = interactionId;
+        if (this.store) this.track(this.writeRecord(entry));
+      }
+    };
+    const promise2 = work(ctx);
+    entry = {
+      jobId,
+      toolName,
+      fingerprint,
+      idempotencyKey,
+      status: "running",
+      promise: promise2,
+      createdAt: now,
+      ...earlyInteractionId !== void 0 ? { interactionId: earlyInteractionId } : {}
+    };
     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 +34295,91 @@ 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) {
+  /**
+   * The durable record for `jobId`, if there is one — including the
+   * executor-lost rewrite. Read-only view for a caller that wants to act on a
+   * record's contents (see `tools/jobs.ts` recovering an interaction id) rather
+   * than just render it.
+   */
+  async peekRecord(jobId) {
+    return this.store ? await this.store.get(jobId) : void 0;
+  }
+  /**
+   * Adopt a result produced OUTSIDE this registry — recovery reading a lost
+   * job's output back off the upstream interaction (`tools/jobs.ts`).
+   *
+   * Without this the job stays `failed` and every later poll re-enters
+   * recovery: another interaction fetch, another media download, and another
+   * copy on disk (`…-2.mp4`, `…-3.mp4`) or in R2, with nothing telling the
+   * caller they are duplicates. The ordinary done path is idempotent, so this
+   * one has to be too.
+   */
+  async adoptResult(jobId, toolName, result, interactionId) {
+    const now = this.now();
+    let entry = this.jobs.get(jobId);
+    if (!entry) {
+      entry = {
+        jobId,
+        toolName,
+        fingerprint: `recovered:${jobId}`,
+        status: "done",
+        promise: Promise.resolve(result),
+        createdAt: now
+      };
+      this.jobs.set(jobId, entry);
+    }
+    entry.status = "done";
+    entry.result = result;
+    entry.settledAt = now;
+    if (interactionId !== void 0) entry.interactionId = interactionId;
+    if (this.store) await this.writeRecord(entry);
+  }
+  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();
@@ -34739,6 +35078,21 @@ var UPLOAD_BASE_URL = "https://generativelanguage.googleapis.com/upload/v1beta";
 var FILE_MAX_BYTES = 2 * 1024 ** 3;
 var FILE_POLL_INTERVAL_MS = 2e3;
 var FILE_POLL_MAX_ATTEMPTS = 150;
+var INTERACTION_POLL_INTERVAL_MS = 3e3;
+var TERMINAL_INTERACTION_STATUSES = /* @__PURE__ */ new Set([
+  "completed",
+  "failed",
+  "cancelled",
+  "incomplete",
+  "budget_exceeded"
+]);
+var MEDIA_URI_HOST = "generativelanguage.googleapis.com";
+var MEDIA_DOWNLOAD_MAX_BYTES = 128 * 1024 * 1024;
+var MEDIA_CAP_SUBJECT = {
+  noun: "Generated media",
+  hint: "Ask for a shorter clip or a lower resolution \u2014 the file itself is still in the Files API for ~48h if you need it another way."
+};
+var INTERACTION_ID_RE = /^[\w-]+$/;
 var CHAIN_404_RETRY_BUDGET_MS = 12e4;
 var CHAIN_404_RETRY_BASE_MS = 2e3;
 var CHAIN_404_RETRY_MAX_SLEEP_MS = 3e4;
@@ -34747,18 +35101,20 @@ function resolveChainRetryBudgetMs() {
   return Number.isFinite(env) && env >= 0 ? env : CHAIN_404_RETRY_BUDGET_MS;
 }
 var ChainedRequest404Error = class extends McpToolError {
-  constructor(previousInteractionId, upstreamMessage, retries, opts) {
+  constructor(previousInteractionId, upstreamMessage, retries, opts, chainExists, verdict) {
     super(
-      `Gemini returned HTTP 404 for a chained request (previous_interaction_id: "${previousInteractionId}"), retried ${retries.attempts}\xD7 over ~${Math.round(retries.waitedMs / 1e3)}s for store lag. Upstream said: ${upstreamMessage}. This does not necessarily mean the interaction expired \u2014 an unknown model id or an expired files/\u2026 uri returns the same generic 404. (For reference: interactions are retained 55 days on the paid tier, 1 day on the free tier, and are scoped to the API key that created them.)`,
+      `Gemini returned HTTP 404 for a chained request (previous_interaction_id: "${previousInteractionId}"), retried ${retries.attempts}\xD7 over ~${Math.round(retries.waitedMs / 1e3)}s for store lag. Upstream said: ${upstreamMessage}. ` + (verdict ?? "This does not necessarily mean the interaction expired \u2014 an unknown model id or an expired files/\u2026 uri returns the same generic 404. ") + "(For reference: interactions are retained 55 days on the paid tier, 1 day on the free tier, and are scoped to the API key that created them.)",
       opts
     );
     this.previousInteractionId = previousInteractionId;
     this.upstreamMessage = upstreamMessage;
     this.retries = retries;
+    this.chainExists = chainExists;
   }
   previousInteractionId;
   upstreamMessage;
   retries;
+  chainExists;
 };
 function generatePart(img) {
   return img.uri ? { file_data: { file_uri: img.uri, mime_type: img.mimeType } } : { inline_data: { mime_type: img.mimeType, data: img.base64 } };
@@ -34810,6 +35166,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)));
@@ -35196,31 +35554,52 @@ var GeminiClient = class {
         hint: "The request may have been blocked by safety filters \u2014 try rephrasing the prompt."
       });
     }
-    return { id: data.id, images, text, grounding };
+    return { id: data.id, images: await this.downloadAll(images), text, grounding };
   }
   /**
-   * Generate video via the omni model (Interactions API, inline delivery). Same
-   * plumbing as {@link interact} — text/image input parts, a `video`
-   * response_format, optional `video_config.task`, and `previous_interaction_id`
-   * for edits. Preview model: shapes are docs-derived; parsing stays tolerant.
+   * Generate video via the omni model (Interactions API). Same plumbing as
+   * {@link interact} — text/image input parts, a `video` response_format,
+   * optional `video_config.task`, and `previous_interaction_id` for edits.
+   *
+   * Delivered by uri unless the caller says otherwise, so the clip is not
+   * capped by the ~4MB inline limit; the bytes are downloaded here either way.
+   * Verified live 2026-08-22 end to end (a real MP4 off the wire), which is
+   * why this path no longer carries the "docs-derived" caveat that music
+   * still does.
    */
   async generateVideo(opts) {
     const model = opts.model ?? DEFAULT_VIDEO_MODEL;
     const inputParts = [{ type: "text", text: opts.input }];
     for (const img of opts.images ?? []) inputParts.push(interactPart(img));
-    const responseFormat = { type: "video", delivery: "inline" };
-    if (opts.aspectRatio) responseFormat.aspect_ratio = opts.aspectRatio;
-    const body = { model, input: inputParts, response_format: responseFormat };
-    if (opts.task) body.generation_config = { video_config: { task: opts.task } };
-    if (opts.previousInteractionId !== void 0) body.previous_interaction_id = opts.previousInteractionId;
-    const data = await this.postInteraction(body, opts);
+    const delivery = opts.delivery ?? "uri";
+    const buildBody = (withDelivery) => {
+      const responseFormat = { type: "video" };
+      if (withDelivery) responseFormat.delivery = delivery;
+      if (opts.aspectRatio) responseFormat.aspect_ratio = opts.aspectRatio;
+      const body2 = { model, input: inputParts, response_format: responseFormat };
+      if (opts.task) body2.generation_config = { video_config: { task: opts.task } };
+      if (opts.previousInteractionId !== void 0) body2.previous_interaction_id = opts.previousInteractionId;
+      if (opts.background === true) body2.background = true;
+      return body2;
+    };
+    const timeoutMs = resolveTimeoutMs(opts.timeoutMs, void 0);
+    let body = buildBody(true);
+    let started;
+    try {
+      started = await this.startInteraction(body, opts, timeoutMs);
+    } catch (err) {
+      if (!isDeliveryUnsupported(err)) throw err;
+      body = buildBody(false);
+      started = await this.startInteraction(body, opts, timeoutMs);
+    }
+    const data = await this.settleInteraction(started, body, timeoutMs);
     const { videos, text } = this.extractInteraction(data);
     if (videos.length === 0) {
       throw new McpToolError("Gemini returned no video", {
-        hint: "The request may have been blocked by a safety filter, or the clip exceeded the ~4MB inline limit \u2014 try a shorter/simpler prompt or a different aspect ratio."
+        hint: "The request may have been blocked by a safety filter \u2014 try a shorter/simpler prompt or a different aspect ratio."
       });
     }
-    return { id: data.id, videos, text };
+    return { id: data.id, videos: await this.downloadAll(videos), text };
   }
   /**
    * Generate music via a Lyria model (Interactions API, inline audio). Reuses
@@ -35234,6 +35613,7 @@ var GeminiClient = class {
     if (opts.audioFormat) responseFormat.audio_format = opts.audioFormat;
     const body = { model, input: inputParts, response_format: responseFormat };
     if (opts.previousInteractionId !== void 0) body.previous_interaction_id = opts.previousInteractionId;
+    if (opts.background === true) body.background = true;
     const data = await this.postInteraction(body, opts);
     const { audios, text } = this.extractInteraction(data);
     if (audios.length === 0) {
@@ -35241,11 +35621,37 @@ var GeminiClient = class {
         hint: "The request may have been blocked by a safety filter \u2014 try rephrasing the prompt."
       });
     }
-    return { id: data.id, audios, text };
+    return { id: data.id, audios: await this.downloadAll(audios), text };
   }
-  /** POST `/interactions` with the chained-404 retry. Shared by all media. */
+  /**
+   * POST `/interactions`, wait out the store lag on a chained 404, and — when
+   * the request was backgrounded — poll until the interaction reaches a
+   * terminal state. Shared by all media.
+   */
   async postInteraction(body, opts) {
-    const { interactionsApi } = this.apisFor(resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
+    const timeoutMs = resolveTimeoutMs(opts.timeoutMs, opts.imageSize);
+    return await this.settleInteraction(await this.startInteraction(body, opts, timeoutMs), body, timeoutMs);
+  }
+  /**
+   * The POST half: issue the request and announce the id.
+   *
+   * Split from the wait so a caller can retry the POST — and ONLY the POST —
+   * without the retry predicate ever seeing an error from after the generation
+   * started. Past this point the work is running and billable.
+   */
+  async startInteraction(body, opts, timeoutMs) {
+    const started = await this.postInteractionOnce(body, opts, timeoutMs);
+    if (started.id) opts.onInteractionStarted?.(started.id);
+    return started;
+  }
+  /** The wait half: poll a backgrounded request to a terminal state. */
+  async settleInteraction(started, body, timeoutMs) {
+    if (body.background !== true) return started;
+    return await this.awaitInteraction(started, timeoutMs);
+  }
+  /** The POST itself, with the chained-404 retry + diagnosis. */
+  async postInteractionOnce(body, opts, timeoutMs) {
+    const { interactionsApi } = this.apisFor(timeoutMs);
     const budgetMs = resolveChainRetryBudgetMs();
     let waitedMs = 0;
     for (let attempt = 0; ; attempt++) {
@@ -35259,13 +35665,183 @@ var GeminiClient = class {
           await this.sleep(delay);
           continue;
         }
-        throw new ChainedRequest404Error(opts.previousInteractionId, err.message, { attempts: attempt, waitedMs }, {
-          hint: "Re-issue the request WITHOUT previous_interaction_id (re-attaching the prior output image if you were editing). If that also 404s, the interaction id is not the cause \u2014 check the model id and any files/\u2026 uri (they expire ~48h). gemini_interact does this probe automatically.",
-          cause: err
-        });
+        const { chainExists, verdict } = await this.diagnoseChain(opts.previousInteractionId);
+        throw new ChainedRequest404Error(
+          opts.previousInteractionId,
+          err.message,
+          { attempts: attempt, waitedMs },
+          {
+            hint: chainExists === true ? "The chain is alive, so re-issuing without previous_interaction_id would re-bill and still fail. Check the model id and any files/\u2026 uri instead." : "Re-issue the request WITHOUT previous_interaction_id (re-attaching the prior output image if you were editing). If that also 404s, the interaction id is not the cause \u2014 check the model id and any files/\u2026 uri (they expire ~48h). gemini_interact does this probe automatically.",
+            cause: err
+          },
+          chainExists,
+          verdict
+        );
       }
     }
   }
+  /**
+   * Ask the API whether the chained interaction is actually gone.
+   *
+   * Three answers, three remediations — and a fourth state that matters just as
+   * much: if the probe itself cannot be completed we return `undefined`, so the
+   * caller says "unknown" rather than inventing "gone".
+   */
+  async diagnoseChain(id) {
+    try {
+      await this.getInteraction(id);
+      return {
+        chainExists: true,
+        verdict: `That interaction still exists (GET /interactions/${id} returned it), so the chain is NOT the cause \u2014 a generic 404 also covers an unknown model id and an expired files/\u2026 uri (~48h). Check those. `
+      };
+    } catch (err) {
+      if (err instanceof ApiError && err.status === 404) {
+        return {
+          chainExists: false,
+          verdict: `That interaction no longer exists (GET /interactions/${id} returned 404 too) \u2014 it expired or was deleted, so re-anchor on the image it produced. That does not necessarily mean it was the cause, though: an unknown model id or an expired files/\u2026 uri returns the same generic 404, so read the upstream text above. `
+        };
+      }
+      if (err instanceof ApiError && err.status === 400) {
+        return {
+          chainExists: false,
+          verdict: `"${id}" is not a valid interaction id \u2014 the API rejected the name as malformed, so it was never a live chain. Check how the id was captured. `
+        };
+      }
+      return {};
+    }
+  }
+  /**
+   * Poll a backgrounded interaction to a terminal state.
+   *
+   * ⚠️ **A poll of work that is still in flight answers `403
+   * permission_denied`** — "There was a problem processing your request. You
+   * will not be charged." (verified live 2026-08-22, against a paid key that
+   * GETs the very same interaction fine once it completes). It is a transient
+   * state dressed as an authorization failure, and taking it at face value
+   * fails every backgrounded generation a few seconds in. A 404 is transient
+   * here too — the same store lag the chained POST retries.
+   *
+   * Neither is distinguishable from the real thing, so the caller's timeout is
+   * what bounds it, and the last poll error rides along in the timeout message
+   * so a genuine permission problem is not invisible.
+   *
+   * A body with no `status` field is likewise treated as "still running"
+   * unless a `model_output` step is already present.
+   */
+  async awaitInteraction(started, budgetMs) {
+    let current = started;
+    let waitedMs = 0;
+    let lastPollError;
+    for (; ; ) {
+      const status = current.status;
+      if (!status && (current.steps ?? []).some((step2) => step2.type === "model_output")) return current;
+      if (status && TERMINAL_INTERACTION_STATUSES.has(status)) {
+        if (status === "completed") return current;
+        throw new McpToolError(
+          `${SERVICE} interaction ${current.id} ${status} (background execution).`,
+          { hint: "A safety filter or an unsupported prompt is the usual cause \u2014 rephrase and retry. The interaction id above can be inspected while it is retained." }
+        );
+      }
+      if (waitedMs + INTERACTION_POLL_INTERVAL_MS > budgetMs) {
+        throw new McpToolError(
+          `${SERVICE} interaction ${current.id} is still running after ${Math.round(waitedMs / 1e3)}s. It continues on Google's side \u2014 the work is not lost.` + (lastPollError ? ` Last poll said: ${lastPollError}` : ""),
+          { hint: "Raise timeout_ms (or max_wait_ms) and retry, or keep the interaction id: the generation completes upstream regardless of this request." }
+        );
+      }
+      await this.sleep(INTERACTION_POLL_INTERVAL_MS);
+      waitedMs += INTERACTION_POLL_INTERVAL_MS;
+      try {
+        current = await this.getInteraction(current.id);
+        lastPollError = void 0;
+      } catch (err) {
+        if (!isTransientPoll(err)) throw err;
+        lastPollError = err instanceof Error ? err.message : String(err);
+      }
+    }
+  }
+  /**
+   * Fetch one interaction. Backs the background poll and the chained-404
+   * diagnosis; also the honest answer to "is that id still alive?".
+   */
+  async getInteraction(id) {
+    if (!INTERACTION_ID_RE.test(id)) {
+      throw new McpToolError(`Not a valid interaction id: "${id}"`, {
+        hint: "An interaction id is the opaque `id` from a previous response (e.g. v1_Chd\u2026), with no slashes or query string."
+      });
+    }
+    const { interactionsApi } = this.apisFor(resolveTimeoutMs(void 0));
+    return await interactionsApi.fetchJson("GET", `/interactions/${id}`);
+  }
+  /**
+   * Fetch a stored interaction and resolve its media to bytes.
+   *
+   * The recovery read: a generation whose executor died is still retrievable
+   * by id for as long as the interaction is retained (55 days paid, 1 day
+   * free). Returns the status alongside the media so a caller can tell "still
+   * running" from "finished with nothing".
+   */
+  async fetchInteractionMedia(id) {
+    const data = await this.getInteraction(id);
+    const { images, videos, audios, text } = this.extractInteraction(data);
+    return {
+      status: data.status,
+      images: await this.downloadAll(images),
+      videos: await this.downloadAll(videos),
+      audios: await this.downloadAll(audios),
+      text
+    };
+  }
+  /**
+   * Resolve one extracted medium to bytes.
+   *
+   * `delivery: 'uri'` hands back a Files API link, and that link **needs the
+   * api key** (verified: 403 without it), so it is not something a caller could
+   * use — the bytes have to arrive here exactly as inline delivery would. The
+   * uri is API-supplied but addresses a request we make with credentials
+   * attached, so the host is checked before it is fetched.
+   */
+  async downloadMedia(media) {
+    if (media.base64) return { base64: media.base64, mimeType: media.mimeType };
+    const requested = media.uri ?? "";
+    const doFetch = this.fetchImpl;
+    const key = this.requireKey();
+    let current = requested;
+    for (let hop = 0; ; hop++) {
+      const url2 = assertMediaHost(current, requested);
+      const res = await doFetch(url2.toString(), {
+        redirect: "manual",
+        headers: { "x-goog-api-key": key }
+      });
+      if (res.status >= 300 && res.status < 400) {
+        const location = res.headers?.get("location");
+        if (!location) {
+          throw new McpToolError(`${SERVICE} media download returned HTTP ${res.status} with no Location header for ${current}`);
+        }
+        if (hop >= MAX_REDIRECTS) {
+          throw new McpToolError(`${SERVICE} media download for ${requested} exceeded ${MAX_REDIRECTS} redirects (last hop: ${location}).`);
+        }
+        current = new URL(location, url2).toString();
+        continue;
+      }
+      if (!res.ok) {
+        throw new McpToolError(
+          `${SERVICE} media download failed (HTTP ${res.status}) for ${current}`,
+          { hint: "Generated files live in the Files API for ~48h and the download requires the api key that created them." }
+        );
+      }
+      const bytes = await readCapped(res, MEDIA_DOWNLOAD_MAX_BYTES, current, requested, MEDIA_CAP_SUBJECT);
+      return {
+        base64: bytesToBase64(bytes),
+        mimeType: media.mimeType || res.headers?.get("content-type") || "application/octet-stream"
+      };
+    }
+  }
+  /** {@link downloadMedia} over a list, preserving order. */
+  async downloadAll(media) {
+    const out = [];
+    for (const m of media) out.push(await this.downloadMedia(m));
+    return out;
+  }
   /**
    * Collect `model_output` media (image/video/audio) + text + grounding from an
    * interactions response. Only the `model_output` step is surfaced — `thought`
@@ -35294,12 +35870,13 @@ var GeminiClient = class {
       for (const parts of [step2.content ?? [], step2.summary ?? []]) {
         for (const part of parts) {
           const mime = part.mime_type ?? part.mimeType;
-          if (part.data) {
-            if (part.type === "image") images.push({ base64: part.data, mimeType: mime ?? "image/jpeg" });
-            else if (part.type === "video") videos.push({ base64: part.data, mimeType: mime ?? "video/mp4" });
-            else if (part.type === "audio") audios.push({ base64: part.data, mimeType: mime ?? "audio/mpeg" });
-          } else if (part.type === "text" && part.text?.trim()) {
-            textParts.push(part.text);
+          if (part.type === "text") {
+            if (part.text?.trim()) textParts.push(part.text);
+          } else if (part.data || part.uri) {
+            const carrier = part.data ? { base64: part.data } : { uri: part.uri };
+            if (part.type === "image") images.push({ ...carrier, mimeType: mime ?? "image/jpeg" });
+            else if (part.type === "video") videos.push({ ...carrier, mimeType: mime ?? "video/mp4" });
+            else if (part.type === "audio") audios.push({ ...carrier, mimeType: mime ?? "audio/mpeg" });
           }
         }
       }
@@ -35313,6 +35890,27 @@ var GeminiClient = class {
     return { images, videos, audios, text: textParts.join("\n") || void 0, grounding };
   }
 };
+function assertMediaHost(candidate, requested) {
+  let parsed;
+  try {
+    parsed = new URL(candidate);
+  } catch {
+    throw new McpToolError(`${SERVICE} returned a media reference that is not a URL: ${candidate || "(empty)"}`);
+  }
+  if (parsed.protocol !== "https:" || parsed.hostname !== MEDIA_URI_HOST) {
+    throw new McpToolError(
+      `${SERVICE} media download was pointed at an unexpected host (${parsed.hostname || candidate}); expected ${MEDIA_URI_HOST}` + (candidate === requested ? "" : ` (redirected from ${requested})`),
+      { hint: "Generated media is served from the Files API on that host only. Report this if it reproduces \u2014 it should not happen." }
+    );
+  }
+  return parsed;
+}
+function isTransientPoll(err) {
+  return err instanceof ApiError && (err.status === 403 || err.status === 404);
+}
+function isDeliveryUnsupported(err) {
+  return err instanceof ApiError && err.status === 400 && /delivery/i.test(err.message);
+}
 function hostedStorage() {
   const blob = blobStoreFromEnv();
   if (!blob) return {};
@@ -35339,9 +35937,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());
@@ -35508,6 +36111,7 @@ function registerInteractTools(server, client2) {
             return await client2.interact({ ...callOpts, images: inputs.length ? inputs : void 0, previousInteractionId });
           } catch (err) {
             if (!(err instanceof ChainedRequest404Error)) throw err;
+            if (err.chainExists === true) throw err;
             if (!onDisk) throw err;
             const reanchorOn = await findInteractionImages(resolveOutputDir(args.output_dir), err.previousInteractionId);
             if (!reanchorOn.length) throw err;
@@ -35568,6 +36172,7 @@ init_dist();
 init_images();
 var VIDEO_ASPECT_RATIOS = ["16:9", "9:16"];
 var VIDEO_TASKS = ["text_to_video", "image_to_video", "reference_to_video", "edit"];
+var VIDEO_DELIVERY = ["inline", "uri"];
 function registerVideoTools(server, client2) {
   server.registerTool(
     "gemini_video_generate",
@@ -35586,6 +36191,8 @@ function registerVideoTools(server, client2) {
         filename: external_exports.string().optional().describe("Base filename for the output video (extension stripped; default: slugified prompt)"),
         output_dir: external_exports.string().optional().describe("Directory to write the video to (default: $GEMINI_OUTPUT_DIR or cwd)"),
         model: external_exports.string().regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")').optional().describe(`Model id override (default: ${DEFAULT_VIDEO_MODEL})`),
+        delivery: external_exports.enum(VIDEO_DELIVERY).optional().describe('How the clip comes back: "uri" (default \u2014 a Files API link the server downloads, no size ceiling) or "inline" (base64, capped ~4MB)'),
+        background: external_exports.boolean().optional().describe("Run the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Trade-off: retrieving a backgrounded interaction is unreliable today (some become permanently unreadable), so the default is off"),
         previous_interaction_id: external_exports.string().optional().describe('Interaction id to edit/continue (with task: "edit")'),
         continue_last: external_exports.boolean().optional().describe("Continue from the most recent video interaction this server created (explicit previous_interaction_id wins)"),
         timeout_ms: timeoutMsSchema,
@@ -35621,7 +36228,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, waitMs: args.max_wait_ms }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_video_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {
         const { inputs, report } = await resolveImageInputs(args, client2);
         const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client2.generateVideo({
           input: args.prompt,
@@ -35630,7 +36237,13 @@ function registerVideoTools(server, client2) {
           aspectRatio: args.aspect_ratio,
           task: args.task,
           previousInteractionId,
-          timeoutMs: args.timeout_ms
+          timeoutMs: args.timeout_ms,
+          delivery: args.delivery,
+          background: args.background,
+          // Hand the id to the job record the moment it exists: if this
+          // machine stops mid-generation, that id is the only route back to
+          // an output that finishes upstream anyway.
+          onInteractionStarted: ctx.reportInteraction
         }));
         client2.session.lastVideoInteractionId = r.id;
         const meta3 = { model, interaction_id: r.id };
@@ -35678,6 +36291,7 @@ function registerMusicTools(server, client2) {
         inline: external_exports.boolean().optional().describe("Return base64 audio inline instead of writing to disk"),
         previous_interaction_id: external_exports.string().optional().describe("Interaction id to continue from"),
         continue_last: external_exports.boolean().optional().describe("Continue from the most recent music interaction this server created (explicit previous_interaction_id wins)"),
+        background: external_exports.boolean().optional().describe("Run the generation on Google's side and poll it, so a killed job can be recovered by gemini_get_result. Off by default \u2014 see gemini_video_generate"),
         timeout_ms: timeoutMsSchema,
         idempotency_key: idempotencyKeySchema,
         async: asyncSchema,
@@ -35715,7 +36329,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, waitMs: args.max_wait_ms }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_music_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {
         const { inputs, report } = await resolveImageInputs(args, client2);
         const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client2.generateMusic({
           input: args.prompt,
@@ -35723,7 +36337,10 @@ function registerMusicTools(server, client2) {
           model: args.model,
           audioFormat: args.audio_format,
           previousInteractionId,
-          timeoutMs: args.timeout_ms
+          timeoutMs: args.timeout_ms,
+          background: args.background,
+          // See gemini_video_generate: the id is what survives the executor.
+          onInteractionStarted: ctx.reportInteraction
         }));
         client2.session.lastMusicInteractionId = r.id;
         const meta3 = { model, interaction_id: r.id };
@@ -35744,19 +36361,84 @@ function registerMusicTools(server, client2) {
 
 // src/tools/jobs.ts
 init_zod();
+init_dist();
+init_images();
 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.',
-      annotations: { readOnlyHint: true, openWorldHint: false },
+      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. A killed video/music job started with `background: true` is recovered from its upstream interaction when it finished there.',
+      // NOT read-only any more: recovering a killed job writes the media it
+      // pulls back, exactly as the generation tool would have.
+      annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
-        job_id: external_exports.string().min(1).describe("The job_id returned by a generation tool called with async: true")
+        job_id: external_exports.string().min(1).describe("The job_id returned by a generation tool called with async: true"),
+        output_dir: external_exports.string().optional().describe("Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or cwd)")
       }
     },
-    async (args) => client2.session.jobs.getResult(args.job_id)
+    async (args) => {
+      try {
+        return await client2.session.jobs.getResult(args.job_id);
+      } catch (err) {
+        const recovered = await recoverFromInteraction(client2, args.job_id, args.output_dir, err);
+        if (recovered) return recovered;
+        throw err;
+      }
+    }
   );
 }
+async function recoverFromInteraction(client2, jobId, outputDir, original) {
+  const record2 = await client2.session.jobs.peekRecord(jobId);
+  const interactionId = record2?.interactionId;
+  if (!interactionId || record2?.status !== "failed") return void 0;
+  let found;
+  try {
+    found = await client2.fetchInteractionMedia(interactionId);
+  } catch (probeErr) {
+    if (isInFlight(probeErr)) return stillRunning(jobId, interactionId);
+    throw new McpToolError(
+      `${errorMessage(original)} Its upstream interaction "${interactionId}" could not be read either (${errorMessage(probeErr)}), so the output is not recoverable.`,
+      { hint: "Any media the lost run did write is still listed by gemini_list_recent_media. Otherwise the generation has to be re-run." }
+    );
+  }
+  const [kind, media] = found.videos.length ? ["video", found.videos] : found.audios.length ? ["audio", found.audios] : found.images.length ? ["image", found.images] : ["image", []];
+  if (media.length === 0) {
+    if (found.status && !TERMINAL_INTERACTION_STATUSES.has(found.status)) return stillRunning(jobId, interactionId);
+    return void 0;
+  }
+  const slug = slugify2(`recovered-${interactionId}`.slice(0, 60));
+  const named = media.map((m, i) => ({
+    media: m,
+    base: media.length > 1 ? `${slug}-${String(i + 1).padStart(2, "0")}` : slug
+  }));
+  const result = await emitMedia(named, kind, { output_dir: outputDir, sink: client2.mediaSink }, {
+    job_id: jobId,
+    recovered_from_interaction: interactionId,
+    note: recoveryNote(record2.error?.message),
+    ...found.text ? { text: found.text } : {}
+  });
+  await client2.session.jobs.adoptResult(jobId, record2.toolName, result, interactionId);
+  return result;
+}
+function recoveryNote(recordedError) {
+  const cause = /was lost:/.test(recordedError ?? "") ? "The executor that started this job was reclaimed before it could return." : "This job failed here before it could return its output.";
+  return `${cause} The generation had already completed upstream and its output was recovered \u2014 it was not re-run, and you were not billed twice.`;
+}
+function stillRunning(jobId, interactionId) {
+  return textResult({
+    job_id: jobId,
+    status: "running",
+    interaction_id: interactionId,
+    note: "The executor that started this job is gone, but the generation is still running upstream. Poll again \u2014 it has not been lost, and re-running it would bill a second time."
+  });
+}
+function isInFlight(err) {
+  const status = err?.status;
+  return status === 403 || status === 404;
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 
 // src/tools/files.ts
 init_zod();
@@ -35928,6 +36610,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",