@chrischall/gemini-mcp 1.0.3 → 1.1.0

package/dist/bundle.js

@@ -1109,11 +1109,11 @@ var init_types = __esm({
               status.dirty();
             }
           } else if (check2.kind === "length") {
-            const tooBig = input.data.length > check2.value;
+            const tooBig2 = input.data.length > check2.value;
             const tooSmall = input.data.length < check2.value;
-            if (tooBig || tooSmall) {
+            if (tooBig2 || tooSmall) {
               ctx = this._getOrReturnCtx(input, ctx);
-              if (tooBig) {
+              if (tooBig2) {
                 addIssueToContext(ctx, {
                   code: ZodIssueCode.too_big,
                   maximum: check2.value,
@@ -1660,8 +1660,8 @@ var init_types = __esm({
               status.dirty();
             }
           } else if (check2.kind === "max") {
-            const tooBig = check2.inclusive ? input.data > check2.value : input.data >= check2.value;
-            if (tooBig) {
+            const tooBig2 = check2.inclusive ? input.data > check2.value : input.data >= check2.value;
+            if (tooBig2) {
               ctx = this._getOrReturnCtx(input, ctx);
               addIssueToContext(ctx, {
                 code: ZodIssueCode.too_big,
@@ -1877,8 +1877,8 @@ var init_types = __esm({
               status.dirty();
             }
           } else if (check2.kind === "max") {
-            const tooBig = check2.inclusive ? input.data > check2.value : input.data >= check2.value;
-            if (tooBig) {
+            const tooBig2 = check2.inclusive ? input.data > check2.value : input.data >= check2.value;
+            if (tooBig2) {
               ctx = this._getOrReturnCtx(input, ctx);
               addIssueToContext(ctx, {
                 code: ZodIssueCode.too_big,
@@ -2292,13 +2292,13 @@ var init_types = __esm({
           return INVALID;
         }
         if (def.exactLength !== null) {
-          const tooBig = ctx.data.length > def.exactLength.value;
+          const tooBig2 = ctx.data.length > def.exactLength.value;
           const tooSmall = ctx.data.length < def.exactLength.value;
-          if (tooBig || tooSmall) {
+          if (tooBig2 || tooSmall) {
             addIssueToContext(ctx, {
-              code: tooBig ? ZodIssueCode.too_big : ZodIssueCode.too_small,
+              code: tooBig2 ? ZodIssueCode.too_big : ZodIssueCode.too_small,
               minimum: tooSmall ? def.exactLength.value : void 0,
-              maximum: tooBig ? def.exactLength.value : void 0,
+              maximum: tooBig2 ? def.exactLength.value : void 0,
               type: "array",
               inclusive: true,
               exact: true,
@@ -5462,10 +5462,10 @@ var init_checks = __esm({
         const size = input.size;
         if (size === def.size)
           return;
-        const tooBig = size > def.size;
+        const tooBig2 = size > def.size;
         payload.issues.push({
           origin: getSizableOrigin(input),
-          ...tooBig ? { code: "too_big", maximum: def.size } : { code: "too_small", minimum: def.size },
+          ...tooBig2 ? { code: "too_big", maximum: def.size } : { code: "too_small", minimum: def.size },
           inclusive: true,
           exact: true,
           input: payload.value,
@@ -5551,10 +5551,10 @@ var init_checks = __esm({
         if (length === def.length)
           return;
         const origin = getLengthableOrigin(input);
-        const tooBig = length > def.length;
+        const tooBig2 = length > def.length;
         payload.issues.push({
           origin,
-          ...tooBig ? { code: "too_big", maximum: def.length } : { code: "too_small", minimum: def.length },
+          ...tooBig2 ? { code: "too_big", maximum: def.length } : { code: "too_small", minimum: def.length },
           inclusive: true,
           exact: true,
           input: payload.value,
@@ -25669,11 +25669,11 @@ var require_resolve = __commonJS({
       return id ? id.replace(TRAILING_SLASH_HASH, "") : "";
     }
     exports.normalizeId = normalizeId;
-    function resolveUrl(resolver, baseId, id) {
+    function resolveUrl2(resolver, baseId, id) {
       id = normalizeId(id);
       return resolver.resolve(baseId, id);
     }
-    exports.resolveUrl = resolveUrl;
+    exports.resolveUrl = resolveUrl2;
     var ANCHOR = /^[a-z_][-a-z0-9._]*$/i;
     function getSchemaRefs(schema, baseId) {
       if (typeof schema == "boolean")
@@ -27186,6 +27186,7 @@ var require_fast_uri = __commonJS({
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
+    var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
     function getParseError(parsed, matches) {
       if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
         return 'URI path must start with "/" when authority is present.';
@@ -27215,6 +27216,11 @@ var require_fast_uri = __commonJS({
           uri = "//" + uri;
         }
       }
+      const authorityMatch = uri.match(AUTHORITY_PREFIX);
+      if (authorityMatch !== null && authorityMatch[1].indexOf("\\") !== -1) {
+        parsed.error = "URI authority must not contain a literal backslash.";
+        malformedAuthorityOrPort = true;
+      }
       const matches = uri.match(URI_PARSE);
       if (matches) {
         parsed.scheme = matches[1];
@@ -27258,7 +27264,7 @@ var require_fast_uri = __commonJS({
         if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport)) {
           if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP === false && nonSimpleDomain(parsed.host)) {
             try {
-              parsed.host = URL.domainToASCII(parsed.host.toLowerCase());
+              parsed.host = new URL("http://" + parsed.host).hostname;
             } catch (e) {
               parsed.error = parsed.error || "Host's domain name can not be converted to ASCII: " + e;
             }
@@ -32802,7 +32808,7 @@ async function loadStdioDotenv() {
 }
 
 // src/version.ts
-var VERSION = "1.0.3";
+var VERSION = "1.1.0";
 
 // src/tools/models.ts
 init_dist();
@@ -32842,6 +32848,355 @@ function filterImageModels(raw) {
 // src/tools/generate.ts
 init_images();
 
+// src/inputs.ts
+init_dist();
+
+// src/fetch-image.ts
+init_dist();
+var IMAGE_URL_MAX_BYTES = 15 * 1024 * 1024;
+var IMAGE_INLINE_MAX_BYTES = 6 * 1024 * 1024;
+var MAX_REDIRECTS = 5;
+var DEFAULT_FETCH_TIMEOUT_MS = 6e4;
+function ipv4Octets(host) {
+  const parts = host.split(".");
+  if (parts.length !== 4) return void 0;
+  const octets = parts.map((p) => /^\d{1,3}$/.test(p) ? Number(p) : NaN);
+  return octets.every((n) => Number.isInteger(n) && n >= 0 && n <= 255) ? octets : void 0;
+}
+function isPrivateIpv4([a, b]) {
+  if (a === 0 || a === 127) return true;
+  if (a === 10) return true;
+  if (a === 172 && b >= 16 && b <= 31) return true;
+  if (a === 192 && b === 168) return true;
+  if (a === 169 && b === 254) return true;
+  if (a === 100 && b >= 64 && b <= 127) return true;
+  if (a === 192 && b === 0) return true;
+  if (a === 198 && (b === 18 || b === 19)) return true;
+  if (a >= 224) return true;
+  return false;
+}
+function ipv6Groups(host) {
+  if (!host.includes(":")) return void 0;
+  let text = host;
+  const tail = [];
+  const dotted = /:((?:\d{1,3}\.){3}\d{1,3})$/.exec(text);
+  if (dotted) {
+    const octets = ipv4Octets(dotted[1]);
+    if (!octets) return void 0;
+    tail.push(octets[0] << 8 | octets[1], octets[2] << 8 | octets[3]);
+    text = text.slice(0, dotted.index);
+  }
+  const halves = text.split("::");
+  if (halves.length > 2) return void 0;
+  const parse3 = (part) => {
+    if (part === "") return [];
+    const out = [];
+    for (const piece of part.split(":")) {
+      if (!/^[0-9a-f]{1,4}$/.test(piece)) return void 0;
+      out.push(parseInt(piece, 16));
+    }
+    return out;
+  };
+  const head = parse3(halves[0]);
+  const rest = halves.length === 2 ? parse3(halves[1]) : [];
+  if (!head || !rest) return void 0;
+  const explicit = [...head, ...rest, ...tail];
+  if (halves.length === 2) {
+    if (explicit.length > 7) return void 0;
+    return [...head, ...Array(8 - explicit.length).fill(0), ...rest, ...tail];
+  }
+  return explicit.length === 8 ? explicit : void 0;
+}
+var V4_BEARING_PREFIXES = [
+  [0, 0, 0, 0, 0, 65535],
+  // ::ffff:0:0/96   — IPv4-mapped
+  [0, 0, 0, 0, 0, 0],
+  //      ::/96           — IPv4-compatible (deprecated)
+  [0, 0, 0, 0, 65535, 0],
+  // ::ffff:0:0:0/96 — IPv4-translated (deprecated SIIT)
+  [100, 65435, 0, 0, 0, 0]
+  // 64:ff9b::/96 — NAT64 well-known (RFC 6052)
+];
+function isPrivateIpv6(groups) {
+  if (groups.every((g) => g === 0)) return true;
+  if (groups.slice(0, 7).every((g) => g === 0) && groups[7] === 1) return true;
+  if ((groups[0] & 65472) === 65152) return true;
+  if ((groups[0] & 65024) === 64512) return true;
+  if (V4_BEARING_PREFIXES.some((prefix) => prefix.every((g, i) => groups[i] === g))) {
+    return isPrivateIpv4([groups[6] >> 8, groups[6] & 255, groups[7] >> 8, groups[7] & 255]);
+  }
+  return false;
+}
+function assertPublicHttpsUrl(raw, requested) {
+  let url2;
+  try {
+    url2 = new URL(raw);
+  } catch {
+    throw new McpToolError(`Not a valid URL: ${raw}`, {
+      hint: "images_url entries must be absolute https:// URLs."
+    });
+  }
+  if (url2.protocol !== "https:") {
+    throw new McpToolError(`Refusing to fetch ${describeUrl(raw, requested)}: only https:// URLs are fetched (got "${url2.protocol}").`, {
+      hint: "Use an https:// URL, or send the bytes with images_base64 / gemini_upload_file."
+    });
+  }
+  const rawHost = url2.hostname.toLowerCase();
+  const isIpv6Literal = rawHost.startsWith("[") && rawHost.endsWith("]");
+  const host = isIpv6Literal ? rawHost.slice(1, -1) : rawHost;
+  const v4 = isIpv6Literal ? void 0 : ipv4Octets(host);
+  const v6 = isIpv6Literal ? ipv6Groups(host) : void 0;
+  const blocked = isIpv6Literal ? v6 === void 0 || isPrivateIpv6(v6) : host === "localhost" || host.endsWith(".localhost") || host.endsWith(".local") || (v4 ? isPrivateIpv4(v4) : false);
+  if (blocked) {
+    throw new McpToolError(
+      `Refusing to fetch ${describeUrl(raw, requested)}: "${url2.hostname}" is a private, loopback or link-local address, not a public host.`,
+      { hint: "images_url is fetched by the server, so it must point at a publicly reachable https:// image." }
+    );
+  }
+  return url2;
+}
+function describeUrl(current, requested) {
+  return current === requested ? current : `${current} (redirected from ${requested})`;
+}
+async function readCapped(res, maxBytes, url2, requested) {
+  const declared = Number(res.headers.get("content-length"));
+  if (Number.isFinite(declared) && declared > maxBytes) {
+    throw tooBig(url2, requested, declared, maxBytes);
+  }
+  const reader = res.body?.getReader();
+  if (!reader) {
+    const buf = new Uint8Array(await res.arrayBuffer());
+    if (buf.byteLength > maxBytes) throw tooBig(url2, requested, buf.byteLength, maxBytes);
+    return buf;
+  }
+  const chunks = [];
+  let total = 0;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      if (!value) continue;
+      total += value.byteLength;
+      if (total > maxBytes) {
+        await reader.cancel().catch(() => {
+        });
+        throw tooBig(url2, requested, total, maxBytes, true);
+      }
+      chunks.push(value);
+    }
+  } finally {
+    reader.releaseLock?.();
+  }
+  const out = new Uint8Array(total);
+  let offset = 0;
+  for (const c of chunks) {
+    out.set(c, offset);
+    offset += c.byteLength;
+  }
+  return out;
+}
+function fetchFailure(err, current, requested, timeoutMs) {
+  const name = err?.name;
+  if (name === "TimeoutError" || name === "AbortError") {
+    return new McpToolError(`Fetching ${describeUrl(current, requested)} timed out after ${timeoutMs}ms.`, {
+      hint: "The server accepted the connection but did not finish sending the image. Try a different URL, or raise timeout_ms."
+    });
+  }
+  return new McpToolError(
+    `Could not fetch ${describeUrl(current, requested)}: ${err instanceof Error ? err.message : String(err)}`,
+    { hint: "Check the URL is reachable from the server and serves the image without authentication." }
+  );
+}
+function tooBig(url2, requested, size, max, partial2 = false) {
+  const mb2 = (n) => `${(n / (1024 * 1024)).toFixed(1)} MB`;
+  return new McpToolError(
+    `Image at ${describeUrl(url2, requested)} is ${partial2 ? "over" : ""} ${mb2(size)}, above the ${mb2(max)} limit for images_url.`,
+    { hint: "Resize or re-encode the image, or upload it yourself with gemini_upload_file and pass the returned file_uri." }
+  );
+}
+async function fetchRemoteImage(requestedUrl, opts = {}) {
+  const doFetch = opts.fetchImpl ?? fetch;
+  const maxBytes = opts.maxBytes ?? IMAGE_URL_MAX_BYTES;
+  const accept = opts.accept ?? ["image/"];
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_FETCH_TIMEOUT_MS;
+  let current = requestedUrl;
+  for (let hop = 0; ; hop++) {
+    const url2 = assertPublicHttpsUrl(current, requestedUrl);
+    const signal = timeoutMs > 0 ? AbortSignal.timeout(timeoutMs) : void 0;
+    let res;
+    try {
+      res = await doFetch(url2.toString(), {
+        redirect: "manual",
+        headers: { accept: accept.map((p) => `${p.replace(/\/$/, "")}/*`).join(", ") },
+        ...signal ? { signal } : {}
+      });
+    } catch (err) {
+      throw fetchFailure(err, current, requestedUrl, timeoutMs);
+    }
+    if (res.status >= 300 && res.status < 400) {
+      const location = res.headers.get("location");
+      if (!location) {
+        throw new McpToolError(`Fetching ${describeUrl(current, requestedUrl)} returned HTTP ${res.status} with no Location header.`);
+      }
+      if (hop >= MAX_REDIRECTS) {
+        throw new McpToolError(`Fetching ${requestedUrl} exceeded ${MAX_REDIRECTS} redirects (last hop: ${location}).`);
+      }
+      current = new URL(location, url2).toString();
+      continue;
+    }
+    if (!res.ok) {
+      throw new McpToolError(`Fetching ${describeUrl(current, requestedUrl)} returned HTTP ${res.status} ${res.statusText || ""}`.trim(), {
+        hint: "The URL must be publicly readable \u2014 a login page or signed-URL expiry shows up here as 401/403/404."
+      });
+    }
+    const contentType = (res.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+    if (!accept.some((prefix) => contentType.startsWith(prefix))) {
+      const expected = accept.map((p) => `${p.replace(/\/$/, "")}/*`).join(" or ");
+      throw new McpToolError(
+        `${describeUrl(current, requestedUrl)} is not ${accept.length === 1 && accept[0] === "image/" ? "an image" : "usable media"}: the server returned Content-Type "${contentType || "(none)"}", expected ${expected}.`,
+        { hint: "Link directly to the media file, not to the page that displays it." }
+      );
+    }
+    let bytes;
+    try {
+      bytes = await readCapped(res, maxBytes, current, requestedUrl);
+    } catch (err) {
+      if (err instanceof McpToolError) throw err;
+      throw fetchFailure(err, current, requestedUrl, timeoutMs);
+    }
+    if (bytes.byteLength === 0) {
+      throw new McpToolError(`${describeUrl(current, requestedUrl)} returned an empty body.`);
+    }
+    return { bytes, mimeType: contentType, size: bytes.byteLength, finalUrl: current, requestedUrl };
+  }
+}
+
+// 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
+  );
+}
+var ASSUMED_TTL_MS = 47 * 60 * 60 * 1e3;
+function expiresAtMs(expirationTime, now) {
+  if (expirationTime) {
+    const t = Date.parse(expirationTime);
+    if (Number.isFinite(t)) return t;
+  }
+  return now + ASSUMED_TTL_MS;
+}
+async function resolveImageInputs(args, client2) {
+  const report = {};
+  const inputs = [];
+  const onDisk = client2.mediaSink?.persistsFiles ?? true;
+  if (args.from_clipboard) {
+    inputs.push(await (await Promise.resolve().then(() => (init_clipboard(), clipboard_exports))).readClipboardImage());
+  }
+  for (const path of args.images ?? []) {
+    inputs.push(await resolveLocalPath(path, client2, onDisk, report));
+  }
+  if (args.images_base64?.length) {
+    const { decodeImageInput: decodeImageInput2 } = await Promise.resolve().then(() => (init_images(), images_exports));
+    for (const b64 of args.images_base64) inputs.push(decodeImageInput2(b64));
+  }
+  const fetched = /* @__PURE__ */ new Map();
+  for (const url2 of args.images_url ?? []) {
+    const hit = fetched.get(url2);
+    if (hit) {
+      inputs.push(hit);
+      continue;
+    }
+    const resolved = await resolveUrl(url2, client2, report);
+    fetched.set(url2, resolved);
+    inputs.push(resolved);
+  }
+  const seenUris = /* @__PURE__ */ new Map();
+  for (const ref of args.images_file_uris ?? []) {
+    const hit = seenUris.get(ref);
+    if (hit) {
+      inputs.push(hit);
+      continue;
+    }
+    const file2 = await client2.getFile(ref);
+    const input = { uri: file2.uri, mimeType: file2.mimeType };
+    seenUris.set(ref, input);
+    (report.file_uris ??= []).push(file2.name);
+    inputs.push(input);
+  }
+  return { inputs, report: Object.keys(report).length > 0 ? report : void 0 };
+}
+async function resolveLocalPath(path, client2, onDisk, report) {
+  const { readImageAsInline: readImageAsInline2, resolveImagePath: resolveImagePath2 } = await Promise.resolve().then(() => (init_images(), images_exports));
+  if (!onDisk) return readImageAsInline2(path);
+  const { stat: stat3 } = await import("node:fs/promises");
+  const resolved = resolveImagePath2(path);
+  let key;
+  try {
+    const { mtimeMs, size } = await stat3(resolved);
+    key = `path\0${resolved}\0${mtimeMs}\0${size}`;
+  } catch {
+    return readImageAsInline2(path);
+  }
+  const cached2 = client2.session.cachedUpload(key);
+  if (cached2) return { uri: cached2.uri, mimeType: cached2.mimeType };
+  const references = client2.session.countReference(key);
+  const inline = await readImageAsInline2(resolved);
+  if (references < 2) return inline;
+  try {
+    const bytes = Uint8Array.from(atob(inline.base64), (c) => c.charCodeAt(0));
+    const displayName = resolved.split(/[\\/]/).pop() || "image";
+    const uploaded = await client2.uploadBytes(bytes, inline.mimeType, displayName);
+    client2.session.uploadCache.set(key, {
+      name: uploaded.name,
+      uri: uploaded.uri,
+      mimeType: uploaded.mimeType,
+      expiresAtMs: expiresAtMs(uploaded.expirationTime, Date.now())
+    });
+    (report.auto_uploaded ??= []).push({ path: resolved, file_uri: uploaded.name, expires: uploaded.expirationTime });
+    return { uri: uploaded.uri, mimeType: uploaded.mimeType };
+  } catch {
+    return inline;
+  }
+}
+async function resolveUrl(url2, client2, report) {
+  const fetched = await client2.fetchRemoteImage(url2);
+  const entry = {
+    url: url2,
+    mime_type: fetched.mimeType,
+    bytes: fetched.size
+  };
+  (report.fetched_urls ??= []).push(entry);
+  if (fetched.size <= IMAGE_INLINE_MAX_BYTES) {
+    return { base64: encodeBase64(fetched.bytes), mimeType: fetched.mimeType };
+  }
+  const displayName = fileNameFromUrl(url2);
+  const uploaded = await client2.uploadBytes(fetched.bytes, fetched.mimeType, displayName);
+  entry.file_uri = uploaded.name;
+  return { uri: uploaded.uri, mimeType: uploaded.mimeType };
+}
+function fileNameFromUrl(url2) {
+  try {
+    const name = new URL(url2).pathname.split("/").filter(Boolean).pop();
+    return name ? decodeURIComponent(name).slice(0, 120) : "image";
+  } catch {
+    return "image";
+  }
+}
+function encodeBase64(bytes) {
+  let binary = "";
+  const CHUNK = 32768;
+  for (let i = 0; i < bytes.length; i += CHUNK) {
+    binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+  }
+  return btoa(binary);
+}
+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`."
+  );
+}
+
 // src/tools/shared.ts
 init_zod();
 init_dist();
@@ -32877,6 +33232,16 @@ 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)."
 );
+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 ${Math.round(IMAGE_URL_MAX_BYTES / (1024 * 1024))}MB each; must be a directly-linked image (Content-Type image/*).`
+  );
+}
+function imagesFileUrisSchema(label = "Reference images") {
+  return external_exports.array(external_exports.string().min(1)).optional().describe(
+    `${label} by Gemini Files API reference ("files/<id>", or the full uri) from gemini_upload_file or POST /upload. Upload once, then reference it across as many calls as you like \u2014 no bytes are re-sent and none enter the conversation. Files are retained ~48h, after which the reference stops resolving.`
+  );
+}
 var sharedImageSchema = {
   // Bare id only: the model is interpolated into the URL path
   // (`/models/${model}:generateContent`), so slashes/colons/queries must be
@@ -32998,7 +33363,7 @@ function assertLocalInputsAvailable(sink, args) {
   if (args.from_clipboard) unavailable.push("`from_clipboard` (reads the macOS clipboard via child_process)");
   if (args.video_path) unavailable.push("`video_path` (uploads a file streamed from disk)");
   if (unavailable.length === 0) return;
-  const fix = "Send image bytes as `images_base64` (raw base64 or a data: URI) instead of `images`/`master_images`/`from_clipboard`, and reference video by `video_url` (a public YouTube URL, or a files/\u2026 uri uploaded elsewhere) instead of `video_path`.";
+  const fix = "Reference images WITHOUT putting bytes in the conversation, in order of preference: (1) `images_url` \u2014 public https URLs the server fetches itself; (2) `images_file_uris` \u2014 upload once with `gemini_upload_file` (it takes a `url` or `data_base64`) and reuse the returned files/\u2026 uri; (3) `POST /upload` on this connector with the raw bytes as the body (`curl -X POST <connector-url>/upload -H 'Authorization: Bearer <token>' -H 'Content-Type: image/jpeg' --data-binary @photo.jpg`), then pass the returned file_uri. As a last resort `images_base64` still works, but it costs ~14k tokens per photo and breaks on a truncated read. Reference video by `video_url` (a public YouTube URL, or a files/\u2026 uri uploaded elsewhere) instead of `video_path`.";
   throw new McpToolError(
     `${unavailable.join(", ")} ${unavailable.length > 1 ? "are" : "is"} unavailable on the hosted connector: it runs on a Cloudflare Worker, which has no filesystem and no local clipboard. ${fix}`,
     { hint: fix }
@@ -33191,7 +33556,9 @@ function registerGenerateTools(server, client2) {
         count: external_exports.number().int().positive().max(8).optional().describe("Number of independent images (default 1)"),
         filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to reference input images (image-conditioned generation)"),
-        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs"),
+        images_url: imagesUrlSchema(),
+        images_file_uris: imagesFileUrisSchema(),
+        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"),
         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,
@@ -33215,13 +33582,15 @@ function registerGenerateTools(server, client2) {
         images: args.images,
         images_base64: args.images_base64,
         from_clipboard: args.from_clipboard,
+        images_url: args.images_url,
+        images_file_uris: args.images_file_uris,
         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 () => {
         const seed = pickSeed(args.seed);
         const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
-        const refInputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const { inputs: refInputs, report } = await withProgressHeartbeat(extra, "Resolving reference images", () => resolveImageInputs(args, client2));
         const video = await withProgressHeartbeat(extra, "Uploading video to the Gemini Files API", () => resolveVideoInput(args, client2));
         const named = [];
         let capturedText;
@@ -33250,6 +33619,7 @@ function registerGenerateTools(server, client2) {
         const meta3 = buildMeta(model, seed, args);
         if (capturedText) meta3.text = capturedText;
         if (capturedGrounding) meta3.grounding = capturedGrounding;
+        if (report) meta3.image_inputs = report;
         if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
         meta3.hint = REFINE_HINT;
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, count, persistsFiles: client2.mediaSink?.persistsFiles });
@@ -33266,7 +33636,9 @@ function registerGenerateTools(server, client2) {
       inputSchema: {
         prompt: external_exports.string().min(1).describe("Instruction describing the edit or composition"),
         images: external_exports.array(external_exports.string().min(1)).optional().describe("Paths to input image file(s) (1 = edit, 2+ = compose)"),
-        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Input images as base64 strings or data URIs"),
+        images_url: imagesUrlSchema("Input images"),
+        images_file_uris: imagesFileUrisSchema("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"),
         filename: external_exports.string().optional().describe("Base filename for the output image (extension stripped; default: slugified prompt)"),
         confirm: schemaConfirm,
         ...sharedImageSchema
@@ -33274,11 +33646,7 @@ function registerGenerateTools(server, client2) {
     },
     async (args, extra) => {
       assertLocalInputsAvailable(client2.mediaSink, args);
-      const hasPaths = (args.images?.length ?? 0) > 0;
-      const hasBase64 = (args.images_base64?.length ?? 0) > 0;
-      if (!hasPaths && !hasBase64 && !args.from_clipboard) {
-        throw new McpToolError("Provide at least one input image via `images`, `images_base64`, or `from_clipboard`.");
-      }
+      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"));
@@ -33291,12 +33659,14 @@ function registerGenerateTools(server, client2) {
         google_search: args.google_search,
         images: args.images,
         images_base64: args.images_base64,
-        from_clipboard: args.from_clipboard
+        from_clipboard: args.from_clipboard,
+        images_url: args.images_url,
+        images_file_uris: args.images_file_uris
       });
       return client2.session.jobs.dispatch({ toolName: "gemini_image_edit", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, async () => {
         const seed = pickSeed(args.seed);
         const slug = args.filename ? baseName(args.filename) : slugify2(args.prompt);
-        const inputs = await gatherImageInputs({ images: args.images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        const { inputs, report } = await withProgressHeartbeat(extra, "Resolving input images", () => resolveImageInputs(args, client2));
         const result = await withProgressHeartbeat(extra, `Editing image (${model})`, () => client2.generate({
           prompt: args.prompt,
           images: inputs,
@@ -33312,6 +33682,7 @@ function registerGenerateTools(server, client2) {
         const meta3 = buildMeta(model, seed, args);
         if (text) meta3.text = text;
         if (result.grounding) meta3.grounding = result.grounding;
+        if (report) meta3.image_inputs = report;
         meta3.hint = REFINE_HINT;
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: client2.mediaSink?.persistsFiles });
         if (risk) meta3.timeout_risk = risk;
@@ -33338,7 +33709,9 @@ function registerSetTools(server, client2) {
         reference_mode: external_exports.enum(["master", "chain"]).optional().describe("master: every image references the master (default). chain: each references the previous."),
         basename: external_exports.string().optional().describe("Base filename prefix for output images (default: slugified master_prompt)"),
         master_images: external_exports.array(external_exports.string().min(1)).optional().describe("Reference image paths passed to the master generation call"),
-        master_images_base64: external_exports.array(external_exports.string().min(1)).optional().describe("Reference images as base64 strings or data URIs for master generation"),
+        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_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
       }
@@ -33363,13 +33736,24 @@ function registerSetTools(server, client2) {
         google_search: args.google_search,
         master_images: args.master_images,
         master_images_base64: args.master_images_base64,
-        from_clipboard: args.from_clipboard
+        from_clipboard: args.from_clipboard,
+        master_images_url: args.master_images_url,
+        master_images_file_uris: args.master_images_file_uris
       });
       return client2.session.jobs.dispatch({ toolName: "gemini_image_set", fingerprint, idempotencyKey: args.idempotency_key, async: args.async }, 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 masterRefInputs = await gatherImageInputs({ images: args.master_images, images_base64: args.master_images_base64, from_clipboard: args.from_clipboard });
+        const carried = await resolveImageInputs(
+          { images_url: args.master_images_url, images_file_uris: args.master_images_file_uris },
+          client2
+        );
+        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 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({
@@ -33385,13 +33769,13 @@ function registerSetTools(server, client2) {
           if (mode === "chain") {
             let ref = master;
             for (let i = 0; i < scenePrompts.length; i++) {
-              const { images: [img] } = await client2.generate({ prompt: scenePrompts[i], images: [ref], seed: seed + i + 1, ...cfg });
+              const { images: [img] } = await client2.generate({ prompt: scenePrompts[i], images: [ref, ...carried.inputs], seed: seed + i + 1, ...cfg });
               named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, "0")}` });
               ref = img;
             }
           } else {
             const scenes = await Promise.all(
-              scenePrompts.map((p, i) => client2.generate({ prompt: p, images: [master], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
+              scenePrompts.map((p, i) => client2.generate({ prompt: p, images: [master, ...carried.inputs], seed: seed + i + 1, ...cfg }).then((r) => r.images[0]))
             );
             scenes.forEach((img, i) => named.push({ image: img, base: `${slug}-${String(i + 1).padStart(2, "0")}` }));
           }
@@ -33401,6 +33785,7 @@ function registerSetTools(server, client2) {
         const meta3 = buildMeta(model, seed, args);
         if (masterText) meta3.text = masterText;
         if (masterResult.grounding) meta3.grounding = masterResult.grounding;
+        if (report) meta3.image_inputs = report;
         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);
@@ -33442,6 +33827,42 @@ var SessionState = class {
    * model against the requested edit.
    */
   writtenOutputs = /* @__PURE__ */ new Set();
+  /**
+   * Files API uploads this session can reuse, keyed by an opaque identity
+   * string (for a local path: absolute path + mtime + size, so an edited file
+   * is a different key rather than a stale hit).
+   *
+   * Backs the stdio "referenced twice → upload once" optimization: the second
+   * time a session sends the same picture, the bytes are replaced by a
+   * `files/…` reference that costs nothing to repeat. Session-scoped, like
+   * everything else here — a uri is minted by ONE user's API key and is only
+   * readable with that key, so sharing this map across the connector's tenants
+   * would hand out references another user cannot use and this user did not
+   * create.
+   */
+  uploadCache = /* @__PURE__ */ new Map();
+  /**
+   * How many times each identity has been referenced this session. The
+   * threshold for auto-uploading is "more than once", so the count has to
+   * outlive the call that first saw it.
+   */
+  referenceCounts = /* @__PURE__ */ new Map();
+  /** Record a reference and return the running total (1 on first sight). */
+  countReference(key) {
+    const next = (this.referenceCounts.get(key) ?? 0) + 1;
+    this.referenceCounts.set(key, next);
+    return next;
+  }
+  /** A cached upload, or `undefined` if absent or past its Files API TTL. */
+  cachedUpload(key, now = Date.now()) {
+    const hit = this.uploadCache.get(key);
+    if (!hit) return void 0;
+    if (hit.expiresAtMs <= now) {
+      this.uploadCache.delete(key);
+      return void 0;
+    }
+    return hit;
+  }
   /** Forget everything. Tests use this; nothing in `src/` calls it. */
   reset() {
     this.jobs.reset();
@@ -33449,6 +33870,8 @@ var SessionState = class {
     this.lastMusicInteractionId = void 0;
     this.lastVideoInteractionId = void 0;
     this.writtenOutputs.clear();
+    this.uploadCache.clear();
+    this.referenceCounts.clear();
   }
 };
 
@@ -33489,6 +33912,22 @@ var ChainedRequest404Error = class extends McpToolError {
   upstreamMessage;
   retries;
 };
+function generatePart(img) {
+  return img.uri ? { file_data: { file_uri: img.uri, mime_type: img.mimeType } } : { inline_data: { mime_type: img.mimeType, data: img.base64 } };
+}
+function interactPart(img) {
+  return img.uri ? { type: "image", uri: img.uri, mime_type: img.mimeType } : { type: "image", mime_type: img.mimeType, data: img.base64 };
+}
+function normalizeFileName(ref) {
+  const trimmed = ref.trim();
+  const match = /(?:^|\/)(files\/[\w-]+)\/?$/.exec(trimmed);
+  if (!match) {
+    throw new McpToolError(`Not a Gemini Files API reference: "${ref}"`, {
+      hint: "Pass the `files/<id>` name (or the full https://\u2026/v1beta/files/<id> uri) returned by gemini_upload_file / POST /upload."
+    });
+  }
+  return match[1];
+}
 var GeminiClient = class {
   /**
    * A key handed in explicitly (the connector's per-session key). When absent
@@ -33577,6 +34016,14 @@ var GeminiClient = class {
     }
     return key;
   }
+  /**
+   * Fetch one `images_url` reference server-side. Routed through the client so
+   * it uses the SAME injected `fetchImpl` as every upstream call — which is
+   * what makes it mockable in tests and correct on the Worker.
+   */
+  async fetchRemoteImage(url2, opts = {}) {
+    return fetchRemoteImage(url2, { ...opts, fetchImpl: this.fetchImpl, timeoutMs: resolveTimeoutMs(opts.timeoutMs) });
+  }
   /** The default model after env override (no per-call arg). */
   defaultModel() {
     return resolveModel(void 0, readEnvVar("GEMINI_IMAGE_MODEL"));
@@ -33608,8 +34055,60 @@ var GeminiClient = class {
    * (enforced locally before any bytes are sent).
    */
   async uploadVideo(path, mimeType) {
-    const key = this.requireKey();
     const blob = await fileBlob(path, { type: mimeType, maxBytes: FILE_MAX_BYTES, label: "Video" });
+    return this.uploadToFilesApi(blob, mimeType, basename(path), blob.size);
+  }
+  /**
+   * Upload already-in-memory bytes (a fetched `images_url`, a `data_base64`
+   * payload, an inline `gemini_upload_file` body) to the Files API. Same three
+   * steps as {@link uploadVideo}, minus the filesystem — which is what makes it
+   * usable on the hosted connector, where there is no disk to stream from.
+   */
+  async uploadBytes(bytes, mimeType, displayName) {
+    const view = bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes);
+    if (view.byteLength > FILE_MAX_BYTES) {
+      throw new McpToolError(`File is ${view.byteLength} bytes, over the Gemini Files API limit of ${FILE_MAX_BYTES} bytes (2 GB).`);
+    }
+    const body = new Blob([view], { type: mimeType });
+    return this.uploadToFilesApi(body, mimeType, displayName, view.byteLength);
+  }
+  /**
+   * Upload a request body straight through to the Files API without buffering
+   * it — the direct-upload HTTP endpoint (`POST /upload` on the Worker) hands
+   * us a `ReadableStream` and a `Content-Length`, and the whole point of that
+   * endpoint is that the bytes never materialize anywhere they'd cost context
+   * or memory.
+   *
+   * `contentLength` is REQUIRED because the resumable protocol's start step
+   * declares it up front (`X-Goog-Upload-Header-Content-Length`); a stream of
+   * unknown length has to be buffered by the caller first.
+   */
+  async uploadStream(stream, mimeType, displayName, contentLength) {
+    if (contentLength > FILE_MAX_BYTES) {
+      throw new McpToolError(`File is ${contentLength} bytes, over the Gemini Files API limit of ${FILE_MAX_BYTES} bytes (2 GB).`);
+    }
+    return this.uploadToFilesApi(stream, mimeType, displayName, contentLength);
+  }
+  /**
+   * The resumable upload itself. Three live-verified steps (docs/GEMINI-API.md
+   * "Files API — local video upload"):
+   *
+   *  1. `POST {UPLOAD_BASE_URL}/files` (command `start`) → the upload session
+   *     URL arrives in the `x-goog-upload-url` RESPONSE HEADER (body is empty).
+   *  2. `POST <session url>` (command `upload, finalize`) with the bytes.
+   *     Response: `{file:…}`.
+   *  3. Poll `GET /v1beta/files/<id>` while `state` is `PROCESSING`, until
+   *     `ACTIVE` (the poll response is the File object UNWRAPPED). Images are
+   *     usually `ACTIVE` immediately; video is what processes.
+   *
+   * These two upload calls are raw `fetchImpl` (not `createApiClient`): step 1
+   * needs the response *header* and step 2 posts a binary body — neither fits
+   * `fetchJson`. The poll DOES go through the shared client (timeout + retry).
+   * Uploads deliberately have no abort timeout: a multi-hundred-MB file can
+   * legitimately take longer than any fixed budget.
+   */
+  async uploadToFilesApi(body, mimeType, displayName, contentLength) {
+    const key = this.requireKey();
     const startPath = "/files";
     const startRes = await this.fetchImpl(`${UPLOAD_BASE_URL}${startPath}`, {
       method: "POST",
@@ -33617,11 +34116,11 @@ var GeminiClient = class {
         "x-goog-api-key": key,
         "X-Goog-Upload-Protocol": "resumable",
         "X-Goog-Upload-Command": "start",
-        "X-Goog-Upload-Header-Content-Length": String(blob.size),
+        "X-Goog-Upload-Header-Content-Length": String(contentLength),
         "X-Goog-Upload-Header-Content-Type": mimeType,
         "Content-Type": "application/json"
       },
-      body: JSON.stringify({ file: { display_name: basename(path) } })
+      body: JSON.stringify({ file: { display_name: displayName } })
     });
     if (!startRes.ok) {
       throw new McpToolError(
@@ -33634,13 +34133,17 @@ var GeminiClient = class {
         hint: "The Files API resumable-upload contract may have changed \u2014 see docs/GEMINI-API.md."
       });
     }
+    const streaming = !(body instanceof Blob);
     const upRes = await this.fetchImpl(uploadUrl, {
       method: "POST",
       headers: {
         "X-Goog-Upload-Offset": "0",
-        "X-Goog-Upload-Command": "upload, finalize"
+        "X-Goog-Upload-Command": "upload, finalize",
+        ...streaming ? { "Content-Length": String(contentLength) } : {}
       },
-      body: blob
+      body,
+      // Required by undici/workerd to send a ReadableStream body at all.
+      ...streaming ? { duplex: "half" } : {}
     });
     if (!upRes.ok) {
       throw new McpToolError(
@@ -33654,8 +34157,8 @@ var GeminiClient = class {
     }
     for (let attempt = 0; file2.state === "PROCESSING"; attempt++) {
       if (attempt >= FILE_POLL_MAX_ATTEMPTS) {
-        throw new McpToolError(`${SERVICE} video file ${name} is still processing after ${FILE_POLL_INTERVAL_MS * FILE_POLL_MAX_ATTEMPTS / 6e4} minutes`, {
-          hint: "Very long videos can take a while to process \u2014 retry later by passing the file uri as video_url."
+        throw new McpToolError(`${SERVICE} file ${name} is still processing after ${FILE_POLL_INTERVAL_MS * FILE_POLL_MAX_ATTEMPTS / 6e4} minutes`, {
+          hint: "Very long videos can take a while to process \u2014 retry later by passing the file uri as video_url / images_file_uris."
         });
       }
       await this.sleep(FILE_POLL_INTERVAL_MS);
@@ -33663,14 +34166,78 @@ var GeminiClient = class {
     }
     if (file2.state !== "ACTIVE") {
       throw new McpToolError(
-        `${SERVICE} video file processing failed (state ${file2.state ?? "unknown"})${file2.error?.message ? `: ${file2.error.message}` : ""}`,
-        { hint: "Check the video is a supported format/codec and under 2 GB." }
+        `${SERVICE} file processing failed (state ${file2.state ?? "unknown"})${file2.error?.message ? `: ${file2.error.message}` : ""}`,
+        { hint: "Check the file is a supported format/codec and under 2 GB." }
       );
     }
     if (!file2.uri) {
       throw new McpToolError(`${SERVICE} did not return a uri for uploaded file ${name}`);
     }
-    return { name, uri: file2.uri, mimeType: file2.mimeType ?? mimeType, expirationTime: file2.expirationTime };
+    return {
+      name,
+      uri: file2.uri,
+      mimeType: file2.mimeType ?? mimeType,
+      expirationTime: file2.expirationTime,
+      sizeBytes: file2.sizeBytes,
+      displayName: file2.displayName
+    };
+  }
+  /**
+   * List the files this API key currently has in the Files API. Retention is
+   * ~48h, so the list is naturally short-lived — an empty list after a day is
+   * expiry, not a bug.
+   */
+  async listFiles(pageSize = 100) {
+    const size = Math.min(Math.max(Math.trunc(pageSize), 1), 100);
+    const data = await this.call("GET", `/files?pageSize=${size}`);
+    return (data.files ?? []).filter((f) => !!f.name && !!f.uri).map((f) => ({
+      name: f.name,
+      uri: f.uri,
+      mimeType: f.mimeType ?? "application/octet-stream",
+      state: f.state,
+      createTime: f.createTime,
+      expirationTime: f.expirationTime,
+      sizeBytes: f.sizeBytes,
+      displayName: f.displayName
+    }));
+  }
+  /**
+   * Fetch one file's metadata. Used to resolve a caller-supplied
+   * `images_file_uris` entry to its real MIME type — and, as a side effect, to
+   * fail fast with a clear "that file is gone" instead of the Interactions
+   * API's generic 404 after a billable request was already built.
+   */
+  async getFile(ref) {
+    const resource = normalizeFileName(ref);
+    const file2 = await this.call("GET", `/${resource}`);
+    if (!file2.uri) {
+      throw new McpToolError(`${SERVICE} returned no uri for ${resource}`, {
+        hint: "Files expire ~48h after upload \u2014 re-upload with gemini_upload_file (or POST /upload) and use the new uri."
+      });
+    }
+    if (file2.state && file2.state !== "ACTIVE") {
+      throw new McpToolError(`${SERVICE} file ${resource} is not usable yet (state ${file2.state}).`, {
+        hint: "Wait for the upload to finish processing, then retry."
+      });
+    }
+    return {
+      name: file2.name ?? resource,
+      uri: file2.uri,
+      mimeType: file2.mimeType ?? "application/octet-stream",
+      expirationTime: file2.expirationTime,
+      sizeBytes: file2.sizeBytes,
+      displayName: file2.displayName
+    };
+  }
+  /**
+   * Delete one uploaded file. `name` is interpolated into the URL path, so it
+   * is validated to a bare `files/<id>` for the same reason the model id is
+   * (see {@link uploadToFilesApi}); a full `https://…/v1beta/files/<id>` uri is
+   * accepted and reduced to that form, since that is what every result echoes.
+   */
+  async deleteFile(name) {
+    const resource = normalizeFileName(name);
+    await this.call("DELETE", `/${resource}`);
   }
   async listModels() {
     const data = await this.call("GET", "/models?pageSize=200");
@@ -33679,9 +34246,7 @@ var GeminiClient = class {
   async generate(opts) {
     const model = resolveModel(opts.model, readEnvVar("GEMINI_IMAGE_MODEL"));
     const parts = [{ text: opts.prompt }];
-    for (const img of opts.images ?? []) {
-      parts.push({ inline_data: { mime_type: img.mimeType, data: img.base64 } });
-    }
+    for (const img of opts.images ?? []) parts.push(generatePart(img));
     if (opts.videoUrl) {
       parts.push({ file_data: { file_uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" } });
     }
@@ -33737,9 +34302,7 @@ var GeminiClient = class {
   async interact(opts) {
     const model = resolveModel(opts.model, readEnvVar("GEMINI_IMAGE_MODEL"));
     const inputParts = [{ type: "text", text: opts.input }];
-    for (const img of opts.images ?? []) {
-      inputParts.push({ type: "image", mime_type: img.mimeType, data: img.base64 });
-    }
+    for (const img of opts.images ?? []) inputParts.push(interactPart(img));
     if (opts.videoUrl) {
       inputParts.push({ type: "video", uri: opts.videoUrl, mime_type: opts.videoMimeType ?? "video/mp4" });
     }
@@ -33772,7 +34335,7 @@ var GeminiClient = class {
   async generateVideo(opts) {
     const model = opts.model ?? DEFAULT_VIDEO_MODEL;
     const inputParts = [{ type: "text", text: opts.input }];
-    for (const img of opts.images ?? []) inputParts.push({ type: "image", mime_type: img.mimeType, data: img.base64 });
+    for (const img of opts.images ?? []) inputParts.push(interactPart(img));
     const responseFormat = { type: "video", delivery: "inline" };
     if (opts.aspectRatio) responseFormat.aspect_ratio = opts.aspectRatio;
     const body = { model, input: inputParts, response_format: responseFormat };
@@ -33794,7 +34357,7 @@ var GeminiClient = class {
   async generateMusic(opts) {
     const model = opts.model ?? DEFAULT_MUSIC_MODEL;
     const inputParts = [{ type: "text", text: opts.input }];
-    for (const img of opts.images ?? []) inputParts.push({ type: "image", mime_type: img.mimeType, data: img.base64 });
+    for (const img of opts.images ?? []) inputParts.push(interactPart(img));
     const responseFormat = { type: "audio" };
     if (opts.audioFormat) responseFormat.audio_format = opts.audioFormat;
     const body = { model, input: inputParts, response_format: responseFormat };
@@ -33953,7 +34516,11 @@ function registerInteractTools(server, client2) {
         previous_interaction_id: external_exports.string().optional().describe("ID from a prior gemini_interact call \u2014 continues that multi-turn conversation"),
         continue_last: external_exports.boolean().optional().describe("Continue from the most recent interaction this server created (convenience for previous_interaction_id; an explicit id wins). Survives a server restart by falling back to the newest <image>.json sidecar in the output dir."),
         images: external_exports.array(external_exports.string().min(1)).optional().describe(`Paths to reference input images. ${NEW_REFERENCES_ONLY}`),
-        images_base64: external_exports.array(external_exports.string().min(1)).optional().describe(`Reference images as base64 strings or data URIs. ${NEW_REFERENCES_ONLY}`),
+        images_url: imagesUrlSchema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
+        images_file_uris: imagesFileUrisSchema(`Reference images. ${NEW_REFERENCES_ONLY} Given`),
+        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. ${NEW_REFERENCES_ONLY}`
+        ),
         model: external_exports.string().optional().describe(`Model id override (default: server default; see gemini_list_models). ${MODEL_CHOICE_GUIDE}`),
         aspect_ratio: external_exports.enum(ASPECT_RATIOS).optional().describe("Output aspect ratio"),
         image_size: external_exports.enum(IMAGE_SIZES).optional().describe("Output resolution (512 = 0.5K, Flash-only)"),
@@ -34011,11 +34578,13 @@ function registerInteractTools(server, client2) {
         images,
         images_base64: args.images_base64,
         from_clipboard: args.from_clipboard,
+        images_url: args.images_url,
+        images_file_uris: args.images_file_uris,
         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 () => {
-        const inputs = await gatherImageInputs({ images, images_base64: args.images_base64, from_clipboard: args.from_clipboard });
+        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 = {
           input: args.input,
@@ -34067,6 +34636,7 @@ function registerInteractTools(server, client2) {
         meta3.hint = `To refine this image, call gemini_interact again with previous_interaction_id: "${r.id}" (or continue_last: true) \u2014 do NOT re-attach the returned image as an input; the interaction already contains it.`;
         if (r.text) meta3.text = r.text;
         if (r.grounding) meta3.grounding = r.grounding;
+        if (report) meta3.image_inputs = report;
         if (video.videoFileMeta) meta3.video_file = video.videoFileMeta;
         const risk = timeoutRiskHint({ model, imageSize: args.image_size, persistsFiles: onDisk });
         if (risk) meta3.timeout_risk = risk;
@@ -34272,12 +34842,159 @@ function registerJobTools(server, client2) {
   );
 }
 
+// src/tools/files.ts
+init_zod();
+init_dist();
+var UPLOAD_URL_MAX_BYTES_DISK = 100 * 1024 * 1024;
+var UPLOAD_URL_MAX_BYTES_HOSTED = 25 * 1024 * 1024;
+var mb = (bytes) => Math.round(bytes / (1024 * 1024));
+var UPLOAD_ACCEPT = ["image/", "video/", "audio/"];
+var RETENTION_NOTE = "Gemini retains uploaded files for ~48h. Until then this reference can be reused across any number of calls (images_file_uris on gemini_image_generate / _edit / _set / gemini_interact, or video_url) without re-sending the bytes.";
+function uploadResult(file2) {
+  return textResult({
+    // The `files/<id>` form is what every tool parameter documents, so it leads.
+    file_uri: file2.name,
+    // The absolute uri, for callers that would rather pass it through verbatim.
+    uri: file2.uri,
+    name: file2.name,
+    mime_type: file2.mimeType,
+    ...file2.sizeBytes ? { size_bytes: Number(file2.sizeBytes) } : {},
+    ...file2.displayName ? { display_name: file2.displayName } : {},
+    expires: file2.expirationTime ?? "~48h from upload",
+    hint: `Pass "${file2.name}" in images_file_uris (or video_url for video) on any image tool. ${RETENTION_NOTE}`
+  });
+}
+function registerFileTools(server, client2) {
+  const onDisk = client2.mediaSink?.persistsFiles ?? true;
+  const urlMaxBytes = onDisk ? UPLOAD_URL_MAX_BYTES_DISK : UPLOAD_URL_MAX_BYTES_HOSTED;
+  server.registerTool(
+    "gemini_upload_file",
+    {
+      description: "Upload an image (or video/audio) to the Gemini Files API ONCE and get back a reusable `files/<id>` reference. Use this instead of pasting base64 into a tool call: the reference is a short string, so no image bytes ever enter the conversation, and it can be reused across many generations until it expires (~48h). Provide exactly one of `url` (the server downloads it), `data_base64`" + (onDisk ? ", or `path` (a local file)." : ".") + (onDisk ? "" : " This connector also accepts raw bytes over HTTP: POST them to /upload with the same Authorization header and a Content-Type of image/*, which avoids base64 entirely."),
+      annotations: { readOnlyHint: false, openWorldHint: true },
+      inputSchema: {
+        url: external_exports.string().url().optional().describe(
+          `Public https URL the SERVER downloads and uploads (image/video/audio, up to ${mb(urlMaxBytes)}MB). No bytes pass through the conversation.` + (onDisk ? "" : " Larger files: POST the raw bytes to /upload, which streams instead of buffering.")
+        ),
+        data_base64: external_exports.string().min(1).optional().describe("Raw base64 or a data: URI. Last resort \u2014 this is the one form that costs model context (~14k tokens for a modest JPEG)."),
+        path: external_exports.string().min(1).optional().describe(
+          onDisk ? "Path to a local file (absolute, or resolved against $GEMINI_INPUT_DIR). Confirm-gated like every other local-file input." : "Unavailable on this hosted connector (no filesystem) \u2014 use `url`, `data_base64`, or POST /upload."
+        ),
+        mime_type: external_exports.string().regex(/^[\w.+-]+\/[\w.+-]+$/, "must be a MIME type like image/png").optional().describe("Override the detected MIME type (sniffed from the bytes / taken from the server response otherwise)"),
+        display_name: external_exports.string().min(1).optional().describe("Human-readable name recorded against the upload"),
+        confirm: schemaConfirm
+      }
+    },
+    async (args, extra) => {
+      const sources = [args.url && "url", args.data_base64 && "data_base64", args.path && "path"].filter(Boolean);
+      if (sources.length !== 1) {
+        throw new McpToolError(
+          sources.length === 0 ? "Provide exactly one of `url`, `data_base64`" + (onDisk ? " or `path`." : ".") : `Provide exactly one source, not ${sources.length} (${sources.join(", ")}).`
+        );
+      }
+      if (args.path) {
+        if (!onDisk) {
+          throw new McpToolError(
+            "`path` is unavailable on the hosted connector: it runs on a Cloudflare Worker, which has no filesystem. Use `url` (the server downloads it), `data_base64`, or POST the raw bytes to /upload with the same Authorization header.",
+            { hint: "Use `url`, `data_base64`, or POST /upload." }
+          );
+        }
+        const gate = await previewLocalInputsUnlessConfirmed(
+          args.confirm,
+          "Upload a local file to the Gemini Files API",
+          "/upload/v1beta/files",
+          [args.path]
+        );
+        if (gate) return gate;
+      }
+      const uploaded = await withProgressHeartbeat(extra, "Uploading to the Gemini Files API", async () => {
+        if (args.url) {
+          const fetched = await client2.fetchRemoteImage(args.url, { maxBytes: urlMaxBytes, accept: UPLOAD_ACCEPT });
+          return client2.uploadBytes(
+            fetched.bytes,
+            args.mime_type ?? fetched.mimeType,
+            args.display_name ?? nameFromUrl(args.url)
+          );
+        }
+        if (args.data_base64) {
+          const { decodeImageInput: decodeImageInput2 } = await Promise.resolve().then(() => (init_images(), images_exports));
+          const decoded = decodeImageInput2(args.data_base64);
+          const bytes2 = Uint8Array.from(atob(decoded.base64), (c) => c.charCodeAt(0));
+          return client2.uploadBytes(bytes2, args.mime_type ?? decoded.mimeType, args.display_name ?? "upload");
+        }
+        const { readImageAsInline: readImageAsInline2, resolveImagePath: resolveImagePath2 } = await Promise.resolve().then(() => (init_images(), images_exports));
+        const resolved = resolveImagePath2(args.path);
+        const inline = await readImageAsInline2(resolved);
+        const bytes = Uint8Array.from(atob(inline.base64), (c) => c.charCodeAt(0));
+        return client2.uploadBytes(
+          bytes,
+          args.mime_type ?? inline.mimeType,
+          args.display_name ?? (resolved.split(/[\\/]/).pop() || "upload")
+        );
+      });
+      return uploadResult(uploaded);
+    }
+  );
+  server.registerTool(
+    "gemini_list_files",
+    {
+      description: "List the files currently uploaded to the Gemini Files API under this API key, with their `files/<id>` references, MIME types and expiry times. Retention is ~48h, so an entry that has vanished has expired rather than failed.",
+      annotations: { readOnlyHint: true, openWorldHint: true },
+      inputSchema: {
+        page_size: external_exports.number().int().positive().max(100).optional().describe("Maximum files to return (1-100, default 100)")
+      }
+    },
+    async (args) => {
+      const files = await client2.listFiles(args.page_size ?? 100);
+      return textResult({
+        count: files.length,
+        files: files.map((f) => ({
+          file_uri: f.name,
+          uri: f.uri,
+          mime_type: f.mimeType,
+          ...f.displayName ? { display_name: f.displayName } : {},
+          ...f.sizeBytes ? { size_bytes: Number(f.sizeBytes) } : {},
+          ...f.state ? { state: f.state } : {},
+          ...f.createTime ? { created: f.createTime } : {},
+          ...f.expirationTime ? { expires: f.expirationTime } : {}
+        })),
+        hint: files.length ? `Pass any file_uri above in images_file_uris on an image tool. ${RETENTION_NOTE}` : "No files uploaded (or all have expired \u2014 retention is ~48h). Upload one with gemini_upload_file."
+      });
+    }
+  );
+  server.registerTool(
+    "gemini_delete_file",
+    {
+      description: "Delete an uploaded file from the Gemini Files API before its ~48h expiry. Any tool call still referencing it will then fail with a generic 404, so delete only references you are finished with.",
+      annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
+      inputSchema: {
+        file_uri: external_exports.string().min(1).describe("The `files/<id>` reference (or full uri) to delete"),
+        confirm: schemaConfirm
+      }
+    },
+    async (args) => {
+      const gate = previewUnlessConfirmed(args.confirm, "Delete an uploaded Gemini file", "DELETE", `/v1beta/${args.file_uri}`);
+      if (gate) return gate;
+      await client2.deleteFile(args.file_uri);
+      return textResult({ deleted: args.file_uri });
+    }
+  );
+}
+function nameFromUrl(url2) {
+  try {
+    const name = new URL(url2).pathname.split("/").filter(Boolean).pop();
+    return name ? decodeURIComponent(name).slice(0, 120) : "upload";
+  } catch {
+    return "upload";
+  }
+}
+
 // src/index.ts
 await loadStdioDotenv();
 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],
+  tools: [registerModelTools, registerGenerateTools, registerSetTools, registerInteractTools, registerVideoTools, registerMusicTools, registerJobTools, registerFileTools],
   deps: client
 });