@chrischall/gemini-mcp 1.4.0 → 1.5.1

package/dist/client.js

@@ -153,13 +153,30 @@ export class GeminiClient {
      * server is single-user, so its one singleton client is one session.
      */
     session = new SessionState();
+    /** Per-account character/style library — hosted connector only (see options). */
+    library;
+    /** Signed upload-URL minter — hosted connector only (see options). */
+    uploadUrls;
     constructor(opts = {}) {
         this.mediaSink = opts.mediaSink ?? createDiskSink();
+        this.library = opts.library;
+        this.uploadUrls = opts.uploadUrls;
         // 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;
         this.explicitApiKey = opts.apiKey?.trim() || undefined;
-        this.fetchImpl = opts.fetchImpl ?? fetch;
+        // Never store the global `fetch` raw on the instance: it would be invoked
+        // as `this.fetchImpl(...)`, handing native fetch this GeminiClient as its
+        // receiver — workerd rejects any non-global receiver with "Illegal
+        // invocation: function called with incorrect 'this' reference", while
+        // Node's fetch does not care, so only production could see the crash
+        // (it did: every hosted generation whose reference image took the >6MB
+        // Files-API promotion). The arrow pins the receiver to the global scope.
+        // An INJECTED impl is stored as-is, so tests can emulate workerd's
+        // receiver check and catch any `this.fetchImpl(...)` call site — which is
+        // also why call sites must alias it to a local before calling (see
+        // uploadToFilesApi). Guarded by tests/tools/hosted-reference-forms.test.ts.
+        this.fetchImpl = opts.fetchImpl ?? ((...args) => fetch(...args));
         this.sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
     }
     /**
@@ -337,9 +354,13 @@ export class GeminiClient {
      */
     async uploadToFilesApi(body, mimeType, displayName, contentLength) {
         const key = this.requireKey();
+        // Local alias so the calls below carry NO receiver: `this.fetchImpl(...)`
+        // would hand native fetch this GeminiClient as `this`, which workerd
+        // rejects with an Illegal invocation (see the constructor note).
+        const doFetch = this.fetchImpl;
         // 1. start — establish the resumable upload session
         const startPath = '/files';
-        const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
+        const startRes = await doFetch(`${UPLOAD_BASE_URL}${startPath}`, {
             method: 'POST',
             headers: {
                 'x-goog-api-key': key,
@@ -369,7 +390,7 @@ export class GeminiClient {
         // falls back to chunked encoding, which the resumable protocol does not
         // accept (this half is docs-derived; see docs/GEMINI-API.md).
         const streaming = !(body instanceof Blob);
-        const upRes = await this.fetchImpl(uploadUrl, {
+        const upRes = await doFetch(uploadUrl, {
             method: 'POST',
             headers: {
                 'X-Goog-Upload-Offset': '0',

package/dist/inputs.js

@@ -7,6 +7,7 @@ export function hasImageInput(args) {
         args.images_base64?.length ||
         args.images_url?.length ||
         args.images_file_uris?.length ||
+        args.images_r2_keys?.length ||
         args.from_clipboard);
 }
 /** Conservative TTL when the API doesn't tell us: documented retention is ~48h. */
@@ -75,6 +76,40 @@ export async function resolveImageInputs(args, client) {
         (report.file_uris ??= []).push(file.name);
         inputs.push(input);
     }
+    // 6. r2_keys — the connector reads its OWN store (tenant-gated), so a signed
+    // upload or an earlier generation becomes a reference without a fetch, a
+    // signature, or a byte in the conversation. Deduped within the call, same as
+    // URLs, and — also same as URLs — a large object is promoted to a Files API
+    // reference rather than inlined, because `generateContent` caps a whole
+    // request near 20MB and two large inline references would fail it.
+    // `readStoredMedia` throws an actionable error for a swept/foreign key.
+    const seenKeys = new Map();
+    for (const key of args.images_r2_keys ?? []) {
+        const hit = seenKeys.get(key);
+        if (hit) {
+            inputs.push(hit);
+            continue;
+        }
+        const stored = await client.readStoredMedia(key);
+        const entry = {
+            r2_key: key.trim(),
+            mime_type: stored.mimeType,
+            bytes: stored.bytes.byteLength,
+        };
+        (report.r2_keys ??= []).push(entry);
+        let input;
+        if (stored.bytes.byteLength <= IMAGE_INLINE_MAX_BYTES) {
+            input = { base64: bytesToBase64(stored.bytes), mimeType: stored.mimeType };
+        }
+        else {
+            const displayName = key.trim().split('/').pop() || 'image';
+            const uploaded = await client.uploadBytes(stored.bytes, stored.mimeType, displayName);
+            entry.file_uri = uploaded.name;
+            input = { uri: uploaded.uri, mimeType: uploaded.mimeType };
+        }
+        seenKeys.set(key, input);
+        inputs.push(input);
+    }
     return { inputs, report: Object.keys(report).length > 0 ? report : undefined };
 }
 /**
@@ -161,5 +196,6 @@ export function requireImageInput(args) {
     if (hasImageInput(args))
         return;
     throw new McpToolError('Provide at least one input image via `images_url` (an https URL the server fetches), `images_file_uris` ' +
-        '(from gemini_upload_file), `images` (a local path), `images_base64`, or `from_clipboard`.');
+        '(from gemini_upload_file), `images_r2_keys` (a hosted-connector upload or earlier generation), ' +
+        '`images` (a local path), `images_base64`, or `from_clipboard`.');
 }

package/dist/jobs.js

@@ -86,6 +86,25 @@ async function refreshMedia(result, sink) {
     body.media = entries;
     if (mediaKeyName)
         body[mediaKeyName] = refs;
+    // A multi-image set also carries a bundle zip; its link expires like any
+    // other and re-signs from its own r2_key. Best-effort, like the rest.
+    const bundle = body.bundle;
+    if (bundle && typeof bundle.r2_key === 'string') {
+        try {
+            const fresh = await sink.resign(bundle.r2_key);
+            if (fresh) {
+                const { expires_at: _staleBundle, ...rest } = bundle;
+                body.bundle = {
+                    ...rest,
+                    url: fresh.ref,
+                    ...(fresh.expiresAt ? { expires_at: fresh.expiresAt } : {}),
+                    curl_hint: `curl -sS -o ${downloadFilename(fresh.key ?? 'media')} "${fresh.ref}"`,
+                };
+                body.bundle_url = fresh.ref;
+            }
+        }
+        catch { /* an un-refreshed bundle link is still a valid replay */ }
+    }
     body.media_urls_refreshed = true;
     return { ...result, content: [{ ...first, text: JSON.stringify(body, null, 2) }, ...(result.content ?? []).slice(1)] };
 }
@@ -119,6 +138,19 @@ function jobHandle(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).`,
     });
 }
+/**
+ * Await `promise` for at most `waitMs`; `undefined` means the budget expired
+ * with the work still pending (rejections propagate as usual). The timer never
+ * holds the process open, and a late rejection after the budget expired is
+ * already handled by the registry's own settle handlers.
+ */
+function awaitWithBudget(promise, waitMs) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => resolve(undefined), waitMs);
+        timer.unref?.();
+        promise.then((result) => { clearTimeout(timer); resolve(result); }, (err) => { clearTimeout(timer); reject(err); });
+    });
+}
 /**
  * One session's jobs. Construct one per session and never share it — see the
  * cross-tenant note at the top of this file. Reachable as
@@ -181,7 +213,7 @@ export class JobRegistry {
      * different registry and therefore a genuinely separate generation.
      */
     async dispatch(opts, work) {
-        const { toolName, fingerprint, idempotencyKey, async } = opts;
+        const { toolName, fingerprint, idempotencyKey, async, waitMs } = opts;
         const now = Date.now();
         let hit;
         if (idempotencyKey !== undefined) {
@@ -199,10 +231,15 @@ export class JobRegistry {
         if (hit) {
             if (async)
                 return jobHandle(hit.jobId, hit.status);
+            const settled = waitMs !== undefined && hit.status === 'running'
+                ? await awaitWithBudget(hit.promise, waitMs)
+                : await hit.promise;
+            if (settled === undefined)
+                return jobHandle(hit.jobId, 'running');
             // Refresh before annotating: a recorded result can outlive the signed
             // URLs inside it, and replaying an expired link is its own kind of wrong
             // answer — it looks like success.
-            return annotateReused(await refreshMedia(await hit.promise, this.resigner), hit.jobId);
+            return annotateReused(await refreshMedia(settled, this.resigner), hit.jobId);
         }
         const jobId = randomUUID();
         this.evict(now);
@@ -222,6 +259,13 @@ export class JobRegistry {
         });
         if (async)
             return jobHandle(jobId, 'running');
+        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 promise;
     }
     /**

package/dist/library.js

@@ -0,0 +1,151 @@
+/**
+ * The per-account reference library: named characters (a reference image + a
+ * description) and named styles (a reusable prompt fragment, optionally with a
+ * reference image of its own).
+ *
+ * Why it exists: keeping a recurring subject consistent across generations
+ * means re-supplying the same reference image and the same description every
+ * session — re-uploading the photo, re-typing the description, re-explaining
+ * the style. The library makes each of those a NAME: save once, then pass
+ * `characters: ["finn"]` / `style: "bold-cartoon-sports"` on any generation.
+ *
+ * Storage is the connector's R2 bucket under `lib/<tenant>/…`:
+ *
+ *  - `lib/<tenant>/characters/<name>.json` — the record
+ *  - `lib/<tenant>/characters/<name>.img`  — the reference image bytes
+ *  - `lib/<tenant>/styles/<name>.json` (+ `.img` when a reference was given)
+ *
+ * Two properties are load-bearing:
+ *
+ *  - **No expiry.** The retention cron sweeps `gen/`, `media/` and `up/` but
+ *    deliberately never `lib/` (media-cleanup.ts) — a saved character outlives
+ *    every signed URL and every upload. That is why saving COPIES the image
+ *    bytes into `lib/` rather than storing an `r2_key` pointer: a pointer into
+ *    `gen/` or `up/` would dangle after the next sweep.
+ *  - **Tenant scoping by construction.** Every key this module touches is
+ *    derived from the session's own tenant id; caller-supplied names are
+ *    validated against a strict slug charset, so no name can address another
+ *    account's namespace (or escape `lib/` at all).
+ *
+ * Worker-safe: no node imports, no module-scope state, structural bucket type.
+ */
+/** Key prefix for the library — the one prefix the retention sweep must skip. */
+export const LIBRARY_KEY_PREFIX = 'lib';
+/**
+ * Library names are slugs: 1–40 chars, lowercase alphanumerics plus `-`/`_`,
+ * starting alphanumeric. Doubles as key-safety (no `/`, `.`, whitespace).
+ */
+export const LIBRARY_NAME_PATTERN = /^[a-z0-9][a-z0-9_-]{0,39}$/;
+export function isValidLibraryName(name) {
+    return LIBRARY_NAME_PATTERN.test(name);
+}
+/** Build the R2-backed library for one session. */
+export function createR2Library(bucket, opts) {
+    const now = opts.now ?? (() => new Date());
+    let tenantCache;
+    const tenantId = () => (tenantCache ??= Promise.resolve(typeof opts.tenant === 'function' ? opts.tenant() : opts.tenant));
+    const assertName = (name) => {
+        if (!isValidLibraryName(name)) {
+            throw new Error(`Invalid library name "${name}" — use 1-40 lowercase letters, digits, "-" or "_" (e.g. "finn", "bold-cartoon-sports").`);
+        }
+        return name;
+    };
+    const keyFor = async (kind, name, ext) => `${LIBRARY_KEY_PREFIX}/${await tenantId()}/${kind}/${assertName(name)}.${ext}`;
+    async function readJson(key) {
+        const object = await bucket.get(key);
+        if (!object)
+            return undefined;
+        try {
+            return JSON.parse(new TextDecoder().decode(await object.arrayBuffer()));
+        }
+        catch {
+            // A malformed record is unreadable, not fatal — callers treat it as absent.
+            return undefined;
+        }
+    }
+    async function readImage(kind, name) {
+        const object = await bucket.get(await keyFor(kind, name, 'img'));
+        if (!object)
+            return undefined;
+        return {
+            bytes: new Uint8Array(await object.arrayBuffer()),
+            mimeType: object.httpMetadata?.contentType ?? 'application/octet-stream',
+        };
+    }
+    async function listRecords(kind) {
+        const prefix = `${LIBRARY_KEY_PREFIX}/${await tenantId()}/${kind}/`;
+        const keys = [];
+        let cursor;
+        for (;;) {
+            const page = await bucket.list({ prefix, cursor, limit: 1000 });
+            keys.push(...page.objects.map((o) => o.key).filter((k) => k.endsWith('.json')));
+            if (!page.truncated)
+                break;
+            cursor = page.cursor;
+        }
+        const records = await Promise.all(keys.map((k) => readJson(k)));
+        return records
+            .filter((r) => r !== undefined)
+            .sort((a, b) => a.name.localeCompare(b.name));
+    }
+    async function deleteEntry(kind, name) {
+        const jsonKey = await keyFor(kind, name, 'json');
+        const existed = (await bucket.get(jsonKey)) !== null;
+        await bucket.delete([jsonKey, await keyFor(kind, name, 'img')]);
+        return existed;
+    }
+    return {
+        async saveCharacter({ name, description, image }) {
+            const jsonKey = await keyFor('characters', name, 'json');
+            const imageKey = await keyFor('characters', name, 'img');
+            const at = now().toISOString();
+            const existing = await readJson(jsonKey);
+            const record = {
+                name,
+                description,
+                image_key: imageKey,
+                mime_type: image.mimeType,
+                created_at: existing?.created_at ?? at,
+                updated_at: at,
+            };
+            await bucket.put(imageKey, image.bytes, { httpMetadata: { contentType: image.mimeType } });
+            await bucket.put(jsonKey, JSON.stringify(record, null, 2), { httpMetadata: { contentType: 'application/json' } });
+            return record;
+        },
+        async getCharacter(name) {
+            return readJson(await keyFor('characters', name, 'json'));
+        },
+        readCharacterImage: (name) => readImage('characters', name),
+        listCharacters: () => listRecords('characters'),
+        deleteCharacter: (name) => deleteEntry('characters', name),
+        async saveStyle({ name, promptFragment, image }) {
+            const jsonKey = await keyFor('styles', name, 'json');
+            const imageKey = await keyFor('styles', name, 'img');
+            const at = now().toISOString();
+            const existing = await readJson(jsonKey);
+            const record = {
+                name,
+                prompt_fragment: promptFragment,
+                ...(image ? { image_key: imageKey, mime_type: image.mimeType } : {}),
+                created_at: existing?.created_at ?? at,
+                updated_at: at,
+            };
+            if (image) {
+                await bucket.put(imageKey, image.bytes, { httpMetadata: { contentType: image.mimeType } });
+            }
+            else if (existing?.image_key) {
+                // Re-saving without an image REPLACES the style — a stale reference
+                // image left behind would silently keep steering generations.
+                await bucket.delete(imageKey);
+            }
+            await bucket.put(jsonKey, JSON.stringify(record, null, 2), { httpMetadata: { contentType: 'application/json' } });
+            return record;
+        },
+        async getStyle(name) {
+            return readJson(await keyFor('styles', name, 'json'));
+        },
+        readStyleImage: (name) => readImage('styles', name),
+        listStyles: () => listRecords('styles'),
+        deleteStyle: (name) => deleteEntry('styles', name),
+    };
+}

package/dist/media-cleanup.js

@@ -17,8 +17,11 @@ const DEFAULT_MAX_OBJECTS = 5_000;
  * `gen/` is where media is written now; `media/` is where it was written before
  * the rename that made URLs read `/media/gen/…` instead of `/media/media/…`.
  * Both are swept — retention that ignores the existing backlog is not retention.
+ * `up/` (signed uploads) is swept on the same schedule: a reference photo worth
+ * keeping gets copied into the character library (`lib/`), which is the ONE
+ * prefix deliberately absent here — saved characters and styles have no expiry.
  */
-const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/'];
+const LEGACY_AND_CURRENT_PREFIXES = ['gen/', 'media/', 'up/'];
 /** R2 accepts bulk deletes in batches; 1000 is the documented ceiling. */
 const DELETE_BATCH = 1_000;
 /** Days → ms, defaulting to 7 for anything missing or nonsensical. */

package/dist/media-endpoint.js

@@ -59,6 +59,12 @@ function baseHeaders(key, object, size) {
         // The bytes are model output being handed to a browser — never let a
         // sniffed content type turn an image response into something executable.
         'x-content-type-options': 'nosniff',
+        // Defense in depth against stored XSS: this route serves user-influenced
+        // bytes from the SAME ORIGIN as the connector's OAuth pages, so if a
+        // scriptable document type (SVG, HTML) ever slipped past the raster-only
+        // upload gates, this neutralizes it — no script, no fetch, and a unique
+        // opaque origin via sandbox. Pixels don't need any of what this disables.
+        'content-security-policy': "default-src 'none'; sandbox",
         // Range support is cheap on R2 and is what makes a resumable `curl -C -`
         // work against a large video.
         'accept-ranges': 'bytes',

package/dist/media-url.js

@@ -19,14 +19,14 @@
 export const MEDIA_URL_TTL_MS = 48 * 60 * 60 * 1000;
 /** KV key holding the lazily-generated signing secret (zero-config path). */
 export const SIGNING_SECRET_KV_KEY = 'media:url-signing-secret';
-function base64UrlEncode(bytes) {
+export function base64UrlEncode(bytes) {
     const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
     let binary = '';
     for (let i = 0; i < view.length; i++)
         binary += String.fromCharCode(view[i]);
     return btoa(binary).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
 }
-function base64UrlDecode(text) {
+export function base64UrlDecode(text) {
     const padded = text.replace(/-/g, '+').replace(/_/g, '/').padEnd(Math.ceil(text.length / 4) * 4, '=');
     const binary = atob(padded);
     const out = new Uint8Array(binary.length);

package/dist/put-endpoint.js

@@ -0,0 +1,122 @@
+import { loadSigningKey } from './media-url.js';
+import { verifyUploadSignature, UPLOAD_MAX_BYTES, UPLOAD_KEY_PREFIX, acceptableUploadType } from './upload-url.js';
+import { wholeMb } from './bytes.js';
+function json(body, status) {
+    return new Response(JSON.stringify(body, null, 2), {
+        status,
+        headers: { 'content-type': 'application/json; charset=utf-8', 'cache-control': 'no-store' },
+    });
+}
+/** Every error names the fix — the caller here is a shell, not a model. */
+function fail(status, error, hint) {
+    return json({ error, hint }, status);
+}
+/** A key this endpoint is willing to even verify a signature for: the upload
+ * prefix, safe segment charset, no dot-segments, no empty segments. */
+export function wellFormedUploadKey(key) {
+    if (!key.startsWith(`${UPLOAD_KEY_PREFIX}/`))
+        return false;
+    const segments = key.split('/');
+    if (segments.length < 2)
+        return false;
+    return segments.every((s) => s.length > 0 && s !== '.' && s !== '..' && /^[A-Za-z0-9._-]+$/.test(s));
+}
+/**
+ * Build the `/put` handler. `basePath` is stripped from the pathname to get the
+ * R2 key, mirroring the `/media` handler so the two never drift.
+ */
+export function createSignedPutHandler(env, basePath = '/put/') {
+    const maxBytes = env.maxBytes ?? UPLOAD_MAX_BYTES;
+    return async function handleSignedPut(request) {
+        if (request.method === 'OPTIONS') {
+            return new Response(null, { status: 204, headers: { allow: 'PUT, OPTIONS' } });
+        }
+        if (request.method !== 'PUT') {
+            return fail(405, `Method ${request.method} not allowed; signed upload URLs are PUT-only.`, 'Send the file bytes with: curl -sS -X PUT -H "Content-Type: <the signed type>" --data-binary @photo.jpg "<upload_url>"');
+        }
+        const url = new URL(request.url);
+        if (!url.pathname.startsWith(basePath))
+            return fail(404, 'Not found.', 'Use the exact upload_url returned by gemini_get_upload_url.');
+        const key = url.pathname
+            .slice(basePath.length)
+            .split('/')
+            .map((segment) => {
+            try {
+                return decodeURIComponent(segment);
+            }
+            catch {
+                return segment;
+            }
+        })
+            .join('/');
+        // Charset-checked BEFORE signature verification: the cross-protocol safety
+        // argument in upload-url.ts rests on keys never containing control chars.
+        if (!wellFormedUploadKey(key)) {
+            return fail(404, 'Not a valid upload key.', 'Use the exact upload_url returned by gemini_get_upload_url — the key path cannot be altered.');
+        }
+        const ct = url.searchParams.get('ct');
+        if (ct && !acceptableUploadType(ct)) {
+            return fail(415, `Unsupported content type "${ct}" — signed uploads accept raster image types only ` +
+                '(jpeg/png/webp/gif/avif/heic/heif/bmp/tiff; not SVG, which can carry scripts).', 'Mint the URL with a raster image content_type (e.g. image/jpeg).');
+        }
+        const now = env.now?.() ?? Date.now();
+        // Read-only key load: verification must never CREATE a signing secret (see
+        // loadSigningKey — a stale KV read would clobber the secret every
+        // outstanding media link was signed with).
+        const signingKey = await loadSigningKey(env.secret, env.store);
+        const check = signingKey
+            ? await verifyUploadSignature(signingKey, key, ct, url.searchParams.get('exp'), url.searchParams.get('sig'), now)
+            : { ok: false, reason: 'invalid' };
+        if (!check.ok) {
+            if (check.reason === 'expired') {
+                return fail(410, 'This upload URL has expired (they are valid for ~10 minutes).', 'Mint a fresh one with gemini_get_upload_url and retry.');
+            }
+            return fail(403, 'Invalid or missing upload signature.', 'Use the upload_url exactly as returned by gemini_get_upload_url, including the ct, exp and sig query parameters.');
+        }
+        const sentType = (request.headers.get('content-type') ?? '').split(';')[0].trim().toLowerCase();
+        if (sentType !== ct) {
+            return fail(415, `Content-Type "${sentType || '(none)'}" does not match the type this URL was minted for ("${ct}").`, `Send -H "Content-Type: ${ct}", or mint a new URL with the right content_type.`);
+        }
+        const declared = Number(request.headers.get('content-length'));
+        if (!request.headers.get('content-length') || !Number.isFinite(declared) || declared <= 0) {
+            return fail(411, 'Content-Length is required (and must be > 0).', 'curl sets it automatically with --data-binary @file.');
+        }
+        if (declared > maxBytes) {
+            return fail(413, `Upload is ${wholeMb(declared)}MB; the cap is ${wholeMb(maxBytes)}MB.`, 'Downscale the image before uploading — a reference photo does not need to be full-resolution.');
+        }
+        if (!request.body) {
+            return fail(400, 'Request had no body.', 'Send the file bytes as the request body, e.g. --data-binary @photo.jpg.');
+        }
+        // Enforce the cap on bytes actually READ, not the declared length — a
+        // hostile client can under-declare and stream more.
+        const chunks = [];
+        let total = 0;
+        const reader = request.body.getReader();
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            total += value.byteLength;
+            if (total > maxBytes) {
+                await reader.cancel().catch(() => { });
+                return fail(413, `Upload exceeded the ${wholeMb(maxBytes)}MB cap while being read.`, 'Downscale the image before uploading.');
+            }
+            chunks.push(value);
+        }
+        const body = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            body.set(chunk, offset);
+            offset += chunk.byteLength;
+        }
+        await env.bucket.put(key, body, { httpMetadata: { contentType: ct ?? 'application/octet-stream' } });
+        return json({
+            r2_key: key,
+            size_bytes: total,
+            content_type: ct,
+            hint: `Uploaded. Reference it by r2_key: pass it in images_r2_keys on a generation tool (master_images_r2_keys on gemini_image_set), ` +
+                `save it permanently with gemini_save_character, or convert it to a ~48h Gemini Files API reference with gemini_upload_file({ r2_key }). ` +
+                `Uploads follow the connector's media retention schedule (MEDIA_TTL_DAYS, default 7 days); saved characters are kept indefinitely.`,
+        }, 201);
+    };
+}

package/dist/storage/media.js

@@ -45,7 +45,7 @@ export async function tenantIdFor(secret) {
 // prefix would make every URL read `/media/media/…`.
 const KEY_PREFIX_DEFAULT = 'gen';
 /** Object-key-safe name: no slashes, no dot-segments, never empty. */
-function safeKeySegment(base) {
+export function safeKeySegment(base) {
     const cleaned = base
         .replace(/[^A-Za-z0-9._-]+/g, '-')
         .replace(/\.{2,}/g, '-')
@@ -67,18 +67,27 @@ export function createR2Sink(bucket, opts) {
     const publicBase = opts.publicBaseUrl?.replace(/\/+$/, '');
     const signedBase = opts.signedBaseUrl?.replace(/\/+$/, '');
     const ttlMs = opts.urlTtlMs ?? 0;
-    /** `<prefix>/` or `<prefix>/<tenant>/` — every key this sink may touch. */
-    let ownPrefixCache;
-    const ownPrefix = () => (ownPrefixCache ??= (async () => {
-        const tenant = typeof opts.tenant === 'function' ? await opts.tenant() : opts.tenant;
+    const readPrefixes = [prefix, ...(opts.readPrefixes ?? [])];
+    let tenantCache;
+    const tenantId = () => (tenantCache ??= Promise.resolve(typeof opts.tenant === 'function' ? opts.tenant() : opts.tenant));
+    /** `<prefix>/` or `<prefix>/<tenant>/` — where every WRITE goes. */
+    const ownPrefix = async () => {
+        const tenant = await tenantId();
         return tenant ? `${prefix}/${tenant}/` : `${prefix}/`;
-    })());
+    };
     /**
-     * Ownership gate for caller-supplied keys. A foreign key is refused without
-     * touching storage, so the refusal is indistinguishable from a swept object.
-     * With no tenant configured there is nothing to enforce (single-user shapes).
+     * Ownership gate for caller-supplied keys: this session's own namespace
+     * under any readable prefix (`gen/<tenant>/…`, plus e.g. `up/`/`lib/` on the
+     * Worker). A foreign key is refused without touching storage, so the refusal
+     * is indistinguishable from a swept object. With no tenant configured there
+     * is nothing to enforce (single-user shapes).
      */
-    const owned = async (key) => !opts.tenant || key.startsWith(await ownPrefix());
+    const owned = async (key) => {
+        if (!opts.tenant)
+            return true;
+        const tenant = await tenantId();
+        return readPrefixes.some((p) => key.startsWith(`${p}/${tenant}/`));
+    };
     return {
         kind: 'r2',
         persistsFiles: false,
@@ -102,14 +111,16 @@ export function createR2Sink(bucket, opts) {
                 return undefined;
             return describe(key, now().getTime() + ttlMs);
         },
-        async persist(items, _opts) {
+        async persist(items, persistOpts) {
             // `mediaExt` is pure string work but lives in images.ts next to node:fs
             // imports; the dynamic import keeps that module off a Worker's eager
             // module graph.
             const { mediaExt } = await import('../images.js');
             const keyBase = await ownPrefix();
             const day = now().toISOString().slice(0, 10);
-            const expiresAtMs = now().getTime() + ttlMs;
+            // Per-persist TTL override, clamped so a link never outlives its object.
+            const effectiveTtlMs = Math.min(persistOpts.urlTtlMs ?? ttlMs, opts.maxUrlTtlMs ?? Infinity);
+            const expiresAtMs = now().getTime() + effectiveTtlMs;
             const refs = [];
             for (const it of items) {
                 const key = `${keyBase}${day}/${randomId()}-${safeKeySegment(it.base)}.${mediaExt(it.mimeType)}`;