@chrischall/gemini-mcp 1.6.2 → 1.8.0

package/dist/client.js

@@ -5,8 +5,10 @@ import { createDiskSink, createR2Sink, tenantIdFor } from './storage/media.js';
 import { createR2Library } from './library.js';
 import { createUploadUrlMinter } from './upload-url.js';
 import { blobStoreFromEnv } from './blob-store.js';
+import { createBlobJobStore } from './job-store.js';
 import { SessionState } from './session.js';
-import { fetchRemoteImage } from './fetch-image.js';
+import { fetchRemoteImage, readCapped, MAX_REDIRECTS } from './fetch-image.js';
+import { bytesToBase64 } from './bytes.js';
 // NOTE: this module must stay SIDE-EFFECT-FREE at module scope — no I/O, no
 // top-level await, no `import.meta.url`. `src/worker.ts` imports it, so every
 // line here runs during Cloudflare isolate startup, where global-scope I/O is
@@ -46,6 +48,39 @@ const FILE_MAX_BYTES = 2 * 1024 ** 3;
 // in ~1s (verified); longer videos take proportionally longer to process.
 const FILE_POLL_INTERVAL_MS = 2_000;
 const FILE_POLL_MAX_ATTEMPTS = 150;
+// Background execution (verified live 2026-08-22): `background: true` returns
+// `in_progress` immediately and the work continues server-side, polled via
+// `GET /interactions/{id}`. Supported by omni (video) and Lyria (music) and
+// NOT by the image models, which 400 with "does not support background
+// interactions" — so only generateVideo/generateMusic send it.
+//
+// The poll stays IN BAND, bounded by the caller's own timeout: on mcp-host the
+// machine stops whenever no request is in flight, so answering early and
+// polling in the background would race a shutdown it loses. Background buys a
+// short-lived upstream socket and an id that outlives us, not a fire-and-forget.
+const INTERACTION_POLL_INTERVAL_MS = 3_000;
+// Statuses that mean the work is over. Anything else — including no status
+// field at all, which two consecutive live polls returned — means keep waiting.
+export const TERMINAL_INTERACTION_STATUSES = new Set([
+    'completed', 'failed', 'cancelled', 'incomplete', 'budget_exceeded',
+]);
+// Generated media comes back as a Files API link on this host and no other. The
+// uri is API-supplied, but it addresses a fetch we make with the API key
+// attached, so it is validated like any other outbound URL in this repo.
+const MEDIA_URI_HOST = 'generativelanguage.googleapis.com';
+// Cap on a single generated-media download. Generous next to what the models
+// actually emit (a 10s 720p clip measured 2.6MB; 10s of 4k is ~60MB) and still
+// bounded, because the bytes are base64'd in memory afterwards — roughly 1.33×
+// again — before the sink ever sees them.
+const MEDIA_DOWNLOAD_MAX_BYTES = 128 * 1024 * 1024;
+/** How an over-cap generated-media download describes itself. */
+const MEDIA_CAP_SUBJECT = {
+    noun: 'Generated media',
+    hint: 'Ask for a shorter clip or a lower resolution — the file itself is still in the Files API for ~48h if you need it another way.',
+};
+// A well-formed interaction id (`v1_Chd…`). Interpolated into the URL path, so
+// it is guarded the same way the model id and file name are.
+const INTERACTION_ID_RE = /^[\w-]+$/;
 // The interactions store is eventually consistent: a freshly returned id can
 // 404 while the SAME id + key resolves fine *minutes* later (observed live
 // 2026-07-06, verified against a real failing id created moments before the
@@ -87,17 +122,30 @@ export class ChainedRequest404Error extends McpToolError {
     previousInteractionId;
     upstreamMessage;
     retries;
+    chainExists;
     constructor(previousInteractionId, 
     /** The upstream error text, verbatim (already redacted + truncated). */
     upstreamMessage, 
     /** How hard we waited out the store lag before giving up. */
-    retries, opts) {
+    retries, opts, 
+    /**
+     * What `GET /interactions/{id}` said afterwards: `false` the interaction is
+     * gone (or was never a valid id), `true` it is alive so the 404 was about
+     * something else, `undefined` the probe itself could not be completed.
+     * Undefined is deliberately distinct from false — "we don't know" must not
+     * read as "it's gone".
+     */
+    chainExists, 
+    /** The one sentence the probe earned us; appended to the message. */
+    verdict) {
         super(`Gemini returned HTTP 404 for a chained request (previous_interaction_id: "${previousInteractionId}"), retried ${retries.attempts}× over ~${Math.round(retries.waitedMs / 1000)}s for store lag. Upstream said: ${upstreamMessage}. ` +
-            'This does not necessarily mean the interaction expired — an unknown model id or an expired files/… uri returns the same generic 404. ' +
+            (verdict ??
+                'This does not necessarily mean the interaction expired — an unknown model id or an expired files/… 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;
     }
 }
 /** `generateContent` part for one reference image (by uri, else inline). */
@@ -167,6 +215,14 @@ export class GeminiClient {
         // A replayed idempotent result must not hand back an expired media URL, so
         // the job registry needs a way to re-sign from the stable r2_key.
         this.session.jobs.resigner = this.mediaSink;
+        // Durable job records, where the deployment has somewhere to keep them.
+        // Without this the hosted connector loses a job the moment its machine
+        // stops — which it does as soon as no request is in flight (job-store.ts).
+        this.session.jobs.store = opts.jobStore;
+        // And on that runtime, `async: true` is served by HOLDING the request:
+        // releasing it is what lets the executor be reclaimed mid-generation.
+        if (opts.jobStore)
+            this.session.jobs.asyncWaitFallbackMs = HOSTED_ASYNC_WAIT_MS;
         this.explicitApiKey = opts.apiKey?.trim() || undefined;
         // Never store the global `fetch` raw on the instance: it would be invoked
         // as `this.fetchImpl(...)`, handing native fetch this GeminiClient as its
@@ -597,35 +653,69 @@ export class GeminiClient {
                 hint: 'The request may have been blocked by safety filters — 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 !== undefined)
-            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 body = { model, input: inputParts, response_format: responseFormat };
+            if (opts.task)
+                body.generation_config = { video_config: { task: opts.task } };
+            if (opts.previousInteractionId !== undefined)
+                body.previous_interaction_id = opts.previousInteractionId;
+            // OPT-IN, not the default — see the background note on MusicOpts and
+            // docs/GEMINI-API.md: omni accepts `background: true`, but polling the
+            // resulting interaction is unreliable enough to lose a paid generation.
+            if (opts.background === true)
+                body.background = true;
+            return body;
+        };
+        // The fallback wraps the POST ALONE. `delivery` is model-implemented, not
+        // just schema-valid: omni takes it, another video model may answer
+        // "<Media> delivery mode is not supported." A 400 on the POST generated
+        // nothing, so re-issuing without the field is free — but a 400 arriving
+        // any later (from a background poll, say) is a 400 about a generation that
+        // is already running, and re-issuing THAT would pay for the clip twice.
+        const timeoutMs = resolveTimeoutMs(opts.timeoutMs, undefined);
+        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 — try a shorter/simpler prompt or a different aspect ratio.',
+                hint: 'The request may have been blocked by a safety filter — 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
@@ -642,6 +732,9 @@ export class GeminiClient {
         const body = { model, input: inputParts, response_format: responseFormat };
         if (opts.previousInteractionId !== undefined)
             body.previous_interaction_id = opts.previousInteractionId;
+        // Opt-in for the same reason video's is (see VideoOpts.background).
+        if (opts.background === true)
+            body.background = true;
         const data = await this.postInteraction(body, opts);
         const { audios, text } = this.extractInteraction(data);
         if (audios.length === 0) {
@@ -649,11 +742,44 @@ export class GeminiClient {
                 hint: 'The request may have been blocked by a safety filter — 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);
+        // Announce the id before waiting on anything: a caller that persists it can
+        // recover the output even if this process never sees the result.
+        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) {
+        // Polling only happens for a request we backgrounded. A synchronous POST
+        // already carries its output, and some responses legitimately arrive with
+        // no `status` at all — polling those would hang on a finished generation.
+        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++) {
@@ -666,9 +792,7 @@ export class GeminiClient {
                 //
                 // What it is NOT is a diagnosis. We only know the status; the body is
                 // generic ("Requested entity was not found.") and covers a bad model id
-                // and an expired files/… uri just as well as a dead interaction. So the
-                // error carries the upstream text and says what it doesn't know — the
-                // caller (tools/interact.ts) probes to find out which it was.
+                // and an expired files/… uri just as well as a dead interaction.
                 if (!(opts.previousInteractionId && err instanceof ApiError && err.status === 404))
                     throw err;
                 // Exponential backoff until the budget is spent. Sized against the
@@ -681,13 +805,198 @@ export class GeminiClient {
                     await this.sleep(delay);
                     continue;
                 }
+                // The budget is spent, so now ASK about the one entity we can ask
+                // about. The probe is free (a 404'd POST generated nothing, and a GET
+                // generates nothing), and it turns the guess into a fact — or into an
+                // explicit "unknown", which is not the same as "gone".
+                const { chainExists, verdict } = await this.diagnoseChain(opts.previousInteractionId);
                 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 — check the model id and any files/… uri (they expire ~48h). gemini_interact does this probe automatically.',
+                    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/… 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 — check the model id and any files/… 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 — ` +
+                    'a generic 404 also covers an unknown model id and an expired files/… 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) — 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/… 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 — 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;
+            // Absent status means "still running" ONLY while nothing has been
+            // produced. A body carrying a model_output step is finished whatever it
+            // says about status — polling that forever would hang on a done job.
+            if (!status && (current.steps ?? []).some((step) => step.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 — rephrase and retry. The interaction id above can be inspected while it is retained.' });
+            }
+            if (waitedMs + INTERACTION_POLL_INTERVAL_MS > budgetMs) {
+                // The generation did NOT stop when we did: it is still running and
+                // still billable upstream, so an error that drops the id throws the
+                // work away.
+                throw new McpToolError(`${SERVICE} interaction ${current.id} is still running after ${Math.round(waitedMs / 1000)}s. It continues on Google's side — 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 = undefined;
+            }
+            catch (err) {
+                if (!isTransientPoll(err))
+                    throw err;
+                lastPollError = err instanceof Error ? err.message : String(err);
+                // Keep the last known interaction (its id is all the next poll needs).
+            }
+        }
+    }
+    /**
+     * 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…), with no slashes or query string.',
+            });
+        }
+        const { interactionsApi } = this.apisFor(resolveTimeoutMs(undefined));
+        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 ?? '';
+        // Local alias so the calls below carry NO receiver (see uploadToFilesApi).
+        const doFetch = this.fetchImpl;
+        const key = this.requireKey();
+        let current = requested;
+        for (let hop = 0;; hop++) {
+            // EVERY hop is revalidated, not just the first. This request carries the
+            // API key, so a redirect — which the response, not us, controls — must
+            // never be able to walk that credential onto another host. Same rule
+            // fetch-image.ts enforces, and stricter: there is exactly one host
+            // generated media is ever served from.
+            const url = assertMediaHost(current, requested);
+            const res = await doFetch(url.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, url).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.' });
+            }
+            // Capped while streaming rather than buffered whole: a generated clip is
+            // small, but `arrayBuffer()` on a surprise is an unbounded allocation.
+            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`
@@ -724,16 +1033,24 @@ export class GeminiClient {
             for (const parts of [step.content ?? [], step.summary ?? []]) {
                 for (const part of parts) {
                     const mime = part.mime_type ?? part.mimeType;
-                    if (part.data) {
+                    // Branch on what the part SAYS IT IS, never on which fields it
+                    // happens to carry: a text part may also carry a uri (grounded
+                    // responses annotate them), and keying off `uri` would file it as
+                    // media and drop its text on the floor.
+                    if (part.type === 'text') {
+                        if (part.text?.trim())
+                            textParts.push(part.text);
+                    }
+                    else if (part.data || part.uri) {
+                        // `delivery: 'uri'` replaces `data` with a Files API link — the part
+                        // carries one or the other, never both. downloadMedia() resolves it.
+                        const carrier = part.data ? { base64: part.data } : { uri: part.uri };
                         if (part.type === 'image')
-                            images.push({ base64: part.data, mimeType: mime ?? 'image/jpeg' });
+                            images.push({ ...carrier, mimeType: mime ?? 'image/jpeg' });
                         else if (part.type === 'video')
-                            videos.push({ base64: part.data, mimeType: mime ?? 'video/mp4' });
+                            videos.push({ ...carrier, 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);
+                            audios.push({ ...carrier, mimeType: mime ?? 'audio/mpeg' });
                     }
                 }
             }
@@ -749,6 +1066,46 @@ export class GeminiClient {
         return { images, videos, audios, text: textParts.join('\n') || undefined, grounding };
     }
 }
+/**
+ * A 400 that means "this model does not implement response_format.delivery".
+ * Verified live 2026-08-22: image and audio answer "<Media> delivery mode is
+ * not supported."; a value outside the enum answers "…not supported for
+ * 'response_format.delivery'". Both are cheap to recover from — the request
+ * never reached generation.
+ */
+/**
+ * Is this poll failure the API being unhelpful about work in progress?
+ *
+ * `403 permission_denied` is what a GET of an in-flight background interaction
+ * returns (verified live), and `404` is the same eventual-consistency lag the
+ * chained POST already waits out. Both resolve on their own; a real 403 simply
+ * runs out the caller's clock and is reported with its text.
+ */
+/**
+ * One hop of a generated-media download, checked before it is fetched.
+ * Generated media is served from exactly one host over https; anything else is
+ * either a change we need to notice or a redirect trying to collect our key.
+ */
+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 — 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);
+}
 /**
  * Everything that needs somewhere to put bytes, when the host offers a blob
  * store (`MCP_BLOB_BASE_URL` / `MCP_BLOB_SIGNING_KEY`, injected by mcp-host).
@@ -797,8 +1154,24 @@ function hostedStorage() {
         }),
         library: createR2Library(blob.bucket, { tenant }),
         uploadUrls: createUploadUrlMinter({ links: blob.links, sign: blob.signWrite, tenant }),
+        // Job records go in the same store as the media, for the same reason: this
+        // runtime's machine stops whenever no request is in flight, taking the
+        // child — and an in-memory registry — with it (src/job-store.ts).
+        jobStore: createBlobJobStore(blob.bucket, { tenant }),
     };
 }
+/**
+ * How long a hosted `async: true` call holds the request open before handing
+ * back a job id.
+ *
+ * Not a tuning knob so much as the shape of the platform: holding the request
+ * is what keeps the executor alive, so this is "how long we are willing to keep
+ * the machine up for one generation". Four minutes is the value observed to
+ * work in practice against claude.ai, and comfortably covers a Pro/4K image or
+ * a modest set; anything slower hands back a durable job id rather than
+ * silently dying, which is the behaviour this whole change is for.
+ */
+const HOSTED_ASYNC_WAIT_MS = 240_000;
 /**
  * How long a freshly-minted media link lives.
  *

package/dist/fetch-image.js

@@ -37,7 +37,7 @@ export const IMAGE_URL_MAX_BYTES = 15 * 1024 * 1024;
  */
 export const IMAGE_INLINE_MAX_BYTES = 6 * 1024 * 1024;
 /** Redirect hops followed before giving up. */
-const MAX_REDIRECTS = 5;
+export const MAX_REDIRECTS = 5;
 /**
  * Per-hop abort budget. Matches the client's default upstream timeout so a URL
  * fetch is bounded like every other network call this server makes; callers
@@ -235,10 +235,10 @@ function describeUrl(current, requested) {
     return current === requested ? current : `${current} (redirected from ${requested})`;
 }
 /** Read a response body, aborting as soon as it exceeds `maxBytes`. */
-async function readCapped(res, maxBytes, url, requested) {
+export async function readCapped(res, maxBytes, url, requested, subject) {
     const declared = Number(res.headers.get('content-length'));
     if (Number.isFinite(declared) && declared > maxBytes) {
-        throw tooBig(url, requested, declared, maxBytes);
+        throw tooBig(url, requested, declared, maxBytes, false, subject);
     }
     const reader = res.body?.getReader();
     if (!reader) {
@@ -246,7 +246,7 @@ async function readCapped(res, maxBytes, url, requested) {
         // then apply the same cap. Correct, just less eager.
         const buf = new Uint8Array(await res.arrayBuffer());
         if (buf.byteLength > maxBytes)
-            throw tooBig(url, requested, buf.byteLength, maxBytes);
+            throw tooBig(url, requested, buf.byteLength, maxBytes, false, subject);
         return buf;
     }
     const chunks = [];
@@ -261,7 +261,7 @@ async function readCapped(res, maxBytes, url, requested) {
             total += value.byteLength;
             if (total > maxBytes) {
                 await reader.cancel().catch(() => { });
-                throw tooBig(url, requested, total, maxBytes, true);
+                throw tooBig(url, requested, total, maxBytes, true, subject);
             }
             chunks.push(value);
         }
@@ -287,9 +287,21 @@ function fetchFailure(err, current, requested, timeoutMs) {
     }
     return new McpToolError(`Could not fetch ${describeUrl(current, requested)}: ${err instanceof Error ? err.message : String(err)}`, { hint: 'Check the URL is reachable from the server and serves the image without authentication.' });
 }
-function tooBig(url, requested, size, max, partial = false) {
-    return new McpToolError(`Image at ${describeUrl(url, requested)} is ${partial ? '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.' });
+/**
+ * `subject` names what was too big and how to act on it. It defaults to the
+ * `images_url` wording because that is where the cap started, but the reader is
+ * shared now — a generated-video download reusing it must not tell the caller
+ * to resize an image.
+ */
+function tooBig(url, requested, size, max, partial = false, subject) {
+    const what = subject ?? IMAGE_CAP_SUBJECT;
+    return new McpToolError(`${what.noun} at ${describeUrl(url, requested)} is ${partial ? 'over ' : ''}${formatMb(size)}, above the ${formatMb(max)} limit${what.limitFor ? ` for ${what.limitFor}` : ''}.`, { hint: what.hint });
 }
+const 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.',
+};
 /**
  * Fetch one image URL server-side, validating protocol, destination, response
  * status, content type and size. Every failure names the offending URL in the