@chrischall/gemini-mcp 1.6.2 → 1.7.0

package/dist/job-store.js

@@ -0,0 +1,138 @@
+/**
+ * The durable half of the job registry (`src/jobs.ts`).
+ *
+ * ## Why this exists
+ *
+ * `JobRegistry` keeps jobs in a `Map`, which is exactly right for stdio: the
+ * process that starts a generation is the process that finishes it, and if it
+ * dies the user is sitting at a terminal watching it die.
+ *
+ * Hosted, that premise is false in a specific and non-obvious way. The
+ * connector is this same stdio server run as a Node child on an mcp-host Fly
+ * machine configured `auto_stop_machines = "stop"` with
+ * `min_machines_running = 0`. Fly stops that machine when nothing is in
+ * flight — mcp-host's own docs put it plainly: *"an open connection is exactly
+ * what stops the machine stopping"*. An `async: true` call is a request that
+ * answers in milliseconds, so it holds nothing open. The machine stops, the
+ * child is killed, and the generation dies **with the only record that it ever
+ * existed**. Polling `gemini_get_result` a couple of minutes later reports the
+ * id as unknown, which reads like an expiry bug and is actually a machine that
+ * went to sleep.
+ *
+ * This is also why a long `max_wait_ms` works where `async: true` does not: the
+ * wait keeps the HTTP request open, and the open request keeps the machine up.
+ *
+ * ## What durability can and cannot buy here
+ *
+ * It buys the RECORD, not the EXECUTION. There is no Workflows, no Queue, no
+ * Durable Object and no KV in reach — the child's environment is allowlist-only
+ * (mcp-host `spawn-env.ts`), and the only durable thing it can address is the
+ * blob store its media already goes to. Nothing here resumes a killed
+ * generation; re-running it would re-bill it, which is the cost this whole
+ * mechanism exists to avoid.
+ *
+ * So the contract is: a job never silently vanishes, and a job whose executor
+ * died ends in a **terminal** state that says so. The bytes a dead job managed
+ * to write are still in `gen/`, which is what `gemini_list_recent_media` is
+ * for.
+ *
+ * ## Liveness is a heartbeat, not a guess
+ *
+ * "Still running" and "the machine ate it" are indistinguishable from a single
+ * stored status, and a timeout long enough to be safe for a 12-scene set is far
+ * too long to be useful. So a running job re-stamps `updatedAt` on an interval
+ * ({@link HEARTBEAT_MS}), and a record whose stamp is older than
+ * {@link EXECUTOR_LOST_AFTER_MS} is read as `failed` — decided at READ time, so
+ * no boot scan is needed and a machine that never comes back still resolves its
+ * jobs the moment anybody asks.
+ *
+ * Every operation is best-effort and swallows its errors. A durable store that
+ * is down must degrade to the in-memory behaviour that came before it, never
+ * fail a generation the user is paying for.
+ */
+import { createHash } from 'node:crypto';
+/** How often a running job re-stamps its record so a reader can see it is alive. */
+export const HEARTBEAT_MS = 60_000;
+/**
+ * How stale a `running` record may get before its executor is presumed dead.
+ *
+ * Three missed heartbeats: long enough that a paused event loop mid-generation
+ * is not mistaken for a dead machine, short enough that a caller learns the
+ * truth in minutes rather than being told to keep polling forever.
+ */
+export const EXECUTOR_LOST_AFTER_MS = 3 * HEARTBEAT_MS;
+/** Where a job record lives, relative to the store root. */
+const PREFIX = 'jobs';
+/**
+ * An idempotency key is an arbitrary caller-supplied string: it can contain
+ * slashes, spaces, or `..`. Hashing it makes the key space closed by
+ * construction rather than by escaping, so no crafted key can address an object
+ * outside this tenant's prefix.
+ */
+function keyHash(idempotencyKey) {
+    return createHash('sha256').update(idempotencyKey).digest('hex').slice(0, 32);
+}
+/** Job records over the mcp-host blob store. */
+export function createBlobJobStore(bucket, opts) {
+    const now = opts.now ?? (() => Date.now());
+    const tenantOf = async () => (typeof opts.tenant === 'function' ? opts.tenant() : opts.tenant);
+    const recordKey = async (jobId) => `${PREFIX}/${await tenantOf()}/${encodeURIComponent(jobId)}.json`;
+    const pointerKey = async (k) => `${PREFIX}/${await tenantOf()}/keys/${keyHash(k)}.json`;
+    async function writeJson(key, value) {
+        try {
+            await bucket.put(key, JSON.stringify(value), { httpMetadata: { contentType: 'application/json' } });
+        }
+        catch {
+            // A durable write that fails leaves the in-memory registry exactly as
+            // capable as it was before this module existed. Failing the generation
+            // instead would trade a recoverable gap for a lost paid result.
+        }
+    }
+    async function readJson(key) {
+        try {
+            const obj = await bucket.get(key);
+            if (!obj)
+                return undefined;
+            return JSON.parse(new TextDecoder().decode(await obj.arrayBuffer()));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    return {
+        async put(record) {
+            await writeJson(await recordKey(record.jobId), record);
+        },
+        async get(jobId) {
+            const record = await readJson(await recordKey(jobId));
+            if (!record || typeof record.status !== 'string')
+                return undefined;
+            if (record.status !== 'running')
+                return record;
+            if (now() - record.updatedAt <= EXECUTOR_LOST_AFTER_MS)
+                return record;
+            // Terminal, and honest about which kind of gone it is. Derived on read
+            // rather than persisted: the process that could have written the
+            // transition is by definition the one that is no longer there.
+            return {
+                ...record,
+                status: 'failed',
+                error: {
+                    message: `Job "${jobId}" was lost: its executor stopped reporting ${Math.round((now() - record.updatedAt) / 1000)}s ` +
+                        `ago, before the generation finished. This connector runs on a machine that stops when no request is ` +
+                        `in flight, so background work started with \`async: true\` does not reliably survive.`,
+                    hint: 'Re-run with `max_wait_ms` (e.g. 240000) instead of `async: true` — holding the request open keeps the ' +
+                        'executor alive. Any images the lost run did finish are still stored: list them with ' +
+                        'gemini_list_recent_media before paying for a regeneration.',
+                },
+            };
+        },
+        async putKey(idempotencyKey, jobId) {
+            await writeJson(await pointerKey(idempotencyKey), { jobId });
+        },
+        async jobIdForKey(idempotencyKey) {
+            const pointer = await readJson(await pointerKey(idempotencyKey));
+            return typeof pointer?.jobId === 'string' ? pointer.jobId : undefined;
+        },
+    };
+}

package/dist/jobs.js

@@ -1,8 +1,23 @@
 import { randomUUID, createHash } from 'node:crypto';
 import { textResult, McpToolError } from '@chrischall/mcp-utils';
 import { downloadFilename } from './media-name.js';
+import { HEARTBEAT_MS } from './job-store.js';
 /** Recently-completed jobs are reusable by key for this long, then evicted. */
 const JOB_TTL_MS = 600_000; // 10 min
+/**
+ * How long a DURABLE record stays reusable by idempotency key.
+ *
+ * Longer than {@link JOB_TTL_MS} on purpose: the in-memory window is bounded by
+ * a process that no longer exists, and the case this covers — a retry after the
+ * hosted machine went to sleep — can easily land further out than ten minutes.
+ * Still bounded, because a stored record survives for the blob store's ~30-day
+ * retention and silently replaying a month-old generation is a wrong answer
+ * that looks like a cache hit.
+ *
+ * 24h is also the longest a signed media link can live here, so a replay inside
+ * this window is one whose URLs can still be re-minted from their keys.
+ */
+const DURABLE_JOB_REUSE_MS = 24 * 60 * 60 * 1000;
 /** Hard cap on retained entries (oldest-settled evicted first). */
 const JOB_MAX = 64;
 function isExpired(entry, now) {
@@ -131,13 +146,38 @@ function annotateReused(result, jobId) {
     };
 }
 /** Immediate handle for an async call — the caller polls `gemini_get_result`. */
-function jobHandle(jobId, status) {
+function jobHandle(jobId, status, durable = false) {
     return textResult({
         job_id: jobId,
         status,
-        hint: `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done" (results are per-process and expire ~10 min after completion).`,
+        hint: durable
+            ? `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done". The job record is stored durably, so a poll still works if this connector restarts — but background work is NOT restarted, so a long generation is safer with max_wait_ms than with async.`
+            : `Generation running in the background. Poll gemini_get_result with job_id "${jobId}" until status is "done" (results are per-process and expire ~10 min after completion).`,
     });
 }
+/**
+ * Whether a result is worth persisting to the durable store.
+ *
+ * A hosted result is a small JSON manifest of `r2_key`s, which is exactly what
+ * a restart needs — the keys outlive every signed URL and `refreshMedia`
+ * re-signs from them. An `inline: true` result is raw base64 image bytes: too
+ * big to keep, and pointless to keep, since nothing about it survives usefully.
+ * Recording the omission is what lets a poll say *why* rather than reporting a
+ * success with nothing in it.
+ */
+const MAX_PERSISTED_RESULT_BYTES = 64 * 1024;
+function persistableResult(result) {
+    if ((result.content ?? []).some((block) => block.type !== 'text'))
+        return { resultOmitted: 'inline' };
+    try {
+        if (JSON.stringify(result).length > MAX_PERSISTED_RESULT_BYTES)
+            return { resultOmitted: 'too_large' };
+    }
+    catch {
+        return { resultOmitted: 'too_large' };
+    }
+    return { result };
+}
 /**
  * Await `promise` for at most `waitMs`; `undefined` means the budget expired
  * with the work still pending (rejections propagate as usual). The timer never
@@ -163,14 +203,123 @@ export class JobRegistry {
      * never expire.
      */
     resigner;
+    /**
+     * Durable backing for this registry, when the deployment has somewhere to put
+     * it. Absent on a local stdio install, where the process that starts a
+     * generation is the process that finishes it and a `Map` is the whole truth.
+     *
+     * Present on the hosted connector, where it is load-bearing: see the header of
+     * `src/job-store.ts` for why an in-memory-only registry cannot work on a
+     * machine that stops whenever no request is in flight.
+     */
+    store;
+    /**
+     * When set, `async: true` is served as a bounded in-band wait instead of an
+     * immediate hand-off.
+     *
+     * Set by the hosted client, because there the two are not the trade-off they
+     * look like. Returning immediately releases the request, and the released
+     * request is the thing keeping the executor alive — so `async: true` is
+     * precisely the way to get a generation killed. Waiting holds the machine up
+     * until the work is done. If the budget still expires the caller gets the same
+     * job handle it asked for, now backed by a durable record.
+     */
+    asyncWaitFallbackMs;
+    /** Injectable clock (tests). */
+    now = () => Date.now();
     jobs = new Map();
     byKey = new Map(); // idempotencyKey -> jobId
     runningByFingerprint = new Map(); // fingerprint -> jobId (only while running)
+    /** Durable bookkeeping still in flight — awaited by `drain()` in tests. */
+    pending = new Set();
+    heartbeatTimer;
     /** Drop every job. Used by `SessionState.reset()` (tests) — not by handlers. */
     reset() {
         this.jobs.clear();
         this.byKey.clear();
         this.runningByFingerprint.clear();
+        this.stopHeartbeat();
+    }
+    /** Await outstanding durable writes. Tests only — handlers never need it. */
+    async drain() {
+        // Yield a macrotask first so a settle handler that has already fired gets
+        // its write queued before we look. Deliberately flushes only what is
+        // ISSUABLE: a job still running has no terminal write to wait for, and
+        // blocking on one would hang any test that drains before finishing a job.
+        for (let round = 0; round < 50; round++) {
+            await new Promise((resolve) => setTimeout(resolve, 0));
+            if (!this.pending.size)
+                return;
+            await Promise.allSettled([...this.pending]);
+        }
+    }
+    /**
+     * Re-stamp every running job's durable record.
+     *
+     * This is what separates "still working" from "the machine went away": a
+     * reader compares the stamp against `EXECUTOR_LOST_AFTER_MS`, so a 12-scene
+     * set that legitimately runs for ten minutes stays `running` while a job whose
+     * child was killed goes terminal within three missed beats.
+     */
+    async beat() {
+        if (!this.store)
+            return;
+        await Promise.allSettled([...this.jobs.values()]
+            .filter((e) => e.status === 'running')
+            // The status is re-read INSIDE the queued task, not sampled here: a job
+            // that finishes while this beat waits its turn must not have `running`
+            // written back over its terminal record.
+            .map((e) => this.writeRecord(e, { onlyWhileRunning: true })));
+    }
+    /**
+     * Queue one durable write for `entry`, after any write already in flight for
+     * it. `onlyWhileRunning` drops the write if the job settled in the meantime —
+     * which is what makes a late heartbeat a no-op rather than a resurrection.
+     */
+    writeRecord(entry, opts = {}) {
+        const next = (entry.writeChain ?? Promise.resolve()).then(async () => {
+            if (opts.onlyWhileRunning && entry.status !== 'running')
+                return;
+            await this.store.put(this.recordFor(entry, this.now()));
+        }, () => undefined);
+        entry.writeChain = next;
+        return next;
+    }
+    recordFor(entry, updatedAt) {
+        return {
+            jobId: entry.jobId,
+            toolName: entry.toolName,
+            fingerprint: entry.fingerprint,
+            ...(entry.idempotencyKey !== undefined ? { idempotencyKey: entry.idempotencyKey } : {}),
+            status: entry.status,
+            createdAt: entry.createdAt,
+            updatedAt,
+            ...(entry.error ? { error: entry.error } : {}),
+            ...(entry.status === 'done' && entry.result ? persistableResult(entry.result) : {}),
+        };
+    }
+    /** Run `p` as durable bookkeeping: tracked for `drain()`, never thrown from. */
+    track(p) {
+        const wrapped = p.catch(() => undefined).finally(() => this.pending.delete(wrapped));
+        this.pending.add(wrapped);
+    }
+    startHeartbeat() {
+        if (this.heartbeatTimer || !this.store)
+            return;
+        this.heartbeatTimer = setInterval(() => {
+            if (![...this.jobs.values()].some((e) => e.status === 'running')) {
+                this.stopHeartbeat();
+                return;
+            }
+            this.track(this.beat());
+        }, HEARTBEAT_MS);
+        // Never hold the process open for bookkeeping.
+        this.heartbeatTimer.unref?.();
+    }
+    stopHeartbeat() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = undefined;
     }
     /** Drop expired entries, then enforce JOB_MAX by evicting oldest-settled first. */
     evict(now) {
@@ -213,8 +362,13 @@ export class JobRegistry {
      * different registry and therefore a genuinely separate generation.
      */
     async dispatch(opts, work) {
-        const { toolName, fingerprint, idempotencyKey, async, waitMs } = opts;
-        const now = Date.now();
+        const { toolName, fingerprint, idempotencyKey } = opts;
+        // Hosted, an immediate hand-off is what gets the executor reclaimed, so
+        // `async` is honoured by HOLDING the request rather than releasing it.
+        const degrade = opts.async === true && this.asyncWaitFallbackMs !== undefined;
+        const async = degrade ? false : opts.async;
+        const waitMs = degrade ? (opts.waitMs ?? this.asyncWaitFallbackMs) : opts.waitMs;
+        const now = this.now();
         let hit;
         if (idempotencyKey !== undefined) {
             const id = this.byKey.get(idempotencyKey);
@@ -228,6 +382,14 @@ export class JobRegistry {
             if (entry && entry.status === 'running')
                 hit = entry;
         }
+        // Nothing in memory, but the key may name a job an earlier child ran. Only
+        // an explicit key unlocks this — the same rule the in-memory path uses, so
+        // a deliberate same-prompt variation is never silently deduplicated.
+        if (!hit && idempotencyKey !== undefined && this.store) {
+            const durable = await this.durableByKey(idempotencyKey, fingerprint);
+            if (durable)
+                return durable;
+        }
         if (hit) {
             if (async)
                 return jobHandle(hit.jobId, hit.status);
@@ -249,25 +411,69 @@ export class JobRegistry {
         if (idempotencyKey !== undefined)
             this.byKey.set(idempotencyKey, jobId);
         this.runningByFingerprint.set(fingerprint, jobId);
-        promise.then((res) => { entry.status = 'done'; entry.result = res; entry.settledAt = Date.now(); }, (err) => {
+        // Write the "running" record BEFORE the work can finish. A record that only
+        // appeared on completion would be missing for exactly the window this whole
+        // mechanism exists to cover.
+        if (this.store) {
+            this.track(this.writeRecord(entry));
+            if (idempotencyKey !== undefined)
+                this.track(this.store.putKey(idempotencyKey, jobId));
+            this.startHeartbeat();
+        }
+        const settle = promise.then((res) => { entry.status = 'done'; entry.result = res; entry.settledAt = this.now(); }, (err) => {
             entry.status = 'failed';
             entry.error = { message: err instanceof Error ? err.message : String(err), hint: err?.hint };
-            entry.settledAt = Date.now();
+            entry.settledAt = this.now();
         }).finally(() => {
             if (this.runningByFingerprint.get(fingerprint) === jobId)
                 this.runningByFingerprint.delete(fingerprint);
         });
+        if (this.store)
+            void settle.then(() => this.track(this.writeRecord(entry)));
         if (async)
-            return jobHandle(jobId, 'running');
+            return jobHandle(jobId, 'running', this.store !== undefined);
         if (waitMs !== undefined) {
             const settled = await awaitWithBudget(promise, waitMs);
             // Budget expired with the work still running: hand back the job id — the
             // work continues and the caller polls, exactly as with `async: true`,
             // except a fast result would have been returned in-band.
-            return settled ?? jobHandle(jobId, 'running');
+            return settled ?? jobHandle(jobId, 'running', this.store !== undefined);
         }
         return promise;
     }
+    /**
+     * Resolve an idempotency key against the durable store — the path a retry
+     * takes when the child that ran the original job is gone.
+     *
+     * `undefined` means "nothing durable to reuse", which includes a job that
+     * FAILED: a retry after an error must really retry. A job still recorded as
+     * running belongs to an executor this process cannot await, so the caller gets
+     * the handle back rather than a promise that would never settle.
+     */
+    async durableByKey(idempotencyKey, fingerprint) {
+        const id = await this.store.jobIdForKey(idempotencyKey);
+        if (!id)
+            return undefined;
+        const record = await this.store.get(id);
+        if (!record)
+            return undefined;
+        // An idempotency key is a habit as often as it is a promise — "1", "test",
+        // "retry". In memory that was survivable because the entry expired in ten
+        // minutes; a durable record lives for the store's retention, so replaying
+        // on the key ALONE would hand back a different prompt's image, weeks later,
+        // and label it a cache hit. The fingerprint is what makes this idempotency
+        // rather than a name lookup: same key + different request is a genuinely
+        // new generation.
+        if (record.fingerprint !== fingerprint)
+            return undefined;
+        if (this.now() - record.updatedAt > DURABLE_JOB_REUSE_MS)
+            return undefined;
+        if (record.status === 'running')
+            return jobHandle(id, 'running', true);
+        if (record.status !== 'done' || !record.result)
+            return undefined;
+        return annotateReused(await refreshMedia(record.result, this.resigner), id);
+    }
     /**
      * Retrieve an async job by id (backs the `gemini_get_result` tool):
      * `running` → a status handle; `done` → the recorded result payload;
@@ -277,15 +483,22 @@ 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.
      */
-    getResult(jobId) {
+    async getResult(jobId) {
         const entry = this.jobs.get(jobId);
         if (!entry) {
-            throw new McpToolError(`No job "${jobId}" — unknown or expired.`, {
-                hint: 'Jobs live with your session and are evicted ~10 min after completion (or on server restart). If the generation likely finished, check the output dir / <image>.json sidecar instead of polling.',
+            const durable = this.store ? await this.store.get(jobId) : undefined;
+            if (durable)
+                return this.fromRecord(durable);
+            throw new McpToolError(this.store
+                ? `No job "${jobId}" — no record of it exists. Either the id is wrong, or the job is older than the ${JOB_RECORD_RETENTION_LABEL} job records are kept.`
+                : `No job "${jobId}" — unknown or expired.`, {
+                hint: this.store
+                    ? 'Job records are stored durably here, so a restart alone does not lose one — an id with no record was never started under this account. Images from a completed run are listed by gemini_list_recent_media.'
+                    : 'Jobs live with your session and are evicted ~10 min after completion (or on server restart). If the generation likely finished, check the output dir / <image>.json sidecar instead of polling.',
             });
         }
         if (entry.status === 'running')
-            return jobHandle(jobId, 'running');
+            return jobHandle(jobId, 'running', this.store !== undefined);
         if (entry.status === 'failed') {
             throw new McpToolError(entry.error?.message ?? 'Job failed.', entry.error?.hint ? { hint: entry.error.hint } : undefined);
         }
@@ -296,4 +509,36 @@ export class JobRegistry {
             throw new McpToolError(`Job "${jobId}" completed without a recorded result.`);
         return entry.result;
     }
+    /**
+     * Render a durable record as a poll answer — the path taken when the child
+     * that ran the job is gone.
+     *
+     * The three outcomes are kept distinct on purpose. Collapsing "your job
+     * failed", "your job was killed" and "no such job" into one message is what
+     * made the original bug read as an expiry problem when it was a machine
+     * lifecycle problem.
+     */
+    async fromRecord(record) {
+        if (record.status === 'running')
+            return jobHandle(record.jobId, 'running', true);
+        if (record.status === 'failed') {
+            throw new McpToolError(record.error?.message ?? 'Job failed.', record.error?.hint ? { hint: record.error.hint } : undefined);
+        }
+        if (record.resultOmitted) {
+            // Both reasons mean "the generation happened, the payload is not here",
+            // but only one of them is the caller's to change.
+            throw new McpToolError(record.resultOmitted === 'inline'
+                ? `Job "${record.jobId}" finished, but its result was returned inline (base64 image data) and inline results are not stored, so there is nothing to replay. Re-run without \`inline: true\` so the media is stored and returned as URLs, which a poll can replay.`
+                : `Job "${record.jobId}" finished, but its result was too large to store (over ${Math.round(MAX_PERSISTED_RESULT_BYTES / 1024)} KB), so there is nothing to replay.`, {
+                hint: 'The generation itself completed — list what it produced with gemini_list_recent_media rather than paying for it again.',
+            });
+        }
+        if (!record.result)
+            throw new McpToolError(`Job "${record.jobId}" completed without a recorded result.`);
+        // Re-sign before replaying: the record outlives the signed URLs inside it,
+        // and handing back a dead link is a failure that looks like a success.
+        return refreshMedia(record.result, this.resigner);
+    }
 }
+/** How long the host keeps a stored object, quoted in the unknown-job message. */
+const JOB_RECORD_RETENTION_LABEL = '30 days';

package/dist/session.js

@@ -5,16 +5,17 @@ import { JobRegistry } from './jobs.js';
  * All of this used to be module-level (`jobs`/`byKey`/`runningByFingerprint` in
  * jobs.ts, `lastInteractionId`/`writtenOutputs` in tools/interact.ts). That is
  * correct for stdio, where a process serves exactly one user — and a
- * cross-tenant leak on the hosted connector, where Cloudflare shares ONE Worker
- * isolate across many Durable Object instances. Module state there is shared by
- * every authenticated claude.ai session in the isolate: the per-session
+ * cross-tenant leak on the hosted connector, where ONE child process serves
+ * every session of this registration at once (mcp-host runs the stdio server as
+ * a supervised child). Module state there is shared by
+ * every authenticated claude.ai session on that child: the per-session
  * `GeminiClient` isolated the API key but not the memory around it, so a
  * colliding `idempotency_key` replayed another user's result, an identical
  * prompt attached to another user's in-flight (billable) job, and
  * `continue_last: true` resumed another user's interaction under your key.
  *
  * So session memory hangs off the `GeminiClient` — the one object the connector
- * already builds per authenticated session (`buildClient` in src/worker.ts) and
+ * already builds per authenticated session and
  * threads into every registrar. Handlers reach it as `client.session`.
  *
  * The rule this encodes: **`src/` must hold no module-level mutable state.**

package/dist/storage/media.js

@@ -45,6 +45,30 @@ export async function tenantIdFor(secret) {
 // `gen`, not `media`: the objects are served at `/media/<key>`, and a `media`
 // prefix would make every URL read `/media/media/…`.
 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.
+ */
+const MAX_LIST_PAGES = 10;
+/**
+ * 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.
+ *
+ * `undefined` for anything that is not a dated object key, so a stray object
+ * under the prefix is skipped rather than turned into a listing failure.
+ */
+function parseMediaKey(key, prefix) {
+    const rest = key.slice(prefix.length);
+    const match = /^(\d{4}-\d{2}-\d{2})\/(.+)$/.exec(rest);
+    if (!match)
+        return undefined;
+    // Drop the random id `persist` prepends and the extension, leaving the
+    // caller's own slug — which is what makes a listing recognisable to a human
+    // looking for "the summer camp ones".
+    const name = match[2].replace(/^[0-9a-f]{4,}-/i, '').replace(/\.[A-Za-z0-9]+$/, '');
+    return { day: match[1], name: name || match[2] };
+}
 /** Object-key-safe name: no slashes, no dot-segments, never empty. */
 export function safeKeySegment(base) {
     const cleaned = base
@@ -103,6 +127,52 @@ export function createR2Sink(bucket, opts) {
                 mimeType: object.httpMetadata?.contentType ?? 'application/octet-stream',
             };
         },
+        async listRecent(opts = {}) {
+            return (await this.listRecentPage(opts)).media;
+        },
+        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;
+            }
+            // 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 };
+        },
         async resign(key) {
             if (!(await owned(key)))
                 return undefined;

package/dist/tools/files.js

@@ -228,6 +228,55 @@ 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 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
+        // the only way to see them again is to pay for the generation twice.
+        server.registerTool('gemini_list_recent_media', {
+            description: 'List images/video/audio this connector recently generated for your account, newest first, with fresh openable URLs. ' +
+                'Use it when a result was lost — a generation whose response never arrived, or an async job whose id came back unknown — ' +
+                'to find what already exists BEFORE re-running (and re-paying for) it. Keywords: lost result, orphaned job, ' +
+                'missing image, what did I generate, recover, recent media.',
+            annotations: { readOnlyHint: true, openWorldHint: false },
+            inputSchema: {
+                limit: z.number().int().positive().max(100).optional().describe('How many to return (default 20, newest first)'),
+                since_day: z
+                    .string()
+                    .regex(/^\d{4}-\d{2}-\d{2}$/)
+                    .optional()
+                    .describe('Only media stored on or after this UTC day, e.g. "2026-08-18"'),
+            },
+        }, async (args) => {
+            const sink = client.mediaSink;
+            if (!sink?.listRecent) {
+                throw new McpToolError('This server writes generated files to disk — list the output directory instead.', {
+                    hint: 'gemini_list_recent_media applies to the hosted connector only.',
+                });
+            }
+            const limit = args.limit ?? 20;
+            const page = sink.listRecentPage
+                ? 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({
+                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.
+                ...(page.truncated ? { truncated: true } : {}),
+                media: found.map((m) => ({
+                    r2_key: m.key,
+                    day: m.day,
+                    name: m.name,
+                    ...(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 } : {}),
+                })),
+                hint: found.length
+                    ? 'Ordered by the day each object was stored (the store keeps no finer timestamp), newest first. Re-sign any expired link with gemini_sign_media.' +
+                        (page.truncated ? ' More media exists than is listed here — narrow with since_day, or raise limit, before concluding something is missing.' : '')
+                    : 'Nothing stored in that window. Media is swept on a retention schedule, so an older generation may already be gone.',
+            });
+        });
     }
     server.registerTool('gemini_delete_file', {
         description: 'Delete an uploaded file, image or photo (by file_uri) from the Gemini Files API before its ~48h expiry. Any tool call still referencing it ' +