@chrischall/gemini-mcp 1.12.0 → 1.14.0

package/dist/storage/media.js

@@ -2,7 +2,8 @@
  * Where generated media goes.
  *
  * The stdio server writes images/video/audio to the local filesystem. The
- * hosted connector (a Cloudflare Worker) has **no filesystem at all** — no
+ * hosted connector runs on a remote machine with **no access to the caller's
+ * filesystem** — no
  * `writeFile`, no output dir, and therefore no `<image>.json` sidecar — so it
  * puts objects into an R2 bucket and hands back URLs instead of paths.
  *
@@ -49,8 +50,13 @@ const KEY_PREFIX_DEFAULT = 'gen';
  * How many listing pages one `listRecent` call will walk. A listing walk is
  * unbounded work and this runs on a tool call, so it is capped — and the cap
  * is REPORTED (see `listRecentPage`) rather than silently truncating.
+ *
+ * Doubled when sidecar records joined the same prefix: each generation now
+ * occupies two objects, so the old budget reached half as many of them.
+ * Reporting `truncated` sooner is not free — it is what sends someone to re-pay
+ * for an image that is sitting right there.
  */
-const MAX_LIST_PAGES = 10;
+const MAX_LIST_PAGES = 20;
 /**
  * Split a stored key back into the day it was written and the name it was asked
  * for — the inverse of the key format `persist` builds.
@@ -78,6 +84,48 @@ export function safeKeySegment(base) {
         .replace(/^[-.]+|[-.]+$/g, '');
     return cleaned || 'media';
 }
+/**
+ * Suffixes that turn a media key into its sidecar's key. Beside the object, not
+ * under a prefix of its own, so one retention sweep covers both.
+ *
+ * TWO of them, because only some records can answer "what do I chain from".
+ * `gemini_interact`, video and music produce an interaction id; a plain
+ * `gemini_image_generate` produces a prompt and nothing to resume. Splitting
+ * them by KEY is what lets a lookup skip the ones that can never match without
+ * opening them — forty ordinary generations used to bury the chain and make
+ * continue_last come back empty. Both end in `.json`, so one check still keeps
+ * records out of a media listing.
+ */
+const SIDECAR_SUFFIX = '.json';
+const CHAIN_SIDECAR_SUFFIX = '.chain.json';
+/**
+ * How many sidecar records a lookup will READ before giving up.
+ *
+ * Deliberately small, and the reason both lookups walk lazily rather than
+ * reusing the listing: a record is a separate object, so "scan the last 200"
+ * means 200 store round trips on a tool call. Newest-first, stopping at the
+ * first match, the common case is one read — the chain being re-anchored is
+ * almost always the previous turn. Only a miss pays the full budget, and a miss
+ * is the error path.
+ */
+const MAX_SIDECAR_READS = 40;
+/** Longest prompt a sidecar keeps. Enough to recognise, not to reproduce. */
+const SIDECAR_PROMPT_MAX = 500;
+/** How many record reads a single listing will have open at once. */
+const DECORATE_CONCURRENCY = 8;
+/** `Promise.all` with a ceiling on how many run at once, preserving order. */
+async function mapLimit(items, limit, fn) {
+    const out = new Array(items.length);
+    let next = 0;
+    const workers = Array.from({ length: Math.min(limit, items.length) }, async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await fn(items[i]);
+        }
+    });
+    await Promise.all(workers);
+    return out;
+}
 /**
  * The hosted-connector sink: one R2 object per generated item.
  *
@@ -133,45 +181,54 @@ export function createR2Sink(bucket, opts) {
         async listRecentPage({ limit = 20, sinceDay } = {}) {
             if (!bucket.list)
                 return { media: [], truncated: false, scannedPages: 0 };
-            // Scoped at the STORE, not filtered afterwards: asking only for our own
-            // prefix means another account's keys are never in hand to leak by a
-            // filtering mistake.
-            const prefix = await ownPrefix();
-            const found = [];
-            let cursor;
-            let truncated = false;
-            let scannedPages = 0;
-            // Bounded: a listing walk is unbounded work, and this runs on a tool call.
-            for (let page = 0; page < MAX_LIST_PAGES; page++) {
-                scannedPages = page + 1;
-                const listed = await bucket.list({ prefix, cursor, limit: 1000 });
-                for (const obj of listed.objects) {
-                    const parsed = parseMediaKey(obj.key, prefix);
-                    if (!parsed)
-                        continue; // not a dated object key — skip, never throw
-                    if (sinceDay && parsed.day < sinceDay)
-                        continue;
-                    found.push({ ...parsed, key: obj.key, ...(obj.size !== undefined ? { sizeBytes: obj.size } : {}) });
-                }
-                if (!listed.truncated || !listed.cursor)
-                    break;
-                cursor = listed.cursor;
-                // Ran out of budget with more to read: the answer is a subset, and
-                // must say so rather than passing for the whole picture.
-                if (page === MAX_LIST_PAGES - 1)
-                    truncated = true;
+            const { entries, sidecarKeys, truncated, scannedPages } = await walk({ sinceDay });
+            const page = entries.slice(0, limit);
+            // Records are read for the RETURNED page only, never the whole walk: one
+            // per entry is one store round trip, and a listing of twenty must not
+            // become a listing of every object stored this month.
+            const media = await decorate(page, sidecarKeys);
+            return { media, truncated: truncated || entries.length > limit, scannedPages };
+        },
+        /**
+         * `<mediaKey>.json` (or `.chain.json`), deliberately beside the object
+         * rather than under a prefix of its own: the retention sweep that removes
+         * the image removes its record with it, so a sidecar can never outlive the
+         * thing it describes. `walk()` is what keeps records out of a media
+         * listing — it skips any key ending in the suffix BEFORE parsing, because
+         * `parseMediaKey` would happily parse one into a valid-looking entry.
+         */
+        async writeSidecar(key, record) {
+            try {
+                if (!(await owned(key)))
+                    return;
+                const suffix = record.interaction_id ? CHAIN_SIDECAR_SUFFIX : SIDECAR_SUFFIX;
+                const body = new TextEncoder().encode(JSON.stringify({
+                    ...record,
+                    // Capped: a record exists to identify a generation later, not to
+                    // store the brief. An 8k prompt would put more bytes in metadata than
+                    // some images have, on every single object.
+                    ...(record.prompt ? { prompt: record.prompt.slice(0, SIDECAR_PROMPT_MAX) } : {}),
+                    created: now().toISOString(),
+                }));
+                await bucket.put(`${key}${suffix}`, body, { httpMetadata: { contentType: 'application/json' } });
             }
-            // Keys sort lexicographically by day, and the id after it is random, so
-            // ordering is by day — which is the honest grain: the store records no
-            // per-object timestamp we could do better with.
-            found.sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : a.key < b.key ? 1 : -1));
-            const page = found.slice(0, limit);
-            const expiresAtMs = now().getTime() + ttlMs;
-            const media = await Promise.all(page.map(async (entry) => {
-                const link = await describe(entry.key, expiresAtMs);
-                return { ...entry, ...(link.unavailable ? {} : { url: link.ref, expiresAt: link.expiresAt }) };
-            }));
-            return { media, truncated: truncated || found.length > limit, scannedPages };
+            catch {
+                // Best-effort by design: the generation is the job, and a record that
+                // fails to write must not fail the image it describes.
+            }
+        },
+        async latestInteractionId(kind) {
+            return newestInteractionId(kind);
+        },
+        async findByInteraction(interactionId) {
+            const wanted = interactionId.trim();
+            if (!wanted)
+                return undefined;
+            const hit = await scanSidecars((record) => record.interaction_id === wanted);
+            // The record the scan already read is passed straight through: re-reading
+            // it to decorate the entry would spend a second round trip on an object
+            // we are holding.
+            return hit ? (await decorate([hit.entry], undefined, hit.record))[0] : undefined;
         },
         async resign(key) {
             if (!(await owned(key)))
@@ -202,14 +259,180 @@ export function createR2Sink(bucket, opts) {
         },
         note: () => publicBase
             ? 'Generated media was uploaded to R2 and the values above are public URLs (not local file paths) — open or download them directly. ' +
-                'This hosted connector has no filesystem, so `output_dir` is ignored and no <image>.json sidecar is written — capture interaction_id from this result to chain further turns.'
+                'This connector has no filesystem, so `output_dir` is ignored — but the interaction id is recorded beside each image, so continue_last and chain recovery still work.'
             : signedBase
                 ? 'Generated media is served by this connector at the signed URLs above — open them in a browser or fetch them with curl; no auth header is needed, the signature is in the link. ' +
                     'They expire (see media[].expires_at), and the objects behind them are cleaned up on a retention schedule. ' +
-                    'This hosted connector has no filesystem, so `output_dir` is ignored and no <image>.json sidecar is written — capture interaction_id from this result to chain further turns.'
+                    'This connector has no filesystem, so `output_dir` is ignored — but the interaction id is recorded beside each image, so continue_last and chain recovery still work.'
                 : 'Generated media was stored, but this connector has no public media URL configured and no signing route available, so the values above are bare object keys rather than fetchable links. ' +
                     'Set MEDIA_PUBLIC_BASE_URL on the Worker, or pass inline: true to receive the bytes directly.',
     };
+    /**
+     * List this account's objects, newest-first, splitting media from the sidecar
+     * records that sit beside them. No record is READ here — that is per-object
+     * work, and both callers want only a slice of it.
+     */
+    async function walk({ sinceDay }) {
+        // A put-only bucket is a supported shape. Answering empty lets the CALLER
+        // raise its own actionable error; asserting `bucket.list!` here threw a
+        // TypeError out of the sink instead.
+        if (!bucket.list)
+            return { entries: [], sidecarKeys: new Set(), truncated: false, scannedPages: 0 };
+        // Scoped at the STORE, not filtered afterwards: asking only for our own
+        // prefix means another account's keys are never in hand to leak by a
+        // filtering mistake.
+        const prefix = await ownPrefix();
+        const found = [];
+        const sidecarKeys = new Set();
+        let cursor;
+        let truncated = false;
+        let scannedPages = 0;
+        // Bounded: a listing walk is unbounded work, and this runs on a tool call.
+        for (let page = 0; page < MAX_LIST_PAGES; page++) {
+            scannedPages = page + 1;
+            const listed = await bucket.list({ prefix, cursor, limit: 1000 });
+            for (const obj of listed.objects) {
+                // A sidecar shares its media's key plus a suffix, so it lands in this
+                // same listing. It is metadata, not a generation: offering one as
+                // "recent media" would hand back a JSON blob to look at.
+                if (obj.key.endsWith(SIDECAR_SUFFIX)) {
+                    sidecarKeys.add(obj.key);
+                    continue;
+                }
+                const parsed = parseMediaKey(obj.key, prefix);
+                if (!parsed)
+                    continue; // not a dated object key — skip, never throw
+                if (sinceDay && parsed.day < sinceDay)
+                    continue;
+                found.push({ ...parsed, key: obj.key, ...(obj.size !== undefined ? { sizeBytes: obj.size } : {}) });
+            }
+            if (!listed.truncated || !listed.cursor)
+                break;
+            cursor = listed.cursor;
+            // Ran out of budget with more to read: the answer is a subset, and must
+            // say so rather than passing for the whole picture.
+            if (page === MAX_LIST_PAGES - 1)
+                truncated = true;
+        }
+        // Keys sort lexicographically by day, and the id after it is random, so
+        // ordering is by day — which is the honest grain: the store records no
+        // per-object timestamp we could do better with.
+        found.sort((a, b) => (a.day < b.day ? 1 : a.day > b.day ? -1 : a.key < b.key ? 1 : -1));
+        return { entries: found, sidecarKeys, truncated, scannedPages };
+    }
+    /**
+     * Attach a fresh link, and the sidecar record where one exists.
+     *
+     * `known` short-circuits the read for a caller that is already holding the
+     * record (see findByInteraction).
+     */
+    async function decorate(entries, sidecarKeys, known) {
+        const expiresAtMs = now().getTime() + ttlMs;
+        // Batched, not one Promise.all over the page: a listing of a hundred fired
+        // a hundred concurrent store reads while the id lookups were carefully
+        // budgeted. One tool call should not open a hundred connections to
+        // decorate a page.
+        return mapLimit(entries, DECORATE_CONCURRENCY, async (entry) => {
+            const link = await describe(entry.key, expiresAtMs);
+            // Only where the walk actually saw a record — media with none (anything
+            // generated before sidecars existed, and anything whose write failed)
+            // keeps its place and simply carries no metadata.
+            const has = sidecarKeys
+                ? sidecarKeys.has(`${entry.key}${CHAIN_SIDECAR_SUFFIX}`) || sidecarKeys.has(`${entry.key}${SIDECAR_SUFFIX}`)
+                : true;
+            const record = known ?? (has ? await readSidecar(entry.key, sidecarKeys) : undefined);
+            return {
+                ...entry,
+                ...(link.unavailable ? {} : { url: link.ref, expiresAt: link.expiresAt }),
+                ...(record?.interaction_id ? { interactionId: record.interaction_id } : {}),
+                ...(record?.prompt ? { prompt: record.prompt } : {}),
+                ...(record?.model ? { model: record.model } : {}),
+                ...(record?.created ? { createdAt: record.created } : {}),
+            };
+        });
+    }
+    /**
+     * Walk stored objects newest-first, reading at most {@link MAX_SIDECAR_READS}
+     * records, and stop at the first one the predicate accepts.
+     *
+     * Lazy on purpose. Reusing the listing would read every record on the page to
+     * answer a question that is nearly always settled by the first — a chain
+     * being re-anchored is the previous turn.
+     */
+    async function scanSidecars(accept) {
+        const { entries, sidecarKeys } = await walk({});
+        let reads = 0;
+        for (const entry of entries) {
+            // Chain records only: a prompt-only record cannot answer this, and
+            // reading it to find that out is what the budget was being spent on.
+            if (!sidecarKeys.has(`${entry.key}${CHAIN_SIDECAR_SUFFIX}`))
+                continue;
+            if (++reads > MAX_SIDECAR_READS)
+                return undefined;
+            const record = await readSidecar(entry.key);
+            if (record?.interaction_id && accept(record))
+                return { entry, record };
+        }
+        return undefined;
+    }
+    /**
+     * The most recent interaction id of a given kind, by the record's OWN
+     * timestamp.
+     *
+     * Key order cannot answer this. Keys sort by day and then by a random id, so
+     * within a day the order is arbitrary — reading "the newest" off it hands
+     * `continue_last` a turn from earlier in the session and silently resumes the
+     * wrong chain. So the newest DAY's records are read (bounded like every other
+     * scan) and compared on `created`.
+     *
+     * A day whose records are all of another kind falls through to the day
+     * before, rather than answering "none": an image chain does not end because
+     * the last thing generated was a video.
+     */
+    async function newestInteractionId(kind) {
+        const { entries, sidecarKeys } = await walk({});
+        let reads = 0;
+        let best;
+        let bestDay;
+        for (const entry of entries) {
+            // Entries are day-descending, so once a day has produced a match every
+            // later entry is older and cannot beat it.
+            if (bestDay && entry.day < bestDay)
+                break;
+            if (!sidecarKeys.has(`${entry.key}${CHAIN_SIDECAR_SUFFIX}`))
+                continue;
+            if (++reads > MAX_SIDECAR_READS)
+                break;
+            const record = await readSidecar(entry.key);
+            if (!record?.interaction_id || (record.kind ?? 'image') !== kind)
+                continue;
+            // A record written before `created` existed sorts oldest rather than
+            // winning on an empty string comparison.
+            const created = record.created ?? '';
+            if (!best || created > best.created)
+                best = { created, id: record.interaction_id };
+            bestDay = entry.day;
+        }
+        return best?.id;
+    }
+    /**
+     * A stored object's sidecar record, or undefined — never a throw. Prefers the
+     * chain record: an object has one or the other, never both.
+     */
+    async function readSidecar(key, sidecarKeys) {
+        const suffix = !sidecarKeys || sidecarKeys.has(`${key}${CHAIN_SIDECAR_SUFFIX}`) ? CHAIN_SIDECAR_SUFFIX : SIDECAR_SUFFIX;
+        try {
+            const obj = await bucket.get?.(`${key}${suffix}`);
+            if (!obj)
+                return undefined;
+            return JSON.parse(new TextDecoder().decode(new Uint8Array(await obj.arrayBuffer())));
+        }
+        catch {
+            // A malformed or unreadable record is the same as none: this decorates a
+            // listing, and a listing that throws is worse than one without prompts.
+            return undefined;
+        }
+    }
     /** One stored object → the ref the caller sees, plus its key and expiry. */
     async function describe(key, expiresAtMs) {
         // A bucket served directly (r2.dev or a custom domain) needs no signature.

package/dist/tools/_confirm.js

@@ -1,4 +1,4 @@
-import { schemaConfirm, textResult } from '@chrischall/mcp-utils';
+import { minifiedResult, schemaConfirm } from '@chrischall/mcp-utils';
 import { previewImageInput, previewVideoInput } from '../images.js';
 export { schemaConfirm };
 /**
@@ -9,7 +9,7 @@ export { schemaConfirm };
 export function previewUnlessConfirmed(confirm, action, method, path, body) {
     if (confirm === true)
         return null;
-    return textResult({
+    return minifiedResult({
         dryRun: true,
         action,
         method,

package/dist/tools/files.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
-import { McpToolError, textResult } from '@chrischall/mcp-utils';
+import { McpToolError, minifiedResult } from '@chrischall/mcp-utils';
 import { withProgressHeartbeat } from './shared.js';
-import { base64ToBytes, wholeMb } from '../bytes.js';
+import { base64ToBytes, bytesToBase64, formatMb, wholeMb } from '../bytes.js';
 import { fileNameFromUrl } from '../fetch-image.js';
 import { downloadFilename } from '../media-name.js';
 import { previewUnlessConfirmed, previewLocalInputsUnlessConfirmed, schemaConfirm } from './_confirm.js';
@@ -17,8 +17,8 @@ import { previewUnlessConfirmed, previewLocalInputsUnlessConfirmed, schemaConfir
  * Three ways in, none of which put bytes in the conversation:
  *
  *  - `gemini_upload_file` with `url` — the SERVER downloads it.
- *  - `POST /upload` on the connector with the raw bytes as the request body —
- *    the intended path for an agent with a shell (see README).
+ *  - `gemini_get_upload_url` → a signed PUT → `gemini_upload_file` with the
+ *    returned `r2_key` — the intended path for a caller with a shell.
  *  - `gemini_upload_file` with `path` — stdio only, reads the local file.
  *
  * `data_base64` exists as a deliberate last resort: it is the one form that
@@ -36,8 +36,8 @@ import { previewUnlessConfirmed, previewLocalInputsUnlessConfirmed, schemaConfir
  * one. A Cloudflare isolate gets 128MB total, hence the much lower hosted
  * figure; Node has no comparable ceiling.
  *
- * `POST /upload` is unaffected: it streams, and is bounded only by the Files
- * API's own 2 GB cap.
+ * The signed-PUT route is unaffected: those bytes go straight to the object
+ * store and are bounded only by the Files API's own 2 GB cap when forwarded.
  */
 const UPLOAD_URL_MAX_BYTES_DISK = 100 * 1024 * 1024;
 const UPLOAD_URL_MAX_BYTES_HOSTED = 25 * 1024 * 1024;
@@ -47,7 +47,7 @@ const RETENTION_NOTE = 'Gemini retains uploaded files for ~48h. Until then this
     '(images_file_uris on gemini_image_generate / _edit / _set / gemini_interact, or video_url) without re-sending the bytes.';
 /** Shape returned by every upload path. */
 function uploadResult(file) {
-    return textResult({
+    return minifiedResult({
         // The `files/<id>` form is what every tool parameter documents, so it leads.
         file_uri: file.name,
         // The absolute uri, for callers that would rather pass it through verbatim.
@@ -60,6 +60,16 @@ function uploadResult(file) {
         hint: `Pass "${file.name}" in images_file_uris (or video_url for video) on any image tool. ${RETENTION_NOTE}`,
     });
 }
+/**
+ * Ceiling on an inline view.
+ *
+ * Not a model limit — an image block is tokenized as an image, and a 1K render
+ * costs about a thousand tokens however many bytes it arrived as. This is the
+ * TRANSPORT: a host that caps tool-result size rejects or truncates an
+ * oversized payload, and a truncated image block reads as a broken tool rather
+ * than a big picture. 8MB clears any render this server produces at 1K or 2K.
+ */
+const VIEW_MAX_BYTES = 8 * 1024 * 1024;
 export function registerFileTools(server, client) {
     const onDisk = client.mediaSink?.persistsFiles ?? true;
     const urlMaxBytes = onDisk ? UPLOAD_URL_MAX_BYTES_DISK : UPLOAD_URL_MAX_BYTES_HOSTED;
@@ -76,8 +86,8 @@ export function registerFileTools(server, client) {
                 : ', or `r2_key` (re-upload media this connector generated, from media[].r2_key in an earlier result).') +
             (onDisk
                 ? ''
-                : ' This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header ' +
-                    'and a Content-Type of image/*, which avoids base64 entirely.'),
+                : ' To upload a local file without base64: mint a signed PUT URL with gemini_get_upload_url, PUT the bytes to it, ' +
+                    'then pass the returned r2_key here.'),
         annotations: { readOnlyHint: false, openWorldHint: true },
         inputSchema: {
             url: z
@@ -86,7 +96,7 @@ export function registerFileTools(server, client) {
                 .optional()
                 .describe(`Public https URL the SERVER downloads and uploads (image/video/audio, up to ${wholeMb(urlMaxBytes)}MB). ` +
                 'No bytes pass through the conversation.' +
-                (onDisk ? '' : ' Larger files: POST the raw bytes to /upload, which streams instead of buffering.')),
+                (onDisk ? '' : ' Larger files: PUT them to a gemini_get_upload_url link and pass the r2_key instead — that path does not buffer.')),
             data_base64: z
                 .string()
                 .min(1)
@@ -108,7 +118,7 @@ export function registerFileTools(server, client) {
                 .optional()
                 .describe(onDisk
                 ? 'Path to a local file (absolute, or resolved against $GEMINI_INPUT_DIR). Confirm-gated like every other local-file input.'
-                : 'Unavailable on this hosted connector (no filesystem) — use `url`, `data_base64`, or POST /upload.'),
+                : 'Unavailable here: this deployment runs on a remote machine and cannot read your filesystem. Use `url`, `r2_key` (via gemini_get_upload_url), or `data_base64`.'),
             mime_type: z
                 .string()
                 .regex(/^[\w.+-]+\/[\w.+-]+$/, 'must be a MIME type like image/png')
@@ -126,8 +136,9 @@ export function registerFileTools(server, client) {
         }
         if (args.path) {
             if (!onDisk) {
-                throw new McpToolError('`path` is unavailable on the hosted connector: it runs on a Cloudflare Worker, which has no filesystem. ' +
-                    'Use `url` (the server downloads it), `data_base64`, or POST the raw bytes to /upload with the same Authorization header.', { hint: 'Use `url`, `data_base64`, or POST /upload.' });
+                throw new McpToolError('`path` is unavailable on the hosted connector: it runs on a remote machine with no access to your filesystem. ' +
+                    'Use `url` (the server downloads it), `r2_key` after PUTting the file to a URL from gemini_get_upload_url, or ' +
+                    '`data_base64` if you cannot make HTTP requests at all.', { hint: 'Use `url`, `r2_key` (gemini_get_upload_url), or `data_base64`.' });
             }
             // Same gate as every other local-file input: a prompt-injected `path`
             // would otherwise ship an arbitrary local file to Google, and an
@@ -178,7 +189,7 @@ export function registerFileTools(server, client) {
         },
     }, async (args) => {
         const files = await client.listFiles(args.page_size ?? 100);
-        return textResult({
+        return minifiedResult({
             count: files.length,
             files: files.map((f) => ({
                 file_uri: f.name,
@@ -220,7 +231,7 @@ export function registerFileTools(server, client) {
                 // Remediation goes in the MESSAGE: MCP serialization drops hints.
                 throw new McpToolError(`No stored media for r2_key "${args.r2_key}" — it has probably passed its retention window. Re-run the generation to get a new one.`, { hint: 'Objects are swept on a retention schedule (MEDIA_TTL_DAYS, default 7 days).' });
             }
-            return textResult({
+            return minifiedResult({
                 url: fresh.ref,
                 r2_key: fresh.key,
                 ...(fresh.expiresAt ? { expires_at: fresh.expiresAt } : {}),
@@ -228,6 +239,44 @@ export function registerFileTools(server, client) {
                 hint: 'In a Claude chat client, download this URL into your sandbox and present it as an output file — inline image blocks and markdown embeds do not render for the end user.',
             });
         });
+        // The tool that lets a model SEE what it made.
+        //
+        // On disk the result is a path an agent's own image tool can open. Here it
+        // is a signed URL, which is not the same thing at all: fetching it takes
+        // network I/O the caller may not be allowed to perform, and a URL is not
+        // something a vision model can look at. Without this, a generate → refine
+        // loop on the hosted connector runs blind.
+        //
+        // Deliberately its own tool rather than pixels on every result. Bytes on
+        // every turn is a cost nobody opted into, and the durable half of a result
+        // is the `r2_key` manifest — small enough to persist, and re-signable long
+        // after any URL in it has expired. This way the caller pays for eyes on the
+        // turns it actually looks, and an image from a LOST turn (found through
+        // gemini_list_recent_media) can be examined exactly the same way.
+        server.registerTool('gemini_view_media', {
+            description: 'Return a generated image as an inline image block, so you can actually SEE it — from its `r2_key`. ' +
+                'The generation tools hand back links, which a model cannot look at; call this to check composition, colour ' +
+                'or garbled text before refining, and to inspect an image recovered with gemini_list_recent_media. ' +
+                'Costs image tokens on the turns you use it, which is why it is a separate call and not part of every result. ' +
+                'Keywords: see the image, view, look at, verify output, check the result, preview.',
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            inputSchema: {
+                r2_key: z.string().min(1).describe('The `media[].r2_key` from a generation result or gemini_list_recent_media'),
+            },
+        }, async (args) => {
+            const key = args.r2_key.trim();
+            const { bytes, mimeType } = await client.readStoredMedia(key);
+            if (bytes.byteLength > VIEW_MAX_BYTES) {
+                // A cap the TRANSPORT imposes, not the model: an oversized block is
+                // rejected or truncated on the way out, which reads as a broken tool
+                // rather than a large image. Say which it is, and name both ways
+                // through. Remediation in the MESSAGE — hints are dropped.
+                throw new McpToolError(`That image is too large to return inline (${formatMb(bytes.byteLength)}, limit ${formatMb(VIEW_MAX_BYTES)}). ` +
+                    'Re-render it at a smaller image_size (1K is plenty to check composition), or take the link from ' +
+                    'gemini_sign_media and open it outside the conversation.');
+            }
+            return { content: [{ type: 'image', data: bytesToBase64(bytes), mimeType }] };
+        });
         // The recovery path for media whose RESULT was lost rather than never
         // produced — a background job killed with its machine still wrote its
         // images, but every reference to them went with the response. Without this
@@ -258,7 +307,7 @@ export function registerFileTools(server, client) {
                 ? await sink.listRecentPage({ limit, sinceDay: args.since_day })
                 : { media: await sink.listRecent({ limit, sinceDay: args.since_day }), truncated: false };
             const found = page.media;
-            return textResult({
+            return minifiedResult({
                 count: found.length,
                 // Never let a bounded walk pass for the whole picture: concluding an
                 // image is gone is what makes someone pay to generate it twice.
@@ -267,6 +316,13 @@ export function registerFileTools(server, client) {
                     r2_key: m.key,
                     day: m.day,
                     name: m.name,
+                    // From the object's sidecar record, where it has one. This is what
+                    // makes a listing identifiable rather than a wall of keys: which
+                    // turn produced it, what was asked for, and the id to chain from.
+                    ...(m.interactionId ? { interaction_id: m.interactionId } : {}),
+                    ...(m.prompt ? { prompt: m.prompt } : {}),
+                    ...(m.model ? { model: m.model } : {}),
+                    ...(m.createdAt ? { created_at: m.createdAt } : {}),
                     ...(m.sizeBytes !== undefined ? { size_bytes: m.sizeBytes } : {}),
                     ...(m.url ? { url: m.url, curl_hint: `curl -sS -o ${downloadFilename(m.key)} "${m.url}"` } : {}),
                     ...(m.expiresAt ? { expires_at: m.expiresAt } : {}),
@@ -293,6 +349,6 @@ export function registerFileTools(server, client) {
         if (gate)
             return gate;
         await client.deleteFile(args.file_uri);
-        return textResult({ deleted: args.file_uri });
+        return minifiedResult({ deleted: args.file_uri });
     });
 }

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, resolveAspectRatio, ASPECT_RATIOS, 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, imagesBase64Schema, imagesR2KeysSchema, charactersSchema, styleSchema, resolveCharacterRefs, composePrompt } from './shared.js';
 import { fingerprintRequest } from '../jobs.js';
 import { sumUsage } from '../usage.js';
 import { attachCost } from '../pricing.js';
@@ -27,7 +27,7 @@ export function registerGenerateTools(server, client) {
             images_url: imagesUrlSchema(),
             images_file_uris: imagesFileUrisSchema(),
             images_r2_keys: imagesR2KeysSchema(),
-            images_base64: z.array(z.string().min(1)).optional().describe('Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
+            images_base64: imagesBase64Schema(),
             characters: charactersSchema,
             style: styleSchema,
             video_url: z.string().url().optional().describe('Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video→image; use a Flash model e.g. gemini-3.1-flash-image)'),
@@ -152,7 +152,7 @@ export function registerGenerateTools(server, client) {
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, count, persistsFiles: client.mediaSink?.persistsFiles });
             if (risk)
                 meta.timeout_risk = risk;
-            return emit(named, { ...args, sink: client.mediaSink }, meta);
+            return emit(named, { ...args, sink: client.mediaSink, sidecar: { prompt: args.prompt } }, meta);
         });
     });
     server.registerTool('gemini_image_edit', {
@@ -167,7 +167,7 @@ export function registerGenerateTools(server, client) {
             images_url: imagesUrlSchema('Input images'),
             images_file_uris: imagesFileUrisSchema('Input images'),
             images_r2_keys: imagesR2KeysSchema('Input images'),
-            images_base64: z.array(z.string().min(1)).optional().describe('Input images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation'),
+            images_base64: imagesBase64Schema('Input images'),
             characters: charactersSchema,
             style: styleSchema,
             filename: z.string().optional().describe('Base filename for the output image (extension stripped; default: slugified prompt)'),
@@ -233,7 +233,7 @@ export function registerGenerateTools(server, client) {
             const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: client.mediaSink?.persistsFiles });
             if (risk)
                 meta.timeout_risk = risk;
-            return emit([{ image: img, base: slug }], { ...args, sink: client.mediaSink }, meta);
+            return emit([{ image: img, base: slug }], { ...args, sink: client.mediaSink, sidecar: { prompt: args.prompt } }, meta);
         });
     });
 }