@chrischall/gemini-mcp 1.0.2 → 1.0.4

package/dist/client.js

@@ -1,9 +1,14 @@
-import { basename, dirname, join } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { loadDotenvSafely, readEnvVar, McpToolError, ApiError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
+import { basename } from 'node:path';
+import { readEnvVar, McpToolError, ApiError, createApiClient, formatApiError, fileBlob } from '@chrischall/mcp-utils';
 import { resolveModel, filterImageModels, DEFAULT_VIDEO_MODEL, DEFAULT_MUSIC_MODEL } from './models.js';
-const __dirname = dirname(fileURLToPath(import.meta.url));
-await loadDotenvSafely({ path: join(__dirname, '..', '.env'), override: false });
+import { createDiskSink } from './storage/media.js';
+import { SessionState } from './session.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
+// forbidden and wrangler's bundle leaves `import.meta.url` undefined. The
+// stdio `.env` bootstrap that used to live here now lives in `src/dotenv.ts`,
+// imported only by `src/index.ts`. Guarded by tests/connector-boot.test.ts.
 const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'; // v1 lacks gemini-3-pro-image; confirmed via Task 5
 const SERVICE = 'Gemini';
 const INTERACTIONS_SERVICE = 'Gemini Interactions';
@@ -38,30 +43,87 @@ const FILE_MAX_BYTES = 2 * 1024 ** 3;
 const FILE_POLL_INTERVAL_MS = 2_000;
 const FILE_POLL_MAX_ATTEMPTS = 150;
 // The interactions store is eventually consistent: a freshly returned id can
-// 404 for a short window right after its turn completes (observed live
-// 2026-07-06 — an id that 404'd on an immediate chain resolved fine minutes
-// later). A chained 404 generated nothing (no cost), so retry before giving up:
-// attempts wait 2s then 4s (~6s total).
-const CHAIN_404_RETRIES = 2;
-const CHAIN_404_RETRY_MS = 2_000;
+// 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
+// failure — docs/GEMINI-API.md). The lag is intermittent and load-dependent, so
+// a heavy turn (4K / Pro / thinking:high) is the likeliest to hit it — which is
+// exactly the turn a caller most wants to chain from.
+//
+// This budget used to be two fixed retries (~6s total) against a lag the repo's
+// own notes measured in minutes, so every rapid iteration surfaced as an expired
+// chain. Match the budget to the observed lag instead: exponential backoff
+// (capped per-sleep) until the budget is spent. A 404'd chained call generates
+// nothing and is not billed, so waiting costs only time — and under `async: true`
+// nothing is even blocking on it.
+const CHAIN_404_RETRY_BUDGET_MS = 120_000;
+const CHAIN_404_RETRY_BASE_MS = 2_000;
+const CHAIN_404_RETRY_MAX_SLEEP_MS = 30_000;
+/** Retry budget for a chained 404: `$GEMINI_CHAIN_RETRY_MS` → 120s. */
+export function resolveChainRetryBudgetMs() {
+    const env = Number(readEnvVar('GEMINI_CHAIN_RETRY_MS'));
+    return Number.isFinite(env) && env >= 0 ? env : CHAIN_404_RETRY_BUDGET_MS;
+}
+/**
+ * A request carrying `previous_interaction_id` returned HTTP 404, after the
+ * store-lag retries were exhausted.
+ *
+ * Deliberately NOT named "chain expired": the only 404 body observed live is
+ * generic ("Requested entity was not found.") and never says *which* entity was
+ * missing. An unknown/renamed model id and an expired Files API `files/…` uri
+ * (~48h TTL) produce the same status and the same generic text, so a 404 on a
+ * chained request is evidence of *a* missing entity, not proof it was the
+ * interaction. Asserting otherwise fabricates a cause and hides the real one —
+ * which is why the upstream text is carried in the message rather than replaced.
+ *
+ * Its own type (rather than a message to regex) so `tools/interact.ts` can key
+ * its sidecar re-anchor off it; that re-issue doubles as the probe that tells
+ * the cases apart (see `chain_recovered` / `chain_not_the_cause` there).
+ */
+export class ChainedRequest404Error extends McpToolError {
+    previousInteractionId;
+    upstreamMessage;
+    retries;
+    constructor(previousInteractionId, 
+    /** The upstream error text, verbatim (already redacted + truncated). */
+    upstreamMessage, 
+    /** How hard we waited out the store lag before giving up. */
+    retries, opts) {
+        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. ' +
+            '(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;
+    }
+}
 export class GeminiClient {
-    apiKey;
-    configError;
+    /**
+     * A key handed in explicitly (the connector's per-session key). When absent
+     * the key is read from the environment at REQUEST time, not here — see
+     * `requireKey`.
+     */
+    explicitApiKey;
     apis = new Map();
     fetchImpl;
     sleep;
+    /**
+     * The media destination for every tool this client is handed to. Public and
+     * readonly: `tools/*` read `client.mediaSink` to decide disk-vs-URL output
+     * AND whether disk-only *inputs* (local paths, clipboard, video upload) are
+     * even available on this runtime.
+     */
+    mediaSink;
+    /**
+     * This client's session memory — job registry, last-interaction id, written
+     * outputs. One client is one session: the hosted connector builds a client
+     * per authenticated user, so hanging the state here is what keeps it from
+     * leaking between tenants sharing an isolate (see src/session.ts). The stdio
+     * server is single-user, so its one singleton client is one session.
+     */
+    session = new SessionState();
     constructor(opts = {}) {
-        const key = readEnvVar('GEMINI_API_KEY');
-        if (!key) {
-            this.apiKey = null;
-            this.configError = new McpToolError('GEMINI_API_KEY environment variable is required', {
-                hint: 'Create a key at https://aistudio.google.com/apikey and set GEMINI_API_KEY in your MCP host env or .env',
-            });
-        }
-        else {
-            this.apiKey = key;
-            this.configError = null;
-        }
+        this.mediaSink = opts.mediaSink ?? createDiskSink();
+        this.explicitApiKey = opts.apiKey?.trim() || undefined;
         this.fetchImpl = opts.fetchImpl ?? fetch;
         this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     }
@@ -96,10 +158,31 @@ export class GeminiClient {
         }
         return entry;
     }
+    /**
+     * The API key for this request: an explicitly-injected key (the connector's
+     * per-session key) else `$GEMINI_API_KEY`.
+     *
+     * Resolved HERE, at request time, not in the constructor — same as every
+     * other env var this client reads. Two reasons:
+     *
+     * 1. It keeps the actionable config error deferred to the first tool call, so
+     *    the server still boots and answers a host's install-time `tools/list`
+     *    probe without a key. (That was already true; this preserves it.)
+     * 2. It makes module-evaluation order irrelevant. `src/index.ts` loads `.env`
+     *    before serving, and reading the key in the constructor meant the
+     *    `client` singleton — constructed when `client.js` is first evaluated —
+     *    could latch "unset" before dotenv ran, depending on import ordering.
+     *    That is an invisible, silent failure (the key just stops working); not
+     *    depending on the order removes the hazard instead of documenting it.
+     */
     requireKey() {
-        if (this.configError)
-            throw this.configError;
-        return this.apiKey;
+        const key = this.explicitApiKey || readEnvVar('GEMINI_API_KEY');
+        if (!key) {
+            throw new McpToolError('GEMINI_API_KEY environment variable is required', {
+                hint: 'Create a key at https://aistudio.google.com/apikey and set GEMINI_API_KEY in your MCP host env or .env',
+            });
+        }
+        return key;
     }
     /** The default model after env override (no per-call arg). */
     defaultModel() {
@@ -352,24 +435,35 @@ export class GeminiClient {
     /** POST `/interactions` with the chained-404 retry. Shared by all media. */
     async postInteraction(body, opts) {
         const { interactionsApi } = this.apisFor(resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
+        const budgetMs = resolveChainRetryBudgetMs();
+        let waitedMs = 0;
         for (let attempt = 0;; attempt++) {
             try {
                 return await interactionsApi.fetchJson('POST', '/interactions', { body });
             }
             catch (err) {
-                // A 404 on a chained call means the referenced interaction wasn't found:
-                // (a) store lag right after the id was created — retry with backoff; or
-                // (b) genuinely gone — interactions are retained 55 days (paid) / 1 day
-                // (free), scoped to the API key's project. The chain is recoverable from
-                // the last output file, so the exhausted-retries error says how.
+                // A 404 on a chained call is worth retrying: the interactions store is
+                // eventually consistent, so a freshly returned id can 404 briefly.
+                //
+                // 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.
                 if (!(opts.previousInteractionId && err instanceof ApiError && err.status === 404))
                     throw err;
-                if (attempt < CHAIN_404_RETRIES) {
-                    await this.sleep(CHAIN_404_RETRY_MS * (attempt + 1));
+                // Exponential backoff until the budget is spent. Sized against the
+                // observed lag (minutes), not against how long a human likes to wait —
+                // the alternative is telling the caller their chain is dead while the
+                // API is seconds from serving it.
+                const delay = Math.min(CHAIN_404_RETRY_BASE_MS * 2 ** attempt, CHAIN_404_RETRY_MAX_SLEEP_MS);
+                if (waitedMs + delay <= budgetMs) {
+                    waitedMs += delay;
+                    await this.sleep(delay);
                     continue;
                 }
-                throw new McpToolError(`Previous interaction "${opts.previousInteractionId}" was not found (retried ${CHAIN_404_RETRIES}× — the interactions store can lag briefly after a turn completes). If the id is old: 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.`, {
-                    hint: 'Retry once more in a few seconds; if it keeps failing, start a new chain by re-attaching the last output as an input plus the same instruction, then chain the NEW interaction id.',
+                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.',
                     cause: err,
                 });
             }

package/dist/dotenv.js

@@ -0,0 +1,29 @@
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadDotenvSafely } from '@chrischall/mcp-utils';
+/**
+ * The stdio server's `.env` bootstrap. **Imported only by `src/index.ts`.**
+ *
+ * This used to run at module scope in `src/client.ts`, which put it in the
+ * hosted connector's import graph (`src/worker.ts` → `./client.js`) and so ran
+ * it during Worker isolate startup. Two things go wrong there:
+ *
+ * 1. wrangler's bundle leaves `import.meta.url` undefined, so
+ *    `fileURLToPath(import.meta.url)` threw and the isolate never booted —
+ *    `The Workers runtime failed to start`. Not a test failure: a deploy
+ *    failure, invisible to the workers-pool suite (see
+ *    `tests/connector-boot.test.ts` for why).
+ * 2. Even had it resolved, it is async I/O at global scope, which Workers
+ *    forbids — and there is no `.env` on a Worker regardless. Config arrives
+ *    through bindings.
+ *
+ * Keeping this in its own module, off `client.ts`, is what makes `client.ts`
+ * side-effect-free and therefore safe to import from a Worker.
+ *
+ * `import.meta.url` is read inside the function body, not at module scope, so
+ * merely importing this file is still inert.
+ */
+export async function loadStdioDotenv() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    await loadDotenvSafely({ path: join(here, '..', '.env'), override: false });
+}

package/dist/index.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 import { runMcp } from '@chrischall/mcp-utils';
+import { loadStdioDotenv } from './dotenv.js';
 import { VERSION } from './version.js';
 import { registerModelTools } from './tools/models.js';
 import { registerGenerateTools } from './tools/generate.js';
@@ -8,12 +9,27 @@ import { registerInteractTools } from './tools/interact.js';
 import { registerVideoTools } from './tools/video.js';
 import { registerMusicTools } from './tools/music.js';
 import { registerJobTools } from './tools/jobs.js';
-// The GeminiClient is a module-level singleton (imported by each tool module)
-// that defers its config error to the first request — so the server boots and
-// answers the host's install-time tools/list probe even without GEMINI_API_KEY.
+import { client } from './client.js';
+// Load `.env` here rather than in client.ts, which the Cloudflare Worker
+// imports: `import.meta.url` + async I/O at module scope crashes the isolate at
+// startup (see src/dotenv.ts, guarded by tests/connector-boot.test.ts).
+//
+// Ordering is deliberately NOT load-bearing: GeminiClient reads
+// $GEMINI_API_KEY at request time, so it does not matter that the `client`
+// singleton is constructed (by the import above) before this line runs.
+await loadStdioDotenv();
+// The registrars take their GeminiClient as an argument (they import only the
+// *type*), so a non-stdio entry point can build one client per authenticated
+// user. This stdio entry point threads the env-driven module-level singleton
+// through runMcp's `deps`, which passes it as each registrar's second argument.
+// That singleton defers its config error to the first request — so the server
+// boots and answers the host's install-time tools/list probe even without
+// GEMINI_API_KEY. It also owns this process's session state (job registry,
+// last-interaction memory); stdio is single-user, so one client is one session.
 await runMcp({
     name: 'gemini-mcp',
     version: VERSION,
     banner: '[gemini-mcp] This project was developed and is maintained by AI (Claude). Use at your own discretion.',
     tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerVideoTools, registerMusicTools, registerJobTools],
+    deps: client,
 });

package/dist/session.js

@@ -0,0 +1,55 @@
+import { JobRegistry } from './jobs.js';
+/**
+ * Everything the server remembers *between tool calls on behalf of one user*.
+ *
+ * All of this used to be module-level (`jobs`/`byKey`/`runningByFingerprint` in
+ * jobs.ts, `lastInteractionId`/`writtenOutputs` in tools/interact.ts). That is
+ * correct for stdio, where a process serves exactly one user — and a
+ * cross-tenant leak on the hosted connector, where Cloudflare shares ONE Worker
+ * isolate across many Durable Object instances. Module state there is shared by
+ * every authenticated claude.ai session in the isolate: the per-session
+ * `GeminiClient` isolated the API key but not the memory around it, so a
+ * colliding `idempotency_key` replayed another user's result, an identical
+ * prompt attached to another user's in-flight (billable) job, and
+ * `continue_last: true` resumed another user's interaction under your key.
+ *
+ * So session memory hangs off the `GeminiClient` — the one object the connector
+ * already builds per authenticated session (`buildClient` in src/worker.ts) and
+ * threads into every registrar. Handlers reach it as `client.session`.
+ *
+ * The rule this encodes: **`src/` must hold no module-level mutable state.**
+ * If you need to remember something across calls, put it here.
+ */
+export class SessionState {
+    /** Idempotency + async-handle registry for this session (issues #52/#53). */
+    jobs = new JobRegistry();
+    /**
+     * The most recent interaction id THIS session created — what
+     * `continue_last: true` resumes. In-memory only, so "last" means "last in
+     * this session"; a restart falls back to the newest sidecar on disk.
+     */
+    lastInteractionId;
+    /**
+     * The same, for the media-specific tools, which keep their own chains.
+     * `gemini_music_generate` IS served by the hosted connector, so this one
+     * leaked across tenants exactly as `lastInteractionId` did; video is
+     * stdio-only today but carries the identical hazard, so both are scoped here.
+     */
+    lastMusicInteractionId;
+    lastVideoInteractionId;
+    /**
+     * Absolute paths of every image this session has written. Used to drop a
+     * chained call's re-attached prior output: the interaction state already
+     * contains that image, and re-sending it as a fresh reference anchors the
+     * model against the requested edit.
+     */
+    writtenOutputs = new Set();
+    /** Forget everything. Tests use this; nothing in `src/` calls it. */
+    reset() {
+        this.jobs.reset();
+        this.lastInteractionId = undefined;
+        this.lastMusicInteractionId = undefined;
+        this.lastVideoInteractionId = undefined;
+        this.writtenOutputs.clear();
+    }
+}

package/dist/sidecar.js

@@ -0,0 +1,72 @@
+/**
+ * Reading the `<image>.json` sidecars `gemini_interact` writes next to every
+ * generated image (see `writeSidecar` in images.ts).
+ *
+ * The sidecars were introduced so an interaction id could survive a lost MCP
+ * response (host timeout). They double as an on-disk index of the whole chain,
+ * which is what makes the two chain recoveries in `tools/interact.ts` possible:
+ *
+ *  - `continue_last` outliving the server process — the in-memory
+ *    `lastInteractionId` dies with the process, but the newest sidecar in the
+ *    output dir still names the interaction to resume.
+ *  - re-anchoring after an interaction id is genuinely gone upstream — the
+ *    sidecar for that id names the image file to re-attach, which is exactly
+ *    the manual recovery the old error message asked the caller to perform.
+ */
+import { readdir, readFile, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+const SIDECAR_SUFFIX = '.json';
+/**
+ * All parseable sidecars in `dir`, newest first. Never throws: a missing dir,
+ * an unreadable file, malformed JSON, or a record with no `interaction_id` is
+ * skipped. Recovery is best-effort by definition — it must not turn a
+ * recoverable chain into a hard failure.
+ */
+export async function readSidecars(dir) {
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const entry of entries) {
+        if (!entry.endsWith(SIDECAR_SUFFIX))
+            continue;
+        const sidecarPath = join(dir, entry);
+        try {
+            const parsed = JSON.parse(await readFile(sidecarPath, 'utf8'));
+            if (typeof parsed !== 'object' || parsed === null)
+                continue;
+            const { interaction_id: interactionId, images } = parsed;
+            if (typeof interactionId !== 'string' || !interactionId)
+                continue;
+            const paths = Array.isArray(images) ? images.filter((p) => typeof p === 'string') : [];
+            records.push({
+                sidecarPath,
+                interactionId,
+                images: paths.filter((p) => existsSync(p)),
+                mtimeMs: (await stat(sidecarPath)).mtimeMs,
+            });
+        }
+        catch {
+            continue;
+        }
+    }
+    return records.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+/**
+ * Output images recorded for `interactionId` (still on disk), or `[]` if that
+ * interaction has no sidecar here. Matching is by id, never "the newest image"
+ * — re-anchoring on the wrong picture would silently corrupt the edit chain.
+ */
+export async function findInteractionImages(dir, interactionId) {
+    const records = await readSidecars(dir);
+    return records.find((r) => r.interactionId === interactionId)?.images ?? [];
+}
+/** The newest sidecar's interaction id, or undefined if `dir` has none. */
+export async function latestInteractionId(dir) {
+    return (await readSidecars(dir))[0]?.interactionId;
+}

package/dist/storage/media.js

@@ -0,0 +1,97 @@
+/**
+ * Where generated media goes.
+ *
+ * The stdio server writes images/video/audio to the local filesystem. The
+ * hosted connector (a Cloudflare Worker) has **no filesystem at all** — no
+ * `writeFile`, no output dir, and therefore no `<image>.json` sidecar — so it
+ * puts objects into an R2 bucket and hands back URLs instead of paths.
+ *
+ * `emit()` / `emitMedia()` (tools/shared.ts) route every byte through one of
+ * these, so the tool handlers themselves stay transport-neutral. The disk sink
+ * is a thin wrapper over the pre-existing `resolveOutputDir` + `writeMedia`
+ * behaviour and must stay byte-for-byte equivalent to it.
+ */
+/**
+ * The stdio sink: `resolveOutputDir(output_dir)` → `writeMedia` per item, in
+ * order (so `uniquePath`'s `name`/`name-2`/`name-3` sequencing is preserved).
+ *
+ * `node:fs` is reached through a dynamic import so this module stays loadable
+ * in a Worker, where the R2 sink is the only one ever constructed.
+ */
+export function createDiskSink() {
+    return {
+        kind: 'disk',
+        persistsFiles: true,
+        async persist(items, opts) {
+            const { writeMedia, resolveOutputDir } = await import('../images.js');
+            const dir = resolveOutputDir(opts.output_dir);
+            const refs = [];
+            // Sequential on purpose: uniquePath checks the filesystem, so writing two
+            // colliding names concurrently would race onto the same path.
+            for (const it of items)
+                refs.push(await writeMedia(dir, it.base, it.base64, it.mimeType));
+            return refs;
+        },
+        note: () => undefined,
+    };
+}
+const KEY_PREFIX_DEFAULT = 'media';
+/** Object-key-safe name: no slashes, no dot-segments, never empty. */
+function safeKeySegment(base) {
+    const cleaned = base
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/\.{2,}/g, '-')
+        .replace(/-+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '');
+    return cleaned || 'media';
+}
+/**
+ * The hosted-connector sink: one R2 object per generated item.
+ *
+ * Keys are `<prefix>/<YYYY-MM-DD>/<random>-<base>.<ext>`. The random component
+ * is what guarantees uniqueness — R2 `put` overwrites silently, so unlike the
+ * disk sink there is no "does it already exist" probe to lean on.
+ */
+export function createR2Sink(bucket, opts) {
+    const prefix = opts.prefix ?? KEY_PREFIX_DEFAULT;
+    const now = opts.now ?? (() => new Date());
+    const randomId = opts.randomId ?? (() => crypto.randomUUID().slice(0, 8));
+    const base = opts.publicBaseUrl?.replace(/\/+$/, '');
+    return {
+        kind: 'r2',
+        persistsFiles: false,
+        async persist(items, _opts) {
+            // `mediaExt` is pure string work but lives in images.ts next to node:fs
+            // imports; the dynamic import keeps that module off a Worker's eager
+            // module graph.
+            const { mediaExt } = await import('../images.js');
+            const day = now().toISOString().slice(0, 10);
+            const refs = [];
+            for (const it of items) {
+                const key = `${prefix}/${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;
+                const bytes = decodeBase64(it.base64);
+                await bucket.put(key, bytes, { httpMetadata: { contentType: it.mimeType } });
+                refs.push(base ? `${base}/${key}` : `r2://${opts.bucketName ?? 'media'}/${key}`);
+            }
+            return refs;
+        },
+        note: () => base
+            ? 'Generated media was uploaded to R2; the values above are public URLs, not local file paths. ' +
+                'This hosted connector has no filesystem, so `output_dir` is ignored and no <image>.json sidecar is written — capture interaction_id from this result to chain further turns.'
+            : 'Generated media was uploaded to R2, which is not publicly served: the values above are object refs (r2://bucket/key), NOT fetchable URLs. ' +
+                'Set MEDIA_PUBLIC_BASE_URL on the Worker to get URLs, or pass inline: true to receive the bytes directly. ' +
+                'This hosted connector has no filesystem, so `output_dir` is ignored and no <image>.json sidecar is written — capture interaction_id from this result to chain further turns.',
+    };
+}
+/**
+ * base64 → bytes without `Buffer`. `Buffer` exists in a Worker under
+ * `nodejs_compat`, but `atob` is the platform primitive on both runtimes and
+ * keeps this module free of any Node dependency.
+ */
+function decodeBase64(b64) {
+    const binary = atob(b64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}

package/dist/tools/generate.js

@@ -1,10 +1,9 @@
 import { z } from 'zod';
 import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
-import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat } from './shared.js';
-import { dispatch, fingerprintRequest } from '../jobs.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const GENERATE_ENDPOINT = '/v1beta/models/{model}:generateContent';
 const SEND_LOCAL_ACTION = 'Send local file input(s) to the Gemini API';
@@ -12,7 +11,7 @@ const SEND_LOCAL_ACTION = 'Send local file input(s) to the Gemini API';
 // results point follow-up edits at gemini_interact instead of an id.
 const REFINE_HINT = 'To iteratively refine this image, use gemini_interact (pass the output file via `images` on the first call, ' +
     'then chain `previous_interaction_id` on each subsequent call).';
-export function registerGenerateTools(server) {
+export function registerGenerateTools(server, client) {
     server.registerTool('gemini_image_generate', {
         description: 'Generate image(s) from a text prompt with a Gemini image model (Nano Banana / Nano Banana Pro). ' +
             'If the result will likely be refined iteratively, prefer gemini_interact (multi-turn) as the entry point.',
@@ -29,6 +28,10 @@ export function registerGenerateTools(server) {
             ...sharedImageSchema,
         },
     }, async (args, extra) => {
+        // Local-path / clipboard / disk-upload inputs simply do not exist on the
+        // hosted connector. Fail here — before the confirm gate previews files and
+        // before any billable call — with the base64/URL alternative.
+        assertLocalInputsAvailable(client.mediaSink, args);
         // Confirm-gate local file inputs: a prompt-injected `images`/`video_path`
         // could exfiltrate a local file. Pure text-to-image calls (no local input)
         // are unaffected. Dry-run makes NO API call.
@@ -45,13 +48,13 @@ export function registerGenerateTools(server) {
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             video_url: args.video_url, video_path: args.video_path,
         });
-        return dispatch({ toolName: 'gemini_image_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_image_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const seed = pickSeed(args.seed);
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
             const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
             // Upload ONCE (before the count loop) — every generate call references
             // the same files/… uri.
-            const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args));
+            const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args, client));
             const named = [];
             let capturedText;
             // For count>1, surface the FIRST call's grounding (each call grounds
@@ -90,10 +93,10 @@ export function registerGenerateTools(server) {
             if (video.videoFileMeta)
                 meta.video_file = video.videoFileMeta;
             meta.hint = REFINE_HINT;
-            const risk = timeoutRiskHint({ model, imageSize: args.image_size, count });
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size, count, persistsFiles: client.mediaSink?.persistsFiles });
             if (risk)
                 meta.timeout_risk = risk;
-            return emit(named, args, meta);
+            return emit(named, { ...args, sink: client.mediaSink }, meta);
         });
     });
     server.registerTool('gemini_image_edit', {
@@ -111,6 +114,7 @@ export function registerGenerateTools(server) {
             ...sharedImageSchema,
         },
     }, async (args, extra) => {
+        assertLocalInputsAvailable(client.mediaSink, args);
         const hasPaths = (args.images?.length ?? 0) > 0;
         const hasBase64 = (args.images_base64?.length ?? 0) > 0;
         if (!hasPaths && !hasBase64 && !args.from_clipboard) {
@@ -127,7 +131,7 @@ export function registerGenerateTools(server) {
             thinking_level: args.thinking_level, google_search: args.google_search,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
         });
-        return dispatch({ toolName: 'gemini_image_edit', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_image_edit', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const seed = pickSeed(args.seed);
             const slug = args.filename ? baseName(args.filename) : slugify(args.prompt);
             const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
@@ -149,10 +153,10 @@ export function registerGenerateTools(server) {
             if (result.grounding)
                 meta.grounding = result.grounding;
             meta.hint = REFINE_HINT;
-            const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: client.mediaSink?.persistsFiles });
             if (risk)
                 meta.timeout_risk = risk;
-            return emit([{ image: img, base: slug }], args, meta);
+            return emit([{ image: img, base: slug }], { ...args, sink: client.mediaSink }, meta);
         });
     });
 }