* do not receive these as inline image blocks.

*

* ⚠️ Call sites (chat.ts, agent.ts, server-node-events.ts) MUST also pass

* `supportsImages: modelSupportsImages(model)` so that text-only model runs

* do not inject unresolvable media:// markers into prompt text.

* `supportsImages: modelSupportsImages(model)` so text-only model runs

* offload images as media refs instead of passing inline image blocks.

*/

offloadedRefs: OffloadedRef[];

};

};

const OFFLOAD_THRESHOLD_BYTES = 2_000_000;

const TEXT_ONLY_OFFLOAD_LIMIT = 10;

const MIME_TO_EXT: Record<string, string> = {

"image/jpeg": ".jpg",

* because they are not passed inline to the model.

*

* ## Text-only model runs

* Pass `supportsImages: false` for text-only model runs so that no media://

* markers are injected into prompt text.

*

* ⚠️ Call sites in chat.ts, agent.ts, and server-node-events.ts MUST be

* updated to pass `supportsImages: modelSupportsImages(model)`. Until they do,

* text-only model runs receive unresolvable media:// markers in their prompt.

* Pass `supportsImages: false` for text-only model runs so images are offloaded

* as `media://inbound/<id>` refs instead of being sent as inline image blocks.

* The agent runner can then resolve the refs through the normal media path.

*

* ## Cleanup on failure

* On any parse failure after files have already been offloaded, best-effort

return { message, images: [], imageOrder: [], offloadedRefs: [] };

}

// For text-only models drop all attachments cleanly. Do not save files or

// inject media:// markers that would never be resolved and would leak

// internal path references into the model's prompt.

if (opts?.supportsImages === false) {

if (attachments.length > 0) {

log?.warn(

`parseMessageWithAttachments: ${attachments.length} attachment(s) dropped — model does not support images`,

);

}

return { message, images: [], imageOrder: [], offloadedRefs: [] };

}

const images: ChatImageContent[] = [];

const imageOrder: PromptImageOrderEntry[] = [];

const offloadedRefs: OffloadedRef[] = [];

let updatedMessage = message;

const shouldForceOffload = opts?.supportsImages === false;

// Track IDs of files saved during this request for cleanup if a later

// attachment fails validation and the entire parse is aborted.

let isOffloaded = false;

if (sizeBytes > OFFLOAD_THRESHOLD_BYTES) {

if (shouldForceOffload && offloadedRefs.length >= TEXT_ONLY_OFFLOAD_LIMIT) {

log?.warn(

`attachment ${label}: dropping image because text-only offload limit ` +

`${TEXT_ONLY_OFFLOAD_LIMIT} was reached`,

);

updatedMessage += "\n[image attachment omitted: text-only attachment limit reached]";

continue;

}

if (shouldForceOffload || sizeBytes > OFFLOAD_THRESHOLD_BYTES) {

const isSupportedForOffload = SUPPORTED_OFFLOAD_MIMES.has(finalMime);

if (!isSupportedForOffload) {

if (shouldForceOffload) {

log?.warn(

`attachment ${label}: format ${finalMime} cannot be offloaded for ` +

"text-only model, dropping",

);

continue;

}

// Passing this inline would reintroduce the OOM risk this PR prevents.

throw new Error(

`attachment ${label}: format ${finalMime} is too large to pass inline ` +

const mediaRef = `media://inbound/${savedMedia.id}`;

updatedMessage += `\n[media attached: ${mediaRef}]`;

log?.info?.(`[Gateway] Intercepted large image payload. Saved: ${mediaRef}`);

log?.info?.(

shouldForceOffload

? `[Gateway] Offloaded image for text-only model. Saved: ${mediaRef}`

: `[Gateway] Intercepted large image payload. Saved: ${mediaRef}`,

);

// Record for transcript metadata — separate from `images` because

// these are not passed inline to the model.