@chrischall/gemini-mcp 1.6.2 → 1.8.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,124 @@ 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.interactionId !== undefined ? { interactionId: entry.interactionId } : {}),
+            ...(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 +363,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 +383,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);
@@ -243,31 +406,98 @@ export class JobRegistry {
         }
         const jobId = randomUUID();
         this.evict(now);
-        const promise = work();
-        const entry = { jobId, toolName, fingerprint, idempotencyKey, status: 'running', promise, createdAt: now };
+        // The work starts before `entry` can exist (the entry holds its promise),
+        // yet a well-behaved job reports its interaction id in its very first
+        // `await` — synchronously, from here's point of view. Dropping that report
+        // would lose exactly the ids that arrive fastest, so it is held until the
+        // entry is there and folded into the record's first write.
+        let entry;
+        let earlyInteractionId;
+        const ctx = {
+            reportInteraction: (interactionId) => {
+                if (!entry) {
+                    earlyInteractionId = interactionId;
+                    return;
+                }
+                if (entry.interactionId === interactionId)
+                    return;
+                entry.interactionId = interactionId;
+                if (this.store)
+                    this.track(this.writeRecord(entry));
+            },
+        };
+        const promise = work(ctx);
+        entry = {
+            jobId, toolName, fingerprint, idempotencyKey, status: 'running', promise, createdAt: now,
+            ...(earlyInteractionId !== undefined ? { interactionId: earlyInteractionId } : {}),
+        };
         this.jobs.set(jobId, entry);
         if (idempotencyKey !== undefined)
             this.byKey.set(idempotencyKey, jobId);
         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 +507,67 @@ 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) {
+    /**
+     * The durable record for `jobId`, if there is one — including the
+     * executor-lost rewrite. Read-only view for a caller that wants to act on a
+     * record's contents (see `tools/jobs.ts` recovering an interaction id) rather
+     * than just render it.
+     */
+    async peekRecord(jobId) {
+        return this.store ? await this.store.get(jobId) : undefined;
+    }
+    /**
+     * Adopt a result produced OUTSIDE this registry — recovery reading a lost
+     * job's output back off the upstream interaction (`tools/jobs.ts`).
+     *
+     * Without this the job stays `failed` and every later poll re-enters
+     * recovery: another interaction fetch, another media download, and another
+     * copy on disk (`…-2.mp4`, `…-3.mp4`) or in R2, with nothing telling the
+     * caller they are duplicates. The ordinary done path is idempotent, so this
+     * one has to be too.
+     */
+    async adoptResult(jobId, toolName, result, interactionId) {
+        const now = this.now();
+        let entry = this.jobs.get(jobId);
+        if (!entry) {
+            // A different child ran the job, so there is nothing in memory to update.
+            // The synthetic entry exists only to render the record and to answer the
+            // next poll from this session; its fingerprint is namespaced so it can
+            // never collide with (or dedup against) a real request identity.
+            entry = {
+                jobId,
+                toolName,
+                fingerprint: `recovered:${jobId}`,
+                status: 'done',
+                promise: Promise.resolve(result),
+                createdAt: now,
+            };
+            this.jobs.set(jobId, entry);
+        }
+        entry.status = 'done';
+        entry.result = result;
+        entry.settledAt = now;
+        if (interactionId !== undefined)
+            entry.interactionId = interactionId;
+        if (this.store)
+            await this.writeRecord(entry);
+    }
+    async getResult(jobId) {
         const entry = this.jobs.get(jobId);
         if (!entry) {
-            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 +578,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.**