@chrischall/gemini-mcp 1.6.1 → 1.7.0

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/media-url.js

@@ -15,6 +15,7 @@
  * Kept free of any Cloudflare import so the whole thing is testable under Node:
  * WebCrypto is the only primitive used, and it exists on both runtimes.
  */
+import { signedLinks } from './signed-url.js';
 /** How long a freshly minted media URL stays valid. Matches Files API retention. */
 export const MEDIA_URL_TTL_MS = 48 * 60 * 60 * 1000;
 /** KV key holding the lazily-generated signing secret (zero-config path). */
@@ -128,8 +129,14 @@ export async function verifyMediaSignature(signingKey, key, exp, sig, nowMs) {
         return { ok: false, reason: 'expired' };
     return { ok: true };
 }
-/** `<base>/<key>?exp=…&sig=…` — the URL handed back to the caller. */
+/**
+ * `<base>/<key>?exp=…&sig=…` — the URL handed back to the caller.
+ *
+ * Delegates to {@link signedLinks} so this and `buildUploadUrl` cannot drift
+ * apart the way they did across the re-host. Prefer taking a {@link SignedLinks}
+ * over a base-URL string in new code; this wrapper exists for callers that
+ * already hold a base.
+ */
 export function buildMediaUrl(baseUrl, key, expiresAtMs, signature) {
-    const path = key.split('/').map(encodeURIComponent).join('/');
-    return `${baseUrl.replace(/\/+$/, '')}/${path}?exp=${expiresAtMs}&sig=${signature}`;
+    return signedLinks(baseUrl).media(key, expiresAtMs, signature);
 }

package/dist/registrars.js

@@ -0,0 +1,50 @@
+/**
+ * The tool roster, and the one place error reporting is attached to it.
+ *
+ * This lives apart from `index.ts` because that file is an ENTRY POINT: it has
+ * top-level `await loadStdioDotenv()` and `await runMcp(…)`, so importing it
+ * starts a server on stdio. Nothing can assert what it wires without booting
+ * it — which is precisely how `.map(reporting)` could be deleted with the
+ * suite still green, leaving hosted failures unattributed again (the exact
+ * regression this repo just spent a debugging round trip on). Here the list is
+ * an ordinary value, and `tests/registrars.test.ts` runs a registrar through it.
+ */
+import { surfaceToolErrors } from './errors.js';
+import { registerModelTools } from './tools/models.js';
+import { registerGenerateTools } from './tools/generate.js';
+import { registerSetTools } from './tools/set.js';
+import { registerInteractTools } from './tools/interact.js';
+import { registerVideoTools } from './tools/video.js';
+import { registerMusicTools } from './tools/music.js';
+import { registerJobTools } from './tools/jobs.js';
+import { registerFileTools } from './tools/files.js';
+import { registerUploadUrlTools } from './tools/uploads.js';
+import { registerLibraryTools } from './tools/library.js';
+/**
+ * Give one registrar a server that reports failures in full.
+ *
+ * A hosted upload-URL failure reached the client as a bare "Error occurred
+ * during tool execution" — no message, no failing step. That wrapper is the
+ * client's, but it is only ever the whole story when our own text is empty, so
+ * every handler's throw is turned into a message naming the tool, the real
+ * error class, and the `cause` chain MCP serialization drops (src/errors.ts).
+ */
+export const reporting = (register) => (server, deps) => register(surfaceToolErrors(server), deps);
+/**
+ * Every registrar, already wrapped. `index.ts` passes this straight to
+ * `runMcp`; the last two self-gate on the client having somewhere to put bytes
+ * (hosted with a blob store they register, on a local install they no-op
+ * rather than advertising a tool that cannot work).
+ */
+export const TOOL_REGISTRARS = [
+    registerModelTools,
+    registerGenerateTools,
+    registerSetTools,
+    registerInteractTools,
+    registerVideoTools,
+    registerMusicTools,
+    registerJobTools,
+    registerFileTools,
+    registerUploadUrlTools,
+    registerLibraryTools,
+].map(reporting);

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/signed-url.js

@@ -0,0 +1,42 @@
+/**
+ * The one place that knows how a link into the object store is SHAPED.
+ *
+ * There are two kinds of signed link — a media GET (`?exp=&sig=`) and an
+ * upload PUT (`?ct=&exp=&sig=`) — and before this module they were two
+ * independent copies of the same string building, in two files, each holding
+ * its own base URL. That is exactly how the re-host from the retired Cloudflare
+ * connector to mcp-host split them: the media builder was moved onto the new
+ * `https://host/b/<registrationId>` base and the upload builder was a separate
+ * edit in a separate file, so nothing structural said the two had to agree.
+ *
+ * Both builders now delegate here, and {@link signedLinks} binds ONE base URL
+ * to both of them at once, so the next re-host either moves both or neither.
+ *
+ * Byte-compatible with what shipped: the path is percent-encoded per segment
+ * (separators survive, everything else is encoded — the gateway decodes per
+ * segment and verifies against the LOGICAL key), and the query parameters keep
+ * their historical order. Every link ever minted still parses.
+ */
+/**
+ * `<base>/<encoded key>?<params>`.
+ *
+ * Parameter order is insertion order and is part of the observable shape —
+ * nothing verifies against it, but the curl commands in `curl_hint` and every
+ * link in a user's history read the same way across a redeploy.
+ */
+export function signedObjectUrl(baseUrl, key, params) {
+    const path = key.split('/').map(encodeURIComponent).join('/');
+    const query = new URLSearchParams();
+    for (const [name, value] of Object.entries(params))
+        query.set(name, String(value));
+    return `${baseUrl.replace(/\/+$/, '')}/${path}?${query}`;
+}
+/** Bind one base URL to both link shapes. */
+export function signedLinks(baseUrl) {
+    const base = baseUrl.replace(/\/+$/, '');
+    return {
+        base,
+        media: (key, expiresAtMs, signature) => signedObjectUrl(base, key, { exp: expiresAtMs, sig: signature }),
+        upload: (key, contentType, expiresAtMs, signature) => signedObjectUrl(base, key, { ct: contentType.toLowerCase(), exp: expiresAtMs, sig: signature }),
+    };
+}

package/dist/storage/media.js

@@ -12,6 +12,7 @@
  * behaviour and must stay byte-for-byte equivalent to it.
  */
 import { base64ToBytes } from '../bytes.js';
+import { signedLinks } from '../signed-url.js';
 /**
  * The stdio sink: `resolveOutputDir(output_dir)` → `writeMedia` per item, in
  * order (so `uniquePath`'s `name`/`name-2`/`name-3` sequencing is preserved).
@@ -44,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
@@ -65,7 +90,7 @@ export function createR2Sink(bucket, opts) {
     const now = opts.now ?? (() => new Date());
     const randomId = opts.randomId ?? (() => crypto.randomUUID().slice(0, 8));
     const publicBase = opts.publicBaseUrl?.replace(/\/+$/, '');
-    const signedBase = opts.signedBaseUrl?.replace(/\/+$/, '');
+    const signedBase = opts.links?.base ?? opts.signedBaseUrl?.replace(/\/+$/, '');
     const ttlMs = opts.urlTtlMs ?? 0;
     const readPrefixes = [prefix, ...(opts.readPrefixes ?? [])];
     let tenantCache;
@@ -102,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;
@@ -145,9 +216,11 @@ export function createR2Sink(bucket, opts) {
         if (publicBase)
             return { ref: `${publicBase}/${key}`, key };
         if (signedBase && opts.sign) {
-            const { buildMediaUrl } = await import('../media-url.js');
             const signature = await opts.sign(key, expiresAtMs);
-            return { ref: buildMediaUrl(signedBase, key, expiresAtMs, signature), key, expiresAt: new Date(expiresAtMs).toISOString() };
+            // `signedLinks` is the ONE shape-owner shared with the upload-URL minter
+            // (src/signed-url.ts) — never hand-build the query here.
+            const link = (opts.links ?? signedLinks(signedBase)).media(key, expiresAtMs, signature);
+            return { ref: link, key, expiresAt: new Date(expiresAtMs).toISOString() };
         }
         // Neither configured. Unreachable in the Worker (which always passes its
         // own origin), so this is a misconfiguration rather than a mode — say so