@chrischall/gemini-mcp 1.4.0 → 1.5.0

package/dist/bundle.js

@@ -32805,7 +32805,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.4.0";
+var VERSION = "1.5.0";
 
 // src/tools/models.ts
 init_dist();
@@ -33102,7 +33102,7 @@ async function fetchRemoteImage(requestedUrl, opts = {}) {
 // src/inputs.ts
 function hasImageInput(args) {
   return Boolean(
-    args.images?.length || args.images_base64?.length || args.images_url?.length || args.images_file_uris?.length || args.from_clipboard
+    args.images?.length || args.images_base64?.length || args.images_url?.length || args.images_file_uris?.length || args.images_r2_keys?.length || args.from_clipboard
   );
 }
 var ASSUMED_TTL_MS = 47 * 60 * 60 * 1e3;
@@ -33151,6 +33151,32 @@ async function resolveImageInputs(args, client2) {
     (report.file_uris ??= []).push(file2.name);
     inputs.push(input);
   }
+  const seenKeys = /* @__PURE__ */ new Map();
+  for (const key of args.images_r2_keys ?? []) {
+    const hit = seenKeys.get(key);
+    if (hit) {
+      inputs.push(hit);
+      continue;
+    }
+    const stored = await client2.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 client2.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 : void 0 };
 }
 async function resolveLocalPath(path, client2, onDisk, report) {
@@ -33205,7 +33231,7 @@ async function resolveUrl(url2, client2, report) {
 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`."
+    "Provide at least one input image via `images_url` (an https URL the server fetches), `images_file_uris` (from gemini_upload_file), `images_r2_keys` (a hosted-connector upload or earlier generation), `images` (a local path), `images_base64`, or `from_clipboard`."
   );
 }
 
@@ -33238,6 +33264,96 @@ function downloadFilename(key) {
   return stripped || last;
 }
 
+// src/zip.ts
+var CRC_TABLE = (() => {
+  const table = new Uint32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 3988292384 ^ c >>> 1 : c >>> 1;
+    table[n] = c >>> 0;
+  }
+  return table;
+})();
+function crc32(bytes) {
+  let crc = 4294967295;
+  for (let i = 0; i < bytes.length; i++) {
+    crc = CRC_TABLE[(crc ^ bytes[i]) & 255] ^ crc >>> 8;
+  }
+  return (crc ^ 4294967295) >>> 0;
+}
+function dosDateTime(at) {
+  const year = Math.max(1980, at.getUTCFullYear());
+  return {
+    time: at.getUTCHours() << 11 | at.getUTCMinutes() << 5 | at.getUTCSeconds() >> 1,
+    date: year - 1980 << 9 | at.getUTCMonth() + 1 << 5 | at.getUTCDate()
+  };
+}
+var LOCAL_HEADER = 67324752;
+var CENTRAL_HEADER = 33639248;
+var EOCD = 101010256;
+var VERSION2 = 20;
+var FLAG_UTF8 = 2048;
+function buildZip(entries, modifiedAt = new Date(Date.UTC(1980, 0, 1))) {
+  const { time: time3, date: date5 } = dosDateTime(modifiedAt);
+  const encoder = new TextEncoder();
+  const parts = [];
+  const central = [];
+  let offset = 0;
+  for (const entry of entries) {
+    const name = encoder.encode(entry.name);
+    const crc = crc32(entry.bytes);
+    const size = entry.bytes.byteLength;
+    const local = new Uint8Array(30 + name.byteLength);
+    const lv = new DataView(local.buffer);
+    lv.setUint32(0, LOCAL_HEADER, true);
+    lv.setUint16(4, VERSION2, true);
+    lv.setUint16(6, FLAG_UTF8, true);
+    lv.setUint16(8, 0, true);
+    lv.setUint16(10, time3, true);
+    lv.setUint16(12, date5, true);
+    lv.setUint32(14, crc, true);
+    lv.setUint32(18, size, true);
+    lv.setUint32(22, size, true);
+    lv.setUint16(26, name.byteLength, true);
+    lv.setUint16(28, 0, true);
+    local.set(name, 30);
+    const dir = new Uint8Array(46 + name.byteLength);
+    const dv = new DataView(dir.buffer);
+    dv.setUint32(0, CENTRAL_HEADER, true);
+    dv.setUint16(4, VERSION2, true);
+    dv.setUint16(6, VERSION2, true);
+    dv.setUint16(8, FLAG_UTF8, true);
+    dv.setUint16(10, 0, true);
+    dv.setUint16(12, time3, true);
+    dv.setUint16(14, date5, true);
+    dv.setUint32(16, crc, true);
+    dv.setUint32(20, size, true);
+    dv.setUint32(24, size, true);
+    dv.setUint16(28, name.byteLength, true);
+    dv.setUint32(42, offset, true);
+    dir.set(name, 46);
+    parts.push(local, entry.bytes);
+    central.push(dir);
+    offset += local.byteLength + size;
+  }
+  const centralSize = central.reduce((n, c) => n + c.byteLength, 0);
+  const eocd = new Uint8Array(22);
+  const ev = new DataView(eocd.buffer);
+  ev.setUint32(0, EOCD, true);
+  ev.setUint16(8, entries.length, true);
+  ev.setUint16(10, entries.length, true);
+  ev.setUint32(12, centralSize, true);
+  ev.setUint32(16, offset, true);
+  const total = offset + centralSize + eocd.byteLength;
+  const out = new Uint8Array(total);
+  let cursor = 0;
+  for (const part of [...parts, ...central, eocd]) {
+    out.set(part, cursor);
+    cursor += part.byteLength;
+  }
+  return out;
+}
+
 // src/tools/shared.ts
 var DEFAULT_SINK = createDiskSink();
 var ASPECT_RATIOS = ["1:1", "2:3", "3:2", "3:4", "4:3", "4:5", "5:4", "9:16", "16:9", "21:9", "1:4", "4:1", "1:8", "8:1"];
@@ -33252,6 +33368,77 @@ var idempotencyKeySchema = external_exports.string().min(1).optional().describe(
 var asyncSchema = external_exports.boolean().optional().describe(
   "Run in the background and return a job_id immediately instead of the image, so a long (Pro/4K) generation cannot hit the host tools/call timeout (-32001). Poll gemini_get_result with the job_id to fetch the result (jobs are per-process and expire ~10 min after completion)."
 );
+var maxWaitMsSchema = external_exports.number().int().positive().max(6e5).optional().describe(
+  'Wait up to this many ms for the result; if generation is still running when the budget expires, return { job_id, status: "running" } immediately instead (poll gemini_get_result). Keeps fast results in-band while a slow batch can never trip the host tools/call timeout (-32001) \u2014 e.g. 20000 for multi-image sets. Ignored when async is set.'
+);
+function imagesR2KeysSchema(label = "Reference images") {
+  return external_exports.array(external_exports.string().min(1)).optional().describe(
+    `${label} by r2_key from THIS connector's store: a signed upload (gemini_get_upload_url \u2192 curl PUT) or an earlier generation's media[].r2_key. The server reads its own bucket directly \u2014 no bytes in the conversation, no signed URL, no ~48h Files API expiry. Hosted connector only.`
+  );
+}
+var charactersSchema = external_exports.array(external_exports.string().min(1)).max(8).optional().describe(
+  "Names of saved characters (see gemini_list_characters / gemini_save_character): each one's reference image and description are attached to the request automatically, keeping recurring subjects consistent without re-sending anything. Hosted connector only."
+);
+var styleSchema = external_exports.string().min(1).optional().describe(
+  "Name of a saved style preset (see gemini_list_styles / gemini_save_style): its prompt fragment \u2014 and reference image, if it has one \u2014 is applied to the request automatically. Hosted connector only."
+);
+async function resolveCharacterRefs(client2, names, styleName) {
+  if (!names?.length && !styleName) return { inputs: [] };
+  const library = client2.library;
+  if (!library) {
+    throw new McpToolError(
+      "`characters` / `style` reference this account's saved library, which exists on the hosted connector only. On this server pass the reference images directly (images / images_url / images_file_uris) and put the style text in the prompt."
+    );
+  }
+  const inputs = [];
+  const described = [];
+  const toInput = async (image, displayName) => {
+    if (image.bytes.byteLength <= IMAGE_INLINE_MAX_BYTES) {
+      return { base64: bytesToBase64(image.bytes), mimeType: image.mimeType };
+    }
+    const uploaded = await client2.uploadBytes(image.bytes, image.mimeType, displayName);
+    return { uri: uploaded.uri, mimeType: uploaded.mimeType };
+  };
+  for (const name of names ?? []) {
+    const record2 = await library.getCharacter(name);
+    const image = record2 && await library.readCharacterImage(name);
+    if (!record2 || !image) {
+      const available = (await library.listCharacters()).map((c) => c.name);
+      throw new McpToolError(
+        `No saved character "${name}". ` + (available.length ? `Saved characters: ${available.join(", ")}. ` : "None are saved yet. ") + "Save one with gemini_save_character."
+      );
+    }
+    inputs.push(await toInput(image, name));
+    described.push(`${record2.name} \u2014 ${record2.description}`);
+  }
+  let styleFragment;
+  let styleImageAttached = false;
+  if (styleName) {
+    const record2 = await library.getStyle(styleName);
+    if (!record2) {
+      const available = (await library.listStyles()).map((s) => s.name);
+      throw new McpToolError(
+        `No saved style "${styleName}". ` + (available.length ? `Saved styles: ${available.join(", ")}. ` : "None are saved yet. ") + "Save one with gemini_save_style."
+      );
+    }
+    styleFragment = record2.prompt_fragment;
+    if (record2.image_key) {
+      const image = await library.readStyleImage(styleName);
+      if (image) {
+        inputs.push(await toInput(image, styleName));
+        styleImageAttached = true;
+      }
+    }
+  }
+  const characterLine = described.length ? `Use the attached reference images for these characters, in order: ${described.map((d, i) => `(${i + 1}) ${d}`).join("; ")}. Keep each character visually consistent with their reference image.` + (styleImageAttached ? ` Attached image (${described.length + 1}) is a style reference, not a character.` : "") : styleImageAttached ? "The first attached image is a style reference." : void 0;
+  const meta3 = {};
+  if (names?.length) meta3.characters = names;
+  if (styleName) meta3.style = styleName;
+  return { inputs, characterLine, styleFragment, meta: Object.keys(meta3).length ? meta3 : void 0 };
+}
+function composePrompt(prompt, refs) {
+  return [refs.characterLine, prompt, refs.styleFragment ? `Style: ${refs.styleFragment}` : void 0].filter(Boolean).join("\n\n");
+}
 function imagesUrlSchema(label = "Reference images") {
   return external_exports.array(external_exports.string().url()).optional().describe(
     `${label} as public https URLs \u2014 the SERVER downloads them, so no image bytes travel through the conversation. Preferred over images_base64, which costs ~14k tokens per photo and breaks if a file read was truncated. Max ${wholeMb(IMAGE_URL_MAX_BYTES)}MB each; must be a directly-linked image (Content-Type image/*).`
@@ -33277,7 +33464,8 @@ var sharedImageSchema = {
   from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
   timeout_ms: timeoutMsSchema,
   idempotency_key: idempotencyKeySchema,
-  async: asyncSchema
+  async: asyncSchema,
+  max_wait_ms: maxWaitMsSchema
 };
 async function resolveVideoInput(args, client2) {
   if (args.video_url && args.video_path) {
@@ -33364,7 +33552,8 @@ async function emitMedia(named, kind, opts, meta3, onWritten) {
   }
   const sink = opts.sink ?? DEFAULT_SINK;
   const persisted = await sink.persist(named.map((n) => ({ base: n.base, base64: n.media.base64, mimeType: n.media.mimeType })), {
-    output_dir: opts.output_dir
+    output_dir: opts.output_dir,
+    urlTtlMs: opts.urlTtlMs
   });
   const refs = persisted.map((p) => p.ref);
   if (sink.persistsFiles) await onWritten?.(refs);
@@ -33393,6 +33582,40 @@ async function emitMedia(named, kind, opts, meta3, onWritten) {
 async function emit(named, opts, meta3, onWritten) {
   return emitMedia(named.map((n) => ({ media: n.image, base: n.base })), "image", opts, meta3, onWritten);
 }
+var SET_URL_TTL_MS = 7 * 24 * 60 * 60 * 1e3;
+var BUNDLE_MAX_TOTAL_BYTES = 24 * 1024 * 1024;
+async function persistBundle(named, sink, base) {
+  if (!sink || sink.persistsFiles || named.length < 2) return {};
+  const totalBytes = named.reduce((sum, n) => sum + Math.floor(n.image.base64.length * 3 / 4), 0);
+  if (totalBytes > BUNDLE_MAX_TOTAL_BYTES) {
+    return {
+      bundle_skipped: `The set totals ~${wholeMb(totalBytes)}MB decoded, over the ${wholeMb(BUNDLE_MAX_TOTAL_BYTES)}MB bundling cap (zipping peaks at ~4x that in Worker memory). Download the images individually via their media urls / curl_hints.`
+    };
+  }
+  try {
+    const { mediaExt: mediaExt2 } = await Promise.resolve().then(() => (init_images(), images_exports));
+    const zip = buildZip(named.map((n) => ({ name: `${n.base}.${mediaExt2(n.image.mimeType)}`, bytes: base64ToBytes(n.image.base64) })));
+    const [persisted] = await sink.persist(
+      [{ base: `${base}-bundle`, base64: bytesToBase64(zip), mimeType: "application/zip" }],
+      { urlTtlMs: SET_URL_TTL_MS }
+    );
+    if (!persisted || persisted.unavailable) {
+      return { bundle_skipped: "The bundle zip could not be stored; the images themselves are unaffected \u2014 download them individually via their media urls / curl_hints." };
+    }
+    return {
+      bundle_url: persisted.ref,
+      bundle: {
+        url: persisted.ref,
+        ...persisted.key ? { r2_key: persisted.key } : {},
+        ...persisted.expiresAt ? { expires_at: persisted.expiresAt } : {},
+        files: named.map((n) => n.base),
+        ...persisted.key ? { curl_hint: `curl -sS -o ${downloadFilename(persisted.key)} "${persisted.ref}"` } : {}
+      }
+    };
+  } catch {
+    return { bundle_skipped: "Bundling failed; the images themselves are unaffected \u2014 download them individually via their media urls / curl_hints." };
+  }
+}
 function assertLocalInputsAvailable(sink, args) {
   if ((sink ?? DEFAULT_SINK).persistsFiles) return;
   const unavailable = [];
@@ -33457,6 +33680,23 @@ async function refreshMedia(result, sink) {
   });
   body.media = entries;
   if (mediaKeyName) body[mediaKeyName] = refs;
+  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 {
+    }
+  }
   body.media_urls_refreshed = true;
   return { ...result, content: [{ ...first, text: JSON.stringify(body, null, 2) }, ...(result.content ?? []).slice(1)] };
 }
@@ -33486,6 +33726,22 @@ 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).`
   });
 }
+function awaitWithBudget(promise2, waitMs) {
+  return new Promise((resolve2, reject) => {
+    const timer = setTimeout(() => resolve2(void 0), waitMs);
+    timer.unref?.();
+    promise2.then(
+      (result) => {
+        clearTimeout(timer);
+        resolve2(result);
+      },
+      (err) => {
+        clearTimeout(timer);
+        reject(err);
+      }
+    );
+  });
+}
 var JobRegistry = class {
   /**
    * Lets a replayed result have its media URLs re-minted. Set by the session
@@ -33538,7 +33794,7 @@ var JobRegistry = class {
    * 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 !== void 0) {
@@ -33552,7 +33808,9 @@ var JobRegistry = class {
     }
     if (hit) {
       if (async) return jobHandle(hit.jobId, hit.status);
-      return annotateReused(await refreshMedia(await hit.promise, this.resigner), hit.jobId);
+      const settled = waitMs !== void 0 && hit.status === "running" ? await awaitWithBudget(hit.promise, waitMs) : await hit.promise;
+      if (settled === void 0) return jobHandle(hit.jobId, "running");
+      return annotateReused(await refreshMedia(settled, this.resigner), hit.jobId);
     }
     const jobId = randomUUID();
     this.evict(now);
@@ -33576,6 +33834,10 @@ var JobRegistry = class {
       if (this.runningByFingerprint.get(fingerprint) === jobId) this.runningByFingerprint.delete(fingerprint);
     });
     if (async) return jobHandle(jobId, "running");
+    if (waitMs !== void 0) {
+      const settled = await awaitWithBudget(promise2, waitMs);
+      return settled ?? jobHandle(jobId, "running");
+    }
     return promise2;
   }
   /**
@@ -33643,7 +33905,10 @@ function registerGenerateTools(server, client2) {
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to reference input images (image-conditioned generation)"),
         images_url: imagesUrlSchema(),
         images_file_uris: imagesFileUrisSchema(),
+        images_r2_keys: imagesR2KeysSchema(),
         images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation"),
+        characters: charactersSchema,
+        style: styleSchema,
         video_url: external_exports.string().url().optional().describe("Public YouTube URL (or a previously uploaded Files API uri) as a video reference (video\u2192image; use a Flash model e.g. gemini-3.1-flash-image)"),
         video_path: videoPathSchema,
         confirm: schemaConfirm,
@@ -33669,13 +33934,19 @@ function registerGenerateTools(server, client2) {
         from_clipboard: args.from_clipboard,
         images_url: args.images_url,
         images_file_uris: args.images_file_uris,
+        images_r2_keys: args.images_r2_keys,
+        characters: args.characters,
+        style: args.style,
         video_url: args.video_url,
         video_path: args.video_path
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_image_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_image_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
         const seed = pickSeed(args.seed);
         const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
-        const { inputs: refInputs, report } = await withProgressHeartbeat(extra, "Resolving reference images", () => resolveImageInputs(args, client2));
+        const charRefs = await resolveCharacterRefs(client2, args.characters, args.style);
+        const prompt = composePrompt(args.prompt, charRefs);
+        const { inputs: directInputs, report } = await withProgressHeartbeat(extra, "Resolving reference images", () => resolveImageInputs(args, client2));
+        const refInputs = [...charRefs.inputs, ...directInputs];
         const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args, client2));
         const named = [];
         let capturedText;
@@ -33686,7 +33957,7 @@ function registerGenerateTools(server, client2) {
           for (let i = 0; i < count; i++) {
             try {
               const result = await client2.generate({
-                prompt: args.prompt,
+                prompt,
                 images: refInputs.length > 0 ? refInputs : void 0,
                 model: args.model,
                 aspectRatio: args.aspect_ratio,
@@ -33713,6 +33984,7 @@ function registerGenerateTools(server, client2) {
         if (capturedText) meta3.text = capturedText;
         if (capturedGrounding) meta3.grounding = capturedGrounding;
         if (report) meta3.image_inputs = report;
+        if (charRefs.meta) Object.assign(meta3, charRefs.meta);
         if (failed.length) {
           meta3.failed_images = failed;
           meta3.partial = `${failed.length} of ${count} image(s) failed; the ${named.length} that succeeded are returned above. Re-run with count set to the shortfall rather than the whole batch \u2014 each failure message is in failed_images.`;
@@ -33735,7 +34007,10 @@ function registerGenerateTools(server, client2) {
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to input image file(s) (1 = edit, 2+ = compose)"),
         images_url: imagesUrlSchema("Input images"),
         images_file_uris: imagesFileUrisSchema("Input images"),
+        images_r2_keys: imagesR2KeysSchema("Input images"),
         images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Input images as base64 strings or data URIs. Last resort: prefer images_url or images_file_uris, which keep image bytes out of the conversation"),
+        characters: charactersSchema,
+        style: styleSchema,
         filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
         confirm: schemaConfirm,
         ...sharedImageSchema
@@ -33743,7 +34018,7 @@ function registerGenerateTools(server, client2) {
     },
     async (args, extra) => {
       assertLocalInputsAvailable(client2.mediaSink, args);
-      requireImageInput(args);
+      if (!args.characters?.length) requireImageInput(args);
       const gate = await previewLocalInputsUnlessConfirmed(args.confirm, SEND_LOCAL_ACTION, GENERATE_ENDPOINT, args.images);
       if (gate) return gate;
       const model = resolveModel(args.model, readEnvVar("GEMINI_IMAGE_MODEL"));
@@ -33758,14 +34033,20 @@ function registerGenerateTools(server, client2) {
         images_base64: args.images_base64,
         from_clipboard: args.from_clipboard,
         images_url: args.images_url,
-        images_file_uris: args.images_file_uris
+        images_file_uris: args.images_file_uris,
+        images_r2_keys: args.images_r2_keys,
+        characters: args.characters,
+        style: args.style
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_image_edit", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_image_edit", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
         const seed = pickSeed(args.seed);
         const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
-        const { inputs, report } = await withProgressHeartbeat(extra, "Resolving input images", () => resolveImageInputs(args, client2));
+        const charRefs = await resolveCharacterRefs(client2, args.characters, args.style);
+        const prompt = composePrompt(args.prompt, charRefs);
+        const { inputs: directInputs, report } = await withProgressHeartbeat(extra, "Resolving input images", () => resolveImageInputs(args, client2));
+        const inputs = [...charRefs.inputs, ...directInputs];
         const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client2.generate({
-          prompt: args.prompt,
+          prompt,
           images: inputs,
           model: args.model,
           aspectRatio: args.aspect_ratio,
@@ -33780,6 +34061,7 @@ function registerGenerateTools(server, client2) {
         if (text) meta3.text = text;
         if (result.grounding) meta3.grounding = result.grounding;
         if (report) meta3.image_inputs = report;
+        if (charRefs.meta) Object.assign(meta3, charRefs.meta);
         meta3.hint = REFINE_HINT;
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: client2.mediaSink?.persistsFiles });
         if (risk) meta3.timeout_risk = risk;
@@ -33797,7 +34079,7 @@ function registerSetTools(server, client2) {
   server.registerTool(
     "gemini_image_set",
     {
-      description: "Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master).",
+      description: 'Generate a consistent SET of images: a master image from master_prompt, then one image per scene that references the master so the subject/style stays consistent. Provide `scenes` (explicit per-image prompts) OR `count` (variations of the master). Scene generations run in parallel (reference_mode "master", the default). On the hosted connector: saved `characters` and a saved `style` can seed the whole set by name, multi-image results include a `bundle_url` zip of every image (one curl instead of N), and `max_wait_ms` returns a pollable job handle if the batch runs long.',
       annotations: { readOnlyHint: false, openWorldHint: true },
       inputSchema: {
         master_prompt: external_exports.string().min(1).describe("Prompt for the master/reference image"),
@@ -33808,6 +34090,9 @@ function registerSetTools(server, client2) {
         master_images: external_exports.array(external_exports.string().min(1)).optional().describe("Reference image paths passed to the master generation call"),
         master_images_url: imagesUrlSchema("Reference images passed to the master AND to every scene call (fetched once)"),
         master_images_file_uris: imagesFileUrisSchema("Reference images passed to the master AND to every scene call"),
+        master_images_r2_keys: imagesR2KeysSchema("Reference images passed to the master AND to every scene call"),
+        characters: charactersSchema,
+        style: styleSchema,
         master_images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs for master generation. Last resort: prefer master_images_url or master_images_file_uris, which keep image bytes out of the conversation"),
         confirm: schemaConfirm,
         ...sharedImageSchema
@@ -33835,27 +34120,34 @@ function registerSetTools(server, client2) {
         master_images_base64: args.master_images_base64,
         from_clipboard: args.from_clipboard,
         master_images_url: args.master_images_url,
-        master_images_file_uris: args.master_images_file_uris
+        master_images_file_uris: args.master_images_file_uris,
+        master_images_r2_keys: args.master_images_r2_keys,
+        characters: args.characters,
+        style: args.style
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_image_set", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_image_set", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
         const seed = pickSeed(args.seed);
         const cfg = { model: args.model, aspectRatio: args.aspect_ratio, imageSize: args.image_size, thinkingLevel: args.thinking_level, googleSearch: args.google_search, timeoutMs: args.timeout_ms };
         const slug = args.basename ? baseName(args.basename) : slugify2(args.master_prompt);
+        const charRefs = await resolveCharacterRefs(client2, args.characters, args.style);
+        const masterPrompt = composePrompt(args.master_prompt, charRefs);
+        const styleOnly = { styleFragment: charRefs.styleFragment };
         const carried = await resolveImageInputs(
-          { images_url: args.master_images_url, images_file_uris: args.master_images_file_uris },
+          { images_url: args.master_images_url, images_file_uris: args.master_images_file_uris, images_r2_keys: args.master_images_r2_keys },
           client2
         );
+        const carriedRefs = [...charRefs.inputs, ...carried.inputs];
         const masterOnly = await resolveImageInputs(
           { images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard },
           client2
         );
-        const masterRefInputs = [...masterOnly.inputs, ...carried.inputs];
+        const masterRefInputs = [...charRefs.inputs, ...masterOnly.inputs, ...carried.inputs];
         const failed = [];
         const report = carried.report || masterOnly.report ? { ...masterOnly.report, ...carried.report } : void 0;
         const named = [];
         const masterResult = await withProgressHeartbeat(extra, `Generating image set (${model})`, async () => {
           const result = await client2.generate({
-            prompt: args.master_prompt,
+            prompt: masterPrompt,
             images: masterRefInputs.length > 0 ? masterRefInputs : void 0,
             seed,
             ...cfg
@@ -33876,7 +34168,7 @@ function registerSetTools(server, client2) {
             let ref = master;
             for (let i = 0; i < scenePrompts.length; i++) {
               try {
-                const { images: [img] } = await client2.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
+                const { images: [img] } = await client2.generate({ prompt: composePrompt(scenePrompts[i], styleOnly), images: [ref, ...carriedRefs], seed: seed + i + 1, ...cfg });
                 named.push({ image: img, base: sceneName(i) });
                 ref = img;
               } catch (err) {
@@ -33885,7 +34177,7 @@ function registerSetTools(server, client2) {
             }
           } else {
             const settled = await Promise.allSettled(
-              scenePrompts.map((p, i) => client2.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
+              scenePrompts.map((p, i) => client2.generate({ prompt: composePrompt(p, styleOnly), images: [master, ...carriedRefs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
             );
             settled.forEach((outcome, i) => {
               if (outcome.status === "fulfilled") named.push({ image: outcome.value, base: sceneName(i) });
@@ -33899,13 +34191,15 @@ function registerSetTools(server, client2) {
         if (masterText) meta3.text = masterText;
         if (masterResult.grounding) meta3.grounding = masterResult.grounding;
         if (report) meta3.image_inputs = report;
+        if (charRefs.meta) Object.assign(meta3, charRefs.meta);
         if (failed.length) {
           meta3.failed_scenes = failed;
           meta3.partial = `${failed.length} of ${failed.length + named.length - 1} scene(s) failed; the master and the ${named.length - 1} scene(s) that succeeded are returned above. Re-run just the failed prompts rather than the whole set \u2014 each failure message is in failed_scenes.`;
         }
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, count: named.length, persistsFiles: client2.mediaSink?.persistsFiles });
         if (risk) meta3.timeout_risk = risk;
-        return emit(named, { ...args, sink: client2.mediaSink }, meta3);
+        if (!args.inline) Object.assign(meta3, await persistBundle(named, client2.mediaSink, slug));
+        return emit(named, { ...args, sink: client2.mediaSink, urlTtlMs: SET_URL_TTL_MS }, meta3);
       });
     }
   );
@@ -34070,8 +34364,14 @@ var GeminiClient = class {
    * 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;
     this.session.jobs.resigner = this.mediaSink;
     this.explicitApiKey = opts.apiKey?.trim() || void 0;
     this.fetchImpl = opts.fetchImpl ?? fetch;
@@ -34671,6 +34971,7 @@ function registerInteractTools(server, client2) {
         timeout_ms: timeoutMsSchema,
         idempotency_key: idempotencyKeySchema,
         async: asyncSchema,
+        max_wait_ms: maxWaitMsSchema,
         from_clipboard: external_exports.boolean().optional().describe("Use the image currently on the macOS system clipboard as an input (downscaled to JPEG)"),
         confirm: schemaConfirm
       }
@@ -34717,7 +35018,7 @@ function registerInteractTools(server, client2) {
         video_url: args.video_url,
         video_path: args.video_path
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_interact", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_interact", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
         const { inputs, report } = await resolveImageInputs({ ...args, images }, client2);
         const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args, client2));
         const callOpts = {
@@ -34821,6 +35122,7 @@ function registerVideoTools(server, client2) {
         timeout_ms: timeoutMsSchema,
         idempotency_key: idempotencyKeySchema,
         async: asyncSchema,
+        max_wait_ms: maxWaitMsSchema,
         confirm: schemaConfirm
       }
     },
@@ -34850,7 +35152,7 @@ function registerVideoTools(server, client2) {
         images_file_uris: args.images_file_uris,
         previous_interaction_id: previousInteractionId
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_video_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_video_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
         const { inputs, report } = await resolveImageInputs(args, client2);
         const r = await withProgressHeartbeat(extra, `Generating video (${model})`, () => client2.generateVideo({
           input: args.prompt,
@@ -34910,6 +35212,7 @@ function registerMusicTools(server, client2) {
         timeout_ms: timeoutMsSchema,
         idempotency_key: idempotencyKeySchema,
         async: asyncSchema,
+        max_wait_ms: maxWaitMsSchema,
         confirm: schemaConfirm
       }
     },
@@ -34943,7 +35246,7 @@ function registerMusicTools(server, client2) {
         images_file_uris: args.images_file_uris,
         previous_interaction_id: previousInteractionId
       });
-      return client2.session.jobs.dispatch({ toolName: "gemini_music_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
+      return client2.session.jobs.dispatch({ toolName: "gemini_music_generate", fingerprint, idempotencyKey: args.idempotency_key, async: args.async, waitMs: args.max_wait_ms }, async () => {
         const { inputs, report } = await resolveImageInputs(args, client2);
         const r = await withProgressHeartbeat(extra, `Generating music (${model})`, () => client2.generateMusic({
           input: args.prompt,

package/dist/client.js

@@ -153,8 +153,14 @@ 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;