@chrischall/gemini-mcp 0.7.2 → 0.9.0

package/dist/bundle.js

@@ -32106,7 +32106,7 @@ var init_server3 = __esm({
 
 // node_modules/@chrischall/mcp-utils/dist/errors/index.js
 function redactSecrets(text) {
-  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(JWT_RE, "[REDACTED]");
+  return text.replace(BEARER_RE, "$1[REDACTED]").replace(BASIC_AUTH_RE, "$1[REDACTED]").replace(SET_COOKIE_RE, "$1$2=[REDACTED]").replace(COOKIE_HEADER_RE, (_m, prefix, pairs) => `${prefix}${pairs.replace(/=[^;,\s]*/g, "=[REDACTED]")}`).replace(API_KEY_RE, "[REDACTED]").replace(QUERY_SECRET_RE, "$1[REDACTED]").replace(AWS_SIGV4_RE, "$1[REDACTED]").replace(JSON_SECRET_DQ_RE, "$1[REDACTED]$2").replace(JSON_SECRET_SQ_RE, "$1[REDACTED]$2").replace(JWT_RE, "[REDACTED]");
 }
 function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
   const str = text === null || text === void 0 ? "" : String(text);
@@ -32115,7 +32115,7 @@ function truncateErrorMessage(text, max = DEFAULT_ERROR_MESSAGE_MAX) {
     return redacted;
   return `${redacted.slice(0, max)}\u2026 [truncated]`;
 }
-var DEFAULT_ERROR_MESSAGE_MAX, McpToolError, BEARER_RE, JWT_RE, BASIC_AUTH_RE, SET_COOKIE_RE, COOKIE_HEADER_RE, API_KEY_RE, QUERY_SECRET_RE;
+var DEFAULT_ERROR_MESSAGE_MAX, McpToolError, BEARER_RE, JWT_RE, BASIC_AUTH_RE, SET_COOKIE_RE, COOKIE_HEADER_RE, API_KEY_RE, QUERY_SECRET_RE, AWS_SIGV4_RE, JSON_SECRET_KEYS, JSON_SECRET_DQ_RE, JSON_SECRET_SQ_RE;
 var init_errors4 = __esm({
   "node_modules/@chrischall/mcp-utils/dist/errors/index.js"() {
     DEFAULT_ERROR_MESSAGE_MAX = 500;
@@ -32150,6 +32150,10 @@ var init_errors4 = __esm({
       // webhook signing secret (Stripe-style)
     ].map((p) => `\\b${p}`).join("|"), "g");
     QUERY_SECRET_RE = /([?&](?:access_token|refresh_token|client_secret|api_?key|signature|token|key|sig)=)[^&#\s"'<>`]+/gi;
+    AWS_SIGV4_RE = /([?&]X-Amz-(?:Signature|Security-Token|Credential)=)[^&#\s"'<>`]+/gi;
+    JSON_SECRET_KEYS = "access_token|refresh_token|client_secret|api_?key|password|passwd|secret|token";
+    JSON_SECRET_DQ_RE = new RegExp(`("(?:${JSON_SECRET_KEYS})"\\s*:\\s*")[^"]*(")`, "gi");
+    JSON_SECRET_SQ_RE = new RegExp(`('(?:${JSON_SECRET_KEYS})'\\s*:\\s*')[^']*(')`, "gi");
   }
 });
 
@@ -32200,6 +32204,13 @@ var init_config = __esm({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/fs/output.js
+var init_output = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/fs/output.js"() {
+    init_config();
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/fs/index.js
 import { openAsBlob } from "node:fs";
 async function fileBlob(path, opts = {}) {
@@ -32216,6 +32227,7 @@ async function fileBlob(path, opts = {}) {
 }
 var init_fs = __esm({
   "node_modules/@chrischall/mcp-utils/dist/fs/index.js"() {
+    init_output();
   }
 });
 
@@ -32225,6 +32237,28 @@ var init_throttle = __esm({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/http/response-cache.js
+var init_response_cache = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/http/response-cache.js"() {
+  }
+});
+
+// node_modules/@chrischall/mcp-utils/dist/http/net-atoms.js
+function parseRetryAfterMs(header, opts = {}) {
+  const defaultMs = opts.defaultMs ?? 2e3;
+  const capMs = opts.capMs ?? 3e4;
+  if (header == null)
+    return defaultMs;
+  const trimmed = header.trim();
+  if (!/^\d+$/.test(trimmed))
+    return defaultMs;
+  return Math.min(Number(trimmed) * 1e3, capMs);
+}
+var init_net_atoms = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/http/net-atoms.js"() {
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/http/index.js
 function hostOf(baseUrl) {
   try {
@@ -32280,7 +32314,11 @@ function createApiClient(opts) {
       const res = await once();
       if (retryStatuses.includes(res.status) && attempt < retry.count) {
         attempt += 1;
-        await sleep(retry.delayMs);
+        const delay = retry.honorRetryAfter ? parseRetryAfterMs(res.headers.get("retry-after"), {
+          defaultMs: retry.delayMs,
+          capMs: retry.maxRetryAfterMs ?? 3e4
+        }) : retry.delayMs;
+        await sleep(delay);
         continue;
       }
       return res;
@@ -32315,7 +32353,26 @@ function createApiClient(opts) {
     }
     return text;
   }
-  return { fetchJson, fetchHtml };
+  async function fetchRaw(method, path, opt = {}) {
+    const headers = { Accept: "*/*", ...opt.headers };
+    const res = await send(method, path, { ...opt, headers });
+    if (res.status === 401)
+      throw unauthorized();
+    if (res.status === 429)
+      throw rateLimited();
+    if (!res.ok) {
+      const text = await res.text().catch(() => "");
+      throw new ApiError(res.status, formatApiError(res.status, method, path, text, { service }));
+    }
+    const bytes = new Uint8Array(await res.arrayBuffer());
+    return {
+      status: res.status,
+      contentType: res.headers.get("content-type"),
+      headers: res.headers,
+      bytes
+    };
+  }
+  return { fetchJson, fetchHtml, fetchRaw };
 }
 function buildQueryString(params) {
   const parts = [];
@@ -32345,6 +32402,9 @@ var init_http = __esm({
   "node_modules/@chrischall/mcp-utils/dist/http/index.js"() {
     init_errors4();
     init_throttle();
+    init_response_cache();
+    init_net_atoms();
+    init_net_atoms();
     DEFAULT_RETRY = { count: 1, delayMs: 2e3 };
     defaultSleep = (ms) => new Promise((r) => setTimeout(r, ms));
     UnauthorizedError = class extends Error {
@@ -32384,9 +32444,16 @@ var init_http = __esm({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/concurrency/single-flight.js
+var init_single_flight = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/concurrency/single-flight.js"() {
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/concurrency/index.js
 var init_concurrency = __esm({
   "node_modules/@chrischall/mcp-utils/dist/concurrency/index.js"() {
+    init_single_flight();
   }
 });
 
@@ -32396,11 +32463,19 @@ var init_dates = __esm({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/zod/parse-lenient.js
+var init_parse_lenient = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/zod/parse-lenient.js"() {
+    init_errors4();
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/zod/index.js
 var PositiveInt, NonNegInt, NonEmptyString, IsoDate, IsoTime, NumericIdString, SafePathSegment, schemaOrigin, schemaConfirm, paginationSchema, pageSchema;
 var init_zod2 = __esm({
   "node_modules/@chrischall/mcp-utils/dist/zod/index.js"() {
     init_zod();
+    init_parse_lenient();
     PositiveInt = external_exports.number().int().positive();
     NonNegInt = external_exports.number().int().nonnegative();
     NonEmptyString = external_exports.string().min(1);
@@ -32421,12 +32496,32 @@ var init_zod2 = __esm({
   }
 });
 
+// node_modules/@chrischall/mcp-utils/dist/auth/cached-token.js
+var init_cached_token = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/auth/cached-token.js"() {
+  }
+});
+
+// node_modules/@chrischall/mcp-utils/dist/auth/es256.js
+var init_es256 = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/auth/es256.js"() {
+  }
+});
+
 // node_modules/@chrischall/mcp-utils/dist/auth/index.js
 var init_auth = __esm({
   "node_modules/@chrischall/mcp-utils/dist/auth/index.js"() {
     init_config();
     init_errors4();
     init_http();
+    init_cached_token();
+    init_es256();
+  }
+});
+
+// node_modules/@chrischall/mcp-utils/dist/scrape/index.js
+var init_scrape = __esm({
+  "node_modules/@chrischall/mcp-utils/dist/scrape/index.js"() {
   }
 });
 
@@ -32443,6 +32538,7 @@ var init_dist = __esm({
     init_dates();
     init_zod2();
     init_auth();
+    init_scrape();
   }
 });
 
@@ -32510,7 +32606,7 @@ var init_clipboard = __esm({
 init_dist();
 
 // src/version.ts
-var VERSION = "0.7.2";
+var VERSION = "0.9.0";
 
 // src/tools/models.ts
 init_dist();
@@ -32540,6 +32636,13 @@ 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 UPLOAD_BASE_URL = "https://generativelanguage.googleapis.com/upload/v1beta";
 var FILE_MAX_BYTES = 2 * 1024 ** 3;
 var FILE_POLL_INTERVAL_MS = 2e3;
@@ -32549,8 +32652,7 @@ var CHAIN_404_RETRY_MS = 2e3;
 var GeminiClient = class {
   apiKey;
   configError;
-  api;
-  interactionsApi;
+  apis = /* @__PURE__ */ new Map();
   fetchImpl;
   sleep;
   constructor(opts = {}) {
@@ -32566,18 +32668,37 @@ var GeminiClient = class {
     }
     this.fetchImpl = opts.fetchImpl ?? fetch;
     this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
-    const shared = {
-      tokenHeader: "x-goog-api-key",
-      getToken: () => this.requireKey(),
-      timeout: REQUEST_TIMEOUT_MS,
-      fetchImpl: this.fetchImpl
-    };
-    this.api = createApiClient({ baseUrl: BASE_URL, serviceName: SERVICE, ...shared });
-    this.interactionsApi = createApiClient({
-      baseUrl: BASE_URL,
-      serviceName: INTERACTIONS_SERVICE,
-      ...shared
-    });
+  }
+  /**
+   * 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 entry;
   }
   requireKey() {
     if (this.configError) throw this.configError;
@@ -32587,8 +32708,9 @@ var GeminiClient = class {
   defaultModel() {
     return resolveModel(void 0, readEnvVar("GEMINI_IMAGE_MODEL"));
   }
-  async call(method, path, body) {
-    return this.api.fetchJson(method, path, body !== void 0 ? { body } : {});
+  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
@@ -32704,7 +32826,8 @@ var GeminiClient = class {
     const data = await this.call(
       "POST",
       `/models/${model}:generateContent`,
-      requestBody
+      requestBody,
+      resolveTimeoutMs(opts.timeoutMs, opts.imageSize)
     );
     const images = [];
     const textParts = [];
@@ -32758,10 +32881,11 @@ var GeminiClient = class {
       if (opts.searchTypes?.length) searchTool.search_types = opts.searchTypes;
       body.tools = [searchTool];
     }
+    const { interactionsApi } = this.apisFor(resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
     let data;
     for (let attempt = 0; ; attempt++) {
       try {
-        data = await this.interactionsApi.fetchJson("POST", "/interactions", {
+        data = await interactionsApi.fetchJson("POST", "/interactions", {
           body
         });
         break;
@@ -32844,7 +32968,7 @@ init_dist();
 
 // src/images.ts
 init_dist();
-import { mkdir, readFile as readFile2, writeFile, access } from "node:fs/promises";
+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) {
@@ -32887,6 +33011,9 @@ async function writeImage(dir, base, base643, 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");
@@ -32930,6 +33057,23 @@ function videoMimeType(p) {
   }
   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);
@@ -32974,6 +33118,15 @@ 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
@@ -32986,7 +33139,10 @@ var sharedImageSchema = {
   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)")
+  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) {
@@ -33005,6 +33161,53 @@ var videoPathSchema = external_exports.string().optional().describe(
 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}`);
+    }
+  }
+  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);
+  }
+}
+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;
@@ -33024,11 +33227,147 @@ async function emit(named, opts, meta3, onWritten) {
   const dir = resolveOutputDir(opts.output_dir);
   const images = [];
   for (const n of named) images.push(await writeImage(dir, n.base, n.image.base64, n.image.mimeType));
-  onWritten?.(images);
+  await onWritten?.(images);
   return textResult({ images, ...meta3 });
 }
 
+// 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);
+  }
+  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);
+  }
+}
+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 = {};
+    }
+    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();
+    }
+  ).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."
+    });
+  }
+  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);
+  }
+  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(
@@ -33044,43 +33383,67 @@ function registerGenerateTools(server) {
         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 (args) => {
+    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 seed = pickSeed(args.seed);
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
-      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 resolveVideoInput(args);
-      const named = [];
-      let capturedText;
-      let capturedGrounding;
-      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
+      const fingerprint = fingerprintRequest("gemini_generate_image", {
+        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 dispatch({ toolName: "gemini_generate_image", 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 { 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;
-      return emit(named, args, meta3);
+        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);
+      });
     }
   );
   server.registerTool(
@@ -33093,35 +33456,54 @@ function registerGenerateTools(server) {
         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) => {
+    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 seed = pickSeed(args.seed);
+      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 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 client.generate({
+      const fingerprint = fingerprintRequest("gemini_edit_image", {
+        model,
         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
+        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_edit_image", 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);
       });
-      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;
-      return emit([{ image: img, base: slug }], args, meta3);
     }
   );
 }
@@ -33143,45 +33525,71 @@ function registerSetTools(server) {
         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) => {
+    async (args, extra) => {
       if (args.scenes && args.count || !args.scenes && !args.count) {
         throw new McpToolError("Provide exactly one of `scenes` or `count`.");
       }
-      const seed = pickSeed(args.seed);
+      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 cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search };
-      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 masterResult = await client.generate({
-        prompt: args.master_prompt,
-        images: masterRefInputs.length > 0 ? masterRefInputs : void 0,
-        seed,
-        ...cfg
+      const fingerprint = fingerprintRequest("gemini_generate_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_generate_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")}` }));
+          }
+          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);
       });
-      const { images: [master], text: masterText } = masterResult;
-      const named = [{ 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")}` }));
-      }
-      const meta3 = buildMeta(model, seed, args);
-      if (masterText) meta3.text = masterText;
-      if (masterResult.grounding) meta3.grounding = masterResult.grounding;
-      return emit(named, args, meta3);
     }
   );
 }
@@ -33209,7 +33617,7 @@ function registerInteractTools(server) {
   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. 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. 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.",
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         input: external_exports.string().min(1).describe("Text prompt or editing instruction"),
@@ -33230,10 +33638,14 @@ function registerInteractTools(server) {
         ),
         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,
-        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,
+        from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
+        confirm: schemaConfirm
       }
     },
-    async (args) => {
+    async (args, extra) => {
       let previousInteractionId = args.previous_interaction_id;
       if (!previousInteractionId && args.continue_last) {
         if (!lastInteractionId) {
@@ -33248,46 +33660,89 @@ function registerInteractTools(server) {
       if (previousInteractionId && images?.length) {
         ({ kept: images, dropped } = splitReattachedOutputs(images));
       }
-      const inputs = await gatherImageInputs({ images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-      const video = await resolveVideoInput(args);
-      const r = await client.interact({
+      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;
+      const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
+      const fingerprint = fingerprintRequest("gemini_interact", {
+        model,
         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
+        aspect_ratio: args.aspect_ratio,
+        image_size: args.image_size,
+        thinking_level: args.thinking_level,
+        previous_interaction_id: previousInteractionId,
+        google_search: args.google_search,
+        search_types: args.search_types,
+        images,
+        images_base64: args.images_base64,
+        from_clipboard: args.from_clipboard,
+        video_url: args.video_url,
+        video_path: args.video_path
       });
-      lastInteractionId = r.id;
-      const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
-      const meta3 = { model, interaction_id: r.id };
-      if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
-      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 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, (paths) => {
-        for (const p of paths) writtenOutputs.add(p);
+      return 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({
+          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;
+        const meta3 = { model, interaction_id: r.id };
+        if (previousInteractionId) meta3.previous_interaction_id = previousInteractionId;
+        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 });
+        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);
+          try {
+            for (const p of paths) await writeSidecar(p, { ...meta3, images: paths });
+          } catch (err) {
+            meta3.sidecar_error = err instanceof Error ? err.message : String(err);
+          }
+        });
       });
     }
   );
 }
 
+// src/tools/jobs.ts
+init_zod();
+function registerJobTools(server) {
+  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.',
+      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)
+  );
+}
+
 // src/index.ts
 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]
+  tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerJobTools]
 });