@jini-ai/agent-runtime 0.2.1 → 0.3.0

package/dist/providers/openai-chat.js

@@ -32,9 +32,42 @@
  * field, not model-aware) — matching OD's own azure handler, which never
  * uses the model-aware picker (Azure deployment names are caller-defined
  * strings, not necessarily matching OpenAI's own model-naming scheme).
+ *
+ * **Image support**: verified against `developers.openai.com/api/docs/api-reference/chat/create`
+ * (the Chat Completions endpoint specifically — a redirect from the older
+ * `platform.openai.com/docs/guides/vision` URL now leads to a *different*, newer Responses API
+ * guide that uses `input_text`/`input_image` part names; those do not apply here and are not
+ * modeled). A user/system/assistant message's `content` may be an array mixing `{type:'text'}` and
+ * `{type:'image_url', image_url:{url, detail?}}` parts; `url` is either an `https://` URL (OpenAI's
+ * servers fetch it — see `invalidOpenAiContentPartReason`'s doc for why this module does not size-
+ * check that case) or a `data:<mime>;base64,<data>` URI. Supported formats per the same reference:
+ * PNG/JPEG/WEBP/non-animated GIF; documented limits are a 512 MB total request payload and 1500
+ * images per request (this module also applies its own conservative single-image guard — see
+ * `MAX_IMAGE_DATA_URI_BASE64_CHARS`'s doc).
+ *
+ * **Tool messages cannot carry an image** — confirmed against the same API reference: a `role:
+ * 'tool'` message's `content` is documented as `string | ChatCompletionContentPartText[]` only
+ * ("For tool messages, only type text is supported"). So a vision self-check whose tool result
+ * includes a screenshot cannot put that image on the `tool` message itself. `runOpenAiToolTurn`
+ * instead keeps the `tool` message text-only (see `splitOpenAiToolResultContent`) and appends one
+ * synthetic `role: 'user'` message carrying every image from the batch, built up while iterating
+ * every `tool_call` in the batch but appended exactly once, after every one of that batch's `tool`
+ * messages — never interleaved between them or emitted per-call, since OpenAI requires every `tool`
+ * message answering a batch of parallel `tool_calls` to directly follow the assistant message with
+ * nothing else in between. This is a real 400 if violated, not a style concern — see
+ * `runOpenAiToolTurn`'s tool-loop body and its test file's multi-tool-call image test.
+ *
+ * **This synthetic follow-up message is a workaround for the OpenAI wire protocol's own text-only
+ * `tool` message, not structure this module invented.** Anthropic's `tool_result` content block can
+ * carry an image directly (see `anthropic-messages.ts`) and needs no such split. Each image (or run
+ * of images) in the follow-up is preceded by a plain-text label naming the tool call it answers
+ * (name + `tool_call_id`) — an unlabeled image sitting alone in a `user` message is indistinguishable
+ * from a human having just pasted a screenshot, which in a vision self-check loop risks the model
+ * treating its own tool's output as a brand-new user request instead of a continuation of its own
+ * reasoning.
  */
 import { createRoleMarkerGuard } from '../role-marker-guard.js';
-import { redactSecrets, validateBaseUrl } from './connection-guard.js';
+import { defaultDnsLookup, pinnedFetch, redactSecrets, validateBaseUrlResolved } from './connection-guard.js';
 import { decodeSseStream } from './sse-decode.js';
 import { buildOpenAIChatTokenParam } from './token-params.js';
 import { createTurnEndGuard } from './turn-end-guard.js';
@@ -46,18 +79,18 @@ export const DEFAULT_OPENAI_MAX_TOKENS = 8192;
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
-function openAiRequestUrl(baseUrl) {
+export function openAiRequestUrl(baseUrl) {
     const base = (baseUrl ?? DEFAULT_OPENAI_BASE_URL).replace(/\/+$/, '');
     return /\/v\d+(\/|$)/.test(base) ? `${base}/chat/completions` : `${base}/v1/chat/completions`;
 }
-function openAiHeaders(options) {
+export function openAiHeaders(options) {
     return {
         'content-type': 'application/json',
         authorization: `Bearer ${options.apiKey}`,
         ...(options.extraHeaders ?? {}),
     };
 }
-function openAiRequestBody(options, messages) {
+export function openAiRequestBody(options, messages) {
     const effectiveMaxTokens = typeof options.maxTokens === 'number' && options.maxTokens > 0 ? options.maxTokens : DEFAULT_OPENAI_MAX_TOKENS;
     return {
         model: options.model,
@@ -69,7 +102,7 @@ function openAiRequestBody(options, messages) {
         ...(options.tools && options.tools.length > 0 ? { tools: options.tools } : {}),
     };
 }
-function extractOpenAiErrorDetail(rawText) {
+export function extractOpenAiErrorDetail(rawText) {
     try {
         const parsed = JSON.parse(rawText);
         if (isRecord(parsed) && isRecord(parsed.error) && typeof parsed.error.message === 'string') {
@@ -81,46 +114,147 @@ function extractOpenAiErrorDetail(rawText) {
     }
     return rawText.trim().slice(0, 500);
 }
+/** Parses one SSE frame's data as a JSON object, or `null` for a malformed/empty keep-alive frame or a non-object payload — both are tolerated by the caller as "nothing to do this frame". */
+export function parseOpenAiSseData(raw) {
+    let data;
+    try {
+        data = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    return isRecord(data) ? data : null;
+}
+export function applyOpenAiStreamUsage(state, data, onEvent) {
+    if (!isRecord(data.usage))
+        return;
+    state.usage = data.usage;
+    onEvent({ type: 'usage', usage: data.usage });
+}
+/** The chunk's first (and, for Chat Completions, only) choice — `null` when the chunk carries no choice at all (e.g. a usage-only trailer chunk). */
+export function firstOpenAiChoice(data) {
+    const choices = Array.isArray(data.choices) ? data.choices : [];
+    const choice = choices[0];
+    return isRecord(choice) ? choice : null;
+}
 /**
- * Runs exactly one OpenAI-compatible (Chat Completions JSON wire format)
- * streaming HTTP request and reduces its SSE events into a single outcome.
- * Extracted so this ~150-line SSE-reduction loop has exactly one
- * implementation shared by every OpenAI-compatible provider turn-runner in
- * this package: `runOpenAiToolTurn` itself (below), plus
- * `azure-chat.ts#runAzureToolTurn` and `ollama-chat.ts#runOllamaToolTurn` —
- * both target byte-identical chat-completions JSON, differing only in URL
- * and auth. Callers own their own base-URL SSRF validation
- * (`validateBaseUrl`) and URL/header/body construction *before* calling
- * this function — it only knows how to run *a* request against whatever
- * URL/headers/body it is handed, and has no opinion on any provider's
- * defaults. Mirrors `anthropic-messages.ts#runSingleAnthropicRequest`'s
- * `emitEnd` contract — see that function's doc.
+ * Feeds one text delta through the role-marker guard and emits the safe portion. Returns
+ * `'break'` once the guard flags contamination (the caller ends the turn immediately), otherwise
+ * `'continue'` — same contract as `anthropic-messages.ts#handleAnthropicTextDelta`.
  */
-export async function runOpenAiCompatibleRequest(init) {
-    const { onEvent, emitEnd, hasEnded } = init;
+export function handleOpenAiTextContentDelta(state, content, onEvent) {
+    const safe = state.guard.feedText(content);
+    if (safe.length > 0) {
+        state.fullText += safe;
+        onEvent({ type: 'text_delta', delta: safe });
+    }
+    if (!state.guard.contaminated)
+        return 'continue';
+    const warn = state.guard.warningEvent();
+    if (warn)
+        onEvent(warn);
+    return 'break';
+}
+/** Builds a fresh `PendingToolCall` from the streaming chunk that first mentions a given tool-call index — OpenAI sends `id`/`function.name` once, on that first chunk, then dribbles `function.arguments` in across subsequent chunks (accumulated separately by the caller). */
+export function newPendingOpenAiToolCall(rawCall, index) {
+    const id = typeof rawCall.id === 'string' ? rawCall.id : `call_${index}`;
+    const fn = isRecord(rawCall.function) ? rawCall.function : {};
+    const name = typeof fn.name === 'string' ? fn.name : '';
+    return { id, name, argsJson: '' };
+}
+/** Accumulates one `delta.tool_calls[]` entry from a streaming chunk into its running `PendingToolCall`. */
+export function accumulateOpenAiToolCallDelta(state, rawCall) {
+    if (!isRecord(rawCall) || typeof rawCall.index !== 'number')
+        return;
+    let pending = state.toolCalls.get(rawCall.index);
+    if (!pending) {
+        pending = newPendingOpenAiToolCall(rawCall, rawCall.index);
+        state.toolCalls.set(rawCall.index, pending);
+    }
+    const fn = isRecord(rawCall.function) ? rawCall.function : null;
+    if (fn && typeof fn.arguments === 'string') {
+        pending.argsJson += fn.arguments;
+    }
+}
+/** Reduces one chunk's `choices[0]` — `finish_reason`, text content, and tool-call deltas — into `state`. Returns `'break'` when the text-delta guard detects contamination. */
+export function handleOpenAiChoiceDelta(state, choice, onEvent) {
+    if (typeof choice.finish_reason === 'string') {
+        state.finishReason = choice.finish_reason;
+    }
+    const delta = isRecord(choice.delta) ? choice.delta : null;
+    if (!delta)
+        return 'continue';
+    if (typeof delta.content === 'string' && delta.content.length > 0) {
+        if (handleOpenAiTextContentDelta(state, delta.content, onEvent) === 'break')
+            return 'break';
+    }
+    if (Array.isArray(delta.tool_calls)) {
+        for (const rawCall of delta.tool_calls) {
+            accumulateOpenAiToolCallDelta(state, rawCall);
+        }
+    }
+    return 'continue';
+}
+/** Parses one accumulated tool call's `argsJson`, falling back to `{}` for empty or malformed JSON — mirrors Anthropic's identical fallback for `input_json_delta` accumulation in `anthropic-messages.ts`. */
+export function resolveOpenAiToolCalls(pending) {
+    return Array.from(pending.values()).map((call) => {
+        let input = {};
+        if (call.argsJson.trim()) {
+            try {
+                input = JSON.parse(call.argsJson);
+            }
+            catch {
+                input = {};
+            }
+        }
+        return { id: call.id, name: call.name, input };
+    });
+}
+function emitPendingOpenAiToolUseEvents(toolCalls, onEvent) {
+    for (const call of toolCalls) {
+        onEvent({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
+    }
+}
+/**
+ * Opens the streaming POST and validates the response, returning its readable body once every
+ * pre-stream failure mode (network error, non-2xx status with no retry available, missing body)
+ * has been ruled out. Calls `emitEnd('error')` and returns `{type: 'ended'}` itself on any of
+ * those — the caller only has to branch on the outcome's `type`, keeping `hasEnded()` as the sole
+ * gate for every exit path (see `runOpenAiCompatibleRequest`'s doc).
+ */
+async function requestOpenAiCompatibleStream(init) {
+    const { onEvent, emitEnd } = init;
     let response;
     try {
-        response = (await fetch(init.url, {
+        response = await (init.fetchImpl ?? pinnedFetch)(init.url, {
             method: 'POST',
             headers: init.headers,
             body: JSON.stringify(init.body),
+            // The caller's SSRF check (`validateBaseUrlResolved`) only ever sees the
+            // ORIGINAL url. Following a redirect would let a public, guard-passing
+            // endpoint hand back a `302 -> http://169.254.169.254/...` and reach the
+            // address the guard exists to refuse — with the provider auth headers
+            // still attached. `model-catalog.ts`'s own fetch already refuses
+            // redirects for the same reason; a redirecting chat-completions endpoint
+            // is not a thing any supported provider does. `pinnedFetch` never
+            // follows one regardless (see its doc); `redirect: 'error'` here is
+            // self-documentation, not the mechanism.
+            redirect: 'error',
             ...(init.signal ? { signal: init.signal } : {}),
-        }));
+        }, init.pinnedAddress);
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
         onEvent({ type: 'error', message: redactSecrets(message, init.redactSecretsList) });
         emitEnd('error');
-        return { finishReason: null, toolCalls: [], text: '' };
+        return { type: 'ended' };
     }
     if (!response.ok) {
         const rawText = await response.text();
-        if (init.retryableBody) {
-            const retryBody = init.retryableBody(response.status, rawText);
-            if (retryBody) {
-                const { retryableBody: _retryableBody, ...retryInit } = init;
-                return runOpenAiCompatibleRequest({ ...retryInit, body: retryBody });
-            }
+        const retryBody = init.retryableBody?.(response.status, rawText);
+        if (retryBody) {
+            const { retryableBody: _retryableBody, ...retryInit } = init;
+            return { type: 'retry', retryInit: { ...retryInit, body: retryBody } };
         }
         onEvent({
             type: 'error',
@@ -128,109 +262,95 @@ export async function runOpenAiCompatibleRequest(init) {
             code: String(response.status),
         });
         emitEnd('error');
-        return { finishReason: null, toolCalls: [], text: '' };
+        return { type: 'ended' };
     }
     if (!response.body) {
         onEvent({ type: 'error', message: `${init.providerLabel} response had no body` });
         emitEnd('error');
+        return { type: 'ended' };
+    }
+    return { type: 'body', body: response.body };
+}
+/**
+ * Reduces one decoded SSE frame into `state`, reporting what the caller's loop should do next:
+ * `'done'` on the `[DONE]` sentinel, `'contaminated'` once the role-marker guard trips on this
+ * frame's text delta, otherwise `'continue'`. Pulling per-frame dispatch out of the loop body
+ * turns what would be four sequential, nesting-penalized `if`s into a single function call plus
+ * one outcome check — see `runOpenAiCompatibleRequest`'s loop below.
+ */
+export function processOpenAiStreamFrame(state, frame, onEvent) {
+    if (frame.data === DONE_SENTINEL)
+        return 'done';
+    const data = parseOpenAiSseData(frame.data);
+    if (!data)
+        return 'continue'; // malformed/empty keep-alive frame, or a non-object payload
+    applyOpenAiStreamUsage(state, data, onEvent);
+    const choice = firstOpenAiChoice(data);
+    if (!choice)
+        return 'continue';
+    return handleOpenAiChoiceDelta(state, choice, onEvent) === 'break' ? 'contaminated' : 'continue';
+}
+/**
+ * Runs exactly one OpenAI-compatible (Chat Completions JSON wire format)
+ * streaming HTTP request and reduces its SSE events into a single outcome.
+ * Extracted so this SSE-reduction loop has exactly one implementation
+ * shared by every OpenAI-compatible provider turn-runner in this package:
+ * `runOpenAiToolTurn` itself (below), plus `azure-chat.ts#runAzureToolTurn`
+ * and `ollama-chat.ts#runOllamaToolTurn` — both target byte-identical
+ * chat-completions JSON, differing only in URL and auth. Callers own their
+ * own base-URL SSRF validation (`validateBaseUrl`) and URL/header/body
+ * construction *before* calling this function — it only knows how to run
+ * *a* request against whatever URL/headers/body it is handed, and has no
+ * opinion on any provider's defaults. Mirrors
+ * `anthropic-messages.ts#runSingleAnthropicRequest`'s `emitEnd` contract —
+ * see that function's doc.
+ */
+export async function runOpenAiCompatibleRequest(init) {
+    const { onEvent, hasEnded } = init;
+    const fetchOutcome = await requestOpenAiCompatibleStream(init);
+    if (fetchOutcome.type === 'ended') {
         return { finishReason: null, toolCalls: [], text: '' };
     }
+    if (fetchOutcome.type === 'retry') {
+        return runOpenAiCompatibleRequest(fetchOutcome.retryInit);
+    }
     onEvent({ type: 'status', label: 'requesting' });
-    const guard = createRoleMarkerGuard(init.guardMessageId);
-    const toolCalls = new Map();
-    let fullText = '';
-    let finishReason = null;
-    let usage = null;
-    for await (const frame of decodeSseStream(response.body)) {
+    const state = {
+        guard: createRoleMarkerGuard(init.guardMessageId),
+        toolCalls: new Map(),
+        fullText: '',
+        finishReason: null,
+        usage: null,
+    };
+    for await (const frame of decodeSseStream(fetchOutcome.body)) {
         // No `hasEnded()` re-check at the top of this loop: the only in-loop call to `emitEnd`
         // (contamination, below) is immediately followed by `break`, and every other call site is a
-        // pre-loop early `return` — traced across all five call sites in this function, same proof as
+        // pre-loop early `return` — traced across all five call sites in this function and
+        // `requestOpenAiCompatibleStream`, same proof as
         // `anthropic-messages.ts#runSingleAnthropicRequest`. `hasEnded()` is still consulted once,
         // after this loop, to decide whether pending tool_use events should still be emitted (a
         // contaminating delta can arrive on a *later* chunk than the one that set `finish_reason`).
-        if (frame.data === DONE_SENTINEL)
+        const result = processOpenAiStreamFrame(state, frame, onEvent);
+        if (result === 'done')
+            break;
+        if (result === 'contaminated') {
+            init.emitEnd('contaminated');
             break;
-        let data;
-        try {
-            data = JSON.parse(frame.data);
-        }
-        catch {
-            continue; // tolerate a malformed/empty keep-alive frame
-        }
-        if (!isRecord(data))
-            continue;
-        if (isRecord(data.usage)) {
-            usage = data.usage;
-            onEvent({ type: 'usage', usage });
-        }
-        const choices = Array.isArray(data.choices) ? data.choices : [];
-        const choice = choices[0];
-        if (!isRecord(choice))
-            continue;
-        if (typeof choice.finish_reason === 'string') {
-            finishReason = choice.finish_reason;
-        }
-        const delta = isRecord(choice.delta) ? choice.delta : null;
-        if (!delta)
-            continue;
-        if (typeof delta.content === 'string' && delta.content.length > 0) {
-            // No `guard.contaminated` pre-check here: the only way it becomes true is the
-            // `emitEnd('contaminated'); break;` a few lines below, which exits this loop immediately —
-            // see `anthropic-messages.ts#runSingleAnthropicRequest`'s identical reachability proof.
-            const safe = guard.feedText(delta.content);
-            if (safe.length > 0) {
-                fullText += safe;
-                onEvent({ type: 'text_delta', delta: safe });
-            }
-            if (guard.contaminated) {
-                const warn = guard.warningEvent();
-                if (warn)
-                    onEvent(warn);
-                emitEnd('contaminated');
-                break;
-            }
-        }
-        if (Array.isArray(delta.tool_calls)) {
-            for (const rawCall of delta.tool_calls) {
-                if (!isRecord(rawCall) || typeof rawCall.index !== 'number')
-                    continue;
-                let pending = toolCalls.get(rawCall.index);
-                if (!pending) {
-                    const id = typeof rawCall.id === 'string' ? rawCall.id : `call_${rawCall.index}`;
-                    const fn = isRecord(rawCall.function) ? rawCall.function : {};
-                    const name = typeof fn.name === 'string' ? fn.name : '';
-                    pending = { id, name, argsJson: '' };
-                    toolCalls.set(rawCall.index, pending);
-                }
-                const fn = isRecord(rawCall.function) ? rawCall.function : null;
-                if (fn && typeof fn.arguments === 'string') {
-                    pending.argsJson += fn.arguments;
-                }
-            }
         }
     }
-    const resolvedToolCalls = Array.from(toolCalls.values()).map((call) => {
-        let input = {};
-        if (call.argsJson.trim()) {
-            try {
-                input = JSON.parse(call.argsJson);
-            }
-            catch {
-                input = {};
-            }
-        }
-        return { id: call.id, name: call.name, input };
-    });
-    if (finishReason === 'tool_calls' && !hasEnded()) {
-        for (const call of resolvedToolCalls) {
-            onEvent({ type: 'tool_use', id: call.id, name: call.name, input: call.input });
-        }
+    const resolvedToolCalls = resolveOpenAiToolCalls(state.toolCalls);
+    if (state.finishReason === 'tool_calls' && !hasEnded()) {
+        emitPendingOpenAiToolUseEvents(resolvedToolCalls, onEvent);
     }
-    return { finishReason, toolCalls: resolvedToolCalls, text: fullText };
+    return { finishReason: state.finishReason, toolCalls: resolvedToolCalls, text: state.fullText };
 }
 /** Validates `options.baseUrl`, then delegates to {@link runOpenAiCompatibleRequest} with OpenAI's own URL/header/body builders. Thin wrapper kept so `runOpenAiToolTurn`'s per-iteration call site stays unchanged by the extraction. */
 async function runSingleOpenAiRequest(options, messages, emitEnd, hasEnded) {
-    const baseUrlCheck = validateBaseUrl(options.baseUrl ?? DEFAULT_OPENAI_BASE_URL);
+    // DNS-resolving, not merely textual: the synchronous check only inspects the literal hostname,
+    // so `https://internal.example.com -> 10.0.0.5` passed it and this runner connected to private
+    // infrastructure on behalf of whoever supplied `baseUrl`. Matches what the Azure, Google and
+    // Ollama runners in this directory already did.
+    const baseUrlCheck = await validateBaseUrlResolved(options.baseUrl ?? DEFAULT_OPENAI_BASE_URL, options.dnsLookup ?? defaultDnsLookup);
     if (baseUrlCheck.error) {
         options.onEvent({ type: 'error', message: baseUrlCheck.error });
         emitEnd('error');
@@ -240,7 +360,9 @@ async function runSingleOpenAiRequest(options, messages, emitEnd, hasEnded) {
         url: openAiRequestUrl(options.baseUrl),
         headers: openAiHeaders(options),
         body: openAiRequestBody(options, messages),
+        ...(baseUrlCheck.pinnedAddress ? { pinnedAddress: baseUrlCheck.pinnedAddress } : {}),
         ...(options.signal ? { signal: options.signal } : {}),
+        ...(options.fetchImpl ? { fetchImpl: options.fetchImpl } : {}),
         redactSecretsList: [options.apiKey],
         guardMessageId: 'openai-turn',
         providerLabel: 'OpenAI',
@@ -249,6 +371,140 @@ async function runSingleOpenAiRequest(options, messages, emitEnd, hasEnded) {
         hasEnded,
     });
 }
+const OPENAI_ALLOWED_IMAGE_MEDIA_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif']);
+/**
+ * OpenAI documents a 512 MB total-payload cap and a 1500-image-per-request cap for the Chat
+ * Completions API (see module doc's "Image support" section) but no single-image byte limit. This
+ * module still bounds one image's base64 length defensively, matching
+ * `anthropic-messages.ts`'s posture — 20 MB is this module's own conservative choice (not an
+ * OpenAI-documented per-image number), anchored to Gemini's documented 20 MB total-inline-request
+ * budget (`google-messages.ts`) as the closest real, vendor-documented single-request inline-image
+ * bound available across this package's providers. Approximated from the base64 *string* length,
+ * not decoded byte count — see `anthropic-messages.ts#MAX_IMAGE_BASE64_CHARS`'s doc for why that's
+ * the right thing to measure (O(1), no decode step, negligible rounding slack at this size).
+ */
+const MAX_IMAGE_DATA_URI_BASE64_CHARS = Math.ceil((20 * 1024 * 1024 * 4) / 3);
+/** OpenAI's documented per-request image count cap (see module doc). Applied per tool-result content array as a conservative simplification — a real request can also carry images from earlier turns this module doesn't track. */
+const MAX_IMAGES_PER_OPENAI_TOOL_RESULT = 1500;
+const OPENAI_DATA_URI_PATTERN = /^data:([^;,]+)(?:;charset=[^;,]+)?;base64,(.+)$/su;
+/**
+ * Validates one content part against OpenAI's real format/size constraints. Returns the violation
+ * reason, or `null` when the part is legal to send.
+ *
+ * A plain `https://` `image_url` (not a `data:` URI) is intentionally not size-checked: OpenAI's
+ * servers fetch that URL, not this adapter, so there is no local payload to bound — same threat-
+ * model split as `anthropic-messages.ts`'s URL-sourced skip (`connection-guard.ts`'s SSRF guard
+ * protects this adapter's own outbound `baseUrl` request, a different thing; an `image_url` that
+ * points at attacker-chosen infrastructure is a request OpenAI's own servers make, not this one).
+ *
+ * @complexity O(1) — reads `data.length`, never decodes or parses the base64 payload.
+ */
+export function invalidOpenAiContentPartReason(part) {
+    if (part.type === 'text')
+        return null;
+    const dataUriMatch = OPENAI_DATA_URI_PATTERN.exec(part.image_url.url);
+    if (!dataUriMatch)
+        return null;
+    const [, mediaType, base64Data] = dataUriMatch;
+    if (!mediaType || !OPENAI_ALLOWED_IMAGE_MEDIA_TYPES.has(mediaType.toLowerCase())) {
+        return `unsupported image media type ${JSON.stringify(mediaType)} (OpenAI's Chat Completions API supports image/jpeg, image/png, image/webp, and non-animated image/gif)`;
+    }
+    if (base64Data && base64Data.length > MAX_IMAGE_DATA_URI_BASE64_CHARS) {
+        return `image exceeds this adapter's 20 MB base64 size guard (${base64Data.length} base64 chars)`;
+    }
+    return null;
+}
+/**
+ * Runtime guard applied to every `OpenAiToolExecutor` result before it is wired onto the outbound
+ * request or reported via `onEvent`. `OpenAiToolResult` is host-owned (see `OpenAiToolExecutor`'s
+ * "Host-owned tool execution" doc comment) — the TS content-part union only constrains a
+ * well-behaved host at compile time, not a buggy one at runtime, e.g. a screenshot helper that
+ * hands back an oversized PNG or a HEIC file mislabeled as `image/jpeg`. Rather than forwarding an
+ * invalid part and letting OpenAI reject the *entire* turn with an opaque upstream 400, this
+ * substitutes a plain-text `isError: true` result the model can see and react to — matching this
+ * package's existing security-conscious posture (`connection-guard.ts`'s SSRF guard,
+ * `role-marker-guard.ts`'s contamination guard, and `anthropic-messages.ts`'s identical guard).
+ *
+ * @complexity O(n) in the number of content parts; O(1) per part (see `invalidOpenAiContentPartReason`).
+ */
+export function sanitizeOpenAiToolResult(result) {
+    if (typeof result.content === 'string')
+        return { content: result.content, isError: false };
+    if (result.content.length > MAX_IMAGES_PER_OPENAI_TOOL_RESULT) {
+        return { content: `tool result rejected: exceeds the ${MAX_IMAGES_PER_OPENAI_TOOL_RESULT}-image-per-request guard (${result.content.length} parts)`, isError: true };
+    }
+    for (const part of result.content) {
+        const reason = invalidOpenAiContentPartReason(part);
+        if (reason)
+            return { content: `tool result rejected: ${reason}`, isError: true };
+    }
+    return { content: result.content, isError: false };
+}
+/**
+ * Splits one (already-sanitized) tool result's content into what can legally sit on the wire
+ * `role: 'tool'` message (text only — see module doc's "Tool messages cannot carry an image"
+ * section) and the `image_url` parts that must instead travel on a follow-up `user` message.
+ *
+ * A string `content` is left untouched (`imageParts: []`) — this is the pre-existing, unchanged
+ * path every current caller already exercises. For an array, text parts are kept in order for the
+ * `tool` message; if there is no text at all (an image-only result), a single placeholder text part
+ * is substituted so the `tool` message's content is never empty (OpenAI rejects empty content).
+ *
+ * @complexity O(n) in the number of content parts.
+ */
+export function splitOpenAiToolResultContent(content) {
+    if (typeof content === 'string')
+        return { toolMessageContent: content, imageParts: [] };
+    const textParts = content.filter((part) => part.type === 'text');
+    const imageParts = content.filter((part) => part.type === 'image_url');
+    const toolMessageContent = textParts.length > 0 ? textParts : [{ type: 'text', text: '(tool result included only non-text content; see the following message)' }];
+    return { toolMessageContent, imageParts };
+}
+/**
+ * Decides why the tool loop should stop after one request, or returns `null` when it should
+ * instead proceed to execute the pending tool calls — mirrors
+ * `anthropic-messages.ts#anthropicLoopExitReason`'s pure decision/effect split.
+ */
+export function openAiLoopExitReason(outcome, toolTurns, maxToolTurns) {
+    if (outcome.finishReason !== 'tool_calls' || outcome.toolCalls.length === 0)
+        return 'stop';
+    if (toolTurns >= maxToolTurns)
+        return 'max_tool_turns';
+    return null;
+}
+/**
+ * Runs every pending tool call in order, sanitizing and splitting each result into its `tool`
+ * message plus any labeled image parts for the batch's single follow-up `user` message — see
+ * module doc's "Tool messages cannot carry an image" section for why the split exists and why the
+ * follow-up is assembled once per batch rather than per call.
+ */
+export async function executeOpenAiToolCalls(executeTool, calls, onEvent) {
+    const toolResultMessages = [];
+    const followUpParts = [];
+    for (const call of calls) {
+        const result = await executeTool(call);
+        const sanitized = sanitizeOpenAiToolResult(result);
+        onEvent({ type: 'tool_result', toolUseId: call.id, content: sanitized.content, isError: sanitized.isError });
+        const split = splitOpenAiToolResultContent(sanitized.content);
+        toolResultMessages.push({ role: 'tool', content: split.toolMessageContent, tool_call_id: call.id });
+        if (split.imageParts.length > 0) {
+            // Attribution label — without it, the model cannot tell this image apart from a human
+            // having just pasted one into the conversation (see module doc). Named per-call so a batch
+            // with multiple image-bearing tool calls stays disambiguated in one follow-up message.
+            followUpParts.push({ type: 'text', text: `Image output from tool \`${call.name}\` (tool_call_id: ${call.id}):` });
+            followUpParts.push(...split.imageParts);
+        }
+    }
+    return { toolResultMessages, followUpParts };
+}
+/** Builds the assistant turn that records the model's pending tool calls in `messages` history — `content` falls back to `null` (never `''`) per the wire schema. */
+export function buildOpenAiAssistantToolCallMessage(text, toolCalls) {
+    return { role: 'assistant', content: text || null, tool_calls: toolCalls };
+}
+/** Appends the batch's `tool` messages plus, when present, the single labeled-image follow-up message — see module doc's "Tool messages cannot carry an image" section for why the follow-up is at most one message per batch. */
+export function buildOpenAiToolExchangeMessages(toolResultMessages, followUpParts) {
+    return [...toolResultMessages, ...(followUpParts.length > 0 ? [{ role: 'user', content: followUpParts }] : [])];
+}
 /**
  * Runs a full OpenAI Chat Completions turn, including the tool-execution
  * loop when `options.executeTool` is supplied and the model requests a
@@ -257,6 +513,7 @@ async function runSingleOpenAiRequest(options, messages, emitEnd, hasEnded) {
  */
 export async function runOpenAiToolTurn(options) {
     const maxToolTurns = options.maxToolTurns ?? DEFAULT_MAX_TOOL_TURNS;
+    const executeTool = options.executeTool;
     const endGuard = createTurnEndGuard(options.onEvent, (reason) => ({ type: 'end', reason }));
     const emitEnd = endGuard.emitEnd;
     let messages = options.messages.slice();
@@ -267,34 +524,26 @@ export async function runOpenAiToolTurn(options) {
         lastFinishReason = outcome.finishReason;
         if (endGuard.hasEnded())
             break;
-        if (outcome.finishReason !== 'tool_calls' || outcome.toolCalls.length === 0) {
-            emitEnd('stop');
+        const exitReason = openAiLoopExitReason(outcome, toolTurns, maxToolTurns);
+        if (exitReason) {
+            emitEnd(exitReason);
             break;
         }
-        if (!options.executeTool) {
+        if (!executeTool) {
             emitEnd('stop');
             break;
         }
-        if (toolTurns >= maxToolTurns) {
-            emitEnd('max_tool_turns');
-            break;
-        }
         toolTurns += 1;
         const assistantToolCalls = outcome.toolCalls.map((call) => ({
             id: call.id,
             type: 'function',
             function: { name: call.name, arguments: JSON.stringify(call.input) },
         }));
-        const toolResultMessages = [];
-        for (const call of outcome.toolCalls) {
-            const result = await options.executeTool(call);
-            options.onEvent({ type: 'tool_result', toolUseId: call.id, content: result.content, isError: false });
-            toolResultMessages.push({ role: 'tool', content: result.content, tool_call_id: call.id });
-        }
+        const { toolResultMessages, followUpParts } = await executeOpenAiToolCalls(executeTool, outcome.toolCalls, options.onEvent);
         messages = [
             ...messages,
-            { role: 'assistant', content: outcome.text || null, tool_calls: assistantToolCalls },
-            ...toolResultMessages,
+            buildOpenAiAssistantToolCallMessage(outcome.text, assistantToolCalls),
+            ...buildOpenAiToolExchangeMessages(toolResultMessages, followUpParts),
         ];
     }
     return { finishReason: lastFinishReason, toolTurns };