@chrischall/gemini-mcp 0.7.2 → 0.9.0

package/dist/client.js

@@ -8,8 +8,24 @@ const BASE_URL = 'https://generativelanguage.googleapis.com/v1beta'; // v1 lacks
 const SERVICE = 'Gemini';
 const INTERACTIONS_SERVICE = 'Gemini Interactions';
 // Per-request abort budget. Image generation routinely runs 30s+ on the Pro
-// model, so this is deliberately 60s (NOT the fleet's usual 15–30s).
+// model, so this is deliberately 60s (NOT the fleet's usual 15–30s) — and 4K
+// output routinely runs past 60s, hence the doubled 4K default. Both are
+// overridable: per-call `timeout_ms` beats $GEMINI_TIMEOUT_MS beats these.
 const REQUEST_TIMEOUT_MS = 60_000;
+const REQUEST_TIMEOUT_4K_MS = 120_000;
+/**
+ * Effective upstream timeout for one request:
+ * per-call `timeout_ms` → `$GEMINI_TIMEOUT_MS` → 120s for 4K output → 60s.
+ * Resolved at request time so an env change doesn't require a new process.
+ */
+export function resolveTimeoutMs(perCallMs, imageSize) {
+    if (perCallMs !== undefined && 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;
+}
 // Files API (local-video upload — docs/GEMINI-API.md "Files API — local video
 // upload", verified 2026-06-12). The resumable upload endpoint lives under
 // `/upload/v1beta`, NOT the normal `/v1beta` base.
@@ -31,8 +47,7 @@ const CHAIN_404_RETRY_MS = 2_000;
 export class GeminiClient {
     apiKey;
     configError;
-    api;
-    interactionsApi;
+    apis = new Map();
     fetchImpl;
     sleep;
     constructor(opts = {}) {
@@ -47,30 +62,39 @@ export class GeminiClient {
             this.apiKey = key;
             this.configError = null;
         }
-        // Both paths share: the key in the `x-goog-api-key` header (Gemini does not
-        // use `Authorization: Bearer`), a 60s abort budget, 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.
         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 });
-        // 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.
-        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)
@@ -81,8 +105,9 @@ export class GeminiClient {
     defaultModel() {
         return resolveModel(undefined, readEnvVar('GEMINI_IMAGE_MODEL'));
     }
-    async call(method, path, body) {
-        return this.api.fetchJson(method, path, body !== undefined ? { body } : {});
+    async call(method, path, body, timeoutMs) {
+        const { api } = this.apisFor(timeoutMs ?? resolveTimeoutMs());
+        return api.fetchJson(method, path, body !== undefined ? { body } : {});
     }
     /**
      * Upload a local video to the Gemini Files API (resumable protocol) and wait
@@ -200,7 +225,7 @@ export class GeminiClient {
         const requestBody = { contents: [{ parts }], generationConfig };
         if (opts.googleSearch)
             requestBody.tools = [{ google_search: {} }];
-        const data = await this.call('POST', `/models/${model}:generateContent`, requestBody);
+        const data = await this.call('POST', `/models/${model}:generateContent`, requestBody, resolveTimeoutMs(opts.timeoutMs, opts.imageSize));
         const images = [];
         const textParts = [];
         let groundingMeta;
@@ -263,10 +288,11 @@ export class GeminiClient {
                 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;

package/dist/images.js

@@ -1,4 +1,4 @@
-import { mkdir, readFile, writeFile, access } from 'node:fs/promises';
+import { mkdir, readFile, writeFile, access, stat, open } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import { join, resolve, isAbsolute } from 'node:path';
 import { readEnvVar, McpToolError } from '@chrischall/mcp-utils';
@@ -57,6 +57,16 @@ export async function writeImage(dir, base, base64, mimeType) {
     await writeFile(path, Buffer.from(base64, 'base64'));
     return resolve(path);
 }
+/**
+ * Write `<imagePath>.json` recording generation metadata (notably the
+ * interaction id) next to a written image. The MCP host's tools/call timeout
+ * can expire while the server-side generation finishes anyway — the response
+ * (and its interaction id) is then lost, but this sidecar survives, so the
+ * multi-turn chain is recoverable from disk.
+ */
+export async function writeSidecar(imagePath, data) {
+    await writeFile(`${imagePath}.json`, JSON.stringify(data, null, 2));
+}
 /**
  * Resolve an input file path, checking (in order):
  *  1. Absolute path that exists → returned as-is.
@@ -116,6 +126,37 @@ export function videoMimeType(p) {
     }
     return mime;
 }
+/**
+ * Preview a local IMAGE input WITHOUT sending it anywhere: resolve the path to
+ * an absolute one, sniff its mime from the leading bytes, and measure its size.
+ * Reads the file locally (to sniff/measure) but makes NO network/API call — so a
+ * prompt-injected `image_path` (e.g. a local secret) is visible before upload.
+ */
+export async function previewImageInput(path) {
+    const resolved = resolveImagePath(path);
+    // Read only the header bytes needed to sniff the MIME (≤12), and take the size
+    // from stat() — a dry-run must not load a large reference image into memory
+    // just to report it (matches previewVideoInput).
+    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();
+    }
+}
+/**
+ * Preview a local VIDEO input WITHOUT uploading it: resolve the path, derive its
+ * mime from the extension, and measure its size. Makes NO network/API call.
+ */
+export async function previewVideoInput(path) {
+    const resolved = resolveVideoPath(path);
+    const { size } = await stat(resolved);
+    return { path: resolved, mimeType: videoMimeType(resolved), size };
+}
 /** Read an image file into `{ base64, mimeType }` for an inline_data part. */
 export async function readImageAsInline(path) {
     const resolved = resolveImagePath(path);

package/dist/index.js

@@ -5,6 +5,7 @@ import { registerModelTools } from './tools/models.js';
 import { registerGenerateTools } from './tools/generate.js';
 import { registerSetTools } from './tools/set.js';
 import { registerInteractTools } from './tools/interact.js';
+import { registerJobTools } from './tools/jobs.js';
 // The GeminiClient is a module-level singleton (imported by each tool module)
 // that defers its config error to the first request — so the server boots and
 // answers the host's install-time tools/list probe even without GEMINI_API_KEY.
@@ -12,5 +13,5 @@ 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],
 });

package/dist/tools/_confirm.js

@@ -0,0 +1,39 @@
+import { schemaConfirm, textResult } from '@chrischall/mcp-utils';
+import { previewImageInput, previewVideoInput } from '../images.js';
+export { schemaConfirm };
+/**
+ * Confirm-gate for a mutating tool (the fleet convention). When `confirm` is not
+ * `true`, returns a no-network dry-run preview of exactly what would be sent;
+ * when it is `true`, returns `null` so the caller proceeds with the write.
+ */
+export function previewUnlessConfirmed(confirm, action, method, path, body) {
+    if (confirm === true)
+        return null;
+    return textResult({
+        dryRun: true,
+        action,
+        method,
+        path,
+        ...(body !== undefined ? { willSend: body } : {}),
+        note: 'Re-run with confirm: true to execute.',
+    });
+}
+/**
+ * Confirm-gate for a Gemini tool that ships LOCAL input files (image/video
+ * paths) to Google. Returns `null` (proceed) when `confirm === true` OR the call
+ * has no local file inputs — so pure text-to-image / base64 / clipboard calls
+ * are unaffected. Otherwise returns a NO-API dry-run echoing each RESOLVED
+ * ABSOLUTE input path plus its mime and size, so a prompt-injected path (e.g.
+ * `~/.ssh/id_rsa`) is visible and interceptable before any byte leaves the box.
+ */
+export 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 });
+}

package/dist/tools/generate.js

@@ -3,7 +3,11 @@ import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, resolveVideoInput, videoPathSchema } from './shared.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat } from './shared.js';
+import { dispatch, fingerprintRequest } from '../jobs.js';
+import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
+const GENERATE_ENDPOINT = '/v1beta/models/{model}:generateContent';
+const SEND_LOCAL_ACTION = 'Send local file input(s) to the Gemini API';
 // generateContent output can't seed an Interactions-API conversation, so
 // results point follow-up edits at gemini_interact instead of an id.
 const REFINE_HINT = 'To iteratively refine this image, use gemini_interact (pass the output file via `images` on the first call, ' +
@@ -21,53 +25,76 @@ export function registerGenerateTools(server) {
             images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs'),
             video_url: z.string().url().optional().describe('Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
             video_path: videoPathSchema,
+            confirm: schemaConfirm,
             ...sharedImageSchema,
         },
-    }, async (args) => {
+    }, async (args, extra) => {
+        // Confirm-gate local file inputs: a prompt-injected `images`/`video_path`
+        // could exfiltrate a local file. Pure text-to-image calls (no local input)
+        // are unaffected. Dry-run makes NO API call.
+        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) : slugify(args.prompt);
-        const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        // Upload ONCE (before the count loop) — every generate call references
-        // the same files/… uri.
-        const video = await resolveVideoInput(args);
-        const named = [];
-        let capturedText;
-        // For count>1, surface the FIRST call's grounding (each call grounds
-        // independently; one representative set of sources beats concatenating N).
-        let capturedGrounding;
-        for (let i = 0; i < count; i++) {
-            // Distinct seed per image (seed+0 for the single-image case == echoed seed)
-            // so count>1 yields N *different* images, not N duplicates.
-            const result = await client.generate({
-                prompt: args.prompt,
-                images: refInputs.length > 0 ? refInputs : undefined,
-                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,
+        // Fingerprint the request identity (excl. server-picked seed / output path)
+        // so a blind re-issue after a host timeout dedups instead of re-billing.
+        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) : slugify(args.prompt);
+            const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+            // Upload ONCE (before the count loop) — every generate call references
+            // the same files/… uri.
+            const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args));
+            const named = [];
+            let capturedText;
+            // For count>1, surface the FIRST call's grounding (each call grounds
+            // independently; one representative set of sources beats concatenating N).
+            let capturedGrounding;
+            await withProgressHeartbeat(extra, `Generating ${count > 1 ? `${count} images` : 'image'} (${model})`, async () => {
+                for (let i = 0; i < count; i++) {
+                    // Distinct seed per image (seed+0 for the single-image case == echoed seed)
+                    // so count>1 yields N *different* images, not N duplicates.
+                    const result = await client.generate({
+                        prompt: args.prompt,
+                        images: refInputs.length > 0 ? refInputs : undefined,
+                        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 meta = buildMeta(model, seed, args);
-        if (capturedText)
-            meta.text = capturedText;
-        if (capturedGrounding)
-            meta.grounding = capturedGrounding;
-        if (video.videoFileMeta)
-            meta.video_file = video.videoFileMeta;
-        meta.hint = REFINE_HINT;
-        return emit(named, args, meta);
+            const meta = buildMeta(model, seed, args);
+            if (capturedText)
+                meta.text = capturedText;
+            if (capturedGrounding)
+                meta.grounding = capturedGrounding;
+            if (video.videoFileMeta)
+                meta.video_file = video.videoFileMeta;
+            meta.hint = REFINE_HINT;
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size, count });
+            if (risk)
+                meta.timeout_risk = risk;
+            return emit(named, args, meta);
+        });
     });
     server.registerTool('gemini_edit_image', {
         description: 'Edit or compose images: provide one or more input images (paths or base64), plus a text instruction. ' +
@@ -80,35 +107,52 @@ export function registerGenerateTools(server) {
             images: z.array(z.string().min(1)).optional().describe('Paths to input image file(s) (1 = edit, 2+ = compose)'),
             images_base64: z.array(z.string().min(1)).optional().describe('Input images as base64 strings or data URIs'),
             filename: z.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);
+        // Confirm-gate local file inputs (see gemini_generate_image). base64 /
+        // clipboard inputs are not local-path reads and pass through ungated.
+        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) : slugify(args.prompt);
-        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-        const result = await 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,
+        const fingerprint = fingerprintRequest('gemini_edit_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,
+            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) : slugify(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 meta = buildMeta(model, seed, args);
+            if (text)
+                meta.text = text;
+            if (result.grounding)
+                meta.grounding = result.grounding;
+            meta.hint = REFINE_HINT;
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+            if (risk)
+                meta.timeout_risk = risk;
+            return emit([{ image: img, base: slug }], args, meta);
         });
-        const { images: [img], text } = result;
-        const meta = buildMeta(model, seed, args);
-        if (text)
-            meta.text = text;
-        if (result.grounding)
-            meta.grounding = result.grounding;
-        meta.hint = REFINE_HINT;
-        return emit([{ image: img, base: slug }], args, meta);
     });
 }

package/dist/tools/interact.js

@@ -2,8 +2,10 @@ import { z } from 'zod';
 import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { client } from '../client.js';
-import { slugify, baseName, gatherImageInputs, resolveImagePath } from '../images.js';
-import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema } from './shared.js';
+import { slugify, baseName, gatherImageInputs, resolveImagePath, writeSidecar } from '../images.js';
+import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, withProgressHeartbeat } from './shared.js';
+import { dispatch, fingerprintRequest } from '../jobs.js';
+import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 // The most recent interaction id this server process created — what
 // `continue_last: true` resumes. In-memory only: an MCP server lives for the
 // host session, so "last" means "last in this session".
@@ -14,6 +16,16 @@ let lastInteractionId;
 // the model against the requested edit (observed in the wild — callers pass
 // the last result path back via `images` despite the description saying not to).
 const writtenOutputs = new Set();
+/**
+ * Test-only: clear the module-level session memory (`lastInteractionId` and the
+ * written-outputs set) so tests that assert the "no prior interaction" path are
+ * order-independent — they can't rely on module-load state once other tests have
+ * run first (e.g. under `--sequence.shuffle`).
+ */
+export function __resetInteractSessionForTest() {
+    lastInteractionId = undefined;
+    writtenOutputs.clear();
+}
 /** Shared warning for the reference-image params. */
 const 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 — the interaction already contains it, and re-sending it " +
@@ -43,6 +55,9 @@ export function registerInteractTools(server) {
             'To refine, capture the returned interaction `id` and pass it as `previous_interaction_id` ' +
             'on the next call — 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 — check the output dir before re-issuing (a re-issue is a second billable generation). ' +
             'Output is JPEG.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
@@ -103,12 +118,16 @@ export function registerInteractTools(server) {
                 .optional()
                 .describe('Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
             video_path: videoPathSchema,
+            timeout_ms: timeoutMsSchema,
+            idempotency_key: idempotencyKeySchema,
+            async: asyncSchema,
             from_clipboard: z
                 .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) {
@@ -123,44 +142,76 @@ export 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({
-            input: args.input,
-            images: inputs.length ? inputs : undefined,
-            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,
-        });
-        lastInteractionId = r.id;
+        // Confirm-gate local file inputs AFTER the re-attach split, so the preview
+        // reflects the paths actually sent (dropped prior-output paths aren't). A
+        // prompt-injected `images`/`video_path` could exfiltrate a local file;
+        // base64/clipboard inputs pass through ungated. Dry-run makes NO API call.
+        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 meta = { model, interaction_id: r.id };
-        if (previousInteractionId)
-            meta.previous_interaction_id = previousInteractionId;
-        if (dropped.length)
-            meta.dropped_previous_output = dropped;
-        meta.hint =
-            `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) — ` +
-                'do NOT re-attach the returned image as an input; the interaction already contains it.';
-        if (r.text)
-            meta.text = r.text;
-        if (r.grounding)
-            meta.grounding = r.grounding;
-        if (video.videoFileMeta)
-            meta.video_file = video.videoFileMeta;
-        const slug = args.filename ? baseName(args.filename) : slugify(args.input);
-        const named = r.images.map((image, i) => ({
-            image,
-            base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
-        }));
-        // writeImage returns already-resolved absolute paths.
-        return emit(named, args, meta, (paths) => { for (const p of paths)
-            writtenOutputs.add(p); });
+        const fingerprint = fingerprintRequest('gemini_interact', {
+            model, input: args.input, 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,
+        });
+        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 : undefined,
+                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 meta = { model, interaction_id: r.id };
+            if (previousInteractionId)
+                meta.previous_interaction_id = previousInteractionId;
+            if (dropped.length)
+                meta.dropped_previous_output = dropped;
+            meta.hint =
+                `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) — ` +
+                    'do NOT re-attach the returned image as an input; the interaction already contains it.';
+            if (r.text)
+                meta.text = r.text;
+            if (r.grounding)
+                meta.grounding = r.grounding;
+            if (video.videoFileMeta)
+                meta.video_file = video.videoFileMeta;
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+            if (risk)
+                meta.timeout_risk = risk;
+            const slug = args.filename ? baseName(args.filename) : slugify(args.input);
+            const named = r.images.map((image, i) => ({
+                image,
+                base: r.images.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
+            }));
+            // writeImage returns already-resolved absolute paths.
+            return emit(named, args, meta, async (paths) => {
+                for (const p of paths)
+                    writtenOutputs.add(p);
+                // Sidecar per image so the interaction id survives a lost MCP response
+                // (host timeout). Best-effort: the image is already on disk and the id
+                // is in the result — a sidecar failure shouldn't fail the call.
+                try {
+                    for (const p of paths)
+                        await writeSidecar(p, { ...meta, images: paths });
+                }
+                catch (err) {
+                    meta.sidecar_error = err instanceof Error ? err.message : String(err);
+                }
+            });
+        });
     });
 }