@dexto/core 1.1.10 → 1.1.11

package/dist/context/utils.js

@@ -2,9 +2,290 @@ import { logger } from "../logger/index.js";
 import { validateModelFileSupport } from "../llm/registry.js";
 import { ContextError } from "./errors.js";
 import { safeStringify } from "../utils/safe-stringify.js";
+import { getFileMediaKind, getResourceKind } from "./media-helpers.js";
 const DEFAULT_OVERHEAD_PER_MESSAGE = 4;
 const MIN_BASE64_HEURISTIC_LENGTH = 512;
 const MAX_TOOL_TEXT_CHARS = 8e3;
+const MIN_TOOL_INLINE_MEDIA_BYTES = 1024;
+function slugifyForFilename(value, maxLength = 48) {
+  if (!value) return null;
+  const slug = value.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+  if (!slug) return null;
+  return slug.length > maxLength ? slug.slice(0, maxLength) : slug;
+}
+function inferExtensionFromMime(mimeType, fallback) {
+  if (!mimeType) return fallback;
+  const subtype = mimeType.split("/")[1]?.split(";")[0]?.split("+")[0];
+  if (!subtype) return fallback;
+  const clean = subtype.replace(/[^a-z0-9]/gi, "").toLowerCase();
+  return clean || fallback;
+}
+function sanitizeExistingFilename(filename) {
+  return filename.replace(/[^a-zA-Z0-9._-]+/g, "-");
+}
+function generateUniqueSuffix() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+function clonePart(part) {
+  if (part.type === "text") {
+    return { type: "text", text: part.text };
+  }
+  if (part.type === "image") {
+    const cloned2 = {
+      type: "image",
+      image: part.image
+    };
+    if (part.mimeType) {
+      cloned2.mimeType = part.mimeType;
+    }
+    return cloned2;
+  }
+  const cloned = {
+    type: "file",
+    data: part.data,
+    mimeType: part.mimeType
+  };
+  if (part.filename) {
+    cloned.filename = part.filename;
+  }
+  return cloned;
+}
+function coerceContentToParts(content) {
+  if (Array.isArray(content)) {
+    const normalized = [];
+    for (const item of content) {
+      if (item == null) continue;
+      if (typeof item === "string") {
+        normalized.push({ type: "text", text: item });
+        continue;
+      }
+      if (typeof item === "object" && "type" in item) {
+        const type = item.type;
+        if (type === "text") {
+          const textPart = item;
+          normalized.push({ type: "text", text: textPart.text });
+          continue;
+        }
+        if (type === "image") {
+          const imagePart = item;
+          const cloned = {
+            type: "image",
+            image: imagePart.image
+          };
+          if (imagePart.mimeType) {
+            cloned.mimeType = imagePart.mimeType;
+          }
+          normalized.push(cloned);
+          continue;
+        }
+        if (type === "file") {
+          const filePart = item;
+          const cloned = {
+            type: "file",
+            data: filePart.data,
+            mimeType: filePart.mimeType ?? "application/octet-stream"
+          };
+          if (filePart.filename) {
+            cloned.filename = filePart.filename;
+          }
+          normalized.push(cloned);
+          continue;
+        }
+      }
+    }
+    return normalized;
+  }
+  if (typeof content === "string") {
+    if (content.length === 0) {
+      return [];
+    }
+    return [{ type: "text", text: content }];
+  }
+  if (content == null) {
+    return [];
+  }
+  return [{ type: "text", text: safeStringify(content) }];
+}
+function detectInlineMedia(part, index) {
+  if (part.type === "text") {
+    return null;
+  }
+  if (part.type === "image") {
+    const value = part.image;
+    const mimeType2 = part.mimeType ?? "image/jpeg";
+    if (typeof value === "string") {
+      if (value.startsWith("@blob:")) return null;
+      if (value.startsWith("http://") || value.startsWith("https://") || value.startsWith("blob:")) {
+        return null;
+      }
+      if (isLikelyBase64String(value, 128)) {
+        return {
+          index,
+          kind: "image",
+          mimeType: mimeType2,
+          approxBytes: base64LengthToBytes(value.length),
+          data: value
+        };
+      }
+    } else if (value instanceof Buffer) {
+      return {
+        index,
+        kind: "image",
+        mimeType: mimeType2,
+        approxBytes: value.length,
+        data: value
+      };
+    } else if (value instanceof Uint8Array) {
+      const buffer = Buffer.from(value);
+      return {
+        index,
+        kind: "image",
+        mimeType: mimeType2,
+        approxBytes: buffer.length,
+        data: buffer
+      };
+    } else if (value instanceof ArrayBuffer) {
+      const buffer = Buffer.from(new Uint8Array(value));
+      return {
+        index,
+        kind: "image",
+        mimeType: mimeType2,
+        approxBytes: buffer.length,
+        data: buffer
+      };
+    }
+    return null;
+  }
+  const data = part.data;
+  const mimeType = part.mimeType ?? "application/octet-stream";
+  const filename = part.filename;
+  if (typeof data === "string") {
+    if (data.startsWith("@blob:")) return null;
+    if (data.startsWith("http://") || data.startsWith("https://") || data.startsWith("blob:")) {
+      return null;
+    }
+    if (data.startsWith("data:")) {
+      const parsed = parseDataUri(data);
+      if (parsed) {
+        return {
+          index,
+          kind: "file",
+          mimeType: parsed.mediaType,
+          approxBytes: base64LengthToBytes(parsed.base64.length),
+          data: parsed.base64,
+          filename
+        };
+      }
+    }
+    if (isLikelyBase64String(data, 128)) {
+      return {
+        index,
+        kind: "file",
+        mimeType,
+        approxBytes: base64LengthToBytes(data.length),
+        data,
+        filename
+      };
+    }
+  } else if (data instanceof Buffer) {
+    return {
+      index,
+      kind: "file",
+      mimeType,
+      approxBytes: data.length,
+      data,
+      filename
+    };
+  } else if (data instanceof Uint8Array) {
+    const buffer = Buffer.from(data);
+    return {
+      index,
+      kind: "file",
+      mimeType,
+      approxBytes: buffer.length,
+      data: buffer,
+      filename
+    };
+  } else if (data instanceof ArrayBuffer) {
+    const buffer = Buffer.from(new Uint8Array(data));
+    return {
+      index,
+      kind: "file",
+      mimeType,
+      approxBytes: buffer.length,
+      data: buffer,
+      filename
+    };
+  }
+  return null;
+}
+function buildToolBlobName(kind, mimeType, options, preferredName) {
+  if (preferredName) {
+    return sanitizeExistingFilename(preferredName);
+  }
+  const toolSegment = slugifyForFilename(options?.toolName ?? "", 40);
+  const callSegment = slugifyForFilename(options?.toolCallId ?? "", 16);
+  const parts = ["tool"];
+  if (toolSegment) parts.push(toolSegment);
+  if (callSegment) parts.push(callSegment);
+  parts.push(kind);
+  const ext = inferExtensionFromMime(
+    mimeType,
+    kind === "image" ? "jpg" : kind === "file" ? "bin" : "bin"
+  );
+  const unique = generateUniqueSuffix();
+  return `${parts.join("-")}-${unique}.${ext}`;
+}
+async function resolveBlobReferenceToParts(resourceUri, resourceManager) {
+  try {
+    const result = await resourceManager.read(resourceUri);
+    const parts = [];
+    for (const item of result.contents ?? []) {
+      if (!item || typeof item !== "object") {
+        continue;
+      }
+      if (typeof item.text === "string") {
+        parts.push({ type: "text", text: item.text });
+        continue;
+      }
+      const base64Data = typeof item.blob === "string" ? item.blob : typeof item.data === "string" ? item.data : void 0;
+      const mimeType = typeof item.mimeType === "string" ? item.mimeType : void 0;
+      if (!base64Data || !mimeType) {
+        continue;
+      }
+      const resolvedMime = mimeType ?? "application/octet-stream";
+      if (resolvedMime.startsWith("image/")) {
+        const dataUri = `data:${resolvedMime};base64,${base64Data}`;
+        const imagePart = {
+          type: "image",
+          image: dataUri,
+          mimeType: resolvedMime
+        };
+        parts.push(imagePart);
+        continue;
+      }
+      const filePart = {
+        type: "file",
+        data: resolvedMime.startsWith("audio/") ? `data:${resolvedMime};base64,${base64Data}` : base64Data,
+        mimeType: resolvedMime
+      };
+      if (typeof item.filename === "string" && item.filename.length > 0) {
+        filePart.filename = item.filename;
+      } else if (typeof result._meta?.originalName === "string") {
+        filePart.filename = result._meta.originalName;
+      }
+      parts.push(filePart);
+    }
+    if (parts.length === 0) {
+      const fallbackName = typeof result._meta?.originalName === "string" && result._meta.originalName || resourceUri;
+      parts.push({ type: "text", text: `[Attachment: ${fallbackName}]` });
+    }
+    return parts;
+  } catch (error) {
+    logger.warn(`Failed to resolve blob reference ${resourceUri}: ${String(error)}`);
+    return [{ type: "text", text: `[Attachment unavailable: ${resourceUri}]` }];
+  }
+}
 function countMessagesTokens(history, tokenizer, overheadPerMessage = DEFAULT_OVERHEAD_PER_MESSAGE) {
   let total = 0;
   logger.debug(`Counting tokens for ${history.length} messages`);
@@ -99,6 +380,136 @@ function getFileData(filePart) {
   logger.warn(`Unexpected file data type in getFileData: ${typeof data}`);
   return "";
 }
+async function getImageDataWithBlobSupport(imagePart, resourceManager) {
+  const { image } = imagePart;
+  if (typeof image === "string" && image.startsWith("@blob:")) {
+    try {
+      const uri = image.substring(1);
+      const resourceUri = uri.startsWith("blob:") ? uri : `blob:${uri}`;
+      const result = await resourceManager.read(resourceUri);
+      if (result.contents[0]?.blob && typeof result.contents[0].blob === "string") {
+        return result.contents[0].blob;
+      }
+      logger.warn(`Blob reference ${image} did not contain blob data`);
+    } catch (error) {
+      logger.warn(`Failed to resolve blob reference ${image}: ${String(error)}`);
+    }
+  }
+  return getImageData(imagePart);
+}
+async function getFileDataWithBlobSupport(filePart, resourceManager) {
+  const { data } = filePart;
+  if (typeof data === "string" && data.startsWith("@blob:")) {
+    try {
+      const uri = data.substring(1);
+      const resourceUri = uri.startsWith("blob:") ? uri : `blob:${uri}`;
+      const result = await resourceManager.read(resourceUri);
+      if (result.contents[0]?.blob && typeof result.contents[0].blob === "string") {
+        return result.contents[0].blob;
+      }
+      logger.warn(`Blob reference ${data} did not contain blob data`);
+    } catch (error) {
+      logger.warn(`Failed to resolve blob reference ${data}: ${String(error)}`);
+    }
+  }
+  return getFileData(filePart);
+}
+async function expandBlobReferences(content, resourceManager) {
+  if (typeof content === "string") {
+    const blobRefPattern = /@blob:[a-f0-9]+/g;
+    const matches = [...content.matchAll(blobRefPattern)];
+    if (matches.length === 0) {
+      return content;
+    }
+    const resolvedCache = /* @__PURE__ */ new Map();
+    const parts = [];
+    let lastIndex = 0;
+    for (const match of matches) {
+      const matchIndex = match.index ?? 0;
+      const token = match[0];
+      if (matchIndex > lastIndex) {
+        const segment = content.slice(lastIndex, matchIndex);
+        if (segment.length > 0) {
+          parts.push({ type: "text", text: segment });
+        }
+      }
+      const uri = token.substring(1);
+      const resourceUri = uri.startsWith("blob:") ? uri : `blob:${uri}`;
+      let resolvedParts = resolvedCache.get(resourceUri);
+      if (!resolvedParts) {
+        resolvedParts = await resolveBlobReferenceToParts(resourceUri, resourceManager);
+        resolvedCache.set(resourceUri, resolvedParts);
+      }
+      if (resolvedParts.length > 0) {
+        parts.push(...resolvedParts.map((part) => ({ ...part })));
+      } else {
+        parts.push({ type: "text", text: token });
+      }
+      lastIndex = matchIndex + token.length;
+    }
+    if (lastIndex < content.length) {
+      const trailing = content.slice(lastIndex);
+      if (trailing.length > 0) {
+        parts.push({ type: "text", text: trailing });
+      }
+    }
+    const normalized = parts.filter((part) => part.type !== "text" || part.text.length > 0);
+    if (normalized.length === 1 && normalized[0]?.type === "text") {
+      return normalized[0].text;
+    }
+    return normalized;
+  }
+  if (Array.isArray(content)) {
+    const expandedParts = [];
+    for (const part of content) {
+      if (part.type === "image" && typeof part.image === "string" && part.image.startsWith("@blob:")) {
+        const uri = part.image.substring(1);
+        const resourceUri = uri.startsWith("blob:") ? uri : `blob:${uri}`;
+        const resolved = await resolveBlobReferenceToParts(resourceUri, resourceManager);
+        if (resolved.length > 0) {
+          expandedParts.push(...resolved.map((part2) => ({ ...part2 })));
+        } else {
+          expandedParts.push(part);
+        }
+        continue;
+      }
+      if (part.type === "file" && typeof part.data === "string" && part.data.startsWith("@blob:")) {
+        const uri = part.data.substring(1);
+        const resourceUri = uri.startsWith("blob:") ? uri : `blob:${uri}`;
+        const resolved = await resolveBlobReferenceToParts(resourceUri, resourceManager);
+        if (resolved.length > 0) {
+          expandedParts.push(...resolved.map((part2) => ({ ...part2 })));
+        } else {
+          try {
+            const resolvedData = await getFileDataWithBlobSupport(
+              part,
+              resourceManager
+            );
+            expandedParts.push({ ...part, data: resolvedData });
+          } catch (error) {
+            logger.warn(`Failed to resolve file blob reference: ${String(error)}`);
+            expandedParts.push(part);
+          }
+        }
+        continue;
+      }
+      if (part.type === "text" && part.text.includes("@blob:")) {
+        const expanded = await expandBlobReferences(part.text, resourceManager);
+        if (typeof expanded === "string") {
+          expandedParts.push({ ...part, text: expanded });
+        } else if (Array.isArray(expanded)) {
+          expandedParts.push(...expanded.map((part2) => ({ ...part2 })));
+        } else {
+          expandedParts.push(part);
+        }
+        continue;
+      }
+      expandedParts.push(part);
+    }
+    return expandedParts;
+  }
+  return content;
+}
 function filterMessagesByLLMCapabilities(messages, config) {
   try {
     return messages.map((message) => {
@@ -175,24 +586,142 @@ function sanitizeDeepObject(obj) {
   }
   return obj;
 }
-function sanitizeToolResultToContent(result) {
+async function normalizeToolResult(result) {
+  const content = await sanitizeToolResultToContentWithBlobs(result);
+  const parts = coerceContentToParts(content);
+  const inlineMedia = [];
+  parts.forEach((part, index) => {
+    const hint = detectInlineMedia(part, index);
+    if (hint) {
+      inlineMedia.push(hint);
+    }
+  });
+  return {
+    parts,
+    inlineMedia
+  };
+}
+function shouldPersistInlineMedia(hint) {
+  const kind = getFileMediaKind(hint.mimeType);
+  if (kind === "audio" || kind === "video") {
+    return true;
+  }
+  return hint.approxBytes >= MIN_TOOL_INLINE_MEDIA_BYTES;
+}
+async function persistToolMedia(normalized, options) {
+  const parts = normalized.parts.map((part) => clonePart(part));
+  const blobStore = options.blobStore;
+  const namingOptions = options.toolName || options.toolCallId ? {
+    ...options.toolName ? { toolName: options.toolName } : {},
+    ...options.toolCallId ? { toolCallId: options.toolCallId } : {}
+  } : void 0;
+  if (blobStore) {
+    for (const hint of normalized.inlineMedia) {
+      if (!shouldPersistInlineMedia(hint)) {
+        continue;
+      }
+      try {
+        const originalName = hint.filename ?? buildToolBlobName(
+          hint.kind === "image" ? "image" : "file",
+          hint.mimeType,
+          namingOptions
+        );
+        const blobRef = await blobStore.store(hint.data, {
+          mimeType: hint.mimeType,
+          originalName,
+          source: "tool"
+        });
+        const resourceUri = blobRef.uri;
+        if (hint.kind === "image") {
+          parts[hint.index] = createBlobImagePart(resourceUri, blobRef.metadata.mimeType);
+        } else {
+          const resolvedMimeType = blobRef.metadata.mimeType || hint.mimeType;
+          const filename = blobRef.metadata.originalName ?? hint.filename;
+          parts[hint.index] = createBlobFilePart(resourceUri, resolvedMimeType, filename);
+        }
+      } catch (error) {
+        logger.warn(
+          `Failed to persist tool media: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+  }
+  const resources = extractResourceDescriptors(parts);
+  return {
+    parts,
+    ...resources ? { resources } : {}
+  };
+}
+async function sanitizeToolResultToContentWithBlobs(result, blobStore, namingOptions) {
   try {
     if (typeof result === "string") {
       const dataUri = parseDataUri(result);
       if (dataUri) {
         const mediaType = dataUri.mediaType;
         logger.debug(
-          `sanitizeToolResultToContent: detected data URI (${mediaType}), converting to media part`
+          `sanitizeToolResultToContentWithBlobs: detected data URI (${mediaType})`
         );
+        const approxSize = Math.floor(dataUri.base64.length * 3 / 4);
+        const shouldStoreAsBlob = blobStore && approxSize > 1024;
+        if (shouldStoreAsBlob) {
+          try {
+            logger.debug(
+              `Storing data URI as blob (${approxSize} bytes, ${mediaType})`
+            );
+            const blobRef = await blobStore.store(result, {
+              mimeType: mediaType,
+              source: "tool",
+              originalName: buildToolBlobName("output", mediaType, namingOptions)
+            });
+            logger.debug(`Stored blob: ${blobRef.uri} (${approxSize} bytes)`);
+            if (mediaType.startsWith("image/")) {
+              return [createBlobImagePart(blobRef.uri, mediaType)];
+            }
+            return [createBlobFilePart(blobRef.uri, mediaType, void 0)];
+          } catch (error) {
+            logger.warn(
+              `Failed to store blob, falling back to inline: ${String(error)}`
+            );
+          }
+        }
         if (mediaType.startsWith("image/")) {
           return [{ type: "image", image: dataUri.base64, mimeType: mediaType }];
         }
-        return [{ type: "file", data: dataUri.base64, mimeType: mediaType }];
+        return [
+          {
+            type: "file",
+            data: dataUri.base64,
+            mimeType: mediaType
+          }
+        ];
       }
       if (isLikelyBase64String(result)) {
-        logger.debug(
-          "sanitizeToolResultToContent: detected base64-like string, converting to file part"
-        );
+        logger.debug("sanitizeToolResultToContentWithBlobs: detected base64-like string");
+        const approxSize = Math.floor(result.length * 3 / 4);
+        const shouldStoreAsBlob = blobStore && approxSize > 1024;
+        if (shouldStoreAsBlob) {
+          try {
+            const blobRef = await blobStore.store(result, {
+              mimeType: "application/octet-stream",
+              source: "tool",
+              originalName: buildToolBlobName("output", void 0, namingOptions)
+            });
+            logger.debug(
+              `Stored tool result as blob: ${blobRef.uri} (${approxSize} bytes)`
+            );
+            return [
+              createBlobFilePart(
+                blobRef.uri,
+                "application/octet-stream",
+                "tool-output.bin"
+              )
+            ];
+          } catch (error) {
+            logger.warn(
+              `Failed to store blob, falling back to inline: ${String(error)}`
+            );
+          }
+        }
         return [
           {
             type: "file",
@@ -206,7 +735,7 @@ function sanitizeToolResultToContent(result) {
         const head = result.slice(0, 4e3);
         const tail = result.slice(-1e3);
         logger.debug(
-          `sanitizeToolResultToContent: truncating long text tool output (len=${result.length})`
+          `sanitizeToolResultToContentWithBlobs: truncating long text tool output (len=${result.length})`
         );
         return `${head}
 ... [${result.length - 5e3} chars omitted] ...
@@ -218,84 +747,219 @@ ${tail}`;
       const parts = [];
       for (const item of result) {
         if (item == null) continue;
-        if (typeof item === "string") {
-          const dataUri = parseDataUri(item);
-          if (dataUri) {
-            const mt = dataUri.mediaType;
-            if (mt.startsWith("image/"))
-              parts.push({ type: "image", image: dataUri.base64, mimeType: mt });
-            else parts.push({ type: "file", data: dataUri.base64, mimeType: mt });
-            continue;
-          }
-          if (isLikelyBase64String(item)) {
-            parts.push({
-              type: "file",
-              data: item,
-              mimeType: "application/octet-stream",
-              filename: "tool-output.bin"
-            });
-            continue;
-          }
-          parts.push({ type: "text", text: item });
-          continue;
-        }
-        if (typeof item === "object") {
-          const obj = item;
-          if (obj.type === "text" && typeof obj.text === "string") {
-            parts.push({ type: "text", text: obj.text });
-            continue;
-          }
-          if (obj.type === "image" && obj.image !== void 0 || "image" in obj) {
-            parts.push({
-              type: "image",
-              image: getImageData({ image: obj.image }),
-              mimeType: obj.mimeType || "image/jpeg"
-            });
-            continue;
-          }
-          if (obj.type === "file" && obj.data !== void 0) {
-            parts.push({
-              type: "file",
-              data: getFileData({ data: obj.data }),
-              mimeType: obj.mimeType || "application/octet-stream",
-              filename: obj.filename
-            });
-            continue;
-          }
-          if ("data" in obj && (typeof obj.mimeType === "string" || obj.filename)) {
-            parts.push({
-              type: "file",
-              data: getFileData({ data: obj.data }),
-              mimeType: obj.mimeType || "application/octet-stream",
-              filename: obj.filename
-            });
-            continue;
-          }
-          const cleaned = sanitizeDeepObject(obj);
-          parts.push({ type: "text", text: safeStringify(cleaned) });
-          continue;
+        const processedItem = await sanitizeToolResultToContentWithBlobs(
+          item,
+          blobStore,
+          namingOptions
+        );
+        if (typeof processedItem === "string") {
+          parts.push({ type: "text", text: processedItem });
+        } else if (Array.isArray(processedItem)) {
+          parts.push(...processedItem);
         }
-        parts.push({ type: "text", text: String(item) });
       }
       return parts;
     }
     if (result && typeof result === "object") {
       const anyObj = result;
+      if ("content" in anyObj && Array.isArray(anyObj.content)) {
+        logger.debug(
+          `Processing MCP tool result with ${anyObj.content.length} content items`
+        );
+        const processedContent = [];
+        for (const item of anyObj.content) {
+          if (item && typeof item === "object") {
+            if (item.type === "resource" && item.resource) {
+              const resource = item.resource;
+              if (resource.text && resource.mimeType) {
+                const fileData = resource.text;
+                const mimeType = resource.mimeType;
+                const approxSize = typeof fileData === "string" ? Math.floor(fileData.length * 3 / 4) : 0;
+                const shouldStoreAsBlob = blobStore && approxSize > 1024;
+                if (shouldStoreAsBlob) {
+                  try {
+                    logger.debug(
+                      `Storing MCP resource as blob (${approxSize} bytes, ${mimeType})`
+                    );
+                    const blobRef = await blobStore.store(fileData, {
+                      mimeType,
+                      source: "tool",
+                      originalName: buildToolBlobName(
+                        mimeType.startsWith("image/") ? "image" : "file",
+                        mimeType,
+                        namingOptions,
+                        resource.title
+                      )
+                    });
+                    logger.debug(
+                      `Stored MCP resource blob: ${blobRef.uri} (${approxSize} bytes)`
+                    );
+                    if (mimeType.startsWith("image/")) {
+                      processedContent.push(
+                        createBlobImagePart(blobRef.uri, mimeType)
+                      );
+                    } else {
+                      processedContent.push(
+                        createBlobFilePart(
+                          blobRef.uri,
+                          mimeType,
+                          resource.title
+                        )
+                      );
+                    }
+                    continue;
+                  } catch (error) {
+                    logger.warn(
+                      `Failed to store MCP resource blob, falling back to inline: ${String(error)}`
+                    );
+                  }
+                }
+                if (mimeType.startsWith("image/")) {
+                  processedContent.push({
+                    type: "image",
+                    image: fileData,
+                    mimeType
+                  });
+                } else if (mimeType.startsWith("video/")) {
+                  processedContent.push({
+                    type: "file",
+                    data: fileData,
+                    mimeType,
+                    filename: resource.title
+                  });
+                } else {
+                  processedContent.push({
+                    type: "file",
+                    data: fileData,
+                    mimeType,
+                    filename: resource.title
+                  });
+                }
+                continue;
+              }
+            }
+            if ("data" in item && item.mimeType) {
+              const fileData = getFileData({ data: item.data });
+              const mimeType = item.mimeType;
+              const approxSize = typeof fileData === "string" ? Math.floor(fileData.length * 3 / 4) : 0;
+              const shouldStoreAsBlob = blobStore && approxSize > 1024;
+              if (shouldStoreAsBlob) {
+                try {
+                  logger.debug(
+                    `Storing MCP content item as blob (${approxSize} bytes, ${mimeType})`
+                  );
+                  const blobRef = await blobStore.store(fileData, {
+                    mimeType,
+                    source: "tool",
+                    originalName: buildToolBlobName(
+                      item.type === "image" ? "image" : "file",
+                      mimeType,
+                      namingOptions,
+                      item.filename
+                    )
+                  });
+                  logger.debug(
+                    `Stored MCP blob: ${blobRef.uri} (${approxSize} bytes)`
+                  );
+                  if (item.type === "image") {
+                    processedContent.push(
+                      createBlobImagePart(blobRef.uri, mimeType)
+                    );
+                  } else {
+                    processedContent.push(
+                      createBlobFilePart(blobRef.uri, mimeType, item.filename)
+                    );
+                  }
+                  continue;
+                } catch (error) {
+                  logger.warn(
+                    `Failed to store MCP blob, falling back to inline: ${String(error)}`
+                  );
+                }
+              }
+              if (item.type === "image") {
+                processedContent.push({
+                  type: "image",
+                  image: fileData,
+                  mimeType
+                });
+              } else {
+                processedContent.push({
+                  type: "file",
+                  data: fileData,
+                  mimeType,
+                  filename: item.filename
+                });
+              }
+              continue;
+            }
+          }
+          processedContent.push(item);
+        }
+        return processedContent;
+      }
       if ("image" in anyObj) {
+        const imageData = getImageData({ image: anyObj.image });
+        const mimeType = anyObj.mimeType || "image/jpeg";
+        const approxSize = typeof imageData === "string" ? Math.floor(imageData.length * 3 / 4) : 0;
+        const shouldStoreAsBlob = blobStore && approxSize > 1024;
+        if (shouldStoreAsBlob) {
+          try {
+            const blobRef = await blobStore.store(imageData, {
+              mimeType,
+              source: "tool",
+              originalName: buildToolBlobName("image", mimeType, namingOptions)
+            });
+            logger.debug(
+              `Stored tool image as blob: ${blobRef.uri} (${approxSize} bytes)`
+            );
+            return [createBlobImagePart(blobRef.uri, mimeType)];
+          } catch (error) {
+            logger.warn(
+              `Failed to store image blob, falling back to inline: ${String(error)}`
+            );
+          }
+        }
         return [
           {
             type: "image",
-            image: getImageData({ image: anyObj.image }),
-            mimeType: anyObj.mimeType || "image/jpeg"
+            image: imageData,
+            mimeType
           }
         ];
       }
       if ("data" in anyObj && anyObj.mimeType) {
+        const fileData = getFileData({ data: anyObj.data });
+        const mimeType = anyObj.mimeType;
+        const approxSize = typeof fileData === "string" ? Math.floor(fileData.length * 3 / 4) : 0;
+        const shouldStoreAsBlob = blobStore && approxSize > 1024;
+        if (shouldStoreAsBlob) {
+          try {
+            const blobRef = await blobStore.store(fileData, {
+              mimeType,
+              source: "tool",
+              originalName: buildToolBlobName(
+                "file",
+                mimeType,
+                namingOptions,
+                anyObj.filename
+              )
+            });
+            logger.debug(
+              `Stored tool file as blob: ${blobRef.uri} (${approxSize} bytes)`
+            );
+            return [createBlobFilePart(blobRef.uri, mimeType, anyObj.filename)];
+          } catch (error) {
+            logger.warn(
+              `Failed to store file blob, falling back to inline: ${String(error)}`
+            );
+          }
+        }
         return [
           {
             type: "file",
-            data: getFileData({ data: anyObj.data }),
-            mimeType: anyObj.mimeType,
+            data: fileData,
+            mimeType,
             filename: anyObj.filename
           }
         ];
@@ -305,7 +969,9 @@ ${tail}`;
     }
     return safeStringify(result ?? "");
   } catch (err) {
-    logger.warn(`sanitizeToolResultToContent failed, falling back to string: ${String(err)}`);
+    logger.warn(
+      `sanitizeToolResultToContentWithBlobs failed, falling back to string: ${String(err)}`
+    );
     try {
       return safeStringify(result ?? "");
     } catch {
@@ -313,6 +979,64 @@ ${tail}`;
     }
   }
 }
+function inferResourceKind(mimeType) {
+  return getResourceKind(mimeType);
+}
+function createBlobImagePart(uri, mimeType) {
+  return {
+    type: "image",
+    image: `@${uri}`,
+    ...mimeType ? { mimeType } : {}
+  };
+}
+function createBlobFilePart(uri, mimeType, filename) {
+  return {
+    type: "file",
+    data: `@${uri}`,
+    mimeType,
+    ...filename ? { filename } : {}
+  };
+}
+function extractResourceDescriptors(parts) {
+  const resources = [];
+  for (const part of parts) {
+    if (part.type === "image" && typeof part.image === "string" && part.image.startsWith("@blob:")) {
+      resources.push({
+        uri: part.image.substring(1),
+        kind: "image",
+        mimeType: part.mimeType ?? "image/jpeg"
+      });
+    }
+    if (part.type === "file" && typeof part.data === "string" && part.data.startsWith("@blob:")) {
+      resources.push({
+        uri: part.data.substring(1),
+        kind: inferResourceKind(part.mimeType),
+        mimeType: part.mimeType,
+        ...part.filename ? { filename: part.filename } : {}
+      });
+    }
+  }
+  return resources.length > 0 ? resources : void 0;
+}
+async function sanitizeToolResult(result, options) {
+  const normalized = await normalizeToolResult(result);
+  const persisted = await persistToolMedia(normalized, {
+    ...options.blobStore ? { blobStore: options.blobStore } : {},
+    toolName: options.toolName,
+    toolCallId: options.toolCallId
+  });
+  const fallbackContent = [{ type: "text", text: "" }];
+  const content = persisted.parts.length > 0 ? persisted.parts : fallbackContent;
+  return {
+    content,
+    ...persisted.resources ? { resources: persisted.resources } : {},
+    meta: {
+      toolName: options.toolName,
+      toolCallId: options.toolCallId,
+      ...typeof options.success === "boolean" ? { success: options.success } : {}
+    }
+  };
+}
 function summarizeToolContentForText(content) {
   if (!Array.isArray(content)) return String(content || "");
   const parts = [];
@@ -363,12 +1087,20 @@ function toTextForToolMessage(content) {
 }
 export {
   countMessagesTokens,
+  expandBlobReferences,
   filterMessagesByLLMCapabilities,
   getFileData,
+  getFileDataWithBlobSupport,
+  getFileMediaKind,
   getImageData,
+  getImageDataWithBlobSupport,
+  getResourceKind,
   isLikelyBase64String,
+  normalizeToolResult,
   parseDataUri,
-  sanitizeToolResultToContent,
+  persistToolMedia,
+  sanitizeToolResult,
+  sanitizeToolResultToContentWithBlobs,
   summarizeToolContentForText,
   toTextForToolMessage
 };