@chrischall/gemini-mcp 1.7.0 → 1.9.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/generate.js

@@ -3,7 +3,7 @@ import { readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs, requireImageInput } from '../inputs.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt } from './shared.js';
+import { emit, resolveAspectRatio, ASPECT_RATIOS, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, resolveVideoInput, videoPathSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const GENERATE_ENDPOINT = '/v1beta/models/{model}:generateContent';
@@ -46,10 +46,15 @@ export function registerGenerateTools(server, client) {
             return gate;
         const count = args.count ?? 1;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        // Resolve shape BEFORE fingerprinting: `orientation: 'portrait'` and
+        // `aspect_ratio: '9:16'` are the same upstream request, so they must
+        // dedup to the same job rather than billing twice (hence the resolved
+        // ratio in the fingerprint below, and no `orientation` alongside it).
+        const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
         // 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_image_generate', {
-            model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            model, prompt: args.prompt, aspect_ratio: aspectRatio, 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,
             images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
@@ -92,7 +97,7 @@ export function registerGenerateTools(server, client) {
                             prompt,
                             images: refInputs.length > 0 ? refInputs : undefined,
                             model: args.model,
-                            aspectRatio: args.aspect_ratio,
+                            aspectRatio,
                             imageSize: args.image_size,
                             seed: seed + i,
                             thinkingLevel: args.thinking_level,
@@ -116,7 +121,7 @@ export function registerGenerateTools(server, client) {
             });
             if (named.length === 0)
                 throw firstError;
-            const meta = buildMeta(model, seed, args);
+            const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
             if (capturedText)
                 meta.text = capturedText;
             if (capturedGrounding)
@@ -171,8 +176,13 @@ export function registerGenerateTools(server, client) {
         if (gate)
             return gate;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        // Resolve shape BEFORE fingerprinting: `orientation: 'portrait'` and
+        // `aspect_ratio: '9:16'` are the same upstream request, so they must
+        // dedup to the same job rather than billing twice (hence the resolved
+        // ratio in the fingerprint below, and no `orientation` alongside it).
+        const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_image_edit', {
-            model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            model, prompt: args.prompt, aspect_ratio: aspectRatio, 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,
             images_url: args.images_url, images_file_uris: args.images_file_uris, images_r2_keys: args.images_r2_keys,
@@ -189,7 +199,7 @@ export function registerGenerateTools(server, client) {
                 prompt,
                 images: inputs,
                 model: args.model,
-                aspectRatio: args.aspect_ratio,
+                aspectRatio,
                 imageSize: args.image_size,
                 seed,
                 thinkingLevel: args.thinking_level,
@@ -197,7 +207,7 @@ export function registerGenerateTools(server, client) {
                 timeoutMs: args.timeout_ms,
             }));
             const { images: [img], text } = result;
-            const meta = buildMeta(model, seed, args);
+            const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
             if (text)
                 meta.text = text;
             if (result.grounding)

package/dist/tools/interact.js

@@ -5,7 +5,7 @@ import { ChainedRequest404Error } from '../client.js';
 import { slugify, baseName, resolveImagePath, writeSidecar, resolveOutputDir, readImageAsInline } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { findInteractionImages, latestInteractionId } from '../sidecar.js';
-import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emit, resolveAspectRatio, orientationSchema, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 // The last-interaction id and the written-outputs set used to live here, at
@@ -87,7 +87,11 @@ export function registerInteractTools(server, client) {
                 .string()
                 .optional()
                 .describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
-            aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
+            aspect_ratio: z
+                .enum(ASPECT_RATIOS)
+                .optional()
+                .describe('Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.'),
+            orientation: orientationSchema,
             image_size: z
                 .enum(IMAGE_SIZES)
                 .optional()
@@ -173,8 +177,10 @@ export function registerInteractTools(server, client) {
         if (gate)
             return gate;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        // Resolved before the fingerprint so "portrait" and "9:16" are one job.
+        const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_interact', {
-            model, input: args.input, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            model, input: args.input, aspect_ratio: aspectRatio, 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,
@@ -187,7 +193,7 @@ export function registerInteractTools(server, client) {
             const callOpts = {
                 input: args.input,
                 model: args.model,
-                aspectRatio: args.aspect_ratio,
+                aspectRatio,
                 imageSize: args.image_size,
                 thinkingLevel: args.thinking_level,
                 googleSearch: args.google_search,
@@ -215,6 +221,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/set.js

@@ -3,7 +3,7 @@ import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt, persistBundle, SET_URL_TTL_MS } from './shared.js';
+import { emit, resolveAspectRatio, ASPECT_RATIOS, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt, persistBundle, SET_URL_TTL_MS } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 export function registerSetTools(server, client) {
@@ -39,9 +39,14 @@ export function registerSetTools(server, client) {
         if (gate)
             return gate;
         const model = resolveModel(args.model, readEnvVar('GEMINI_IMAGE_MODEL'));
+        // Resolve shape BEFORE fingerprinting: `orientation: 'portrait'` and
+        // `aspect_ratio: '9:16'` are the same upstream request, so they must
+        // dedup to the same job rather than billing twice (hence the resolved
+        // ratio in the fingerprint below, and no `orientation` alongside it).
+        const aspectRatio = resolveAspectRatio(args, ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_image_set', {
             model, master_prompt: args.master_prompt, scenes: args.scenes, count: args.count,
-            reference_mode: args.reference_mode, aspect_ratio: args.aspect_ratio, image_size: args.image_size,
+            reference_mode: args.reference_mode, aspect_ratio: aspectRatio, 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,
             master_images_url: args.master_images_url, master_images_file_uris: args.master_images_file_uris,
@@ -49,7 +54,7 @@ export function registerSetTools(server, client) {
         });
         return client.session.jobs.dispatch({ toolName: 'gemini_image_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, 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 cfg = { model: args.model, aspectRatio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
             const slug = args.basename ? baseName(args.basename) : slugify(args.master_prompt);
             // 1. master (optionally seeded from reference images).
             //
@@ -141,7 +146,7 @@ export function registerSetTools(server, client) {
                 return result;
             });
             const masterText = masterResult.text;
-            const meta = buildMeta(model, seed, args);
+            const meta = buildMeta(model, seed, { ...args, aspect_ratio: aspectRatio });
             if (masterText)
                 meta.text = masterText;
             if (masterResult.grounding)

package/dist/tools/shared.js

@@ -16,6 +16,65 @@ const DEFAULT_SINK = createDiskSink();
 export const 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'];
 /** Supported output resolutions. `512` is Flash-only (0.5K); `1K`/`2K`/`4K` work on all image models. */
 export const IMAGE_SIZES = ['512', '1K', '2K', '4K'];
+/**
+ * The words people actually use for shape, as a shorthand over
+ * {@link ASPECT_RATIOS}.
+ *
+ * Landscape and portrait output was always *possible* — every generation tool
+ * has taken `aspect_ratio` since the beginning. But that parameter is a
+ * 14-value enum described as "Output aspect ratio", with nothing linking
+ * "portrait" to `9:16`, so a request phrased the way a person phrases it did
+ * not reliably reach the API. A capability that cannot be addressed is, from
+ * the caller's side, a missing one.
+ */
+export const ORIENTATIONS = ['landscape', 'portrait', 'square'];
+/**
+ * One mapping, deliberately shared by images and video.
+ *
+ * `16:9`/`9:16` rather than a photo ratio like `3:2` so that "portrait" means
+ * the same shape whatever is being generated — omni offers only these two, and
+ * an orientation that silently meant something different per tool would be a
+ * worse shorthand than no shorthand. Anyone wanting 35mm or print proportions
+ * still names the ratio outright, which always wins (see
+ * {@link resolveAspectRatio}).
+ */
+const ORIENTATION_RATIO = {
+    landscape: '16:9',
+    portrait: '9:16',
+    square: '1:1',
+};
+/**
+ * Settle `aspect_ratio` and `orientation` into the one value sent upstream.
+ *
+ * An explicit ratio wins: it is the more specific request, and a caller who
+ * named `21:9` while also saying "landscape" meant `21:9`. `supported` is the
+ * calling tool's own enum — the image tools accept all of
+ * {@link ASPECT_RATIOS}, omni accepts two — and an orientation outside it is
+ * REFUSED rather than rounded to the nearest shape. Quietly substituting
+ * `16:9` for an unsupported `square` would hand back a picture the caller
+ * never asked for and give them no way to tell it had been swapped.
+ */
+export function resolveAspectRatio(opts, supported) {
+    if (opts.aspect_ratio)
+        return opts.aspect_ratio;
+    if (!opts.orientation)
+        return undefined;
+    const ratio = ORIENTATION_RATIO[opts.orientation];
+    if (!supported.includes(ratio)) {
+        // Remediation belongs in the MESSAGE — the host drops `hint`.
+        throw new McpToolError(`orientation "${opts.orientation}" (${ratio}) is not available for this model, which supports ${supported.join(' and ')}. ` +
+            `Ask for ${supported.map((r) => `"${r}"`).join(' or ')} via aspect_ratio, or choose another orientation.`, { hint: `Supported aspect ratios: ${supported.join(', ')}.` });
+    }
+    return ratio;
+}
+/** The `orientation` parameter, worded so the shorthand is discoverable. */
+export const orientationSchema = z
+    .enum(ORIENTATIONS)
+    .optional()
+    .describe('Shape of the output, in plain terms: "landscape" (wide, 16:9), "portrait" (tall, 9:16) or "square" (1:1). ' +
+    'Use this for a request phrased as landscape/portrait/vertical/horizontal. For any other proportion — ' +
+    '35mm photo (3:2), print (4:3), social (4:5), cinematic (21:9) — name it with aspect_ratio instead, ' +
+    'which overrides this when both are given.');
 /**
  * When to pick which Nano Banana model — shared by every tool's `model` param
  * so the guidance can't drift between them.
@@ -228,7 +287,11 @@ export const sharedImageSchema = {
         .regex(/^[\w.-]+$/, 'must be a bare model id (letters, digits, ".", "_", "-")')
         .optional()
         .describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
-    aspect_ratio: z.enum(ASPECT_RATIOS).optional().describe('Output aspect ratio'),
+    aspect_ratio: z
+        .enum(ASPECT_RATIOS)
+        .optional()
+        .describe('Exact output aspect ratio. For a plain landscape/portrait/square request, `orientation` is the shorthand; this wins if both are given.'),
+    orientation: orientationSchema,
     image_size: z.enum(IMAGE_SIZES).optional().describe('Output resolution (512 = 0.5K, Flash-only)'),
     output_dir: z.string().optional().describe('Directory to write images to (default: $GEMINI_OUTPUT_DIR or cwd)'),
     inline: z.boolean().optional().describe('Return base64 images inline instead of writing to disk'),
@@ -384,8 +447,12 @@ export function timeoutRiskHint(opts) {
 /** Build the result metadata echoed to the caller (omitting unset optionals). */
 export function buildMeta(model, seed, opts) {
     const meta = { model, seed };
+    // The RESOLVED ratio, and the orientation only when one was asked for — so a
+    // caller who said "portrait" can see both what they asked and what it became.
     if (opts.aspect_ratio)
         meta.aspect_ratio = opts.aspect_ratio;
+    if (opts.orientation)
+        meta.orientation = opts.orientation;
     if (opts.image_size)
         meta.image_size = opts.image_size;
     return meta;

package/dist/tools/video.js

@@ -3,12 +3,17 @@ import { McpToolError } from '@chrischall/mcp-utils';
 import { slugify, baseName } from '../images.js';
 import { resolveImageInputs } from '../inputs.js';
 import { DEFAULT_VIDEO_MODEL } from '../models.js';
-import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
+import { emitMedia, resolveAspectRatio, orientationSchema, timeoutMsSchema, idempotencyKeySchema, asyncSchema, maxWaitMsSchema, withProgressHeartbeat, assertLocalInputsAvailable, imagesUrlSchema, imagesFileUrisSchema } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 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
@@ -25,7 +30,8 @@ export function registerVideoTools(server, client) {
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             prompt: z.string().min(1).describe('Description of the video to generate (or the edit instruction when task=edit)'),
-            aspect_ratio: z.enum(VIDEO_ASPECT_RATIOS).optional().describe('Output aspect ratio (omni: 16:9 or 9:16)'),
+            aspect_ratio: z.enum(VIDEO_ASPECT_RATIOS).optional().describe('Exact output aspect ratio (omni: 16:9 or 9:16). `orientation` is the plain-language shorthand; this wins if both are given.'),
+            orientation: orientationSchema,
             task: z.enum(VIDEO_TASKS).optional().describe('text_to_video (default), image_to_video / reference_to_video (need image input), or edit (needs previous_interaction_id)'),
             images: z.array(z.string().min(1)).optional().describe('Reference image path(s) for image_to_video / reference_to_video'),
             images_url: imagesUrlSchema('Reference stills'),
@@ -39,6 +45,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,
@@ -64,22 +72,32 @@ export function registerVideoTools(server, client) {
         if (gate)
             return gate;
         const model = args.model?.trim() || DEFAULT_VIDEO_MODEL;
+        // omni has no square, so `orientation: 'square'` is refused here rather
+        // than rounded to 16:9 — see resolveAspectRatio. Resolved before the
+        // fingerprint so "portrait" and "9:16" dedup to one billable job.
+        const aspectRatio = resolveAspectRatio(args, VIDEO_ASPECT_RATIOS);
         const fingerprint = fingerprintRequest('gemini_video_generate', {
-            model, prompt: args.prompt, aspect_ratio: args.aspect_ratio, task: args.task,
+            model, prompt: args.prompt, aspect_ratio: aspectRatio, task: args.task,
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             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,
                 images: inputs.length ? inputs : undefined,
                 model: args.model,
-                aspectRatio: args.aspect_ratio,
+                aspectRatio,
                 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.9.0'; // x-release-please-version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chrischall/gemini-mcp",
-  "version": "1.7.0",
+  "version": "1.9.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>",
@@ -45,7 +45,7 @@
     "typecheck": "tsc -p tsconfig.test.json"
   },
   "dependencies": {
-    "@chrischall/mcp-utils": "^0.14.0",
+    "@chrischall/mcp-utils": "^0.15.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "dotenv": "^17.4.0",
     "zod": "^4.4.2"