@chrischall/gemini-mcp 1.0.1 → 1.0.3

package/dist/bundle.js

@@ -32602,19 +32602,227 @@ var init_clipboard = __esm({
   }
 });
 
+// src/images.ts
+var images_exports = {};
+__export(images_exports, {
+  baseName: () => baseName,
+  decodeImageInput: () => decodeImageInput,
+  gatherImageInputs: () => gatherImageInputs,
+  loadImageInputs: () => loadImageInputs,
+  mediaExt: () => mediaExt,
+  previewImageInput: () => previewImageInput,
+  previewVideoInput: () => previewVideoInput,
+  readImageAsInline: () => readImageAsInline,
+  resolveImagePath: () => resolveImagePath,
+  resolveOutputDir: () => resolveOutputDir,
+  resolveVideoPath: () => resolveVideoPath,
+  slugify: () => slugify2,
+  uniquePath: () => uniquePath,
+  videoMimeType: () => videoMimeType,
+  writeImage: () => writeImage,
+  writeMedia: () => writeMedia,
+  writeSidecar: () => writeSidecar
+});
+import { mkdir, readFile as readFile2, writeFile, access, stat, open } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join as join3, resolve, isAbsolute } from "node:path";
+function slugify2(text, max = 40) {
+  const s = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, max).replace(/-+$/g, "");
+  return s || "image";
+}
+async function exists(p) {
+  try {
+    await access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function uniquePath(dir, base, ext) {
+  let candidate = join3(dir, `${base}.${ext}`);
+  let n = 2;
+  while (await exists(candidate)) {
+    candidate = join3(dir, `${base}-${n}.${ext}`);
+    n++;
+  }
+  return candidate;
+}
+function sniffMimeBytes(buf) {
+  if (buf.length >= 4 && buf[0] === 137 && buf[1] === 80 && buf[2] === 78 && buf[3] === 71) {
+    return "image/png";
+  }
+  if (buf.length >= 3 && buf[0] === 255 && buf[1] === 216 && buf[2] === 255) {
+    return "image/jpeg";
+  }
+  if (buf.length >= 12 && buf[0] === 82 && buf[1] === 73 && buf[2] === 70 && buf[3] === 70 && buf[8] === 87 && buf[9] === 69 && buf[10] === 66 && buf[11] === 80) {
+    return "image/webp";
+  }
+  return "image/png";
+}
+function mediaExt(mimeType) {
+  const m = mimeType.toLowerCase();
+  if (m.includes("jpeg")) return "jpg";
+  if (m.includes("webp")) return "webp";
+  if (m.includes("png")) return "png";
+  if (m.includes("mp4")) return "mp4";
+  if (m.includes("quicktime")) return "mov";
+  if (m.includes("webm")) return "webm";
+  if (m.includes("wav")) return "wav";
+  if (m.includes("mpeg") || m.includes("mp3")) return "mp3";
+  if (m.includes("ogg")) return "ogg";
+  return m.split("/")[1]?.split(";")[0]?.replace(/^x-/, "") || "bin";
+}
+async function writeMedia(dir, base, base643, mimeType) {
+  await mkdir(dir, { recursive: true });
+  const path = await uniquePath(dir, base, mediaExt(mimeType));
+  await writeFile(path, Buffer.from(base643, "base64"));
+  return resolve(path);
+}
+async function writeImage(dir, base, base643, mimeType) {
+  return writeMedia(dir, base, base643, mimeType);
+}
+async function writeSidecar(imagePath, data) {
+  await writeFile(`${imagePath}.json`, JSON.stringify(data, null, 2));
+}
+function resolveInputPath(p, kind) {
+  if (isAbsolute(p) && existsSync(p)) return p;
+  const inputDir = readEnvVar("GEMINI_INPUT_DIR");
+  if (inputDir) {
+    const candidate = join3(inputDir, p);
+    if (existsSync(candidate)) return resolve(candidate);
+  }
+  const cwd = resolve(p);
+  if (existsSync(cwd)) return cwd;
+  const hint = `Set GEMINI_INPUT_DIR to a directory containing your ${kind.toLowerCase()}s, or pass an absolute path.`;
+  throw new McpToolError(
+    `${kind} not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ""),
+    { hint }
+  );
+}
+function resolveImagePath(p) {
+  return resolveInputPath(p, "Image");
+}
+function resolveVideoPath(p) {
+  return resolveInputPath(p, "Video");
+}
+function videoMimeType(p) {
+  const ext = p.includes(".") ? p.slice(p.lastIndexOf(".") + 1).toLowerCase() : "";
+  const mime = VIDEO_MIME_BY_EXT[ext];
+  if (!mime) {
+    throw new McpToolError(`Unsupported video format: ${ext ? `.${ext}` : p}`, {
+      hint: `Supported extensions: ${Object.keys(VIDEO_MIME_BY_EXT).map((e) => `.${e}`).join(", ")}`
+    });
+  }
+  return mime;
+}
+async function previewImageInput(path) {
+  const resolved = resolveImagePath(path);
+  const { size } = await stat(resolved);
+  const fh = await open(resolved, "r");
+  try {
+    const head = Buffer.alloc(16);
+    const { bytesRead } = await fh.read(head, 0, 16, 0);
+    return { path: resolved, mimeType: sniffMimeBytes(head.subarray(0, bytesRead)), size };
+  } finally {
+    await fh.close();
+  }
+}
+async function previewVideoInput(path) {
+  const resolved = resolveVideoPath(path);
+  const { size } = await stat(resolved);
+  return { path: resolved, mimeType: videoMimeType(resolved), size };
+}
+async function readImageAsInline(path) {
+  const resolved = resolveImagePath(path);
+  const buf = await readFile2(resolved);
+  const mimeType = sniffMimeBytes(buf);
+  return { base64: buf.toString("base64"), mimeType };
+}
+function decodeImageInput(input) {
+  const trimmed = input.trim();
+  if (trimmed.startsWith("data:")) {
+    const marker = trimmed.indexOf(";base64,");
+    if (marker === -1) {
+      throw new Error(`Unsupported data URI (expected ;base64,<data>): ${trimmed.slice(0, 48)}\u2026`);
+    }
+    const mimeType = trimmed.slice(5, trimmed.indexOf(";", 5)) || "image/png";
+    return { mimeType, base64: trimmed.slice(marker + ";base64,".length) };
+  }
+  const buf = Buffer.from(trimmed, "base64");
+  return { base64: trimmed, mimeType: sniffMimeBytes(buf) };
+}
+async function loadImageInputs(paths = [], base64s = []) {
+  const fromPaths = await Promise.all(paths.map((p) => readImageAsInline(p)));
+  const fromBase64s = base64s.map((b) => decodeImageInput(b));
+  return [...fromPaths, ...fromBase64s];
+}
+async function gatherImageInputs(opts) {
+  const clipboardImages = opts.from_clipboard ? [await (await Promise.resolve().then(() => (init_clipboard(), clipboard_exports))).readClipboardImage()] : [];
+  const fileImages = await loadImageInputs(opts.images, opts.images_base64);
+  return [...clipboardImages, ...fileImages];
+}
+function baseName(name) {
+  const stripped = name.replace(/\.(png|jpe?g|webp|mp4|mov|webm|mp3|wav|ogg)$/i, "");
+  const safe = stripped.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
+  return safe || "image";
+}
+function resolveOutputDir(perCall) {
+  return perCall?.trim() || readEnvVar("GEMINI_OUTPUT_DIR") || process.cwd();
+}
+var VIDEO_MIME_BY_EXT;
+var init_images = __esm({
+  "src/images.ts"() {
+    "use strict";
+    init_dist();
+    VIDEO_MIME_BY_EXT = {
+      mp4: "video/mp4",
+      mpeg: "video/mpeg",
+      mpg: "video/mpg",
+      mov: "video/mov",
+      avi: "video/avi",
+      flv: "video/x-flv",
+      webm: "video/webm",
+      wmv: "video/wmv",
+      "3gp": "video/3gpp",
+      "3gpp": "video/3gpp"
+    };
+  }
+});
+
 // src/index.ts
 init_dist();
 
+// src/dotenv.ts
+init_dist();
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+async function loadStdioDotenv() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  await loadDotenvSafely({ path: join(here, "..", ".env"), override: false });
+}
+
 // src/version.ts
-var VERSION = "1.0.1";
+var VERSION = "1.0.3";
 
 // src/tools/models.ts
 init_dist();
+function registerModelTools(server, client2) {
+  server.registerTool(
+    "gemini_list_models",
+    {
+      description: "List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.",
+      annotations: { readOnlyHint: true }
+    },
+    async () => {
+      const models = await client2.listModels();
+      return textResult({ default: client2.defaultModel(), models });
+    }
+  );
+}
 
-// src/client.ts
+// src/tools/generate.ts
+init_zod();
 init_dist();
-import { basename, dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
 
 // src/models.ts
 var DEFAULT_IMAGE_MODEL = "gemini-3.1-flash-image";
@@ -32631,1052 +32839,1095 @@ function filterImageModels(raw) {
   }));
 }
 
-// src/client.ts
-var __dirname = dirname(fileURLToPath(import.meta.url));
-await loadDotenvSafely({ path: join(__dirname, "..", ".env"), override: false });
-var BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
-var SERVICE = "Gemini";
-var INTERACTIONS_SERVICE = "Gemini Interactions";
-var REQUEST_TIMEOUT_MS = 6e4;
-var REQUEST_TIMEOUT_4K_MS = 12e4;
-function resolveTimeoutMs(perCallMs, imageSize) {
-  if (perCallMs !== void 0 && perCallMs > 0) return perCallMs;
-  const env = Number(readEnvVar("GEMINI_TIMEOUT_MS"));
-  if (Number.isFinite(env) && env > 0) return env;
-  return imageSize === "4K" ? REQUEST_TIMEOUT_4K_MS : REQUEST_TIMEOUT_MS;
+// src/tools/generate.ts
+init_images();
+
+// src/tools/shared.ts
+init_zod();
+init_dist();
+init_images();
+
+// src/storage/media.ts
+function createDiskSink() {
+  return {
+    kind: "disk",
+    persistsFiles: true,
+    async persist(items, opts) {
+      const { writeMedia: writeMedia2, resolveOutputDir: resolveOutputDir2 } = await Promise.resolve().then(() => (init_images(), images_exports));
+      const dir = resolveOutputDir2(opts.output_dir);
+      const refs = [];
+      for (const it of items) refs.push(await writeMedia2(dir, it.base, it.base64, it.mimeType));
+      return refs;
+    },
+    note: () => void 0
+  };
 }
-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 CHAIN_404_RETRIES = 2;
-var CHAIN_404_RETRY_MS = 2e3;
-var GeminiClient = class {
-  apiKey;
-  configError;
-  apis = /* @__PURE__ */ new Map();
-  fetchImpl;
-  sleep;
-  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.fetchImpl = opts.fetchImpl ?? fetch;
-    this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+
+// src/tools/shared.ts
+var DEFAULT_SINK = createDiskSink();
+var ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:4", "4:1", "1:8", "8:1"];
+var IMAGE_SIZES = ["512", "1K", "2K", "4K"];
+var MODEL_CHOICE_GUIDE = "gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse \u2014 balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks \u2014 highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).";
+var timeoutMsSchema = external_exports.number().int().positive().optional().describe(
+  "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 \u2014 or 120000 when image_size is 4K, which routinely runs past 60s)"
+);
+var idempotencyKeySchema = external_exports.string().min(1).optional().describe(
+  "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."
+);
+var asyncSchema = external_exports.boolean().optional().describe(
+  "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."
+);
+var sharedImageSchema = {
+  // Bare id only: the model is interpolated into the URL path
+  // (`/models/${model}:generateContent`), so slashes/colons/queries must be
+  // rejected to keep a crafted value from escaping the path segment.
+  model: external_exports.string().regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")').optional().describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
+  aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Output aspect ratio"),
+  image_size: external_exports.enum(IMAGE_SIZES).optional().describe("Output resolution (512 = 0.5K, Flash-only)"),
+  output_dir: external_exports.string().optional().describe("Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"),
+  inline: external_exports.boolean().optional().describe("Return base64 images inline instead of writing to disk"),
+  seed: external_exports.number().int().optional().describe("Seed for reproducible generation; random if omitted"),
+  thinking_level: external_exports.enum(["minimal", "high"]).optional().describe("Reasoning depth (Gemini 3 models); higher can help complex/structural edits"),
+  google_search: external_exports.boolean().optional().describe("Ground the image in live Google Search results (current events, weather, data)"),
+  from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
+  timeout_ms: timeoutMsSchema,
+  idempotency_key: idempotencyKeySchema,
+  async: asyncSchema
+};
+async function resolveVideoInput(args, client2) {
+  if (args.video_url && args.video_path) {
+    throw new McpToolError("Provide `video_url` OR `video_path`, not both.");
   }
-  /**
-   * The `createApiClient` pair for one timeout budget, built lazily and
-   * memoized per distinct timeout (a handful of values in practice). Both
-   * share: the key in the `x-goog-api-key` header (Gemini does not use
-   * `Authorization: Bearer`) and the default 429 retry (once after 2s — the
-   * free tier rate-limits aggressively). `getToken` calls requireKey() so key
-   * resolution stays at REQUEST time: the server boots without a key and the
-   * actionable config error (with its aistudio hint) surfaces on the first
-   * tool call, not at startup.
-   */
-  apisFor(timeoutMs) {
-    let entry = this.apis.get(timeoutMs);
-    if (!entry) {
-      const shared = {
-        tokenHeader: "x-goog-api-key",
-        getToken: () => this.requireKey(),
-        timeout: timeoutMs,
-        fetchImpl: this.fetchImpl
-      };
-      entry = {
-        api: createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared }),
-        // Separate client for the Interactions API so errors name the right API.
-        // The beta-era Api-Revision header is gone: the API went GA and requests
-        // succeed without it (verified live 2026-07-06; see docs/GEMINI-API.md).
-        // Don't re-add a pinned revision — it would freeze us on old semantics.
-        interactionsApi: createApiClient({ baseUrl: BASE_URL, serviceName: INTERACTIONS_SERVICE, ...shared })
-      };
-      this.apis.set(timeoutMs, entry);
+  if (!args.video_path) return { videoUrl: args.video_url };
+  const path = resolveVideoPath(args.video_path);
+  const uploaded = await client2.uploadVideo(path, videoMimeType(args.video_path));
+  const videoFileMeta = { uri: uploaded.uri, name: uploaded.name };
+  if (uploaded.expirationTime) videoFileMeta.expires = uploaded.expirationTime;
+  return { videoUrl: uploaded.uri, videoMimeType: uploaded.mimeType, videoFileMeta };
+}
+var videoPathSchema = external_exports.string().optional().describe(
+  "Path to a local video file \u2014 uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url."
+);
+function pickSeed(seed) {
+  return seed ?? Math.floor(Math.random() * 2147483e3);
+}
+var HEARTBEAT_DEFAULT_MS = 1e4;
+async function withProgressHeartbeat(extra, message, fn) {
+  const progressToken = extra?._meta?.progressToken;
+  const send = extra?.sendNotification;
+  const env = Number(readEnvVar("GEMINI_HEARTBEAT_MS"));
+  const intervalMs = Number.isFinite(env) ? env : HEARTBEAT_DEFAULT_MS;
+  const debug = !!readEnvVar("GEMINI_DEBUG");
+  const active = progressToken !== void 0 && !!send && intervalMs > 0;
+  if (debug) {
+    if (active) {
+      console.error(`[gemini-mcp] heartbeat active: progressToken present, interval=${intervalMs}ms \u2014 ${message}`);
+    } else {
+      const reason = progressToken === void 0 ? "no progressToken from host (host cannot extend its tools/call timeout; long calls will hit it)" : !send ? "host provided no sendNotification channel" : "heartbeat disabled (GEMINI_HEARTBEAT_MS=0)";
+      console.error(`[gemini-mcp] heartbeat inactive: ${reason} \u2014 ${message}`);
     }
-    return entry;
   }
-  requireKey() {
-    if (this.configError) throw this.configError;
-    return this.apiKey;
+  if (progressToken === void 0 || !send || intervalMs <= 0) return fn();
+  let ticks = 0;
+  const timer = setInterval(() => {
+    ticks++;
+    const elapsed = Math.round(ticks * intervalMs / 1e3);
+    if (debug) console.error(`[gemini-mcp] heartbeat: ${message} \u2014 still working (${elapsed}s)`);
+    void send({
+      method: "notifications/progress",
+      params: {
+        progressToken,
+        progress: ticks,
+        message: `${message} \u2014 still working (${elapsed}s)`
+      }
+    }).catch(() => {
+    });
+  }, intervalMs);
+  timer.unref?.();
+  try {
+    return await fn();
+  } finally {
+    clearInterval(timer);
   }
-  /** The default model after env override (no per-call arg). */
-  defaultModel() {
-    return resolveModel(void 0, readEnvVar("GEMINI_IMAGE_MODEL"));
+}
+function timeoutRiskHint(opts) {
+  const proModel = /(?:^|[-_./])pro(?:[-_./]|$)/i.test(opts.model);
+  const fourK = opts.imageSize === "4K";
+  const multi = (opts.count ?? 1) > 1;
+  if (!proModel && !fourK && !multi) return void 0;
+  const why = [proModel && "Pro model", fourK && "4K output", multi && `count=${opts.count}`].filter(Boolean).join(" + ");
+  const lead = `Slow config (${why}) can exceed a host's tools/call timeout (e.g. Claude Desktop ~30s, error -32001). `;
+  if (opts.persistsFiles === false) {
+    return lead + `This connector has no filesystem, so a lost response cannot be recovered from disk \u2014 there is no output dir and no <image>.json sidecar. Use \`async: true\` to get a job_id immediately and poll gemini_get_result, or use a Flash model / drop image_size to 1K/2K for a faster in-band result.`;
   }
-  async call(method, path, body, timeoutMs) {
-    const { api } = this.apisFor(timeoutMs ?? resolveTimeoutMs());
-    return api.fetchJson(method, path, body !== void 0 ? { body } : {});
+  return lead + `If the host gives up mid-generation the image is still written to disk (and gemini_interact leaves an <image>.json sidecar with the interaction id) \u2014 no rerun needed, just look in the output dir. For a faster in-band result use a Flash model, drop image_size to 1K/2K, or \u2014 in Claude Code \u2014 set MCP_TOOL_TIMEOUT.`;
+}
+function buildMeta(model, seed, opts) {
+  const meta3 = { model, seed };
+  if (opts.aspect_ratio) meta3.aspect_ratio = opts.aspect_ratio;
+  if (opts.image_size) meta3.image_size = opts.image_size;
+  return meta3;
+}
+async function emitMedia(named, kind, opts, meta3, onWritten) {
+  const inline = opts.inline && kind !== "video";
+  if (inline) {
+    const blocks = named.map((n) => ({ type: kind, data: n.media.base64, mimeType: n.media.mimeType }));
+    if (meta3 && Object.keys(meta3).length > 0) {
+      return { content: [{ type: "text", text: JSON.stringify(meta3, null, 2) }, ...blocks] };
+    }
+    return { content: blocks };
+  }
+  const sink = opts.sink ?? DEFAULT_SINK;
+  const refs = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
+    output_dir: opts.output_dir
+  });
+  if (sink.persistsFiles) await onWritten?.(refs);
+  const note = opts.inline && kind === "video" ? { inline_unsupported: "video has no MCP inline content type \u2014 written to disk instead" } : {};
+  const storageNote = sink.note();
+  const storage = sink.persistsFiles ? {} : { storage: sink.kind, storage_note: storageNote };
+  return textResult({ [`${kind}s`]: refs, ...note, ...storage, ...meta3 });
+}
+async function emit(named, opts, meta3, onWritten) {
+  return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), "image", opts, meta3, onWritten);
+}
+function assertLocalInputsAvailable(sink, args) {
+  if ((sink ?? DEFAULT_SINK).persistsFiles) return;
+  const unavailable = [];
+  if (args.images?.length) unavailable.push("`images` (local file paths)");
+  if (args.master_images?.length) unavailable.push("`master_images` (local file paths)");
+  if (args.from_clipboard) unavailable.push("`from_clipboard` (reads the macOS clipboard via child_process)");
+  if (args.video_path) unavailable.push("`video_path` (uploads a file streamed from disk)");
+  if (unavailable.length === 0) return;
+  const fix = "Send image bytes as `images_base64` (raw base64 or a data: URI) instead of `images`/`master_images`/`from_clipboard`, and reference video by `video_url` (a public YouTube URL, or a files/\u2026 uri uploaded elsewhere) instead of `video_path`.";
+  throw new McpToolError(
+    `${unavailable.join(", ")} ${unavailable.length > 1 ? "are" : "is"} unavailable on the hosted connector: it runs on a Cloudflare Worker, which has no filesystem and no local clipboard. ${fix}`,
+    { hint: fix }
+  );
+}
+
+// src/jobs.ts
+init_dist();
+import { randomUUID, createHash } from "node:crypto";
+var JOB_TTL_MS = 6e5;
+var JOB_MAX = 64;
+function isExpired(entry, now) {
+  return entry.settledAt !== void 0 && now - entry.settledAt > JOB_TTL_MS;
+}
+function fingerprintRequest(toolName, parts) {
+  return createHash("sha256").update(`${toolName}\0${JSON.stringify(parts)}`).digest("hex");
+}
+function annotateReused(result, jobId) {
+  const content = result.content ?? [];
+  const first = content[0];
+  if (first && first.type === "text") {
+    let obj;
+    try {
+      obj = JSON.parse(first.text);
+    } catch {
+      obj = {};
+    }
+    obj.reused = true;
+    obj.reused_job_id = jobId;
+    return { ...result, content: [{ ...first, text: JSON.stringify(obj, null, 2) }, ...content.slice(1)] };
+  }
+  return {
+    ...result,
+    content: [{ type: "text", text: JSON.stringify({ reused: true, reused_job_id: jobId }, null, 2) }, ...content]
+  };
+}
+function jobHandle(jobId, status) {
+  return textResult({
+    job_id: jobId,
+    status,
+    hint: `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done" (results are per-process and expire ~10 min after completion).`
+  });
+}
+var JobRegistry = class {
+  jobs = /* @__PURE__ */ new Map();
+  byKey = /* @__PURE__ */ new Map();
+  // idempotencyKey -> jobId
+  runningByFingerprint = /* @__PURE__ */ new Map();
+  // fingerprint -> jobId (only while running)
+  /** Drop every job. Used by `SessionState.reset()` (tests) — not by handlers. */
+  reset() {
+    this.jobs.clear();
+    this.byKey.clear();
+    this.runningByFingerprint.clear();
+  }
+  /** Drop expired entries, then enforce JOB_MAX by evicting oldest-settled first. */
+  evict(now) {
+    for (const [id, entry] of this.jobs) {
+      if (isExpired(entry, now)) this.remove(id, entry);
+    }
+    if (this.jobs.size < JOB_MAX) return;
+    const settled = [...this.jobs.values()].filter((e) => e.settledAt !== void 0).sort((a, b) => (a.settledAt ?? 0) - (b.settledAt ?? 0));
+    for (const e of settled) {
+      if (this.jobs.size < JOB_MAX) break;
+      this.remove(e.jobId, e);
+    }
+  }
+  remove(id, entry) {
+    this.jobs.delete(id);
+    if (entry.idempotencyKey !== void 0 && this.byKey.get(entry.idempotencyKey) === id) this.byKey.delete(entry.idempotencyKey);
+    if (this.runningByFingerprint.get(entry.fingerprint) === id) this.runningByFingerprint.delete(entry.fingerprint);
   }
   /**
-   * Upload a local video to the Gemini Files API (resumable protocol) and wait
-   * for it to become usable. Three live-verified steps (docs/GEMINI-API.md
-   * "Files API — local video upload"):
-   *
-   *  1. `POST {UPLOAD_BASE_URL}/files` (command `start`) → the upload session
-   *     URL arrives in the `x-goog-upload-url` RESPONSE HEADER (body is empty).
-   *  2. `POST <session url>` (command `upload, finalize`) with the bytes —
-   *     a file-backed Blob (`fileBlob`/`fs.openAsBlob`), so fetch STREAMS the
-   *     video from disk; it is never buffered in memory. Response: `{file:…}`.
-   *  3. Poll `GET /v1beta/files/<id>` while `state` is `PROCESSING`, until
-   *     `ACTIVE` (the poll response is the File object UNWRAPPED).
-   *
-   * These two upload calls are raw `fetchImpl` (not `createApiClient`): step 1
-   * needs the response *header* and step 2 posts a binary body — neither fits
-   * `fetchJson`. The poll DOES go through the shared client (timeout + retry).
-   * Uploads deliberately have no abort timeout: a multi-hundred-MB video can
-   * legitimately take longer than any fixed budget.
+   * Run `work` under the registry, deduplicating where safe:
+   * - with an `idempotencyKey`: attach to a matching `running` OR recently-`done`
+   *   job (not `failed`, not expired);
+   * - without a key: attach only to a matching **in-flight** job by fingerprint
+   *   (two truly-simultaneous identical requests are a timeout-retry race, never
+   *   an intentional variation).
+   * On a dedup hit the shared result is returned with `reused: true`. When
+   * `async` is set, a `{ job_id, status }` handle is returned immediately (no
+   * await) and the caller retrieves the result via `getResult`. Otherwise a
+   * new job runs synchronously and failures propagate to the caller as before.
    *
-   * Returned files live ~48h (`expirationTime`); per-file cap is 2 GB
-   * (enforced locally before any bytes are sent).
+   * Both dedup paths are scoped to THIS registry, i.e. to one session — a
+   * colliding `idempotency_key` or an identical prompt from another user is a
+   * different registry and therefore a genuinely separate generation.
    */
-  async uploadVideo(path, mimeType) {
-    const key = this.requireKey();
-    const blob = await fileBlob(path, { type: mimeType, maxBytes: FILE_MAX_BYTES, label: "Video" });
-    const startPath = "/files";
-    const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
-      method: "POST",
-      headers: {
-        "x-goog-api-key": key,
-        "X-Goog-Upload-Protocol": "resumable",
-        "X-Goog-Upload-Command": "start",
-        "X-Goog-Upload-Header-Content-Length": String(blob.size),
-        "X-Goog-Upload-Header-Content-Type": mimeType,
-        "Content-Type": "application/json"
+  async dispatch(opts, work) {
+    const { toolName, fingerprint, idempotencyKey, async } = opts;
+    const now = Date.now();
+    let hit;
+    if (idempotencyKey !== void 0) {
+      const id = this.byKey.get(idempotencyKey);
+      const entry2 = id ? this.jobs.get(id) : void 0;
+      if (entry2 && entry2.status !== "failed" && !isExpired(entry2, now)) hit = entry2;
+    } else {
+      const id = this.runningByFingerprint.get(fingerprint);
+      const entry2 = id ? this.jobs.get(id) : void 0;
+      if (entry2 && entry2.status === "running") hit = entry2;
+    }
+    if (hit) {
+      if (async) return jobHandle(hit.jobId, hit.status);
+      return annotateReused(await hit.promise, hit.jobId);
+    }
+    const jobId = randomUUID();
+    this.evict(now);
+    const promise2 = work();
+    const entry = { jobId, toolName, fingerprint, idempotencyKey, status: "running", promise: promise2, createdAt: now };
+    this.jobs.set(jobId, entry);
+    if (idempotencyKey !== void 0) this.byKey.set(idempotencyKey, jobId);
+    this.runningByFingerprint.set(fingerprint, jobId);
+    promise2.then(
+      (res) => {
+        entry.status = "done";
+        entry.result = res;
+        entry.settledAt = Date.now();
       },
-      body: JSON.stringify({ file: { display_name: basename(path) } })
+      (err) => {
+        entry.status = "failed";
+        entry.error = { message: err instanceof Error ? err.message : String(err), hint: err?.hint };
+        entry.settledAt = Date.now();
+      }
+    ).finally(() => {
+      if (this.runningByFingerprint.get(fingerprint) === jobId) this.runningByFingerprint.delete(fingerprint);
     });
-    if (!startRes.ok) {
-      throw new McpToolError(
-        formatApiError(startRes.status, "POST", `/upload/v1beta${startPath}`, await startRes.text(), { service: SERVICE })
-      );
-    }
-    const uploadUrl = startRes.headers.get("x-goog-upload-url");
-    if (!uploadUrl) {
-      throw new McpToolError(`${SERVICE} upload start did not return an x-goog-upload-url header`, {
-        hint: "The Files API resumable-upload contract may have changed \u2014 see docs/GEMINI-API.md."
+    if (async) return jobHandle(jobId, "running");
+    return promise2;
+  }
+  /**
+   * Retrieve an async job by id (backs the `gemini_get_result` tool):
+   * `running` → a status handle; `done` → the recorded result payload;
+   * `failed` → the recorded error; unknown/expired → an actionable error.
+   *
+   * A job id from ANOTHER session is simply not in this registry, so it takes
+   * the unknown-id path — the poll tool cannot be used to read another user's
+   * result even if they know the uuid.
+   */
+  getResult(jobId) {
+    const entry = this.jobs.get(jobId);
+    if (!entry) {
+      throw new McpToolError(`No job "${jobId}" \u2014 unknown or expired.`, {
+        hint: "Jobs live with your session and are evicted ~10 min after completion (or on server restart). If the generation likely finished, check the output dir / <image>.json sidecar instead of polling."
       });
     }
-    const upRes = await this.fetchImpl(uploadUrl, {
-      method: "POST",
-      headers: {
-        "X-Goog-Upload-Offset": "0",
-        "X-Goog-Upload-Command": "upload, finalize"
-      },
-      body: blob
-    });
-    if (!upRes.ok) {
-      throw new McpToolError(
-        formatApiError(upRes.status, "POST", "/upload/v1beta/files (finalize)", await upRes.text(), { service: SERVICE })
-      );
-    }
-    let file2 = (await upRes.json()).file ?? {};
-    const name = file2.name ?? "";
-    if (!/^files\/[\w-]+$/.test(name)) {
-      throw new McpToolError(`${SERVICE} upload returned an unexpected file name: ${name || "(none)"}`);
-    }
-    for (let attempt = 0; file2.state === "PROCESSING"; attempt++) {
-      if (attempt >= FILE_POLL_MAX_ATTEMPTS) {
-        throw new McpToolError(`${SERVICE} video file ${name} is still processing after ${FILE_POLL_INTERVAL_MS * FILE_POLL_MAX_ATTEMPTS / 6e4} minutes`, {
-          hint: "Very long videos can take a while to process \u2014 retry later by passing the file uri as video_url."
-        });
-      }
-      await this.sleep(FILE_POLL_INTERVAL_MS);
-      file2 = await this.call("GET", `/${name}`);
-    }
-    if (file2.state !== "ACTIVE") {
-      throw new McpToolError(
-        `${SERVICE} video file processing failed (state ${file2.state ?? "unknown"})${file2.error?.message ? `: ${file2.error.message}` : ""}`,
-        { hint: "Check the video is a supported format/codec and under 2 GB." }
-      );
-    }
-    if (!file2.uri) {
-      throw new McpToolError(`${SERVICE} did not return a uri for uploaded file ${name}`);
+    if (entry.status === "running") return jobHandle(jobId, "running");
+    if (entry.status === "failed") {
+      throw new McpToolError(entry.error?.message ?? "Job failed.", entry.error?.hint ? { hint: entry.error.hint } : void 0);
     }
-    return { name, uri: file2.uri, mimeType: file2.mimeType ?? mimeType, expirationTime: file2.expirationTime };
-  }
-  async listModels() {
-    const data = await this.call("GET", "/models?pageSize=200");
-    return filterImageModels(data.models ?? []);
+    if (!entry.result) throw new McpToolError(`Job "${jobId}" completed without a recorded result.`);
+    return entry.result;
   }
-  async generate(opts) {
-    const model = resolveModel(opts.model, readEnvVar("GEMINI_IMAGE_MODEL"));
-    const parts = [{ text: opts.prompt }];
-    for (const img of opts.images ?? []) {
-      parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
-    }
-    if (opts.videoUrl) {
-      parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" } });
-    }
-    const generationConfig = { responseModalities: ["TEXT", "IMAGE"] };
-    if (opts.aspectRatio || opts.imageSize) {
-      const imageConfig = {};
-      if (opts.aspectRatio) imageConfig.aspectRatio = opts.aspectRatio;
-      if (opts.imageSize) imageConfig.imageSize = opts.imageSize;
-      generationConfig.imageConfig = imageConfig;
-    }
-    if (opts.seed !== void 0) generationConfig.seed = opts.seed;
-    if (opts.thinkingLevel !== void 0) generationConfig.thinkingConfig = { thinkingLevel: opts.thinkingLevel };
-    const requestBody = { contents: [{ parts }], generationConfig };
-    if (opts.googleSearch) requestBody.tools = [{ google_search: {} }];
-    const data = await this.call(
-      "POST",
-      `/models/${model}:generateContent`,
-      requestBody,
-      resolveTimeoutMs(opts.timeoutMs, opts.imageSize)
-    );
-    const images = [];
-    const textParts = [];
-    let groundingMeta;
-    for (const cand of data.candidates ?? []) {
-      for (const part of cand.content?.parts ?? []) {
-        const inline = part.inline_data ?? part.inlineData;
-        if (inline?.data) {
-          images.push({ base64: inline.data, mimeType: inline.mime_type ?? inline.mimeType ?? "image/jpeg" });
-        } else if (typeof part.text === "string" && part.text.trim()) {
-          textParts.push(part.text);
-        }
-      }
-      if (cand.groundingMetadata) groundingMeta = cand.groundingMetadata;
-    }
-    if (images.length === 0) {
-      throw new McpToolError(`${SERVICE} returned no image`, {
-        hint: "The request may have been blocked by safety filters \u2014 try rephrasing the prompt."
-      });
-    }
-    const text = textParts.join("\n") || void 0;
-    let grounding;
-    if (groundingMeta) {
-      const queries = (groundingMeta.webSearchQueries ?? []).filter(Boolean);
-      const sources = (groundingMeta.groundingChunks ?? []).map((c) => c.web).filter((w) => !!w);
-      if (queries.length > 0 || sources.length > 0) {
-        grounding = {};
-        if (queries.length > 0) grounding.queries = queries;
-        if (sources.length > 0) grounding.sources = sources;
+};
+
+// src/tools/_confirm.ts
+init_dist();
+init_images();
+function previewUnlessConfirmed(confirm, action, method, path, body) {
+  if (confirm === true) return null;
+  return textResult({
+    dryRun: true,
+    action,
+    method,
+    path,
+    ...body !== void 0 ? { willSend: body } : {},
+    note: "Re-run with confirm: true to execute."
+  });
+}
+async function previewLocalInputsUnlessConfirmed(confirm, action, endpoint, imagePaths, videoPath) {
+  const hasLocal = (imagePaths?.length ?? 0) > 0 || Boolean(videoPath);
+  if (confirm === true || !hasLocal) return null;
+  const inputs = [];
+  for (const p of imagePaths ?? []) inputs.push(await previewImageInput(p));
+  if (videoPath) inputs.push(await previewVideoInput(videoPath));
+  return previewUnlessConfirmed(confirm, action, "POST", endpoint, { inputs });
+}
+
+// src/tools/generate.ts
+var GENERATE_ENDPOINT = "/v1beta/models/{model}:generateContent";
+var SEND_LOCAL_ACTION = "Send local file input(s) to the Gemini API";
+var 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).";
+function registerGenerateTools(server, client2) {
+  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.",
+      annotations: { readOnlyHint: false, openWorldHint: true },
+      inputSchema: {
+        prompt: external_exports.string().min(1).describe("Text prompt describing the image"),
+        count: external_exports.number().int().positive().max(8).optional().describe("Number of independent images (default 1)"),
+        filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
+        images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to reference input images (image-conditioned generation)"),
+        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs"),
+        video_url: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
+        video_path: videoPathSchema,
+        confirm: schemaConfirm,
+        ...sharedImageSchema
       }
-    }
-    return { images, text, grounding };
-  }
-  async interact(opts) {
-    const model = resolveModel(opts.model, readEnvVar("GEMINI_IMAGE_MODEL"));
-    const inputParts = [{ type: "text", text: opts.input }];
-    for (const img of opts.images ?? []) {
-      inputParts.push({ type: "image", mime_type: img.mimeType, data: img.base64 });
-    }
-    if (opts.videoUrl) {
-      inputParts.push({ type: "video", uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" });
-    }
-    const responseFormat = { type: "image", mime_type: "image/jpeg" };
-    if (opts.aspectRatio) responseFormat.aspect_ratio = opts.aspectRatio;
-    if (opts.imageSize) responseFormat.image_size = opts.imageSize;
-    const body = { model, input: inputParts, response_format: responseFormat };
-    if (opts.thinkingLevel !== void 0) body.generation_config = { thinking_level: opts.thinkingLevel };
-    if (opts.previousInteractionId !== void 0) body.previous_interaction_id = opts.previousInteractionId;
-    if (opts.googleSearch || opts.searchTypes?.length) {
-      const searchTool = { type: "google_search" };
-      if (opts.searchTypes?.length) searchTool.search_types = opts.searchTypes;
-      body.tools = [searchTool];
-    }
-    const data = await this.postInteraction(body, opts);
-    const { images, text, grounding } = this.extractInteraction(data, opts.searchTypes);
-    if (images.length === 0) {
-      throw new McpToolError("Gemini returned no image", {
-        hint: "The request may have been blocked by safety filters \u2014 try rephrasing the prompt."
-      });
-    }
-    return { id: data.id, 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.
-   */
-  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({ type: "image", mime_type: img.mimeType, data: img.base64 });
-    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 { 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."
-      });
-    }
-    return { id: data.id, videos, text };
-  }
-  /**
-   * Generate music via a Lyria model (Interactions API, inline audio). Reuses
-   * the interact plumbing with an `audio` response_format. Preview model.
-   */
-  async generateMusic(opts) {
-    const model = opts.model ?? DEFAULT_MUSIC_MODEL;
-    const inputParts = [{ type: "text", text: opts.input }];
-    for (const img of opts.images ?? []) inputParts.push({ type: "image", mime_type: img.mimeType, data: img.base64 });
-    const responseFormat = { type: "audio" };
-    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;
-    const data = await this.postInteraction(body, opts);
-    const { audios, text } = this.extractInteraction(data);
-    if (audios.length === 0) {
-      throw new McpToolError("Gemini returned no audio", {
-        hint: "The request may have been blocked by a safety filter \u2014 try rephrasing the prompt."
+    },
+    async (args, extra) => {
+      assertLocalInputsAvailable(client2.mediaSink, args);
+      const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images, args.video_path);
+      if (gate) return gate;
+      const count = args.count ?? 1;
+      const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+      const fingerprint = fingerprintRequest("gemini_image_generate", {
+        model,
+        prompt: args.prompt,
+        aspect_ratio: args.aspect_ratio,
+        image_size: args.image_size,
+        thinking_level: args.thinking_level,
+        google_search: args.google_search,
+        count,
+        images: args.images,
+        images_base64: args.images_base64,
+        from_clipboard: args.from_clipboard,
+        video_url: args.video_url,
+        video_path: args.video_path
       });
-    }
-    return { id: data.id, audios, text };
-  }
-  /** POST `/interactions` with the chained-404 retry. Shared by all media. */
-  async postInteraction(body, opts) {
-    const { interactionsApi } = this.apisFor(resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
-    for (let attempt = 0; ; attempt++) {
-      try {
-        return await interactionsApi.fetchJson("POST", "/interactions", { body });
-      } catch (err) {
-        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));
-          continue;
-        }
-        throw new McpToolError(
-          `Previous interaction "${opts.previousInteractionId}" was not found (retried ${CHAIN_404_RETRIES}\xD7 \u2014 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.",
-            cause: err
-          }
-        );
-      }
-    }
-  }
-  /**
-   * Collect `model_output` media (image/video/audio) + text + grounding from an
-   * interactions response. Only the `model_output` step is surfaced — `thought`
-   * steps (internal reasoning / draft images) are dropped on purpose so they
-   * can't leak into text or pollute the outputs. Tolerant of snake/camel MIME.
-   */
-  extractInteraction(data, searchTypes) {
-    const images = [];
-    const videos = [];
-    const audios = [];
-    const textParts = [];
-    const searchQueries = [];
-    const searchSuggestions = /* @__PURE__ */ new Set();
-    for (const step of data.steps ?? []) {
-      if (step.type === "google_search_call") {
-        for (const q of step.arguments?.queries ?? []) if (q?.trim()) searchQueries.push(q);
-        continue;
-      }
-      if (step.type === "google_search_result") {
-        if (searchTypes?.includes("image_search")) {
-          for (const r of step.result ?? []) if (r.search_suggestions?.trim()) searchSuggestions.add(r.search_suggestions);
-        }
-        continue;
-      }
-      if (step.type !== "model_output") continue;
-      for (const parts of [step.content ?? [], step.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);
+      return client2.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) : slugify2(args.prompt);
+        const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args, client2));
+        const named = [];
+        let capturedText;
+        let capturedGrounding;
+        await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : "image"} (${model})`, async () => {
+          for (let i = 0; i < count; i++) {
+            const result = await client2.generate({
+              prompt: args.prompt,
+              images: refInputs.length > 0 ? refInputs : void 0,
+              model: args.model,
+              aspectRatio: args.aspect_ratio,
+              imageSize: args.image_size,
+              seed: seed + i,
+              thinkingLevel: args.thinking_level,
+              googleSearch: args.google_search,
+              videoUrl: video.videoUrl,
+              videoMimeType: video.videoMimeType,
+              timeoutMs: args.timeout_ms
+            });
+            const { images: [img], text } = result;
+            if (text && !capturedText) capturedText = text;
+            if (result.grounding && !capturedGrounding) capturedGrounding = result.grounding;
+            named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, "0")}` });
           }
-        }
-      }
-    }
-    let grounding;
-    if (searchQueries.length > 0 || searchSuggestions.size > 0) {
-      grounding = {};
-      if (searchQueries.length > 0) grounding.queries = searchQueries;
-      if (searchSuggestions.size > 0) grounding.search_suggestions = [...searchSuggestions];
+        });
+        const meta3 = buildMeta(model, seed, args);
+        if (capturedText) meta3.text = capturedText;
+        if (capturedGrounding) meta3.grounding = capturedGrounding;
+        if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
+        meta3.hint = REFINE_HINT;
+        const risk = timeoutRiskHint({ model, imageSize: args.image_size, count, persistsFiles: client2.mediaSink?.persistsFiles });
+        if (risk) meta3.timeout_risk = risk;
+        return emit(named, { ...args, sink: client2.mediaSink }, meta3);
+      });
     }
-    return { images, videos, audios, text: textParts.join("\n") || void 0, grounding };
-  }
-};
-var client = new GeminiClient();
-
-// src/tools/models.ts
-function registerModelTools(server) {
+  );
   server.registerTool(
-    "gemini_list_models",
+    "gemini_image_edit",
     {
-      description: "List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.",
-      annotations: { readOnlyHint: true }
+      description: "Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. For a SERIES of successive edits to the same image, prefer gemini_interact (multi-turn) \u2014 it keeps edit context and avoids re-processing the full image each round; use gemini_image_edit for one-off edits or composing multiple distinct inputs. Gemini over-preserves the input; there is no edit-strength control \u2014 for large structural changes, reroll with a different `seed` or more forceful wording.",
+      annotations: { readOnlyHint: false, openWorldHint: true },
+      inputSchema: {
+        prompt: external_exports.string().min(1).describe("Instruction describing the edit or composition"),
+        images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to input image file(s) (1 = edit, 2+ = compose)"),
+        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Input images as base64 strings or data URIs"),
+        filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
+        confirm: schemaConfirm,
+        ...sharedImageSchema
+      }
     },
-    async () => {
-      const models = await client.listModels();
-      return textResult({ default: client.defaultModel(), models });
+    async (args, extra) => {
+      assertLocalInputsAvailable(client2.mediaSink, args);
+      const hasPaths = (args.images?.length ?? 0) > 0;
+      const hasBase64 = (args.images_base64?.length ?? 0) > 0;
+      if (!hasPaths && !hasBase64 && !args.from_clipboard) {
+        throw new McpToolError("Provide at least one input image via `images`, `images_base64`, or `from_clipboard`.");
+      }
+      const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images);
+      if (gate) return gate;
+      const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+      const fingerprint = fingerprintRequest("gemini_image_edit", {
+        model,
+        prompt: args.prompt,
+        aspect_ratio: args.aspect_ratio,
+        image_size: args.image_size,
+        thinking_level: args.thinking_level,
+        google_search: args.google_search,
+        images: args.images,
+        images_base64: args.images_base64,
+        from_clipboard: args.from_clipboard
+      });
+      return client2.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) : slugify2(args.prompt);
+        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client2.generate({
+          prompt: args.prompt,
+          images: inputs,
+          model: args.model,
+          aspectRatio: args.aspect_ratio,
+          imageSize: args.image_size,
+          seed,
+          thinkingLevel: args.thinking_level,
+          googleSearch: args.google_search,
+          timeoutMs: args.timeout_ms
+        }));
+        const { images: [img], text } = result;
+        const meta3 = buildMeta(model, seed, args);
+        if (text) meta3.text = text;
+        if (result.grounding) meta3.grounding = result.grounding;
+        meta3.hint = REFINE_HINT;
+        const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: client2.mediaSink?.persistsFiles });
+        if (risk) meta3.timeout_risk = risk;
+        return emit([{ image: img, base: slug }], { ...args, sink: client2.mediaSink }, meta3);
+      });
     }
   );
 }
 
-// src/tools/generate.ts
+// src/tools/set.ts
 init_zod();
 init_dist();
-
-// src/images.ts
-init_dist();
-import { mkdir, readFile as readFile2, writeFile, access, stat, open } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { join as join3, resolve, isAbsolute } from "node:path";
-function slugify2(text, max = 40) {
-  const s = text.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "").slice(0, max).replace(/-+$/g, "");
-  return s || "image";
-}
-async function exists(p) {
-  try {
-    await access(p);
-    return true;
-  } catch {
-    return false;
-  }
-}
-async function uniquePath(dir, base, ext) {
-  let candidate = join3(dir, `${base}.${ext}`);
-  let n = 2;
-  while (await exists(candidate)) {
-    candidate = join3(dir, `${base}-${n}.${ext}`);
-    n++;
-  }
-  return candidate;
-}
-function sniffMimeBytes(buf) {
-  if (buf.length >= 4 && buf[0] === 137 && buf[1] === 80 && buf[2] === 78 && buf[3] === 71) {
-    return "image/png";
-  }
-  if (buf.length >= 3 && buf[0] === 255 && buf[1] === 216 && buf[2] === 255) {
-    return "image/jpeg";
-  }
-  if (buf.length >= 12 && buf[0] === 82 && buf[1] === 73 && buf[2] === 70 && buf[3] === 70 && buf[8] === 87 && buf[9] === 69 && buf[10] === 66 && buf[11] === 80) {
-    return "image/webp";
-  }
-  return "image/png";
-}
-function mediaExt(mimeType) {
-  const m = mimeType.toLowerCase();
-  if (m.includes("jpeg")) return "jpg";
-  if (m.includes("webp")) return "webp";
-  if (m.includes("png")) return "png";
-  if (m.includes("mp4")) return "mp4";
-  if (m.includes("quicktime")) return "mov";
-  if (m.includes("webm")) return "webm";
-  if (m.includes("wav")) return "wav";
-  if (m.includes("mpeg") || m.includes("mp3")) return "mp3";
-  if (m.includes("ogg")) return "ogg";
-  return m.split("/")[1]?.split(";")[0]?.replace(/^x-/, "") || "bin";
-}
-async function writeMedia(dir, base, base643, mimeType) {
-  await mkdir(dir, { recursive: true });
-  const path = await uniquePath(dir, base, mediaExt(mimeType));
-  await writeFile(path, Buffer.from(base643, "base64"));
-  return resolve(path);
-}
-async function writeSidecar(imagePath, data) {
-  await writeFile(`${imagePath}.json`, JSON.stringify(data, null, 2));
-}
-function resolveInputPath(p, kind) {
-  if (isAbsolute(p) && existsSync(p)) return p;
-  const inputDir = readEnvVar("GEMINI_INPUT_DIR");
-  if (inputDir) {
-    const candidate = join3(inputDir, p);
-    if (existsSync(candidate)) return resolve(candidate);
-  }
-  const cwd = resolve(p);
-  if (existsSync(cwd)) return cwd;
-  const hint = `Set GEMINI_INPUT_DIR to a directory containing your ${kind.toLowerCase()}s, or pass an absolute path.`;
-  throw new McpToolError(
-    `${kind} not found: ${p}` + (inputDir ? ` (also searched GEMINI_INPUT_DIR=${inputDir})` : ""),
-    { hint }
-  );
-}
-function resolveImagePath(p) {
-  return resolveInputPath(p, "Image");
-}
-function resolveVideoPath(p) {
-  return resolveInputPath(p, "Video");
-}
-var VIDEO_MIME_BY_EXT = {
-  mp4: "video/mp4",
-  mpeg: "video/mpeg",
-  mpg: "video/mpg",
-  mov: "video/mov",
-  avi: "video/avi",
-  flv: "video/x-flv",
-  webm: "video/webm",
-  wmv: "video/wmv",
-  "3gp": "video/3gpp",
-  "3gpp": "video/3gpp"
-};
-function videoMimeType(p) {
-  const ext = p.includes(".") ? p.slice(p.lastIndexOf(".") + 1).toLowerCase() : "";
-  const mime = VIDEO_MIME_BY_EXT[ext];
-  if (!mime) {
-    throw new McpToolError(`Unsupported video format: ${ext ? `.${ext}` : p}`, {
-      hint: `Supported extensions: ${Object.keys(VIDEO_MIME_BY_EXT).map((e) => `.${e}`).join(", ")}`
-    });
-  }
-  return mime;
-}
-async function previewImageInput(path) {
-  const resolved = resolveImagePath(path);
-  const { size } = await stat(resolved);
-  const fh = await open(resolved, "r");
-  try {
-    const head = Buffer.alloc(16);
-    const { bytesRead } = await fh.read(head, 0, 16, 0);
-    return { path: resolved, mimeType: sniffMimeBytes(head.subarray(0, bytesRead)), size };
-  } finally {
-    await fh.close();
-  }
-}
-async function previewVideoInput(path) {
-  const resolved = resolveVideoPath(path);
-  const { size } = await stat(resolved);
-  return { path: resolved, mimeType: videoMimeType(resolved), size };
-}
-async function readImageAsInline(path) {
-  const resolved = resolveImagePath(path);
-  const buf = await readFile2(resolved);
-  const mimeType = sniffMimeBytes(buf);
-  return { base64: buf.toString("base64"), mimeType };
-}
-function decodeImageInput(input) {
-  const trimmed = input.trim();
-  if (trimmed.startsWith("data:")) {
-    const marker = trimmed.indexOf(";base64,");
-    if (marker === -1) {
-      throw new Error(`Unsupported data URI (expected ;base64,<data>): ${trimmed.slice(0, 48)}\u2026`);
-    }
-    const mimeType = trimmed.slice(5, trimmed.indexOf(";", 5)) || "image/png";
-    return { mimeType, base64: trimmed.slice(marker + ";base64,".length) };
-  }
-  const buf = Buffer.from(trimmed, "base64");
-  return { base64: trimmed, mimeType: sniffMimeBytes(buf) };
-}
-async function loadImageInputs(paths = [], base64s = []) {
-  const fromPaths = await Promise.all(paths.map((p) => readImageAsInline(p)));
-  const fromBase64s = base64s.map((b) => decodeImageInput(b));
-  return [...fromPaths, ...fromBase64s];
-}
-async function gatherImageInputs(opts) {
-  const clipboardImages = opts.from_clipboard ? [await (await Promise.resolve().then(() => (init_clipboard(), clipboard_exports))).readClipboardImage()] : [];
-  const fileImages = await loadImageInputs(opts.images, opts.images_base64);
-  return [...clipboardImages, ...fileImages];
-}
-function baseName(name) {
-  const stripped = name.replace(/\.(png|jpe?g|webp|mp4|mov|webm|mp3|wav|ogg)$/i, "");
-  const safe = stripped.replace(/[^A-Za-z0-9._-]+/g, "-").replace(/-+/g, "-").replace(/^-+|-+$/g, "");
-  return safe || "image";
-}
-function resolveOutputDir(perCall) {
-  return perCall?.trim() || readEnvVar("GEMINI_OUTPUT_DIR") || process.cwd();
+init_images();
+function registerSetTools(server, client2) {
+  server.registerTool(
+    "gemini_image_set",
+    {
+      description: "Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master).",
+      annotations: { readOnlyHint: false, openWorldHint: true },
+      inputSchema: {
+        master_prompt: external_exports.string().min(1).describe("Prompt for the master/reference image"),
+        scenes: external_exports.array(external_exports.string().min(1)).min(1).max(8).optional().describe("Per-image prompts (1-8); each references the master"),
+        count: external_exports.number().int().positive().max(8).optional().describe("Number of variations of master_prompt (when scenes omitted)"),
+        reference_mode: external_exports.enum(["master", "chain"]).optional().describe("master: every image references the master (default). chain: each references the previous."),
+        basename: external_exports.string().optional().describe("Base filename prefix for output images (default: slugified master_prompt)"),
+        master_images: external_exports.array(external_exports.string().min(1)).optional().describe("Reference image paths passed to the master generation call"),
+        master_images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs for master generation"),
+        confirm: schemaConfirm,
+        ...sharedImageSchema
+      }
+    },
+    async (args, extra) => {
+      assertLocalInputsAvailable(client2.mediaSink, args);
+      if (args.scenes && args.count || !args.scenes && !args.count) {
+        throw new McpToolError("Provide exactly one of `scenes` or `count`.");
+      }
+      const gate = await previewLocalInputsUnlessConfirmed(args.confirm, "Send local master image input(s) to the Gemini API", "/v1beta/models/{model}:generateContent", args.master_images);
+      if (gate) return gate;
+      const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+      const fingerprint = fingerprintRequest("gemini_image_set", {
+        model,
+        master_prompt: args.master_prompt,
+        scenes: args.scenes,
+        count: args.count,
+        reference_mode: args.reference_mode,
+        aspect_ratio: args.aspect_ratio,
+        image_size: args.image_size,
+        thinking_level: args.thinking_level,
+        google_search: args.google_search,
+        master_images: args.master_images,
+        master_images_base64: args.master_images_base64,
+        from_clipboard: args.from_clipboard
+      });
+      return client2.session.jobs.dispatch({ toolName: "gemini_image_set", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        const seed = pickSeed(args.seed);
+        const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
+        const slug = args.basename ? baseName(args.basename) : slugify2(args.master_prompt);
+        const masterRefInputs = await gatherImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard });
+        const named = [];
+        const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
+          const result = await client2.generate({
+            prompt: args.master_prompt,
+            images: masterRefInputs.length > 0 ? masterRefInputs : void 0,
+            seed,
+            ...cfg
+          });
+          const master = result.images[0];
+          named.push({ image: master, base: `${slug}-master` });
+          const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
+          const mode = args.reference_mode ?? "master";
+          if (mode === "chain") {
+            let ref = master;
+            for (let i = 0; i < scenePrompts.length; i++) {
+              const { images: [img] } = await client2.generate({ prompt: scenePrompts[i], images: [ref], seed: seed + i + 1, ...cfg });
+              named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, "0")}` });
+              ref = img;
+            }
+          } else {
+            const scenes = await Promise.all(
+              scenePrompts.map((p, i) => client2.generate({ prompt: p, images: [master], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
+            );
+            scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, "0")}` }));
+          }
+          return result;
+        });
+        const masterText = masterResult.text;
+        const meta3 = buildMeta(model, seed, args);
+        if (masterText) meta3.text = masterText;
+        if (masterResult.grounding) meta3.grounding = masterResult.grounding;
+        const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client2.mediaSink?.persistsFiles });
+        if (risk) meta3.timeout_risk = risk;
+        return emit(named, { ...args, sink: client2.mediaSink }, meta3);
+      });
+    }
+  );
 }
 
-// src/tools/shared.ts
+// src/tools/interact.ts
 init_zod();
 init_dist();
-var ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:4", "4:1", "1:8", "8:1"];
-var IMAGE_SIZES = ["512", "1K", "2K", "4K"];
-var MODEL_CHOICE_GUIDE = "gemini-3.1-flash-image (Nano Banana 2) is the versatile generalist workhorse \u2014 balances speed with state-of-the-art 4K generation, world knowledge, and reliable text rendering; excels at multi-reference-image processing and consistency. gemini-3-pro-image (Nano Banana Pro) is the premium choice for the most complex visual tasks \u2014 highest world knowledge, advanced localization, accurate brand consistency, precision creative control. gemini-3.1-flash-lite-image (Nano Banana 2 Lite) is the fastest/cheapest for simple tasks (1K only, no search grounding).";
-var timeoutMsSchema = external_exports.number().int().positive().optional().describe(
-  "Upstream request timeout in ms for this call (default: $GEMINI_TIMEOUT_MS, else 60000 \u2014 or 120000 when image_size is 4K, which routinely runs past 60s)"
-);
-var idempotencyKeySchema = external_exports.string().min(1).optional().describe(
-  "Opaque idempotency key: a repeat call with the same key returns the recorded result (reused: true) instead of billing a new generation. Set it when retrying after a host timeout (-32001) to avoid a duplicate charge."
-);
-var asyncSchema = external_exports.boolean().optional().describe(
-  "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."
-);
-var sharedImageSchema = {
-  // Bare id only: the model is interpolated into the URL path
-  // (`/models/${model}:generateContent`), so slashes/colons/queries must be
-  // rejected to keep a crafted value from escaping the path segment.
-  model: external_exports.string().regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")').optional().describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
-  aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Output aspect ratio"),
-  image_size: external_exports.enum(IMAGE_SIZES).optional().describe("Output resolution (512 = 0.5K, Flash-only)"),
-  output_dir: external_exports.string().optional().describe("Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)"),
-  inline: external_exports.boolean().optional().describe("Return base64 images inline instead of writing to disk"),
-  seed: external_exports.number().int().optional().describe("Seed for reproducible generation; random if omitted"),
-  thinking_level: external_exports.enum(["minimal", "high"]).optional().describe("Reasoning depth (Gemini 3 models); higher can help complex/structural edits"),
-  google_search: external_exports.boolean().optional().describe("Ground the image in live Google Search results (current events, weather, data)"),
-  from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
-  timeout_ms: timeoutMsSchema,
-  idempotency_key: idempotencyKeySchema,
-  async: asyncSchema
-};
-async function resolveVideoInput(args) {
-  if (args.video_url && args.video_path) {
-    throw new McpToolError("Provide `video_url` OR `video_path`, not both.");
+
+// src/client.ts
+init_dist();
+import { basename } from "node:path";
+
+// src/session.ts
+var SessionState = class {
+  /** 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 = /* @__PURE__ */ new Set();
+  /** Forget everything. Tests use this; nothing in `src/` calls it. */
+  reset() {
+    this.jobs.reset();
+    this.lastInteractionId = void 0;
+    this.lastMusicInteractionId = void 0;
+    this.lastVideoInteractionId = void 0;
+    this.writtenOutputs.clear();
   }
-  if (!args.video_path) return { videoUrl: args.video_url };
-  const path = resolveVideoPath(args.video_path);
-  const uploaded = await client.uploadVideo(path, videoMimeType(args.video_path));
-  const videoFileMeta = { uri: uploaded.uri, name: uploaded.name };
-  if (uploaded.expirationTime) videoFileMeta.expires = uploaded.expirationTime;
-  return { videoUrl: uploaded.uri, videoMimeType: uploaded.mimeType, videoFileMeta };
-}
-var videoPathSchema = external_exports.string().optional().describe(
-  "Path to a local video file \u2014 uploaded to the Gemini Files API (~48h retention, 2 GB max) and used as the video reference. Alternative to video_url."
-);
-function pickSeed(seed) {
-  return seed ?? Math.floor(Math.random() * 2147483e3);
+};
+
+// src/client.ts
+var BASE_URL = "https://generativelanguage.googleapis.com/v1beta";
+var SERVICE = "Gemini";
+var INTERACTIONS_SERVICE = "Gemini Interactions";
+var REQUEST_TIMEOUT_MS = 6e4;
+var REQUEST_TIMEOUT_4K_MS = 12e4;
+function resolveTimeoutMs(perCallMs, imageSize) {
+  if (perCallMs !== void 0 && perCallMs > 0) return perCallMs;
+  const env = Number(readEnvVar("GEMINI_TIMEOUT_MS"));
+  if (Number.isFinite(env) && env > 0) return env;
+  return imageSize === "4K" ? REQUEST_TIMEOUT_4K_MS : REQUEST_TIMEOUT_MS;
 }
-var HEARTBEAT_DEFAULT_MS = 1e4;
-async function withProgressHeartbeat(extra, message, fn) {
-  const progressToken = extra?._meta?.progressToken;
-  const send = extra?.sendNotification;
-  const env = Number(readEnvVar("GEMINI_HEARTBEAT_MS"));
-  const intervalMs = Number.isFinite(env) ? env : HEARTBEAT_DEFAULT_MS;
-  const debug = !!readEnvVar("GEMINI_DEBUG");
-  const active = progressToken !== void 0 && !!send && intervalMs > 0;
-  if (debug) {
-    if (active) {
-      console.error(`[gemini-mcp] heartbeat active: progressToken present, interval=${intervalMs}ms \u2014 ${message}`);
-    } else {
-      const reason = progressToken === void 0 ? "no progressToken from host (host cannot extend its tools/call timeout; long calls will hit it)" : !send ? "host provided no sendNotification channel" : "heartbeat disabled (GEMINI_HEARTBEAT_MS=0)";
-      console.error(`[gemini-mcp] heartbeat inactive: ${reason} \u2014 ${message}`);
-    }
+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 CHAIN_404_RETRY_BUDGET_MS = 12e4;
+var CHAIN_404_RETRY_BASE_MS = 2e3;
+var CHAIN_404_RETRY_MAX_SLEEP_MS = 3e4;
+function resolveChainRetryBudgetMs() {
+  const env = Number(readEnvVar("GEMINI_CHAIN_RETRY_MS"));
+  return Number.isFinite(env) && env >= 0 ? env : CHAIN_404_RETRY_BUDGET_MS;
+}
+var ChainedRequest404Error = class extends McpToolError {
+  constructor(previousInteractionId, upstreamMessage, retries, opts) {
+    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.)`,
+      opts
+    );
+    this.previousInteractionId = previousInteractionId;
+    this.upstreamMessage = upstreamMessage;
+    this.retries = retries;
   }
-  if (progressToken === void 0 || !send || intervalMs <= 0) return fn();
-  let ticks = 0;
-  const timer = setInterval(() => {
-    ticks++;
-    const elapsed = Math.round(ticks * intervalMs / 1e3);
-    if (debug) console.error(`[gemini-mcp] heartbeat: ${message} \u2014 still working (${elapsed}s)`);
-    void send({
-      method: "notifications/progress",
-      params: {
-        progressToken,
-        progress: ticks,
-        message: `${message} \u2014 still working (${elapsed}s)`
-      }
-    }).catch(() => {
-    });
-  }, intervalMs);
-  timer.unref?.();
-  try {
-    return await fn();
-  } finally {
-    clearInterval(timer);
+  previousInteractionId;
+  upstreamMessage;
+  retries;
+};
+var GeminiClient = class {
+  /**
+   * 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 = /* @__PURE__ */ 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 = {}) {
+    this.mediaSink = opts.mediaSink ?? createDiskSink();
+    this.explicitApiKey = opts.apiKey?.trim() || void 0;
+    this.fetchImpl = opts.fetchImpl ?? fetch;
+    this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   }
-}
-function timeoutRiskHint(opts) {
-  const proModel = /(?:^|[-_./])pro(?:[-_./]|$)/i.test(opts.model);
-  const fourK = opts.imageSize === "4K";
-  const multi = (opts.count ?? 1) > 1;
-  if (!proModel && !fourK && !multi) return void 0;
-  const why = [proModel && "Pro model", fourK && "4K output", multi && `count=${opts.count}`].filter(Boolean).join(" + ");
-  return `Slow config (${why}) can exceed a host's tools/call timeout (e.g. Claude Desktop ~30s, error -32001). If the host gives up mid-generation the image is still written to disk (and gemini_interact leaves an <image>.json sidecar with the interaction id) \u2014 no rerun needed, just look in the output dir. For a faster in-band result use a Flash model, drop image_size to 1K/2K, or \u2014 in Claude Code \u2014 set MCP_TOOL_TIMEOUT.`;
-}
-function buildMeta(model, seed, opts) {
-  const meta3 = { model, seed };
-  if (opts.aspect_ratio) meta3.aspect_ratio = opts.aspect_ratio;
-  if (opts.image_size) meta3.image_size = opts.image_size;
-  return meta3;
-}
-async function emitMedia(named, kind, opts, meta3, onWritten) {
-  const inline = opts.inline && kind !== "video";
-  if (inline) {
-    const blocks = named.map((n) => ({ type: kind, data: n.media.base64, mimeType: n.media.mimeType }));
-    if (meta3 && Object.keys(meta3).length > 0) {
-      return { content: [{ type: "text", text: JSON.stringify(meta3, null, 2) }, ...blocks] };
+  /**
+   * The `createApiClient` pair for one timeout budget, built lazily and
+   * memoized per distinct timeout (a handful of values in practice). Both
+   * share: the key in the `x-goog-api-key` header (Gemini does not use
+   * `Authorization: Bearer`) and the default 429 retry (once after 2s — the
+   * free tier rate-limits aggressively). `getToken` calls requireKey() so key
+   * resolution stays at REQUEST time: the server boots without a key and the
+   * actionable config error (with its aistudio hint) surfaces on the first
+   * tool call, not at startup.
+   */
+  apisFor(timeoutMs) {
+    let entry = this.apis.get(timeoutMs);
+    if (!entry) {
+      const shared = {
+        tokenHeader: "x-goog-api-key",
+        getToken: () => this.requireKey(),
+        timeout: timeoutMs,
+        fetchImpl: this.fetchImpl
+      };
+      entry = {
+        api: createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared }),
+        // Separate client for the Interactions API so errors name the right API.
+        // The beta-era Api-Revision header is gone: the API went GA and requests
+        // succeed without it (verified live 2026-07-06; see docs/GEMINI-API.md).
+        // Don't re-add a pinned revision — it would freeze us on old semantics.
+        interactionsApi: createApiClient({ baseUrl: BASE_URL, serviceName: INTERACTIONS_SERVICE, ...shared })
+      };
+      this.apis.set(timeoutMs, entry);
     }
-    return { content: blocks };
+    return entry;
   }
-  const dir = resolveOutputDir(opts.output_dir);
-  const paths = [];
-  for (const n of named) paths.push(await writeMedia(dir, n.base, n.media.base64, n.media.mimeType));
-  await onWritten?.(paths);
-  const note = opts.inline && kind === "video" ? { inline_unsupported: "video has no MCP inline content type \u2014 written to disk instead" } : {};
-  return textResult({ [`${kind}s`]: paths, ...note, ...meta3 });
-}
-async function emit(named, opts, meta3, onWritten) {
-  return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), "image", opts, meta3, onWritten);
-}
-
-// src/jobs.ts
-init_dist();
-import { randomUUID, createHash } from "node:crypto";
-var JOB_TTL_MS = 6e5;
-var JOB_MAX = 64;
-var jobs = /* @__PURE__ */ new Map();
-var byKey = /* @__PURE__ */ new Map();
-var runningByFingerprint = /* @__PURE__ */ new Map();
-function isExpired(entry, now) {
-  return entry.settledAt !== void 0 && now - entry.settledAt > JOB_TTL_MS;
-}
-function evict(now) {
-  for (const [id, entry] of jobs) {
-    if (isExpired(entry, now)) remove(id, 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() {
+    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;
   }
-  if (jobs.size < JOB_MAX) return;
-  const settled = [...jobs.values()].filter((e) => e.settledAt !== void 0).sort((a, b) => (a.settledAt ?? 0) - (b.settledAt ?? 0));
-  for (const e of settled) {
-    if (jobs.size < JOB_MAX) break;
-    remove(e.jobId, e);
+  /** The default model after env override (no per-call arg). */
+  defaultModel() {
+    return resolveModel(void 0, readEnvVar("GEMINI_IMAGE_MODEL"));
   }
-}
-function remove(id, entry) {
-  jobs.delete(id);
-  if (entry.idempotencyKey !== void 0 && byKey.get(entry.idempotencyKey) === id) byKey.delete(entry.idempotencyKey);
-  if (runningByFingerprint.get(entry.fingerprint) === id) runningByFingerprint.delete(entry.fingerprint);
-}
-function fingerprintRequest(toolName, parts) {
-  return createHash("sha256").update(`${toolName}\0${JSON.stringify(parts)}`).digest("hex");
-}
-function annotateReused(result, jobId) {
-  const content = result.content ?? [];
-  const first = content[0];
-  if (first && first.type === "text") {
-    let obj;
-    try {
-      obj = JSON.parse(first.text);
-    } catch {
-      obj = {};
+  async call(method, path, body, timeoutMs) {
+    const { api } = this.apisFor(timeoutMs ?? resolveTimeoutMs());
+    return api.fetchJson(method, path, body !== void 0 ? { body } : {});
+  }
+  /**
+   * Upload a local video to the Gemini Files API (resumable protocol) and wait
+   * for it to become usable. Three live-verified steps (docs/GEMINI-API.md
+   * "Files API — local video upload"):
+   *
+   *  1. `POST {UPLOAD_BASE_URL}/files` (command `start`) → the upload session
+   *     URL arrives in the `x-goog-upload-url` RESPONSE HEADER (body is empty).
+   *  2. `POST <session url>` (command `upload, finalize`) with the bytes —
+   *     a file-backed Blob (`fileBlob`/`fs.openAsBlob`), so fetch STREAMS the
+   *     video from disk; it is never buffered in memory. Response: `{file:…}`.
+   *  3. Poll `GET /v1beta/files/<id>` while `state` is `PROCESSING`, until
+   *     `ACTIVE` (the poll response is the File object UNWRAPPED).
+   *
+   * These two upload calls are raw `fetchImpl` (not `createApiClient`): step 1
+   * needs the response *header* and step 2 posts a binary body — neither fits
+   * `fetchJson`. The poll DOES go through the shared client (timeout + retry).
+   * Uploads deliberately have no abort timeout: a multi-hundred-MB video can
+   * legitimately take longer than any fixed budget.
+   *
+   * Returned files live ~48h (`expirationTime`); per-file cap is 2 GB
+   * (enforced locally before any bytes are sent).
+   */
+  async uploadVideo(path, mimeType) {
+    const key = this.requireKey();
+    const blob = await fileBlob(path, { type: mimeType, maxBytes: FILE_MAX_BYTES, label: "Video" });
+    const startPath = "/files";
+    const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
+      method: "POST",
+      headers: {
+        "x-goog-api-key": key,
+        "X-Goog-Upload-Protocol": "resumable",
+        "X-Goog-Upload-Command": "start",
+        "X-Goog-Upload-Header-Content-Length": String(blob.size),
+        "X-Goog-Upload-Header-Content-Type": mimeType,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ file: { display_name: basename(path) } })
+    });
+    if (!startRes.ok) {
+      throw new McpToolError(
+        formatApiError(startRes.status, "POST", `/upload/v1beta${startPath}`, await startRes.text(), { service: SERVICE })
+      );
     }
-    obj.reused = true;
-    obj.reused_job_id = jobId;
-    return { ...result, content: [{ ...first, text: JSON.stringify(obj, null, 2) }, ...content.slice(1)] };
-  }
-  return {
-    ...result,
-    content: [{ type: "text", text: JSON.stringify({ reused: true, reused_job_id: jobId }, null, 2) }, ...content]
-  };
-}
-function jobHandle(jobId, status) {
-  return textResult({
-    job_id: jobId,
-    status,
-    hint: `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done" (results are per-process and expire ~10 min after completion).`
-  });
-}
-async function dispatch(opts, work) {
-  const { toolName, fingerprint, idempotencyKey, async } = opts;
-  const now = Date.now();
-  let hit;
-  if (idempotencyKey !== void 0) {
-    const id = byKey.get(idempotencyKey);
-    const entry2 = id ? jobs.get(id) : void 0;
-    if (entry2 && entry2.status !== "failed" && !isExpired(entry2, now)) hit = entry2;
-  } else {
-    const id = runningByFingerprint.get(fingerprint);
-    const entry2 = id ? jobs.get(id) : void 0;
-    if (entry2 && entry2.status === "running") hit = entry2;
-  }
-  if (hit) {
-    if (async) return jobHandle(hit.jobId, hit.status);
-    return annotateReused(await hit.promise, hit.jobId);
-  }
-  const jobId = randomUUID();
-  evict(now);
-  const promise2 = work();
-  const entry = { jobId, toolName, fingerprint, idempotencyKey, status: "running", promise: promise2, createdAt: now };
-  jobs.set(jobId, entry);
-  if (idempotencyKey !== void 0) byKey.set(idempotencyKey, jobId);
-  runningByFingerprint.set(fingerprint, jobId);
-  promise2.then(
-    (res) => {
-      entry.status = "done";
-      entry.result = res;
-      entry.settledAt = Date.now();
-    },
-    (err) => {
-      entry.status = "failed";
-      entry.error = { message: err instanceof Error ? err.message : String(err), hint: err?.hint };
-      entry.settledAt = Date.now();
+    const uploadUrl = startRes.headers.get("x-goog-upload-url");
+    if (!uploadUrl) {
+      throw new McpToolError(`${SERVICE} upload start did not return an x-goog-upload-url header`, {
+        hint: "The Files API resumable-upload contract may have changed \u2014 see docs/GEMINI-API.md."
+      });
     }
-  ).finally(() => {
-    if (runningByFingerprint.get(fingerprint) === jobId) runningByFingerprint.delete(fingerprint);
-  });
-  if (async) return jobHandle(jobId, "running");
-  return promise2;
-}
-function getJobResult(jobId) {
-  const entry = jobs.get(jobId);
-  if (!entry) {
-    throw new McpToolError(`No job "${jobId}" \u2014 unknown or expired.`, {
-      hint: "Jobs are per-process and evicted ~10 min after completion (or on server restart). If the generation likely finished, check the output dir / <image>.json sidecar instead of polling."
+    const upRes = await this.fetchImpl(uploadUrl, {
+      method: "POST",
+      headers: {
+        "X-Goog-Upload-Offset": "0",
+        "X-Goog-Upload-Command": "upload, finalize"
+      },
+      body: blob
     });
+    if (!upRes.ok) {
+      throw new McpToolError(
+        formatApiError(upRes.status, "POST", "/upload/v1beta/files (finalize)", await upRes.text(), { service: SERVICE })
+      );
+    }
+    let file2 = (await upRes.json()).file ?? {};
+    const name = file2.name ?? "";
+    if (!/^files\/[\w-]+$/.test(name)) {
+      throw new McpToolError(`${SERVICE} upload returned an unexpected file name: ${name || "(none)"}`);
+    }
+    for (let attempt = 0; file2.state === "PROCESSING"; attempt++) {
+      if (attempt >= FILE_POLL_MAX_ATTEMPTS) {
+        throw new McpToolError(`${SERVICE} video file ${name} is still processing after ${FILE_POLL_INTERVAL_MS * FILE_POLL_MAX_ATTEMPTS / 6e4} minutes`, {
+          hint: "Very long videos can take a while to process \u2014 retry later by passing the file uri as video_url."
+        });
+      }
+      await this.sleep(FILE_POLL_INTERVAL_MS);
+      file2 = await this.call("GET", `/${name}`);
+    }
+    if (file2.state !== "ACTIVE") {
+      throw new McpToolError(
+        `${SERVICE} video file processing failed (state ${file2.state ?? "unknown"})${file2.error?.message ? `: ${file2.error.message}` : ""}`,
+        { hint: "Check the video is a supported format/codec and under 2 GB." }
+      );
+    }
+    if (!file2.uri) {
+      throw new McpToolError(`${SERVICE} did not return a uri for uploaded file ${name}`);
+    }
+    return { name, uri: file2.uri, mimeType: file2.mimeType ?? mimeType, expirationTime: file2.expirationTime };
   }
-  if (entry.status === "running") return jobHandle(jobId, "running");
-  if (entry.status === "failed") {
-    throw new McpToolError(entry.error?.message ?? "Job failed.", entry.error?.hint ? { hint: entry.error.hint } : void 0);
+  async listModels() {
+    const data = await this.call("GET", "/models?pageSize=200");
+    return filterImageModels(data.models ?? []);
   }
-  if (!entry.result) throw new McpToolError(`Job "${jobId}" completed without a recorded result.`);
-  return entry.result;
-}
-
-// src/tools/_confirm.ts
-init_dist();
-function previewUnlessConfirmed(confirm, action, method, path, body) {
-  if (confirm === true) return null;
-  return textResult({
-    dryRun: true,
-    action,
-    method,
-    path,
-    ...body !== void 0 ? { willSend: body } : {},
-    note: "Re-run with confirm: true to execute."
-  });
-}
-async function previewLocalInputsUnlessConfirmed(confirm, action, endpoint, imagePaths, videoPath) {
-  const hasLocal = (imagePaths?.length ?? 0) > 0 || Boolean(videoPath);
-  if (confirm === true || !hasLocal) return null;
-  const inputs = [];
-  for (const p of imagePaths ?? []) inputs.push(await previewImageInput(p));
-  if (videoPath) inputs.push(await previewVideoInput(videoPath));
-  return previewUnlessConfirmed(confirm, action, "POST", endpoint, { inputs });
-}
-
-// src/tools/generate.ts
-var GENERATE_ENDPOINT = "/v1beta/models/{model}:generateContent";
-var SEND_LOCAL_ACTION = "Send local file input(s) to the Gemini API";
-var 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).";
-function registerGenerateTools(server) {
-  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.",
-      annotations: { readOnlyHint: false, openWorldHint: true },
-      inputSchema: {
-        prompt: external_exports.string().min(1).describe("Text prompt describing the image"),
-        count: external_exports.number().int().positive().max(8).optional().describe("Number of independent images (default 1)"),
-        filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
-        images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to reference input images (image-conditioned generation)"),
-        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs"),
-        video_url: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
-        video_path: videoPathSchema,
-        confirm: schemaConfirm,
-        ...sharedImageSchema
+  async generate(opts) {
+    const model = resolveModel(opts.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+    const parts = [{ text: opts.prompt }];
+    for (const img of opts.images ?? []) {
+      parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
+    }
+    if (opts.videoUrl) {
+      parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" } });
+    }
+    const generationConfig = { responseModalities: ["TEXT", "IMAGE"] };
+    if (opts.aspectRatio || opts.imageSize) {
+      const imageConfig = {};
+      if (opts.aspectRatio) imageConfig.aspectRatio = opts.aspectRatio;
+      if (opts.imageSize) imageConfig.imageSize = opts.imageSize;
+      generationConfig.imageConfig = imageConfig;
+    }
+    if (opts.seed !== void 0) generationConfig.seed = opts.seed;
+    if (opts.thinkingLevel !== void 0) generationConfig.thinkingConfig = { thinkingLevel: opts.thinkingLevel };
+    const requestBody = { contents: [{ parts }], generationConfig };
+    if (opts.googleSearch) requestBody.tools = [{ google_search: {} }];
+    const data = await this.call(
+      "POST",
+      `/models/${model}:generateContent`,
+      requestBody,
+      resolveTimeoutMs(opts.timeoutMs, opts.imageSize)
+    );
+    const images = [];
+    const textParts = [];
+    let groundingMeta;
+    for (const cand of data.candidates ?? []) {
+      for (const part of cand.content?.parts ?? []) {
+        const inline = part.inline_data ?? part.inlineData;
+        if (inline?.data) {
+          images.push({ base64: inline.data, mimeType: inline.mime_type ?? inline.mimeType ?? "image/jpeg" });
+        } else if (typeof part.text === "string" && part.text.trim()) {
+          textParts.push(part.text);
+        }
       }
-    },
-    async (args, extra) => {
-      const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images, args.video_path);
-      if (gate) return gate;
-      const count = args.count ?? 1;
-      const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
-      const fingerprint = fingerprintRequest("gemini_image_generate", {
-        model,
-        prompt: args.prompt,
-        aspect_ratio: args.aspect_ratio,
-        image_size: args.image_size,
-        thinking_level: args.thinking_level,
-        google_search: args.google_search,
-        count,
-        images: args.images,
-        images_base64: args.images_base64,
-        from_clipboard: args.from_clipboard,
-        video_url: args.video_url,
-        video_path: args.video_path
+      if (cand.groundingMetadata) groundingMeta = cand.groundingMetadata;
+    }
+    if (images.length === 0) {
+      throw new McpToolError(`${SERVICE} returned no image`, {
+        hint: "The request may have been blocked by safety filters \u2014 try rephrasing the prompt."
       });
-      return 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) : slugify2(args.prompt);
-        const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args));
-        const named = [];
-        let capturedText;
-        let capturedGrounding;
-        await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : "image"} (${model})`, async () => {
-          for (let i = 0; i < count; i++) {
-            const result = await client.generate({
-              prompt: args.prompt,
-              images: refInputs.length > 0 ? refInputs : void 0,
-              model: args.model,
-              aspectRatio: args.aspect_ratio,
-              imageSize: args.image_size,
-              seed: seed + i,
-              thinkingLevel: args.thinking_level,
-              googleSearch: args.google_search,
-              videoUrl: video.videoUrl,
-              videoMimeType: video.videoMimeType,
-              timeoutMs: args.timeout_ms
-            });
-            const { images: [img], text } = result;
-            if (text && !capturedText) capturedText = text;
-            if (result.grounding && !capturedGrounding) capturedGrounding = result.grounding;
-            named.push({ image: img, base: count === 1 ? slug : `${slug}-${String(i + 1).padStart(2, "0")}` });
-          }
-        });
-        const meta3 = buildMeta(model, seed, args);
-        if (capturedText) meta3.text = capturedText;
-        if (capturedGrounding) meta3.grounding = capturedGrounding;
-        if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
-        meta3.hint = REFINE_HINT;
-        const risk = timeoutRiskHint({ model, imageSize: args.image_size, count });
-        if (risk) meta3.timeout_risk = risk;
-        return emit(named, args, meta3);
+    }
+    const text = textParts.join("\n") || void 0;
+    let grounding;
+    if (groundingMeta) {
+      const queries = (groundingMeta.webSearchQueries ?? []).filter(Boolean);
+      const sources = (groundingMeta.groundingChunks ?? []).map((c) => c.web).filter((w) => !!w);
+      if (queries.length > 0 || sources.length > 0) {
+        grounding = {};
+        if (queries.length > 0) grounding.queries = queries;
+        if (sources.length > 0) grounding.sources = sources;
+      }
+    }
+    return { images, text, grounding };
+  }
+  async interact(opts) {
+    const model = resolveModel(opts.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+    const inputParts = [{ type: "text", text: opts.input }];
+    for (const img of opts.images ?? []) {
+      inputParts.push({ type: "image", mime_type: img.mimeType, data: img.base64 });
+    }
+    if (opts.videoUrl) {
+      inputParts.push({ type: "video", uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" });
+    }
+    const responseFormat = { type: "image", mime_type: "image/jpeg" };
+    if (opts.aspectRatio) responseFormat.aspect_ratio = opts.aspectRatio;
+    if (opts.imageSize) responseFormat.image_size = opts.imageSize;
+    const body = { model, input: inputParts, response_format: responseFormat };
+    if (opts.thinkingLevel !== void 0) body.generation_config = { thinking_level: opts.thinkingLevel };
+    if (opts.previousInteractionId !== void 0) body.previous_interaction_id = opts.previousInteractionId;
+    if (opts.googleSearch || opts.searchTypes?.length) {
+      const searchTool = { type: "google_search" };
+      if (opts.searchTypes?.length) searchTool.search_types = opts.searchTypes;
+      body.tools = [searchTool];
+    }
+    const data = await this.postInteraction(body, opts);
+    const { images, text, grounding } = this.extractInteraction(data, opts.searchTypes);
+    if (images.length === 0) {
+      throw new McpToolError("Gemini returned no image", {
+        hint: "The request may have been blocked by safety filters \u2014 try rephrasing the prompt."
+      });
+    }
+    return { id: data.id, 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.
+   */
+  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({ type: "image", mime_type: img.mimeType, data: img.base64 });
+    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 { 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."
       });
     }
-  );
-  server.registerTool(
-    "gemini_image_edit",
-    {
-      description: "Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. For a SERIES of successive edits to the same image, prefer gemini_interact (multi-turn) \u2014 it keeps edit context and avoids re-processing the full image each round; use gemini_image_edit for one-off edits or composing multiple distinct inputs. Gemini over-preserves the input; there is no edit-strength control \u2014 for large structural changes, reroll with a different `seed` or more forceful wording.",
-      annotations: { readOnlyHint: false, openWorldHint: true },
-      inputSchema: {
-        prompt: external_exports.string().min(1).describe("Instruction describing the edit or composition"),
-        images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to input image file(s) (1 = edit, 2+ = compose)"),
-        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Input images as base64 strings or data URIs"),
-        filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
-        confirm: schemaConfirm,
-        ...sharedImageSchema
-      }
-    },
-    async (args, extra) => {
-      const hasPaths = (args.images?.length ?? 0) > 0;
-      const hasBase64 = (args.images_base64?.length ?? 0) > 0;
-      if (!hasPaths && !hasBase64 && !args.from_clipboard) {
-        throw new McpToolError("Provide at least one input image via `images`, `images_base64`, or `from_clipboard`.");
-      }
-      const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images);
-      if (gate) return gate;
-      const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
-      const fingerprint = fingerprintRequest("gemini_image_edit", {
-        model,
-        prompt: args.prompt,
-        aspect_ratio: args.aspect_ratio,
-        image_size: args.image_size,
-        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 () => {
-        const seed = pickSeed(args.seed);
-        const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
-        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client.generate({
-          prompt: args.prompt,
-          images: inputs,
-          model: args.model,
-          aspectRatio: args.aspect_ratio,
-          imageSize: args.image_size,
-          seed,
-          thinkingLevel: args.thinking_level,
-          googleSearch: args.google_search,
-          timeoutMs: args.timeout_ms
-        }));
-        const { images: [img], text } = result;
-        const meta3 = buildMeta(model, seed, args);
-        if (text) meta3.text = text;
-        if (result.grounding) meta3.grounding = result.grounding;
-        meta3.hint = REFINE_HINT;
-        const risk = timeoutRiskHint({ model, imageSize: args.image_size });
-        if (risk) meta3.timeout_risk = risk;
-        return emit([{ image: img, base: slug }], args, meta3);
+    return { id: data.id, videos, text };
+  }
+  /**
+   * Generate music via a Lyria model (Interactions API, inline audio). Reuses
+   * the interact plumbing with an `audio` response_format. Preview model.
+   */
+  async generateMusic(opts) {
+    const model = opts.model ?? DEFAULT_MUSIC_MODEL;
+    const inputParts = [{ type: "text", text: opts.input }];
+    for (const img of opts.images ?? []) inputParts.push({ type: "image", mime_type: img.mimeType, data: img.base64 });
+    const responseFormat = { type: "audio" };
+    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;
+    const data = await this.postInteraction(body, opts);
+    const { audios, text } = this.extractInteraction(data);
+    if (audios.length === 0) {
+      throw new McpToolError("Gemini returned no audio", {
+        hint: "The request may have been blocked by a safety filter \u2014 try rephrasing the prompt."
       });
     }
-  );
-}
-
-// src/tools/set.ts
-init_zod();
-init_dist();
-function registerSetTools(server) {
-  server.registerTool(
-    "gemini_image_set",
-    {
-      description: "Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master).",
-      annotations: { readOnlyHint: false, openWorldHint: true },
-      inputSchema: {
-        master_prompt: external_exports.string().min(1).describe("Prompt for the master/reference image"),
-        scenes: external_exports.array(external_exports.string().min(1)).min(1).max(8).optional().describe("Per-image prompts (1-8); each references the master"),
-        count: external_exports.number().int().positive().max(8).optional().describe("Number of variations of master_prompt (when scenes omitted)"),
-        reference_mode: external_exports.enum(["master", "chain"]).optional().describe("master: every image references the master (default). chain: each references the previous."),
-        basename: external_exports.string().optional().describe("Base filename prefix for output images (default: slugified master_prompt)"),
-        master_images: external_exports.array(external_exports.string().min(1)).optional().describe("Reference image paths passed to the master generation call"),
-        master_images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs for master generation"),
-        confirm: schemaConfirm,
-        ...sharedImageSchema
+    return { id: data.id, audios, text };
+  }
+  /** 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) {
+        if (!(opts.previousInteractionId && err instanceof ApiError && err.status === 404)) throw err;
+        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 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
+        });
       }
-    },
-    async (args, extra) => {
-      if (args.scenes && args.count || !args.scenes && !args.count) {
-        throw new McpToolError("Provide exactly one of `scenes` or `count`.");
+    }
+  }
+  /**
+   * Collect `model_output` media (image/video/audio) + text + grounding from an
+   * interactions response. Only the `model_output` step is surfaced — `thought`
+   * steps (internal reasoning / draft images) are dropped on purpose so they
+   * can't leak into text or pollute the outputs. Tolerant of snake/camel MIME.
+   */
+  extractInteraction(data, searchTypes) {
+    const images = [];
+    const videos = [];
+    const audios = [];
+    const textParts = [];
+    const searchQueries = [];
+    const searchSuggestions = /* @__PURE__ */ new Set();
+    for (const step of data.steps ?? []) {
+      if (step.type === "google_search_call") {
+        for (const q of step.arguments?.queries ?? []) if (q?.trim()) searchQueries.push(q);
+        continue;
       }
-      const gate = await previewLocalInputsUnlessConfirmed(args.confirm, "Send local master image input(s) to the Gemini API", "/v1beta/models/{model}:generateContent", args.master_images);
-      if (gate) return gate;
-      const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
-      const fingerprint = fingerprintRequest("gemini_image_set", {
-        model,
-        master_prompt: args.master_prompt,
-        scenes: args.scenes,
-        count: args.count,
-        reference_mode: args.reference_mode,
-        aspect_ratio: args.aspect_ratio,
-        image_size: args.image_size,
-        thinking_level: args.thinking_level,
-        google_search: args.google_search,
-        master_images: args.master_images,
-        master_images_base64: args.master_images_base64,
-        from_clipboard: args.from_clipboard
-      });
-      return dispatch({ toolName: "gemini_image_set", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
-        const seed = pickSeed(args.seed);
-        const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
-        const slug = args.basename ? baseName(args.basename) : slugify2(args.master_prompt);
-        const masterRefInputs = await gatherImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard });
-        const named = [];
-        const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
-          const result = await client.generate({
-            prompt: args.master_prompt,
-            images: masterRefInputs.length > 0 ? masterRefInputs : void 0,
-            seed,
-            ...cfg
-          });
-          const master = result.images[0];
-          named.push({ image: master, base: `${slug}-master` });
-          const scenePrompts = args.scenes ?? Array.from({ length: args.count ?? 0 }, () => args.master_prompt);
-          const mode = args.reference_mode ?? "master";
-          if (mode === "chain") {
-            let ref = master;
-            for (let i = 0; i < scenePrompts.length; i++) {
-              const { images: [img] } = await client.generate({ prompt: scenePrompts[i], images: [ref], seed: seed + i + 1, ...cfg });
-              named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, "0")}` });
-              ref = img;
-            }
-          } else {
-            const scenes = await Promise.all(
-              scenePrompts.map((p, i) => client.generate({ prompt: p, images: [master], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
-            );
-            scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, "0")}` }));
+      if (step.type === "google_search_result") {
+        if (searchTypes?.includes("image_search")) {
+          for (const r of step.result ?? []) if (r.search_suggestions?.trim()) searchSuggestions.add(r.search_suggestions);
+        }
+        continue;
+      }
+      if (step.type !== "model_output") continue;
+      for (const parts of [step.content ?? [], step.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);
           }
-          return result;
-        });
-        const masterText = masterResult.text;
-        const meta3 = buildMeta(model, seed, args);
-        if (masterText) meta3.text = masterText;
-        if (masterResult.grounding) meta3.grounding = masterResult.grounding;
-        const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length });
-        if (risk) meta3.timeout_risk = risk;
-        return emit(named, args, meta3);
+        }
+      }
+    }
+    let grounding;
+    if (searchQueries.length > 0 || searchSuggestions.size > 0) {
+      grounding = {};
+      if (searchQueries.length > 0) grounding.queries = searchQueries;
+      if (searchSuggestions.size > 0) grounding.search_suggestions = [...searchSuggestions];
+    }
+    return { images, videos, audios, text: textParts.join("\n") || void 0, grounding };
+  }
+};
+var client = new GeminiClient();
+
+// src/tools/interact.ts
+init_images();
+
+// src/sidecar.ts
+import { readdir, readFile as readFile3, stat as stat2 } from "node:fs/promises";
+import { existsSync as existsSync2 } from "node:fs";
+import { join as join4 } from "node:path";
+var SIDECAR_SUFFIX = ".json";
+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 = join4(dir, entry);
+    try {
+      const parsed = JSON.parse(await readFile3(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) => existsSync2(p)),
+        mtimeMs: (await stat2(sidecarPath)).mtimeMs
       });
+    } catch {
+      continue;
     }
-  );
+  }
+  return records.sort((a, b) => b.mtimeMs - a.mtimeMs);
+}
+async function findInteractionImages(dir, interactionId) {
+  const records = await readSidecars(dir);
+  return records.find((r) => r.interactionId === interactionId)?.images ?? [];
+}
+async function latestInteractionId(dir) {
+  return (await readSidecars(dir))[0]?.interactionId;
 }
 
 // src/tools/interact.ts
-init_zod();
-init_dist();
-var lastInteractionId;
-var writtenOutputs = /* @__PURE__ */ new Set();
 var NEW_REFERENCES_ONLY = "NEW reference images only (e.g. a style or target photo). When chaining with previous_interaction_id, do NOT re-attach the prior turn's output \u2014 the interaction already contains it, and re-sending it anchors the model against your edit.";
-function splitReattachedOutputs(images) {
+function splitReattachedOutputs(images, writtenOutputs) {
   const kept = [];
   const dropped = [];
   for (const p of images) {
@@ -33689,16 +33940,18 @@ function splitReattachedOutputs(images) {
   }
   return { kept, dropped };
 }
-function registerInteractTools(server) {
+function registerInteractTools(server, client2) {
+  const onDiskRuntime = client2.mediaSink?.persistsFiles ?? true;
+  const recoveryDescription = onDiskRuntime ? "If a call times out on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction \u2014 check the output dir before re-issuing (a re-issue is a second billable generation). If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). " : "This connector has no filesystem: there is no output dir and no `<image>.json` sidecar, so a lost response cannot be recovered from disk and a 404 on a chained call cannot be re-anchored automatically. Capture the returned `interaction_id` from every result, and use `async: true` + gemini_get_result for long generations. ";
   server.registerTool(
     "gemini_interact",
     {
-      description: "Preferred tool for iterative or multi-step refinement of a single image \u2014 multi-turn generation/editing via Gemini's Interactions API. To refine, capture the returned interaction `id` and pass it as `previous_interaction_id` on the next call \u2014 do NOT start a new interaction or re-upload the image for each tweak. `continue_last: true` chains from this session's most recent interaction without threading the id. If a call times out on the client side, the generation usually still completes: the image plus a `<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` still resumes that interaction \u2014 check the output dir before re-issuing (a re-issue is a second billable generation). Output is JPEG.",
+      description: "Preferred tool for iterative or multi-step refinement of a single image \u2014 multi-turn generation/editing via Gemini's Interactions API. To refine, capture the returned interaction `id` and pass it as `previous_interaction_id` on the next call \u2014 do NOT start a new interaction or re-upload the image for each tweak. `continue_last: true` chains from this session's most recent interaction without threading the id. " + recoveryDescription + "Output is JPEG.",
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         input: external_exports.string().min(1).describe("Text prompt or editing instruction"),
         previous_interaction_id: external_exports.string().optional().describe("ID from a prior gemini_interact call \u2014 continues that multi-turn conversation"),
-        continue_last: external_exports.boolean().optional().describe("Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins)"),
+        continue_last: external_exports.boolean().optional().describe("Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins). Survives a server restart by falling back to the newest <image>.json sidecar in the output dir."),
         images: external_exports.array(external_exports.string().min(1)).optional().describe(`Paths to reference input images. ${NEW_REFERENCES_ONLY}`),
         images_base64: external_exports.array(external_exports.string().min(1)).optional().describe(`Reference images as base64 strings or data URIs. ${NEW_REFERENCES_ONLY}`),
         model: external_exports.string().optional().describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
@@ -33722,19 +33975,26 @@ function registerInteractTools(server) {
       }
     },
     async (args, extra) => {
+      assertLocalInputsAvailable(client2.mediaSink, args);
+      const onDisk = client2.mediaSink?.persistsFiles ?? true;
       let previousInteractionId = args.previous_interaction_id;
+      let continuedFromSidecar = false;
       if (!previousInteractionId && args.continue_last) {
-        if (!lastInteractionId) {
+        previousInteractionId = client2.session.lastInteractionId;
+        if (!previousInteractionId && onDisk) {
+          previousInteractionId = await latestInteractionId(resolveOutputDir(args.output_dir));
+          continuedFromSidecar = previousInteractionId !== void 0;
+        }
+        if (!previousInteractionId) {
           throw new McpToolError("No previous interaction to continue in this session.", {
-            hint: "Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id."
+            hint: onDisk ? "Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id." : "Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id. (This hosted connector has no filesystem, so there are no <image>.json sidecars to recover an id from across restarts.)"
           });
         }
-        previousInteractionId = lastInteractionId;
       }
       let images = args.images;
       let dropped = [];
       if (previousInteractionId && images?.length) {
-        ({ kept: images, dropped } = splitReattachedOutputs(images));
+        ({ kept: images, dropped } = splitReattachedOutputs(images, client2.session.writtenOutputs));
       }
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, "Send local file input(s) to the Gemini Interactions API", "/v1beta/interactions", images, args.video_path);
       if (gate) return gate;
@@ -33754,40 +34014,69 @@ function registerInteractTools(server) {
         video_url: args.video_url,
         video_path: args.video_path
       });
-      return dispatch({ toolName: "gemini_interact", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_interact", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
         const inputs = await gatherImageInputs({ images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args));
-        const r = await withProgressHeartbeat(extra, "Generating image (Gemini Interactions API)", () => client.interact({
+        const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args, client2));
+        const callOpts = {
           input: args.input,
-          images: inputs.length ? inputs : void 0,
           model: args.model,
           aspectRatio: args.aspect_ratio,
           imageSize: args.image_size,
           thinkingLevel: args.thinking_level,
-          previousInteractionId,
           googleSearch: args.google_search,
           searchTypes: args.search_types,
           videoUrl: video.videoUrl,
           videoMimeType: video.videoMimeType,
           timeoutMs: args.timeout_ms
-        }));
-        lastInteractionId = r.id;
+        };
+        let chainRecovered;
+        const r = await withProgressHeartbeat(extra, "Generating image (Gemini Interactions API)", async () => {
+          try {
+            return await client2.interact({ ...callOpts, images: inputs.length ? inputs : void 0, previousInteractionId });
+          } catch (err) {
+            if (!(err instanceof ChainedRequest404Error)) throw err;
+            if (!onDisk) throw err;
+            const reanchorOn = await findInteractionImages(resolveOutputDir(args.output_dir), err.previousInteractionId);
+            if (!reanchorOn.length) throw err;
+            const carried = await Promise.all(reanchorOn.map((p) => readImageAsInline(p)));
+            try {
+              const probe = await client2.interact({ ...callOpts, images: [...carried, ...inputs], previousInteractionId: void 0 });
+              chainRecovered = { expired_interaction_id: err.previousInteractionId, reanchored_on: reanchorOn };
+              return probe;
+            } catch (probeErr) {
+              if (!(probeErr instanceof ApiError && probeErr.status === 404)) throw probeErr;
+              throw new McpToolError(
+                // Remediation goes in the MESSAGE, not just `hint`: MCP error
+                // serialization surfaces the message and drops the hint, so a
+                // hint-only fix is invisible exactly when it's needed.
+                `The interaction id is not the cause of this 404: the same request re-issued WITHOUT previous_interaction_id ("${err.previousInteractionId}") also returned 404. Upstream said: ${probeErr.message}. Check that the model id ("${model}") resolves \u2014 see gemini_list_models \u2014 and that any files/\u2026 uri you referenced hasn't expired (~48h TTL). Re-chaining or re-anchoring will not help.`,
+                {
+                  hint: `Check the model id ("${model}") resolves \u2014 see gemini_list_models \u2014 and that any files/\u2026 uri you referenced hasn't expired (~48h TTL). Re-chaining or re-anchoring will not help.`,
+                  cause: probeErr
+                }
+              );
+            }
+          }
+        });
+        client2.session.lastInteractionId = r.id;
         const meta3 = { model, interaction_id: r.id };
-        if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
+        if (chainRecovered) meta3.chain_recovered = chainRecovered;
+        else if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
+        if (continuedFromSidecar) meta3.continued_from_sidecar = true;
         if (dropped.length) meta3.dropped_previous_output = dropped;
         meta3.hint = `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) \u2014 do NOT re-attach the returned image as an input; the interaction already contains it.`;
         if (r.text) meta3.text = r.text;
         if (r.grounding) meta3.grounding = r.grounding;
         if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
-        const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+        const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: onDisk });
         if (risk) meta3.timeout_risk = risk;
         const slug = args.filename ? baseName(args.filename) : slugify2(args.input);
         const named = r.images.map((image, i) => ({
           image,
           base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, "0")}` : slug
         }));
-        return emit(named, args, meta3, async (paths) => {
-          for (const p of paths) writtenOutputs.add(p);
+        return emit(named, { ...args, sink: client2.mediaSink }, meta3, async (paths) => {
+          for (const p of paths) client2.session.writtenOutputs.add(p);
           try {
             for (const p of paths) await writeSidecar(p, { ...meta3, images: paths });
           } catch (err) {
@@ -33802,10 +34091,10 @@ function registerInteractTools(server) {
 // src/tools/video.ts
 init_zod();
 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 lastVideoInteractionId;
-function registerVideoTools(server) {
+function registerVideoTools(server, client2) {
   server.registerTool(
     "gemini_video_generate",
     {
@@ -33830,14 +34119,15 @@ function registerVideoTools(server) {
       }
     },
     async (args, extra) => {
+      assertLocalInputsAvailable(client2.mediaSink, args);
       let previousInteractionId = args.previous_interaction_id;
       if (!previousInteractionId && args.continue_last) {
-        if (!lastVideoInteractionId) {
+        if (!client2.session.lastVideoInteractionId) {
           throw new McpToolError("No previous video interaction to continue in this session.", {
             hint: "Generate a video first, or pass an explicit previous_interaction_id."
           });
         }
-        previousInteractionId = lastVideoInteractionId;
+        previousInteractionId = client2.session.lastVideoInteractionId;
       }
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, "Send local image input(s) to the Gemini omni API", "/v1beta/interactions", args.images);
       if (gate) return gate;
@@ -33852,9 +34142,9 @@ function registerVideoTools(server) {
         from_clipboard: args.from_clipboard,
         previous_interaction_id: previousInteractionId
       });
-      return dispatch({ toolName: "gemini_video_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_video_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
         const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client.generateVideo({
+        const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client2.generateVideo({
           input: args.prompt,
           images: inputs.length ? inputs : void 0,
           model: args.model,
@@ -33863,7 +34153,7 @@ function registerVideoTools(server) {
           previousInteractionId,
           timeoutMs: args.timeout_ms
         }));
-        lastVideoInteractionId = r.id;
+        client2.session.lastVideoInteractionId = r.id;
         const meta3 = { model, interaction_id: r.id };
         if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
         if (r.text) meta3.text = r.text;
@@ -33873,7 +34163,7 @@ function registerVideoTools(server) {
           media,
           base: r.videos.length > 1 ? `${slug}-${String(i + 1).padStart(2, "0")}` : slug
         }));
-        return emitMedia(named, "video", { output_dir: args.output_dir }, meta3);
+        return emitMedia(named, "video", { output_dir: args.output_dir, sink: client2.mediaSink }, meta3);
       });
     }
   );
@@ -33882,13 +34172,13 @@ function registerVideoTools(server) {
 // src/tools/music.ts
 init_zod();
 init_dist();
+init_images();
 var MUSIC_MODELS = ["lyria-3-clip-preview", "lyria-3-pro-preview"];
 var AUDIO_FORMATS = ["mp3", "wav"];
 function isProModel(model) {
   return /pro/i.test(model);
 }
-var lastMusicInteractionId;
-function registerMusicTools(server) {
+function registerMusicTools(server, client2) {
   server.registerTool(
     "gemini_music_generate",
     {
@@ -33913,6 +34203,7 @@ function registerMusicTools(server) {
       }
     },
     async (args, extra) => {
+      assertLocalInputsAvailable(client2.mediaSink, args);
       const model = args.model ?? DEFAULT_MUSIC_MODEL;
       if (args.audio_format === "wav" && !isProModel(model)) {
         throw new McpToolError(`WAV output requires a Pro model; ${model} only produces MP3.`, {
@@ -33921,12 +34212,12 @@ function registerMusicTools(server) {
       }
       let previousInteractionId = args.previous_interaction_id;
       if (!previousInteractionId && args.continue_last) {
-        if (!lastMusicInteractionId) {
+        if (!client2.session.lastMusicInteractionId) {
           throw new McpToolError("No previous music interaction to continue in this session.", {
             hint: "Generate music first, or pass an explicit previous_interaction_id."
           });
         }
-        previousInteractionId = lastMusicInteractionId;
+        previousInteractionId = client2.session.lastMusicInteractionId;
       }
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, "Send local image input(s) to the Gemini Lyria API", "/v1beta/interactions", args.images);
       if (gate) return gate;
@@ -33939,9 +34230,9 @@ function registerMusicTools(server) {
         from_clipboard: args.from_clipboard,
         previous_interaction_id: previousInteractionId
       });
-      return dispatch({ toolName: "gemini_music_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_music_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
         const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client.generateMusic({
+        const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client2.generateMusic({
           input: args.prompt,
           images: inputs.length ? inputs : void 0,
           model: args.model,
@@ -33949,7 +34240,7 @@ function registerMusicTools(server) {
           previousInteractionId,
           timeoutMs: args.timeout_ms
         }));
-        lastMusicInteractionId = r.id;
+        client2.session.lastMusicInteractionId = r.id;
         const meta3 = { model, interaction_id: r.id };
         if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
         if (r.text) meta3.text = r.text;
@@ -33959,7 +34250,7 @@ function registerMusicTools(server) {
           media,
           base: r.audios.length > 1 ? `${slug}-${String(i + 1).padStart(2, "0")}` : slug
         }));
-        return emitMedia(named, "audio", { inline: args.inline, output_dir: args.output_dir }, meta3);
+        return emitMedia(named, "audio", { inline: args.inline, output_dir: args.output_dir, sink: client2.mediaSink }, meta3);
       });
     }
   );
@@ -33967,24 +34258,26 @@ function registerMusicTools(server) {
 
 // src/tools/jobs.ts
 init_zod();
-function registerJobTools(server) {
+function registerJobTools(server, client2) {
   server.registerTool(
     "gemini_get_result",
     {
-      description: 'Retrieve an async generation started with `async: true`. Pass the returned `job_id`: while running it reports status "running"; on completion it returns the normal result (image paths / inline images + meta); on failure it raises the recorded error. Jobs are per-process and expire ~10 min after completion \u2014 if a job id is unknown, check the output dir / <image>.json sidecar.',
+      description: 'Retrieve an async generation started with `async: true`. Pass the returned `job_id`: while running it reports status "running"; on completion it returns the normal result (image paths / inline images + meta); on failure it raises the recorded error. Jobs belong to your session and expire ~10 min after completion \u2014 if a job id is unknown, check the output dir / <image>.json sidecar.',
       annotations: { readOnlyHint: true, openWorldHint: false },
       inputSchema: {
         job_id: external_exports.string().min(1).describe("The job_id returned by a generation tool called with async: true")
       }
     },
-    async (args) => getJobResult(args.job_id)
+    async (args) => client2.session.jobs.getResult(args.job_id)
   );
 }
 
 // src/index.ts
+await loadStdioDotenv();
 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]
+  tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerVideoTools, registerMusicTools, registerJobTools],
+  deps: client
 });