@sema-ai/core 1.275.1

package/dist/brain/openai.js

@@ -0,0 +1,784 @@
+import {} from "../internal/llm.js";
+import { repairTextToolCalls } from "./tool-call-repair.js";
+import { DEGENERATE_MESSAGE, inspectDegenerate } from "./repetition.js";
+import { WALLTIME_CUTOFF_MESSAGE } from "./walltime.js";
+import { emitBrainTelemetry } from "./status-sink.js";
+import { OPENAI_RESERVED, applyExtraBody } from "./request-params.js";
+import { DEFAULT_EFFORT_LEVELS, isThinkingLevel, resolveEffort } from "./reasoning.js";
+import { runStreamingBrain } from "./stream-engine.js";
+/**
+ * design/120 P2.0: close an accumulated tool_calls slot into a ToolCall. Returns undefined when the
+ * slot has no name or its accumulated arguments are not a valid JSON object (fail-closed: no
+ * `toolcall_end` is emitted, the call can never execute in-stream; finalize() then either retries —
+ * more deltas may have arrived — or surfaces it via the existing malformed-drop + note path).
+ * Idempotent on success (cached); a failure is NOT cached.
+ */
+function closeToolCallAccum(acc) {
+    if (acc.closedTc)
+        return acc.closedTc;
+    if (!acc.name)
+        return undefined;
+    let args;
+    if (acc.args) {
+        try {
+            const parsed = JSON.parse(acc.args);
+            // bug-hunt #6 (kept from finalize): a top-level string/array/number/null must fail closed so a
+            // non-object never reaches tool.execute / the MCP wire.
+            if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed))
+                return undefined;
+            args = parsed;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    else {
+        args = {}; // genuinely a no-argument tool call
+    }
+    if (!acc.id)
+        acc.id = `call_${Math.random().toString(36).slice(2)}`;
+    acc.closedTc = { type: "toolCall", id: acc.id, name: acc.name, arguments: args };
+    return acc.closedTc;
+}
+function textOf(content) {
+    if (typeof content === "string") {
+        return content;
+    }
+    return content
+        .filter((c) => c.type === "text" && typeof c.text === "string")
+        .map((c) => c.text)
+        .join("");
+}
+/** TB 战线逮的真 bug(pytorch-model-cli:模型 Read 了 /app/image.png → 我们塞 image_url → DeepSeek
+ *  纯文本 API 400 拒收,任务当场死):当 SERVING model 声明无视觉(`Model.input` 不含 "image")时,
+ *  图像部件降级为文本占位符,绝不发 image_url/image block。model 元数据缺席 ⇒ 维持今日行为(发图)。
+ *  按当次 model 判 = 降级链换模型也各自正确(CC 同款降级姿态)。 */
+function visionOf(model) {
+    return model?.input === undefined ? true : model.input.includes("image");
+}
+const IMAGE_OMITTED = "[image omitted: the serving model does not support image input]";
+/** PDF read: OpenAI-compatible chat APIs have NO document content block — a `document` block (base64 PDF
+ *  from the Read tool) is substituted with this honest placeholder (+ telemetry), never silently dropped
+ *  and never fake-supported. The model is told the working alternative. Degradation chain v2: the Read tool
+ *  now forks on the serving model's capabilities (pdftotext text extraction → rendered pages → placeholder),
+ *  so this brain-level guard only fires for residual paths (e.g. a mid-task failover across API families, or
+ *  a caller-injected document block). */
+const DOCUMENT_OMITTED = "[PDF document omitted: PDF direct read requires an Anthropic-family model; re-Read the file (the engine will extract text/render pages when possible) or extract the text via Bash instead (e.g. `pdftotext`).]";
+/** Build OpenAI user-message content: a plain string, or multimodal parts when images are present. */
+function toUserContent(content, supportsVision = true) {
+    if (typeof content === "string") {
+        return content;
+    }
+    const hasImage = content.some((c) => c.type === "image");
+    // PDF read: document blocks never reach an OpenAI-compatible API — count them once here and fold the
+    // honest placeholder into every return path below (string or parts), never a silent drop.
+    const nDocs = content.filter((c) => c.type === "document").length;
+    if (nDocs > 0)
+        emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
+    if (!hasImage) {
+        const base = textOf(content);
+        if (nDocs === 0)
+            return base;
+        return base ? `${base}\n${DOCUMENT_OMITTED}` : DOCUMENT_OMITTED;
+    }
+    if (!supportsVision) {
+        const n = content.filter((c) => c.type === "image").length;
+        emitBrainTelemetry({ kind: "vision_placeholder", count: n }); // [398] C4: silent quality loss → frame
+        const base = textOf(content);
+        const note = n > 1 ? `[${n} images omitted: the serving model does not support image input]` : IMAGE_OMITTED;
+        const withNote = base ? `${base}\n${note}` : note;
+        return nDocs > 0 ? `${withNote}\n${DOCUMENT_OMITTED}` : withNote;
+    }
+    const parts = [];
+    for (const c of content) {
+        if (c.type === "text" && typeof c.text === "string") {
+            parts.push({ type: "text", text: c.text });
+        }
+        else if (c.type === "image" && c.data && c.mimeType) {
+            parts.push({
+                type: "image_url",
+                image_url: { url: `data:${c.mimeType};base64,${c.data}` },
+            });
+        }
+        else if (c.type === "document") {
+            parts.push({ type: "text", text: DOCUMENT_OMITTED });
+        }
+    }
+    return parts;
+}
+function thinkingCompat(model) {
+    return (model.compat ?? {});
+}
+/**
+ * Enable thinking on the request per the model's `compat.thinkingFormat` (design/46). A bare
+ * `reasoning_effort` (the old behavior) only works for the OpenAI family; DeepSeek/Qwen/zai/etc. each
+ * need their own switch. Thinking is requested by passing a `reasoning` level; a falsy value OR the
+ * explicit `"off"` tier leaves thinking unset (absence = provider default) — the harness already maps
+ * `off → undefined`, but a direct/public caller may pass `"off"`, which must NOT become `reasoning_effort:"off"`
+ * (an invalid value). Defaults to `"openai"`, so existing configs that don't set `compat.thinkingFormat`
+ * behave exactly as before (`reasoning_effort`).
+ */
+function applyThinking(body, model, reasoning) {
+    if (!model.reasoning || !reasoning || reasoning === "off")
+        return;
+    const compat = thinkingCompat(model);
+    const supportsEffort = compat.supportsReasoningEffort ?? true; // absent = supported
+    // Clamp the requested intensity to a tier THIS endpoint's `reasoning_effort` actually accepts (design/96
+    // S5): forwarding a level the endpoint rejects ("xhigh"/"max" to stock OpenAI) 422s the whole request. Only
+    // a known ThinkingLevel is mapped; an unrecognized/legacy string passes through unchanged (back-compat).
+    const effort = isThinkingLevel(reasoning)
+        ? resolveEffort(reasoning, compat.reasoningEffortLevels ?? DEFAULT_EFFORT_LEVELS).effective
+        : reasoning;
+    // design/111 L1 — translate the (clamped) level to THIS model's provider-specific `reasoning_effort` wire
+    // value via `thinkingLevelMap`. Semantics (per the field's contract): a MISSING key ⇒ provider default (send
+    // the level name as-is = prior behavior); a STRING ⇒ that provider-specific value (e.g. a model that names
+    // its tiers differently, or wants a numeric/label form); `null` ⇒ the tier is UNSUPPORTED on this model, so
+    // send NO effort value — thinking still enables via the format's own enable key where one exists
+    // (deepseek/together/qwen), i.e. it runs at the provider default tier rather than a rejected one. Only a
+    // known ThinkingLevel is mapped; a legacy passthrough string is sent unchanged.
+    let effortWire = effort;
+    if (isThinkingLevel(effort) && model.thinkingLevelMap) {
+        const mapped = model.thinkingLevelMap[effort];
+        if (mapped === null)
+            effortWire = undefined;
+        else if (mapped !== undefined)
+            effortWire = mapped;
+    }
+    // Per the thinkingFormat spec, `deepseek` and `together` emit their enable key PLUS `reasoning_effort`
+    // (when supported) — the dual key is intentional, not a leak; a provider that doesn't take effort sets
+    // `supportsReasoningEffort: false`.
+    const format = compat.thinkingFormat ?? "openai";
+    switch (format) {
+        case "openai":
+            if (supportsEffort && effortWire !== undefined)
+                body.reasoning_effort = effortWire;
+            break;
+        case "openrouter":
+            body.reasoning = { effort: effortWire };
+            break;
+        case "deepseek":
+            body.thinking = { type: "enabled" };
+            if (supportsEffort && effortWire !== undefined)
+                body.reasoning_effort = effortWire;
+            break;
+        case "together":
+            body.reasoning = { enabled: true };
+            if (supportsEffort && effortWire !== undefined)
+                body.reasoning_effort = effortWire;
+            break;
+        case "qwen":
+        case "zai":
+            // Binary enable-only: the intensity tier is NOT honored as a gradient (resolveBinary → graded:false).
+            body.enable_thinking = true;
+            break;
+        case "qwen-chat-template": {
+            const k = (typeof body.chat_template_kwargs === "object" && body.chat_template_kwargs) || {};
+            body.chat_template_kwargs = { ...k, enable_thinking: true };
+            break;
+        }
+        default: {
+            // Exhaustiveness guard (#5 anti-drift): a thinkingFormat added upstream must declare how it enables
+            // thinking here — the `never` assignment FAILS tsc if a case is missing, so a new format can't silently
+            // disable thinking. At runtime (defensive) an unrecognized format leaves thinking unset, the safe choice
+            // (we don't know its enable key; sending the wrong one could 422 the request).
+            const _exhaustive = format;
+            void _exhaustive;
+            break;
+        }
+    }
+}
+/**
+ * Convert vendored LLM messages + system prompt into OpenAI chat-completions messages.
+ *
+ * Reasoning replay (design/46): when `replayThinking` is on (default), prior assistant `reasoning_content`
+ * is replayed **only on tool-call turns** — DeepSeek requires the thinking on a tool-call turn, while
+ * non-tool turns ignore it (so replaying there only bloats the context window for no effect; dropping it
+ * keeps the prefix lean → less compaction). Set `replayThinking: false` to never replay. When a provider
+ * needs the field present on every assistant message (`compat.requiresReasoningContentOnAssistantMessages`),
+ * an empty `reasoning_content` is emitted on non-replay turns.
+ */
+function toOpenAIMessages(ctx, replayThinking = true, model) {
+    const supportsVision = visionOf(model);
+    const out = [];
+    const needsEmptyReasoningField = !!model?.reasoning && thinkingCompat(model).requiresReasoningContentOnAssistantMessages === true;
+    if (ctx.systemPrompt) {
+        out.push({ role: "system", content: ctx.systemPrompt });
+    }
+    // design/66 image: OpenAI-compatible chat APIs accept images only on USER messages — the `tool` role
+    // is text-only — so images returned by tools are carried in a synthetic user message with a provenance
+    // marker (the standard agent-framework pattern; CC doesn't need this — the Anthropic API takes image
+    // blocks inside tool_result natively). Buffered and flushed AFTER the whole consecutive tool-result
+    // batch: strict providers reject a user message interleaved between an assistant's tool responses.
+    let pendingImages = [];
+    const flushImages = () => {
+        if (pendingImages.length === 0)
+            return;
+        const ids = [...new Set(pendingImages.map((i) => i.toolCallId))].join(", ");
+        out.push({
+            role: "user",
+            content: [
+                { type: "text", text: `[Image${pendingImages.length > 1 ? "s" : ""} from tool result ${ids}]` },
+                ...pendingImages.map((i) => ({ type: "image_url", image_url: { url: `data:${i.mimeType};base64,${i.data}` } })),
+            ],
+        });
+        pendingImages = [];
+    };
+    for (const m of ctx.messages) {
+        if (m.role !== "toolResult")
+            flushImages();
+        if (m.role === "user") {
+            out.push({ role: "user", content: toUserContent(m.content, supportsVision) });
+        }
+        else if (m.role === "assistant") {
+            const text = m.content
+                .filter((c) => c.type === "text")
+                .map((c) => c.text)
+                .join("");
+            const toolCalls = m.content.filter((c) => c.type === "toolCall");
+            const msg = { role: "assistant", content: text };
+            const reasoning = m.content
+                .filter((c) => c.type === "thinking")
+                .map((c) => c.thinking)
+                .join("");
+            // Conditional replay: only tool-call turns (where DeepSeek requires it); non-tool turns drop it.
+            if (replayThinking && reasoning && toolCalls.length > 0) {
+                msg.reasoning_content = reasoning;
+            }
+            else if (needsEmptyReasoningField) {
+                msg.reasoning_content = ""; // provider requires the field present on every assistant message
+            }
+            if (toolCalls.length > 0) {
+                msg.tool_calls = toolCalls.map((tc) => ({
+                    id: tc.id,
+                    type: "function",
+                    function: { name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) },
+                }));
+            }
+            out.push(msg);
+        }
+        else if (m.role === "toolResult") {
+            // Error tool results stay text-only (CC source messages.ts:2342: an image in an error
+            // tool_result is rejected by the API — sanitize rather than 400 forever).
+            const rawImages = !m.isError && Array.isArray(m.content)
+                ? m.content.filter((c) => c.type === "image" && typeof c.data === "string" && typeof c.mimeType === "string")
+                : [];
+            const images = supportsVision ? rawImages : [];
+            if (!supportsVision && rawImages.length > 0)
+                emitBrainTelemetry({ kind: "vision_placeholder", count: rawImages.length }); // [398] C4
+            // PDF read: no document block on this API family — replace with the honest placeholder + telemetry.
+            const nDocs = Array.isArray(m.content) ? m.content.filter((c) => c.type === "document").length : 0;
+            if (nDocs > 0)
+                emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
+            const baseText0 = textOf(m.content);
+            const baseText = nDocs > 0 ? (baseText0 ? `${baseText0}\n${DOCUMENT_OMITTED}` : DOCUMENT_OMITTED) : baseText0;
+            const text = !supportsVision && rawImages.length > 0 ? (baseText ? `${baseText}\n${IMAGE_OMITTED}` : IMAGE_OMITTED) : baseText;
+            out.push({
+                role: "tool",
+                tool_call_id: m.toolCallId,
+                content: toolResultText(text, images.length > 0, m.content),
+            });
+            for (const img of images)
+                pendingImages.push({ toolCallId: m.toolCallId, data: img.data, mimeType: img.mimeType });
+        }
+    }
+    flushImages();
+    return out;
+}
+/**
+ * The `tool` role message's text (council #1/Q1): three outcomes, made explicit —
+ *  1. the result had text → that text;
+ *  2. no text but images travel in the follow-up user message → a pointer sentinel;
+ *  3. no text and nothing travels (an ERROR result whose only content was images, stripped by the
+ *     CC image-in-error rule) → a non-empty placeholder, since a strictly-validating
+ *     OpenAI-compatible gateway may reject an empty-string tool content with a 400.
+ */
+function toolResultText(text, hasCarriedImages, original) {
+    if (text !== "")
+        return text;
+    if (hasCarriedImages)
+        return "(image attached below)";
+    return Array.isArray(original) && original.length > 0 ? "(non-text tool result omitted)" : "";
+}
+function toOpenAITools(ctx) {
+    if (!ctx.tools || ctx.tools.length === 0) {
+        return undefined;
+    }
+    return ctx.tools.map((t) => ({
+        type: "function",
+        function: { name: t.name, description: t.description, parameters: t.parameters },
+    }));
+}
+function mapFinishReason(reason, hadToolCalls) {
+    // toolUse iff tool calls actually SURVIVED accumulation (hadToolCalls). E2: a raw finish_reason of
+    // "tool_calls" must NOT independently force toolUse — a provider can report "tool_calls" while every call
+    // was dropped (e.g. a delta carrying id/args but never a `name` → the `if (!acc.name) continue` path, which
+    // unlike a malformed-JSON drop registers no toolError), and handing the harness a tool-use turn with ZERO
+    // tool calls hangs it. With no surviving calls a "tool_calls" finish degrades to a plain "stop".
+    if (hadToolCalls) {
+        return "toolUse";
+    }
+    if (reason === "length") {
+        return "length";
+    }
+    return "stop";
+}
+function computeUsage(model, raw) {
+    const input = raw?.prompt_tokens ?? 0;
+    const output = raw?.completion_tokens ?? 0;
+    const total = raw?.total_tokens ?? input + output;
+    // Prompt tokens served from the server-side prefix cache (a cache HIT). vLLM/OpenAI expose it as
+    // `prompt_tokens_details.cached_tokens`; DeepSeek as `prompt_cache_hit_tokens` (borrowed from
+    // CodeWhale's client.rs). Surfaced so a caller can see real cache effectiveness from the response.
+    const cacheRead = raw?.prompt_tokens_details?.cached_tokens ?? raw?.prompt_cache_hit_tokens ?? 0;
+    const c = model.cost;
+    const costInput = (input / 1e6) * (c?.input ?? 0);
+    const costOutput = (output / 1e6) * (c?.output ?? 0);
+    return {
+        input,
+        output,
+        cacheRead,
+        cacheWrite: 0,
+        totalTokens: total,
+        cost: { input: costInput, output: costOutput, cacheRead: 0, cacheWrite: 0, total: costInput + costOutput },
+    };
+}
+/**
+ * Create a Brain that talks to an OpenAI-compatible chat-completions endpoint (your model gateway).
+ * Translates the unified Context into an OpenAI request and the streamed response back into the unified
+ * AssistantMessageEvent protocol, including native tool calls. The connect/retry/timeout/read-loop
+ * machinery lives in the shared {@link runStreamingBrain} engine (design/32); this adapter owns the
+ * OpenAI request shaping + chat-completions SSE parsing + finalization.
+ */
+export function createOpenAIBrain(config = {}) {
+    const doFetch = config.fetchImpl ?? fetch;
+    const stream = (model, context, options) => runStreamingBrain({
+        model,
+        doFetch,
+        signal: options?.signal,
+        config,
+        httpLabel: "gateway",
+        buildRequest: () => {
+            const apiKey = options?.apiKey ?? config.apiKey;
+            const root = (model.baseUrl || config.baseUrl || "").replace(/\/+$/, "");
+            if (!root) {
+                throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
+            }
+            const body = {
+                model: model.id,
+                messages: toOpenAIMessages(context, config.replayThinking, model),
+                stream: true,
+                stream_options: { include_usage: true },
+            };
+            const tools = toOpenAITools(context);
+            if (tools)
+                body.tools = tools;
+            if (options?.temperature !== undefined)
+                body.temperature = options.temperature;
+            if (options?.maxTokens !== undefined) {
+                // design/119 #3: honor the declared field name (the knob existed but was never read —
+                // newer stock-OpenAI models take max_completion_tokens). Default keeps the prior wire shape.
+                const mtField = (model.compat ?? {}).maxTokensField;
+                body[mtField ?? "max_tokens"] = options.maxTokens;
+            }
+            if (options?.stop)
+                body.stop = options.stop;
+            applyThinking(body, model, options?.reasoning);
+            // User-supplied headers (model/config/options) augment the request; the structural + auth headers
+            // are hard-locked AFTER the spreads so they can NEVER be overridden (council design/40 security).
+            const headers = {
+                ...model.headers,
+                ...config.headers,
+                ...options?.headers,
+            };
+            headers["content-type"] = "application/json";
+            if (apiKey)
+                headers["authorization"] = `Bearer ${apiKey}`;
+            return { url: `${root}/chat/completions`, headers, body: JSON.stringify(applyExtraBody(body, model.extraBody, OPENAI_RESERVED)) };
+        },
+        makeParser: (ctrl) => {
+            const { out, partial } = ctrl;
+            let accumText = "";
+            let accumReasoning = "";
+            let accumRefusal = ""; // CC-parity B3: a policy refusal streamed in delta.refusal
+            let degenerate = false; // tripped if the model loops on the same char/phrase forever
+            // Repetition telemetry (clay 2026-07-10): the cut event + allowance-spared hits for THIS stream.
+            // Polls re-inspect the same growing text every ~64 chars — dedupe spared by rule+segment so one
+            // boot block doesn't log once per poll. Attached to the final message as `repetition`.
+            let repCut;
+            const repSpared = new Map();
+            const pollRepetition = (text) => {
+                const insp = inspectDegenerate(text);
+                for (const s of insp.spared) {
+                    const k = `${s.rule} ${s.segment}`;
+                    const prev = repSpared.get(k);
+                    if (prev === undefined)
+                        repSpared.set(k, s);
+                    else if (s.reps > prev.reps)
+                        prev.reps = s.reps; // keep the loop's PEAK depth across polls
+                }
+                if (insp.degenerate)
+                    repCut = insp.cut;
+                return insp.degenerate;
+            };
+            // design/130 P2b: tripped when the wall clock crossed the soft per-call deadline — a
+            // DELIBERATE cut like `degenerate` (salvage the prefix; the loop drives a write-out turn).
+            let walltimeCut = false;
+            const callDeadlineMs = options?.callDeadlineMs;
+            let lastDegenCheck = 0;
+            let lastDegenCheckReasoning = 0; // bug-hunt #4: separate cursor for the reasoning accumulator
+            const detectRep = config.detectRepetition !== false;
+            let emittedTextStart = false;
+            let emittedThinkingStart = false;
+            let thinkingClosed = false;
+            let textIndex = 0;
+            const toolAccum = new Map();
+            let finishReason = null;
+            let usageRaw;
+            // Reuse one block object per stream (mutated in place) instead of allocating a fresh full-text
+            // snapshot array on every delta — the per-delta `partial` would otherwise carry the whole
+            // text-so-far, making a long stream O(n²) in allocation.
+            const thinkingBlock = { type: "thinking", thinking: "" };
+            const textBlock = { type: "text", text: "" };
+            const pushReasoningDelta = (delta) => {
+                if (!delta)
+                    return;
+                ctrl.sawContentToken(); // a thinking delta counts as the first token for reasoning models (O5)
+                if (thinkingClosed)
+                    return; // ignore reasoning after the thinking block closed (interleaved)
+                if (!emittedThinkingStart) {
+                    emittedThinkingStart = true;
+                    partial.content = [thinkingBlock];
+                    out.push({ type: "thinking_start", contentIndex: 0, partial: { ...partial } });
+                }
+                accumReasoning += delta;
+                thinkingBlock.thinking = accumReasoning;
+                out.push({ type: "thinking_delta", contentIndex: 0, delta, partial: { ...partial } });
+                // bug-hunt #4: a reasoning model can loop FOREVER inside reasoning_content with NO answer text.
+                // The text path (pushTextDelta) polls looksDegenerate, but reasoning had no tripwire — on a
+                // no-timeoutSec config that is an unbounded cost window; on the leader path it only aborts after
+                // ~24h mislabeled as `timeout` instead of a cheap `degenerate` cut. Poll the reasoning tail on the
+                // same ~64-char cadence; on a hit, cut the stream (the `degenerate` flag drives the error path).
+                if (detectRep && !degenerate && accumReasoning.length - lastDegenCheckReasoning >= 64) {
+                    lastDegenCheckReasoning = accumReasoning.length;
+                    if (pollRepetition(accumReasoning)) {
+                        degenerate = true;
+                        ctrl.cancel();
+                    }
+                }
+            };
+            const closeThinking = () => {
+                if (emittedThinkingStart && !thinkingClosed) {
+                    thinkingClosed = true;
+                    out.push({ type: "thinking_end", contentIndex: 0, content: accumReasoning, partial: { ...partial } });
+                }
+            };
+            const pushTextDelta = (delta) => {
+                if (!delta)
+                    return;
+                ctrl.sawContentToken();
+                if (!emittedTextStart) {
+                    closeThinking();
+                    emittedTextStart = true;
+                    textIndex = emittedThinkingStart ? 1 : 0;
+                    partial.content = [textBlock];
+                    out.push({ type: "text_start", contentIndex: textIndex, partial: { ...partial } });
+                }
+                accumText += delta;
+                textBlock.text = accumText;
+                out.push({ type: "text_delta", contentIndex: textIndex, delta, partial: { ...partial } });
+                // Poll for degenerate repetition every ~64 chars; on a hit, cancel the stream (read loop ends).
+                if (detectRep && !degenerate && accumText.length - lastDegenCheck >= 64) {
+                    lastDegenCheck = accumText.length;
+                    if (pollRepetition(accumText)) {
+                        degenerate = true;
+                        ctrl.cancel();
+                    }
+                }
+            };
+            return {
+                // design/124 §0.5-2: tiering introspection — direct reads off the closure accumulators.
+                // A streamed refusal counts as substantive (fail-closed: finalize routes it to the
+                // `refused` error path; retrying a policy refusal would just re-pay for the same refusal).
+                snapshot() {
+                    const hasCompletedToolCall = [...toolAccum.values()].some((a) => a.closedTc !== undefined);
+                    const hasSubstantiveText = accumText.trim() !== "" || accumRefusal.trim() !== "";
+                    return {
+                        hasSubstantiveText,
+                        hasCompletedToolCall,
+                        hasOnlyThinking: accumReasoning.length > 0 && !hasSubstantiveText && !hasCompletedToolCall,
+                    };
+                },
+                // design/124 tier B: close the open thinking block (thinking_end at index 0) so the UI
+                // stream is sealed before the whole turn is re-sent. Idempotent via `thinkingClosed`.
+                sealForRetry() {
+                    closeThinking();
+                },
+                onLine(rawLine) {
+                    // design/130 P2b: poll the soft call deadline once per provider chunk (cheap — one
+                    // Date.now()). Crossing it cancels the stream deliberately; the salvage below keeps
+                    // the prefix and the sentinel errorMessage drives the loop's bounded write-out turn.
+                    // (A fully-stalled stream emits no chunks — the engine's idle watchdog owns that case.)
+                    if (callDeadlineMs !== undefined && !walltimeCut && !degenerate && Date.now() >= callDeadlineMs) {
+                        walltimeCut = true;
+                        ctrl.cancel();
+                        return; // codex HIGH: do NOT parse the triggering chunk — its delta must not join the salvage
+                    }
+                    if (walltimeCut)
+                        return; // any residual buffered line after the cut is equally dropped
+                    const line = rawLine.trim();
+                    if (!line.startsWith("data:"))
+                        return;
+                    const data = line.slice(5).trim();
+                    if (!data || data === "[DONE]")
+                        return;
+                    let chunk;
+                    try {
+                        chunk = JSON.parse(data);
+                    }
+                    catch {
+                        return;
+                    }
+                    if (chunk.usage)
+                        usageRaw = chunk.usage;
+                    const choice = chunk.choices?.[0];
+                    if (!choice)
+                        return;
+                    if (choice.finish_reason)
+                        finishReason = choice.finish_reason;
+                    const delta = choice.delta;
+                    // `reasoning` and `reasoning_content` are cross-provider aliases for the same stream — a gateway that
+                    // mirrors BOTH in one chunk must not double-count it. Prefer `reasoning`, else `reasoning_content`.
+                    if (delta?.reasoning)
+                        pushReasoningDelta(delta.reasoning);
+                    else if (delta?.reasoning_content)
+                        pushReasoningDelta(delta.reasoning_content);
+                    if (delta?.refusal) {
+                        // E1: a refusal token IS the first/next token of this stream. Without resetting the
+                        // first-token/idle watchdog, a refusal-only stream (no content/reasoning/tool_calls ever)
+                        // leaves the timers armed → a spurious `[network] first-token timeout` that mislabels (and
+                        // retries) a policy refusal instead of landing on the intended fail-closed `refused` path.
+                        ctrl.sawContentToken();
+                        accumRefusal += delta.refusal; // CC-parity B3
+                    }
+                    if (delta?.content)
+                        pushTextDelta(delta.content);
+                    if (delta?.tool_calls) {
+                        ctrl.sawContentToken();
+                        for (const tc of delta.tool_calls) {
+                            // Some gateways omit `index` for parallel tool calls — `tc.index ?? 0` would collapse them all into
+                            // slot 0 (overwriting id/name, concatenating args). A new tool call always carries an `id`, so
+                            // allocate a fresh slot on id and route an id-less continuation fragment to the most recent slot.
+                            const idx = tc.index ?? (tc.id ? toolAccum.size : Math.max(0, toolAccum.size - 1));
+                            if (!toolAccum.has(idx)) {
+                                // design/120 P2.0: a NEW slot opening means every lower slot's argument stream is
+                                // complete (the OpenAI wire streams tool calls in index order) — close them and emit
+                                // `toolcall_end` so an in-stream executor (agent-loop P2) can start those calls while
+                                // the rest of the response is still streaming. Fail-closed: if an interleaving gateway
+                                // violates the order assumption, the early parse fails, nothing is emitted (failures
+                                // are not cached), and finalize() retries with the full accumulation — behavior then
+                                // degrades to the pre-P2 batch path, never to a malformed execution.
+                                for (const [prevIdx, prevAcc] of [...toolAccum.entries()].sort((a, b) => a[0] - b[0])) {
+                                    if (prevIdx >= idx || prevAcc.closedTc)
+                                        continue;
+                                    // codex review BLOCKER-1: a slot with EMPTY args must NOT close early. An
+                                    // interleaving gateway can open index 1 while index 0 has only streamed its
+                                    // name — empty args would "successfully" close as a no-argument call `{}`,
+                                    // cache it, and the real argument deltas arriving later would be lost (finalize
+                                    // returns the cache) — wrong in-stream input AND a default-OFF regression. A
+                                    // NON-empty accumulation that parses is self-delimiting (a complete JSON object
+                                    // admits no legal continuation fragments), so closing it early is safe; no-arg
+                                    // calls simply wait for finalize like trailing calls.
+                                    if (prevAcc.args === "")
+                                        continue;
+                                    const closed = closeToolCallAccum(prevAcc);
+                                    if (closed) {
+                                        out.push({ type: "toolcall_end", contentIndex: prevIdx, toolCall: closed, partial: { ...partial } });
+                                    }
+                                }
+                            }
+                            const acc = toolAccum.get(idx) ?? { id: "", name: "", args: "" };
+                            if (tc.id)
+                                acc.id = tc.id;
+                            if (tc.function?.name)
+                                acc.name = tc.function.name;
+                            // Once a slot closed early (non-empty, complete JSON — self-delimiting), a further
+                            // fragment for it would make the concatenation unparseable; the cached call is the
+                            // only self-consistent reading, and the emitted toolcall_end may already be
+                            // executing. Drop such protocol-violating late fragments instead of accumulating a
+                            // divergence between the cache and finalize (codex review BLOCKER-1 defense belt).
+                            if (tc.function?.arguments && !acc.closedTc)
+                                acc.args += tc.function.arguments;
+                            toolAccum.set(idx, acc);
+                        }
+                    }
+                },
+                finalize() {
+                    closeThinking();
+                    if (emittedTextStart) {
+                        out.push({ type: "text_end", contentIndex: textIndex, content: accumText, partial: { ...partial } });
+                    }
+                    const finalContent = [];
+                    // audit A-5: persist the reasoning as a thinking block (BEFORE text, aligned with the
+                    // anthropic brain). The harness stores this FINAL message in the session, so without it
+                    // the `replayThinking` path (file-header note: DeepSeek REQUIRES reasoning_content on
+                    // tool-call turns) could never fire for messages this brain itself produced — the replay
+                    // filter looks for `type:"thinking"` blocks that were never there (tests passed only on
+                    // hand-built messages). Non-replaying providers are unaffected: toOpenAIMessages only
+                    // serializes thinking when the model's compat opts in.
+                    if (accumReasoning)
+                        finalContent.push({ type: "thinking", thinking: accumReasoning });
+                    if (accumText)
+                        finalContent.push({ type: "text", text: accumText });
+                    const toolCalls = [];
+                    const malformed = [];
+                    for (const acc of [...toolAccum.entries()].sort((a, b) => a[0] - b[0]).map((e) => e[1])) {
+                        if (!acc.name)
+                            continue;
+                        // design/120 P2.0: parse/id logic lives in closeToolCallAccum (shared with the in-stream
+                        // `toolcall_end` emission at slot-open — same parse discipline, same cached ToolCall
+                        // object, so a streamed id and the final content id can never diverge). A slot not yet
+                        // closed (trailing call — its stream only "ends" at finish, or an early close that
+                        // failed) is closed HERE but deliberately WITHOUT emitting toolcall_end: finalize also
+                        // runs on error finals, and emitting an addTool signal one tick before `error` would
+                        // start a tool the terminal path then has to settle — for zero streaming benefit (the
+                        // response is already over). The provider contract stays one-directional: every emitted
+                        // toolcall_end appears in the done content; not every content call emitted an event
+                        // (trailing calls and text-repair calls below run on the batch path).
+                        const tc = closeToolCallAccum(acc);
+                        if (tc) {
+                            toolCalls.push(tc);
+                            finalContent.push(tc);
+                        }
+                        else {
+                            // Truncated/invalid arguments (common on finish_reason="length") or a non-object top
+                            // level. Do NOT execute the tool with empty `{}` — surface it instead.
+                            malformed.push(`${acc.name}(${acc.args.slice(0, 200)})`);
+                        }
+                    }
+                    // Opt-in: recover tool calls a weak model emitted as text.
+                    if (config.repairTextToolCalls && toolCalls.length === 0 && accumText && context.tools && context.tools.length > 0) {
+                        const names = new Set(context.tools.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+                        const repaired = repairTextToolCalls(accumText, names);
+                        if (repaired.toolCalls.length > 0) {
+                            finalContent.length = 0;
+                            if (accumReasoning)
+                                finalContent.push({ type: "thinking", thinking: accumReasoning }); // A-5: survive the rebuild
+                            if (repaired.cleanedText)
+                                finalContent.push({ type: "text", text: repaired.cleanedText });
+                            for (const tc of repaired.toolCalls) {
+                                finalContent.push(tc);
+                                toolCalls.push(tc);
+                            }
+                        }
+                    }
+                    const toolError = malformed.length > 0
+                        ? `tool call argument(s) not valid JSON (likely truncated, finish_reason="${finishReason ?? "?"}"): ${malformed.join("; ")}`
+                        : undefined;
+                    const noUsableContent = toolCalls.length === 0 && !accumText.trim();
+                    // bug-hunt #2: a PARTIAL tool batch — at least one valid call AND a truncated one (a parallel
+                    // batch cut at the last token by finish_reason="length"). The valid call(s) must still execute
+                    // (failing the whole task over a recoverable truncation would discard real work — and a brain
+                    // `error` is a TERMINAL task failure here, not a re-prompt), but the dropped call used to vanish
+                    // silently (its error rode the `done` event, which the assembler reads only on error turns). Make
+                    // the loss VISIBLE in the assistant content so the model re-issues it next turn.
+                    // Make the dropped call(s) visible whenever ANY were malformed — INCLUDING the case where no call
+                    // survived but there IS text (the `toolCalls.length > 0` guard left that path silent → a clean
+                    // `done`, so the loop saw zero tool calls and ended the task with the text as a final answer, the
+                    // intended action lost with zero signal). The note in the assistant content surfaces the loss.
+                    if (toolError !== undefined) {
+                        finalContent.push({
+                            type: "text",
+                            text: `\n[note: ${malformed.length} tool call(s) were truncated (finish_reason="${finishReason ?? "?"}") and dropped — re-issue them next turn: ${malformed.join("; ")}]`,
+                        });
+                    }
+                    // A "length" cutoff that produced NO answer text (verbose reasoning ate the whole budget) is a
+                    // real failure, not an empty "success" — surface it like a malformed-tool turn.
+                    const truncatedEmpty = finishReason === "length" && noUsableContent && !toolError;
+                    // service [405] P0: under a DYNAMICALLY shrunk cap (design/130 P1) the truncation is the
+                    // ENGINE's own doing, not a deployment mistake — fail-louding it turned a recoverable
+                    // reasoning cut into a dead turn (TB full-89: 14 calls, two solved tasks lost). Degrade to
+                    // a plain `length` stop: the loop's truncated-output continue picks it up, and the runtime
+                    // reasoning observation exempts the NEXT call from the cap. Static caps keep bug-hunt
+                    // F2b's fail-loud (a config error should stay loud).
+                    const dynamicCut = truncatedEmpty && options?.maxTokensDynamic === true;
+                    // bug-hunt #3: a provider SAFETY cut (finish_reason="content_filter") censors/truncates output
+                    // for policy — `mapFinishReason` collapsed it to a clean "stop", reporting a compromised turn as
+                    // success (the silent false-negative class). Fail closed even if partial text was produced.
+                    const safetyCut = finishReason === "content_filter";
+                    // CC-parity B3: OpenAI streams a policy REFUSAL in `delta.refusal` and normally finishes
+                    // `finish_reason:"stop"` (not content_filter) — so without this it lands as a clean empty "stop"
+                    // success with the refusal text dropped. Fail closed (parity with anthropic's stop_reason="refusal").
+                    const refused = accumRefusal.trim().length > 0;
+                    // bug-hunt #8: a conforming provider ALWAYS closes a stream with a finish_reason. No usable
+                    // content AND no finish_reason ⇒ a torn stream or an in-band error frame `onLine` swallowed
+                    // (catch→return) — must NOT surface as an empty "stop" success. (A degenerate cut cancels
+                    // deliberately and always carries content, so it is excluded.)
+                    const emptyNoFinish = noUsableContent && finishReason == null && !degenerate && !walltimeCut;
+                    // P2b: `walltimeCut` wins the whole chain — the cut is OURS (deliberate, wall-clock), so no
+                    // downstream cause may re-attribute it; the sentinel must survive verbatim for the loop's
+                    // write-out recovery + the assembler's timeout-with-salvage mapping.
+                    // `degenerate` wins over `toolError` (design/39 + council): when a turn both loops AND emits a
+                    // malformed tool call, the loop is the root cause → `DEGENERATE_MESSAGE` must survive so the
+                    // assembler maps it to `output.degenerate` + salvages the text (the tool-error string is dropped).
+                    // `toolError` is INTENTIONALLY chosen ahead of `emptyNoFinish` (cross-model review): on the rare
+                    // collision (a malformed tool call + a torn stream) the tool-error string names the tool and already
+                    // signals the missing close via `finish_reason="?"` — strictly more specific than the generic frame.
+                    const errorMessage = walltimeCut
+                        ? WALLTIME_CUTOFF_MESSAGE
+                        : degenerate
+                            ? DEGENERATE_MESSAGE
+                            : safetyCut
+                                ? `response cut by the provider content filter (finish_reason="content_filter") — the output was censored/truncated for policy and is unreliable`
+                                : refused
+                                    ? `response refused by the model for policy reasons: ${accumRefusal.trim()}`
+                                    : (toolError ??
+                                        (truncatedEmpty && !dynamicCut
+                                            ? accumReasoning.trim()
+                                                ? `response truncated at max_tokens (finish_reason="length") with no answer text — the model spent the whole budget on reasoning (${accumReasoning.length} reasoning chars). Raise max_tokens, or disable thinking for this task.`
+                                                : `response truncated at max_tokens (finish_reason="length") with no answer text — raise max_tokens`
+                                            : emptyNoFinish
+                                                ? `model stream ended with no content and no finish_reason — the response was lost (a torn stream or an in-band provider error frame)`
+                                                : undefined));
+                    const errored = walltimeCut ||
+                        degenerate ||
+                        safetyCut ||
+                        refused ||
+                        emptyNoFinish ||
+                        (toolError !== undefined && noUsableContent) ||
+                        (truncatedEmpty && !dynamicCut);
+                    // Structured cause, mirroring the errorMessage precedence chain: tagged ONLY when truncatedEmpty
+                    // is the selected cause, so callers can escalate max_tokens without parsing prose.
+                    const errorKind = !walltimeCut && !degenerate && !safetyCut && !refused && toolError === undefined && truncatedEmpty && !dynamicCut
+                        ? "length_empty"
+                        : undefined;
+                    const finalMessage = {
+                        ...partial,
+                        content: finalContent.length > 0 ? finalContent : [{ type: "text", text: "" }],
+                        stopReason: errored ? "error" : mapFinishReason(finishReason, toolCalls.length > 0),
+                        usage: computeUsage(model, usageRaw),
+                        ...(usageRaw === undefined ? { usageMissing: true } : {}), // T1-5: no provider frame → UNKNOWN, not zero
+                        timestamp: Date.now(),
+                        ...(errorMessage ? { errorMessage } : {}),
+                        ...(errorKind ? { errorKind } : {}),
+                        // Repetition telemetry: cut event + allowance-spared hits (deduped) observed on this stream.
+                        ...(repCut !== undefined || repSpared.size > 0
+                            ? { repetition: { ...(repCut !== undefined ? { cut: repCut } : {}), ...(repSpared.size > 0 ? { spared: [...repSpared.values()] } : {}) } }
+                            : {}),
+                    };
+                    if (errored) {
+                        out.push({ type: "error", reason: "error", error: finalMessage });
+                    }
+                    else {
+                        out.push({
+                            type: "done",
+                            reason: finalMessage.stopReason,
+                            message: finalMessage,
+                        });
+                    }
+                },
+            };
+        },
+    });
+    return { stream };
+}
+//# sourceMappingURL=openai.js.map