@chrischall/gemini-mcp 1.6.1 → 1.7.0

package/dist/client.js

@@ -5,6 +5,7 @@ import { createDiskSink, createR2Sink, tenantIdFor } from './storage/media.js';
 import { createR2Library } from './library.js';
 import { createUploadUrlMinter } from './upload-url.js';
 import { blobStoreFromEnv } from './blob-store.js';
+import { createBlobJobStore } from './job-store.js';
 import { SessionState } from './session.js';
 import { fetchRemoteImage } from './fetch-image.js';
 // NOTE: this module must stay SIDE-EFFECT-FREE at module scope — no I/O, no
@@ -167,6 +168,14 @@ export class GeminiClient {
         // A replayed idempotent result must not hand back an expired media URL, so
         // the job registry needs a way to re-sign from the stable r2_key.
         this.session.jobs.resigner = this.mediaSink;
+        // Durable job records, where the deployment has somewhere to keep them.
+        // Without this the hosted connector loses a job the moment its machine
+        // stops — which it does as soon as no request is in flight (job-store.ts).
+        this.session.jobs.store = opts.jobStore;
+        // And on that runtime, `async: true` is served by HOLDING the request:
+        // releasing it is what lets the executor be reclaimed mid-generation.
+        if (opts.jobStore)
+            this.session.jobs.asyncWaitFallbackMs = HOSTED_ASYNC_WAIT_MS;
         this.explicitApiKey = opts.apiKey?.trim() || undefined;
         // Never store the global `fetch` raw on the instance: it would be invoked
         // as `this.fetchImpl(...)`, handing native fetch this GeminiClient as its
@@ -776,7 +785,11 @@ function hostedStorage() {
     const tenant = () => tenantIdFor(readEnvVar('GEMINI_API_KEY') ?? 'local');
     return {
         mediaSink: createR2Sink(blob.bucket, {
-            signedBaseUrl: blob.baseUrl,
+            // The SAME `links` object the minter gets below. Media GETs and upload
+            // PUTs are one store reached two ways; handing each its own base URL is
+            // how the re-host moved the media links to /b/<registrationId>/ and left
+            // the upload links behind. One object, two shapes, no second edit.
+            links: blob.links,
             sign: blob.signRead,
             urlTtlMs: BLOB_URL_TTL_MS,
             // Hard ceiling on any PER-PERSIST override. `gemini_image_set` asks for
@@ -792,9 +805,25 @@ function hostedStorage() {
             tenant,
         }),
         library: createR2Library(blob.bucket, { tenant }),
-        uploadUrls: createUploadUrlMinter({ baseUrl: blob.baseUrl, sign: blob.signWrite, tenant }),
+        uploadUrls: createUploadUrlMinter({ links: blob.links, sign: blob.signWrite, tenant }),
+        // Job records go in the same store as the media, for the same reason: this
+        // runtime's machine stops whenever no request is in flight, taking the
+        // child — and an in-memory registry — with it (src/job-store.ts).
+        jobStore: createBlobJobStore(blob.bucket, { tenant }),
     };
 }
+/**
+ * How long a hosted `async: true` call holds the request open before handing
+ * back a job id.
+ *
+ * Not a tuning knob so much as the shape of the platform: holding the request
+ * is what keeps the executor alive, so this is "how long we are willing to keep
+ * the machine up for one generation". Four minutes is the value observed to
+ * work in practice against claude.ai, and comfortably covers a Pro/4K image or
+ * a modest set; anything slower hands back a durable job id rather than
+ * silently dying, which is the behaviour this whole change is for.
+ */
+const HOSTED_ASYNC_WAIT_MS = 240_000;
 /**
  * How long a freshly-minted media link lives.
  *

package/dist/errors.js

@@ -0,0 +1,120 @@
+/**
+ * Making a failure say what actually failed.
+ *
+ * A hosted `gemini_get_upload_url` call came back to the client as
+ * `{"error": "Error occurred during tool execution", "request_id": "req_…"}` —
+ * no message, no failing step, no stack. That outer wrapper is the client's and
+ * not ours to change, but it is only ever reached when what we hand back is
+ * itself uninformative, and two of this repo's habits make that likely:
+ *
+ *  - a thrown non-`McpToolError` surfaces as bare `err.message`, which for a
+ *    runtime fault (`Illegal invocation`, `fetch failed`) names neither the
+ *    tool nor the operation that was in flight; and
+ *  - `cause` is dropped by MCP serialization, so a wrapped error arrives with
+ *    its actual root cause deleted — the trap `ChainedRequest404Error` in
+ *    client.ts already documents for `hint`, which the host drops too.
+ *
+ * So: {@link describeError} flattens the whole chain into the message,
+ * {@link step} labels the operation, and {@link surfaceToolErrors} wraps a
+ * server so EVERY registered handler gets both without each registrar
+ * remembering to. `index.ts` applies it to every registrar in the list.
+ */
+import { McpToolError } from '@chrischall/mcp-utils';
+/** How far down a `cause` chain to walk before assuming it is pathological. */
+const MAX_CAUSE_DEPTH = 5;
+/**
+ * One flat, self-describing line for anything throwable — including the
+ * `cause` chain, which MCP serialization deletes.
+ *
+ * The error's class name is prefixed only when it carries information: a bare
+ * `Error` says nothing a reader does not already know, while `TypeError:
+ * Illegal invocation` is the entire diagnosis of the workerd receiver bug (see
+ * the fetchImpl note in CLAUDE.md).
+ */
+export function describeError(err) {
+    const seen = new Set();
+    const describe = (value, depth) => {
+        if (!(value instanceof Error)) {
+            if (typeof value === 'string')
+                return value;
+            try {
+                return typeof value === 'object' && value !== null ? JSON.stringify(value) : String(value);
+            }
+            catch {
+                return String(value);
+            }
+        }
+        // A generic `Error` name is noise; anything else is the diagnosis.
+        const named = value.name && value.name !== 'Error' && value.name !== 'McpToolError'
+            ? `${value.name}: ${value.message}`
+            : value.message;
+        const hint = value instanceof McpToolError && value.hint && !value.message.includes(value.hint)
+            ? ` ${value.hint}`
+            : '';
+        const cause = value.cause;
+        // Self-referential and over-deep chains are real (a retry wrapper that
+        // re-wraps its own error); walking one forever is not an option.
+        if (cause === undefined || cause === null || depth >= MAX_CAUSE_DEPTH || seen.has(cause)) {
+            return `${named}${hint}`;
+        }
+        seen.add(cause);
+        return `${named}${hint} [caused by: ${describe(cause, depth + 1)}]`;
+    };
+    seen.add(err);
+    return describe(err, 0);
+}
+/**
+ * Run one named operation, and on failure say which one it was.
+ *
+ * Only the INNERMOST step labels: an already-labelled failure passes straight
+ * through, so a nested `step` reports `signing the upload URL: …` rather than
+ * `minting: signing the upload URL: …`. The label is what the caller needs;
+ * the call stack above it is not.
+ */
+export async function step(label, run) {
+    try {
+        return await run();
+    }
+    catch (err) {
+        if (err instanceof StepError)
+            throw err;
+        throw new StepError(`${label}: ${describeError(err)}`, err);
+    }
+}
+/** An `McpToolError` that has already been attributed to a step. */
+class StepError extends McpToolError {
+    constructor(message, cause) {
+        super(message, { cause });
+        this.name = 'McpToolError';
+    }
+}
+/**
+ * Wrap a server so every tool registered through it reports failures fully.
+ *
+ * A `Proxy` rather than a spread: `McpServer` methods are bound to real private
+ * state, and registrars reach for more than `registerTool` (`server.server`,
+ * `registerResource`). Everything but `registerTool` passes through untouched,
+ * and a successful result is returned byte-identically — this only ever changes
+ * what an exception looks like.
+ */
+export function surfaceToolErrors(server) {
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            const value = Reflect.get(target, prop, receiver);
+            if (prop !== 'registerTool' || typeof value !== 'function') {
+                return typeof value === 'function' ? value.bind(target) : value;
+            }
+            return (name, config, handler) => value.call(target, name, config, async (...args) => {
+                try {
+                    return await handler(...args);
+                }
+                catch (err) {
+                    // Named for the tool AND the underlying error. When the client
+                    // still shows its own generic wrapper, this text is what a
+                    // maintainer has to work from — so it carries everything.
+                    throw new McpToolError(`${name} failed: ${describeError(err)}`, { cause: err });
+                }
+            });
+        },
+    });
+}

package/dist/index.js

@@ -2,16 +2,7 @@
 import { runMcp } from '@chrischall/mcp-utils';
 import { loadStdioDotenv } from './dotenv.js';
 import { VERSION } from './version.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';
+import { TOOL_REGISTRARS } from './registrars.js';
 import { client } from './client.js';
 // Load `.env` here rather than in client.ts: `import.meta.url` + async I/O at
 // module scope is not safe in every runtime this module graph reaches (see
@@ -29,24 +20,14 @@ await loadStdioDotenv();
 // boots and answers the host's install-time tools/list probe even without
 // GEMINI_API_KEY. It also owns this process's session state (job registry,
 // last-interaction memory); stdio is single-user, so one client is one session.
+//
+// The roster itself lives in registrars.ts: this file cannot be imported
+// without booting a server, and a list nothing can import is a list nothing
+// can test (see the note there).
 await runMcp({
     name: 'gemini-mcp',
     version: VERSION,
     banner: '[gemini-mcp] This project was developed and is maintained by AI (Claude). Use at your own discretion.',
-    tools: [
-        registerModelTools,
-        registerGenerateTools,
-        registerSetTools,
-        registerInteractTools,
-        registerVideoTools,
-        registerMusicTools,
-        registerJobTools,
-        registerFileTools,
-        // Both gate on the client having somewhere to put bytes: hosted with a
-        // blob store they register, and on a local install they no-op rather than
-        // advertising a tool that cannot work.
-        registerUploadUrlTools,
-        registerLibraryTools,
-    ],
+    tools: TOOL_REGISTRARS,
     deps: client,
 });

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;
+        },
+    };
+}