@sema-agent/core 7.48.0 → 7.49.0

package/dist/brain/open-responses.js

@@ -1,12 +1,13 @@
 import {} from "../internal/llm.js";
 import { BrainError } from "./errors.js";
 import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
-import { STREAM_TORN_WARNING, createRepetitionPoll, noteResponseModel, parseStreamedToolArgs, placeTurnNotes } from "./stream-shared.js";
+import { STREAM_TORN_WARNING, createRepetitionPoll, modelOutputInvalidOf, noteResponseModel, nameMissingCause, parseStreamedToolArgs, placeTurnNotes } from "./stream-shared.js";
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { requestRouteOf } from "./request-route.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
@@ -199,12 +200,12 @@ function responsesErrorCode(code) {
 const INCOMPLETE_MAX_OUTPUT_TOKENS = "max_output_tokens";
 const INCOMPLETE_CONTENT_FILTER = "content_filter";
 const RESPONSE_INCOMPLETE_WARNING = 'The response above may be incomplete: the endpoint reported status "incomplete" with no reason this client recognises.';
-function closeFunctionCall(acc, responseIds) {
+function closeFunctionCall(acc, responseIds, closed) {
     if (acc.closedTc)
         return acc.closedTc;
     if (!acc.name)
         return undefined;
-    const args = parseStreamedToolArgs(acc.args);
+    const args = parseStreamedToolArgs(acc.args, closed);
     if (args === undefined)
         return undefined;
     const { engineId, wireId } = admitToolCallId(acc.callId, "call_", responseIds);
@@ -237,7 +238,7 @@ export function createOpenResponsesBrain(config = {}) {
             maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const root = resolveRequestRoot(model.baseUrl, config.baseUrl);
+                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl);
                 if (!root) {
                     throw new Error("createOpenResponsesBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
                 }
@@ -288,11 +289,13 @@ export function createOpenResponsesBrain(config = {}) {
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
-                const wire = applyExtraBody(body, model.extraBody, RESPONSES_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, RESPONSES_RESERVED);
                 return {
                     url: joinRequestUrl(root, "/responses"),
                     headers,
                     body: JSON.stringify(wire),
+                    extraBodyDropped,
+                    route: requestRouteOf(routeCredential, rootOrigin),
                     outputCapTokens: effectiveOutputCap(wire, OUTPUT_CAP_KEYS.responses),
                     capDerivedPaths: OUTPUT_CAP_KEYS.responses,
                     onCommitted: () => {
@@ -343,7 +346,7 @@ export function createOpenResponsesBrain(config = {}) {
                     }
                 };
                 const openItem = (index, kind, itemId) => {
-                    const acc = { kind, text: "", itemId, callId: "", name: "", args: "", closed: false };
+                    const acc = { kind, text: "", itemId, callId: "", name: "", args: "", closed: false, itemDone: false };
                     items.set(index, acc);
                     return acc;
                 };
@@ -413,7 +416,7 @@ export function createOpenResponsesBrain(config = {}) {
                             out.push({ type: "text_end", contentIndex: index, content: messageFace(acc), partial: { ...partial } });
                     }
                     else {
-                        const tc = closeFunctionCall(acc, responseIds);
+                        const tc = closeFunctionCall(acc, responseIds, true);
                         if (tc)
                             out.push({ type: "toolcall_end", contentIndex: index, toolCall: tc, partial: { ...partial } });
                     }
@@ -544,6 +547,7 @@ export function createOpenResponsesBrain(config = {}) {
                             }
                             if (!acc.itemId && frame.item?.id)
                                 acc.itemId = frame.item.id;
+                            acc.itemDone = true;
                             closeItem(index, acc);
                             return;
                         }
@@ -631,6 +635,7 @@ export function createOpenResponsesBrain(config = {}) {
                         const unnamed = [];
                         let anyText = false;
                         let reasoningSeen = false;
+                        const endedCut = terminalStatus === undefined || terminalStatus === "incomplete";
                         for (const [, acc] of [...items.entries()].sort((a, b) => a[0] - b[0])) {
                             if (acc.kind === "reasoning") {
                                 if (acc.text.length === 0)
@@ -651,7 +656,8 @@ export function createOpenResponsesBrain(config = {}) {
                                 }
                             }
                             else {
-                                const tc = closeFunctionCall(acc, responseIds);
+                                const closed = acc.itemDone || !endedCut;
+                                const tc = closeFunctionCall(acc, responseIds, closed);
                                 if (tc) {
                                     toolCalls.push(tc);
                                     finalContent.push(tc);
@@ -660,7 +666,7 @@ export function createOpenResponsesBrain(config = {}) {
                                     malformed.push(`${acc.name}(${acc.args.slice(0, MALFORMED_ARGS_CHARS)})`);
                                 }
                                 else {
-                                    unnamed.push(`call_id="${acc.callId || "?"}"(${acc.args.slice(0, MALFORMED_ARGS_CHARS)})`);
+                                    (nameMissingCause(closed) === "truncated" ? malformed : unnamed).push(`call_id="${acc.callId || "?"}"(${acc.args.slice(0, MALFORMED_ARGS_CHARS)})`);
                                 }
                             }
                         }
@@ -728,6 +734,8 @@ export function createOpenResponsesBrain(config = {}) {
                             : !safetyCut && !refused && toolError === undefined && truncatedEmpty && !dynamicCut && !staticReasoningCut
                                 ? "length_empty"
                                 : undefined;
+                        const capFacts = { capStop: truncated, outputTokens: usageRaw?.output_tokens, capTokens: sentMaxTokens };
+                        const modelOutputInvalid = errored && toolError !== undefined && !degenerate && !safetyCut && !refused ? modelOutputInvalidOf({ truncated: malformed.length, unnamed: unnamed.length }, capFacts) : undefined;
                         const diagnostics = capabilityNotes.length > 0
                             ? [...(partial.diagnostics ?? []), { type: CAPABILITY_DIAGNOSTIC_TYPE, timestamp: Date.now(), details: { notes: [...capabilityNotes] } }]
                             : [];
@@ -741,6 +749,7 @@ export function createOpenResponsesBrain(config = {}) {
                             ...(responseId !== undefined ? { responseId } : {}),
                             ...(errorMessageOut ? { errorMessage: errorMessageOut } : {}),
                             ...(errorKind ? { errorKind } : {}),
+                            ...(modelOutputInvalid !== undefined ? { modelOutputInvalid } : {}),
                             ...(tornWithContent ? { partialFinalized: true } : {}),
                             ...(rep.cut !== undefined || rep.spared.length > 0
                                 ? { repetition: { ...(rep.cut !== undefined ? { cut: rep.cut } : {}), ...(rep.spared.length > 0 ? { spared: rep.spared } : {}) } }

package/dist/brain/openai.js

@@ -1,23 +1,25 @@
 import {} from "../internal/llm.js";
 import { repairTextToolCalls } from "./tool-call-repair.js";
 import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
-import { STREAM_TORN_WARNING, createRepetitionPoll, noteResponseModel, parseStreamedToolArgs, placeTurnNotes, truncationCauseClause } from "./stream-shared.js";
+import { STREAM_TORN_WARNING, createRepetitionPoll, createStreamEndLedger, echoFoldedWord, modelOutputInvalidOf, noteResponseModel, nameMissingCause, parseStreamedToolArgs, placeTurnNotes, truncationCauseClause } from "./stream-shared.js";
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders } from "./request-params.js";
-import { BrainError } from "./errors.js";
-import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRoot, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { BrainError, providerErrorWord } from "./errors.js";
+import { inBandProviderError } from "./provider-dialect.js";
+import { adjudicateModelRoute, applyRouteCredentialHeaders, assertServableRequestRoot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential, routeRefusalText } from "./route-adjudicator.js";
+import { requestRouteOf } from "./request-route.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
 import { resolveFetch } from "./transport.js";
-function closeToolCallAccum(acc, responseIds) {
+function closeToolCallAccum(acc, responseIds, closed) {
     if (acc.closedTc)
         return acc.closedTc;
     if (!acc.name)
         return undefined;
-    const args = parseStreamedToolArgs(acc.args);
+    const args = parseStreamedToolArgs(acc.args, closed);
     if (args === undefined)
         return undefined;
     const { engineId, wireId } = admitToolCallId(acc.id, "call_", responseIds);
@@ -250,6 +252,45 @@ function toOpenAITools(ctx) {
         function: { name: t.name, description: t.description, parameters: t.parameters },
     }));
 }
+const FINISH_REASON_READINGS = Object.freeze({
+    stop: { kind: "finished" },
+    length: { kind: "finished" },
+    tool_calls: { kind: "finished" },
+    function_call: { kind: "finished" },
+    content_filter: { kind: "refusal" },
+    sensitive: { kind: "refusal" },
+    model_context_window_exceeded: { kind: "input_too_long" },
+    insufficient_system_resource: { kind: "provider_cut", code: "server" },
+    aborted: { kind: "provider_cut", code: "server" },
+    network_error: { kind: "provider_cut", code: "network" },
+});
+function deltaOf(raw) {
+    return typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : undefined;
+}
+function finishWordOf(raw) {
+    if (!raw)
+        return null;
+    return typeof raw === "string" ? raw : "?";
+}
+function lateContentKind(delta) {
+    if (delta === undefined)
+        return undefined;
+    const calls = delta.tool_calls;
+    if (calls !== undefined && calls !== null && !(Array.isArray(calls) && calls.length === 0))
+        return "tool_calls";
+    if (delta.refusal)
+        return "refusal";
+    if (delta.content)
+        return "text";
+    if (delta.reasoning || delta.reasoning_content)
+        return "reasoning";
+    return undefined;
+}
+function readFinishReason(reason) {
+    if (reason == null)
+        return undefined;
+    return Object.hasOwn(FINISH_REASON_READINGS, reason) ? FINISH_REASON_READINGS[reason] : { kind: "unrecognized" };
+}
 function mapFinishReason(reason, hadToolCalls) {
     if (hadToolCalls) {
         return "toolUse";
@@ -300,7 +341,7 @@ export function createOpenAIBrain(config = {}) {
             maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const root = resolveRequestRoot(model.baseUrl, config.baseUrl);
+                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl);
                 if (!root) {
                     throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
                 }
@@ -348,11 +389,13 @@ export function createOpenAIBrain(config = {}) {
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     headers["authorization"] = `Bearer ${apiKey}`;
-                const wire = applyExtraBody(body, model.extraBody, OPENAI_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, OPENAI_RESERVED);
                 return {
                     url: joinRequestUrl(root, "/chat/completions"),
                     headers,
                     body: JSON.stringify(wire),
+                    extraBodyDropped,
+                    route: requestRouteOf(routeCredential, rootOrigin),
                     outputCapTokens: effectiveOutputCap(wire, OUTPUT_CAP_KEYS.openai),
                     capDerivedPaths: [mtField],
                     onCommitted: () => {
@@ -379,7 +422,9 @@ export function createOpenAIBrain(config = {}) {
                 const toolAccum = new Map();
                 const responseIds = responseToolCallIds();
                 let finishReason = null;
-                const terminalFrameSeen = () => finishReason != null;
+                let inBandError;
+                const afterEnd = createStreamEndLedger();
+                const terminalFrameSeen = () => finishReason != null || inBandError !== undefined;
                 let usageRaw;
                 let malformedFrames = 0;
                 let malformedSample;
@@ -452,6 +497,8 @@ export function createOpenAIBrain(config = {}) {
                         closeThinking();
                     },
                     onLine(rawLine) {
+                        if (inBandError !== undefined)
+                            return;
                         const line = rawLine.trim();
                         if (!line.startsWith("data:"))
                             return;
@@ -467,15 +514,34 @@ export function createOpenAIBrain(config = {}) {
                             malformedSample ??= data.slice(0, 160);
                             return;
                         }
+                        const stated = chunk.error;
+                        if (typeof stated === "object" && stated !== null && !Array.isArray(stated)) {
+                            if (terminalFrameSeen()) {
+                                afterEnd.note("error", providerErrorWord(stated) ?? "?");
+                                return;
+                            }
+                            inBandError = inBandProviderError(ctrl.dialect, stated, "gateway");
+                            ctrl.cancel();
+                            return;
+                        }
                         if (chunk.usage)
                             usageRaw = chunk.usage;
                         noteResponseModel(partial, chunk.model, model.id);
                         const choice = chunk.choices?.[0];
                         if (!choice)
                             return;
-                        if (choice.finish_reason)
-                            finishReason = choice.finish_reason;
-                        const delta = choice.delta;
+                        const finishWord = finishWordOf(choice.finish_reason);
+                        if (terminalFrameSeen()) {
+                            const late = lateContentKind(deltaOf(choice.delta));
+                            if (finishWord !== null && finishWord !== finishReason)
+                                afterEnd.note("ending", finishWord);
+                            else if (late !== undefined)
+                                afterEnd.note("content", late);
+                            return;
+                        }
+                        if (finishWord !== null)
+                            finishReason = finishWord;
+                        const delta = deltaOf(choice.delta);
                         if (delta?.reasoning)
                             pushReasoningDelta(delta.reasoning);
                         else if (delta?.reasoning_content)
@@ -486,7 +552,7 @@ export function createOpenAIBrain(config = {}) {
                         }
                         if (delta?.content)
                             pushTextDelta(delta.content);
-                        if (delta?.tool_calls) {
+                        if (Array.isArray(delta?.tool_calls)) {
                             ctrl.sawContentToken();
                             for (const tc of delta.tool_calls) {
                                 const idx = tc.index ?? (tc.id ? toolAccum.size : Math.max(0, toolAccum.size - 1));
@@ -496,9 +562,9 @@ export function createOpenAIBrain(config = {}) {
                                             continue;
                                         if (prevAcc.args === "")
                                             continue;
-                                        const closed = closeToolCallAccum(prevAcc, responseIds);
-                                        if (closed) {
-                                            out.push({ type: "toolcall_end", contentIndex: prevIdx, toolCall: closed, partial: { ...partial } });
+                                        const done = closeToolCallAccum(prevAcc, responseIds, false);
+                                        if (done) {
+                                            out.push({ type: "toolcall_end", contentIndex: prevIdx, toolCall: done, partial: { ...partial } });
                                         }
                                     }
                                 }
@@ -516,7 +582,7 @@ export function createOpenAIBrain(config = {}) {
                     finalize(opts) {
                         closeThinking();
                         const textFace = degenerate && degenFace === "text" && rep.cut !== undefined ? trimDegenerateTail(accumText, rep.cut) : accumText;
-                        if (emittedTextStart && (opts?.truncated !== true || finishReason != null)) {
+                        if (emittedTextStart && ((opts?.truncated !== true && inBandError === undefined) || finishReason != null)) {
                             out.push({ type: "text_end", contentIndex: textIndex, content: textFace, partial: { ...partial } });
                         }
                         const finalContent = [];
@@ -528,16 +594,17 @@ export function createOpenAIBrain(config = {}) {
                         const malformed = [];
                         const unnamed = [];
                         let emptyPlaceholders = 0;
+                        const endedCut = finishReason === "length" || finishReason == null;
                         for (const acc of [...toolAccum.entries()].sort((a, b) => a[0] - b[0]).map((e) => e[1])) {
                             if (!acc.name) {
                                 if (!acc.id && acc.args === "") {
                                     emptyPlaceholders++;
                                     continue;
                                 }
-                                unnamed.push(`id="${acc.id || "?"}"(${acc.args.slice(0, 200)})`);
+                                (nameMissingCause(!endedCut) === "truncated" ? malformed : unnamed).push(`id="${acc.id || "?"}"(${acc.args.slice(0, 200)})`);
                                 continue;
                             }
-                            const tc = closeToolCallAccum(acc, responseIds);
+                            const tc = closeToolCallAccum(acc, responseIds, !endedCut);
                             if (tc) {
                                 toolCalls.push(tc);
                                 finalContent.push(tc);
@@ -570,8 +637,9 @@ export function createOpenAIBrain(config = {}) {
                             unnamed.push(emptyPlaceholders > 0 ? emptySlots : "<no tool_call delta arrived on the stream>");
                         }
                         const toolErrorParts = [];
+                        const capFacts = { capStop: finishReason === "length", outputTokens: usageRaw?.completion_tokens, capTokens: sentMaxTokens };
                         if (malformed.length > 0) {
-                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, finish_reason="${finishReason ?? "?"}"${truncationCauseClause({ capStop: finishReason === "length", outputTokens: usageRaw?.completion_tokens, capTokens: sentMaxTokens, terminalFrameSeen: terminalFrameSeen() })}): ${malformed.join("; ")}`);
+                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, finish_reason="${finishReason ?? "?"}"${truncationCauseClause({ ...capFacts, terminalFrameSeen: terminalFrameSeen() })}): ${malformed.join("; ")}`);
                         }
                         if (unnamed.length > 0) {
                             toolErrorParts.push(`tool call(s) arrived with no tool name and cannot be executed (finish_reason="${finishReason ?? "?"}"): ${unnamed.join("; ")}`);
@@ -589,9 +657,18 @@ export function createOpenAIBrain(config = {}) {
                             notes.push({ cause: "bad_frame", count: malformedFrames, text: `\n[note: ${malformedFrames} provider stream frame(s) were not valid JSON and were dropped — the streamed output may be missing content (first sample: ${JSON.stringify(malformedSample)})]` });
                         }
                         placeTurnNotes(partial, finalContent, notes);
+                        if (inBandError !== undefined) {
+                            ctrl.keepOutput({ content: finalContent, usage: computeUsage(model, usageRaw), ...(usageRaw === undefined ? { usageMissing: true } : {}) });
+                            throw inBandError;
+                        }
                         const truncatedEmpty = finishReason === "length" && noUsableContent && !toolError;
                         const dynamicCut = truncatedEmpty && options?.maxTokensDynamic === true;
-                        const safetyCut = finishReason === "content_filter";
+                        const finishReading = readFinishReason(finishReason);
+                        const safetyCut = finishReading?.kind === "refusal";
+                        const contextWindowExceeded = finishReading?.kind === "input_too_long";
+                        const providerCut = finishReading?.kind === "provider_cut" ? finishReading : undefined;
+                        const finishReasonUnknown = finishReading?.kind === "unrecognized" ? echoFoldedWord(finishReason ?? "") : undefined;
+                        const finishQuoted = JSON.stringify((finishReason ?? "").slice(0, 64));
                         const refused = accumRefusal.trim().length > 0;
                         const emptyNoFinish = noUsableContent && finishReason == null && !degenerate;
                         const maxTokensNote = sentMaxTokens !== undefined
@@ -604,20 +681,26 @@ export function createOpenAIBrain(config = {}) {
                         const errorMessage = degenerate
                             ? DEGENERATE_MESSAGE
                             : safetyCut
-                                ? `[refusal] response cut by the provider content filter (finish_reason="content_filter") — the output was censored/truncated for policy and is unreliable`
+                                ? `[refusal] response cut by the provider content filter (finish_reason=${finishQuoted}) — the output was censored/truncated for policy and is unreliable`
                                 : refused
                                     ? `[refusal] response refused by the model for policy reasons: ${accumRefusal.trim()}`
-                                    : (toolError ??
-                                        (truncatedEmpty && !dynamicCut
-                                            ? accumReasoning.trim()
-                                                ? `[length_empty] response truncated at max_tokens (finish_reason="length", ${maxTokensNote}) 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.`
-                                                : `[length_empty] response truncated at max_tokens (finish_reason="length", ${maxTokensNote}) with no answer text — raise max_tokens`
-                                            : emptyNoFinish
-                                                ? `[stream_torn] model stream ended with no content and no finish_reason — the response was lost (a torn stream or an in-band provider error frame)${malformedFrames > 0 ? ` — ${malformedFrames} unparseable data frame(s) were dropped on this stream (first sample: ${JSON.stringify(malformedSample)})` : ""}`
-                                                : undefined));
+                                    : contextWindowExceeded
+                                        ? `[invalid_request] model context window exceeded (finish_reason=${finishQuoted}) — the conversation no longer fits the model's context window`
+                                        : providerCut !== undefined
+                                            ? `[${providerCut.code}] response cut short by the provider (finish_reason=${finishQuoted}) — the text above may be incomplete`
+                                            : (toolError ??
+                                                (truncatedEmpty && !dynamicCut
+                                                    ? accumReasoning.trim()
+                                                        ? `[length_empty] response truncated at max_tokens (finish_reason="length", ${maxTokensNote}) 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.`
+                                                        : `[length_empty] response truncated at max_tokens (finish_reason="length", ${maxTokensNote}) with no answer text — raise max_tokens`
+                                                    : emptyNoFinish
+                                                        ? `[stream_torn] model stream ended with no content and no finish_reason — the response was lost (a torn stream or an in-band provider error frame)${malformedFrames > 0 ? ` — ${malformedFrames} unparseable data frame(s) were dropped on this stream (first sample: ${JSON.stringify(malformedSample)})` : ""}`
+                                                        : undefined));
                         const errored = degenerate ||
                             safetyCut ||
                             refused ||
+                            contextWindowExceeded ||
+                            providerCut !== undefined ||
                             emptyNoFinish ||
                             (toolError !== undefined && noUsableContent) ||
                             (truncatedEmpty && !dynamicCut);
@@ -625,9 +708,14 @@ export function createOpenAIBrain(config = {}) {
                         const errorMessageOut = tornWithContent ? (errorMessage ? `${errorMessage}\n${STREAM_TORN_WARNING}` : STREAM_TORN_WARNING) : errorMessage;
                         const errorKind = degenerate
                             ? "degenerate"
-                            : !safetyCut && !refused && toolError === undefined && truncatedEmpty && !dynamicCut
-                                ? "length_empty"
-                                : undefined;
+                            : !safetyCut && !refused && contextWindowExceeded
+                                ? "input_too_long"
+                                : !safetyCut && !refused && toolError === undefined && truncatedEmpty && !dynamicCut
+                                    ? "length_empty"
+                                    : undefined;
+                        const modelOutputInvalid = errored && toolError !== undefined && !degenerate && !safetyCut && !refused && !contextWindowExceeded && providerCut === undefined
+                            ? modelOutputInvalidOf({ truncated: malformed.length, unnamed: unnamed.length }, capFacts)
+                            : undefined;
                         const finalMessage = {
                             ...partial,
                             content: finalContent.length > 0 ? finalContent : [{ type: "text", text: "" }],
@@ -637,7 +725,10 @@ export function createOpenAIBrain(config = {}) {
                             timestamp: Date.now(),
                             ...(errorMessageOut ? { errorMessage: errorMessageOut } : {}),
                             ...(errorKind ? { errorKind } : {}),
+                            ...(modelOutputInvalid !== undefined ? { modelOutputInvalid } : {}),
                             ...(tornWithContent ? { partialFinalized: true } : {}),
+                            ...(finishReasonUnknown !== undefined ? { finishReasonUnknown } : {}),
+                            ...(afterEnd.ignored !== undefined ? { streamEndIgnored: afterEnd.ignored } : {}),
                             ...(rep.cut !== undefined || rep.spared.length > 0
                                 ? { repetition: { ...(rep.cut !== undefined ? { cut: rep.cut } : {}), ...(rep.spared.length > 0 ? { spared: rep.spared } : {}) } }
                                 : {}),

package/dist/brain/provider-dialect.d.ts

@@ -0,0 +1,214 @@
+/**
+ * The provider dialect table — what each provider endpoint MEANS by the way it fails, declared once per
+ * endpoint and read by every seat that reports a provider failure.
+ *
+ * KEY. An endpoint is named by (wire family, host suffix + path): the same brand can serve two endpoints whose
+ * failures read in opposite ways (Moonshot's open platform states an exhausted balance as a 429, its coding
+ * subscription states a spent usage window as a 403 and keeps 429 for momentary overload), and the same word
+ * can mean opposite things on two brands (`insufficient_quota` is a per-minute token limit on DashScope and an
+ * empty balance on OpenAI). So the table is keyed by where the request went, never by vendor name or by word.
+ * A request whose endpoint matches no key reads only the GENERIC rows: the statements whose meaning does not
+ * depend on who said them.
+ *
+ * COLUMNS. A dialect is a record of named columns about one endpoint. `failures` is the failure-classification
+ * column: rows that turn a status, the envelope's word (`error.code`, else `error.type` — the same word
+ * `apiErrorCode` carries) and the envelope's sentence (`error.message`) into one {@link ProviderCondition}. The
+ * context-limit refusal is a flag on the same rows (`inputTooLong`), so "this 400 is the input being too long"
+ * and "this 400 is something else the provider named" are read off one row and cannot disagree.
+ *
+ * ONE VERDICT, TWO SEATS. {@link judgeHttpFailure} answers once per failed response; the retry decision, the
+ * retry frame (`BrainStatus.providerCondition`) and the terminal (`BrainError` → `AssistantMessage` →
+ * `terminal.detail`) all read that answer. An in-band error frame (a provider error delivered inside a 200
+ * stream) is judged by {@link judgeInBandError} over the same rows.
+ *
+ * DEGRADATION DIRECTION. Every row whose evidence is prose is fragile (a provider rewords and the row stops
+ * matching). A row that stops matching falls to the endpoint's own status row, then to the generic rows, then
+ * to the status alone — which in every case is the retrying reading, never the stopping one: a missed quota
+ * costs a backoff ladder, a false quota costs the user a run.
+ */
+import type { Model } from "../internal/llm.js";
+import type { AssertAllKeysHandled } from "../core/ask-origin.js";
+import { BrainError, type FailedBody } from "./errors.js";
+/**
+ * What the provider said about the account or its own capacity when it failed a request — the one closed set
+ * both the retry frame and the terminal report:
+ *  - `quota_exhausted` — the account cannot be served until someone acts or a window resets (an empty balance,
+ *    an overdue bill, a spent usage window, a free tier used up). Not retried.
+ *  - `throttled` — slow down: a request / token rate limit that clears on its own. Retried (backoff, the
+ *    provider's `Retry-After` as the floor).
+ *  - `overloaded` — the provider's own capacity, not the account's. Retried.
+ *  - `stop_other` — a refusal that resending cannot change (credentials, model access, the request itself, its
+ *    content, the plan's tier). Not retried. A context-limit refusal is one of these and is ALSO typed
+ *    `input_too_long` on its own seat.
+ *  - `unknown` — the endpoint said nothing this table can read. Retried exactly as the status alone would be.
+ */
+export declare const PROVIDER_CONDITIONS: readonly ["quota_exhausted", "throttled", "overloaded", "stop_other", "unknown"];
+export type ProviderCondition = (typeof PROVIDER_CONDITIONS)[number];
+/**
+ * Which evidence the condition rests on:
+ *  - `unified_header` — a subscription quota header (`anthropic-ratelimit-unified-representative-claim` /
+ *    `-overage-status` / `-overage-disabled-reason`) on a 429.
+ *  - `provider_code` — a row keyed on the envelope's word (`error.code`, else `error.type`) or its sentence
+ *    (`error.message`) matched.
+ *  - `status` — no row read the envelope (none arrived, it did not end, or no row names its word or sentence): the
+ *    default for what arrived — the endpoint's row for the status, else the generic row, else the status alone; an
+ *    in-band error frame, which states no status, defaults to `unknown`.
+ */
+export declare const PROVIDER_CONDITION_SOURCES: readonly ["unified_header", "provider_code", "status"];
+export type ProviderConditionSource = (typeof PROVIDER_CONDITION_SOURCES)[number];
+/**
+ * What each condition means to this engine — the one place retryability lives:
+ *  - `retryable` — the connect ladder re-sends a response judged so (the provider's explicit `x-should-retry`
+ *    verdict still outranks it, in both directions);
+ *  - `inBandCode` — the brain error code an in-band error frame carries (it has no status to classify by).
+ */
+export declare const PROVIDER_CONDITION_TRAITS: {
+    readonly quota_exhausted: {
+        readonly retryable: false;
+        readonly inBandCode: "rate_limit";
+    };
+    readonly throttled: {
+        readonly retryable: true;
+        readonly inBandCode: "rate_limit";
+    };
+    readonly overloaded: {
+        readonly retryable: true;
+        readonly inBandCode: "server";
+    };
+    readonly stop_other: {
+        readonly retryable: false;
+        readonly inBandCode: "invalid_request";
+    };
+    readonly unknown: {
+        readonly retryable: true;
+        readonly inBandCode: "server";
+    };
+};
+/** Compile-time fence: every condition has a traits row. */
+export type ConditionTraitsCoverEveryCondition = AssertAllKeysHandled<Exclude<ProviderCondition, keyof typeof PROVIDER_CONDITION_TRAITS>>;
+/** Membership read for a value that crossed a seat (a brand-read error member, a host-minted message). */
+export declare function isProviderCondition(v: unknown): v is ProviderCondition;
+export declare function isProviderConditionSource(v: unknown): v is ProviderConditionSource;
+/**
+ * The context-limit refusal FAMILY, anchored at the START of the provider's diagnostic (`error.message`). The
+ * two error directions cost asymmetrically, and the asymmetry is what sets the width: a FALSE POSITIVE (a bare
+ * "Input is too long" prefix that is really field-length validation) costs one bounded recovery attempt on a
+ * request that already failed — the retry fails identically and the original error surfaces, self-limiting. A
+ * FALSE NEGATIVE (an unlisted GENUINE refusal read as an authoritative negative) permanently suppresses
+ * recovery for that turn: the task dies where it would have recovered. So within a PARSED provider envelope the
+ * whole conservative family classifies when it matches AT POSITION 0 of the diagnostic — "a provider stating
+ * this error states it first"; a reflection arrives behind a preamble ("validation failed; offending prompt: …")
+ * and the position-0 anchor is what separates the two. A prefixed genuine refusal inside a parsed envelope
+ * therefore reads as ruled-out — the residual narrowing, accepted (prose-only bodies keep the historic prose
+ * reach through the "unknown" arm).
+ *
+ * Members, by provenance: the loop's historic prose patterns re-anchored at position 0; the llama.cpp openings
+ * ("the request exceeds the available context size", "request (N tokens) exceeds …"); Gemini / Vertex through
+ * an OpenAI-compatible gateway ("the input token count (N) exceeds the maximum number of tokens allowed (M)");
+ * llama.cpp-family /v1 servers ("requested tokens (N) exceed context window of M"); two conservative gateway
+ * paraphrases ("your input exceeds the context window …", "the number of tokens in the request exceeds …");
+ * DashScope ("Range of input length should be [1, N]"); Moonshot's open platform ("Input token length too
+ * long"); Moonshot's coding endpoint ("Invalid request: Your request exceeded model token limit: N …" and
+ * "total message size N exceeds limit M"); Z.AI ("Prompt too long"). An unlisted subject-first provider spelling
+ * is a member to ADD; the anchor stays. A provider that names this refusal with a STRUCTURAL code says so on its
+ * own row instead (`context_length_exceeded` below, GLM's `1261`), and a code row outranks every sentence.
+ */
+export declare const INPUT_TOO_LONG_ANCHORED_RE: RegExp;
+/** True when the (provider-authored) diagnostic OPENS with the context-limit refusal family. */
+export declare function startsWithInputTooLongAnchor(diagnostic: string): boolean;
+/**
+ * Three-state context-limit verdict: `"yes"` — the provider stated it, on a row that says so; `"no"` — the
+ * status cannot carry it, or the provider's envelope parsed and states something else; `"unknown"` — a status
+ * that can carry it whose body established no provenance (a text/plain gateway, or a body that did not end — the
+ * terminal marks the latter `errorBodyIncomplete`, so no seat reads its prose either).
+ */
+export type InputTooLongVerdict = "yes" | "no" | "unknown";
+/** One row of the failure column. A row with no `status` applies to every status. */
+export interface FailureRow {
+    readonly status?: readonly number[];
+    /** The envelope's word (`error.code` when a string, else `error.type`), compared exactly. */
+    readonly word?: readonly string[];
+    /** Matched against the envelope's `error.message`. Anchored unless the row's evidence says otherwise. */
+    readonly sentence?: RegExp;
+    readonly condition: ProviderCondition;
+    /** This row's statement IS the context-limit refusal. */
+    readonly inputTooLong?: true;
+}
+/** Where a dialect applies: the wire families it was evidenced for, its host suffixes, an optional path prefix. */
+export interface DialectKey {
+    readonly wires: readonly Model["api"][];
+    /** A request host equal to one of these, or ending in `.` + one. */
+    readonly hosts: readonly string[];
+    /** A path prefix, matched at a segment boundary. Absent = every path on the host. */
+    readonly path?: string;
+}
+/** One endpoint's declared dialect: its key and its columns. */
+export interface ProviderDialect {
+    readonly name: string;
+    readonly key: DialectKey;
+    readonly failures: readonly FailureRow[];
+}
+/**
+ * The declared dialects. Each row's source is the provider's own error documentation as collected in the
+ * per-provider matrix (status, word, sentence → condition); a `sentence` row is the fragile kind and degrades
+ * as the module note says.
+ */
+export declare const PROVIDER_DIALECTS: readonly ProviderDialect[];
+/**
+ * The rows every endpoint answers to beneath its own, and the only rows an unrecognized endpoint has. Each
+ * states something whose meaning no provider in the table overloads: Payment Required, OpenAI's spend codes,
+ * the structural context-limit code and the context-limit sentences, the transport's 413. The cross-provider
+ * word `insufficient_quota` is pinned to `unknown` here on purpose — on an endpoint nobody declared, it is as
+ * likely a token-rate limit as an empty balance.
+ */
+export declare const GENERIC_FAILURES: readonly FailureRow[];
+/**
+ * The TRANSIENT statuses — the server family and the two transient 4xx (408 request timeout, 409 lock timeout;
+ * CC's own retry predicate treats them like 5xx). Two readers, one fact: unread, such a status defaults to
+ * `unknown` (retried), and no row turns one into a stop (pinned), so the connect ladder decides them without
+ * reading the body (a stalled error body must not cost each retry the body's read bound); the terminal still
+ * reads and judges it.
+ */
+export declare function isTransientStatus(status: number): boolean;
+/** The endpoint a request went to, or `undefined` when no dialect declares it. */
+export declare function resolveProviderDialect(url: string, wire: Model["api"]): ProviderDialect | undefined;
+/** One failure's reading off the table. */
+export interface ProviderVerdict {
+    readonly condition: ProviderCondition;
+    readonly source: ProviderConditionSource;
+    /** When the condition is `quota_exhausted` and the provider stated when it lifts: wall-clock epoch ms. */
+    readonly resetAtMs?: number;
+    readonly inputTooLong: InputTooLongVerdict;
+}
+type HeaderBag = {
+    get?: (name: string) => string | null;
+} | undefined | null;
+/**
+ * Judge one failed HTTP response. `body` is the error body as read (`endedNormally` false = cut by a bound or
+ * torn): only a body that ENDED may steer, so a cut one is read as stating nothing — the endpoint's status row
+ * and the generic rows still apply. Absent `body` = not read (a status whose verdict no body can change).
+ */
+export declare function judgeHttpFailure(args: {
+    dialect: ProviderDialect | undefined;
+    status: number;
+    headers?: HeaderBag;
+    body?: FailedBody;
+}): ProviderVerdict;
+/** Judge an in-band error frame's envelope object (a provider error delivered inside a 200 stream). */
+export declare function judgeInBandError(dialect: ProviderDialect | undefined, envelope: {
+    message?: unknown;
+    code?: unknown;
+    type?: unknown;
+}): ProviderVerdict;
+/**
+ * The failure an in-band error frame states, as the brain error the stream's terminal carries: the code its
+ * condition reads as ({@link PROVIDER_CONDITION_TRAITS}), the provider's word and sentence in the message, the word
+ * on the echo seat, the verdict, and the context-limit reading of the same row. A frame the provider sent on its
+ * own stream is a provider failure by construction (`apiError`); it states no status.
+ */
+export declare function inBandProviderError(dialect: ProviderDialect | undefined, envelope: {
+    message?: unknown;
+    code?: unknown;
+    type?: unknown;
+}, label: string): BrainError;
+export {};