@chrischall/gemini-mcp 1.7.0 → 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.7.0";
+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;
@@ -34120,6 +34126,7 @@ var JobRegistry = class {
       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) : {}
     };
@@ -34205,8 +34212,30 @@ 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);
@@ -34266,6 +34295,45 @@ 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.
    */
+  /**
+   * 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) {
@@ -35010,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;
@@ -35018,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 } };
@@ -35469,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
@@ -35507,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) {
@@ -35514,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++) {
@@ -35532,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`
@@ -35567,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" });
           }
         }
       }
@@ -35586,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 {};
@@ -35786,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;
@@ -35846,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",
@@ -35864,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,
@@ -35899,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,
@@ -35908,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 };
@@ -35956,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,
@@ -35993,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,
@@ -36001,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 };
@@ -36022,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 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 },
+      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();