@opencow-ai/opencow-agent-sdk 0.4.10 → 0.4.12

package/dist/sdk.js

@@ -31267,6 +31267,27 @@ var init_types3 = __esm(() => {
   CanonicalUserAbortError = APIUserAbortError;
 });
 
+// src/session/canonical/imageSource.ts
+function normalizeCanonicalImageSource(source) {
+  if (!source || typeof source !== "object")
+    return null;
+  const s = source;
+  if (s.type === "base64" && typeof s.data === "string") {
+    return {
+      kind: "base64",
+      mediaType: typeof s.media_type === "string" ? s.media_type : "image/png",
+      data: s.data
+    };
+  }
+  if (s.type === "url" && typeof s.url === "string") {
+    return { kind: "url", url: s.url };
+  }
+  return null;
+}
+function imageSourceToDataUri(img) {
+  return img.kind === "base64" ? `data:${img.mediaType};base64,${img.data}` : img.url;
+}
+
 // src/session/canonical/index.ts
 var init_canonical = __esm(() => {
   init_types3();
@@ -94790,6 +94811,71 @@ var init_geminiAuth = __esm(() => {
   }, {}), GEMINI_ADC_CACHE_TTL_MS);
 });
 
+// src/providers/shared/dsmlSentinel.ts
+function normalizeDsmlSentinel(value) {
+  return value.replace(/｜/g, "|").replace(/\s+/g, "");
+}
+function isDsmlFunctionCallSentinelPrefix(value) {
+  const normalized = normalizeDsmlSentinel(value);
+  return normalized.length > 0 && DSML_FUNCTION_CALL_SENTINEL.startsWith(normalized);
+}
+function findDsmlFunctionCallSentinel(text) {
+  const re = /<\s*[｜|]\s*DSML\s*[｜|]\s*function_calls\b/;
+  const match = re.exec(text);
+  if (!match || match.index === undefined)
+    return null;
+  return { start: match.index, end: match.index + match[0].length };
+}
+function findTrailingDsmlCandidateStart(text) {
+  for (let i2 = 0;i2 < text.length; i2++) {
+    if (isDsmlFunctionCallSentinelPrefix(text.slice(i2))) {
+      return i2;
+    }
+  }
+  return null;
+}
+function createDsmlFunctionCallTextFilter() {
+  let pending = "";
+  const drain = (final) => {
+    let output = "";
+    while (pending) {
+      const sentinel = findDsmlFunctionCallSentinel(pending);
+      if (sentinel) {
+        output += pending.slice(0, sentinel.start).trimEnd();
+        pending = pending.slice(sentinel.end);
+        continue;
+      }
+      if (final) {
+        output += pending;
+        pending = "";
+        break;
+      }
+      const candidateStart = findTrailingDsmlCandidateStart(pending);
+      if (candidateStart === null) {
+        output += pending;
+        pending = "";
+        break;
+      }
+      output += pending.slice(0, candidateStart).trimEnd();
+      pending = pending.slice(candidateStart);
+      break;
+    }
+    return output;
+  };
+  return {
+    push(text) {
+      if (!text)
+        return "";
+      pending += text;
+      return drain(false);
+    },
+    flush() {
+      return drain(true);
+    }
+  };
+}
+var DSML_FUNCTION_CALL_SENTINEL = "<|DSML|function_calls";
+
 // src/providers/shared/geminiCredentials.ts
 function readGeminiAccessToken() {
   if (isBareMode())
@@ -95342,19 +95428,9 @@ function splitToolResultMedia(content) {
       continue;
     }
     if (block?.type === "image") {
-      const src = block.source;
-      if (src?.type === "base64" && typeof src.data === "string") {
-        images.push({
-          kind: "base64",
-          mediaType: src.media_type ?? "image/png",
-          data: src.data
-        });
-        continue;
-      }
-      if (src?.type === "url" && typeof src.url === "string") {
-        images.push({ kind: "url", url: src.url });
-        continue;
-      }
+      const img = normalizeCanonicalImageSource(block.source);
+      if (img)
+        images.push(img);
       continue;
     }
     if (typeof block?.text === "string") {
@@ -95365,8 +95441,7 @@ function splitToolResultMedia(content) {
 `), images };
 }
 function toResponsesInputImagePart(img) {
-  const url3 = img.kind === "base64" ? `data:${img.mediaType};base64,${img.data}` : img.url;
-  return { type: "input_image", image_url: url3 };
+  return { type: "input_image", image_url: imageSourceToDataUri(img) };
 }
 function convertContentBlocksToResponsesParts(content, role) {
   const textType = role === "assistant" ? "output_text" : "input_text";
@@ -95385,18 +95460,9 @@ function convertContentBlocksToResponsesParts(content, role) {
       case "image": {
         if (role === "assistant")
           break;
-        const source = block.source;
-        if (source?.type === "base64") {
-          parts.push({
-            type: "input_image",
-            image_url: `data:${source.media_type};base64,${source.data}`
-          });
-        } else if (source?.type === "url" && source.url) {
-          parts.push({
-            type: "input_image",
-            image_url: source.url
-          });
-        }
+        const img = normalizeCanonicalImageSource(block.source);
+        if (img)
+          parts.push(toResponsesInputImagePart(img));
         break;
       }
       case "thinking":
@@ -95706,9 +95772,21 @@ async function* codexStreamToAnthropic(response, model) {
   let nextContentBlockIndex = 0;
   let sawToolUse = false;
   let finalResponse;
+  const dsmlTextFilter = createDsmlFunctionCallTextFilter();
   const closeActiveTextBlock = async function* () {
     if (activeTextBlockIndex === null)
       return;
+    const flushedText = dsmlTextFilter.flush();
+    if (flushedText) {
+      yield {
+        type: "content_block_delta",
+        index: activeTextBlockIndex,
+        delta: {
+          type: "text_delta",
+          text: flushedText
+        }
+      };
+    }
     yield {
       type: "content_block_stop",
       index: activeTextBlockIndex
@@ -95820,14 +95898,17 @@ async function* codexStreamToAnthropic(response, model) {
     if (event.event === "response.output_text.delta") {
       yield* startTextBlockIfNeeded();
       if (activeTextBlockIndex !== null) {
-        yield {
-          type: "content_block_delta",
-          index: activeTextBlockIndex,
-          delta: {
-            type: "text_delta",
-            text: payload.delta ?? ""
-          }
-        };
+        const filteredText = dsmlTextFilter.push(payload.delta ?? "");
+        if (filteredText) {
+          yield {
+            type: "content_block_delta",
+            index: activeTextBlockIndex,
+            delta: {
+              type: "text_delta",
+              text: filteredText
+            }
+          };
+        }
       }
       continue;
     }
@@ -95969,6 +96050,7 @@ var init_shim = __esm(() => {
   init_sdk();
   init_schema();
   init_capabilities2();
+  init_canonical();
 });
 
 // src/providers/shared/providerRecommendation.ts
@@ -96111,19 +96193,9 @@ function splitToolResultMedia2(content) {
       continue;
     }
     if (block?.type === "image") {
-      const source = block.source;
-      if (source?.type === "base64" && typeof source.data === "string") {
-        images.push({
-          kind: "base64",
-          mediaType: source.media_type ?? "image/png",
-          data: source.data
-        });
-        continue;
-      }
-      if (source?.type === "url" && typeof source.url === "string") {
-        images.push({ kind: "url", url: source.url });
-        continue;
-      }
+      const img = normalizeCanonicalImageSource(block.source);
+      if (img)
+        images.push(img);
       continue;
     }
     if (block?.type === "tool_reference" && typeof block.tool_name === "string") {
@@ -96138,8 +96210,7 @@ function splitToolResultMedia2(content) {
 `), images };
 }
 function toOpenAIImageUrl(img) {
-  const url3 = img.kind === "base64" ? `data:${img.mediaType};base64,${img.data}` : img.url;
-  return { type: "image_url", image_url: { url: url3 } };
+  return { type: "image_url", image_url: { url: imageSourceToDataUri(img) } };
 }
 function convertContentBlocks(content) {
   if (typeof content === "string")
@@ -96153,17 +96224,9 @@ function convertContentBlocks(content) {
         parts.push({ type: "text", text: block.text ?? "" });
         break;
       case "image": {
-        const src = block.source;
-        if (src?.type === "base64") {
-          parts.push({
-            type: "image_url",
-            image_url: {
-              url: `data:${src.media_type};base64,${src.data}`
-            }
-          });
-        } else if (src?.type === "url") {
-          parts.push({ type: "image_url", image_url: { url: src.url } });
-        }
+        const img = normalizeCanonicalImageSource(block.source);
+        if (img)
+          parts.push(toOpenAIImageUrl(img));
         break;
       }
       case "tool_use":
@@ -96433,32 +96496,6 @@ function buildOpenAIRequestBody(params, ctx) {
   }
   return body;
 }
-function normalizeDsmlSentinelPrefix(value) {
-  return value.replace(/｜/g, "|").replace(/\s+/g, "");
-}
-function isDsmlFunctionCallSentinelPrefix(value) {
-  const normalized = normalizeDsmlSentinelPrefix(value);
-  return normalized.length > 0 && DSML_FUNCTION_CALL_SENTINEL.startsWith(normalized);
-}
-function findTrailingDsmlSentinelCandidateStart(text) {
-  const lt = text.lastIndexOf("<");
-  if (lt === -1)
-    return null;
-  return isDsmlFunctionCallSentinelPrefix(text.slice(lt)) ? lt : null;
-}
-function findBufferedTextFlushBoundary(text) {
-  const sentinelStart = findTrailingDsmlSentinelCandidateStart(text);
-  if (sentinelStart === null)
-    return text.length;
-  return text.slice(0, sentinelStart).trimEnd().length;
-}
-function findDsmlFunctionCallSentinel(text) {
-  const re = /<\s*[｜|]\s*DSML\s*[｜|]\s*function_calls\b/;
-  const match = re.exec(text);
-  if (!match || match.index === undefined)
-    return null;
-  return { start: match.index, end: match.index + match[0].length };
-}
 async function* openaiStreamToAnthropic(response, model) {
   const messageId = makeMessageId2();
   let contentBlockIndex = 0;
@@ -96470,27 +96507,13 @@ async function* openaiStreamToAnthropic(response, model) {
   let hasEmittedFinalUsage = false;
   let hasProcessedFinishReason = false;
   let pendingTextBuffer = "";
+  const dsmlTextFilter = createDsmlFunctionCallTextFilter();
   const emitBufferedText = (mode) => {
     const events = [];
-    if (!pendingTextBuffer)
+    if (!pendingTextBuffer && mode !== "final")
       return events;
-    const sentinel = findDsmlFunctionCallSentinel(pendingTextBuffer);
-    if (sentinel) {
-      const visible2 = pendingTextBuffer.slice(0, sentinel.start).trimEnd();
-      pendingTextBuffer = pendingTextBuffer.slice(sentinel.end);
-      if (visible2) {
-        events.push(...emitTextDeltaEvents(visible2));
-      }
-      if (pendingTextBuffer) {
-        events.push(...emitBufferedText(mode));
-      }
-      return events;
-    }
-    const emitUntil = mode === "final" ? pendingTextBuffer.length : mode === "before_tool_call" ? findTrailingDsmlSentinelCandidateStart(pendingTextBuffer) ?? pendingTextBuffer.length : findBufferedTextFlushBoundary(pendingTextBuffer);
-    if (emitUntil <= 0)
-      return events;
-    const visible = pendingTextBuffer.slice(0, emitUntil);
-    pendingTextBuffer = pendingTextBuffer.slice(emitUntil);
+    const visible = mode === "final" ? dsmlTextFilter.push(pendingTextBuffer) + dsmlTextFilter.flush() : dsmlTextFilter.push(pendingTextBuffer);
+    pendingTextBuffer = "";
     if (visible) {
       events.push(...emitTextDeltaEvents(visible));
     }
@@ -97067,7 +97090,7 @@ function createOpenAIShimClient(options) {
     messages: beta.messages
   };
 }
-var GITHUB_MODELS_DEFAULT_BASE = "https://models.github.ai/inference", GITHUB_API_VERSION = "2022-11-28", GITHUB_429_MAX_RETRIES = 3, GITHUB_429_BASE_DELAY_SEC = 1, GITHUB_429_MAX_DELAY_SEC = 32, DSML_FUNCTION_CALL_SENTINEL = "<|DSML|function_calls", OpenAIShimStream;
+var GITHUB_MODELS_DEFAULT_BASE = "https://models.github.ai/inference", GITHUB_API_VERSION = "2022-11-28", GITHUB_429_MAX_RETRIES = 3, GITHUB_429_BASE_DELAY_SEC = 1, GITHUB_429_MAX_DELAY_SEC = 32, OpenAIShimStream;
 var init_shim2 = __esm(() => {
   init_sdk();
   init_envUtils();
@@ -97080,6 +97103,7 @@ var init_shim2 = __esm(() => {
   init_schemaSanitizer();
   init_providerProfile();
   init_capabilities2();
+  init_canonical();
   OpenAIShimStream = class OpenAIShimStream {
     generator;
     controller = new AbortController;
@@ -273582,9 +273606,21 @@ var init_mcpWebSocketTransport = __esm(() => {
 });
 
 // src/capabilities/adapters/callToolResultAdapter.ts
+async function buildImageBlock(bytes, mediaType, uploadMedia) {
+  let url3 = null;
+  if (uploadMedia) {
+    try {
+      url3 = await uploadMedia({ bytes, mediaType });
+    } catch (e) {
+      logError(e);
+    }
+  }
+  const source = url3 ? { type: "url", url: url3 } : { type: "base64", media_type: mediaType, data: bytes.toString("base64") };
+  return { type: "image", source };
+}
 async function translateMcpContentItem(input) {
   const { item, options: options2 } = input;
-  const { sourceName } = options2;
+  const { sourceName, uploadMedia } = options2;
   switch (item.type) {
     case "text":
       return [{ type: "text", text: item.text }];
@@ -273602,14 +273638,7 @@ async function translateMcpContentItem(input) {
       const ext = item.mimeType?.split("/")[1] || "png";
       const resized = await maybeResizeAndDownsampleImageBuffer(imageBuffer, imageBuffer.length, ext);
       return [
-        {
-          type: "image",
-          source: {
-            data: resized.buffer.toString("base64"),
-            media_type: `image/${resized.mediaType}`,
-            type: "base64"
-          }
-        }
+        await buildImageBlock(resized.buffer, `image/${resized.mediaType}`, uploadMedia)
       ];
     }
     case "resource": {
@@ -273626,14 +273655,7 @@ async function translateMcpContentItem(input) {
           const resized = await maybeResizeAndDownsampleImageBuffer(imageBuffer, imageBuffer.length, ext);
           return [
             { type: "text", text: prefix },
-            {
-              type: "image",
-              source: {
-                data: resized.buffer.toString("base64"),
-                media_type: `image/${resized.mediaType}`,
-                type: "base64"
-              }
-            }
+            await buildImageBlock(resized.buffer, `image/${resized.mediaType}`, uploadMedia)
           ];
         }
         return await persistBlobToTextBlock({
@@ -273687,6 +273709,7 @@ var IMAGE_MIME_TYPES;
 var init_callToolResultAdapter = __esm(() => {
   init_imageResizer();
   init_mcpOutputStorage();
+  init_log2();
   IMAGE_MIME_TYPES = new Set([
     "image/jpeg",
     "image/png",
@@ -282652,7 +282675,7 @@ function getAnthropicEnvMetadata() {
 function getBuildAgeMinutes() {
   if (false)
     ;
-  const buildTime = new Date("2026-06-23T14:32:49.206Z").getTime();
+  const buildTime = new Date("2026-06-24T10:02:32.669Z").getTime();
   if (isNaN(buildTime))
     return;
   return Math.floor((Date.now() - buildTime) / 60000);
@@ -285976,6 +285999,16 @@ async function validateContentTokens(content, ext, maxTokens) {
     throw new MaxFileReadTokenExceededError(effectiveCount, effectiveMaxTokens);
   }
 }
+async function maybeUploadBytes(uploadMedia, bytes, mediaType) {
+  if (!uploadMedia)
+    return null;
+  try {
+    return await uploadMedia({ bytes, mediaType });
+  } catch (e) {
+    logError(e);
+    return null;
+  }
+}
 function createImageResponse(buffer, mediaType, originalSize, dimensions) {
   return {
     type: "image",
@@ -286023,6 +286056,10 @@ async function callInner(file_path, fullFilePath, resolvedFilePath, ext, offset,
   if (IMAGE_EXTENSIONS.has(ext)) {
     const data2 = await readImageWithTokenBudget(resolvedFilePath, maxTokens);
     context4.nestedMemoryAttachmentTriggers?.add(fullFilePath);
+    const uploadedUrl = await maybeUploadBytes(context4.uploadMedia, Buffer.from(data2.file.base64, "base64"), data2.file.type);
+    if (uploadedUrl) {
+      data2.file.url = uploadedUrl;
+    }
     logFileOperation({
       operation: "read",
       tool: "FileReadTool",
@@ -286064,14 +286101,14 @@ async function callInner(file_path, fullFilePath, resolvedFilePath, ext, offset,
         const imgPath = path11.join(extractResult.data.file.outputDir, f);
         const imgBuffer = await getFsImplementation().readFile(imgPath);
         const resized = await maybeResizeAndDownsampleImageBuffer(imgBuffer, imgBuffer.length, "jpeg");
-        return {
-          type: "image",
-          source: {
-            type: "base64",
-            media_type: `image/${resized.mediaType}`,
-            data: resized.buffer.toString("base64")
-          }
+        const mediaType = `image/${resized.mediaType}`;
+        const uploadedUrl2 = await maybeUploadBytes(context4.uploadMedia, resized.buffer, mediaType);
+        const source = uploadedUrl2 ? { type: "url", url: uploadedUrl2 } : {
+          type: "base64",
+          media_type: mediaType,
+          data: resized.buffer.toString("base64")
         };
+        return { type: "image", source };
       }));
       return {
         data: extractResult.data,
@@ -286119,20 +286156,17 @@ async function callInner(file_path, fullFilePath, resolvedFilePath, ext, offset,
       filePath: fullFilePath,
       content: pdfData.file.base64
     });
+    const uploadedUrl = await maybeUploadBytes(context4.uploadMedia, Buffer.from(pdfData.file.base64, "base64"), "application/pdf");
+    const documentSource = uploadedUrl ? { type: "url", url: uploadedUrl } : {
+      type: "base64",
+      media_type: "application/pdf",
+      data: pdfData.file.base64
+    };
     return {
       data: pdfData,
       newMessages: [
         createUserMessage({
-          content: [
-            {
-              type: "document",
-              source: {
-                type: "base64",
-                media_type: "application/pdf",
-                data: pdfData.file.base64
-              }
-            }
-          ],
+          content: [{ type: "document", source: documentSource }],
           isMeta: true
         })
       ]
@@ -286339,6 +286373,7 @@ var init_FileReadTool = __esm(() => {
           base64: exports_external2.string().describe("Base64-encoded image data"),
           type: imageMediaTypes.describe("The MIME type of the image"),
           originalSize: exports_external2.number().describe("Original file size in bytes"),
+          url: exports_external2.string().optional().describe("Fetchable URL for the (compressed) image when a host uploader is configured; takes precedence over base64 for rendering"),
           dimensions: exports_external2.object({
             originalWidth: exports_external2.number().optional().describe("Original image width in pixels"),
             originalHeight: exports_external2.number().optional().describe("Original image height in pixels"),
@@ -286567,17 +286602,18 @@ var init_FileReadTool = __esm(() => {
     mapToolResultToToolResultBlockParam(data, toolUseID) {
       switch (data.type) {
         case "image": {
+          const source = data.file.url ? { type: "url", url: data.file.url } : {
+            type: "base64",
+            data: data.file.base64,
+            media_type: data.file.type
+          };
           return {
             tool_use_id: toolUseID,
             type: "tool_result",
             content: [
               {
                 type: "image",
-                source: {
-                  type: "base64",
-                  data: data.file.base64,
-                  media_type: data.file.type
-                }
+                source
               }
             ]
           };
@@ -293936,6 +293972,7 @@ ${deferredToolList}
       const STALL_THRESHOLD_MS2 = 30000;
       let totalStallTime = 0;
       let stallCount = 0;
+      const dsmlTextFilters = new Map;
       for await (const part of stream4) {
         resetStreamIdleTimer();
         const now = Date.now();
@@ -294002,6 +294039,7 @@ ${deferredToolList}
                   ...part.content_block,
                   text: ""
                 };
+                dsmlTextFilters.set(part.index, createDsmlFunctionCallTextFilter());
                 break;
               case "thinking":
                 contentBlocks[part.index] = {
@@ -294061,7 +294099,13 @@ ${deferredToolList}
                     });
                     throw new Error("Content block is not a text block");
                   }
-                  contentBlock.text += delta.text;
+                  {
+                    const filter2 = dsmlTextFilters.get(part.index) ?? createDsmlFunctionCallTextFilter();
+                    dsmlTextFilters.set(part.index, filter2);
+                    const visibleText = filter2.push(delta.text);
+                    delta.text = visibleText;
+                    contentBlock.text += visibleText;
+                  }
                   break;
                 case "signature_delta":
                   if (false) {}
@@ -294110,6 +294154,11 @@ ${deferredToolList}
               });
               throw new Error("Message not found");
             }
+            const filter2 = dsmlTextFilters.get(part.index);
+            if (filter2 && contentBlock.type === "text") {
+              contentBlock.text += filter2.flush();
+              dsmlTextFilters.delete(part.index);
+            }
             const m = {
               message: {
                 ...partialMessage,
@@ -299960,6 +300009,7 @@ class QueryEngine {
       agents = [],
       setSDKStatus,
       onToolInvoke,
+      uploadMedia,
       orphanedPermission
     } = this.config;
     this.discoveredSkillNames.clear();
@@ -300063,7 +300113,8 @@ class QueryEngine {
         });
       },
       setSDKStatus,
-      onToolInvoke
+      onToolInvoke,
+      uploadMedia
     };
     if (orphanedPermission && !this.hasHandledOrphanedPermission) {
       this.hasHandledOrphanedPermission = true;
@@ -300152,7 +300203,8 @@ class QueryEngine {
       setResponseLength: () => {},
       updateFileHistoryState: processUserInputContext.updateFileHistoryState,
       updateAttributionState: processUserInputContext.updateAttributionState,
-      setSDKStatus
+      setSDKStatus,
+      uploadMedia
     };
     headlessProfilerCheckpoint("before_skills_plugins");
     const [skills, { enabled: enabledPlugins }] = await Promise.all([
@@ -300647,6 +300699,7 @@ async function* ask({
   agents = [],
   setSDKStatus,
   onToolInvoke,
+  uploadMedia,
   orphanedPermission
 }) {
   const engine = new QueryEngine({
@@ -300679,6 +300732,7 @@ async function* ask({
     includePartialMessages,
     setSDKStatus,
     onToolInvoke,
+    uploadMedia,
     abortController,
     orphanedPermission,
     ...{}
@@ -329426,7 +329480,7 @@ function toInternalTool(sdkTool) {
       });
       const content = await translateCallToolResultContent({
         content: result.content,
-        options: { sourceName: sdkTool.name }
+        options: { sourceName: sdkTool.name, uploadMedia: context4.uploadMedia }
       });
       return { data: content };
     }
@@ -329949,6 +330003,7 @@ function runSdkQueryRuntime(params) {
           includePartialMessages: Boolean(options2.includePartialMessages),
           agents: mergedAgents,
           onToolInvoke: typeof options2.onToolInvoke === "function" ? options2.onToolInvoke : undefined,
+          uploadMedia: typeof options2.uploadMedia === "function" ? options2.uploadMedia : undefined,
           setSDKStatus: (status) => {
             turnStatusStream.enqueue({
               type: "system",
@@ -336002,4 +336057,4 @@ export {
   AbortError2 as AbortError
 };
 
-//# debugId=432C8411F9337F1F64756E2164756E21
+//# debugId=72C79E88061B251D64756E2164756E21

package/dist/session/canonical/imageSource.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Shared, url-aware normalization for canonical image sources.
+ *
+ * Canonical image blocks carry a discriminated `source` union
+ * (`CanonicalImageSource`: base64 | url). Every wire adapter that has to
+ * render an image — OpenAI Chat Completions, OpenAI Responses, and the
+ * tool_result fan-out on both — needs the same "is this base64 or a url"
+ * decision. This module owns that single decision so the providers stay in
+ * lock-step (truthiness checks, the `image/png` fallback, and "drop unknown
+ * sources silently" all live here, not duplicated four times).
+ */
+/** Result of normalizing a raw image `source` into a wire-agnostic shape. */
+export type NormalizedImageSource = {
+    kind: 'base64';
+    mediaType: string;
+    data: string;
+} | {
+    kind: 'url';
+    url: string;
+};
+/**
+ * Reduce a raw (untrusted) image `source` to a normalized base64/url shape,
+ * or `null` when it is neither. Callers treat `null` as "drop this image"
+ * — silently, to avoid smuggling a misleading placeholder into the model's
+ * context.
+ *
+ * Takes `unknown` because the source arrives off a loosely-typed message
+ * payload (history replay, MCP tool output) where the discriminant is not
+ * statically guaranteed.
+ */
+export declare function normalizeCanonicalImageSource(source: unknown): NormalizedImageSource | null;
+/**
+ * Render a normalized image as a single string usable wherever a wire format
+ * wants one field: a `data:` URI for base64, or the url verbatim. Used by the
+ * OpenAI `image_url` and Responses `input_image` parts.
+ */
+export declare function imageSourceToDataUri(img: NormalizedImageSource): string;

package/dist/session/canonical/index.d.ts

@@ -5,4 +5,5 @@
  * future refactors (e.g. splitting types/runtime validators/brands) do
  * not ripple through consumer imports.
  */
-export { CANONICAL_VERSION, CanonicalAPIError, CanonicalUserAbortError, type CanonicalBase64ImageSource, type CanonicalContentBlock, type CanonicalContentBlockParam, type CanonicalImageBlockParam, type CanonicalMessage, type CanonicalMessageParam, type CanonicalStreamEvent, type CanonicalTextBlock, type CanonicalTextBlockParam, type CanonicalRedactedThinkingBlock, type CanonicalRedactedThinkingBlockParam, type CanonicalThinkingBlock, type CanonicalThinkingBlockParam, type CanonicalToolResultBlockParam, type CanonicalToolUnion, type CanonicalToolUseBlock, type CanonicalToolUseBlockParam, type CanonicalUsage, type CanonicalVersion, } from './types.js';
+export { CANONICAL_VERSION, CanonicalAPIError, CanonicalUserAbortError, type CanonicalBase64ImageSource, type CanonicalURLImageSource, type CanonicalImageSource, type CanonicalContentBlock, type CanonicalContentBlockParam, type CanonicalImageBlockParam, type CanonicalMessage, type CanonicalMessageParam, type CanonicalStreamEvent, type CanonicalTextBlock, type CanonicalTextBlockParam, type CanonicalRedactedThinkingBlock, type CanonicalRedactedThinkingBlockParam, type CanonicalThinkingBlock, type CanonicalThinkingBlockParam, type CanonicalToolResultBlockParam, type CanonicalToolUnion, type CanonicalToolUseBlock, type CanonicalToolUseBlockParam, type CanonicalUsage, type CanonicalVersion, } from './types.js';
+export { imageSourceToDataUri, normalizeCanonicalImageSource, type NormalizedImageSource, } from './imageSource.js';