@pentoshi/clai 4.0.3 → 4.2.0

package/dist/llm/http.js

@@ -2,8 +2,15 @@ import { modelAcceptsImages, modelSupportsThinking, isReasoningUnsupported, mode
 import { resolveSampling } from "./sampling.js";
 import { accumulateOpenAiToolCallDelta, finalizeOpenAiToolCalls, fromWireName, parseOpenAiMessageToolCalls, } from "./tool-protocol.js";
 import { openAiToolBodyFields, toOpenAiToolMessages, } from "./adapters/openai-tools.js";
-import { parseOpenAiUsage } from "./token-usage.js";
-import { REASONING_CLOSE, REASONING_OPEN, wrapReasoning, } from "./reasoning-marker.js";
+import { parseFireworksUsage, parseOpenAiUsage, } from "./token-usage.js";
+import { generationFetch } from "./operation-usage.js";
+import { isOperationPolicyError } from "./operation-ledger.js";
+import { emitStreamReasoningArtifacts, emitStreamReasoningDelta, } from "./stream-events.js";
+import { CHAT_COMPLETIONS_STREAM_TERMINAL, requireTerminalProof, } from "./stream-terminal.js";
+import { createReasoningArtifact, createReasoningArtifactProvenance, } from "./reasoning-artifacts.js";
+import { classifyBynaraModel, classifyNvidiaModel, } from "./model-families.js";
+import { compileRequestPlan, } from "./request-plan.js";
+import { singleLeadingSystemMessages } from "./system-messages.js";
 export class ProviderError extends Error {
     status;
     body;
@@ -190,10 +197,11 @@ export function ingestOpenAiModelCatalog(provider, payload) {
                 : [];
     return ingestModelCatalogEntries(provider, entries);
 }
-export async function readJson(response) {
-    const text = await readBodyCapped(response, MAX_JSON_RESPONSE_BYTES);
+export async function readJson(response, signal) {
+    const text = await readBodyCapped(response, MAX_JSON_RESPONSE_BYTES, signal);
     if (!response.ok) {
         let detail = "";
+        let extractedMessage = "";
         try {
             const body = JSON.parse(text);
             const error = body.error;
@@ -223,10 +231,23 @@ export async function readJson(response) {
                     detail = ` — ${msg}`;
                 }
             }
+            extractedMessage = msg;
         }
         catch {
-            if (text.length > 0)
-                detail = ` — ${text.slice(0, 200)}`;
+            // Non-JSON body — the raw text is surfaced via the full-response rule
+            // below, so nothing is lost here.
+        }
+        // Show the full error received from the request: the extracted
+        // `error.message` alone routinely hides the actionable part of a gateway
+        // error (upstream detail, codes, validation fields). Append the complete
+        // body whenever it carries anything beyond that extracted message.
+        const bodyText = text.slice(0, MAX_ERROR_BODY_CHARS);
+        if (bodyAddsInformation(bodyText, extractedMessage)) {
+            const shown = collapseWhitespace(bodyText);
+            const capped = shown.length > MAX_ERROR_BODY_IN_MESSAGE_CHARS
+                ? `${shown.slice(0, MAX_ERROR_BODY_IN_MESSAGE_CHARS)}…`
+                : shown;
+            detail = `${detail} — full response: ${capped}`;
         }
         const retryAfterSeconds = parseRetryAfterHeader(response.headers.get("retry-after")) ??
             parseRetryHintFromBody(text);
@@ -234,24 +255,67 @@ export async function readJson(response) {
             ? ` (retry after ${Math.ceil(retryAfterSeconds)}s)`
             : "";
         const codeHint = statusCodeHint(response.status);
-        throw new ProviderError(`Provider request failed with HTTP ${response.status}${retryHint}${detail}${codeHint}`, response.status, text.slice(0, 1_000), retryAfterSeconds);
+        throw new ProviderError(`Provider request failed with HTTP ${response.status}${retryHint}${detail}${codeHint}`, response.status, bodyText, retryAfterSeconds);
     }
     return JSON.parse(text);
 }
 /** Hard cap on a JSON response body so a misbehaving provider can't OOM us. */
 const MAX_JSON_RESPONSE_BYTES = 4 * 1024 * 1024;
-async function readBodyCapped(response, maxBytes) {
+/** How much of a provider error body we retain on the ProviderError. */
+export const MAX_ERROR_BODY_CHARS = 8_000;
+/** How much of that body is embedded in the user-visible error message. */
+export const MAX_ERROR_BODY_IN_MESSAGE_CHARS = 2_000;
+export function collapseWhitespace(text) {
+    return text.replace(/\s+/g, " ").trim();
+}
+/**
+ * True when the raw response body carries information beyond the message we
+ * already extracted from it (extra JSON fields, non-JSON payloads, …). Pure
+ * `{"error":{"message": …}}` envelopes are redundant and stay compact.
+ */
+export function bodyAddsInformation(bodyText, extracted) {
+    const collapsed = collapseWhitespace(bodyText);
+    if (!collapsed)
+        return false;
+    if (!extracted)
+        return true;
+    const normalizedExtracted = collapseWhitespace(extracted);
+    // The user-facing text already carries the entire body verbatim.
+    if (normalizedExtracted.includes(collapsed))
+        return false;
+    if (!collapsed.includes(normalizedExtracted))
+        return true;
+    const rest = collapsed
+        .replace(normalizedExtracted, " ")
+        .replace(/\b(errors?|message|msg|detail|details|type|code|status)\b/gi, " ")
+        .replace(/[{}\[\]":,]/g, " ")
+        .trim();
+    return rest.length > 0;
+}
+async function readBodyCapped(response, maxBytes, signal) {
     const reader = response.body?.getReader();
     if (!reader) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Response body read aborted");
+        }
         const text = await response.text();
         return text.length > maxBytes ? text.slice(0, maxBytes) : text;
     }
     const decoder = new TextDecoder("utf-8", { fatal: false });
     let collected = "";
     let bytesRead = 0;
+    const cancelOnAbort = () => {
+        void reader.cancel(signal?.reason).catch(() => undefined);
+    };
+    signal?.addEventListener("abort", cancelOnAbort, { once: true });
     try {
         while (bytesRead < maxBytes) {
-            const { done, value } = await reader.read();
+            const { done, value } = signal
+                ? await readWithAbort(reader, signal)
+                : await reader.read();
+            if (signal?.aborted) {
+                throw signal.reason ?? new Error("Response body read aborted");
+            }
             if (done)
                 break;
             if (!value)
@@ -276,6 +340,7 @@ async function readBodyCapped(response, maxBytes) {
         collected += decoder.decode();
     }
     finally {
+        signal?.removeEventListener("abort", cancelOnAbort);
         try {
             reader.releaseLock();
         }
@@ -298,8 +363,8 @@ async function readBodyCapped(response, maxBytes) {
  * re-generated the same prefix before one happened to finish inside the window.
  */
 export const DEFAULT_STREAM_IDLE_TIMEOUT_MS = 240_000;
-export const THINKING_STREAM_IDLE_TIMEOUT_MS = 600_000;
-export const THINKING_STREAM_INITIAL_IDLE_TIMEOUT_MS = 600_000;
+export const THINKING_STREAM_IDLE_TIMEOUT_MS = 900_000;
+export const THINKING_STREAM_INITIAL_IDLE_TIMEOUT_MS = 900_000;
 export function streamIdleBudgets(reasoningEnabled) {
     const idleTimeoutMs = reasoningEnabled
         ? THINKING_STREAM_IDLE_TIMEOUT_MS
@@ -483,6 +548,79 @@ export async function* readStreamLines(response, options = {}) {
         }
     }
 }
+const DEFAULT_COMPATIBLE_REASONING_ARTIFACT_POLICY = {
+    scope: "all-history",
+    persistence: "tool-turn",
+};
+function artifactRaw(value) {
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === "object") {
+        return value;
+    }
+    return undefined;
+}
+function compatibleReasoningArtifacts(input) {
+    const policy = input.policy ?? DEFAULT_COMPATIBLE_REASONING_ARTIFACT_POLICY;
+    const provenance = createReasoningArtifactProvenance({
+        provider: input.providerId,
+        model: input.model,
+        dialect: "openai-compatible",
+        endpoint: input.baseUrl,
+    });
+    const artifacts = [];
+    const primaryToolPosition = input.toolCalls.length > 0 ? 0 : undefined;
+    if (input.reasoning?.text) {
+        artifacts.push(createReasoningArtifact({
+            kind: "plaintext",
+            raw: input.reasoning.text,
+            displaySummary: input.reasoning.text,
+            provenance,
+            replay: policy,
+            position: {
+                sequence: input.reasoning.sequence,
+                placement: primaryToolPosition === undefined ? "assistant" : "before-tool-call",
+                ...(primaryToolPosition === undefined
+                    ? {}
+                    : { toolCallIndex: primaryToolPosition }),
+            },
+        }));
+    }
+    for (const detail of input.details ?? []) {
+        artifacts.push(createReasoningArtifact({
+            kind: "structured-details",
+            raw: detail.raw,
+            provenance,
+            replay: policy,
+            position: {
+                sequence: detail.sequence,
+                placement: primaryToolPosition === undefined ? "assistant" : "before-tool-call",
+                ...(primaryToolPosition === undefined
+                    ? {}
+                    : { toolCallIndex: primaryToolPosition }),
+            },
+        }));
+    }
+    for (const signature of input.thoughtSignatures ?? []) {
+        const toolCallIndex = signature.toolCallIndex;
+        artifacts.push(createReasoningArtifact({
+            kind: "thought-signature",
+            raw: signature.raw,
+            provenance,
+            replay: toolCallIndex === undefined
+                ? { scope: "none", persistence: "never" }
+                : { scope: "tool-turn", persistence: "tool-turn" },
+            position: {
+                sequence: signature.sequence,
+                placement: toolCallIndex === undefined ? "assistant" : "on-tool-call",
+                ...(toolCallIndex === undefined ? {} : { toolCallIndex }),
+            },
+        }));
+    }
+    return artifacts.length ? artifacts : undefined;
+}
 /** Map shared OpenAI-compatible payload → CompletionResult (includes usage). */
 export function toCompletionResult(provider, model, payload) {
     return {
@@ -492,6 +630,10 @@ export function toCompletionResult(provider, model, payload) {
         ...(payload.toolCalls?.length ? { toolCalls: payload.toolCalls } : {}),
         ...(payload.finishReason ? { finishReason: payload.finishReason } : {}),
         ...(payload.usage ? { usage: payload.usage } : {}),
+        ...(payload.reasoningBlock ? { reasoningBlock: payload.reasoningBlock } : {}),
+        ...(payload.reasoningArtifacts
+            ? { reasoningArtifacts: payload.reasoningArtifacts }
+            : {}),
     };
 }
 /**
@@ -544,7 +686,7 @@ export function createSseFrameAssembler(options) {
         },
     };
 }
-export function toOpenAiMessages(messages, supportsVision = true) {
+export function toOpenAiMessages(messages, supportsVision = true, replay) {
     return toOpenAiToolMessages(messages, (message) => {
         if (supportsVision &&
             message.images &&
@@ -564,44 +706,12 @@ export function toOpenAiMessages(messages, supportsVision = true) {
             return parts;
         }
         return message.content;
-    });
-}
-export function classifyNvidiaModel(model) {
-    const m = model.toLowerCase();
-    if (/kimi-k2(?:\.6|-thinking|-instruct)?/.test(m))
-        return "kimi-thinking";
-    if (/deepseek-v4/.test(m))
-        return "deepseek-v4";
-    // Match newer Nemotron-3 (uses enable_thinking + reasoning_budget) before
-    // the legacy Nemotron pattern below — the older `nemotron` bucket would
-    // otherwise swallow these too.
-    if (/nemotron-3/.test(m))
-        return "nemotron-3";
-    if (/glm-?[345]/.test(m))
-        return "glm-thinking";
-    if (/gemma-?[34]/.test(m))
-        return "enable-thinking";
-    if (/deepseek-(?:v3|r1)|nemotron/.test(m))
-        return "thinking";
-    if (/gpt-oss|qwen3|mistral-(?:medium|small|large)-(?:[3-9]|\d{2,})/.test(m))
-        return "effort-only";
-    return "none";
+    }, replay);
 }
+export { classifyBynaraModel, classifyNvidiaModel, } from "./model-families.js";
 function supportsOpenRouterReasoning(model) {
     return /:thinking|deepseek-r1|qwen3|kimi-k2|claude-(?:opus|sonnet|haiku)-4|gpt-5|(?:^|\/)o[134]|grok.*reasoner/i.test(model);
 }
-export function classifyBynaraModel(model) {
-    const m = model.toLowerCase();
-    if (/kimi/.test(m))
-        return "kimi";
-    if (/deepseek/.test(m))
-        return "deepseek";
-    if (/agnes/.test(m))
-        return "agnes";
-    if (/stepfun|step-3/.test(m))
-        return "stepfun";
-    return "none";
-}
 const MODAL_DEFAULT_EFFORTS = ["low", "high", "max"];
 const MODAL_EFFORT_PREFERENCE = {
     minimal: ["minimal", "low", "medium", "high", "max"],
@@ -933,7 +1043,7 @@ export function isOpenAiReasoningModel(model) {
         /(?:^|\/)o[134](?:\.|-|$)/.test(m) ||
         /muse-spark/.test(m));
 }
-export function buildChatBody(options) {
+function emitChatCompletionsBody(options) {
     // Skip reasoning knobs entirely for models observed to reject them this
     // session (see isReasoningUnsupportedError). This is how thinking degrades
     // gracefully: the request still runs, just without the unsupported option.
@@ -972,8 +1082,16 @@ export function buildChatBody(options) {
         : (options.maxTokens ?? defaultMaxTokens);
     const body = {
         model: options.model,
-        messages: toOpenAiMessages(options.messages, options.supportsVision),
+        messages: toOpenAiMessages(singleLeadingSystemMessages(options.messages), options.supportsVision, options.replayTarget
+            ? {
+                target: options.replayTarget,
+                observe: options.reasoningArtifactReplayObserver,
+            }
+            : undefined),
         stream: options.stream,
+        ...(options.providerId === "fireworks"
+            ? { perf_metrics_in_response: true }
+            : {}),
         ...(reasoningModel
             ? { max_completion_tokens: effectiveMaxTokens }
             : { max_tokens: effectiveMaxTokens }),
@@ -998,6 +1116,35 @@ export function buildChatBody(options) {
     }
     return JSON.stringify(body);
 }
+export function buildChatBody(options) {
+    return emitChatCompletionsBody(options);
+}
+/**
+ * Serializes a compiled canonical plan onto the Chat Completions wire. Wire
+ * dialect knobs that the plan intentionally does not model (gateway reasoning
+ * style, stream-usage flag, replay observer) stay serializer-side extras.
+ */
+export function chatCompletionsBodyFromPlan(plan, extras = {}) {
+    return emitChatCompletionsBody({
+        model: plan.route.model,
+        providerId: plan.route.provider,
+        messages: [...plan.timeline.messages],
+        maxTokens: plan.controls.requestedMaxTokens,
+        temperature: plan.controls.temperature,
+        stream: plan.controls.stream,
+        includeStreamUsage: extras.includeStreamUsage,
+        reasoning: plan.controls.reasoning,
+        reasoningStyle: extras.reasoningStyle,
+        supportsVision: plan.images.visionAccepted,
+        tools: plan.tools.definitions.length
+            ? [...plan.tools.definitions]
+            : undefined,
+        toolChoice: plan.tools.choice,
+        parallelToolCalls: plan.tools.parallelToolCalls,
+        replayTarget: plan.replay.target,
+        reasoningArtifactReplayObserver: extras.reasoningArtifactReplayObserver,
+    });
+}
 function sentReasoningEffort(requestBody) {
     try {
         const body = JSON.parse(requestBody);
@@ -1021,35 +1168,27 @@ function privateReasoningNote(provider, requestBody, reasoningTokens) {
     const effortText = effort ? ` at ${effort} effort` : "";
     return `Reasoning is private on ${provider}: the model reasoned${effortText} and used ${reasoningTokens.toLocaleString("en-US")} reasoning tokens, but the API returns no reasoning text to display.`;
 }
-function foldReasoning(provider, requestBody, text, reasoning, usage) {
-    if (reasoning && reasoning.trim()) {
-        return `${wrapReasoning(reasoning)}${text}`;
-    }
-    const tokens = usage?.reasoningTokens ?? 0;
-    if (tokens > 0) {
-        return `${wrapReasoning(privateReasoningNote(provider, requestBody, tokens))}${text}`;
-    }
-    return text;
-}
 export async function openAiCompatibleComplete(options) {
-    const supportsVision = modelAcceptsImages(options.providerId, options.model);
-    const requestBody = buildChatBody({
+    const plan = compileRequestPlan({
+        provider: options.providerId,
         model: options.model,
-        providerId: options.providerId,
         messages: options.messages,
-        maxTokens: options.maxTokens,
-        temperature: options.temperature,
         stream: false,
+        endpoint: options.baseUrl,
         reasoning: options.reasoning,
-        reasoningStyle: options.reasoningStyle,
-        supportsVision,
         tools: options.tools,
         toolChoice: options.toolChoice,
         parallelToolCalls: options.parallelToolCalls,
+        temperature: options.temperature,
+        maxTokens: options.maxTokens,
+    });
+    const requestBody = chatCompletionsBodyFromPlan(plan, {
+        reasoningStyle: options.reasoningStyle,
+        reasoningArtifactReplayObserver: options.reasoningArtifactReplayObserver,
     });
     let response;
     try {
-        response = await fetch(`${options.baseUrl}/chat/completions`, {
+        response = await generationFetch(`${options.baseUrl}/chat/completions`, {
             method: "POST",
             signal: options.signal ?? null,
             headers: {
@@ -1067,6 +1206,8 @@ export async function openAiCompatibleComplete(options) {
     catch (error) {
         if (error instanceof Error && error.name === "AbortError")
             throw error;
+        if (isOperationPolicyError(error))
+            throw error;
         const msg = error instanceof Error ? error.message : String(error);
         throw new ProviderError(`${options.provider} request could not be sent (${msg}). Check connectivity to ${options.baseUrl}.`);
     }
@@ -1089,14 +1230,42 @@ export async function openAiCompatibleComplete(options) {
     }
     // If the API returns reasoning separately, prepend it inside <think>
     // tags so the existing thinking parser can pick it up uniformly.
-    const usage = parseOpenAiUsage(data.usage);
+    // Fireworks exposes cache metrics in headers for complete calls and can also
+    // include them in perf_metrics. Other compatible routes use their standard
+    // usage object plus any explicitly configured aliases.
+    const usage = options.providerId === "fireworks"
+        ? parseFireworksUsage(data.usage, data.perf_metrics, response.headers)
+        : parseOpenAiUsage(data.usage, options.usageAliases);
     const reasoning = message?.reasoning_content ?? message?.reasoning;
+    const detailsRaw = artifactRaw(message?.reasoning_details);
+    const thoughtSignature = message?.extra_content?.google?.thought_signature;
+    const reasoningArtifacts = compatibleReasoningArtifacts({
+        providerId: options.providerId,
+        model: options.model,
+        baseUrl: options.baseUrl,
+        toolCalls,
+        policy: options.reasoningArtifactPolicy,
+        ...(typeof reasoning === "string" && reasoning
+            ? { reasoning: { text: reasoning, sequence: 0 } }
+            : {}),
+        ...(detailsRaw ? { details: [{ raw: detailsRaw, sequence: 1 }] } : {}),
+        ...(thoughtSignature
+            ? {
+                thoughtSignatures: [
+                    {
+                        raw: thoughtSignature,
+                        sequence: 2,
+                        ...(toolCalls.length ? { toolCallIndex: 0 } : {}),
+                    },
+                ],
+            }
+            : {}),
+    });
     if (typeof reasoning === "string" && reasoning.trim()) {
         learnModelEmitsReasoning(options.providerId, options.model);
     }
-    const full = foldReasoning(options.provider, requestBody, text, reasoning, usage);
     return {
-        text: full,
+        text,
         ...(toolCalls.length ? { toolCalls } : {}),
         ...(choice?.finish_reason
             ? { finishReason: choice.finish_reason }
@@ -1104,6 +1273,10 @@ export async function openAiCompatibleComplete(options) {
                 ? { finishReason: "tool_calls" }
                 : {}),
         ...(usage ? { usage } : {}),
+        ...(typeof reasoning === "string" && reasoning
+            ? { reasoningBlock: { text: reasoning } }
+            : {}),
+        ...(reasoningArtifacts ? { reasoningArtifacts } : {}),
     };
 }
 export async function openAiCompatibleStream(options) {
@@ -1184,25 +1357,27 @@ export async function openAiCompatibleStream(options) {
     };
     const onCallerAbort = () => idleController.abort(options.signal?.reason);
     options.signal?.addEventListener("abort", onCallerAbort, { once: true });
-    const supportsVision = modelAcceptsImages(options.providerId, options.model);
-    const requestBody = buildChatBody({
+    const plan = compileRequestPlan({
+        provider: options.providerId,
         model: options.model,
-        providerId: options.providerId,
         messages: options.messages,
-        maxTokens: options.maxTokens,
-        temperature: options.temperature,
         stream: true,
-        includeStreamUsage: options.includeStreamUsage,
+        endpoint: options.baseUrl,
         reasoning: options.reasoning,
-        reasoningStyle: options.reasoningStyle,
-        supportsVision,
         tools: options.tools,
         toolChoice: options.toolChoice,
         parallelToolCalls: options.parallelToolCalls,
+        temperature: options.temperature,
+        maxTokens: options.maxTokens,
+    });
+    const requestBody = chatCompletionsBodyFromPlan(plan, {
+        reasoningStyle: options.reasoningStyle,
+        includeStreamUsage: options.includeStreamUsage,
+        reasoningArtifactReplayObserver: options.reasoningArtifactReplayObserver,
     });
     let response;
     try {
-        response = await fetch(`${options.baseUrl}/chat/completions`, {
+        response = await generationFetch(`${options.baseUrl}/chat/completions`, {
             method: "POST",
             signal: idleController.signal,
             headers: {
@@ -1245,35 +1420,84 @@ export async function openAiCompatibleStream(options) {
     }
     const contentType = response.headers.get("content-type") ?? "";
     if (response.status === 202 || /\bapplication\/json\b/i.test(contentType)) {
-        clearIdleTimers();
-        options.signal?.removeEventListener("abort", onCallerAbort);
-        const data = await readJson(response);
-        if (response.status === 202) {
-            const requestId = data.requestId ?? data.id;
-            throw new ProviderError(`${options.provider} returned a pending async response${requestId ? ` (${requestId})` : ""}; streaming did not start.`, response.status, JSON.stringify(data).slice(0, 1_000));
-        }
-        const choice = data.choices?.[0];
-        const message = choice?.message;
-        const toolCalls = parseOpenAiMessageToolCalls(message?.tool_calls);
-        const text = message?.content ?? "";
-        const jsonUsage = parseOpenAiUsage(data.usage);
-        const reasoning = message?.reasoning_content ?? message?.reasoning;
-        const full = foldReasoning(options.provider, requestBody, text, reasoning, jsonUsage);
-        if (full.trim() || toolCalls.length > 0) {
-            if (full.trim())
-                options.onToken(full);
-            return {
-                text: full,
-                ...(toolCalls.length ? { toolCalls } : {}),
-                ...(choice?.finish_reason
-                    ? { finishReason: choice.finish_reason }
-                    : toolCalls.length
-                        ? { finishReason: "tool_calls" }
+        try {
+            const data = await readJson(response, idleController.signal);
+            if (response.status === 202) {
+                const requestId = data.requestId ?? data.id;
+                throw new ProviderError(`${options.provider} returned a pending async response${requestId ? ` (${requestId})` : ""}; streaming did not start.`, response.status, JSON.stringify(data).slice(0, 1_000));
+            }
+            const choice = data.choices?.[0];
+            const message = choice?.message;
+            const toolCalls = parseOpenAiMessageToolCalls(message?.tool_calls);
+            const text = message?.content ?? "";
+            const jsonUsage = options.providerId === "fireworks"
+                ? parseFireworksUsage(data.usage, data.perf_metrics, response.headers)
+                : parseOpenAiUsage(data.usage, options.usageAliases);
+            const reasoning = message?.reasoning_content ?? message?.reasoning;
+            const detailsRaw = artifactRaw(message?.reasoning_details);
+            const thoughtSignature = message?.extra_content?.google?.thought_signature;
+            const reasoningArtifacts = compatibleReasoningArtifacts({
+                providerId: options.providerId,
+                model: options.model,
+                baseUrl: options.baseUrl,
+                toolCalls,
+                policy: options.reasoningArtifactPolicy,
+                ...(typeof reasoning === "string" && reasoning
+                    ? { reasoning: { text: reasoning, sequence: 0 } }
+                    : {}),
+                ...(detailsRaw ? { details: [{ raw: detailsRaw, sequence: 1 }] } : {}),
+                ...(thoughtSignature
+                    ? {
+                        thoughtSignatures: [
+                            {
+                                raw: thoughtSignature,
+                                sequence: 2,
+                                ...(toolCalls.length ? { toolCallIndex: 0 } : {}),
+                            },
+                        ],
+                    }
+                    : {}),
+            });
+            if (text.trim() ||
+                toolCalls.length > 0 ||
+                (typeof reasoning === "string" && reasoning.trim())) {
+                emitStreamReasoningArtifacts(options.onStreamEvent, reasoningArtifacts);
+                if (text)
+                    options.onToken(text);
+                return {
+                    text,
+                    ...(toolCalls.length ? { toolCalls } : {}),
+                    ...(choice?.finish_reason
+                        ? { finishReason: choice.finish_reason }
+                        : toolCalls.length
+                            ? { finishReason: "tool_calls" }
+                            : {}),
+                    ...(jsonUsage ? { usage: jsonUsage } : {}),
+                    ...(typeof reasoning === "string" && reasoning
+                        ? { reasoningBlock: { text: reasoning } }
                         : {}),
-                ...(jsonUsage ? { usage: jsonUsage } : {}),
-            };
+                    ...(reasoningArtifacts ? { reasoningArtifacts } : {}),
+                };
+            }
+            throw new ProviderError(`${options.provider} returned JSON instead of an SSE stream, but no completion text was present.`, response.status, JSON.stringify(data).slice(0, 1_000));
+        }
+        catch (error) {
+            if (idleFired) {
+                const seconds = Math.round(firedBudgetMs / 1000);
+                if (firedWatchdog === "transport" || !sawTransportActivity) {
+                    if (!sawTransportActivity) {
+                        throw new ProviderError(`${options.provider} request timed out before any response (${seconds}s) — no data arrived on the connection.`);
+                    }
+                    throw new ProviderError(`${options.provider} stream transport timeout (${seconds}s) — no data arrived on the connection after it had started.`);
+                }
+                throw new ProviderError(`${options.provider} stream stalled — ${STREAM_STALL_MARKER} for ${seconds}s`);
+            }
+            throw error;
+        }
+        finally {
+            clearIdleTimers();
+            options.signal?.removeEventListener("abort", onCallerAbort);
         }
-        throw new ProviderError(`${options.provider} returned JSON instead of an SSE stream, but no completion text was present.`, response.status, JSON.stringify(data).slice(0, 1_000));
     }
     const decoder = new TextDecoder();
     const reader = response.body.getReader();
@@ -1283,30 +1507,63 @@ export async function openAiCompatibleStream(options) {
     let reasoningSeen = "";
     let contentWireSeen = "";
     let reasoningWireSeen = "";
-    let inReasoning = false;
     let finishReason;
-    let streamUsage;
+    let terminalSignal;
+    const terminalPolicy = options.streamTerminal ?? CHAT_COMPLETIONS_STREAM_TERMINAL;
+    const emittedByteCounts = () => {
+        let toolArgumentBytes = 0;
+        for (const state of toolCallState.values()) {
+            toolArgumentBytes += state.arguments.length;
+        }
+        return {
+            answerBytes: visible.length,
+            reasoningBytes: reasoningSeen.length,
+            toolArgumentBytes,
+        };
+    };
+    let streamUsage = options.providerId === "fireworks"
+        ? parseFireworksUsage(undefined, undefined, response.headers)
+        : undefined;
     const toolCallState = new Map();
+    let reasoningArtifactSequence;
+    let nextArtifactSequence = 0;
+    let lastToolCallIndex;
+    const structuredDetails = [];
+    const thoughtSignatures = [];
+    const pendingThoughtSignatures = [];
+    const finalReasoningArtifacts = (toolCalls) => {
+        if (pendingThoughtSignatures.length) {
+            const toolCallIndex = toolCalls.length ? 0 : undefined;
+            for (const capture of pendingThoughtSignatures.splice(0)) {
+                thoughtSignatures.push(toolCallIndex === undefined
+                    ? capture
+                    : { ...capture, toolCallIndex });
+            }
+        }
+        return compatibleReasoningArtifacts({
+            providerId: options.providerId,
+            model: options.model,
+            baseUrl: options.baseUrl,
+            toolCalls,
+            policy: options.reasoningArtifactPolicy,
+            ...(reasoningSeen
+                ? {
+                    reasoning: {
+                        text: reasoningSeen,
+                        sequence: reasoningArtifactSequence ?? 0,
+                    },
+                }
+                : {}),
+            ...(structuredDetails.length ? { details: structuredDetails } : {}),
+            ...(thoughtSignatures.length ? { thoughtSignatures } : {}),
+        });
+    };
     const normalizeChannelDelta = (token, seen) => {
         if (seen.length >= 64 && token.length >= seen.length && token.startsWith(seen)) {
             return { delta: token.slice(seen.length), seen: token };
         }
         return { delta: token, seen: seen + token };
     };
-    const enterReasoning = () => {
-        if (inReasoning)
-            return;
-        inReasoning = true;
-        full += REASONING_OPEN;
-        options.onToken(REASONING_OPEN);
-    };
-    const exitReasoning = () => {
-        if (!inReasoning)
-            return;
-        inReasoning = false;
-        full += REASONING_CLOSE;
-        options.onToken(REASONING_CLOSE);
-    };
     const emitPrivateReasoningNote = (hasToolCalls) => {
         if (reasoningSeen.trim())
             return;
@@ -1316,10 +1573,7 @@ export async function openAiCompatibleStream(options) {
         if (tokens <= 0)
             return;
         const note = privateReasoningNote(options.provider, requestBody, tokens);
-        enterReasoning();
-        full += note;
-        options.onToken(note);
-        exitReasoning();
+        emitStreamReasoningDelta(options.onStreamEvent, note);
     };
     /**
      * Reasoning-echo suppression.
@@ -1343,8 +1597,6 @@ export async function openAiCompatibleStream(options) {
     const emitVisible = (text) => {
         if (!text)
             return;
-        if (inReasoning)
-            exitReasoning();
         visible += text;
         full += text;
         options.onToken(text);
@@ -1357,9 +1609,7 @@ export async function openAiCompatibleStream(options) {
     const emitReasoningEcho = (text) => {
         if (!text)
             return;
-        enterReasoning();
-        full += text;
-        options.onToken(text);
+        emitStreamReasoningDelta(options.onStreamEvent, text);
     };
     /** Release a still-undecided hold-back as the answer (stream ended early). */
     const flushEchoBuffer = () => {
@@ -1453,11 +1703,19 @@ export async function openAiCompatibleStream(options) {
                 if (payload === undefined)
                     continue;
                 if (payload === "[DONE]") {
+                    terminalSignal = "done-sentinel";
+                    requireTerminalProof({
+                        provider: options.provider,
+                        policy: terminalPolicy,
+                        signal: terminalSignal,
+                        ...emittedByteCounts(),
+                    });
                     flushEchoBuffer();
-                    exitReasoning();
                     cleanup();
                     const toolCalls = finalizeOpenAiToolCalls(toolCallState);
                     emitPrivateReasoningNote(toolCalls.length > 0);
+                    const reasoningArtifacts = finalReasoningArtifacts(toolCalls);
+                    emitStreamReasoningArtifacts(options.onStreamEvent, reasoningArtifacts);
                     if (!visible.trim() && toolCalls.length === 0) {
                         // Thinking models (Kimi/Moonshot via Mantle, etc.) often emit only
                         // reasoning, sometimes with tool sentinels inside <think>. Returning
@@ -1468,6 +1726,8 @@ export async function openAiCompatibleStream(options) {
                                 text: full,
                                 ...(finishReason ? { finishReason } : { finishReason: "stop" }),
                                 ...(streamUsage ? { usage: streamUsage } : {}),
+                                ...(reasoningSeen ? { reasoningBlock: { text: reasoningSeen } } : {}),
+                                ...(reasoningArtifacts ? { reasoningArtifacts } : {}),
                             };
                         }
                         throw new ProviderError(`${options.provider} completed without a visible answer.`);
@@ -1481,6 +1741,8 @@ export async function openAiCompatibleStream(options) {
                                 ? { finishReason: "tool_calls" }
                                 : {}),
                         ...(streamUsage ? { usage: streamUsage } : {}),
+                        ...(reasoningSeen ? { reasoningBlock: { text: reasoningSeen } } : {}),
+                        ...(reasoningArtifacts ? { reasoningArtifacts } : {}),
                     };
                 }
                 let parsed;
@@ -1504,13 +1766,18 @@ export async function openAiCompatibleStream(options) {
                     throw new ProviderError(`${options.provider} stream error: ${detail}`, undefined, payload.slice(0, 500));
                 }
                 {
-                    const chunkUsage = parseOpenAiUsage(parsed.usage);
+                    const chunkUsage = options.providerId === "fireworks"
+                        ? parseFireworksUsage(parsed.usage, parsed.perf_metrics, response.headers)
+                        : parseOpenAiUsage(parsed.usage, options.usageAliases);
                     if (chunkUsage)
                         streamUsage = chunkUsage;
                     const choice = parsed.choices?.[0];
                     const delta = choice?.delta;
                     const reasoningToken = delta?.reasoning_content ?? delta?.reasoning;
                     const token = delta?.content;
+                    const detailRaw = artifactRaw(delta?.reasoning_details);
+                    const thoughtSignature = delta?.extra_content?.google?.thought_signature;
+                    const artifactSequence = nextArtifactSequence++;
                     const toolProgress = delta?.tool_calls?.some((toolCall) => Boolean(toolCall.id ||
                         toolCall.function?.name ||
                         toolCall.function?.arguments));
@@ -1518,63 +1785,101 @@ export async function openAiCompatibleStream(options) {
                         chunkUsage ||
                         reasoningToken ||
                         token ||
+                        detailRaw ||
+                        thoughtSignature ||
                         toolProgress) {
                         resetIdleTimer();
                     }
-                    if (choice?.finish_reason)
+                    if (choice?.finish_reason) {
                         finishReason = choice.finish_reason;
+                        terminalSignal = "finish-reason";
+                    }
                     if (reasoningToken) {
                         const normalized = normalizeChannelDelta(reasoningToken, reasoningWireSeen);
                         reasoningWireSeen = normalized.seen;
                         if (normalized.delta) {
+                            reasoningArtifactSequence ??= artifactSequence;
                             if (!reasoningSeen) {
                                 learnModelEmitsReasoning(options.providerId, options.model);
                             }
-                            enterReasoning();
                             reasoningSeen += normalized.delta;
-                            full += normalized.delta;
-                            options.onToken(normalized.delta);
+                            emitStreamReasoningDelta(options.onStreamEvent, normalized.delta);
                         }
                     }
+                    if (detailRaw) {
+                        structuredDetails.push({ raw: detailRaw, sequence: artifactSequence });
+                    }
                     if (token) {
                         const normalized = normalizeChannelDelta(token, contentWireSeen);
                         contentWireSeen = normalized.seen;
                         if (normalized.delta)
                             handleContentToken(normalized.delta);
                     }
+                    const deltaToolCallIndices = [];
                     if (delta?.tool_calls?.length) {
                         for (const tc of delta.tool_calls) {
                             const accInfo = accumulateOpenAiToolCallDelta(toolCallState, tc);
-                            if (!options.onToolCallDelta)
-                                continue;
-                            const wire = accInfo.name;
-                            const canonical = wire
-                                ? (fromWireName(wire) ?? wire)
-                                : undefined;
-                            const largeArgTick = !accInfo.nameBecameKnown &&
-                                accInfo.argumentsBytes > 0 &&
-                                accInfo.argumentsBytes % 4096 <
-                                    (typeof tc.function?.arguments === "string"
-                                        ? tc.function.arguments.length
-                                        : 0);
-                            if (accInfo.nameBecameKnown || largeArgTick) {
-                                options.onToolCallDelta({
-                                    index: accInfo.index,
-                                    ...(accInfo.id !== undefined ? { id: accInfo.id } : {}),
-                                    ...(canonical !== undefined ? { name: canonical } : {}),
-                                    argumentsBytes: accInfo.argumentsBytes,
-                                });
+                            deltaToolCallIndices.push(accInfo.index);
+                            lastToolCallIndex = accInfo.index;
+                            if (options.onToolCallDelta) {
+                                const wire = accInfo.name;
+                                const canonical = wire
+                                    ? (fromWireName(wire) ?? wire)
+                                    : undefined;
+                                const largeArgTick = !accInfo.nameBecameKnown &&
+                                    accInfo.argumentsBytes > 0 &&
+                                    accInfo.argumentsBytes % 4096 <
+                                        (typeof tc.function?.arguments === "string"
+                                            ? tc.function.arguments.length
+                                            : 0);
+                                if (accInfo.nameBecameKnown || largeArgTick) {
+                                    options.onToolCallDelta({
+                                        index: accInfo.index,
+                                        ...(accInfo.id !== undefined ? { id: accInfo.id } : {}),
+                                        ...(canonical !== undefined ? { name: canonical } : {}),
+                                        argumentsBytes: accInfo.argumentsBytes,
+                                    });
+                                }
                             }
                         }
                     }
+                    const signatureToolCallIndex = deltaToolCallIndices[0] ?? lastToolCallIndex;
+                    if (thoughtSignature) {
+                        const capture = {
+                            raw: thoughtSignature,
+                            sequence: artifactSequence,
+                            ...(signatureToolCallIndex === undefined
+                                ? {}
+                                : { toolCallIndex: signatureToolCallIndex }),
+                        };
+                        if (signatureToolCallIndex === undefined) {
+                            pendingThoughtSignatures.push(capture);
+                        }
+                        else {
+                            thoughtSignatures.push(capture);
+                        }
+                    }
+                    if (deltaToolCallIndices.length && pendingThoughtSignatures.length) {
+                        const toolCallIndex = deltaToolCallIndices[0];
+                        for (const capture of pendingThoughtSignatures.splice(0)) {
+                            thoughtSignatures.push({ ...capture, toolCallIndex });
+                        }
+                    }
                 }
             }
         }
         flushEchoBuffer();
-        exitReasoning();
         cleanup();
+        requireTerminalProof({
+            provider: options.provider,
+            policy: terminalPolicy,
+            signal: terminalSignal,
+            ...emittedByteCounts(),
+        });
         const toolCalls = finalizeOpenAiToolCalls(toolCallState);
         emitPrivateReasoningNote(toolCalls.length > 0);
+        const reasoningArtifacts = finalReasoningArtifacts(toolCalls);
+        emitStreamReasoningArtifacts(options.onStreamEvent, reasoningArtifacts);
         if (!visible.trim() && toolCalls.length === 0) {
             // See [DONE] branch — hand thinking-only streams to the runner so it can
             // salvage sentinel tool blocks (or nudge) instead of hard-failing.
@@ -1583,6 +1888,8 @@ export async function openAiCompatibleStream(options) {
                     text: full,
                     ...(finishReason ? { finishReason } : { finishReason: "stop" }),
                     ...(streamUsage ? { usage: streamUsage } : {}),
+                    ...(reasoningSeen ? { reasoningBlock: { text: reasoningSeen } } : {}),
+                    ...(reasoningArtifacts ? { reasoningArtifacts } : {}),
                 };
             }
             throw new ProviderError(`${options.provider} completed without a visible answer.`);
@@ -1596,6 +1903,8 @@ export async function openAiCompatibleStream(options) {
                     ? { finishReason: "tool_calls" }
                     : {}),
             ...(streamUsage ? { usage: streamUsage } : {}),
+            ...(reasoningSeen ? { reasoningBlock: { text: reasoningSeen } } : {}),
+            ...(reasoningArtifacts ? { reasoningArtifacts } : {}),
         };
     }
     catch (error) {