@plumbus/core 0.8.0-beta.0 → 0.8.0-beta.10

package/dist/ai/provider.js

@@ -2,13 +2,74 @@
 // Abstract interface for AI provider adapters (OpenAI, Anthropic, etc.)
 import { createRequire } from 'node:module';
 import { allKnownModels, estimateModelCost as calculateModelCost, } from './model-pricing.js';
+import { createOpenAIStrictOutputStreamUnwrapper, toOpenAIStrictOutputSchema, unwrapOpenAIStrictOutput, } from './openai-strict-schema.js';
 import { AIIncompleteOutputError, AIInvalidRequestError, AIRefusalError } from './refusal.js';
-/** Compose a request's optional user signal with a timeout, returning a single AbortSignal. */
-export function combineRequestSignals(userSignal, timeoutMs) {
-    const timeoutSignal = AbortSignal.timeout(timeoutMs);
-    if (!userSignal)
-        return timeoutSignal;
-    return AbortSignal.any([userSignal, timeoutSignal]);
+/**
+ * Resolve a `cache` option into per-section flags.
+ * `true` → `{ system: true, tools: true, messages: false }`.
+ * `false` / `undefined` / no section enabled → `undefined` (no provider marks).
+ */
+function resolvePromptCache(cache) {
+    if (cache === undefined || cache === false)
+        return undefined;
+    if (cache === true)
+        return { system: true, tools: true, messages: false };
+    const resolved = {
+        system: cache.system === true,
+        tools: cache.tools === true,
+        messages: cache.messages === true,
+    };
+    if (!resolved.system && !resolved.tools && !resolved.messages)
+        return undefined;
+    return resolved;
+}
+const ANTHROPIC_CACHE_CONTROL = Object.freeze({ type: 'ephemeral' });
+/** Attach Anthropic `cache_control` to the last content block of a message. */
+function withAnthropicMessageCacheControl(message) {
+    const content = message.content;
+    if (typeof content === 'string') {
+        return {
+            ...message,
+            content: [{ type: 'text', text: content, cache_control: { ...ANTHROPIC_CACHE_CONTROL } }],
+        };
+    }
+    if (!Array.isArray(content) || content.length === 0)
+        return message;
+    const blocks = content.map((block, index) => {
+        if (index !== content.length - 1 || block == null || typeof block !== 'object') {
+            return block;
+        }
+        return { ...block, cache_control: { ...ANTHROPIC_CACHE_CONTROL } };
+    });
+    return { ...message, content: blocks };
+}
+/** Apply Anthropic cache marks to a Messages API request body in place. */
+function applyAnthropicPromptCache(body, cache) {
+    if (cache.system && typeof body.system === 'string' && body.system.length > 0) {
+        body.system = [
+            {
+                type: 'text',
+                text: body.system,
+                cache_control: { ...ANTHROPIC_CACHE_CONTROL },
+            },
+        ];
+    }
+    if (cache.tools && Array.isArray(body.tools) && body.tools.length > 0) {
+        const tools = body.tools;
+        const lastIndex = tools.length - 1;
+        const last = tools[lastIndex];
+        if (last) {
+            tools[lastIndex] = { ...last, cache_control: { ...ANTHROPIC_CACHE_CONTROL } };
+        }
+    }
+    if (cache.messages && Array.isArray(body.messages) && body.messages.length > 0) {
+        const messages = body.messages;
+        const lastIndex = messages.length - 1;
+        const last = messages[lastIndex];
+        if (last) {
+            messages[lastIndex] = withAnthropicMessageCacheControl(last);
+        }
+    }
 }
 /**
  * Shared logic used by adapter `listModels` implementations: join a list of
@@ -20,6 +81,11 @@ function knownReasoningEfforts(provider, model) {
     if (provider !== 'openai')
         return null;
     const id = model.replace(/-\d{4}-\d{2}-\d{2}$/, '');
+    // https://developers.openai.com/api/docs/guides/latest-model and each model's page.
+    if (['gpt-6-sol', 'gpt-6-luna'].includes(id))
+        return ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
+    if (['gpt-6-astra', 'gpt-6.1-sol'].includes(id))
+        return ['low', 'medium', 'high', 'xhigh', 'max'];
     if (['gpt-5.6', 'gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna'].includes(id))
         return ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
     if (['gpt-5.2', 'gpt-5.4', 'gpt-5.5'].includes(id))
@@ -81,15 +147,28 @@ export class ProviderAPIError extends Error {
     statusCode;
     retryable;
     attempts;
+    /**
+     * Set when the request's own timeout ended it (`ProviderRequest.timeout`, a prompt's
+     * `model.timeoutMs`, or the adapter's `requestTimeout`): the limit that was reached, in
+     * milliseconds. Such a failure is not retryable — the provider may have billed the work, and
+     * asking again with the same limit usually ends the same way.
+     */
+    timeoutMs;
     constructor(args) {
-        super(args.message);
+        super(args.message, args.cause === undefined ? undefined : { cause: args.cause });
         this.name = 'ProviderAPIError';
         this.providerName = args.providerName;
         this.statusCode = args.statusCode;
         this.retryable = args.retryable;
         this.attempts = args.attempts;
+        if (args.timeoutMs !== undefined)
+            this.timeoutMs = args.timeoutMs;
     }
 }
+/**
+ * True for a provider HTTP failure from any adapter: a `ProviderAPIError` instance, or an error
+ * of the same shape built by an adapter package with its own copy of core (`@plumbus/ai-bedrock`).
+ */
 export function isProviderAPIError(value) {
     if (value instanceof ProviderAPIError)
         return true;
@@ -102,6 +181,14 @@ export function isProviderAPIError(value) {
         typeof candidate.retryable === 'boolean' &&
         typeof candidate.attempts === 'number');
 }
+/**
+ * True when the request's own timeout ended it (`timeoutMs` on the call, a prompt override, the
+ * prompt's `model.timeoutMs`, or the adapter's `requestTimeout`): a `ProviderAPIError` carrying
+ * the limit reached as `timeoutMs`. Not retryable; raise the timeout rather than asking again.
+ */
+export function isProviderTimeoutError(value) {
+    return isProviderAPIError(value) && typeof value.timeoutMs === 'number';
+}
 const retryableStatusCodes = new Set([408, 429, 500, 502, 503, 504]);
 const maxProviderAttempts = 3;
 const baseRetryDelayMs = 750;
@@ -128,6 +215,13 @@ function computeRetryDelayMs(attempt, retryAfterHeader) {
     }
     return Math.min(baseRetryDelayMs * 2 ** (attempt - 1), maxRetryDelayMs);
 }
+// Every OpenAI structured-output path is strict, and strict mode refuses optional properties:
+// each one goes out as required-but-nullable. The AI service drops the nulls again before the
+// prompt's Zod schema validates the answer (`restoreOmittedOptionalProperties`). String formats
+// strict mode does not support (`uri`) are left out of the sent schema, and `allOf` is merged
+// into one schema; Zod still checks the original. A root that is not an object (an array, a
+// union) goes inside a `{ "value": ... }` envelope that `unwrapOpenAIStructuredContent` (or, on a
+// stream, `unwrapOpenAIStructuredStream`) takes off the answer again.
 function buildOpenAIResponseFormat(request) {
     if (request.responseFormat !== 'json')
         return undefined;
@@ -138,27 +232,63 @@ function buildOpenAIResponseFormat(request) {
         json_schema: {
             name: 'response',
             strict: true,
-            schema: request.responseSchema,
+            schema: toOpenAIStrictOutputSchema(request.responseSchema).schema,
         },
     };
 }
+/** Whether the request's strict structured output went out inside the root envelope. */
+function hasOpenAIStructuredEnvelope(request) {
+    return (request.responseFormat === 'json' &&
+        !!request.responseSchema &&
+        toOpenAIStrictOutputSchema(request.responseSchema).enveloped);
+}
+/** The answer as the caller's schema describes it: out of the root envelope if it was sent in one. */
+function unwrapOpenAIStructuredContent(request, content) {
+    return hasOpenAIStructuredEnvelope(request) ? unwrapOpenAIStrictOutput(content) : content;
+}
+/** A Chat Completions stream with the root envelope taken out of its text deltas. */
+async function* unwrapOpenAIStructuredStream(events) {
+    const unwrapper = createOpenAIStrictOutputStreamUnwrapper();
+    let ended = false;
+    for await (const event of events) {
+        if (event.type === 'content_delta' && typeof event.delta === 'string') {
+            const delta = unwrapper.push(event.delta);
+            if (delta)
+                yield { ...event, delta };
+            continue;
+        }
+        if (event.type === 'done' && !ended) {
+            ended = true;
+            const rest = unwrapper.end();
+            if (rest)
+                yield { type: 'content_delta', delta: rest };
+        }
+        yield event;
+    }
+    if (!ended) {
+        const rest = unwrapper.end();
+        if (rest)
+            yield { type: 'content_delta', delta: rest };
+    }
+}
 const OPENAI_STRUCTURED_OUTPUT_TOOL_NAME = 'return_structured_response';
 function shouldUseOpenAIStructuredTool(args) {
     return (args.request.structuredOutputTransport === 'tool' &&
         args.request.responseFormat === 'json' &&
         !!args.request.responseSchema);
 }
-function buildOpenAIStructuredOutputTool(schema) {
+/** The structured-output function; Chat Completions nests it under `function`, Responses does not. */
+function openAIStructuredOutputFunction(schema) {
     return {
-        type: 'function',
-        function: {
-            name: OPENAI_STRUCTURED_OUTPUT_TOOL_NAME,
-            description: 'Return the complete structured response for this request.',
-            strict: true,
-            parameters: schema,
-        },
+        name: OPENAI_STRUCTURED_OUTPUT_TOOL_NAME,
+        description: 'Return the complete structured response for this request.',
+        strict: true,
+        parameters: toOpenAIStrictOutputSchema(schema).schema,
     };
 }
+function buildOpenAIStructuredOutputTool(schema) {
+    return { type: 'function', function: openAIStructuredOutputFunction(schema) };
+}
 function extractOpenAIMessageContent(message) {
     const structuredToolCall = message.tool_calls?.find((toolCall) => toolCall.function?.name === OPENAI_STRUCTURED_OUTPUT_TOOL_NAME);
     const toolArguments = structuredToolCall?.function?.arguments;
@@ -183,11 +313,16 @@ function buildEmptyOpenAIStructuredContentError(args) {
 }
 function openAIUsageToTokenUsage(usage) {
     const reasoning = usage.completion_tokens_details?.reasoning_tokens;
+    const cacheWrites = usage.prompt_tokens_details?.cache_write_tokens;
     return {
         inputTokens: usage.prompt_tokens,
         outputTokens: usage.completion_tokens,
         totalTokens: usage.total_tokens,
         cachedInputTokens: usage.prompt_tokens_details?.cached_tokens ?? 0,
+        // Prompt tokens written to the cache, counted inside `prompt_tokens` like cache reads. GPT-5.6
+        // and later bill them at 1.25× input (`estimateModelCost`); unread they were priced as
+        // ordinary input.
+        ...(typeof cacheWrites === 'number' ? { cacheWriteTokens: cacheWrites } : {}),
         // Reasoning models count their thinking inside `completion_tokens`. Without this split a
         // caller that hit `max_completion_tokens` cannot tell a long answer from a long deliberation,
         // and can only guess at which knob to turn.
@@ -196,19 +331,26 @@ function openAIUsageToTokenUsage(usage) {
 }
 function shouldUseOpenAIMaxCompletionTokens(model) {
     const normalizedModel = model.trim().toLowerCase();
-    return /^(?:o\d|o\d-|o\d\.)/.test(normalizedModel) || normalizedModel.startsWith('gpt-5');
+    return (/^(?:o\d|o\d-|o\d\.)/.test(normalizedModel) ||
+        normalizedModel.startsWith('gpt-5') ||
+        normalizedModel.startsWith('gpt-6'));
 }
 /**
- * `gpt-5.5+` only accept the API default temperature (1). Sending any other
- * value (including Plumbus's 0.7 default) returns HTTP 400 `unsupported_value`.
+ * `gpt-5.5+` only accept the API default temperature (1). GPT-6 accepts
+ * temperature only when reasoning is explicitly disabled. Sending any other
+ * value with active/default GPT-6 reasoning returns HTTP 400.
  *
  * Do not broaden this to all `gpt-5*` models — earlier lines such as
  * `gpt-5.4` / `gpt-5.4-mini` still support custom temperature. Token-limit
  * mapping (`max_completion_tokens`) remains a separate, wider check.
  */
-function shouldOmitOpenAITemperature(model) {
+function shouldOmitOpenAITemperature(model, request) {
     const normalizedModel = model.trim().toLowerCase();
-    return /^gpt-5\.(?:[5-9]|\d{2,})(?:$|[-.])/.test(normalizedModel);
+    if (/^gpt-5\.(?:[5-9]|\d{2,})(?:$|[-.])/.test(normalizedModel))
+        return true;
+    if (!isGpt6Family(model))
+        return false;
+    return normalizeProviderRequestReasoning(request)?.mode !== 'disabled';
 }
 function applyOpenAITokenLimit(body, model, maxTokens) {
     if (!maxTokens)
@@ -219,10 +361,10 @@ function applyOpenAITokenLimit(body, model, maxTokens) {
     }
     body.max_tokens = maxTokens;
 }
-function applyOpenAITemperature(body, model, temperature) {
-    if (shouldOmitOpenAITemperature(model))
+function applyOpenAITemperature(body, model, request) {
+    if (shouldOmitOpenAITemperature(model, request))
         return;
-    body.temperature = temperature ?? 0.7;
+    body.temperature = request.temperature ?? 0.7;
 }
 function normalizeProviderRequestReasoning(request) {
     return request.reasoning;
@@ -233,8 +375,28 @@ function unsupportedReasoning(provider, reasoning) {
         message: `AI provider "${provider}" cannot represent reasoning mode "${reasoning.mode}"`,
     });
 }
+/**
+ * GPT-6 models accept no `minimal` effort, and GPT-6 Astra and GPT-6.1 Sol also
+ * reject `none`, so disabled reasoning cannot be represented for them.
+ */
+function assertOpenAIReasoningSupported(model, reasoning) {
+    if (!isGpt6Family(model))
+        return;
+    if (reasoning.mode === 'effort' && reasoning.effort === 'minimal') {
+        throw new AIInvalidRequestError({
+            reason: 'reasoning_effort_unsupported',
+            message: `OpenAI model "${model}" does not support reasoning effort "minimal"; use "low"`,
+        });
+    }
+    if (reasoning.mode === 'disabled' && isGpt6WithoutNoneEffort(model)) {
+        throw new AIInvalidRequestError({
+            reason: 'reasoning_disabled_unsupported',
+            message: `OpenAI model "${model}" cannot disable reasoning; its lowest effort is "low"`,
+        });
+    }
+}
 /** Translate provider-neutral reasoning onto OpenAI's top-level `reasoning_effort`. */
-function applyOpenAIReasoning(body, request) {
+function applyOpenAIReasoning(body, request, model) {
     const reasoning = normalizeProviderRequestReasoning(request);
     if (!reasoning) {
         if (request.reasoningEffort)
@@ -243,11 +405,70 @@ function applyOpenAIReasoning(body, request) {
     }
     if (reasoning.mode === 'budget')
         unsupportedReasoning('openai', reasoning);
+    assertOpenAIReasoningSupported(model, reasoning);
     body.reasoning_effort = reasoning.mode === 'disabled' ? 'none' : reasoning.effort;
 }
+/**
+ * Claude models that return HTTP 400 for any non-default `temperature`, `top_p` or
+ * `top_k` on every request, thinking on or off. `disabled` is the `thinking` type sent
+ * for `{ mode: 'disabled' }` (Sonnet 5.5 takes `between_tools` instead); a model
+ * without it cannot turn thinking off. Opus 5, Sonnet 5.5 and Haiku 5.5 accept that
+ * type only at effort `high` or below; a disabled request sends no effort, and their
+ * defaults are `high` (`medium` on Haiku 5.5). Of these models only Mythos Preview
+ * accepts `thinking: { type: 'enabled', budget_tokens }`.
+ * Sources: https://platform.claude.com/docs/en/build-with-claude/thinking#sampling-parameters
+ * and https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting
+ */
+const FIXED_SAMPLING_CLAUDE_MODELS = {
+    'fable-5-1': {},
+    'mythos-5-1': {},
+    'fable-5': {},
+    'mythos-5': {},
+    'mythos-preview': { budget: true },
+    'opus-5-5': {},
+    'opus-5': { disabled: 'disabled' },
+    'opus-4-8': { disabled: 'disabled' },
+    'opus-4-7': { disabled: 'disabled' },
+    'sonnet-5-5': { disabled: 'between_tools' },
+    'sonnet-5': { disabled: 'disabled' },
+    'haiku-5-5': { disabled: 'disabled' },
+};
+/** Looks up a fixed-sampling Claude model, including dated and platform-prefixed ids. */
+function fixedSamplingClaudeModel(model) {
+    if (typeof model !== 'string')
+        return undefined;
+    const normalizedModel = model.trim().toLowerCase();
+    const id = /(?:^|[./])claude-([a-z]+-(?:\d+(?:-\d{1,2})?|preview))(?=$|[-@:])/.exec(normalizedModel)?.[1];
+    return id && Object.hasOwn(FIXED_SAMPLING_CLAUDE_MODELS, id)
+        ? FIXED_SAMPLING_CLAUDE_MODELS[id]
+        : undefined;
+}
 /** Translate provider-neutral reasoning onto Anthropic Messages API fields. */
 function applyAnthropicReasoning(body, request) {
     const reasoning = normalizeProviderRequestReasoning(request);
+    const fixedSampling = fixedSamplingClaudeModel(body.model);
+    // These models accept only the API default, so any temperature (Plumbus's 0.7
+    // default or a prompt's own) is left out, as for OpenAI gpt-5.5+.
+    const temperature = fixedSampling ? undefined : request.temperature;
+    if (fixedSampling) {
+        delete body.temperature;
+        if (reasoning?.mode === 'budget' && !fixedSampling.budget) {
+            throw new AIInvalidRequestError({
+                reason: 'reasoning_budget_unsupported',
+                message: `Anthropic model "${body.model}" does not accept a thinking budget; use an effort`,
+            });
+        }
+        if (reasoning?.mode === 'disabled') {
+            if (!fixedSampling.disabled) {
+                throw new AIInvalidRequestError({
+                    reason: 'reasoning_disabled_unsupported',
+                    message: `Anthropic model "${body.model}" cannot turn thinking off; use effort "low"`,
+                });
+            }
+            body.thinking = { type: fixedSampling.disabled };
+            return;
+        }
+    }
     if (!reasoning)
         return;
     if (reasoning.mode === 'disabled') {
@@ -267,13 +488,13 @@ function applyAnthropicReasoning(body, request) {
                 message: 'Anthropic reasoning budget must be smaller than maxTokens',
             });
         }
-        if (request.temperature != null && request.temperature !== 1) {
+        if (temperature != null && temperature !== 1) {
             throw new AIInvalidRequestError({
                 reason: 'reasoning_temperature_conflict',
                 message: 'Anthropic thinking requires temperature 1 or an omitted temperature',
             });
         }
-        if (request.temperature == null)
+        if (temperature == null)
             delete body.temperature;
         body.thinking = {
             type: 'enabled',
@@ -285,13 +506,13 @@ function applyAnthropicReasoning(body, request) {
     if (reasoning.effort === 'minimal') {
         unsupportedReasoning('anthropic', reasoning);
     }
-    if (request.temperature != null && request.temperature !== 1) {
+    if (temperature != null && temperature !== 1) {
         throw new AIInvalidRequestError({
             reason: 'reasoning_temperature_conflict',
             message: 'Anthropic adaptive thinking requires temperature 1 or an omitted temperature',
         });
     }
-    if (request.temperature == null)
+    if (temperature == null)
         delete body.temperature;
     body.thinking = { type: 'adaptive', display: 'omitted' };
     const outputConfig = body.output_config && typeof body.output_config === 'object'
@@ -321,30 +542,157 @@ function buildProviderErrorMessage(label, statusCode, body, attempts) {
     const detail = body || 'Request failed';
     return `${label} error (${statusCode})${suffix}: ${detail}`;
 }
+// ── Request deadlines ──
+/** The longest delay Node's timers keep: `AbortSignal.timeout` fires at once above it. */
+const MAX_REQUEST_TIMEOUT_MS = 2_147_483_647;
+/**
+ * Where Node's fetch (undici, bundled or installed) keeps the process's dispatcher: undici 7.27+
+ * under `.2` (and the same agent under `.1`), earlier versions under `.1` only.
+ */
+const UNDICI_GLOBAL_DISPATCHERS = [
+    Symbol.for('undici.globalDispatcher.2'),
+    Symbol.for('undici.globalDispatcher.1'),
+];
+function globalUndiciDispatcher() {
+    for (const key of UNDICI_GLOBAL_DISPATCHERS) {
+        const dispatcher = globalThis[key];
+        if (typeof dispatcher?.dispatch === 'function') {
+            return dispatcher;
+        }
+    }
+    return undefined;
+}
+/**
+ * How far above the request's timeout undici's own limits are set. Undici runs them on coarse
+ * timers (a 499 ms tick) that can fire up to half a second before their delay, so limits equal
+ * to the timeout beat the request's own timer on a reused connection and the call failed as a
+ * bare `fetch failed` instead of the timeout. One second keeps undici's limits strictly behind.
+ */
+const TRANSPORT_LIMIT_MARGIN_MS = 1_000;
+/**
+ * Node's fetch gives up by itself after 300 s without response headers, or without the next
+ * body chunk (undici's `headersTimeout` / `bodyTimeout`). A non-streamed answer that took longer
+ * to generate failed with `fetch failed` (`UND_ERR_HEADERS_TIMEOUT`) whatever the request's
+ * timeout allowed. This dispatcher passes each request to the process's dispatcher — a proxy or
+ * agent the application installed included — with both limits set just above the request's
+ * timeout, so that timeout alone decides. Fetch implementations other than undici ignore
+ * `dispatcher`.
+ */
+function deadlineDispatcher(timeoutMs) {
+    const transportLimitMs = Math.min(timeoutMs + TRANSPORT_LIMIT_MARGIN_MS, MAX_REQUEST_TIMEOUT_MS);
+    return {
+        get isMockActive() {
+            return globalUndiciDispatcher()?.isMockActive;
+        },
+        dispatch(options, handler) {
+            const dispatcher = globalUndiciDispatcher();
+            if (!dispatcher)
+                throw new Error('Node fetch has no global dispatcher');
+            return dispatcher.dispatch({ ...options, headersTimeout: transportLimitMs, bodyTimeout: transportLimitMs }, handler);
+        },
+    };
+}
+/** `error` and the errors it wraps (`cause`), outermost first. */
+function errorChain(error) {
+    const chain = [];
+    let current = error;
+    for (let depth = 0; depth < 5 && typeof current === 'object' && current !== null; depth += 1) {
+        chain.push(current);
+        current = current.cause;
+    }
+    return chain;
+}
+/** Throws `AIInvalidRequestError` (before any I/O) unless `timeoutMs` is a usable request timeout. */
+export function assertRequestTimeout(timeoutMs) {
+    if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > MAX_REQUEST_TIMEOUT_MS) {
+        throw new AIInvalidRequestError({
+            reason: 'timeout_invalid',
+            message: `AI request timeout must be a whole number of milliseconds from 1 to ${MAX_REQUEST_TIMEOUT_MS}; got ${String(timeoutMs)}`,
+        });
+    }
+}
+function createRequestDeadline(args) {
+    const timeoutMs = args.timeout ?? args.defaultTimeout;
+    assertRequestTimeout(timeoutMs);
+    let attempts = 0;
+    let timer;
+    return {
+        providerName: args.providerName,
+        errorLabel: args.errorLabel,
+        timeoutMs,
+        attempt() {
+            attempts += 1;
+            timer = AbortSignal.timeout(timeoutMs);
+            return {
+                signal: args.signal ? AbortSignal.any([args.signal, timer]) : timer,
+                dispatcher: deadlineDispatcher(timeoutMs),
+            };
+        },
+        classify(error) {
+            if (!timer?.aborted || isProviderAPIError(error))
+                return error;
+            const chain = errorChain(error);
+            const aborted = chain.some((link) => {
+                const name = link.name;
+                return link === timer?.reason || name === 'TimeoutError' || name === 'AbortError';
+            });
+            if (!aborted)
+                return error;
+            // The caller's own cancellation is rethrown as raised, unless the timeout fired first.
+            if (args.signal?.aborted && !chain.includes(timer.reason))
+                return error;
+            return new ProviderAPIError({
+                providerName: args.providerName,
+                message: `${args.errorLabel} request timed out after ${timeoutMs} ms`,
+                retryable: false,
+                attempts,
+                timeoutMs,
+                cause: error,
+            });
+        },
+    };
+}
+/** Reads a JSON answer; a body the request's timeout cut off fails as that timeout. */
+async function readResponseJson(response, deadline) {
+    try {
+        return await response.json();
+    }
+    catch (error) {
+        throw deadline.classify(error);
+    }
+}
 async function executeRequestWithRetry(args) {
+    const { deadline } = args;
     for (let attempt = 1; attempt <= maxProviderAttempts; attempt++) {
-        const response = await args.send();
-        if (response.ok) {
-            return response;
+        let response;
+        let body;
+        try {
+            response = await args.send(deadline.attempt());
+            if (response.ok) {
+                return response;
+            }
+            body = await response.text();
+        }
+        catch (error) {
+            throw deadline.classify(error);
         }
-        const body = await response.text();
         const retryable = isRetryableStatusCode(response.status);
         if (!retryable || attempt === maxProviderAttempts) {
             throw new ProviderAPIError({
-                providerName: args.providerName,
+                providerName: deadline.providerName,
                 statusCode: response.status,
                 retryable,
                 attempts: attempt,
-                message: buildProviderErrorMessage(args.errorLabel, response.status, body, attempt),
+                message: buildProviderErrorMessage(deadline.errorLabel, response.status, body, attempt),
             });
         }
         await waitForRetry(computeRetryDelayMs(attempt, response.headers.get('retry-after')));
     }
     throw new ProviderAPIError({
-        providerName: args.providerName,
+        providerName: deadline.providerName,
         retryable: false,
         attempts: maxProviderAttempts,
-        message: `${args.errorLabel} request failed`,
+        message: `${deadline.errorLabel} request failed`,
     });
 }
 // ── Provider tool-calling helpers ──
@@ -480,23 +828,39 @@ function hasOpenAIResponsesContinuation(request) {
 function isGpt56Family(model) {
     return /^gpt-5\.6(?:$|[-.])/.test(model.trim().toLowerCase());
 }
+function isGpt6Family(model) {
+    return /^gpt-6(?:$|[-.])/.test(model.trim().toLowerCase());
+}
+/** GPT-6 Astra and GPT-6.1 Sol: lowest reasoning effort is `low`, not `none`. */
+function isGpt6WithoutNoneEffort(model) {
+    return /^gpt-6(?:-astra|\.1-sol)(?:$|-)/.test(model.trim().toLowerCase());
+}
 /**
  * Chat Completions cannot combine function tools with active reasoning on
- * GPT-5.6. Keep every compatible request on the existing transport, but use
- * Responses for explicit reasoning effort, GPT-5.6's default reasoning, and
- * continuation rounds that already carry Responses output state.
+ * GPT-5.6 or GPT-6 ("Function tools with reasoning_effort are not supported for
+ * gpt-6-luna in /v1/chat/completions. To use function tools, use /v1/responses or
+ * set reasoning_effort to 'none'."). Keep every compatible request on the existing
+ * transport. Caller tools use Responses for explicit reasoning effort, these families'
+ * default reasoning, and continuation rounds that already carry Responses output
+ * state. The structured-output tool of `structuredOutputTransport: 'tool'` is one
+ * forced call with no continuation, so it moves only where Chat Completions refuses
+ * it: these families with reasoning not disabled. On other models (o-series, earlier
+ * gpt-5 lines, an OpenAI-compatible `baseUrl` that may have no `/responses`) it stays
+ * on Chat Completions, with its reasoning effort, as before.
  */
 function shouldUseOpenAIResponses(request, model) {
     if (hasOpenAIResponsesContinuation(request))
         return true;
-    if (!request.tools || request.tools.length === 0)
-        return false;
     const reasoning = normalizeProviderRequestReasoning(request);
     if (reasoning?.mode === 'disabled')
         return false;
-    if (reasoning?.mode === 'effort' || request.reasoningEffort !== undefined)
-        return true;
-    return reasoning === undefined && isGpt56Family(model);
+    const chatRefusesToolsUnderReasoning = isGpt56Family(model) || isGpt6Family(model);
+    if (request.tools && request.tools.length > 0) {
+        if (reasoning?.mode === 'effort' || request.reasoningEffort !== undefined)
+            return true;
+        return reasoning === undefined && chatRefusesToolsUnderReasoning;
+    }
+    return shouldUseOpenAIStructuredTool({ request }) && chatRefusesToolsUnderReasoning;
 }
 function toOpenAIResponsesInput(request) {
     if (!request.messages || request.messages.length === 0) {
@@ -544,7 +908,7 @@ function buildOpenAIResponsesToolChoice(toolChoice) {
         return toolChoice;
     return { type: 'function', name: toolChoice.function.name };
 }
-function applyOpenAIResponsesReasoning(body, request) {
+function applyOpenAIResponsesReasoning(body, request, model) {
     const reasoning = normalizeProviderRequestReasoning(request);
     if (!reasoning) {
         if (request.reasoningEffort)
@@ -553,16 +917,24 @@ function applyOpenAIResponsesReasoning(body, request) {
     }
     if (reasoning.mode === 'budget')
         unsupportedReasoning('openai', reasoning);
+    assertOpenAIReasoningSupported(model, reasoning);
     body.reasoning = { effort: reasoning.mode === 'disabled' ? 'none' : reasoning.effort };
 }
 function openAIResponsesUsageToTokenUsage(usage) {
     const inputTokens = usage?.input_tokens ?? 0;
     const outputTokens = usage?.output_tokens ?? 0;
+    const reasoning = usage?.output_tokens_details?.reasoning_tokens;
+    const cacheWrites = usage?.input_tokens_details?.cache_write_tokens;
     return {
         inputTokens,
         outputTokens,
         totalTokens: usage?.total_tokens ?? inputTokens + outputTokens,
         cachedInputTokens: usage?.input_tokens_details?.cached_tokens ?? 0,
+        // As on Chat Completions: the share of `input_tokens` written to the cache.
+        ...(typeof cacheWrites === 'number' ? { cacheWriteTokens: cacheWrites } : {}),
+        // As on Chat Completions (`openAIUsageToTokenUsage`): the reasoning share of `output_tokens`,
+        // which already counts it and is what is priced.
+        ...(typeof reasoning === 'number' ? { reasoningTokens: reasoning } : {}),
     };
 }
 function extractOpenAIResponsesContent(output) {
@@ -597,6 +969,11 @@ async function completeOpenAIResponses(args) {
         assertNoStructuredOutputToolConflict(request);
         validateCallerTools(request.tools);
     }
+    // `structuredOutputTransport: 'tool'` under active reasoning: the same forced strict function
+    // as on Chat Completions, in the Responses tool shape (its fields sit on the tool itself).
+    const structuredToolSchema = shouldUseOpenAIStructuredTool({ request })
+        ? request.responseSchema
+        : undefined;
     const body = {
         model,
         input: toOpenAIResponsesInput(request),
@@ -605,16 +982,38 @@ async function completeOpenAIResponses(args) {
     };
     if (request.system)
         body.instructions = request.system;
-    applyOpenAITemperature(body, model, request.temperature);
-    applyOpenAIResponsesReasoning(body, request);
+    applyOpenAITemperature(body, model, request);
+    applyOpenAIResponsesReasoning(body, request, model);
     if (request.maxTokens)
         body.max_output_tokens = request.maxTokens;
+    if (structuredToolSchema) {
+        body.tools = [{ type: 'function', ...openAIStructuredOutputFunction(structuredToolSchema) }];
+        body.tool_choice = { type: 'function', name: OPENAI_STRUCTURED_OUTPUT_TOOL_NAME };
+    }
+    else if (request.responseFormat === 'json') {
+        body.text = {
+            format: request.responseSchema
+                ? {
+                    type: 'json_schema',
+                    name: 'response',
+                    strict: true,
+                    schema: toOpenAIStrictOutputSchema(request.responseSchema).schema,
+                }
+                : { type: 'json_object' },
+        };
+    }
     if (request.tools && request.tools.length > 0) {
+        // `strict: false` keeps caller tools as they are on Chat Completions. With `strict` omitted,
+        // Responses "will attempt to normalize your schema into strict mode when possible", and does
+        // so by listing every property as required: an optional argument the user never gave
+        // (`unit` of `get_weather`) came back filled in (`"unit": "celsius"`), and the app's input
+        // check cannot tell it from a real one.
         body.tools = request.tools.map((tool) => ({
             type: 'function',
             name: tool.name,
             description: tool.description,
             parameters: tool.parameters,
+            strict: false,
         }));
         const toolChoice = buildOpenAIResponsesToolChoice(request.toolChoice);
         if (toolChoice !== undefined)
@@ -622,24 +1021,36 @@ async function completeOpenAIResponses(args) {
         if (request.toolExecution?.parallelToolCalls === false)
             body.parallel_tool_calls = false;
     }
-    const response = await executeRequestWithRetry({
+    const deadline = createRequestDeadline({
         providerName: 'openai',
         errorLabel: 'OpenAI Responses API',
-        send: () => fetch(`${args.baseUrl}/responses`, {
+        signal: request.signal,
+        timeout: request.timeout,
+        defaultTimeout: args.defaultTimeout,
+    });
+    const response = await executeRequestWithRetry({
+        deadline,
+        send: (transport) => fetch(`${args.baseUrl}/responses`, {
             method: 'POST',
             headers: {
+                ...request.transportHeaders,
                 'Content-Type': 'application/json',
                 Authorization: `Bearer ${args.apiKey}`,
             },
             body: JSON.stringify(body),
-            signal: combineRequestSignals(request.signal, request.timeout ?? args.defaultTimeout),
+            ...transport,
         }),
     });
-    const data = (await response.json());
+    const data = (await readResponseJson(response, deadline));
     const usage = openAIResponsesUsageToTokenUsage(data.usage);
     const output = data.output ?? [];
     const extracted = extractOpenAIResponsesContent(output);
-    const content = extracted.content || data.output_text || '';
+    const structuredArguments = structuredToolSchema
+        ? output.find((item) => item.type === 'function_call' && item.name === OPENAI_STRUCTURED_OUTPUT_TOOL_NAME)?.arguments
+        : undefined;
+    const content = unwrapOpenAIStructuredContent(request, typeof structuredArguments === 'string' && structuredArguments.length > 0
+        ? structuredArguments
+        : extracted.content || data.output_text || '');
     const responseModel = data.model ?? model;
     if (data.status === 'failed' || data.error) {
         throw new ProviderAPIError({
@@ -657,7 +1068,8 @@ async function completeOpenAIResponses(args) {
             usage,
         });
     }
-    const toolCalls = parseOpenAIResponsesToolCalls(output);
+    // The structured-output call is the answer, not a tool call for the caller to run.
+    const toolCalls = structuredToolSchema ? [] : parseOpenAIResponsesToolCalls(output);
     if (toolCalls.length > 0) {
         return {
             content,
@@ -779,12 +1191,15 @@ export function createOpenAIAdapter(config) {
                 model,
                 messages,
             };
-            applyOpenAITemperature(body, model, request.temperature);
-            applyOpenAIReasoning(body, request);
+            applyOpenAITemperature(body, model, request);
+            applyOpenAIReasoning(body, request, model);
             applyOpenAITokenLimit(body, model, request.maxTokens);
             if (request.tools && request.tools.length > 0) {
                 assertNoStructuredOutputToolConflict(request);
                 validateCallerTools(request.tools);
+                const responseFormat = buildOpenAIResponseFormat(request);
+                if (responseFormat)
+                    body.response_format = responseFormat;
                 body.tools = request.tools.map((t) => ({
                     type: 'function',
                     function: { name: t.name, description: t.description, parameters: t.parameters },
@@ -817,25 +1232,32 @@ export function createOpenAIAdapter(config) {
             if (typeof request.seed === 'number') {
                 body.seed = request.seed;
             }
-            const resp = await executeRequestWithRetry({
+            const deadline = createRequestDeadline({
                 providerName: 'openai',
                 errorLabel: 'OpenAI API',
-                send: () => fetch(`${baseUrl}/chat/completions`, {
+                signal: request.signal,
+                timeout: request.timeout,
+                defaultTimeout,
+            });
+            const resp = await executeRequestWithRetry({
+                deadline,
+                send: (transport) => fetch(`${baseUrl}/chat/completions`, {
                     method: 'POST',
                     headers: {
+                        ...request.transportHeaders,
                         'Content-Type': 'application/json',
                         Authorization: `Bearer ${config.apiKey}`,
                     },
                     body: JSON.stringify(body),
-                    signal: combineRequestSignals(request.signal, request.timeout ?? defaultTimeout),
+                    ...transport,
                 }),
             });
-            const data = (await resp.json());
+            const data = (await readResponseJson(resp, deadline));
             const choice = data.choices[0];
             if (!choice)
                 throw new Error('OpenAI returned no choices');
             const usage = openAIUsageToTokenUsage(data.usage);
-            const content = extractOpenAIMessageContent(choice.message);
+            const content = unwrapOpenAIStructuredContent(request, extractOpenAIMessageContent(choice.message));
             if (choice.message.refusal) {
                 throw new AIRefusalError({
                     provider: 'openai',
@@ -899,8 +1321,8 @@ export function createOpenAIAdapter(config) {
                 stream: true,
                 stream_options: { include_usage: true },
             };
-            applyOpenAITemperature(body, model, request.temperature);
-            applyOpenAIReasoning(body, request);
+            applyOpenAITemperature(body, model, request);
+            applyOpenAIReasoning(body, request, model);
             applyOpenAITokenLimit(body, model, request.maxTokens);
             const responseFormat = buildOpenAIResponseFormat(request);
             if (responseFormat) {
@@ -909,19 +1331,26 @@ export function createOpenAIAdapter(config) {
             if (typeof request.seed === 'number') {
                 body.seed = request.seed;
             }
+            const deadline = createRequestDeadline({
+                providerName: 'openai',
+                errorLabel: 'OpenAI API',
+                signal: request.signal,
+                timeout: request.timeout,
+                defaultTimeout,
+            });
             let resp;
             try {
                 resp = await executeRequestWithRetry({
-                    providerName: 'openai',
-                    errorLabel: 'OpenAI API',
-                    send: () => fetch(`${baseUrl}/chat/completions`, {
+                    deadline,
+                    send: (transport) => fetch(`${baseUrl}/chat/completions`, {
                         method: 'POST',
                         headers: {
+                            ...request.transportHeaders,
                             'Content-Type': 'application/json',
                             Authorization: `Bearer ${config.apiKey}`,
                         },
                         body: JSON.stringify(body),
-                        signal: combineRequestSignals(request.signal, request.timeout ?? defaultTimeout),
+                        ...transport,
                     }),
                 });
             }
@@ -929,30 +1358,38 @@ export function createOpenAIAdapter(config) {
                 yield {
                     type: 'error',
                     error: error instanceof Error ? error.message : String(error),
+                    cause: error,
                 };
                 return;
             }
-            yield* parseSSEStream(resp, parseOpenAISSEChunk);
+            const events = parseSSEStream(resp, parseOpenAISSEChunk, deadline);
+            yield* hasOpenAIStructuredEnvelope(request) ? unwrapOpenAIStructuredStream(events) : events;
         },
         async embed(request) {
             const body = {
                 model: request.model ?? defaultEmbeddingModel,
                 input: request.texts,
             };
-            const resp = await executeRequestWithRetry({
+            const deadline = createRequestDeadline({
                 providerName: 'openai',
                 errorLabel: 'OpenAI Embedding API',
-                send: () => fetch(`${baseUrl}/embeddings`, {
+                signal: request.signal,
+                timeout: request.timeout,
+                defaultTimeout,
+            });
+            const resp = await executeRequestWithRetry({
+                deadline,
+                send: (transport) => fetch(`${baseUrl}/embeddings`, {
                     method: 'POST',
                     headers: {
                         'Content-Type': 'application/json',
                         Authorization: `Bearer ${config.apiKey}`,
                     },
                     body: JSON.stringify(body),
-                    signal: AbortSignal.timeout(defaultTimeout),
+                    ...transport,
                 }),
             });
-            const data = (await resp.json());
+            const data = (await readResponseJson(resp, deadline));
             const totalTokens = data.usage.total_tokens;
             return {
                 embeddings: data.data.map((d) => d.embedding),
@@ -1046,21 +1483,31 @@ export function createAnthropicAdapter(config) {
                 if (callerToolChoice !== undefined)
                     body.tool_choice = callerToolChoice;
             }
-            const resp = await executeRequestWithRetry({
+            const promptCache = resolvePromptCache(request.cache);
+            if (promptCache)
+                applyAnthropicPromptCache(body, promptCache);
+            const deadline = createRequestDeadline({
                 providerName: 'anthropic',
                 errorLabel: 'Anthropic API',
-                send: () => fetch(`${baseUrl}/messages`, {
+                signal: request.signal,
+                timeout: request.timeout,
+                defaultTimeout,
+            });
+            const resp = await executeRequestWithRetry({
+                deadline,
+                send: (transport) => fetch(`${baseUrl}/messages`, {
                     method: 'POST',
                     headers: {
+                        ...request.transportHeaders,
                         'Content-Type': 'application/json',
                         'x-api-key': config.apiKey,
                         'anthropic-version': '2023-06-01',
                     },
                     body: JSON.stringify(body),
-                    signal: combineRequestSignals(request.signal, request.timeout ?? defaultTimeout),
+                    ...transport,
                 }),
             });
-            const data = (await resp.json());
+            const data = (await readResponseJson(resp, deadline));
             const usage = anthropicUsageToTokenUsage(data.usage);
             const text = data.content
                 .filter((c) => c.type === 'text')
@@ -1108,11 +1555,7 @@ export function createAnthropicAdapter(config) {
             };
         },
         async *stream(request) {
-            // Multi-turn path: when `messages` is supplied, send them verbatim.
-            // Single-turn path: synthesize a single user message from `prompt`.
-            const messages = request.messages && request.messages.length > 0
-                ? request.messages.map((m) => ({ role: m.role, content: m.content }))
-                : [{ role: 'user', content: request.prompt }];
+            const messages = toAnthropicMessages(request);
             const body = {
                 model: request.model ?? defaultModel,
                 messages,
@@ -1131,20 +1574,30 @@ export function createAnthropicAdapter(config) {
                 };
             }
             applyAnthropicReasoning(body, request);
+            const promptCache = resolvePromptCache(request.cache);
+            if (promptCache)
+                applyAnthropicPromptCache(body, promptCache);
+            const deadline = createRequestDeadline({
+                providerName: 'anthropic',
+                errorLabel: 'Anthropic API',
+                signal: request.signal,
+                timeout: request.timeout,
+                defaultTimeout,
+            });
             let resp;
             try {
                 resp = await executeRequestWithRetry({
-                    providerName: 'anthropic',
-                    errorLabel: 'Anthropic API',
-                    send: () => fetch(`${baseUrl}/messages`, {
+                    deadline,
+                    send: (transport) => fetch(`${baseUrl}/messages`, {
                         method: 'POST',
                         headers: {
+                            ...request.transportHeaders,
                             'Content-Type': 'application/json',
                             'x-api-key': config.apiKey,
                             'anthropic-version': '2023-06-01',
                         },
                         body: JSON.stringify(body),
-                        signal: combineRequestSignals(request.signal, request.timeout ?? defaultTimeout),
+                        ...transport,
                     }),
                 });
             }
@@ -1152,11 +1605,12 @@ export function createAnthropicAdapter(config) {
                 yield {
                     type: 'error',
                     error: error instanceof Error ? error.message : String(error),
+                    cause: error,
                 };
                 return;
             }
             let initialUsage;
-            for await (const event of parseSSEStream(resp, parseAnthropicSSEChunk)) {
+            for await (const event of parseSSEStream(resp, parseAnthropicSSEChunk, deadline)) {
                 if (event.type === 'usage' && event.usage)
                     initialUsage = event.usage;
                 if (event.type === 'done' && event.usage && initialUsage) {
@@ -1230,7 +1684,7 @@ export function createAnthropicAdapter(config) {
         },
     };
 }
-async function* parseSSEStream(resp, parseChunk) {
+async function* parseSSEStream(resp, parseChunk, deadline) {
     if (!resp.body) {
         yield { type: 'error', error: 'No response body for streaming' };
         return;
@@ -1241,7 +1695,10 @@ async function* parseSSEStream(resp, parseChunk) {
     let currentEvent = '';
     try {
         while (true) {
-            const { done, value } = await reader.read();
+            // The request's timeout covers the whole stream: a cut-off read fails as that timeout.
+            const { done, value } = await reader.read().catch((error) => {
+                throw deadline.classify(error);
+            });
             if (done)
                 break;
             buffer += decoder.decode(value, { stream: true });
@@ -1282,15 +1739,7 @@ function parseOpenAISSEChunk(_eventType, data) {
         // Usage-only chunk (sent when stream_options.include_usage is true)
         if (parsed.usage &&
             (!parsed.choices || parsed.choices.length === 0 || !parsed.choices[0]?.delta?.content)) {
-            return {
-                type: 'usage',
-                usage: {
-                    inputTokens: parsed.usage.prompt_tokens,
-                    outputTokens: parsed.usage.completion_tokens,
-                    totalTokens: parsed.usage.total_tokens,
-                    cachedInputTokens: parsed.usage.prompt_tokens_details?.cached_tokens ?? 0,
-                },
-            };
+            return { type: 'usage', usage: openAIUsageToTokenUsage(parsed.usage) };
         }
         const choice = parsed.choices?.[0];
         if (!choice)