@framers/agentos 0.10.24 → 0.10.25

package/dist/core/llm/providers/implementations/OpenAIProvider.js

@@ -3,7 +3,7 @@ import { stripForeignVendorParams } from '../openrouter-only-params.js';
 import { resolveOpenAiCacheRetentionParams, resolvePromptCacheKey } from '../openai-cache-params.js';
 import { OpenAIProviderError } from '../errors/OpenAIProviderError.js';
 import { ApiKeyPool } from '../../../providers/ApiKeyPool.js';
-import { toOpenAiResponseFormat } from './openai-response-format-guard.js';
+import { toOpenAiResponseFormat, toOpenAiResponsesTextFormat } from './openai-response-format-guard.js';
 import { clampMaxOutputTokens } from '../model-output-limits.js';
 import { mapEffortToOpenAiReasoningEffort, mapEffortToOpenAiReasoningEffortForModel, mapEffortToOpenAiResponsesEffort } from '../model-effort.js';
 import { computeRetryBackoffMs } from './retry-backoff.js';
@@ -115,27 +115,54 @@ export function openAiHasLongContextPricing(modelId) {
 /**
  * Whether OpenAI serves `modelId` only through the Responses API. OpenAI lists
  * the `-pro` tiers, the codex models, `gpt-5.6-cyber` and the deep-research
- * models as Responses-only. OpenAIProvider sends a request to /v1/responses
- * only when it is a non-streamed GPT-5 or GPT-6 call carrying function tools
- * and an effort, and to /v1/chat/completions otherwise, where these ids fail.
+ * models as Responses-only; on /v1/chat/completions they fail (gpt-5.3-codex
+ * answers 404). OpenAIProvider sends every call to these ids to /v1/responses
+ * (see {@link openAiRequiresResponsesApi}).
+ *
+ * Only OpenAI's own families (`gpt-`, the o-series, `codex-`) qualify. Groq,
+ * xAI, Together and Mistral delegate to this class with their own model ids,
+ * and an id such as `grok-4-pro` on one of those endpoints is served by its
+ * Chat Completions route.
  *
  * @param modelId Provider-side model identifier.
  * @returns `true` when the model has no Chat Completions endpoint.
  */
 export function isOpenAIResponsesOnlyModel(modelId) {
-    return /-pro(-\d{4}-\d{2}-\d{2})?$|codex|^gpt-5\.6-cyber|deep-research/i.test(modelId);
+    return /^(gpt-|o\d|codex-)/i.test(modelId)
+        && /-pro(-\d{4}-\d{2}-\d{2})?$|codex|^gpt-5\.6-cyber|deep-research/i.test(modelId);
+}
+/**
+ * Whether a call to `modelId` can be served only by `/v1/responses`:
+ *
+ *   - any call to a Responses-only model ({@link isOpenAIResponsesOnlyModel});
+ *   - a GPT-6 call carrying function tools. Chat Completions does not serve
+ *     it: `gpt-6-astra` rejects tool calls there with or without a
+ *     `reasoning_effort` (probed 2026-09-10 and 2026-09-30), the `gpt-6.1-sol` model page lists
+ *     tool calling on Responses only, and the `gpt-6-sol` / `gpt-6-luna`
+ *     pages allow chat tool calls only with `reasoning_effort: 'none'`. A
+ *     2026-09-30 probe of a GPT-6 tool call with no `reasoning_effort` on
+ *     /v1/chat/completions returned HTTP 400.
+ *
+ * {@link shouldRouteToOpenAiResponsesApi} applies this rule to streamed and
+ * non-streamed calls alike.
+ *
+ * @param modelId Provider-side model identifier.
+ * @param options The request's tools.
+ * @returns `true` when the call has no Chat Completions route.
+ */
+export function openAiRequiresResponsesApi(modelId, options) {
+    return (isOpenAIResponsesOnlyModel(modelId) ||
+        (/^gpt-6/i.test(modelId) && requestHasFunctionTools(options.tools)));
 }
 /**
  * ModelInfo capabilities for a GPT-5, GPT-6 or o-series id, limited to what
  * OpenAIProvider can serve.
  *
  *   - Responses-only models ({@link isOpenAIResponsesOnlyModel}) list as
- *     `chat` only. This provider reaches them only on its narrow Responses
- *     path, and the refresh leaves the Responses-only o-series ids out.
- *   - GPT-6 omits `tool_use`. OpenAI requires the Responses API for GPT-6
- *     Astra tool calls and `reasoning_effort: "none"` for Sol and Luna tool
- *     calls on Chat Completions, and this provider routes a tool call to
- *     Responses only when it carries an effort and is not streamed.
+ *     `chat` only. Tool and streaming support vary from model to model on
+ *     that tier, and the refresh leaves the Responses-only o-series ids out.
+ *   - GPT-6 lists `tool_use`: every GPT-6 tool call, streamed or not, goes to
+ *     `/v1/responses` ({@link openAiRequiresResponsesApi}).
  *   - `o1-mini` and `o1-preview` have no function calling or structured
  *     outputs. They and `o3-mini` take text only, and every other id takes
  *     images (per model input modalities, checked 2026-09-29).
@@ -147,9 +174,7 @@ export function openAiReasoningCapabilities(modelId) {
     const id = modelId.toLowerCase();
     if (isOpenAIResponsesOnlyModel(id) || /^o1-(mini|preview)/.test(id))
         return ['chat'];
-    const caps = ['chat', 'json_mode'];
-    if (!/^gpt-6/.test(id))
-        caps.push('tool_use');
+    const caps = ['chat', 'json_mode', 'tool_use'];
     if (!/^o3-mini/.test(id))
         caps.push('vision_input');
     return caps;
@@ -183,32 +208,30 @@ export function isOpenAIReasoningModel(modelId) {
     return /^(o\d|gpt-5|gpt-6)/i.test(modelId);
 }
 /**
- * Whether OpenAI rejects `reasoning_effort` sent ALONGSIDE function tools on
- * the `/v1/chat/completions` endpoint for `modelId`. The GPT-5 family enforces
- * this — "Function tools with reasoning_effort are not supported for gpt-5.5
- * in /v1/chat/completions. Please use /v1/responses instead." (live-observed
- * 2026-07-08 when the codegen frontier fallback chain routed a tool-carrying,
- * effort:xhigh orchestrator turn to gpt-5.5, hard-erroring the whole build).
+ * Whether OpenAI rejects `reasoning_effort` sent alongside function tools on
+ * the `/v1/chat/completions` endpoint for `modelId`. The GPT-5 family does:
+ * "Function tools with reasoning_effort are not supported for gpt-5.5 in
+ * /v1/chat/completions. Please use /v1/responses instead." (live-observed
+ * 2026-07-08, when the codegen frontier fallback chain sent a tool-carrying,
+ * effort:xhigh orchestrator turn to gpt-5.5 and the whole build failed).
  *
- * Such a call is routed to `/v1/responses` when it qualifies (see
- * {@link shouldRouteToOpenAiResponsesApi}, which preserves BOTH effort and
- * tools); otherwise it stays on chat/completions and must DROP
- * `reasoning_effort` (the model then reasons at its default depth) rather than
- * 400 the entire request. Scoped to the GPT-5 and GPT-6 families: the o-series
- * (o1/o3/o4) still accepts `reasoning_effort` + tools on chat/completions, so
- * dropping it there would be a needless reasoning-depth regression. Widen this
- * predicate if a future o-series enforces the same Responses-API requirement.
+ * GPT-6 does as well. Live-probed 2026-09-10 (chat.completions,
+ * `gpt-6-astra`, `reasoning_effort: 'xhigh'` and one function tool): HTTP 400
+ * `invalid_request_error`, "Function tools with reasoning_effort are not
+ * supported for gpt-6-astra in /v1/chat/completions. To use function tools,
+ * use /v1/responses or set reasoning_effort to 'none'." The 2026-09-30 probe
+ * found that `gpt-6-sol` and `gpt-6-luna` accept `'none'` there while
+ * `gpt-6-astra` rejects it, and that a GPT-6 tool call with no
+ * `reasoning_effort` also returns 400, so every GPT-6 tool call goes to
+ * `/v1/responses` ({@link openAiRequiresResponsesApi}).
  *
- * GPT-6 enforces the SAME restriction — live-probed 2026-09-10
- * (chat.completions, `gpt-6-astra`, `reasoning_effort: 'xhigh'` + one function
- * tool): HTTP 400 `invalid_request_error` — "Function tools with
- * reasoning_effort are not supported for gpt-6-astra in /v1/chat/completions.
- * To use function tools, use /v1/responses or set reasoning_effort to 'none'."
- * The suggested `'none'` escape hatch does NOT exist on this family: the same
- * probe with `reasoning_effort: 'none'` returns HTTP 400 `unsupported_value`
- * ("Supported values are: 'low', 'medium', 'high', and 'xhigh'"). Dropping the
- * param entirely (or routing to `/v1/responses`) is therefore the only viable
- * path, which is exactly what the two call sites below already do.
+ * {@link shouldRouteToOpenAiResponsesApi} sends a GPT-5 tool call that
+ * carries an effort to `/v1/responses`, which keeps both the effort and the
+ * tools. A call whose message content Responses cannot carry stays on
+ * chat/completions, where the chat builder drops `reasoning_effort` so the
+ * call succeeds at the model's default depth. The o-series (o1/o3/o4) accepts
+ * `reasoning_effort` with tools on chat/completions, so it stays outside this
+ * predicate; widen it if a future o-series model enforces the same rule.
  *
  * @param modelId Provider-side model identifier (e.g. `'gpt-5.5'`, `'gpt-6-astra'`).
  */
@@ -275,35 +298,196 @@ export function flattenResponsesTextContent(content) {
         return '';
     return content.filter(isTextPart).map((p) => p.text).join('\n');
 }
+/** Whether one content part is an image URL block, which `/v1/responses` takes as `input_image`. */
+function isImageUrlPart(part) {
+    if (part == null || typeof part !== 'object')
+        return false;
+    const p = part;
+    return (p.type === 'image_url' &&
+        p.image_url != null &&
+        typeof p.image_url === 'object' &&
+        typeof p.image_url.url === 'string');
+}
 /**
- * Whether a NON-streaming call must use `/v1/responses` instead of
- * `/v1/chat/completions`: a gpt-5/gpt-6 reasoning model carrying function tools
- * AND a requested effort — the ONLY combination chat/completions 400s on
- * ("Function tools with reasoning_effort are not supported … Please use
- * /v1/responses instead") and the only case where the Responses path buys
- * anything (preserved reasoning depth). Excludes, per the 2026-07-08 Codex
- * review, requests that carry a `responseFormat` (the Responses path maps no
- * structured output — those stay on chat/completions where R4 drops effort) or
- * message content the input mapper cannot carry (see
- * {@link isResponsesMappableContent}). Every excluded case stays on
- * chat/completions; R4's effort-drop remains the defense-in-depth floor there.
+ * Whether the `/v1/responses` builder can carry message `m` without losing
+ * content. Text-only content ({@link isResponsesMappableContent}) maps on
+ * every role. User and tool messages may also carry image parts: a user turn
+ * sends them as `input_image`, and a tool result becomes a
+ * `function_call_output` whose output is an `input_text` / `input_image`
+ * array (the form OpenAI's function-calling reference gives for it). Any other
+ * part, such as audio, a file or an Anthropic `tool_result` block, has no
+ * mapping.
  *
- * Content gating is delegated to {@link isResponsesMappableContent} rather
- * than tested inline. It previously required EVERY message's content to be a
- * plain string, which silently excluded Anthropic-style cache-marked system
- * blocks (`systemBlocks` / `SystemContentBlock[]`, which reach the provider as
- * an all-text content array). Callers that set `systemBlocks` to fix a cold
- * prompt cache therefore lost Responses routing and hard-400ed on
- * chat/completions — the exact failure this router exists to prevent. All-text
- * arrays now route and are flattened losslessly; true multimodal content is
- * still excluded, because the mapper still cannot represent it.
+ * @param m A request message.
+ * @returns `true` when the message maps onto Responses input losslessly.
+ */
+export function isResponsesMappableMessage(m) {
+    if (isResponsesMappableContent(m.content))
+        return true;
+    return ((m.role === 'user' || m.role === 'tool') &&
+        Array.isArray(m.content) &&
+        m.content.every((part) => isTextPart(part) || isImageUrlPart(part)));
+}
+/**
+ * The `/v1/responses` form of a user or tool message's content. Text-only
+ * content stays the flattened string {@link flattenResponsesTextContent}
+ * builds; content with images becomes `input_text` and `input_image` parts.
+ * Every image carries a `detail`, `'auto'` (the API's default) when the source
+ * part set none. Callers gate on {@link isResponsesMappableMessage} first.
+ */
+function toResponsesInputContent(content) {
+    if (!Array.isArray(content) || isResponsesMappableContent(content)) {
+        return flattenResponsesTextContent(content);
+    }
+    return content.map((part) => isImageUrlPart(part)
+        ? { type: 'input_image', image_url: part.image_url.url, detail: part.image_url.detail ?? 'auto' }
+        : { type: 'input_text', text: isTextPart(part) ? part.text : '' });
+}
+/**
+ * Whether a call goes to `/v1/responses` instead of `/v1/chat/completions`.
+ * Streamed and non-streamed calls follow this one rule.
+ *
+ *   - Every call {@link openAiRequiresResponsesApi} names: Responses-only
+ *     models and GPT-6 tool calls.
+ *   - A GPT-5 or GPT-6 call that carries function tools and an effort, when
+ *     every message maps ({@link isResponsesMappableMessage}). Chat
+ *     Completions rejects `reasoning_effort` alongside function tools for
+ *     these families ("Function tools with reasoning_effort are not supported
+ *     ... Please use /v1/responses instead"); Responses keeps both, and a
+ *     `responseFormat` travels as `text.format`.
+ *
+ * Content gating goes through {@link isResponsesMappableMessage}, which
+ * accepts Anthropic-style cache-marked system blocks (`systemBlocks` reach the
+ * provider as an all-text content array) and flattens them without loss. A
+ * GPT-5 tool call whose content does not map stays on chat/completions, where
+ * the chat builder drops the effort (see
+ * {@link openAiRejectsReasoningEffortWithTools}).
+ *
+ * @param modelId Provider-side model identifier.
+ * @param messages The request messages.
+ * @param options The request's tools, effort and response format.
+ * @returns `true` when the call goes to `/v1/responses`.
  */
 export function shouldRouteToOpenAiResponsesApi(modelId, messages, options) {
+    if (openAiRequiresResponsesApi(modelId, options))
+        return true;
     return (openAiRejectsReasoningEffortWithTools(modelId) &&
         requestHasFunctionTools(options.tools) &&
         mapEffortToOpenAiReasoningEffort(options.effort) !== undefined &&
-        options.responseFormat === undefined &&
-        messages.every((m) => isResponsesMappableContent(m.content)));
+        messages.every(isResponsesMappableMessage));
+}
+/**
+ * Reads a `/v1/responses` `output` array: assistant text from the
+ * `output_text` parts of message items and tool calls from `function_call`
+ * items (`call_id` becomes the call id). Reasoning and other item types count
+ * toward `itemCount` only.
+ */
+function summarizeResponsesOutput(output) {
+    const items = output ?? [];
+    let text = '';
+    const toolCalls = [];
+    for (const item of items) {
+        if (item.type === 'message') {
+            for (const part of item.content ?? []) {
+                if (part.type === 'output_text' && typeof part.text === 'string')
+                    text += part.text;
+            }
+        }
+        else if (item.type === 'function_call') {
+            toolCalls.push({
+                id: item.call_id ?? '',
+                type: 'function',
+                function: { name: item.name ?? '', arguments: item.arguments ?? '' },
+            });
+        }
+    }
+    return { text, toolCalls, itemCount: items.length };
+}
+/**
+ * HTTP-equivalent statuses of the `/v1/responses` error codes that mean the
+ * request may succeed later or elsewhere. A stream that fails with one of them
+ * before any output throws with this status, so the fallback walker treats it
+ * like the HTTP error a failed request returns.
+ */
+const RESPONSES_RETRYABLE_ERROR_STATUS = {
+    server_error: 500,
+    rate_limit_exceeded: 429,
+    vector_store_timeout: 504,
+};
+/** The HTTP-equivalent status of a `/v1/responses` error code, when it is a retryable one. */
+function responsesErrorStatus(code) {
+    return typeof code === 'string' ? RESPONSES_RETRYABLE_ERROR_STATUS[code] : undefined;
+}
+/**
+ * The chat-style finish reason of a `/v1/responses` result, shared by the
+ * streamed and non-streamed mappings. An incomplete response reports why it
+ * stopped, as Chat Completions does, even when it holds a function call (the
+ * call may be cut off): `length` when the output budget ran out and
+ * `content_filter` when a filter stopped it. Otherwise `tool_calls` when the
+ * turn called tools, else `stop`.
+ */
+function responsesFinishReason(status, incompleteReason, hasToolCalls) {
+    if (status === 'incomplete') {
+        if (incompleteReason === 'max_output_tokens' || incompleteReason === 'max_tokens')
+            return 'length';
+        if (incompleteReason === 'content_filter')
+            return 'content_filter';
+    }
+    return hasToolCalls ? 'tool_calls' : 'stop';
+}
+/**
+ * Brings a streamed call in line with its authoritative form (the item on
+ * `response.output_item.done`, the text on
+ * `response.function_call_arguments.done`, or the call in the terminal
+ * response) and returns the delta that carries the difference, or
+ * `undefined` when the emitted deltas already match.
+ *
+ * Argument deltas only append, so when the authoritative arguments extend
+ * the streamed text the missing suffix goes out as `arguments_delta`, and a
+ * consumer that rebuilds calls from deltas (StreamingReconstructor) ends with
+ * the same arguments as the final chunk. Arguments that do not extend the
+ * streamed text cannot be corrected by appending; they are kept in
+ * `finalArguments` for the final chunk and logged.
+ *
+ * @param call The streamed call, updated in place.
+ * @param authoritative The call's final id, name and arguments; absent
+ *   fields are left as streamed.
+ * @returns The correcting delta, or `undefined`.
+ */
+function reconcileStreamedCall(call, authoritative) {
+    const delta = { index: call.index };
+    const fn = {};
+    let changed = false;
+    if (authoritative.id && authoritative.id !== call.id) {
+        call.id = authoritative.id;
+        delta.id = authoritative.id;
+        delta.type = 'function';
+        changed = true;
+    }
+    if (authoritative.name && authoritative.name !== call.name) {
+        call.name = authoritative.name;
+        fn.name = authoritative.name;
+        changed = true;
+    }
+    const args = authoritative.arguments;
+    if (typeof args === 'string' && args !== call.arguments) {
+        if (args.startsWith(call.arguments)) {
+            fn.arguments_delta = args.slice(call.arguments.length);
+            call.arguments = args;
+            call.finalArguments = undefined;
+            changed = true;
+        }
+        else if (call.finalArguments !== args) {
+            call.finalArguments = args;
+            console.warn(`OpenAIProvider: streamed arguments for tool call ${call.id || `#${call.index}`} ` +
+                'do not match the final function_call item; the final chunk carries the final arguments.');
+        }
+    }
+    if (!changed)
+        return undefined;
+    if (fn.name !== undefined || fn.arguments_delta !== undefined)
+        delta.function = fn;
+    return delta;
 }
 export class OpenAIProvider {
     /**
@@ -596,9 +780,9 @@ export class OpenAIProvider {
     async generateCompletion(modelId, messages, options) {
         this.ensureInitialized();
         const apiKey = await this.getApiKey(options.apiKeyOverride);
-        // GPT-5 rejects `reasoning_effort` + function tools on /chat/completions
-        // and demands /v1/responses. Route ONLY that exact case there (preserving
-        // BOTH reasoning depth and tools); everything else keeps the chat path.
+        // Responses-only models, GPT-6 tool calls and GPT-5/6 tool calls that
+        // carry an effort go to /v1/responses; every other call takes the chat
+        // path. generateCompletionStream applies the same rule.
         if (shouldRouteToOpenAiResponsesApi(modelId, messages, options)) {
             const responsesBody = this.buildResponsesPayload(modelId, messages, options);
             const responsesApiResponse = await this.makeApiRequest('/responses', 'POST', apiKey, responsesBody, false, options.requestTimeout);
@@ -611,61 +795,373 @@ export class OpenAIProvider {
     /** @inheritdoc */
     async *generateCompletionStream(modelId, messages, options) {
         this.ensureInitialized();
-        const apiKey = await this.getApiKey(options.apiKeyOverride);
-        const requestBody = this.buildChatCompletionPayload(modelId, messages, options, true);
-        const stream = (await this.makeApiRequest('/chat/completions', 'POST', apiKey, requestBody, true, // Indicate streaming response is expected
-        options.requestTimeout));
-        // Accumulators for streaming tool calls
-        const accumulatedToolCalls = new Map();
         const abortSignal = options.abortSignal;
+        // Checked before any network work, so an aborted call never reaches the
+        // OAuth token fetch or the POST.
         if (abortSignal?.aborted) {
-            yield {
-                id: `openai-abort-${Date.now()}`,
-                object: 'chat.completion.chunk',
-                created: Math.floor(Date.now() / 1000),
-                modelId,
-                choices: [],
-                error: { message: 'Stream aborted prior to first chunk', type: 'abort' },
-                isFinal: true,
-            };
+            yield this.abortedStreamChunk(modelId, 'Stream aborted prior to first chunk');
             return;
         }
-        const abortHandler = () => {
-            // Emit final abort chunk and ensure generator completes.
-            // We cannot directly cancel the underlying ReadableStream cleanly cross-platform here; consumer side will stop.
-            // Provide a terminal chunk for consistent teardown.
-            // Note: We don't attempt to read further chunks after abort.
-        };
-        abortSignal?.addEventListener('abort', abortHandler, { once: true });
-        for await (const chunk of this.parseSseStream(stream)) {
+        const apiKey = await this.getApiKey(options.apiKeyOverride);
+        // The routing rule generateCompletion uses, so a streamed call reaches the
+        // same endpoint with the same effort as its non-streamed twin.
+        const viaResponses = shouldRouteToOpenAiResponsesApi(modelId, messages, options);
+        const endpoint = viaResponses ? '/responses' : '/chat/completions';
+        const requestBody = viaResponses
+            ? this.buildResponsesPayload(modelId, messages, options, true)
+            : this.buildChatCompletionPayload(modelId, messages, options, true);
+        let stream;
+        try {
+            stream = await this.makeApiRequest(endpoint, 'POST', apiKey, requestBody, true, options.requestTimeout, abortSignal);
+        }
+        catch (error) {
+            // An abort during the request surfaces as the abort chunk, not a throw.
             if (abortSignal?.aborted) {
-                yield {
-                    id: `openai-abort-${Date.now()}`,
-                    object: 'chat.completion.chunk',
-                    created: Math.floor(Date.now() / 1000),
-                    modelId,
-                    choices: [],
-                    error: { message: 'Stream aborted by caller', type: 'abort' },
-                    isFinal: true,
-                };
+                yield this.abortedStreamChunk(modelId, 'Stream aborted by caller');
+                return;
+            }
+            throw error;
+        }
+        if (viaResponses) {
+            yield* this.mapResponsesStream(stream, modelId, abortSignal);
+            return;
+        }
+        yield* this.mapChatStream(stream, modelId, abortSignal);
+    }
+    /**
+     * The terminal chunk a stream yields when the caller's signal aborts it.
+     * @private
+     */
+    abortedStreamChunk(modelId, message) {
+        return {
+            id: `openai-abort-${Date.now()}`,
+            object: 'chat.completion.chunk',
+            created: Math.floor(Date.now() / 1000),
+            modelId,
+            choices: [],
+            error: { message, type: 'abort' },
+            isFinal: true,
+        };
+    }
+    /**
+     * Maps a `/v1/chat/completions` SSE stream onto
+     * {@link ModelCompletionResponse} chunks, accumulating streamed tool calls
+     * by index. A caller abort ends the stream with the abort chunk.
+     * @private
+     */
+    async *mapChatStream(stream, modelId, abortSignal) {
+        const accumulatedToolCalls = new Map();
+        for await (const data of this.parseSseStream(stream, abortSignal)) {
+            if (abortSignal?.aborted)
                 break;
+            // OpenAI ends the stream with [DONE]; the finish and usage chunks come before it.
+            if (data === '[DONE]')
+                return;
+            let mapped;
+            try {
+                const apiChunk = JSON.parse(data);
+                mapped = this.mapApiToStreamChunkResponse(apiChunk, accumulatedToolCalls);
+            }
+            catch (error) {
+                console.warn('OpenAIProvider: Failed to parse stream chunk JSON:', data, error);
+                continue;
             }
-            if (chunk === '[DONE]') {
-                // The [DONE] message is a signal for the end of the stream from OpenAI.
-                // A final response chunk with isFinal=true and potential usage should be yielded by the parser if data exists.
-                // If OpenAI includes usage in the last data chunk before [DONE], parseSseStream handles it.
+            yield mapped;
+        }
+        if (abortSignal?.aborted) {
+            yield this.abortedStreamChunk(modelId, 'Stream aborted by caller');
+        }
+    }
+    /**
+     * Maps a `/v1/responses` SSE stream onto the {@link ModelCompletionResponse}
+     * chunks the chat stream produces.
+     *
+     *   - `response.output_text.delta` yields a text chunk.
+     *   - A `function_call` item yields a tool-call delta with its id and name
+     *     (`response.output_item.added`), then its argument fragments
+     *     (`response.function_call_arguments.delta`). Tool-call indexes are
+     *     dense in order of appearance, so a reasoning item ahead of the calls
+     *     leaves no gap.
+     *   - The item's final form (`response.function_call_arguments.done`,
+     *     `response.output_item.done`) and the terminal response are
+     *     authoritative. Text, a call id or name, or an argument suffix that the
+     *     deltas did not carry goes out as one more delta, exactly once, before
+     *     the final chunk. A consumer that rebuilds the turn from deltas
+     *     (StreamingReconstructor) and one that reads the final chunk
+     *     (streamText, GMI) therefore see the same text and calls, including
+     *     when a proxy strips the delta events.
+     *   - `response.completed` and `response.incomplete` yield exactly one final
+     *     chunk with the finish reason, tool calls and usage.
+     *   - Before any text or tool call has gone out, `response.failed`, an
+     *     `error` event, and a body that ends or fails to read before a terminal
+     *     event throw an {@link OpenAIProviderError}, as a failed HTTP request
+     *     does: the status of a retryable error code
+     *     ({@link RESPONSES_RETRYABLE_ERROR_STATUS}) or `NETWORK_ERROR` for the
+     *     cut-off or failed body, and a failed response's billed usage in
+     *     `details.usage`. Callers can then fail over and meter the attempt.
+     *   - After output, those failures and a caller abort each yield one final
+     *     chunk carrying an error instead, so the partial answer stays with the
+     *     caller.
+     *
+     * Reasoning summaries, content-part events and refusals carry nothing this
+     * mapping surfaces and are skipped.
+     * @private
+     */
+    async *mapResponsesStream(stream, modelId, abortSignal) {
+        let responseId = `openai-resp-${Date.now()}`;
+        let created = Math.floor(Date.now() / 1000);
+        let responseModel = modelId;
+        let emittedText = '';
+        const calls = [];
+        const callByOutputIndex = new Map();
+        const callByItemId = new Map();
+        // Whether any text or tool call has gone out to the caller.
+        const deliveredOutput = () => emittedText.length > 0 || calls.length > 0;
+        // A read that failed mid-body (a dropped connection) ends the event loop
+        // like a body cut off before its terminal event.
+        const reading = {};
+        const noteResponse = (response) => {
+            if (!response)
                 return;
+            if (typeof response.id === 'string' && response.id)
+                responseId = response.id;
+            if (typeof response.created_at === 'number')
+                created = response.created_at;
+            if (typeof response.model === 'string' && response.model)
+                responseModel = response.model;
+        };
+        const chunk = (fields) => ({
+            id: responseId,
+            object: 'chat.completion.chunk',
+            created,
+            modelId: responseModel,
+            choices: [{ index: 0, message: { role: 'assistant', content: null }, finishReason: null }],
+            ...fields,
+        });
+        const textChunk = (delta) => chunk({
+            choices: [{ index: 0, message: { role: 'assistant', content: delta }, finishReason: null }],
+            responseTextDelta: delta,
+        });
+        // Finds the call an event names, by call id first, then output position,
+        // then item id, and starts a new one when none matches.
+        const trackCall = (outputIndex, itemId, callId) => {
+            let call = (callId ? calls.find((c) => c.id === callId) : undefined) ??
+                (outputIndex !== undefined ? callByOutputIndex.get(outputIndex) : undefined) ??
+                (itemId ? callByItemId.get(itemId) : undefined);
+            if (!call) {
+                call = { index: calls.length, id: '', name: '', arguments: '' };
+                calls.push(call);
             }
+            if (outputIndex !== undefined)
+                callByOutputIndex.set(outputIndex, call);
+            if (itemId)
+                callByItemId.set(itemId, call);
+            return call;
+        };
+        for await (const data of this.readResponsesSse(stream, abortSignal, reading)) {
+            if (abortSignal?.aborted)
+                break;
+            // /v1/responses sends no [DONE]; treat one as the end of the body.
+            if (data === '[DONE]')
+                break;
+            let event;
             try {
-                const apiChunk = JSON.parse(chunk);
-                yield this.mapApiToStreamChunkResponse(apiChunk, accumulatedToolCalls);
+                event = JSON.parse(data);
             }
             catch (error) {
-                console.warn('OpenAIProvider: Failed to parse stream chunk JSON:', chunk, error);
-                // Decide if to yield an error chunk or continue if minor parsing issue
+                console.warn('OpenAIProvider: Failed to parse /responses stream event JSON:', data, error);
+                continue;
+            }
+            switch (event.type) {
+                case 'response.created':
+                case 'response.in_progress':
+                    noteResponse(event.response);
+                    break;
+                case 'response.output_text.delta':
+                    if (typeof event.delta === 'string' && event.delta) {
+                        emittedText += event.delta;
+                        yield textChunk(event.delta);
+                    }
+                    break;
+                case 'response.output_item.added':
+                case 'response.output_item.done': {
+                    const item = event.item;
+                    if (item?.type !== 'function_call')
+                        break;
+                    const call = trackCall(event.output_index, item.id, item.call_id);
+                    const delta = reconcileStreamedCall(call, {
+                        id: item.call_id,
+                        name: item.name,
+                        // An added item's arguments are normally '' and carry nothing yet.
+                        arguments: event.type === 'response.output_item.done' ? item.arguments : item.arguments || undefined,
+                    });
+                    if (delta)
+                        yield chunk({ toolCallsDeltas: [delta] });
+                    break;
+                }
+                case 'response.function_call_arguments.delta': {
+                    if (typeof event.delta !== 'string' || !event.delta)
+                        break;
+                    const call = trackCall(event.output_index, event.item_id);
+                    if (call.finalArguments !== undefined)
+                        break;
+                    call.arguments += event.delta;
+                    yield chunk({ toolCallsDeltas: [{ index: call.index, function: { arguments_delta: event.delta } }] });
+                    break;
+                }
+                case 'response.function_call_arguments.done': {
+                    if (typeof event.arguments !== 'string')
+                        break;
+                    const delta = reconcileStreamedCall(trackCall(event.output_index, event.item_id), {
+                        arguments: event.arguments,
+                    });
+                    if (delta)
+                        yield chunk({ toolCallsDeltas: [delta] });
+                    break;
+                }
+                case 'response.completed':
+                case 'response.incomplete': {
+                    const response = event.response;
+                    noteResponse(response);
+                    const output = response?.output ?? [];
+                    const summary = summarizeResponsesOutput(output);
+                    // The terminal output is authoritative: send whatever the deltas left out.
+                    const corrections = [];
+                    output.forEach((item, outputIndex) => {
+                        if (item.type !== 'function_call')
+                            return;
+                        const delta = reconcileStreamedCall(trackCall(outputIndex, item.id, item.call_id), {
+                            id: item.call_id,
+                            name: item.name,
+                            arguments: item.arguments,
+                        });
+                        if (delta)
+                            corrections.push(delta);
+                    });
+                    let missingText = '';
+                    if (summary.text && summary.text !== emittedText) {
+                        if (summary.text.startsWith(emittedText)) {
+                            missingText = summary.text.slice(emittedText.length);
+                        }
+                        else {
+                            console.warn('OpenAIProvider: streamed /responses text does not match the final output; keeping the streamed text.');
+                        }
+                    }
+                    if (missingText || corrections.length > 0) {
+                        emittedText += missingText;
+                        const correction = missingText ? textChunk(missingText) : chunk({});
+                        if (corrections.length > 0)
+                            correction.toolCallsDeltas = corrections;
+                        yield correction;
+                    }
+                    const usage = response?.usage
+                        ? this.mapResponsesUsage(response.usage, response.model ?? modelId)
+                        : undefined;
+                    const status = response?.status ?? (event.type === 'response.incomplete' ? 'incomplete' : 'completed');
+                    if (summary.itemCount === 0 && emittedText.length === 0 && calls.length === 0) {
+                        // Nothing streamed and nothing in the output: the malformed body
+                        // the non-streamed mapping throws INVALID_RESPONSE for.
+                        yield chunk({
+                            choices: [],
+                            error: {
+                                message: `OpenAI /responses returned no usable output (status: ${status})`,
+                                type: 'invalid_response',
+                            },
+                            ...(usage ? { usage } : {}),
+                            isFinal: true,
+                        });
+                        return;
+                    }
+                    const toolCalls = calls
+                        .filter((c) => c.id && c.name)
+                        .map((c) => ({
+                        id: c.id,
+                        type: 'function',
+                        function: { name: c.name, arguments: c.finalArguments ?? c.arguments },
+                    }));
+                    const finishReason = responsesFinishReason(status, response?.incomplete_details?.reason, toolCalls.length > 0);
+                    if (emittedText.length === 0 && toolCalls.length === 0) {
+                        this.warnReasoningOnlyOutput(response ?? { id: responseId, status }, modelId, finishReason);
+                    }
+                    yield chunk({
+                        ...(typeof response?.service_tier === 'string' ? { serviceTier: response.service_tier } : {}),
+                        choices: [{
+                                index: 0,
+                                message: {
+                                    role: 'assistant',
+                                    content: null,
+                                    tool_calls: toolCalls.length > 0 ? toolCalls : undefined,
+                                },
+                                finishReason,
+                                logprobs: null,
+                            }],
+                        usage,
+                        isFinal: true,
+                    });
+                    return;
+                }
+                case 'response.failed': {
+                    const response = event.response;
+                    noteResponse(response);
+                    const message = response?.error?.message ?? 'OpenAI /responses reported the response as failed';
+                    const usage = response?.usage ? this.mapResponsesUsage(response.usage, response.model ?? modelId) : undefined;
+                    if (!deliveredOutput()) {
+                        throw new OpenAIProviderError(message, 'RESPONSES_FAILED', response?.error?.code ?? undefined, 'response_failed', responsesErrorStatus(response?.error?.code), { error: response?.error, ...(usage ? { usage } : {}) });
+                    }
+                    yield chunk({
+                        choices: [],
+                        error: {
+                            message,
+                            type: 'response_failed',
+                            ...(response?.error?.code ? { code: response.error.code } : {}),
+                            ...(response?.error ? { details: response.error } : {}),
+                        },
+                        ...(usage ? { usage } : {}),
+                        isFinal: true,
+                    });
+                    return;
+                }
+                case 'error': {
+                    const message = event.message ?? 'OpenAI /responses stream error';
+                    if (!deliveredOutput()) {
+                        throw new OpenAIProviderError(message, 'RESPONSES_STREAM_ERROR', event.code ?? undefined, 'stream_error', responsesErrorStatus(event.code));
+                    }
+                    yield chunk({
+                        choices: [],
+                        error: {
+                            message,
+                            type: 'stream_error',
+                            ...(event.code ? { code: event.code } : {}),
+                        },
+                        isFinal: true,
+                    });
+                    return;
+                }
+                default:
+                    // Reasoning summaries, content parts, output_text.done, refusals.
+                    break;
             }
         }
-        abortSignal?.removeEventListener('abort', abortHandler);
+        if (abortSignal?.aborted) {
+            yield this.abortedStreamChunk(modelId, 'Stream aborted by caller');
+            return;
+        }
+        const endMessage = reading.failure
+            ? `OpenAI /responses stream failed before response.completed: ${reading.failure.message}`
+            : 'OpenAI /responses stream ended before response.completed';
+        if (!deliveredOutput()) {
+            // A connection cut before anything arrived, which a retry or another
+            // provider can serve.
+            throw new OpenAIProviderError(endMessage, 'NETWORK_ERROR', undefined, 'stream_truncated', undefined, reading.failure);
+        }
+        yield chunk({
+            choices: [],
+            error: {
+                message: endMessage,
+                type: 'stream_truncated',
+            },
+            isFinal: true,
+        });
     }
     /** @inheritdoc */
     async generateEmbeddings(modelId, texts, options) {
@@ -787,15 +1283,16 @@ export class OpenAIProvider {
                 payload.top_p = options.topP;
         }
         else {
-            // Reasoning models (o-series, GPT-5) take `reasoning_effort`
+            // Reasoning models (o-series, GPT-5, GPT-6) take `reasoning_effort`
             // (none|low|medium|high|xhigh) in place of the sampling params they
-            // reject. Map the agentos effort scale onto it so `effort: 'max'` actually
-            // drives gpt-5.x at its xhigh ceiling instead of being silently dropped.
-            // customModelParams (below) can still override.
-            // GPT-5 rejects `reasoning_effort` + function tools on chat/completions
-            // (it demands the Responses API, which agentos doesn't implement). When
-            // the request carries tools, DROP the effort param instead of 400ing —
-            // the model reasons at its default depth and the tool call succeeds.
+            // reject. Map the agentos effort scale onto it so `effort: 'max'` drives
+            // them at their xhigh ceiling. customModelParams (below) can still
+            // override.
+            // GPT-5 and GPT-6 reject `reasoning_effort` with function tools on
+            // chat/completions. shouldRouteToOpenAiResponsesApi sends those calls to
+            // /v1/responses; one that still arrives here (its content cannot go to
+            // Responses) drops the effort, so the model reasons at its default
+            // depth and the tool call succeeds.
             const reasoningEffort = mapEffortToOpenAiReasoningEffortForModel(options.effort, modelId);
             const dropEffortForTools = requestHasFunctionTools(options.tools) &&
                 openAiRejectsReasoningEffortWithTools(modelId);
@@ -909,28 +1406,54 @@ export class OpenAIProvider {
             payload.service_tier = options.serviceTier;
     }
     /**
-     * Build a `/v1/responses` request body for a gpt-5/gpt-6 reasoning +
-     * function-tool call (the only case
-     * {@link shouldRouteToOpenAiResponsesApi} routes here).
-     * Preserves BOTH `reasoning.effort` and `tools`, which chat/completions
-     * rejects together. No structured output by construction (the router
-     * excludes responseFormat). Message content arrives as either a plain
-     * string or an all-text block array — {@link flattenResponsesTextContent}
-     * joins the latter, so cache-marked `systemBlocks` survive intact instead of
-     * collapsing to an empty prompt. True multimodal content never reaches here
-     * (the router excludes it via {@link isResponsesMappableContent}).
+     * Build a `/v1/responses` request body for a call
+     * {@link shouldRouteToOpenAiResponsesApi} sends there: a Responses-only
+     * model, a GPT-6 tool call, or a GPT-5/GPT-6 tool call that carries an
+     * effort.
+     *
+     *   - System, assistant and text-only turns carry flattened text
+     *     ({@link flattenResponsesTextContent}), so cache-marked `systemBlocks`
+     *     arrive joined instead of empty. A user turn with images carries
+     *     `input_text` / `input_image` parts, and a tool result with images
+     *     becomes a `function_call_output` whose output is that part array.
+     *   - `tools`, `reasoning` and `text.format` appear only when the call has
+     *     function tools, an effort the model maps, or an OpenAI-shaped
+     *     `responseFormat`. `stream: true` marks a streamed call; Responses has
+     *     no `stream_options.include_usage` and reports usage on the terminal
+     *     event.
+     *   - A chat-style `reasoning_effort` in `customModelParams` moves to
+     *     `reasoning.effort`, because Responses rejects the top-level key.
+     *
      * Live-probed 2026-07-08; block-content path live-probed 2026-09-12.
+     *
+     * @throws {OpenAIProviderError} `RESPONSES_UNMAPPABLE_CONTENT` when a
+     *   message carries a part Responses cannot represent (audio, a file, an
+     *   Anthropic `tool_result` block). Only a call with no Chat Completions
+     *   route reaches here with such content; the error is not retryable, like
+     *   the 400 or 404 Chat Completions would return for it.
      * @private
      */
-    buildResponsesPayload(modelId, messages, options) {
+    buildResponsesPayload(modelId, messages, options, stream = false) {
+        const unmappable = messages.find((m) => !isResponsesMappableMessage(m));
+        if (unmappable) {
+            const partTypes = Array.isArray(unmappable.content)
+                ? Array.from(new Set(unmappable.content.map((part) => String(part?.type))))
+                : [typeof unmappable.content];
+            throw new OpenAIProviderError(`OpenAI serves ${modelId} for this call only on /v1/responses, which cannot carry a ` +
+                `'${unmappable.role}' message with content parts [${partTypes.join(', ')}]`, 'RESPONSES_UNMAPPABLE_CONTENT');
+        }
         const input = [];
         for (const m of messages) {
-            const text = flattenResponsesTextContent(m.content);
             if (m.role === 'tool') {
                 // Tool result → function_call_output paired by call_id.
-                input.push({ type: 'function_call_output', call_id: m.tool_call_id, output: text });
+                input.push({ type: 'function_call_output', call_id: m.tool_call_id, output: toResponsesInputContent(m.content) });
+                continue;
+            }
+            if (m.role === 'user') {
+                input.push({ role: 'user', content: toResponsesInputContent(m.content) });
                 continue;
             }
+            const text = flattenResponsesTextContent(m.content);
             if (m.role === 'assistant' && m.tool_calls && m.tool_calls.length > 0) {
                 // Optional assistant text first, then one function_call item per call.
                 if (text.length > 0)
@@ -945,19 +1468,25 @@ export class OpenAIProvider {
                 }
                 continue;
             }
-            // system / user / plain assistant. Drop an empty assistant turn (no text,
-            // no tool_calls carries nothing); keep empty system/user defensively.
+            // system / plain assistant. Drop an empty assistant turn (no text, no
+            // tool_calls carries nothing); keep an empty system turn defensively.
             if (m.role === 'assistant' && text.length === 0)
                 continue;
             input.push({ role: m.role, content: text });
         }
-        const payload = {
-            model: modelId,
-            input,
-            tools: this.toResponsesTools(options.tools),
-            reasoning: { effort: mapEffortToOpenAiResponsesEffort(modelId, options.effort) },
-            store: false,
-        };
+        const payload = { model: modelId, input, store: false };
+        // A Responses-only model can be called without tools, and a
+        // `reasoning: {}` or `tools: undefined` key has no meaning on the wire.
+        if (requestHasFunctionTools(options.tools))
+            payload.tools = this.toResponsesTools(options.tools);
+        const effort = mapEffortToOpenAiResponsesEffort(modelId, options.effort);
+        if (effort !== undefined)
+            payload.reasoning = { effort };
+        const textFormat = toOpenAiResponsesTextFormat(options.responseFormat);
+        if (textFormat)
+            payload.text = { format: textFormat };
+        if (stream)
+            payload.stream = true;
         if (options.toolChoice !== undefined) {
             payload.tool_choice = this.toResponsesToolChoice(options.toolChoice);
         }
@@ -981,6 +1510,60 @@ export class OpenAIProvider {
                 Object.assign(payload, passthrough);
             }
         }
+        // customModelParams is shared with the chat path, whose effort key is the
+        // top-level `reasoning_effort`. Responses rejects that key and takes the
+        // value as `reasoning.effort`, so move it there.
+        if ('reasoning_effort' in payload) {
+            const passedEffort = payload.reasoning_effort;
+            delete payload.reasoning_effort;
+            if (passedEffort !== undefined && passedEffort !== null) {
+                const reasoning = payload.reasoning && typeof payload.reasoning === 'object'
+                    ? payload.reasoning
+                    : {};
+                payload.reasoning = { ...reasoning, effort: passedEffort };
+            }
+        }
+        // The chat path's output limits (`max_completion_tokens`, `max_tokens`)
+        // are `max_output_tokens` here; Responses rejects the chat names. An
+        // explicit `max_output_tokens` in customModelParams wins.
+        for (const chatLimit of ['max_completion_tokens', 'max_tokens']) {
+            if (!(chatLimit in payload))
+                continue;
+            const limit = payload[chatLimit];
+            delete payload[chatLimit];
+            const passedOutputLimit = options.customModelParams?.max_output_tokens;
+            if (typeof limit === 'number' && passedOutputLimit === undefined) {
+                payload.max_output_tokens = limit;
+            }
+        }
+        // Chat-only stream settings have no Responses counterpart.
+        delete payload.stream_options;
+        // Other chat-shaped overrides, reshaped because Responses rejects them as
+        // written for /chat/completions: a named-function `tool_choice` (its name
+        // sits under `function`), chat-style function `tools`, `response_format`
+        // (Responses reads `text.format`) and a top-level `verbosity` (Responses
+        // reads `text.verbosity`). Values already in the Responses shape pass
+        // through unchanged.
+        if (payload.tool_choice !== undefined)
+            payload.tool_choice = this.toResponsesToolChoice(payload.tool_choice);
+        if (payload.tools !== undefined)
+            payload.tools = this.toResponsesTools(payload.tools);
+        if ('response_format' in payload || 'verbosity' in payload) {
+            const text = payload.text && typeof payload.text === 'object' ? { ...payload.text } : {};
+            if ('response_format' in payload) {
+                const format = toOpenAiResponsesTextFormat(payload.response_format);
+                if (format)
+                    text.format = format;
+                delete payload.response_format;
+            }
+            if ('verbosity' in payload) {
+                if (payload.verbosity !== undefined && payload.verbosity !== null)
+                    text.verbosity = payload.verbosity;
+                delete payload.verbosity;
+            }
+            if (Object.keys(text).length > 0)
+                payload.text = text;
+        }
         return payload;
     }
     /** Reshape chat-completions function tools → the Responses flat tool shape. */
@@ -994,8 +1577,13 @@ export class OpenAIProvider {
                     type: 'function',
                     name: tool.function.name,
                     description: tool.function.description,
-                    parameters: tool.function.parameters,
-                    strict: false,
+                    // Responses requires `parameters` on a function tool, so an
+                    // argument-less tool gets the empty object schema.
+                    parameters: tool.function.parameters ?? { type: 'object', properties: {} },
+                    // A caller's explicit `strict` is kept. Otherwise false: strict mode
+                    // needs a schema most tools do not have (every property required,
+                    // no additional properties).
+                    strict: tool.function.strict ?? false,
                 };
             }
             return t; // already-flat or non-function tool: pass through
@@ -1009,6 +1597,28 @@ export class OpenAIProvider {
         if (tc?.type === 'function' && tc.function?.name) {
             return { type: 'function', name: tc.function.name };
         }
+        // Chat nests an allowed-tools choice under `allowed_tools`, with
+        // `{type:'function', function:{name}}` entries; Responses takes `mode` and
+        // `tools` at the top level, with flat function names.
+        if (tc?.type === 'allowed_tools' && tc.allowed_tools && typeof tc.allowed_tools === 'object') {
+            const { mode, tools } = tc.allowed_tools;
+            return {
+                type: 'allowed_tools',
+                ...(mode !== undefined ? { mode } : {}),
+                ...(tools !== undefined
+                    ? {
+                        tools: Array.isArray(tools)
+                            ? tools.map((entry) => {
+                                const tool = entry;
+                                return tool?.type === 'function' && tool.function?.name
+                                    ? { type: 'function', name: tool.function.name }
+                                    : entry;
+                            })
+                            : tools,
+                    }
+                    : {}),
+            };
+        }
         return toolChoice;
     }
     /**
@@ -1027,34 +1637,9 @@ export class OpenAIProvider {
      * @private
      */
     mapResponsesToCompletionResponse(apiResponse, modelId) {
-        const output = apiResponse.output ?? [];
-        let assistantText = '';
-        const toolCalls = [];
-        for (const item of output) {
-            if (item.type === 'message') {
-                for (const part of item.content ?? []) {
-                    if (part.type === 'output_text' && typeof part.text === 'string')
-                        assistantText += part.text;
-                }
-            }
-            else if (item.type === 'function_call') {
-                toolCalls.push({
-                    id: item.call_id ?? '',
-                    type: 'function',
-                    function: { name: item.name ?? '', arguments: item.arguments ?? '' },
-                });
-            }
-            // reasoning + any other item type: ignored.
-        }
-        const incompleteReason = apiResponse.incomplete_details?.reason;
-        const finishReason = toolCalls.length > 0
-            ? 'tool_calls'
-            : apiResponse.status === 'incomplete'
-                ? (incompleteReason === 'max_output_tokens' ? 'length'
-                    : incompleteReason === 'content_filter' ? 'content_filter'
-                        : 'stop')
-                : 'stop';
-        if (output.length === 0) {
+        const { text: assistantText, toolCalls, itemCount } = summarizeResponsesOutput(apiResponse.output);
+        const finishReason = responsesFinishReason(apiResponse.status, apiResponse.incomplete_details?.reason, toolCalls.length > 0);
+        if (itemCount === 0) {
             // GENUINELY empty 2xx — no output items at all. This is the malformed
             // body the guard was written for: throw so generateText's fallback
             // advances instead of treating it as a successful empty turn.
@@ -1069,17 +1654,7 @@ export class OpenAIProvider {
             throw new OpenAIProviderError(`OpenAI /responses returned no usable output (status: ${apiResponse.status ?? 'unknown'})`, 'INVALID_RESPONSE', undefined, undefined, undefined, apiResponse);
         }
         if (assistantText.length === 0 && toolCalls.length === 0) {
-            // Items present but no message/function_call — reasoning-only output.
-            // Surfaced as an empty turn carrying the real finishReason ('length'
-            // when max_output_tokens capped it), so the caller can retry with a
-            // larger budget. Reasoning tokens are drawn from the SAME output budget
-            // as the visible answer, so a reasoning model needs a materially larger
-            // maxTokens than a non-reasoning one to leave room for a reply.
-            console.warn(`OpenAIProvider: /responses returned reasoning-only output for ${apiResponse.model ?? modelId} ` +
-                `(status: ${apiResponse.status ?? 'unknown'}${incompleteReason ? `, reason: ${incompleteReason}` : ''}` +
-                `${apiResponse.usage?.output_tokens !== undefined ? `, output_tokens: ${apiResponse.usage.output_tokens}` : ''}` +
-                `) — returning an empty turn with finishReason '${finishReason}'. ` +
-                `Raise max output tokens: reasoning tokens consume the same budget as the reply.`);
+            this.warnReasoningOnlyOutput(apiResponse, modelId, finishReason);
         }
         return {
             id: apiResponse.id,
@@ -1098,22 +1673,50 @@ export class OpenAIProvider {
                     logprobs: null,
                 }],
             usage: apiResponse.usage
-                ? this.calculateUsage({
-                    prompt_tokens: apiResponse.usage.input_tokens,
-                    completion_tokens: apiResponse.usage.output_tokens,
-                    total_tokens: apiResponse.usage.total_tokens,
-                    // Responses API spells the cached detail input_tokens_details;
-                    // re-key to the chat spelling the shared mapper reads.
-                    ...(apiResponse.usage.input_tokens_details
-                        ? { prompt_tokens_details: {
-                                cached_tokens: apiResponse.usage.input_tokens_details.cached_tokens,
-                                cache_write_tokens: apiResponse.usage.input_tokens_details.cache_write_tokens,
-                            } }
-                        : {}),
-                }, apiResponse.model ?? modelId)
+                ? this.mapResponsesUsage(apiResponse.usage, apiResponse.model ?? modelId)
                 : undefined,
         };
     }
+    /**
+     * Logs a `/v1/responses` turn that holds output items but no message and
+     * no function call: reasoning-only output. It is returned as an empty turn
+     * carrying the real finish reason (`length` when max_output_tokens capped
+     * it), so the caller can retry with a larger budget. Reasoning tokens come
+     * out of the same output budget as the visible answer, so a reasoning model
+     * needs a materially larger maxTokens than a non-reasoning one to leave
+     * room for a reply.
+     * @private
+     */
+    warnReasoningOnlyOutput(apiResponse, modelId, finishReason) {
+        const incompleteReason = apiResponse.incomplete_details?.reason;
+        console.warn(`OpenAIProvider: /responses returned reasoning-only output for ${apiResponse.model ?? modelId} ` +
+            `(status: ${apiResponse.status ?? 'unknown'}${incompleteReason ? `, reason: ${incompleteReason}` : ''}` +
+            `${apiResponse.usage?.output_tokens !== undefined ? `, output_tokens: ${apiResponse.usage.output_tokens}` : ''}` +
+            `); returning an empty turn with finishReason '${finishReason}'. ` +
+            `Raise max output tokens: reasoning tokens consume the same budget as the reply.`);
+    }
+    /**
+     * Token usage and cost for a `/v1/responses` result. The Responses API
+     * spells the counts `input_tokens` / `output_tokens` and the cached detail
+     * `input_tokens_details`; they are re-keyed to the chat spelling so both
+     * endpoints meter through {@link calculateUsage}.
+     * @private
+     */
+    mapResponsesUsage(usage, modelId) {
+        return this.calculateUsage({
+            prompt_tokens: usage.input_tokens,
+            completion_tokens: usage.output_tokens,
+            total_tokens: usage.total_tokens,
+            ...(usage.input_tokens_details
+                ? {
+                    prompt_tokens_details: {
+                        cached_tokens: usage.input_tokens_details.cached_tokens,
+                        cache_write_tokens: usage.input_tokens_details.cache_write_tokens,
+                    },
+                }
+                : {}),
+        }, modelId);
+    }
     /**
      * Maps the raw OpenAI API Chat Completion response to the standard ModelCompletionResponse.
      * @private
@@ -1353,7 +1956,7 @@ export class OpenAIProvider {
         const outputRate = isLong ? pricing.output * OPENAI_LONG_CONTEXT_OUTPUT_MULTIPLIER : pricing.output;
         return (promptTokens / 1000) * inputRate + (completionTokens / 1000) * outputRate;
     }
-    async makeApiRequest(endpoint, method, apiKey, body, expectStream = false, requestTimeoutOverride) {
+    async makeApiRequest(endpoint, method, apiKey, body, expectStream = false, requestTimeoutOverride, abortSignal) {
         const url = `${this.config.baseURL}${endpoint}`;
         const headers = {
             'Authorization': `Bearer ${apiKey}`,
@@ -1368,6 +1971,9 @@ export class OpenAIProvider {
         }
         let lastError = new OpenAIProviderError('Request failed after all retries.', 'MAX_RETRIES_REACHED');
         for (let attempt = 0; attempt < this.config.maxRetries; attempt++) {
+            if (abortSignal?.aborted) {
+                throw new OpenAIProviderError('Request aborted by caller.', 'REQUEST_ABORTED');
+            }
             const controller = new AbortController();
             // CR8: honor a per-call requestTimeout override (e.g. long codegen) over
             // the provider's default; only Anthropic read this before.
@@ -1375,6 +1981,11 @@ export class OpenAIProvider {
                 ? requestTimeoutOverride
                 : this.config.requestTimeout;
             const timeoutId = setTimeout(() => controller.abort(), effectiveTimeout);
+            // The caller's signal aborts this attempt's fetch as the timer does. The
+            // listener is removed when the attempt settles; a returned stream body
+            // is cancelled by parseSseStream instead.
+            const abortAttempt = () => controller.abort();
+            abortSignal?.addEventListener('abort', abortAttempt, { once: true });
             try {
                 const requestOptions = {
                     method,
@@ -1420,6 +2031,10 @@ export class OpenAIProvider {
             }
             catch (error) {
                 clearTimeout(timeoutId);
+                // A caller abort ends the request here; it is not a timeout to retry.
+                if (abortSignal?.aborted) {
+                    throw new OpenAIProviderError('Request aborted by caller.', 'REQUEST_ABORTED');
+                }
                 if (error instanceof OpenAIProviderError) { // If already our custom error, re-throw if not retryable
                     if (error.code === 'API_CLIENT_ERROR')
                         throw error;
@@ -1445,6 +2060,9 @@ export class OpenAIProvider {
                 console.warn(`[LLM] Retry ${attempt + 1}/${this.config.maxRetries - 1} in ${(delay / 1000).toFixed(1)}s — ${shortMsg}`);
                 await new Promise(resolve => setTimeout(resolve, delay));
             }
+            finally {
+                abortSignal?.removeEventListener('abort', abortAttempt);
+            }
         }
         // For network errors, replace the cryptic cause chain with a clean message
         if (lastError instanceof OpenAIProviderError && lastError.code === 'NETWORK_ERROR') {
@@ -1453,17 +2071,44 @@ export class OpenAIProvider {
         throw lastError; // Throw the last encountered error after all retries
     }
     /**
-     * Parses an SSE (Server-Sent Events) stream.
+     * {@link parseSseStream} for the /v1/responses mapper: a read that fails
+     * mid-body (parseSseStream's `STREAM_PARSING_ERROR`) ends the stream and is
+     * recorded on `reading.failure` instead of propagating, so the mapper
+     * handles it like a body cut off before its terminal event.
+     * @private
+     */
+    async *readResponsesSse(stream, abortSignal, reading) {
+        try {
+            yield* this.parseSseStream(stream, abortSignal);
+        }
+        catch (error) {
+            if (error instanceof OpenAIProviderError && error.code === 'STREAM_PARSING_ERROR') {
+                reading.failure = error;
+                return;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Parses an SSE (Server-Sent Events) stream and yields each `data:` payload.
+     *
+     * When `abortSignal` fires, the reader is cancelled at once, which settles
+     * a read that is waiting on the network, and the generator ends without
+     * yielding more; the caller then emits its abort chunk.
      * @private
      */
-    async *parseSseStream(stream) {
+    async *parseSseStream(stream, abortSignal) {
         const reader = stream.getReader();
         const decoder = new TextDecoder();
         let buffer = '';
+        const cancelOnAbort = () => {
+            reader.cancel().catch(() => undefined);
+        };
+        abortSignal?.addEventListener('abort', cancelOnAbort, { once: true });
         try {
-            while (true) {
+            while (!abortSignal?.aborted) {
                 const { done, value } = await reader.read();
-                if (done)
+                if (done || abortSignal?.aborted)
                     break;
                 buffer += decoder.decode(value, { stream: true });
                 let eolIndex;
@@ -1483,25 +2128,42 @@ export class OpenAIProvider {
                     }
                 }
             }
-            // Process any remaining data in the buffer (e.g. if stream ends without \n\n)
-            if (buffer.startsWith('data: ')) {
-                const dataContent = buffer.substring('data: '.length).trim();
-                if (dataContent)
-                    yield dataContent;
-            }
-            else if (buffer.trim()) { // Sometimes final [DONE] might not be prefixed by "data: "
-                if (buffer.trim() === "[DONE]")
-                    yield "[DONE]";
-                else
-                    console.warn("OpenAIProvider: Trailing stream data not processed:", buffer);
+            if (abortSignal?.aborted)
+                return;
+            // A body that ends without the closing blank line leaves its last block
+            // in the buffer. Treat it as one block, so a terminal `event:` +
+            // `data:` pair (the /v1/responses framing) is read like any other.
+            buffer += decoder.decode();
+            const trailing = buffer.trim();
+            if (trailing) {
+                let sawData = false;
+                for (const line of buffer.split('\n')) {
+                    if (!line.startsWith('data: '))
+                        continue;
+                    sawData = true;
+                    const dataContent = line.substring('data: '.length).trim();
+                    if (dataContent)
+                        yield dataContent;
+                }
+                // Sometimes the final [DONE] is not prefixed by "data: ".
+                if (!sawData) {
+                    if (trailing === '[DONE]')
+                        yield '[DONE]';
+                    else
+                        console.warn('OpenAIProvider: Trailing stream data not processed:', buffer);
+                }
             }
         }
         catch (error) {
+            // A read that fails because the caller aborted is the abort, not a stream error.
+            if (abortSignal?.aborted)
+                return;
             const message = error instanceof Error ? error.message : 'Stream parsing error';
             console.error('OpenAIProvider: Error reading or parsing SSE stream:', message, error);
             throw new OpenAIProviderError(message, 'STREAM_PARSING_ERROR', undefined, undefined, undefined, error);
         }
         finally {
+            abortSignal?.removeEventListener('abort', cancelOnAbort);
             // Ensure stream is closed if `break` or `return` is called within the generator
             if (!reader.closed) {
                 await reader.cancel().catch(err => console.error("OpenAIProvider: Error cancelling stream reader:", err));