@chrischall/gemini-mcp 1.7.0 → 1.8.0

package/dist/jobs.js

@@ -294,6 +294,7 @@ export class JobRegistry {
             status: entry.status,
             createdAt: entry.createdAt,
             updatedAt,
+            ...(entry.interactionId !== undefined ? { interactionId: entry.interactionId } : {}),
             ...(entry.error ? { error: entry.error } : {}),
             ...(entry.status === 'done' && entry.result ? persistableResult(entry.result) : {}),
         };
@@ -405,8 +406,31 @@ export class JobRegistry {
         }
         const jobId = randomUUID();
         this.evict(now);
-        const promise = work();
-        const entry = { jobId, toolName, fingerprint, idempotencyKey, status: 'running', promise, createdAt: now };
+        // The work starts before `entry` can exist (the entry holds its promise),
+        // yet a well-behaved job reports its interaction id in its very first
+        // `await` — synchronously, from here's point of view. Dropping that report
+        // would lose exactly the ids that arrive fastest, so it is held until the
+        // entry is there and folded into the record's first write.
+        let entry;
+        let earlyInteractionId;
+        const ctx = {
+            reportInteraction: (interactionId) => {
+                if (!entry) {
+                    earlyInteractionId = interactionId;
+                    return;
+                }
+                if (entry.interactionId === interactionId)
+                    return;
+                entry.interactionId = interactionId;
+                if (this.store)
+                    this.track(this.writeRecord(entry));
+            },
+        };
+        const promise = work(ctx);
+        entry = {
+            jobId, toolName, fingerprint, idempotencyKey, status: 'running', promise, createdAt: now,
+            ...(earlyInteractionId !== undefined ? { interactionId: earlyInteractionId } : {}),
+        };
         this.jobs.set(jobId, entry);
         if (idempotencyKey !== undefined)
             this.byKey.set(idempotencyKey, jobId);
@@ -483,6 +507,51 @@ export class JobRegistry {
      * the unknown-id path — the poll tool cannot be used to read another user's
      * result even if they know the uuid.
      */
+    /**
+     * The durable record for `jobId`, if there is one — including the
+     * executor-lost rewrite. Read-only view for a caller that wants to act on a
+     * record's contents (see `tools/jobs.ts` recovering an interaction id) rather
+     * than just render it.
+     */
+    async peekRecord(jobId) {
+        return this.store ? await this.store.get(jobId) : undefined;
+    }
+    /**
+     * Adopt a result produced OUTSIDE this registry — recovery reading a lost
+     * job's output back off the upstream interaction (`tools/jobs.ts`).
+     *
+     * Without this the job stays `failed` and every later poll re-enters
+     * recovery: another interaction fetch, another media download, and another
+     * copy on disk (`…-2.mp4`, `…-3.mp4`) or in R2, with nothing telling the
+     * caller they are duplicates. The ordinary done path is idempotent, so this
+     * one has to be too.
+     */
+    async adoptResult(jobId, toolName, result, interactionId) {
+        const now = this.now();
+        let entry = this.jobs.get(jobId);
+        if (!entry) {
+            // A different child ran the job, so there is nothing in memory to update.
+            // The synthetic entry exists only to render the record and to answer the
+            // next poll from this session; its fingerprint is namespaced so it can
+            // never collide with (or dedup against) a real request identity.
+            entry = {
+                jobId,
+                toolName,
+                fingerprint: `recovered:${jobId}`,
+                status: 'done',
+                promise: Promise.resolve(result),
+                createdAt: now,
+            };
+            this.jobs.set(jobId, entry);
+        }
+        entry.status = 'done';
+        entry.result = result;
+        entry.settledAt = now;
+        if (interactionId !== undefined)
+            entry.interactionId = interactionId;
+        if (this.store)
+            await this.writeRecord(entry);
+    }
     async getResult(jobId) {
         const entry = this.jobs.get(jobId);
         if (!entry) {

package/dist/tools/interact.js

@@ -215,6 +215,15 @@ export function registerInteractTools(server, client) {
                 catch (err) {
                     if (!(err instanceof ChainedRequest404Error))
                         throw err;
+                    // The client already asked: if the interaction is ALIVE, the 404 was
+                    // about something else (the model id, an expired files/… uri), and
+                    // re-anchoring would bill a second generation to answer a question
+                    // that is already answered — while silently dropping the
+                    // conversation context, returning a plausible image the model built
+                    // without the prior turn. Only probe when the chain is gone or the
+                    // probe itself could not be completed.
+                    if (err.chainExists === true)
+                        throw err;
                     // Re-anchoring needs the prior output image, which only the sidecar
                     // index can locate — and that index lives on disk.
                     if (!onDisk)

package/dist/tools/jobs.js

@@ -1,4 +1,8 @@
 import { z } from 'zod';
+import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { TERMINAL_INTERACTION_STATUSES } from '../client.js';
+import { emitMedia } from './shared.js';
+import { slugify } from '../images.js';
 /**
  * Poll tool for the async generation pattern (issue #52). A generation tool
  * called with `async: true` returns a `job_id` immediately (instead of blocking
@@ -15,10 +19,131 @@ export function registerJobTools(server, client) {
             'while running it reports status "running"; on completion it returns the normal result (image URLs/paths + meta); ' +
             'on failure it raises the recorded error, including the case where the generation was killed before it finished. ' +
             'On the hosted connector job records are stored durably and survive a restart; on a local stdio server they live ' +
-            'with the process and expire ~10 min after completion, where the output dir / <image>.json sidecar is the fallback.',
-        annotations: { readOnlyHint: true, openWorldHint: false },
+            'with the process and expire ~10 min after completion, where the output dir / <image>.json sidecar is the fallback. ' +
+            'A killed video/music job started with `background: true` is recovered from its upstream interaction when it finished there.',
+        // NOT read-only any more: recovering a killed job writes the media it
+        // pulls back, exactly as the generation tool would have.
+        annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             job_id: z.string().min(1).describe('The job_id returned by a generation tool called with async: true'),
+            output_dir: z.string().optional().describe('Where to write media recovered from a killed job (default: $GEMINI_OUTPUT_DIR or cwd)'),
         },
-    }, async (args) => client.session.jobs.getResult(args.job_id));
+    }, async (args) => {
+        try {
+            return await client.session.jobs.getResult(args.job_id);
+        }
+        catch (err) {
+            // The interesting failure is "your executor died mid-generation". If
+            // that job had reported an upstream interaction id, the generation
+            // itself may well have finished on Google's side — the machine
+            // stopping killed the *waiting*, not the work.
+            const recovered = await recoverFromInteraction(client, args.job_id, args.output_dir, err);
+            if (recovered)
+                return recovered;
+            throw err;
+        }
+    });
+}
+/**
+ * Try to answer a failed poll from the upstream interaction instead.
+ *
+ * Returns `undefined` when there is nothing to recover from — no record, no id,
+ * or an interaction that cannot be read — leaving the original (accurate)
+ * error to stand. Recovery must never convert a real loss into a false success,
+ * so every path that does not produce media falls through.
+ */
+async function recoverFromInteraction(client, jobId, outputDir, original) {
+    const record = await client.session.jobs.peekRecord(jobId);
+    const interactionId = record?.interactionId;
+    if (!interactionId || record?.status !== 'failed')
+        return undefined;
+    let found;
+    try {
+        found = await client.fetchInteractionMedia(interactionId);
+    }
+    catch (probeErr) {
+        // A 403 (and a 404, the store lag) means the work is STILL RUNNING — that
+        // is what a GET of an in-flight interaction answers, verified live:
+        // t+20s 403, t+40s completed with the clip. Reporting "unrecoverable"
+        // there is the worst wrong answer available, because the caller re-pays
+        // for a generation that was about to land.
+        if (isInFlight(probeErr))
+            return stillRunning(jobId, interactionId);
+        // Anything else: a backgrounded interaction can settle into a permanent
+        // 400 and never become retrievable. Say so on top of the real error rather
+        // than pretending the output is somewhere.
+        throw new McpToolError(`${errorMessage(original)} Its upstream interaction "${interactionId}" could not be read either (${errorMessage(probeErr)}), so the output is not recoverable.`, { hint: 'Any media the lost run did write is still listed by gemini_list_recent_media. Otherwise the generation has to be re-run.' });
+    }
+    const [kind, media] = found.videos.length
+        ? ['video', found.videos]
+        : found.audios.length
+            ? ['audio', found.audios]
+            : found.images.length
+                ? ['image', found.images]
+                : ['image', []];
+    if (media.length === 0) {
+        // Still running upstream is a genuinely different answer from lost: the
+        // caller should poll again, not re-pay. But a TERMINAL status with no media
+        // (failed, cancelled, …) is not that — telling someone to poll again would
+        // loop them forever on a generation that is never going to arrive, so the
+        // real error stands.
+        if (found.status && !TERMINAL_INTERACTION_STATUSES.has(found.status))
+            return stillRunning(jobId, interactionId);
+        return undefined;
+    }
+    const slug = slugify(`recovered-${interactionId}`.slice(0, 60));
+    const named = media.map((m, i) => ({
+        media: m,
+        base: media.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
+    }));
+    const result = await emitMedia(named, kind, { output_dir: outputDir, sink: client.mediaSink }, {
+        job_id: jobId,
+        recovered_from_interaction: interactionId,
+        note: recoveryNote(record.error?.message),
+        ...(found.text ? { text: found.text } : {}),
+    });
+    // Settle the job with what we just recovered. Otherwise it stays `failed`
+    // and the next poll re-fetches the interaction, re-downloads the media and
+    // writes another copy — the ordinary done path is idempotent, so this one
+    // has to be too.
+    await client.session.jobs.adoptResult(jobId, record.toolName, result, interactionId);
+    return result;
+}
+/**
+ * Why this job needed recovering — only claimed when it is known.
+ *
+ * Recovery fires for any failed job that got as far as an interaction id, and
+ * that is broader than "the machine stopped": a backgrounded call whose own
+ * wait expired, or a sync call that failed after the POST returned, both land
+ * here with a perfectly healthy executor. `job-store.ts` is the only thing that
+ * writes the executor-lost message, so it is the only thing that licenses the
+ * executor-lost sentence. The two facts that hold on every path — not re-run,
+ * not billed twice — are stated either way.
+ */
+function recoveryNote(recordedError) {
+    const cause = /was lost:/.test(recordedError ?? '')
+        ? 'The executor that started this job was reclaimed before it could return.'
+        : 'This job failed here before it could return its output.';
+    return `${cause} The generation had already completed upstream and its output was recovered — it was not re-run, and you were not billed twice.`;
+}
+/** The generation outlived its executor and is not finished yet. */
+function stillRunning(jobId, interactionId) {
+    return textResult({
+        job_id: jobId,
+        status: 'running',
+        interaction_id: interactionId,
+        note: 'The executor that started this job is gone, but the generation is still running upstream. Poll again — it has not been lost, and re-running it would bill a second time.',
+    });
+}
+/**
+ * Does this probe failure mean "still working"? 403 is what a GET of an
+ * in-flight background interaction returns (verified live), and 404 is the
+ * interactions store's eventual consistency.
+ */
+function isInFlight(err) {
+    const status = err?.status;
+    return status === 403 || status === 404;
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
 }

package/dist/tools/music.js

@@ -36,6 +36,7 @@ export function registerMusicTools(server, client) {
             inline: z.boolean().optional().describe('Return base64 audio inline instead of writing to disk'),
             previous_interaction_id: z.string().optional().describe('Interaction id to continue from'),
             continue_last: z.boolean().optional().describe('Continue from the most recent music interaction this server created (explicit previous_interaction_id wins)'),
+            background: z.boolean().optional().describe('Run the generation on Google\'s side and poll it, so a killed job can be recovered by gemini_get_result. Off by default — see gemini_video_generate'),
             timeout_ms: timeoutMsSchema,
             idempotency_key: idempotencyKeySchema,
             async: asyncSchema,
@@ -68,7 +69,7 @@ export function registerMusicTools(server, client) {
             images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {
             const { inputs, report } = await resolveImageInputs(args, client);
             const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client.generateMusic({
                 input: args.prompt,
@@ -77,6 +78,9 @@ export function registerMusicTools(server, client) {
                 audioFormat: args.audio_format,
                 previousInteractionId,
                 timeoutMs: args.timeout_ms,
+                background: args.background,
+                // See gemini_video_generate: the id is what survives the executor.
+                onInteractionStarted: ctx.reportInteraction,
             }));
             client.session.lastMusicInteractionId = r.id;
             const meta = { model, interaction_id: r.id };

package/dist/tools/video.js

@@ -9,6 +9,11 @@ import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js'
 /** omni's own aspect-ratio enum — NOT the image tools' ASPECT_RATIOS. */
 const VIDEO_ASPECT_RATIOS = ['16:9', '9:16'];
 const VIDEO_TASKS = ['text_to_video', 'image_to_video', 'reference_to_video', 'edit'];
+// `delivery` is transport, not content: uri hands back a Files API link the
+// client downloads with the api key, inline returns base64 capped at ~4MB.
+// Left unset here so the client's verified default (uri) applies; this is an
+// escape hatch for a video model that rejects delivery outright.
+const VIDEO_DELIVERY = ['inline', 'uri'];
 // The most-recent video interaction id (for continue_last) lives on
 // `client.session`, NOT at module scope — one Cloudflare isolate serves many
 // authenticated connector sessions, so a module-level id would let one user's
@@ -39,6 +44,8 @@ export function registerVideoTools(server, client) {
                 .regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")')
                 .optional()
                 .describe(`Model id override (default: ${DEFAULT_VIDEO_MODEL})`),
+            delivery: z.enum(VIDEO_DELIVERY).optional().describe('How the clip comes back: "uri" (default — a Files API link the server downloads, no size ceiling) or "inline" (base64, capped ~4MB)'),
+            background: z.boolean().optional().describe('Run the generation on Google\'s side and poll it, so a killed job can be recovered by gemini_get_result. Trade-off: retrieving a backgrounded interaction is unreliable today (some become permanently unreadable), so the default is off'),
             previous_interaction_id: z.string().optional().describe('Interaction id to edit/continue (with task: "edit")'),
             continue_last: z.boolean().optional().describe('Continue from the most recent video interaction this server created (explicit previous_interaction_id wins)'),
             timeout_ms: timeoutMsSchema,
@@ -70,7 +77,7 @@ export function registerVideoTools(server, client) {
             images_url: args.images_url, images_file_uris: args.images_file_uris,
             previous_interaction_id: previousInteractionId,
         });
-        return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async (ctx) => {
             const { inputs, report } = await resolveImageInputs(args, client);
             const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client.generateVideo({
                 input: args.prompt,
@@ -80,6 +87,12 @@ export function registerVideoTools(server, client) {
                 task: args.task,
                 previousInteractionId,
                 timeoutMs: args.timeout_ms,
+                delivery: args.delivery,
+                background: args.background,
+                // Hand the id to the job record the moment it exists: if this
+                // machine stops mid-generation, that id is the only route back to
+                // an output that finishes upstream anyway.
+                onInteractionStarted: ctx.reportInteraction,
             }));
             client.session.lastVideoInteractionId = r.id;
             const meta = { model, interaction_id: r.id };

package/dist/version.js

@@ -1,2 +1,2 @@
 /** Single source of the server version. release-please bumps the literal below. */
-export const VERSION = '1.7.0'; // x-release-please-version
+export const VERSION = '1.8.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "mcpName": "io.github.chrischall/gemini-mcp",
   "description": "Gemini image-generation MCP server for Claude — developed and maintained by AI (Claude Code)",
   "author": "Claude Code (AI) <https://www.anthropic.com/claude>",

package/server.json

@@ -6,12 +6,12 @@
     "url": "https://github.com/chrischall/gemini-mcp",
     "source": "github"
   },
-  "version": "1.7.0",
+  "version": "1.8.0",
   "packages": [
     {
       "registryType": "npm",
       "identifier": "@chrischall/gemini-mcp",
-      "version": "1.7.0",
+      "version": "1.8.0",
       "transport": {
         "type": "stdio"
       },