@chrischall/gemini-mcp 1.0.2 → 1.0.3

package/dist/tools/interact.js

@@ -1,31 +1,17 @@
 import { z } from 'zod';
-import { McpToolError, readEnvVar } from '@chrischall/mcp-utils';
+import { McpToolError, ApiError, readEnvVar } from '@chrischall/mcp-utils';
 import { resolveModel } from '../models.js';
-import { client } from '../client.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 { ChainedRequest404Error } from '../client.js';
+import { slugify, baseName, gatherImageInputs, resolveImagePath, writeSidecar, resolveOutputDir, readImageAsInline } from '../images.js';
+import { findInteractionImages, latestInteractionId } from '../sidecar.js';
+import { emit, ASPECT_RATIOS, IMAGE_SIZES, MODEL_CHOICE_GUIDE, resolveVideoInput, videoPathSchema, timeoutMsSchema, timeoutRiskHint, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { 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".
-let lastInteractionId;
-// Absolute paths of every image this tool has written this session. Used to
-// drop a chained call's re-attached prior output: the interaction state
-// already contains that image, and re-sending it as a fresh reference anchors
-// the model against the requested edit (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();
-}
+// The last-interaction id and the written-outputs set used to live here, at
+// module scope. On the hosted connector that leaks across tenants — one
+// Cloudflare isolate serves many authenticated sessions, so `continue_last`
+// from user B would resume user A's interaction under B's key. Both now live
+// on `client.session` (src/session.ts), one per authenticated session.
 /** 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 " +
@@ -35,7 +21,7 @@ const NEW_REFERENCES_ONLY = 'NEW reference images only (e.g. a style or target p
  * this server itself generated (which the interaction already contains).
  * Unresolvable paths are kept so `gatherImageInputs` surfaces its usual error.
  */
-function splitReattachedOutputs(images) {
+function splitReattachedOutputs(images, writtenOutputs) {
     const kept = [];
     const dropped = [];
     for (const p of images) {
@@ -48,16 +34,29 @@ function splitReattachedOutputs(images) {
     }
     return { kept, dropped };
 }
-export function registerInteractTools(server) {
+export function registerInteractTools(server, client) {
+    // The sidecar/re-anchor half of this description is only true where there is
+    // a filesystem. Describing it anyway on the hosted connector would tell the
+    // model to go looking in an output dir that does not exist — so the
+    // description is built from the sink's capability, not hardcoded.
+    const onDiskRuntime = client.mediaSink?.persistsFiles ?? true;
+    const recoveryDescription = onDiskRuntime
+        ? 'If a call times out on the client side, the generation usually still completes: the image plus a ' +
+            '`<image>.json` sidecar recording its interaction id land in the output dir, and `continue_last: true` ' +
+            'still resumes that interaction — check the output dir before re-issuing (a re-issue is a second billable generation). ' +
+            'If a chained call 404s, this tool re-anchors itself on the prior output image and re-issues un-chained: ' +
+            'success is reported as `chain_recovered` (the chain was the problem, and you get your image anyway); ' +
+            'a second 404 is reported as the interaction id NOT being the cause (check the model id / files uri instead). '
+        : 'This connector has no filesystem: there is no output dir and no `<image>.json` sidecar, so a lost response ' +
+            'cannot be recovered from disk and a 404 on a chained call cannot be re-anchored automatically. Capture the ' +
+            'returned `interaction_id` from every result, and use `async: true` + gemini_get_result for long generations. ';
     server.registerTool('gemini_interact', {
         description: 'Preferred tool for iterative or multi-step refinement of a single image — ' +
             "multi-turn generation/editing via Gemini's Interactions API. " +
             'To refine, capture the returned interaction `id` and pass it as `previous_interaction_id` ' +
             'on the next call — 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). ' +
+            recoveryDescription +
             'Output is JPEG.',
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
@@ -69,7 +68,7 @@ export function registerInteractTools(server) {
             continue_last: z
                 .boolean()
                 .optional()
-                .describe('Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins)'),
+                .describe('Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins). Survives a server restart by falling back to the newest <image>.json sidecar in the output dir.'),
             images: z
                 .array(z.string().min(1))
                 .optional()
@@ -128,19 +127,36 @@ export function registerInteractTools(server) {
             confirm: schemaConfirm,
         },
     }, async (args, extra) => {
+        assertLocalInputsAvailable(client.mediaSink, args);
+        // Every sidecar-backed recovery below reads the output dir off disk. A
+        // sink with no filesystem has none, so those paths are skipped entirely
+        // rather than left to silently read an empty directory.
+        const onDisk = client.mediaSink?.persistsFiles ?? true;
         let previousInteractionId = args.previous_interaction_id;
+        // `continue_last` resumes the in-memory id first, then falls back to the
+        // newest sidecar in the output dir. The in-memory id dies with the server
+        // process, but the interaction itself lives on upstream — without the
+        // sidecar fallback an MCP restart mid-workflow reads as an expired chain
+        // and costs the caller a manual re-anchor for no reason.
+        let continuedFromSidecar = false;
         if (!previousInteractionId && args.continue_last) {
-            if (!lastInteractionId) {
+            previousInteractionId = client.session.lastInteractionId;
+            if (!previousInteractionId && onDisk) {
+                previousInteractionId = await latestInteractionId(resolveOutputDir(args.output_dir));
+                continuedFromSidecar = previousInteractionId !== undefined;
+            }
+            if (!previousInteractionId) {
                 throw new McpToolError('No previous interaction to continue in this session.', {
-                    hint: 'Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id.',
+                    hint: onDisk
+                        ? 'Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id.'
+                        : 'Call gemini_interact once without continue_last first, or pass an explicit previous_interaction_id. (This hosted connector has no filesystem, so there are no <image>.json sidecars to recover an id from across restarts.)',
                 });
             }
-            previousInteractionId = lastInteractionId;
         }
         let images = args.images;
         let dropped = [];
         if (previousInteractionId && images?.length) {
-            ({ kept: images, dropped } = splitReattachedOutputs(images));
+            ({ kept: images, dropped } = splitReattachedOutputs(images, client.session.writtenOutputs));
         }
         // 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
@@ -157,27 +173,78 @@ export function registerInteractTools(server) {
             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 () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_interact', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const inputs = await gatherImageInputs({ images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
-            const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args));
-            const r = await withProgressHeartbeat(extra, 'Generating image (Gemini Interactions API)', () => client.interact({
+            const video = await withProgressHeartbeat(extra, 'Uploading video to the Gemini Files API', () => resolveVideoInput(args, client));
+            const callOpts = {
                 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;
+            };
+            // A 404 on a chained request proves *something* was missing, not that it
+            // was the interaction (the upstream body is generic — see
+            // ChainedRequest404Error). So the recovery doubles as the experiment that
+            // settles it: re-attach that turn's output image — located by id via its
+            // sidecar, never "the newest image", since re-anchoring on the wrong
+            // picture would silently corrupt the edit — and re-issue WITHOUT the
+            // chain. Succeeds → the chain really was the problem, and the caller gets
+            // their image. 404s again → the id was never the cause, and saying so
+            // beats sending them to chase an interaction that was fine all along.
+            // Neither 404 generates anything, so a success costs the one generation
+            // the manual re-anchor would have cost.
+            let chainRecovered;
+            const r = await withProgressHeartbeat(extra, 'Generating image (Gemini Interactions API)', async () => {
+                try {
+                    return await client.interact({ ...callOpts, images: inputs.length ? inputs : undefined, previousInteractionId });
+                }
+                catch (err) {
+                    if (!(err instanceof ChainedRequest404Error))
+                        throw err;
+                    // Re-anchoring needs the prior output image, which only the sidecar
+                    // index can locate — and that index lives on disk.
+                    if (!onDisk)
+                        throw err;
+                    const reanchorOn = await findInteractionImages(resolveOutputDir(args.output_dir), err.previousInteractionId);
+                    if (!reanchorOn.length)
+                        throw err;
+                    const carried = await Promise.all(reanchorOn.map((p) => readImageAsInline(p)));
+                    try {
+                        const probe = await client.interact({ ...callOpts, images: [...carried, ...inputs], previousInteractionId: undefined });
+                        chainRecovered = { expired_interaction_id: err.previousInteractionId, reanchored_on: reanchorOn };
+                        return probe;
+                    }
+                    catch (probeErr) {
+                        if (!(probeErr instanceof ApiError && probeErr.status === 404))
+                            throw probeErr;
+                        throw new McpToolError(
+                        // Remediation goes in the MESSAGE, not just `hint`: MCP error
+                        // serialization surfaces the message and drops the hint, so a
+                        // hint-only fix is invisible exactly when it's needed.
+                        `The interaction id is not the cause of this 404: the same request re-issued WITHOUT previous_interaction_id ("${err.previousInteractionId}") also returned 404. Upstream said: ${probeErr.message}. ` +
+                            `Check that the model id ("${model}") resolves — see gemini_list_models — and that any files/… uri you referenced hasn't expired (~48h TTL). Re-chaining or re-anchoring will not help.`, {
+                            hint: `Check the model id ("${model}") resolves — see gemini_list_models — and that any files/… uri you referenced hasn't expired (~48h TTL). Re-chaining or re-anchoring will not help.`,
+                            cause: probeErr,
+                        });
+                    }
+                }
+            });
+            client.session.lastInteractionId = r.id;
             const meta = { model, interaction_id: r.id };
-            if (previousInteractionId)
+            // On recovery the prior id was NOT used — reporting it as
+            // previous_interaction_id would misrepresent what the model saw.
+            if (chainRecovered)
+                meta.chain_recovered = chainRecovered;
+            else if (previousInteractionId)
                 meta.previous_interaction_id = previousInteractionId;
+            if (continuedFromSidecar)
+                meta.continued_from_sidecar = true;
             if (dropped.length)
                 meta.dropped_previous_output = dropped;
             meta.hint =
@@ -189,7 +256,7 @@ export function registerInteractTools(server) {
                 meta.grounding = r.grounding;
             if (video.videoFileMeta)
                 meta.video_file = video.videoFileMeta;
-            const risk = timeoutRiskHint({ model, imageSize: args.image_size });
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: onDisk });
             if (risk)
                 meta.timeout_risk = risk;
             const slug = args.filename ? baseName(args.filename) : slugify(args.input);
@@ -197,10 +264,12 @@ export function registerInteractTools(server) {
                 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) => {
+            // writeImage returns already-resolved absolute paths. `emit` only
+            // invokes this callback for a filesystem-backed sink, so there is no
+            // branch here claiming a sidecar the hosted connector cannot write.
+            return emit(named, { ...args, sink: client.mediaSink }, meta, async (paths) => {
                 for (const p of paths)
-                    writtenOutputs.add(p);
+                    client.session.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.

package/dist/tools/jobs.js

@@ -1,17 +1,20 @@
 import { z } from 'zod';
-import { getJobResult } from '../jobs.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
  * past a host's tools/call timeout); this tool retrieves that job's status and,
  * once complete, its normal result payload.
  */
-export function registerJobTools(server) {
+// The client is REQUIRED, not decorative: the job registry hangs off it
+// (`client.session.jobs`) so each authenticated connector session polls its own
+// jobs. Reading a module-level registry here would let any session fetch any
+// other session's result by job id — see src/session.ts.
+export function registerJobTools(server, client) {
     server.registerTool('gemini_get_result', {
-        description: 'Retrieve an async generation started with `async: true`. Pass the returned `job_id`: while running it reports status "running"; on completion it returns the normal result (image paths / inline images + meta); on failure it raises the recorded error. Jobs are per-process and expire ~10 min after completion — if a job id is unknown, check the output dir / <image>.json sidecar.',
+        description: 'Retrieve an async generation started with `async: true`. Pass the returned `job_id`: while running it reports status "running"; on completion it returns the normal result (image paths / inline images + meta); on failure it raises the recorded error. Jobs belong to your session and expire ~10 min after completion — if a job id is unknown, check the output dir / <image>.json sidecar.',
         annotations: { readOnlyHint: true, openWorldHint: false },
         inputSchema: {
             job_id: z.string().min(1).describe('The job_id returned by a generation tool called with async: true'),
         },
-    }, async (args) => getJobResult(args.job_id));
+    }, async (args) => client.session.jobs.getResult(args.job_id));
 }

package/dist/tools/models.js

@@ -1,6 +1,5 @@
 import { textResult } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
-export function registerModelTools(server) {
+export function registerModelTools(server, client) {
     server.registerTool('gemini_list_models', {
         description: 'List the Gemini image-generation models available to your API key (Nano Banana / Nano Banana Pro family), and the current default model.',
         annotations: { readOnlyHint: true },

package/dist/tools/music.js

@@ -1,20 +1,20 @@
 import { z } from 'zod';
 import { McpToolError } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
 import { DEFAULT_MUSIC_MODEL } from '../models.js';
-import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat } from './shared.js';
-import { dispatch, fingerprintRequest } from '../jobs.js';
+import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
 const MUSIC_MODELS = ['lyria-3-clip-preview', 'lyria-3-pro-preview'];
 const AUDIO_FORMATS = ['mp3', 'wav'];
 /** WAV is Lyria-3-Pro-only (docs); reject it on the clip model up front. */
 function isProModel(model) { return /pro/i.test(model); }
-// Most-recent music interaction id (this process), for continue_last.
-let lastMusicInteractionId;
-/** Test-only: clear the module-level session memory. */
-export function __resetMusicMemory() { lastMusicInteractionId = undefined; }
-export function registerMusicTools(server) {
+// The most-recent music 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
+// continue_last resume another user's interaction under their own key.
+// See src/session.ts.
+export function registerMusicTools(server, client) {
     server.registerTool('gemini_music_generate', {
         description: 'Generate music from a text prompt (mood, genre, instruments, structure, or lyrics inline) via a Lyria model ' +
             '(preview): lyria-3-clip-preview (~30s clips, default) or lyria-3-pro-preview (longer, WAV-capable). Written to ' +
@@ -39,6 +39,7 @@ export function registerMusicTools(server) {
             confirm: schemaConfirm,
         },
     }, async (args, extra) => {
+        assertLocalInputsAvailable(client.mediaSink, args);
         const model = args.model ?? DEFAULT_MUSIC_MODEL;
         if (args.audio_format === 'wav' && !isProModel(model)) {
             throw new McpToolError(`WAV output requires a Pro model; ${model} only produces MP3.`, {
@@ -47,12 +48,12 @@ export function registerMusicTools(server) {
         }
         let previousInteractionId = args.previous_interaction_id;
         if (!previousInteractionId && args.continue_last) {
-            if (!lastMusicInteractionId) {
+            if (!client.session.lastMusicInteractionId) {
                 throw new McpToolError('No previous music interaction to continue in this session.', {
                     hint: 'Generate music first, or pass an explicit previous_interaction_id.',
                 });
             }
-            previousInteractionId = lastMusicInteractionId;
+            previousInteractionId = client.session.lastMusicInteractionId;
         }
         const gate = await previewLocalInputsUnlessConfirmed(args.confirm, 'Send local image input(s) to the Gemini Lyria API', '/v1beta/interactions', args.images);
         if (gate)
@@ -62,7 +63,7 @@ export function registerMusicTools(server) {
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             previous_interaction_id: previousInteractionId,
         });
-        return dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_music_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
             const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client.generateMusic({
                 input: args.prompt,
@@ -72,7 +73,7 @@ export function registerMusicTools(server) {
                 previousInteractionId,
                 timeoutMs: args.timeout_ms,
             }));
-            lastMusicInteractionId = r.id;
+            client.session.lastMusicInteractionId = r.id;
             const meta = { model, interaction_id: r.id };
             if (previousInteractionId)
                 meta.previous_interaction_id = previousInteractionId;
@@ -84,7 +85,7 @@ export function registerMusicTools(server) {
                 media,
                 base: r.audios.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
             }));
-            return emitMedia(named, 'audio', { inline: args.inline, output_dir: args.output_dir }, meta);
+            return emitMedia(named, 'audio', { inline: args.inline, output_dir: args.output_dir, sink: client.mediaSink }, meta);
         });
     });
 }

package/dist/tools/set.js

@@ -1,12 +1,11 @@
 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 } from '../images.js';
-import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat } from './shared.js';
-import { dispatch, fingerprintRequest } from '../jobs.js';
+import { emit, sharedImageSchema, pickSeed, buildMeta, timeoutRiskHint, withProgressHeartbeat, assertLocalInputsAvailable } from './shared.js';
+import { fingerprintRequest } from '../jobs.js';
 import { previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
-export function registerSetTools(server) {
+export function registerSetTools(server, client) {
     server.registerTool('gemini_image_set', {
         description: 'Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master).',
         annotations: { readOnlyHint: false, openWorldHint: true },
@@ -22,6 +21,7 @@ export function registerSetTools(server) {
             ...sharedImageSchema,
         },
     }, async (args, extra) => {
+        assertLocalInputsAvailable(client.mediaSink, args);
         // `scenes` is min(1) at the schema, so a non-undefined value is non-empty.
         if ((args.scenes && args.count) || (!args.scenes && !args.count)) {
             throw new McpToolError('Provide exactly one of `scenes` or `count`.');
@@ -38,7 +38,7 @@ export function registerSetTools(server) {
             thinking_level: args.thinking_level, google_search: args.google_search,
             master_images: args.master_images, master_images_base64: args.master_images_base64, from_clipboard: args.from_clipboard,
         });
-        return dispatch({ toolName: 'gemini_image_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_image_set', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const seed = pickSeed(args.seed);
             const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
             const slug = args.basename ? baseName(args.basename) : slugify(args.master_prompt);
@@ -81,10 +81,10 @@ export function registerSetTools(server) {
                 meta.grounding = masterResult.grounding;
             // A set is master + N scenes in one tools/call — the most timeout-prone
             // tool. Effective image count drives the risk hint.
-            const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length });
+            const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client.mediaSink?.persistsFiles });
             if (risk)
                 meta.timeout_risk = risk;
-            return emit(named, args, meta);
+            return emit(named, { ...args, sink: client.mediaSink }, meta);
         });
     });
 }

package/dist/tools/shared.js

@@ -1,7 +1,13 @@
 import { z } from 'zod';
 import { textResult, McpToolError, readEnvVar } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
-import { writeMedia, resolveOutputDir, resolveVideoPath, videoMimeType } from '../images.js';
+import { resolveVideoPath, videoMimeType } from '../images.js';
+import { createDiskSink } from '../storage/media.js';
+/**
+ * Fallback sink for call sites that pass no explicit one (every pre-existing
+ * test, and any caller constructed before the sink seam existed). The stdio
+ * server's behaviour is therefore unchanged by omission, not by convention.
+ */
+const DEFAULT_SINK = createDiskSink();
 /** Supported output aspect ratios (Gemini image API). */
 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. */
@@ -80,7 +86,7 @@ export const sharedImageSchema = {
  * The uploaded file (uri + expiry) is echoed via `videoFileMeta` so a caller
  * can pass the uri straight back as `video_url` instead of re-uploading.
  */
-export async function resolveVideoInput(args) {
+export async function resolveVideoInput(args, client) {
     if (args.video_url && args.video_path) {
         throw new McpToolError('Provide `video_url` OR `video_path`, not both.');
     }
@@ -177,6 +183,10 @@ export async function withProgressHeartbeat(extra, message, fn) {
  * `meta.timeout_risk` so a caller that *does* get the result is steered off the
  * slow path next time and knows the image still landed on disk when a host bails.
  * `undefined` for fast configs (no field added).
+ *
+ * `persistsFiles: false` (the hosted connector) swaps the disk-recovery half of
+ * the advice for the async job handle — pointing a Worker's caller at "look in
+ * the output dir" would be advice about a filesystem that does not exist.
  */
 export function timeoutRiskHint(opts) {
     // Delimiter-anchored so real Pro ids (gemini-3-pro-image, nano-banana-pro)
@@ -189,7 +199,14 @@ export function timeoutRiskHint(opts) {
     const why = [proModel && 'Pro model', fourK && '4K output', multi && `count=${opts.count}`]
         .filter(Boolean)
         .join(' + ');
-    return (`Slow config (${why}) can exceed a host's tools/call timeout (e.g. Claude Desktop ~30s, error -32001). ` +
+    const lead = `Slow config (${why}) can exceed a host's tools/call timeout (e.g. Claude Desktop ~30s, error -32001). `;
+    if (opts.persistsFiles === false) {
+        return (lead +
+            `This connector has no filesystem, so a lost response cannot be recovered from disk — there is no output dir and no ` +
+            `<image>.json sidecar. Use \`async: true\` to get a job_id immediately and poll gemini_get_result, ` +
+            `or use a Flash model / drop image_size to 1K/2K for a faster in-band result.`);
+    }
+    return (lead +
         `If the host gives up mid-generation the image is still written to disk (and gemini_interact leaves an ` +
         `<image>.json sidecar with the interaction id) — no rerun needed, just look in the output dir. ` +
         `For a faster in-band result use a Flash model, drop image_size to 1K/2K, or — in Claude Code — set MCP_TOOL_TIMEOUT.`);
@@ -220,14 +237,23 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
         }
         return { content: blocks };
     }
-    const dir = resolveOutputDir(opts.output_dir);
-    const paths = [];
-    for (const n of named)
-        paths.push(await writeMedia(dir, n.base, n.media.base64, n.media.mimeType));
-    await onWritten?.(paths);
+    const sink = opts.sink ?? DEFAULT_SINK;
+    const refs = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
+        output_dir: opts.output_dir,
+    });
+    // `onWritten` (sidecars, the written-outputs set) is meaningful only when the
+    // refs are real files. On a sink with no filesystem there is nothing to sit
+    // next to, so it is skipped rather than handed URLs it would misinterpret.
+    if (sink.persistsFiles)
+        await onWritten?.(refs);
     // Note a downgraded inline-video request so the caller isn't left wondering.
     const note = opts.inline && kind === 'video' ? { inline_unsupported: 'video has no MCP inline content type — written to disk instead' } : {};
-    return textResult({ [`${kind}s`]: paths, ...note, ...meta });
+    // Say where the bytes actually went whenever they are NOT local paths — the
+    // key is the same (`images`/`videos`/`audios`), so without this a caller would
+    // reasonably read a URL as a file path.
+    const storageNote = sink.note();
+    const storage = sink.persistsFiles ? {} : { storage: sink.kind, storage_note: storageNote };
+    return textResult({ [`${kind}s`]: refs, ...note, ...storage, ...meta });
 }
 /**
  * Image convenience wrapper over {@link emitMedia} — preserves the original
@@ -236,3 +262,39 @@ export async function emitMedia(named, kind, opts, meta, onWritten) {
 export async function emit(named, opts, meta, onWritten) {
     return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), 'image', opts, meta, onWritten);
 }
+/**
+ * Inputs that can only come off a local filesystem. On the hosted connector
+ * (a Cloudflare Worker) none of them exist:
+ *
+ *  - `images` / `master_images` — file paths read with `node:fs`.
+ *  - `from_clipboard` — shells out to `osascript`/`sips` via `child_process`.
+ *  - `video_path` — the Files API upload streams the file off disk.
+ *
+ * Called at the top of every generation handler, BEFORE any billable upstream
+ * call, so a caller gets a clear "use images_base64 / video_url instead"
+ * instead of an obscure module-resolution or ENOENT crash. A no-op on the disk
+ * sink, so the stdio behaviour (including its own "Image not found" errors) is
+ * untouched.
+ */
+export function assertLocalInputsAvailable(sink, args) {
+    if ((sink ?? DEFAULT_SINK).persistsFiles)
+        return;
+    const unavailable = [];
+    if (args.images?.length)
+        unavailable.push('`images` (local file paths)');
+    if (args.master_images?.length)
+        unavailable.push('`master_images` (local file paths)');
+    if (args.from_clipboard)
+        unavailable.push('`from_clipboard` (reads the macOS clipboard via child_process)');
+    if (args.video_path)
+        unavailable.push('`video_path` (uploads a file streamed from disk)');
+    if (unavailable.length === 0)
+        return;
+    // Remediation goes in the MESSAGE, not just `hint`: MCP error serialization
+    // surfaces the message and drops the hint, so hint-only advice is invisible
+    // exactly when it is needed.
+    const fix = 'Send image bytes as `images_base64` (raw base64 or a data: URI) instead of `images`/`master_images`/`from_clipboard`, ' +
+        'and reference video by `video_url` (a public YouTube URL, or a files/… uri uploaded elsewhere) instead of `video_path`.';
+    throw new McpToolError(`${unavailable.join(', ')} ${unavailable.length > 1 ? 'are' : 'is'} unavailable on the hosted connector: ` +
+        `it runs on a Cloudflare Worker, which has no filesystem and no local clipboard. ${fix}`, { hint: fix });
+}

package/dist/tools/video.js

@@ -1,20 +1,21 @@
 import { z } from 'zod';
 import { McpToolError } from '@chrischall/mcp-utils';
-import { client } from '../client.js';
 import { slugify, baseName, gatherImageInputs } from '../images.js';
 import { DEFAULT_VIDEO_MODEL } from '../models.js';
-import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat } from './shared.js';
-import { dispatch, fingerprintRequest } from '../jobs.js';
+import { emitMedia, timeoutMsSchema, idempotencyKeySchema, asyncSchema, withProgressHeartbeat, assertLocalInputsAvailable } 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'];
-// Most-recent video interaction id (this process), for continue_last. Separate
-// from the image interact memory — a "last video" and "last image" are distinct.
-let lastVideoInteractionId;
-/** Test-only: clear the module-level session memory. */
-export function __resetVideoMemory() { lastVideoInteractionId = undefined; }
-export function registerVideoTools(server) {
+// 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
+// continue_last resume another user's interaction under their own key. Video is
+// not registered on the Worker today, but the hazard is identical, so it is
+// scoped the same way. It stays separate from the image interact memory: a
+// "last video" and a "last image" are distinct chains. See src/session.ts.
+export function registerVideoTools(server, client) {
     server.registerTool('gemini_video_generate', {
         description: 'Generate a short video via the Gemini omni model (preview): text→video, image→video / reference→video ' +
             '(supply reference image[s]), or edit a prior video (task: "edit" + previous_interaction_id / continue_last). ' +
@@ -43,14 +44,15 @@ export function registerVideoTools(server) {
             confirm: schemaConfirm,
         },
     }, async (args, extra) => {
+        assertLocalInputsAvailable(client.mediaSink, args);
         let previousInteractionId = args.previous_interaction_id;
         if (!previousInteractionId && args.continue_last) {
-            if (!lastVideoInteractionId) {
+            if (!client.session.lastVideoInteractionId) {
                 throw new McpToolError('No previous video interaction to continue in this session.', {
                     hint: 'Generate a video first, or pass an explicit previous_interaction_id.',
                 });
             }
-            previousInteractionId = lastVideoInteractionId;
+            previousInteractionId = client.session.lastVideoInteractionId;
         }
         // Confirm-gate local file inputs (a prompt-injected `images` path could
         // exfiltrate a local file); base64 / clipboard pass through ungated.
@@ -63,7 +65,7 @@ export function registerVideoTools(server) {
             images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard,
             previous_interaction_id: previousInteractionId,
         });
-        return dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+        return client.session.jobs.dispatch({ toolName: 'gemini_video_generate', fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
             const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
             const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client.generateVideo({
                 input: args.prompt,
@@ -74,7 +76,7 @@ export function registerVideoTools(server) {
                 previousInteractionId,
                 timeoutMs: args.timeout_ms,
             }));
-            lastVideoInteractionId = r.id;
+            client.session.lastVideoInteractionId = r.id;
             const meta = { model, interaction_id: r.id };
             if (previousInteractionId)
                 meta.previous_interaction_id = previousInteractionId;
@@ -86,7 +88,7 @@ export function registerVideoTools(server) {
                 media,
                 base: r.videos.length > 1 ? `${slug}-${String(i + 1).padStart(2, '0')}` : slug,
             }));
-            return emitMedia(named, 'video', { output_dir: args.output_dir }, meta);
+            return emitMedia(named, 'video', { output_dir: args.output_dir, sink: client.mediaSink }, meta);
         });
     });
 }

package/dist/version.js

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