@ljoukov/llm 5.0.4 → 7.0.0

package/dist/index.js

@@ -6,6 +6,8 @@ import path5 from "path";
 import {
   FinishReason,
   FunctionCallingConfigMode,
+  MediaResolution,
+  PartMediaResolutionLevel,
   ThinkingLevel,
   createPartFromBase64,
   createPartFromFunctionResponse,
@@ -204,11 +206,6 @@ function getGeminiImagePricing(modelId) {
 }
 
 // src/openai/pricing.ts
-var OPENAI_GPT_52_PRICING = {
-  inputRate: 1.75 / 1e6,
-  cachedRate: 0.175 / 1e6,
-  outputRate: 14 / 1e6
-};
 var OPENAI_GPT_54_PRICING = {
   inputRate: 2.5 / 1e6,
   cachedRate: 0.25 / 1e6,
@@ -219,37 +216,31 @@ var OPENAI_GPT_54_PRIORITY_PRICING = {
   cachedRate: 0.5 / 1e6,
   outputRate: 30 / 1e6
 };
-var OPENAI_GPT_53_CODEX_PRICING = {
-  inputRate: 1.25 / 1e6,
-  cachedRate: 0.125 / 1e6,
-  outputRate: 10 / 1e6
-};
-var OPENAI_GPT_5_MINI_PRICING = {
+var OPENAI_GPT_54_MINI_PRICING = {
   inputRate: 0.25 / 1e6,
   cachedRate: 0.025 / 1e6,
   outputRate: 2 / 1e6
 };
+var OPENAI_GPT_54_NANO_PRICING = {
+  inputRate: 0.05 / 1e6,
+  cachedRate: 5e-3 / 1e6,
+  outputRate: 0.4 / 1e6
+};
 function getOpenAiPricing(modelId) {
   if (modelId.includes("gpt-5.4-fast")) {
     return OPENAI_GPT_54_PRIORITY_PRICING;
   }
-  if (modelId.includes("gpt-5.4")) {
-    return OPENAI_GPT_54_PRICING;
-  }
-  if (modelId.includes("gpt-5.3-codex-spark")) {
-    return OPENAI_GPT_5_MINI_PRICING;
-  }
-  if (modelId.includes("gpt-5.3-codex")) {
-    return OPENAI_GPT_53_CODEX_PRICING;
+  if (modelId.includes("gpt-5.4-mini")) {
+    return OPENAI_GPT_54_MINI_PRICING;
   }
-  if (modelId.includes("gpt-5.2")) {
-    return OPENAI_GPT_52_PRICING;
+  if (modelId.includes("gpt-5.4-nano")) {
+    return OPENAI_GPT_54_NANO_PRICING;
   }
-  if (modelId.includes("gpt-5-mini")) {
-    return OPENAI_GPT_5_MINI_PRICING;
+  if (modelId.includes("gpt-5.3-codex-spark")) {
+    return OPENAI_GPT_54_MINI_PRICING;
   }
-  if (modelId.includes("gpt-5.1-codex-mini")) {
-    return OPENAI_GPT_5_MINI_PRICING;
+  if (modelId.includes("gpt-5.4")) {
+    return OPENAI_GPT_54_PRICING;
   }
   return void 0;
 }
@@ -2718,22 +2709,15 @@ async function runOpenAiCall(fn, modelId, runOptions) {
 }
 
 // src/openai/models.ts
-var OPENAI_MODEL_IDS = [
-  "gpt-5.4",
-  "gpt-5.3-codex",
-  "gpt-5.2",
-  "gpt-5.1-codex-mini"
-];
+var OPENAI_MODEL_IDS = ["gpt-5.4", "gpt-5.4-mini", "gpt-5.4-nano"];
 function isOpenAiModelId(value) {
   return OPENAI_MODEL_IDS.includes(value);
 }
 var CHATGPT_MODEL_IDS = [
   "chatgpt-gpt-5.4",
   "chatgpt-gpt-5.4-fast",
-  "chatgpt-gpt-5.3-codex",
-  "chatgpt-gpt-5.3-codex-spark",
-  "chatgpt-gpt-5.2",
-  "chatgpt-gpt-5.1-codex-mini"
+  "chatgpt-gpt-5.4-mini",
+  "chatgpt-gpt-5.3-codex-spark"
 ];
 function isChatGptModelId(value) {
   return CHATGPT_MODEL_IDS.includes(value);
@@ -3256,19 +3240,16 @@ function getCurrentAgentLoggingSession() {
 
 // src/files.ts
 import { AsyncLocalStorage as AsyncLocalStorage2 } from "async_hooks";
-import { Buffer as Buffer4, File as NodeFile } from "buffer";
+import { Buffer as Buffer4 } from "buffer";
 import { createHash } from "crypto";
-import { createReadStream, createWriteStream, openAsBlob } from "fs";
-import { copyFile, mkdir as mkdir2, mkdtemp, readFile, stat, unlink, writeFile as writeFile2 } from "fs/promises";
+import { createReadStream } from "fs";
+import { copyFile, mkdir as mkdir2, readFile, stat, unlink, writeFile as writeFile2 } from "fs/promises";
 import os3 from "os";
 import path4 from "path";
-import { Readable } from "stream";
 import { pipeline } from "stream/promises";
 import { Storage } from "@google-cloud/storage";
 import mime from "mime";
 var DEFAULT_FILE_TTL_SECONDS = 48 * 60 * 60;
-var OPENAI_FILE_CREATE_MAX_BYTES = 512 * 1024 * 1024;
-var OPENAI_UPLOAD_PART_MAX_BYTES = 64 * 1024 * 1024;
 var GEMINI_FILE_POLL_INTERVAL_MS = 1e3;
 var GEMINI_FILE_POLL_TIMEOUT_MS = 6e4;
 var FILES_TEMP_ROOT = path4.join(os3.tmpdir(), "ljoukov-llm-files");
@@ -3277,7 +3258,7 @@ var FILES_CACHE_CONTENT_ROOT = path4.join(FILES_CACHE_ROOT, "content");
 var FILES_CACHE_METADATA_ROOT = path4.join(FILES_CACHE_ROOT, "metadata");
 var filesState = getRuntimeSingleton(/* @__PURE__ */ Symbol.for("@ljoukov/llm.filesState"), () => ({
   metadataById: /* @__PURE__ */ new Map(),
-  openAiUploadCacheByKey: /* @__PURE__ */ new Map(),
+  canonicalUploadCacheByKey: /* @__PURE__ */ new Map(),
   materializedById: /* @__PURE__ */ new Map(),
   geminiMirrorById: /* @__PURE__ */ new Map(),
   vertexMirrorById: /* @__PURE__ */ new Map(),
@@ -3358,7 +3339,7 @@ function formatUploadLogLine(event) {
 }
 function recordUploadEvent(event) {
   const scope = fileUploadScopeStorage.getStore();
-  const resolvedSource = event.source ?? scope?.source ?? (event.backend === "openai" ? "files_api" : "provider_mirror");
+  const resolvedSource = event.source ?? scope?.source ?? (event.backend === "gcs" ? "files_api" : "provider_mirror");
   const timestampedEvent = {
     ...event,
     source: resolvedSource,
@@ -3405,16 +3386,117 @@ async function computeFileSha256Hex(filePath) {
   }
   return hash.digest("hex");
 }
-function toStoredFile(file) {
+function buildCanonicalFileId(filename, mimeType, sha256Hex) {
+  return `file_${createHash("sha256").update(filename).update("\0").update(mimeType).update("\0").update(sha256Hex).digest("hex")}`;
+}
+function resolveCanonicalFilesBucket() {
+  const raw = process.env.LLM_FILES_GCS_BUCKET ?? process.env.VERTEX_GCS_BUCKET ?? process.env.LLM_VERTEX_GCS_BUCKET;
+  const trimmed = raw?.trim();
+  if (!trimmed) {
+    throw new Error(
+      "LLM_FILES_GCS_BUCKET (or VERTEX_GCS_BUCKET) must be set to use the canonical files API."
+    );
+  }
+  return trimmed.replace(/^gs:\/\//u, "").replace(/\/+$/u, "");
+}
+function resolveCanonicalFilesPrefix() {
+  const raw = process.env.LLM_FILES_GCS_PREFIX;
+  const trimmed = raw?.trim().replace(/^\/+/u, "").replace(/\/+$/u, "");
+  return trimmed ? `${trimmed}/` : "canonical-files/";
+}
+function isLatexLikeFile(filename, mimeType) {
+  const extension = path4.extname(filename).trim().toLowerCase();
+  const normalisedMimeType = mimeType.trim().toLowerCase();
+  return extension === ".tex" || extension === ".ltx" || extension === ".latex" || normalisedMimeType === "application/x-tex" || normalisedMimeType === "text/x-tex";
+}
+function resolveCanonicalStorageContentType(filename, mimeType) {
+  if (isLatexLikeFile(filename, mimeType)) {
+    return "text/plain";
+  }
+  return mimeType;
+}
+function resolveCanonicalObjectExtension(filename, mimeType) {
+  if (isLatexLikeFile(filename, mimeType)) {
+    return "txt";
+  }
+  const fromFilename = path4.extname(filename).replace(/^\./u, "").trim().toLowerCase();
+  if (fromFilename) {
+    return fromFilename;
+  }
+  const fromMimeType = mime.getExtension(mimeType)?.trim().toLowerCase();
+  if (fromMimeType) {
+    return fromMimeType;
+  }
+  return "bin";
+}
+function buildCanonicalObjectName(fileId, filename, mimeType) {
+  const extension = resolveCanonicalObjectExtension(filename, mimeType);
+  return `${resolveCanonicalFilesPrefix()}${fileId}.${extension}`;
+}
+function toSafeStorageFilename(filename) {
+  const normalized = normaliseFilename(filename).replace(/[^\w.-]+/gu, "-");
+  return normalized.length > 0 ? normalized : "attachment.bin";
+}
+function parseUnixSeconds(value, fallback) {
+  if (value) {
+    const numeric = Number.parseInt(value, 10);
+    if (Number.isFinite(numeric) && numeric > 0) {
+      return numeric;
+    }
+  }
+  if (fallback) {
+    const millis = Date.parse(fallback);
+    if (Number.isFinite(millis)) {
+      return Math.floor(millis / 1e3);
+    }
+  }
+  return Math.floor(Date.now() / 1e3);
+}
+function parseOptionalUnixSeconds(value) {
+  if (!value) {
+    return void 0;
+  }
+  const millis = Date.parse(value);
+  if (Number.isFinite(millis)) {
+    return Math.floor(millis / 1e3);
+  }
+  const numeric = Number.parseInt(value, 10);
+  return Number.isFinite(numeric) && numeric > 0 ? numeric : void 0;
+}
+function toStoredFileFromCanonicalMetadata(options) {
+  const metadata = options.objectMetadata.metadata;
+  const filenameRaw = typeof metadata?.filename === "string" && metadata.filename.trim().length > 0 ? metadata.filename.trim() : path4.basename(options.objectName);
+  const filename = normaliseFilename(filenameRaw);
+  const bytesRaw = options.objectMetadata.size;
+  const bytes = typeof bytesRaw === "string" ? Number.parseInt(bytesRaw, 10) : typeof bytesRaw === "number" ? bytesRaw : 0;
+  const purpose = metadata?.purpose === "user_data" ? "user_data" : "user_data";
+  const createdAt = parseUnixSeconds(
+    typeof metadata?.createdAtUnix === "string" ? metadata.createdAtUnix : void 0,
+    typeof options.objectMetadata.timeCreated === "string" ? options.objectMetadata.timeCreated : void 0
+  );
+  const expiresAt = parseOptionalUnixSeconds(
+    typeof metadata?.expiresAt === "string" ? metadata.expiresAt : void 0
+  );
+  const mimeType = typeof metadata?.mimeType === "string" && metadata.mimeType.trim().length > 0 ? metadata.mimeType.trim() : typeof options.objectMetadata.contentType === "string" && options.objectMetadata.contentType.trim().length > 0 ? options.objectMetadata.contentType.trim() : resolveMimeType(filename, void 0);
+  const sha256Hex = typeof metadata?.sha256 === "string" && metadata.sha256.trim().length > 0 ? metadata.sha256.trim() : void 0;
   return {
-    id: file.id,
-    bytes: file.bytes,
-    created_at: file.created_at,
-    filename: file.filename,
-    object: "file",
-    purpose: file.purpose,
-    status: file.status,
-    expires_at: file.expires_at
+    file: {
+      id: options.fileId,
+      bytes: Number.isFinite(bytes) ? bytes : 0,
+      created_at: createdAt,
+      filename,
+      object: "file",
+      purpose,
+      status: "processed",
+      ...expiresAt ? { expires_at: expiresAt } : {}
+    },
+    filename,
+    bytes: Number.isFinite(bytes) ? bytes : 0,
+    mimeType,
+    sha256Hex,
+    localPath: options.localPath,
+    bucketName: options.bucketName,
+    objectName: options.objectName
   };
 }
 function buildCacheKey(filename, mimeType, sha256Hex) {
@@ -3435,7 +3517,7 @@ function isFresh(file) {
 function recordMetadata(metadata) {
   filesState.metadataById.set(metadata.file.id, metadata);
   if (metadata.sha256Hex) {
-    filesState.openAiUploadCacheByKey.set(
+    filesState.canonicalUploadCacheByKey.set(
       buildCacheKey(
         metadata.filename,
         metadata.mimeType ?? "application/octet-stream",
@@ -3484,7 +3566,9 @@ async function persistMetadataToDisk(metadata) {
     bytes: metadata.bytes,
     mimeType: metadata.mimeType,
     sha256Hex: metadata.sha256Hex,
-    localPath: metadata.localPath
+    localPath: metadata.localPath,
+    bucketName: metadata.bucketName,
+    objectName: metadata.objectName
   };
   await writeFile2(
     buildCachedMetadataPath(metadata.file.id),
@@ -3516,175 +3600,271 @@ async function loadPersistedMetadata(fileId) {
       bytes: payload.bytes,
       mimeType: payload.mimeType,
       sha256Hex: payload.sha256Hex,
-      localPath: payload.localPath
+      localPath: payload.localPath,
+      bucketName: payload.bucketName,
+      objectName: payload.objectName
     });
   } catch {
     return void 0;
   }
 }
-async function uploadOpenAiFileFromBytes(params) {
-  const cacheKey = buildCacheKey(params.filename, params.mimeType, params.sha256Hex);
-  const cached = filesState.openAiUploadCacheByKey.get(cacheKey);
-  if (cached && isFresh(cached.file)) {
-    return cached;
+async function writeCanonicalFileFromPath(options) {
+  const file = getStorageClient().bucket(options.bucketName).file(options.objectName);
+  const storageContentType = resolveCanonicalStorageContentType(
+    options.metadata.filename ?? "attachment.bin",
+    options.mimeType
+  );
+  try {
+    await pipeline(
+      createReadStream(options.filePath),
+      file.createWriteStream({
+        resumable: options.bytes >= 10 * 1024 * 1024,
+        preconditionOpts: { ifGenerationMatch: 0 },
+        metadata: {
+          contentType: storageContentType,
+          contentDisposition: `inline; filename="${toSafeStorageFilename(options.metadata.filename ?? "attachment.bin")}"`,
+          metadata: options.metadata
+        }
+      })
+    );
+    return true;
+  } catch (error) {
+    const code = error.code;
+    if (code === 412 || code === "412") {
+      return false;
+    }
+    throw error;
   }
-  const client = getOpenAiClient();
-  const startedAtMs = Date.now();
-  let uploaded;
-  let mode;
-  if (params.bytes.byteLength <= OPENAI_FILE_CREATE_MAX_BYTES) {
-    mode = "files.create";
-    uploaded = await client.files.create({
-      file: new NodeFile([new Uint8Array(params.bytes)], params.filename, {
-        type: params.mimeType
-      }),
-      purpose: params.purpose,
-      expires_after: {
-        anchor: "created_at",
-        seconds: params.expiresAfterSeconds
+}
+async function writeCanonicalFileFromBytes(options) {
+  const file = getStorageClient().bucket(options.bucketName).file(options.objectName);
+  const storageContentType = resolveCanonicalStorageContentType(
+    options.metadata.filename ?? "attachment.bin",
+    options.mimeType
+  );
+  try {
+    await file.save(options.bytes, {
+      resumable: options.bytes.byteLength >= 10 * 1024 * 1024,
+      preconditionOpts: { ifGenerationMatch: 0 },
+      metadata: {
+        contentType: storageContentType,
+        contentDisposition: `inline; filename="${toSafeStorageFilename(options.metadata.filename ?? "attachment.bin")}"`,
+        metadata: options.metadata
       }
     });
-  } else {
-    mode = "uploads";
-    const upload = await client.uploads.create({
-      bytes: params.bytes.byteLength,
-      filename: params.filename,
-      mime_type: params.mimeType,
-      purpose: params.purpose
-    });
-    const partIds = [];
-    for (let offset = 0; offset < params.bytes.byteLength; offset += OPENAI_UPLOAD_PART_MAX_BYTES) {
-      const chunk = params.bytes.subarray(
-        offset,
-        Math.min(offset + OPENAI_UPLOAD_PART_MAX_BYTES, params.bytes.byteLength)
-      );
-      const uploadPart = await client.uploads.parts.create(upload.id, {
-        data: new NodeFile([new Uint8Array(chunk)], `${params.sha256Hex}.part`, {
-          type: params.mimeType
-        })
-      });
-      partIds.push(uploadPart.id);
-    }
-    const completed = await client.uploads.complete(upload.id, { part_ids: partIds });
-    const fileId = completed.file?.id;
-    if (!fileId) {
-      throw new Error("OpenAI upload completed without a file id.");
+    return true;
+  } catch (error) {
+    const code = error.code;
+    if (code === 412 || code === "412") {
+      return false;
     }
-    uploaded = await client.files.retrieve(fileId);
+    throw error;
   }
-  const file = toStoredFile(uploaded);
-  const metadata = recordMetadata({
-    file,
-    filename: file.filename,
-    bytes: file.bytes,
-    mimeType: params.mimeType,
-    sha256Hex: params.sha256Hex
+}
+async function refreshCanonicalObjectMetadata(options) {
+  const storageContentType = resolveCanonicalStorageContentType(
+    options.metadata.filename ?? "attachment.bin",
+    options.mimeType
+  );
+  await getStorageClient().bucket(options.bucketName).file(options.objectName).setMetadata({
+    contentType: storageContentType,
+    contentDisposition: `inline; filename="${toSafeStorageFilename(options.metadata.filename ?? "attachment.bin")}"`,
+    metadata: options.metadata
   });
-  recordUploadEvent({
-    backend: "openai",
-    mode,
-    filename: metadata.filename,
-    bytes: metadata.bytes,
-    durationMs: Math.max(0, Date.now() - startedAtMs),
-    mimeType: params.mimeType,
-    fileId: metadata.file.id
+}
+async function createCanonicalMetadata(options) {
+  const createdAt = Math.floor(Date.now() / 1e3);
+  const expiresAt = createdAt + options.expiresAfterSeconds;
+  const storedFile = {
+    id: options.fileId,
+    bytes: options.bytes,
+    created_at: createdAt,
+    filename: options.filename,
+    object: "file",
+    purpose: options.purpose,
+    status: "processed",
+    expires_at: expiresAt
+  };
+  const metadata = recordMetadata({
+    file: storedFile,
+    filename: options.filename,
+    bytes: options.bytes,
+    mimeType: options.mimeType,
+    sha256Hex: options.sha256Hex,
+    localPath: options.localPath,
+    bucketName: options.bucketName,
+    objectName: options.objectName
   });
+  await persistMetadataToDisk(metadata);
   return metadata;
 }
-async function uploadOpenAiFileFromPath(params) {
+async function uploadCanonicalFileFromBytes(params) {
   const cacheKey = buildCacheKey(params.filename, params.mimeType, params.sha256Hex);
-  const cached = filesState.openAiUploadCacheByKey.get(cacheKey);
+  const cached = filesState.canonicalUploadCacheByKey.get(cacheKey);
   if (cached && isFresh(cached.file)) {
     return cached;
   }
-  const client = getOpenAiClient();
+  const fileId = buildCanonicalFileId(params.filename, params.mimeType, params.sha256Hex);
+  const bucketName = resolveCanonicalFilesBucket();
+  const objectName = buildCanonicalObjectName(fileId, params.filename, params.mimeType);
+  const metadataFields = {
+    fileId,
+    filename: params.filename,
+    mimeType: params.mimeType,
+    purpose: params.purpose,
+    sha256: params.sha256Hex,
+    createdAtUnix: Math.floor(Date.now() / 1e3).toString(),
+    expiresAt: new Date(Date.now() + params.expiresAfterSeconds * 1e3).toISOString()
+  };
   const startedAtMs = Date.now();
-  let uploaded;
-  let mode;
-  if (params.bytes <= OPENAI_FILE_CREATE_MAX_BYTES) {
-    mode = "files.create";
-    const blob = await openAsBlob(params.filePath, { type: params.mimeType });
-    uploaded = await client.files.create({
-      file: new NodeFile([blob], params.filename, { type: params.mimeType }),
-      purpose: params.purpose,
-      expires_after: {
-        anchor: "created_at",
-        seconds: params.expiresAfterSeconds
-      }
+  const uploaded = await writeCanonicalFileFromBytes({
+    bytes: params.bytes,
+    bucketName,
+    objectName,
+    mimeType: params.mimeType,
+    metadata: metadataFields
+  });
+  if (!uploaded) {
+    await refreshCanonicalObjectMetadata({
+      bucketName,
+      objectName,
+      mimeType: params.mimeType,
+      metadata: metadataFields
     });
-  } else {
-    mode = "uploads";
-    const upload = await client.uploads.create({
-      bytes: params.bytes,
+  }
+  const localPath = await cacheBufferLocally(params.bytes, params.sha256Hex);
+  const canonical = await createCanonicalMetadata({
+    fileId,
+    filename: params.filename,
+    mimeType: params.mimeType,
+    purpose: params.purpose,
+    expiresAfterSeconds: params.expiresAfterSeconds,
+    sha256Hex: params.sha256Hex,
+    bytes: params.bytes.byteLength,
+    bucketName,
+    objectName,
+    localPath
+  });
+  if (uploaded) {
+    recordUploadEvent({
+      backend: "gcs",
+      mode: "gcs",
       filename: params.filename,
-      mime_type: params.mimeType,
-      purpose: params.purpose
-    });
-    const partIds = [];
-    const stream = createReadStream(params.filePath, {
-      highWaterMark: OPENAI_UPLOAD_PART_MAX_BYTES
+      bytes: params.bytes.byteLength,
+      durationMs: Math.max(0, Date.now() - startedAtMs),
+      mimeType: params.mimeType,
+      fileId,
+      fileUri: `gs://${bucketName}/${objectName}`
     });
-    let partIndex = 0;
-    for await (const chunk of stream) {
-      const buffer = Buffer4.isBuffer(chunk) ? chunk : Buffer4.from(chunk);
-      const uploadPart = await client.uploads.parts.create(upload.id, {
-        data: new NodeFile(
-          [new Uint8Array(buffer)],
-          `${params.sha256Hex}.${partIndex.toString()}.part`,
-          {
-            type: params.mimeType
-          }
-        )
-      });
-      partIds.push(uploadPart.id);
-      partIndex += 1;
-    }
-    const completed = await client.uploads.complete(upload.id, { part_ids: partIds });
-    const fileId = completed.file?.id;
-    if (!fileId) {
-      throw new Error("OpenAI upload completed without a file id.");
-    }
-    uploaded = await client.files.retrieve(fileId);
   }
-  const file = toStoredFile(uploaded);
-  const metadata = recordMetadata({
-    file,
-    filename: file.filename,
-    bytes: file.bytes,
+  return canonical;
+}
+async function uploadCanonicalFileFromPath(params) {
+  const cacheKey = buildCacheKey(params.filename, params.mimeType, params.sha256Hex);
+  const cached = filesState.canonicalUploadCacheByKey.get(cacheKey);
+  if (cached && isFresh(cached.file)) {
+    return cached;
+  }
+  const fileId = buildCanonicalFileId(params.filename, params.mimeType, params.sha256Hex);
+  const bucketName = resolveCanonicalFilesBucket();
+  const objectName = buildCanonicalObjectName(fileId, params.filename, params.mimeType);
+  const metadataFields = {
+    fileId,
+    filename: params.filename,
+    mimeType: params.mimeType,
+    purpose: params.purpose,
+    sha256: params.sha256Hex,
+    createdAtUnix: Math.floor(Date.now() / 1e3).toString(),
+    expiresAt: new Date(Date.now() + params.expiresAfterSeconds * 1e3).toISOString()
+  };
+  const startedAtMs = Date.now();
+  const uploaded = await writeCanonicalFileFromPath({
+    filePath: params.filePath,
+    bucketName,
+    objectName,
+    bytes: params.bytes,
     mimeType: params.mimeType,
-    sha256Hex: params.sha256Hex
+    metadata: metadataFields
   });
-  recordUploadEvent({
-    backend: "openai",
-    mode,
-    filename: metadata.filename,
-    bytes: metadata.bytes,
-    durationMs: Math.max(0, Date.now() - startedAtMs),
+  if (!uploaded) {
+    await refreshCanonicalObjectMetadata({
+      bucketName,
+      objectName,
+      mimeType: params.mimeType,
+      metadata: metadataFields
+    });
+  }
+  const localPath = await cacheFileLocally(params.filePath, params.sha256Hex);
+  const canonical = await createCanonicalMetadata({
+    fileId,
+    filename: params.filename,
     mimeType: params.mimeType,
-    fileId: metadata.file.id
+    purpose: params.purpose,
+    expiresAfterSeconds: params.expiresAfterSeconds,
+    sha256Hex: params.sha256Hex,
+    bytes: params.bytes,
+    bucketName,
+    objectName,
+    localPath
   });
-  return metadata;
+  if (uploaded) {
+    recordUploadEvent({
+      backend: "gcs",
+      mode: "gcs",
+      filename: params.filename,
+      bytes: params.bytes,
+      durationMs: Math.max(0, Date.now() - startedAtMs),
+      mimeType: params.mimeType,
+      fileId,
+      fileUri: `gs://${bucketName}/${objectName}`
+    });
+  }
+  return canonical;
+}
+async function resolveCanonicalStorageLocation(fileId) {
+  const cached = filesState.metadataById.get(fileId) ?? await loadPersistedMetadata(fileId);
+  if (cached?.bucketName && cached.objectName) {
+    return {
+      bucketName: cached.bucketName,
+      objectName: cached.objectName
+    };
+  }
+  const bucketName = resolveCanonicalFilesBucket();
+  const [files2] = await getStorageClient().bucket(bucketName).getFiles({
+    prefix: `${resolveCanonicalFilesPrefix()}${fileId}.`,
+    maxResults: 1,
+    autoPaginate: false
+  });
+  const file = files2[0];
+  if (!file) {
+    throw new Error(`Canonical file ${fileId} was not found in GCS.`);
+  }
+  return {
+    bucketName,
+    objectName: file.name
+  };
 }
-async function retrieveOpenAiFile(fileId) {
+async function retrieveCanonicalFile(fileId) {
   const cached = filesState.metadataById.get(fileId);
-  if (cached && isFresh(cached.file)) {
+  if (cached && isFresh(cached.file) && cached.bucketName && cached.objectName) {
     return cached;
   }
   const persisted = await loadPersistedMetadata(fileId);
-  if (persisted && isFresh(persisted.file)) {
+  if (persisted && isFresh(persisted.file) && persisted.bucketName && persisted.objectName) {
     return persisted;
   }
-  const client = getOpenAiClient();
-  const retrieved = await client.files.retrieve(fileId);
-  const file = toStoredFile(retrieved);
-  const metadata = recordMetadata({
-    file,
-    filename: file.filename,
-    bytes: file.bytes,
-    mimeType: cached?.mimeType ?? persisted?.mimeType ?? resolveMimeType(file.filename, void 0),
-    sha256Hex: cached?.sha256Hex ?? persisted?.sha256Hex,
-    localPath: cached?.localPath ?? persisted?.localPath
-  });
+  const existingLocalPath = cached?.localPath ?? persisted?.localPath;
+  const { bucketName, objectName } = await resolveCanonicalStorageLocation(fileId);
+  const [objectMetadata] = await getStorageClient().bucket(bucketName).file(objectName).getMetadata();
+  const metadata = recordMetadata(
+    toStoredFileFromCanonicalMetadata({
+      fileId,
+      bucketName,
+      objectName,
+      objectMetadata,
+      localPath: existingLocalPath
+    })
+  );
   await persistMetadataToDisk(metadata);
   return metadata;
 }
@@ -3712,7 +3892,7 @@ function resolveVertexMirrorBucket() {
   const trimmed = raw?.trim();
   if (!trimmed) {
     throw new Error(
-      "VERTEX_GCS_BUCKET must be set to use OpenAI-backed file ids with Vertex Gemini models."
+      "VERTEX_GCS_BUCKET must be set to use canonical file ids with Vertex Gemini models."
     );
   }
   return trimmed.replace(/^gs:\/\//u, "").replace(/\/+$/u, "");
@@ -3742,61 +3922,41 @@ function getGeminiMirrorClient() {
   }
   return filesState.geminiClientPromise;
 }
-async function materializeOpenAiFile(fileId) {
+async function materializeCanonicalFile(fileId) {
   const cachedPromise = filesState.materializedById.get(fileId);
   if (cachedPromise) {
     return await cachedPromise;
   }
   const promise = (async () => {
-    const metadata = await retrieveOpenAiFile(fileId);
-    if (metadata.localPath && metadata.sha256Hex && metadata.mimeType) {
+    const metadata = await retrieveCanonicalFile(fileId);
+    if (metadata.localPath && metadata.sha256Hex && metadata.mimeType && metadata.bucketName && metadata.objectName) {
       return {
         file: metadata.file,
         filename: metadata.filename,
         bytes: metadata.bytes,
         mimeType: metadata.mimeType,
         sha256Hex: metadata.sha256Hex,
-        localPath: metadata.localPath
+        localPath: metadata.localPath,
+        bucketName: metadata.bucketName,
+        objectName: metadata.objectName
       };
     }
-    await mkdir2(FILES_TEMP_ROOT, { recursive: true });
-    const tempDir = await mkdtemp(
-      path4.join(FILES_TEMP_ROOT, `${fileId.replace(/[^a-z0-9_-]/giu, "")}-`)
-    );
-    const localPath = path4.join(tempDir, normaliseFilename(metadata.filename, `${fileId}.bin`));
-    const response = await getOpenAiClient().files.content(fileId);
-    if (!response.ok) {
-      throw new Error(
-        `Failed to download OpenAI file ${fileId}: ${response.status} ${response.statusText}`
-      );
+    if (!metadata.bucketName || !metadata.objectName) {
+      throw new Error(`Canonical file ${fileId} is missing GCS location metadata.`);
     }
-    const responseMimeType = response.headers.get("content-type")?.trim() || void 0;
-    const mimeType = resolveMimeType(metadata.filename, responseMimeType);
-    const hash = createHash("sha256");
-    let bytes = 0;
-    if (response.body) {
-      const source = Readable.fromWeb(response.body);
-      const writable = createWriteStream(localPath, { flags: "wx" });
-      source.on("data", (chunk) => {
-        const buffer = Buffer4.isBuffer(chunk) ? chunk : Buffer4.from(chunk);
-        hash.update(buffer);
-        bytes += buffer.byteLength;
-      });
-      await pipeline(source, writable);
-    } else {
-      const buffer = Buffer4.from(await response.arrayBuffer());
-      hash.update(buffer);
-      bytes = buffer.byteLength;
-      await writeFile2(localPath, buffer);
-    }
-    const sha256Hex = hash.digest("hex");
+    const [downloadedBytes] = await getStorageClient().bucket(metadata.bucketName).file(metadata.objectName).download();
+    const mimeType = metadata.mimeType ?? resolveMimeType(metadata.filename, void 0);
+    const sha256Hex = metadata.sha256Hex ?? computeSha256Hex(downloadedBytes);
+    const localPath = await cacheBufferLocally(downloadedBytes, sha256Hex);
     const updated = recordMetadata({
       file: metadata.file,
       filename: metadata.filename,
-      bytes: bytes || metadata.bytes,
+      bytes: downloadedBytes.byteLength || metadata.bytes,
       mimeType,
       sha256Hex,
-      localPath
+      localPath,
+      bucketName: metadata.bucketName,
+      objectName: metadata.objectName
     });
     await persistMetadataToDisk(updated);
     return {
@@ -3805,7 +3965,9 @@ async function materializeOpenAiFile(fileId) {
       bytes: updated.bytes,
       mimeType: updated.mimeType ?? mimeType,
       sha256Hex,
-      localPath
+      localPath,
+      bucketName: metadata.bucketName,
+      objectName: metadata.objectName
     };
   })();
   filesState.materializedById.set(fileId, promise);
@@ -3821,14 +3983,14 @@ async function ensureGeminiFileMirror(fileId) {
   if (cached) {
     return cached;
   }
-  const materialized = await materializeOpenAiFile(fileId);
+  const materialized = await materializeCanonicalFile(fileId);
   const client = await getGeminiMirrorClient();
   const name = buildGeminiMirrorName(materialized.sha256Hex);
   try {
     const existing = await client.files.get({ name });
     if (existing.name && existing.uri && existing.mimeType) {
       const mirror2 = {
-        openAiFileId: fileId,
+        canonicalFileId: fileId,
         name: existing.name,
         uri: existing.uri,
         mimeType: existing.mimeType,
@@ -3856,7 +4018,7 @@ async function ensureGeminiFileMirror(fileId) {
     throw new Error("Gemini file upload completed without a usable URI.");
   }
   const mirror = {
-    openAiFileId: fileId,
+    canonicalFileId: fileId,
     name: resolved.name,
     uri: resolved.uri,
     mimeType: resolved.mimeType,
@@ -3881,7 +4043,7 @@ async function ensureVertexFileMirror(fileId) {
   if (cached) {
     return cached;
   }
-  const materialized = await materializeOpenAiFile(fileId);
+  const materialized = await materializeCanonicalFile(fileId);
   const bucketName = resolveVertexMirrorBucket();
   const prefix = resolveVertexMirrorPrefix();
   const extension = mime.getExtension(materialized.mimeType) ?? path4.extname(materialized.filename).replace(/^\./u, "") ?? "bin";
@@ -3922,7 +4084,7 @@ async function ensureVertexFileMirror(fileId) {
     }
   }
   const mirror = {
-    openAiFileId: fileId,
+    canonicalFileId: fileId,
     bucket: bucketName,
     objectName,
     fileUri: `gs://${bucketName}/${objectName}`,
@@ -3953,7 +4115,7 @@ async function filesCreate(params) {
     const filename2 = normaliseFilename(params.filename, path4.basename(filePath));
     const mimeType2 = resolveMimeType(filename2, params.mimeType);
     const sha256Hex2 = await computeFileSha256Hex(filePath);
-    const uploaded2 = await uploadOpenAiFileFromPath({
+    const uploaded2 = await uploadCanonicalFileFromPath({
       filePath,
       filename: filename2,
       mimeType: mimeType2,
@@ -3962,19 +4124,13 @@ async function filesCreate(params) {
       sha256Hex: sha256Hex2,
       bytes: info.size
     });
-    const localPath2 = await cacheFileLocally(filePath, sha256Hex2);
-    const cached2 = recordMetadata({
-      ...uploaded2,
-      localPath: localPath2
-    });
-    await persistMetadataToDisk(cached2);
-    return cached2.file;
+    return uploaded2.file;
   }
   const filename = normaliseFilename(params.filename);
   const bytes = toBuffer(params.data);
   const mimeType = resolveMimeType(filename, params.mimeType, "text/plain");
   const sha256Hex = computeSha256Hex(bytes);
-  const uploaded = await uploadOpenAiFileFromBytes({
+  const uploaded = await uploadCanonicalFileFromBytes({
     bytes,
     filename,
     mimeType,
@@ -3982,16 +4138,10 @@ async function filesCreate(params) {
     expiresAfterSeconds,
     sha256Hex
   });
-  const localPath = await cacheBufferLocally(bytes, sha256Hex);
-  const cached = recordMetadata({
-    ...uploaded,
-    localPath
-  });
-  await persistMetadataToDisk(cached);
-  return cached.file;
+  return uploaded.file;
 }
 async function filesRetrieve(fileId) {
-  return (await retrieveOpenAiFile(fileId)).file;
+  return (await retrieveCanonicalFile(fileId)).file;
 }
 async function filesDelete(fileId) {
   const cachedGemini = filesState.geminiMirrorById.get(fileId);
@@ -4018,34 +4168,73 @@ async function filesDelete(fileId) {
     } catch {
     }
   }
-  const response = await getOpenAiClient().files.delete(fileId);
+  try {
+    const { bucketName, objectName } = await resolveCanonicalStorageLocation(fileId);
+    await getStorageClient().bucket(bucketName).file(objectName).delete({ ignoreNotFound: true });
+  } catch {
+  }
   filesState.metadataById.delete(fileId);
+  filesState.canonicalUploadCacheByKey.forEach((value, key) => {
+    if (value.file.id === fileId) {
+      filesState.canonicalUploadCacheByKey.delete(key);
+    }
+  });
   filesState.materializedById.delete(fileId);
   try {
     await unlink(buildCachedMetadataPath(fileId));
   } catch {
   }
   return {
-    id: response.id,
-    deleted: response.deleted,
+    id: fileId,
+    deleted: true,
     object: "file"
   };
 }
 async function filesContent(fileId) {
-  return await getOpenAiClient().files.content(fileId);
+  const metadata = await retrieveCanonicalFile(fileId);
+  if (!metadata.bucketName || !metadata.objectName) {
+    throw new Error(`Canonical file ${fileId} is missing GCS location metadata.`);
+  }
+  const [bytes] = await getStorageClient().bucket(metadata.bucketName).file(metadata.objectName).download();
+  const headers = new Headers();
+  headers.set("content-type", metadata.mimeType ?? resolveMimeType(metadata.filename, void 0));
+  headers.set("content-length", bytes.byteLength.toString());
+  headers.set(
+    "content-disposition",
+    `inline; filename="${toSafeStorageFilename(metadata.filename)}"`
+  );
+  return new Response(bytes, {
+    status: 200,
+    headers
+  });
 }
 async function getCanonicalFileMetadata(fileId) {
-  const metadata = await retrieveOpenAiFile(fileId);
+  const metadata = await retrieveCanonicalFile(fileId);
   const mimeType = metadata.mimeType ?? resolveMimeType(metadata.filename, void 0);
   const updated = metadata.mimeType === mimeType ? metadata : recordMetadata({
     ...metadata,
     mimeType
   });
+  if (!updated.bucketName || !updated.objectName) {
+    throw new Error(`Canonical file ${fileId} is missing GCS location metadata.`);
+  }
   return {
     ...updated,
-    mimeType
+    mimeType,
+    bucketName: updated.bucketName,
+    objectName: updated.objectName
   };
 }
+async function getCanonicalFileSignedUrl(options) {
+  const metadata = await getCanonicalFileMetadata(options.fileId);
+  const [signedUrl] = await getStorageClient().bucket(metadata.bucketName).file(metadata.objectName).getSignedUrl({
+    version: "v4",
+    action: "read",
+    expires: Date.now() + (options.expiresAfterSeconds ?? 15 * 60) * 1e3,
+    responseType: resolveCanonicalStorageContentType(metadata.filename, metadata.mimeType)
+  });
+  return signedUrl;
+}
 var files = {
   create: filesCreate,
   retrieve: filesRetrieve,
@@ -4407,6 +4596,7 @@ function isJsonSchemaObject(schema) {
   return false;
 }
 var CANONICAL_GEMINI_FILE_URI_PREFIX = "openai://file/";
+var CANONICAL_LLM_FILE_ID_PATTERN = /^file_[a-f0-9]{64}$/u;
 function buildCanonicalGeminiFileUri(fileId) {
   return `${CANONICAL_GEMINI_FILE_URI_PREFIX}${fileId}`;
 }
@@ -4417,6 +4607,75 @@ function parseCanonicalGeminiFileId(fileUri) {
   const fileId = fileUri.slice(CANONICAL_GEMINI_FILE_URI_PREFIX.length).trim();
   return fileId.length > 0 ? fileId : void 0;
 }
+function isCanonicalLlmFileId(fileId) {
+  return typeof fileId === "string" && CANONICAL_LLM_FILE_ID_PATTERN.test(fileId.trim());
+}
+function isLlmMediaResolution(value) {
+  return value === "auto" || value === "low" || value === "medium" || value === "high" || value === "original";
+}
+function resolveEffectiveMediaResolution(detail, fallback) {
+  return detail ?? fallback;
+}
+function supportsOpenAiOriginalImageDetail(model) {
+  if (!model) {
+    return false;
+  }
+  const providerModel = isChatGptModelId(model) ? resolveChatGptProviderModel(model) : model;
+  const match = /^gpt-(\d+)(?:\.(\d+))?/u.exec(providerModel);
+  if (!match) {
+    return false;
+  }
+  const major = Number(match[1]);
+  const minor = Number(match[2] ?? "0");
+  if (!Number.isFinite(major) || !Number.isFinite(minor)) {
+    return false;
+  }
+  return major > 5 || major === 5 && minor >= 4;
+}
+function toOpenAiImageDetail(mediaResolution, model) {
+  switch (mediaResolution) {
+    case "low":
+      return "low";
+    case "medium":
+      return "high";
+    case "high":
+      return "high";
+    case "original":
+      return supportsOpenAiOriginalImageDetail(model) ? "original" : "high";
+    case "auto":
+    default:
+      return "auto";
+  }
+}
+function toGeminiMediaResolution(mediaResolution) {
+  switch (mediaResolution) {
+    case "low":
+      return MediaResolution.MEDIA_RESOLUTION_LOW;
+    case "medium":
+      return MediaResolution.MEDIA_RESOLUTION_MEDIUM;
+    case "high":
+    case "original":
+      return MediaResolution.MEDIA_RESOLUTION_HIGH;
+    case "auto":
+    default:
+      return void 0;
+  }
+}
+function toGeminiPartMediaResolution(mediaResolution) {
+  switch (mediaResolution) {
+    case "low":
+      return PartMediaResolutionLevel.MEDIA_RESOLUTION_LOW;
+    case "medium":
+      return PartMediaResolutionLevel.MEDIA_RESOLUTION_MEDIUM;
+    case "high":
+      return PartMediaResolutionLevel.MEDIA_RESOLUTION_HIGH;
+    case "original":
+      return PartMediaResolutionLevel.MEDIA_RESOLUTION_ULTRA_HIGH;
+    case "auto":
+    default:
+      return void 0;
+  }
+}
 function cloneContentPart(part) {
   switch (part.type) {
     case "text":
@@ -4545,7 +4804,8 @@ function convertGeminiContentToLlmContent(content) {
     parts: convertGooglePartsToLlmParts(content.parts ?? [])
   };
 }
-function toGeminiPart(part) {
+function toGeminiPart(part, options) {
+  const defaultMediaResolution = options?.defaultMediaResolution;
   switch (part.type) {
     case "text":
       return {
@@ -4553,6 +4813,18 @@ function toGeminiPart(part) {
         thought: part.thought === true ? true : void 0
       };
     case "inlineData": {
+      if (isInlineImageMime(part.mimeType)) {
+        const mimeType = part.mimeType ?? "application/octet-stream";
+        const geminiPart = createPartFromBase64(
+          part.data,
+          mimeType,
+          toGeminiPartMediaResolution(defaultMediaResolution)
+        );
+        if (part.filename && geminiPart.inlineData) {
+          geminiPart.inlineData.displayName = part.filename;
+        }
+        return geminiPart;
+      }
       const inlineData = {
         data: part.data,
         mimeType: part.mimeType
@@ -4565,31 +4837,35 @@ function toGeminiPart(part) {
       };
     }
     case "input_image": {
+      const mediaResolution = resolveEffectiveMediaResolution(part.detail, defaultMediaResolution);
+      const geminiPartMediaResolution = toGeminiPartMediaResolution(mediaResolution);
       if (part.file_id) {
-        return {
-          fileData: {
-            fileUri: buildCanonicalGeminiFileUri(part.file_id),
-            mimeType: inferToolOutputMimeTypeFromFilename(part.filename) ?? "application/octet-stream"
-          }
-        };
+        return createPartFromUri(
+          buildCanonicalGeminiFileUri(part.file_id),
+          inferToolOutputMimeTypeFromFilename(part.filename) ?? "application/octet-stream",
+          geminiPartMediaResolution
+        );
       }
       if (typeof part.image_url !== "string" || part.image_url.trim().length === 0) {
         throw new Error("input_image requires image_url or file_id.");
       }
       const parsed = parseDataUrlPayload(part.image_url);
       if (parsed) {
-        const geminiPart = createPartFromBase64(parsed.dataBase64, parsed.mimeType);
+        const geminiPart = createPartFromBase64(
+          parsed.dataBase64,
+          parsed.mimeType,
+          geminiPartMediaResolution
+        );
         if (part.filename && geminiPart.inlineData) {
           geminiPart.inlineData.displayName = part.filename;
         }
         return geminiPart;
       }
-      return {
-        fileData: {
-          fileUri: part.image_url,
-          mimeType: inferToolOutputMimeTypeFromFilename(part.filename) ?? "application/octet-stream"
-        }
-      };
+      return createPartFromUri(
+        part.image_url,
+        inferToolOutputMimeTypeFromFilename(part.filename) ?? "application/octet-stream",
+        geminiPartMediaResolution
+      );
     }
     case "input_file": {
       if (part.file_id) {
@@ -4632,11 +4908,11 @@ function toGeminiPart(part) {
       throw new Error("Unsupported LLM content part");
   }
 }
-function convertLlmContentToGeminiContent(content) {
+function convertLlmContentToGeminiContent(content, options) {
   const role = content.role === "assistant" ? "model" : "user";
   return {
     role,
-    parts: content.parts.map(toGeminiPart)
+    parts: content.parts.map((part) => toGeminiPart(part, options))
   };
 }
 function resolveProvider(model) {
@@ -4817,11 +5093,25 @@ async function storeCanonicalPromptFile(options) {
     mimeType: options.mimeType
   };
 }
-async function prepareOpenAiPromptContentItem(item) {
+async function prepareOpenAiPromptContentItem(item, options) {
   if (!isOpenAiNativeContentItem(item)) {
     return item;
   }
-  if (item.type === "input_image" && typeof item.image_url === "string" && item.image_url.trim().toLowerCase().startsWith("data:")) {
+  if (item.type === "input_image") {
+    if (isCanonicalLlmFileId(item.file_id)) {
+      const signedUrl2 = await getCanonicalFileSignedUrl({ fileId: item.file_id });
+      return {
+        type: "input_image",
+        image_url: signedUrl2,
+        detail: toOpenAiImageDetail(
+          isLlmMediaResolution(item.detail) ? item.detail : void 0,
+          options?.model
+        )
+      };
+    }
+    if (options?.offloadInlineData !== true || typeof item.image_url !== "string" || !item.image_url.trim().toLowerCase().startsWith("data:")) {
+      return item;
+    }
     const parsed = parseDataUrlPayload(item.image_url);
     if (!parsed) {
       return item;
@@ -4834,13 +5124,27 @@ async function prepareOpenAiPromptContentItem(item) {
         guessInlineDataFilename(parsed.mimeType)
       )
     });
+    const signedUrl = await getCanonicalFileSignedUrl({ fileId: uploaded.fileId });
     return {
       type: "input_image",
-      detail: item.detail === "high" || item.detail === "low" ? item.detail : "auto",
-      file_id: uploaded.fileId
+      image_url: signedUrl,
+      detail: toOpenAiImageDetail(
+        isLlmMediaResolution(item.detail) ? item.detail : void 0,
+        options?.model
+      )
+    };
+  }
+  if (item.type !== "input_file") {
+    return item;
+  }
+  if (isCanonicalLlmFileId(item.file_id)) {
+    const signedUrl = await getCanonicalFileSignedUrl({ fileId: item.file_id });
+    return {
+      type: "input_file",
+      file_url: signedUrl
     };
   }
-  if (item.type !== "input_file" || item.file_id) {
+  if (options?.offloadInlineData !== true) {
     return item;
   }
   if (typeof item.file_data === "string" && item.file_data.trim().length > 0) {
@@ -4854,7 +5158,11 @@ async function prepareOpenAiPromptContentItem(item) {
       mimeType,
       filename
     });
-    return { type: "input_file", file_id: uploaded.fileId };
+    const signedUrl = await getCanonicalFileSignedUrl({ fileId: uploaded.fileId });
+    return {
+      type: "input_file",
+      file_url: signedUrl
+    };
   }
   if (typeof item.file_url === "string" && item.file_url.trim().toLowerCase().startsWith("data:")) {
     const parsed = parseDataUrlPayload(item.file_url);
@@ -4869,11 +5177,15 @@ async function prepareOpenAiPromptContentItem(item) {
         guessInlineDataFilename(parsed.mimeType)
       )
     });
-    return { type: "input_file", file_id: uploaded.fileId };
+    const signedUrl = await getCanonicalFileSignedUrl({ fileId: uploaded.fileId });
+    return {
+      type: "input_file",
+      file_url: signedUrl
+    };
   }
   return item;
 }
-async function prepareOpenAiPromptInput(input) {
+async function prepareOpenAiPromptInput(input, options) {
   const prepareItem = async (item) => {
     if (!item || typeof item !== "object") {
       return item;
@@ -4883,7 +5195,7 @@ async function prepareOpenAiPromptInput(input) {
       return {
         ...record,
         content: await Promise.all(
-          record.content.map((part) => prepareOpenAiPromptContentItem(part))
+          record.content.map((part) => prepareOpenAiPromptContentItem(part, options))
         )
       };
     }
@@ -4891,19 +5203,48 @@ async function prepareOpenAiPromptInput(input) {
       return {
         ...record,
         output: await Promise.all(
-          record.output.map((part) => prepareOpenAiPromptContentItem(part))
+          record.output.map((part) => prepareOpenAiPromptContentItem(part, options))
         )
       };
     }
-    return await prepareOpenAiPromptContentItem(item);
+    return await prepareOpenAiPromptContentItem(item, options);
   };
   return await Promise.all(input.map((item) => prepareItem(item)));
 }
-async function maybePrepareOpenAiPromptInput(input) {
-  if (estimateOpenAiInlinePromptBytes(input) <= INLINE_ATTACHMENT_PROMPT_THRESHOLD_BYTES) {
+function hasCanonicalOpenAiFileReferences(input) {
+  let found = false;
+  const visitItems = (items) => {
+    for (const item of items) {
+      if (found || !item || typeof item !== "object") {
+        continue;
+      }
+      if (Array.isArray(item.content)) {
+        visitItems(item.content);
+      }
+      if (Array.isArray(item.output)) {
+        visitItems(item.output);
+      }
+      if (!isOpenAiNativeContentItem(item)) {
+        continue;
+      }
+      if ((item.type === "input_image" || item.type === "input_file") && isCanonicalLlmFileId(item.file_id)) {
+        found = true;
+        return;
+      }
+    }
+  };
+  visitItems(input);
+  return found;
+}
+async function maybePrepareOpenAiPromptInput(input, options) {
+  const offloadInlineData = estimateOpenAiInlinePromptBytes(input) > INLINE_ATTACHMENT_PROMPT_THRESHOLD_BYTES;
+  if (!offloadInlineData && !hasCanonicalOpenAiFileReferences(input)) {
     return Array.from(input);
   }
-  return await prepareOpenAiPromptInput(input);
+  return await prepareOpenAiPromptInput(input, {
+    ...options,
+    offloadInlineData
+  });
 }
 function estimateGeminiInlinePromptBytes(contents) {
   let total = 0;
@@ -4934,22 +5275,25 @@ async function prepareGeminiPromptContents(contents) {
     for (const part of content.parts ?? []) {
       const canonicalFileId = parseCanonicalGeminiFileId(part.fileData?.fileUri);
       if (canonicalFileId) {
+        const mediaResolution = part.mediaResolution?.level;
         await getCanonicalFileMetadata(canonicalFileId);
         if (backend === "api") {
           const mirrored = await ensureGeminiFileMirror(canonicalFileId);
-          parts.push(createPartFromUri(mirrored.uri, mirrored.mimeType));
+          parts.push(createPartFromUri(mirrored.uri, mirrored.mimeType, mediaResolution));
         } else {
           const mirrored = await ensureVertexFileMirror(canonicalFileId);
           parts.push({
             fileData: {
               fileUri: mirrored.fileUri,
               mimeType: mirrored.mimeType
-            }
+            },
+            ...mediaResolution ? { mediaResolution: { level: mediaResolution } } : {}
           });
         }
         continue;
       }
       if (part.inlineData?.data) {
+        const mediaResolution = part.mediaResolution?.level;
         const mimeType = part.inlineData.mimeType ?? "application/octet-stream";
         const filename = normaliseAttachmentFilename(
           getInlineAttachmentFilename(part.inlineData) ?? part.inlineData.displayName ?? guessInlineDataFilename(mimeType),
@@ -4962,14 +5306,15 @@ async function prepareGeminiPromptContents(contents) {
         });
         if (backend === "api") {
           const mirrored = await ensureGeminiFileMirror(stored.fileId);
-          parts.push(createPartFromUri(mirrored.uri, mirrored.mimeType));
+          parts.push(createPartFromUri(mirrored.uri, mirrored.mimeType, mediaResolution));
         } else {
           const mirrored = await ensureVertexFileMirror(stored.fileId);
           parts.push({
             fileData: {
               fileUri: mirrored.fileUri,
               mimeType: mirrored.mimeType
-            }
+            },
+            ...mediaResolution ? { mediaResolution: { level: mediaResolution } } : {}
           });
         }
         continue;
@@ -5432,7 +5777,7 @@ function resolveTextContents(input) {
   }
   return contents;
 }
-function toOpenAiInput(contents) {
+function toOpenAiInput(contents, options) {
   const OPENAI_ROLE_FROM_LLM = {
     user: "user",
     assistant: "assistant",
@@ -5440,6 +5785,8 @@ function toOpenAiInput(contents) {
     developer: "developer",
     tool: "assistant"
   };
+  const defaultMediaResolution = options?.defaultMediaResolution;
+  const model = options?.model;
   return contents.map((content) => {
     const parts = [];
     for (const part of content.parts) {
@@ -5454,7 +5801,7 @@ function toOpenAiInput(contents) {
             const imagePart = {
               type: "input_image",
               image_url: dataUrl,
-              detail: "auto"
+              detail: toOpenAiImageDetail(defaultMediaResolution, model)
             };
             setInlineAttachmentFilename(
               imagePart,
@@ -5471,11 +5818,15 @@ function toOpenAiInput(contents) {
           break;
         }
         case "input_image": {
+          const mediaResolution = resolveEffectiveMediaResolution(
+            part.detail,
+            defaultMediaResolution
+          );
           const imagePart = {
             type: "input_image",
             ...part.file_id ? { file_id: part.file_id } : {},
             ...part.image_url ? { image_url: part.image_url } : {},
-            detail: part.detail === "high" || part.detail === "low" ? part.detail : "auto"
+            detail: toOpenAiImageDetail(mediaResolution, model)
           };
           if (part.filename) {
             setInlineAttachmentFilename(imagePart, part.filename);
@@ -5508,9 +5859,11 @@ function toOpenAiInput(contents) {
     };
   });
 }
-function toChatGptInput(contents) {
+function toChatGptInput(contents, options) {
   const instructionsParts = [];
   const input = [];
+  const defaultMediaResolution = options?.defaultMediaResolution;
+  const model = options?.model;
   for (const content of contents) {
     if (content.role === "system" || content.role === "developer") {
       for (const part of content.parts) {
@@ -5546,7 +5899,7 @@ function toChatGptInput(contents) {
             parts.push({
               type: "input_image",
               image_url: dataUrl,
-              detail: "auto"
+              detail: toOpenAiImageDetail(defaultMediaResolution, model)
             });
           } else {
             parts.push({
@@ -5560,14 +5913,19 @@ function toChatGptInput(contents) {
           }
           break;
         }
-        case "input_image":
+        case "input_image": {
+          const mediaResolution = resolveEffectiveMediaResolution(
+            part.detail,
+            defaultMediaResolution
+          );
           parts.push({
             type: "input_image",
             ...part.file_id ? { file_id: part.file_id } : {},
             ...part.image_url ? { image_url: part.image_url } : {},
-            detail: part.detail === "high" || part.detail === "low" ? part.detail : "auto"
+            detail: toOpenAiImageDetail(mediaResolution, model)
           });
           break;
+        }
         case "input_file":
           parts.push({
             type: "input_file",
@@ -5960,6 +6318,9 @@ function isLlmToolOutputContentItem(value) {
         return false;
       }
     }
+    if (value.detail !== void 0 && value.detail !== null && !isLlmMediaResolution(value.detail)) {
+      return false;
+    }
     return value.image_url !== void 0 || value.file_id !== void 0;
   }
   if (itemType === "input_file") {
@@ -5974,17 +6335,30 @@ function isLlmToolOutputContentItem(value) {
   }
   return false;
 }
-function toOpenAiToolOutput(value) {
+function toOpenAiToolOutput(value, options) {
+  const normalizeImageItem = (item) => {
+    if (item.type !== "input_image") {
+      return item;
+    }
+    const mediaResolution = resolveEffectiveMediaResolution(
+      item.detail,
+      options?.defaultMediaResolution
+    );
+    return {
+      ...item,
+      detail: toOpenAiImageDetail(mediaResolution, options?.model)
+    };
+  };
   if (isLlmToolOutputContentItem(value)) {
-    return [value];
+    return [normalizeImageItem(value)];
   }
   if (Array.isArray(value) && value.every((item) => isLlmToolOutputContentItem(item))) {
-    return value;
+    return value.map((item) => normalizeImageItem(item));
   }
   return mergeToolOutput(value);
 }
-function toChatGptToolOutput(value) {
-  const toolOutput = toOpenAiToolOutput(value);
+function toChatGptToolOutput(value, options) {
+  const toolOutput = toOpenAiToolOutput(value, options);
   if (typeof toolOutput === "string") {
     return toolOutput;
   }
@@ -5996,7 +6370,12 @@ function toChatGptToolOutput(value) {
       type: "input_image",
       ...item.file_id ? { file_id: item.file_id } : {},
       ...item.image_url ? { image_url: item.image_url } : {},
-      ...item.detail ? { detail: item.detail } : {}
+      ...item.detail ? {
+        detail: toOpenAiImageDetail(
+          resolveEffectiveMediaResolution(item.detail, options?.defaultMediaResolution),
+          options?.model
+        )
+      } : {}
     };
   });
 }
@@ -6167,9 +6546,6 @@ async function maybeSpillToolOutputItem(item, toolName, options) {
   return item;
 }
 async function maybeSpillToolOutput(value, toolName, options) {
-  if (options?.provider === "chatgpt") {
-    return value;
-  }
   if (typeof value === "string") {
     if (options?.force !== true && Buffer5.byteLength(value, "utf8") <= TOOL_OUTPUT_SPILL_THRESHOLD_BYTES) {
       return value;
@@ -6255,34 +6631,41 @@ async function maybeSpillCombinedToolCallOutputs(callResults, options) {
     })
   );
 }
-function buildGeminiToolOutputMediaPart(item) {
+function buildGeminiToolOutputMediaPart(item, options) {
   if (item.type === "input_image") {
+    const mediaResolution = resolveEffectiveMediaResolution(
+      item.detail,
+      options?.defaultMediaResolution
+    );
+    const geminiPartMediaResolution = toGeminiPartMediaResolution(mediaResolution);
     if (typeof item.file_id === "string" && item.file_id.trim().length > 0) {
-      return {
-        fileData: {
-          fileUri: buildCanonicalGeminiFileUri(item.file_id),
-          mimeType: inferToolOutputMimeTypeFromFilename(item.filename) ?? "application/octet-stream"
-        }
-      };
+      return createPartFromUri(
+        buildCanonicalGeminiFileUri(item.file_id),
+        inferToolOutputMimeTypeFromFilename(item.filename) ?? "application/octet-stream",
+        geminiPartMediaResolution
+      );
     }
     if (typeof item.image_url !== "string" || item.image_url.trim().length === 0) {
       return null;
     }
     const parsed = parseDataUrlPayload(item.image_url);
     if (parsed) {
-      const part = createPartFromBase64(parsed.dataBase64, parsed.mimeType);
+      const part = createPartFromBase64(
+        parsed.dataBase64,
+        parsed.mimeType,
+        geminiPartMediaResolution
+      );
       const displayName = item.filename?.trim();
       if (displayName && part.inlineData) {
         part.inlineData.displayName = displayName;
       }
       return part;
     }
-    return {
-      fileData: {
-        fileUri: item.image_url,
-        mimeType: inferToolOutputMimeTypeFromFilename(item.filename) ?? "application/octet-stream"
-      }
-    };
+    return createPartFromUri(
+      item.image_url,
+      inferToolOutputMimeTypeFromFilename(item.filename) ?? "application/octet-stream",
+      geminiPartMediaResolution
+    );
   }
   if (item.type === "input_file") {
     if (typeof item.file_id === "string" && item.file_id.trim().length > 0) {
@@ -6360,7 +6743,9 @@ function buildGeminiFunctionResponseParts(options) {
   }
   const responseOutput = outputItems.map((item) => toGeminiToolOutputPlaceholder(item));
   const responseParts = outputItems.flatMap((item) => {
-    const mediaPart = buildGeminiToolOutputMediaPart(item);
+    const mediaPart = buildGeminiToolOutputMediaPart(item, {
+      defaultMediaResolution: options.defaultMediaResolution
+    });
     return mediaPart ? [mediaPart] : [];
   });
   const responsePayload = { output: responseOutput };
@@ -7127,6 +7512,7 @@ function startLlmCallLoggerFromContents(options) {
       ...options.request.imageAspectRatio ? { imageAspectRatio: options.request.imageAspectRatio } : {},
       ...options.request.imageSize ? { imageSize: options.request.imageSize } : {},
       ...options.request.thinkingLevel ? { thinkingLevel: options.request.thinkingLevel } : {},
+      ...options.request.mediaResolution ? { mediaResolution: options.request.mediaResolution } : {},
       ...options.request.openAiTextFormat ? { openAiTextFormat: sanitiseLogValue(options.request.openAiTextFormat) } : {},
       ...getCurrentToolCallContext() ? { toolContext: getCurrentToolCallContext() } : {}
     },
@@ -7237,7 +7623,13 @@ async function runTextCall(params) {
   const { result } = await collectFileUploadMetrics(async () => {
     try {
       if (provider === "openai") {
-        const openAiInput = await maybePrepareOpenAiPromptInput(toOpenAiInput(contents));
+        const openAiInput = await maybePrepareOpenAiPromptInput(
+          toOpenAiInput(contents, {
+            defaultMediaResolution: request.mediaResolution,
+            model: request.model
+          }),
+          { model: request.model, provider: "openai" }
+        );
         const openAiTools = toOpenAiTools(request.tools);
         const reasoningEffort = resolveOpenAiReasoningEffort(
           modelForProvider,
@@ -7311,7 +7703,14 @@ async function runTextCall(params) {
           }
         }, modelForProvider);
       } else if (provider === "chatgpt") {
-        const chatGptInput = toChatGptInput(contents);
+        const chatGptInput = toChatGptInput(contents, {
+          defaultMediaResolution: request.mediaResolution,
+          model: request.model
+        });
+        const preparedChatGptInput = await maybePrepareOpenAiPromptInput(chatGptInput.input, {
+          model: request.model,
+          provider: "chatgpt"
+        });
         const reasoningEffort = resolveOpenAiReasoningEffort(request.model, request.thinkingLevel);
         const openAiTools = toOpenAiTools(request.tools);
         const requestPayload = {
@@ -7320,7 +7719,7 @@ async function runTextCall(params) {
           stream: true,
           ...providerInfo.serviceTier ? { service_tier: providerInfo.serviceTier } : {},
           instructions: chatGptInput.instructions ?? "You are a helpful assistant.",
-          input: chatGptInput.input,
+          input: preparedChatGptInput,
           include: ["reasoning.encrypted_content"],
           reasoning: {
             effort: toOpenAiReasoningEffort(reasoningEffort),
@@ -7408,12 +7807,18 @@ async function runTextCall(params) {
         }, modelForProvider);
       } else {
         const geminiContents = await maybePrepareGeminiPromptContents(
-          contents.map(convertLlmContentToGeminiContent)
+          contents.map(
+            (content2) => convertLlmContentToGeminiContent(content2, {
+              defaultMediaResolution: request.mediaResolution
+            })
+          )
         );
         const thinkingConfig = resolveGeminiThinkingConfig(modelForProvider, request.thinkingLevel);
+        const mediaResolution = toGeminiMediaResolution(request.mediaResolution);
         const config = {
           maxOutputTokens: 32e3,
           ...thinkingConfig ? { thinkingConfig } : {},
+          ...mediaResolution ? { mediaResolution } : {},
           ...request.responseMimeType ? { responseMimeType: request.responseMimeType } : {},
           ...request.responseJsonSchema ? { responseJsonSchema: request.responseJsonSchema } : {},
           ...request.responseModalities ? { responseModalities: Array.from(request.responseModalities) } : {},
@@ -8091,7 +8496,10 @@ async function runToolLoop(request) {
         summary: "detailed"
       };
       let previousResponseId;
-      let input = toOpenAiInput(contents);
+      let input = toOpenAiInput(contents, {
+        defaultMediaResolution: request.mediaResolution,
+        model: request.model
+      });
       for (let stepIndex = 0; stepIndex < maxSteps; stepIndex += 1) {
         const turn = stepIndex + 1;
         const stepStartedAtMs = Date.now();
@@ -8118,7 +8526,10 @@ async function runToolLoop(request) {
         let reasoningSummary = "";
         let stepToolCallText;
         let stepToolCallPayload;
-        const preparedInput = await maybePrepareOpenAiPromptInput(input);
+        const preparedInput = await maybePrepareOpenAiPromptInput(input, {
+          model: request.model,
+          provider: "openai"
+        });
         const stepRequestPayload = {
           model: providerInfo.model,
           input: preparedInput,
@@ -8249,7 +8660,10 @@ async function runToolLoop(request) {
           const stepToolCalls = [];
           if (responseToolCalls.length === 0) {
             const steeringInput2 = steeringInternal?.drainPendingContents() ?? [];
-            const steeringItems2 = steeringInput2.length > 0 ? toOpenAiInput(steeringInput2) : [];
+            const steeringItems2 = steeringInput2.length > 0 ? toOpenAiInput(steeringInput2, {
+              defaultMediaResolution: request.mediaResolution,
+              model: request.model
+            }) : [];
             finalText = responseText;
             finalThoughts = reasoningSummary;
             const stepCompletedAtMs2 = Date.now();
@@ -8380,13 +8794,19 @@ async function runToolLoop(request) {
               toolOutputs.push({
                 type: "custom_tool_call_output",
                 call_id: entry.call.call_id,
-                output: toOpenAiToolOutput(outputPayload)
+                output: toOpenAiToolOutput(outputPayload, {
+                  defaultMediaResolution: request.mediaResolution,
+                  model: request.model
+                })
               });
             } else {
               toolOutputs.push({
                 type: "function_call_output",
                 call_id: entry.call.call_id,
-                output: toOpenAiToolOutput(outputPayload)
+                output: toOpenAiToolOutput(outputPayload, {
+                  defaultMediaResolution: request.mediaResolution,
+                  model: request.model
+                })
               });
             }
           }
@@ -8411,7 +8831,10 @@ async function runToolLoop(request) {
             timing
           });
           const steeringInput = steeringInternal?.drainPendingContents() ?? [];
-          const steeringItems = steeringInput.length > 0 ? toOpenAiInput(steeringInput) : [];
+          const steeringItems = steeringInput.length > 0 ? toOpenAiInput(steeringInput, {
+            defaultMediaResolution: request.mediaResolution,
+            model: request.model
+          }) : [];
           stepCallLogger?.complete({
             responseText,
             toolCallText: stepToolCallText,
@@ -8456,7 +8879,10 @@ async function runToolLoop(request) {
       const openAiNativeTools = toOpenAiTools(request.modelTools);
       const openAiTools = openAiNativeTools ? [...openAiNativeTools, ...openAiAgentTools] : [...openAiAgentTools];
       const reasoningEffort = resolveOpenAiReasoningEffort(request.model, request.thinkingLevel);
-      const toolLoopInput = toChatGptInput(contents);
+      const toolLoopInput = toChatGptInput(contents, {
+        defaultMediaResolution: request.mediaResolution,
+        model: request.model
+      });
       const conversationId = `tool-loop-${randomBytes(8).toString("hex")}`;
       const promptCacheKey = conversationId;
       let input = [...toolLoopInput.input];
@@ -8472,6 +8898,10 @@ async function runToolLoop(request) {
         let reasoningSummaryText = "";
         let stepToolCallText;
         let stepToolCallPayload;
+        const preparedInput = await maybePrepareOpenAiPromptInput(input, {
+          model: request.model,
+          provider: "chatgpt"
+        });
         const markFirstModelEvent = () => {
           if (firstModelEventAtMs === void 0) {
             firstModelEventAtMs = Date.now();
@@ -8483,7 +8913,7 @@ async function runToolLoop(request) {
           stream: true,
           ...providerInfo.serviceTier ? { service_tier: providerInfo.serviceTier } : {},
           instructions: toolLoopInput.instructions ?? "You are a helpful assistant.",
-          input,
+          input: preparedInput,
           prompt_cache_key: promptCacheKey,
           include: ["reasoning.encrypted_content"],
           tools: openAiTools,
@@ -8560,7 +8990,10 @@ async function runToolLoop(request) {
           stepToolCallText = serialiseLogArtifactText(stepToolCallPayload);
           if (responseToolCalls.length === 0) {
             const steeringInput2 = steeringInternal?.drainPendingContents() ?? [];
-            const steeringItems2 = steeringInput2.length > 0 ? toChatGptInput(steeringInput2).input : [];
+            const steeringItems2 = steeringInput2.length > 0 ? toChatGptInput(steeringInput2, {
+              defaultMediaResolution: request.mediaResolution,
+              model: request.model
+            }).input : [];
             finalText = responseText;
             finalThoughts = reasoningSummaryText;
             const stepCompletedAtMs2 = Date.now();
@@ -8692,7 +9125,10 @@ async function runToolLoop(request) {
               toolOutputs.push({
                 type: "custom_tool_call_output",
                 call_id: entry.ids.callId,
-                output: toChatGptToolOutput(outputPayload)
+                output: toChatGptToolOutput(outputPayload, {
+                  defaultMediaResolution: request.mediaResolution,
+                  model: request.model
+                })
               });
             } else {
               toolOutputs.push({
@@ -8706,7 +9142,10 @@ async function runToolLoop(request) {
               toolOutputs.push({
                 type: "function_call_output",
                 call_id: entry.ids.callId,
-                output: toChatGptToolOutput(outputPayload)
+                output: toChatGptToolOutput(outputPayload, {
+                  defaultMediaResolution: request.mediaResolution,
+                  model: request.model
+                })
               });
             }
           }
@@ -8730,7 +9169,10 @@ async function runToolLoop(request) {
             timing
           });
           const steeringInput = steeringInternal?.drainPendingContents() ?? [];
-          const steeringItems = steeringInput.length > 0 ? toChatGptInput(steeringInput).input : [];
+          const steeringItems = steeringInput.length > 0 ? toChatGptInput(steeringInput, {
+            defaultMediaResolution: request.mediaResolution,
+            model: request.model
+          }).input : [];
           stepCallLogger?.complete({
             responseText,
             toolCallText: stepToolCallText,
@@ -9061,7 +9503,11 @@ async function runToolLoop(request) {
     const geminiFunctionTools = buildGeminiFunctionDeclarations(request.tools);
     const geminiNativeTools = toGeminiTools(request.modelTools);
     const geminiTools = geminiNativeTools ? geminiNativeTools.concat(geminiFunctionTools) : geminiFunctionTools;
-    const geminiContents = contents.map(convertLlmContentToGeminiContent);
+    const geminiContents = contents.map(
+      (content) => convertLlmContentToGeminiContent(content, {
+        defaultMediaResolution: request.mediaResolution
+      })
+    );
     for (let stepIndex = 0; stepIndex < maxSteps; stepIndex += 1) {
       const turn = stepIndex + 1;
       const stepStartedAtMs = Date.now();
@@ -9079,6 +9525,7 @@ async function runToolLoop(request) {
         }
       };
       const thinkingConfig = resolveGeminiThinkingConfig(request.model, request.thinkingLevel);
+      const mediaResolution = toGeminiMediaResolution(request.mediaResolution);
       const config = {
         maxOutputTokens: 32e3,
         tools: geminiTools,
@@ -9087,7 +9534,8 @@ async function runToolLoop(request) {
             mode: FunctionCallingConfigMode.VALIDATED
           }
         },
-        ...thinkingConfig ? { thinkingConfig } : {}
+        ...thinkingConfig ? { thinkingConfig } : {},
+        ...mediaResolution ? { mediaResolution } : {}
       };
       const onEvent = request.onEvent;
       const preparedGeminiContents = await maybePrepareGeminiPromptContents(geminiContents);
@@ -9243,7 +9691,13 @@ async function runToolLoop(request) {
           } else if (response.responseText.length > 0) {
             geminiContents.push({ role: "model", parts: [{ text: response.responseText }] });
           }
-          geminiContents.push(...steeringInput2.map(convertLlmContentToGeminiContent));
+          geminiContents.push(
+            ...steeringInput2.map(
+              (content) => convertLlmContentToGeminiContent(content, {
+                defaultMediaResolution: request.mediaResolution
+              })
+            )
+          );
           continue;
         }
         const toolCalls = [];
@@ -9335,7 +9789,8 @@ async function runToolLoop(request) {
             ...buildGeminiFunctionResponseParts({
               toolName: entry.toolName,
               callId: entry.call.id,
-              outputPayload
+              outputPayload,
+              defaultMediaResolution: request.mediaResolution
             })
           );
         }
@@ -9380,7 +9835,13 @@ async function runToolLoop(request) {
         geminiContents.push({ role: "user", parts: responseParts });
         const steeringInput = steeringInternal?.drainPendingContents() ?? [];
         if (steeringInput.length > 0) {
-          geminiContents.push(...steeringInput.map(convertLlmContentToGeminiContent));
+          geminiContents.push(
+            ...steeringInput.map(
+              (content) => convertLlmContentToGeminiContent(content, {
+                defaultMediaResolution: request.mediaResolution
+              })
+            )
+          );
         }
       } catch (error) {
         stepCallLogger?.fail(error, {
@@ -9636,7 +10097,7 @@ async function generateImages(request) {
                     }
                     return image;
                   })(),
-                  model: "gpt-5.2"
+                  model: "gpt-5.4-mini"
                 })
               )
             );
@@ -9942,7 +10403,6 @@ function resolveSubagentToolConfig(selection, currentDepth) {
     maxWaitTimeoutMs,
     promptPattern,
     ...instructions ? { instructions } : {},
-    ...config.model ? { model: config.model } : {},
     ...maxSteps ? { maxSteps } : {},
     inheritTools: config.inheritTools !== false,
     inheritFilesystemTool: config.inheritFilesystemTool !== false
@@ -9994,7 +10454,6 @@ function createSubagentToolController(options) {
             `Subagent depth limit reached (${options.config.maxDepth}). Cannot spawn at depth ${childDepth}.`
           );
         }
-        const model = options.config.model ?? options.parentModel;
         const id = `agent_${randomBytes2(6).toString("hex")}`;
         const now = Date.now();
         const { roleName, roleInstructions } = resolveAgentType(input.agent_type);
@@ -10014,7 +10473,7 @@ function createSubagentToolController(options) {
         const agent = {
           id,
           depth: childDepth,
-          model,
+          model: options.parentModel,
           ...nickname ? { nickname } : {},
           agentRole: roleName,
           status: "idle",
@@ -11769,7 +12228,8 @@ async function viewImageCodex(input, options) {
   return [
     {
       type: "input_image",
-      image_url: `data:${mimeType};base64,${bytes.toString("base64")}`
+      image_url: `data:${mimeType};base64,${bytes.toString("base64")}`,
+      ...options.mediaResolution ? { detail: options.mediaResolution } : {}
     }
   ];
 }
@@ -12449,7 +12909,11 @@ async function runAgentLoopInternal(request, context) {
   const toolLoopRequestWithSteering = toolLoopRequest.steering === steeringChannel ? toolLoopRequest : { ...toolLoopRequest, steering: steeringChannel };
   const filesystemSelection = filesystemTool ?? filesystem_tool;
   const subagentSelection = subagentTool ?? subagent_tool ?? subagents;
-  const filesystemTools = resolveFilesystemTools(request.model, filesystemSelection);
+  const filesystemTools = resolveFilesystemTools(
+    request.model,
+    filesystemSelection,
+    request.mediaResolution
+  );
   const resolvedSubagentConfig = resolveSubagentToolConfig(subagentSelection, context.depth);
   const subagentController = createSubagentController({
     runId,
@@ -12601,24 +13065,47 @@ async function runAgentLoopInternal(request, context) {
     await subagentController?.closeAll();
   }
 }
-function resolveFilesystemTools(model, selection) {
+function resolveFilesystemTools(model, selection, defaultMediaResolution) {
+  const withDefaultMediaResolution = (options) => {
+    if (defaultMediaResolution === void 0) {
+      return options;
+    }
+    return {
+      mediaResolution: defaultMediaResolution,
+      ...options ?? {}
+    };
+  };
   if (selection === void 0 || selection === false) {
     return {};
   }
   if (selection === true) {
-    return createFilesystemToolSetForModel(model, "auto");
+    return createFilesystemToolSetForModel(model, withDefaultMediaResolution(void 0) ?? {});
   }
   if (typeof selection === "string") {
-    return createFilesystemToolSetForModel(model, selection);
+    return createFilesystemToolSetForModel(model, selection, withDefaultMediaResolution(void 0));
   }
   if (selection.enabled === false) {
     return {};
   }
   if (selection.options && selection.profile !== void 0) {
-    return createFilesystemToolSetForModel(model, selection.profile, selection.options);
+    return createFilesystemToolSetForModel(
+      model,
+      selection.profile,
+      withDefaultMediaResolution(selection.options)
+    );
   }
   if (selection.options) {
-    return createFilesystemToolSetForModel(model, selection.options);
+    return createFilesystemToolSetForModel(
+      model,
+      withDefaultMediaResolution(selection.options) ?? {}
+    );
+  }
+  if (defaultMediaResolution !== void 0) {
+    return createFilesystemToolSetForModel(
+      model,
+      selection.profile ?? "auto",
+      withDefaultMediaResolution(void 0)
+    );
   }
   return createFilesystemToolSetForModel(model, selection.profile ?? "auto");
 }
@@ -12641,7 +13128,7 @@ function createSubagentController(params) {
   return createSubagentToolController({
     config: params.resolvedSubagentConfig,
     parentDepth: params.depth,
-    parentModel: params.resolvedSubagentConfig.model ?? params.model,
+    parentModel: params.model,
     forkContextMessages: normalizeForkContextMessages(params.toolLoopRequest.input),
     onBackgroundMessage: (message) => {
       params.steering?.append({ role: "user", content: message });
@@ -12661,6 +13148,7 @@ function createSubagentController(params) {
           modelTools: params.toolLoopRequest.modelTools,
           maxSteps: subagentRequest.maxSteps,
           thinkingLevel: params.toolLoopRequest.thinkingLevel,
+          mediaResolution: params.toolLoopRequest.mediaResolution,
           signal: subagentRequest.signal
         },
         {