@ljoukov/llm 6.0.0 → 7.0.0

package/dist/index.js

@@ -3240,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");
@@ -3261,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(),
@@ -3342,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,
@@ -3389,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) {
@@ -3419,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",
@@ -3468,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),
@@ -3500,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 retrieveOpenAiFile(fileId) {
+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 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;
 }
@@ -3696,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, "");
@@ -3726,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 {
@@ -3789,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);
@@ -3805,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,
@@ -3840,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,
@@ -3865,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";
@@ -3906,7 +4084,7 @@ async function ensureVertexFileMirror(fileId) {
     }
   }
   const mirror = {
-    openAiFileId: fileId,
+    canonicalFileId: fileId,
     bucket: bucketName,
     objectName,
     fileUri: `gs://${bucketName}/${objectName}`,
@@ -3937,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,
@@ -3946,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,
@@ -3966,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);
@@ -4002,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,
@@ -4391,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}`;
 }
@@ -4401,6 +4607,9 @@ 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";
 }
@@ -4888,7 +5097,21 @@ 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;
@@ -4901,16 +5124,27 @@ async function prepareOpenAiPromptContentItem(item, options) {
         guessInlineDataFilename(parsed.mimeType)
       )
     });
+    const signedUrl = await getCanonicalFileSignedUrl({ fileId: uploaded.fileId });
     return {
       type: "input_image",
+      image_url: signedUrl,
       detail: toOpenAiImageDetail(
         isLlmMediaResolution(item.detail) ? item.detail : void 0,
         options?.model
-      ),
-      file_id: uploaded.fileId
+      )
+    };
+  }
+  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) {
@@ -4924,7 +5158,11 @@ async function prepareOpenAiPromptContentItem(item, options) {
       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);
@@ -4939,7 +5177,11 @@ async function prepareOpenAiPromptContentItem(item, options) {
         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;
 }
@@ -4969,11 +5211,40 @@ async function prepareOpenAiPromptInput(input, options) {
   };
   return await Promise.all(input.map((item) => prepareItem(item)));
 }
+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) {
-  if (estimateOpenAiInlinePromptBytes(input) <= INLINE_ATTACHMENT_PROMPT_THRESHOLD_BYTES) {
+  const offloadInlineData = estimateOpenAiInlinePromptBytes(input) > INLINE_ATTACHMENT_PROMPT_THRESHOLD_BYTES;
+  if (!offloadInlineData && !hasCanonicalOpenAiFileReferences(input)) {
     return Array.from(input);
   }
-  return await prepareOpenAiPromptInput(input, options);
+  return await prepareOpenAiPromptInput(input, {
+    ...options,
+    offloadInlineData
+  });
 }
 function estimateGeminiInlinePromptBytes(contents) {
   let total = 0;
@@ -6275,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;
@@ -7360,7 +7628,7 @@ async function runTextCall(params) {
             defaultMediaResolution: request.mediaResolution,
             model: request.model
           }),
-          { model: request.model }
+          { model: request.model, provider: "openai" }
         );
         const openAiTools = toOpenAiTools(request.tools);
         const reasoningEffort = resolveOpenAiReasoningEffort(
@@ -7439,6 +7707,10 @@ async function runTextCall(params) {
           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 = {
@@ -7447,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),
@@ -8255,7 +8527,8 @@ async function runToolLoop(request) {
         let stepToolCallText;
         let stepToolCallPayload;
         const preparedInput = await maybePrepareOpenAiPromptInput(input, {
-          model: request.model
+          model: request.model,
+          provider: "openai"
         });
         const stepRequestPayload = {
           model: providerInfo.model,
@@ -8625,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();
@@ -8636,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,