@sema-agent/core 7.47.0 → 7.49.0

package/dist/brain/anthropic.js

@@ -2,12 +2,13 @@ import {} from "../internal/llm.js";
 import { BrainError } from "./errors.js";
 import { startsWithInputTooLongAnchor } from "./input-too-long.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, modelOutputInvalidOf, noteResponseModel, nameMissingCause, parseStreamedToolArgs, placeTurnNotes, truncationCauseClause } from "./stream-shared.js";
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry, reportReasoningWireFacts } from "./status-sink.js";
 import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, modelSupportsVision, sendableImages } from "./media-degrade.js";
 import { ANTHROPIC_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, lockHeader, mergeHeaders, takeHeaderCasefold } 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 { MIN_THINKING_TOKENS, budgetCapSkipsThinking, declaredEffortLevels, reasoningBudgetShare, reasoningRequestCarried, resolveEffort } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
@@ -213,12 +214,12 @@ function computeUsage(model, u) {
         },
     };
 }
-function closeToolUseBlock(acc, responseIds) {
+function closeToolUseBlock(acc, responseIds, closed) {
     if (acc.closedTc)
         return acc.closedTc;
     if (!acc.toolName)
         return undefined;
-    const args = parseStreamedToolArgs(acc.toolJson);
+    const args = parseStreamedToolArgs(acc.toolJson, closed);
     if (args === undefined)
         return undefined;
     const { engineId, wireId } = admitToolCallId(acc.toolId, "toolu_", responseIds);
@@ -243,7 +244,7 @@ export function createAnthropicBrain(config = {}) {
             maxRetries: options?.maxRetries,
             stallTimeouts: options?.stallTimeouts,
             buildRequest: (overrides) => {
-                const root = resolveRequestRoot(model.baseUrl, config.baseUrl, "https://api.anthropic.com");
+                const { root, origin: rootOrigin } = resolveRequestRootOf(model.baseUrl, config.baseUrl, "https://api.anthropic.com");
                 const routeCredential = resolveRouteCredential({
                     optionsApiKey: options?.apiKey,
                     optionsHeaders: options?.headers,
@@ -349,11 +350,13 @@ export function createAnthropicBrain(config = {}) {
                         : model.maxTokens !== undefined
                             ? "model"
                             : "config-default";
-                const wire = applyExtraBody(body, model.extraBody, ANTHROPIC_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, ANTHROPIC_RESERVED);
                 return {
                     url: joinRequestUrl(root, "/v1/messages"),
                     headers,
                     body: JSON.stringify(wire),
+                    extraBodyDropped,
+                    route: requestRouteOf(routeCredential, rootOrigin),
                     outputCapTokens: effectiveOutputCap(wire, OUTPUT_CAP_KEYS.anthropic),
                     capDerivedPaths: [...OUTPUT_CAP_KEYS.anthropic, "thinking.budget_tokens"],
                     onCommitted: () => {
@@ -371,7 +374,6 @@ export function createAnthropicBrain(config = {}) {
                 const responseIds = responseToolCallIds();
                 const usageRaw = {};
                 let stopReason = null;
-                const terminalFrameSeen = () => stopReason != null;
                 let stopDetails;
                 let nextContentIndex = 0;
                 let malformedFrames = 0;
@@ -382,7 +384,116 @@ export function createAnthropicBrain(config = {}) {
                 let lastDegenCheck = 0;
                 let lastDegenCheckThinking = 0;
                 const detectRep = config.detectRepetition !== false;
+                let messageStopped = false;
+                const afterEnd = createStreamEndLedger();
+                const streamEnded = () => stopReason != null || messageStopped;
+                const mergeDeltaUsage = (u) => {
+                    if (!u)
+                        return;
+                    if (u.output_tokens !== undefined)
+                        usageRaw.output_tokens = u.output_tokens;
+                    if (u.input_tokens != null && u.input_tokens > 0)
+                        usageRaw.input_tokens = u.input_tokens;
+                    if (u.cache_read_input_tokens != null && u.cache_read_input_tokens > 0)
+                        usageRaw.cache_read_input_tokens = u.cache_read_input_tokens;
+                    if (u.cache_creation_input_tokens != null && u.cache_creation_input_tokens > 0) {
+                        usageRaw.cache_creation_input_tokens = u.cache_creation_input_tokens;
+                    }
+                };
+                const reportedUsage = () => ({
+                    usage: computeUsage(model, usageRaw),
+                    ...(Object.keys(usageRaw).length === 0 ? { usageMissing: true } : {}),
+                });
+                const wordOf = (v) => (typeof v === "string" && v !== "" ? v : "?");
+                const refuseAfterEnd = (evt) => {
+                    switch (evt.type) {
+                        case "message_delta": {
+                            mergeDeltaUsage(evt.usage);
+                            const late = evt.delta?.stop_reason;
+                            if (typeof late === "string" && late !== "" && late !== stopReason)
+                                afterEnd.note("ending", late);
+                            return;
+                        }
+                        case "content_block_start":
+                            afterEnd.note("content", wordOf(evt.content_block?.type));
+                            return;
+                        case "content_block_delta":
+                            afterEnd.note("content", wordOf(evt.delta?.type));
+                            return;
+                        case "content_block_stop":
+                        case "message_start":
+                            afterEnd.note("content", evt.type);
+                            return;
+                        case "error":
+                            afterEnd.note("error", wordOf(evt.error?.type));
+                            return;
+                        default:
+                            return;
+                    }
+                };
+                const assembleTurn = (stampOn) => {
+                    const finalContent = [];
+                    const toolCalls = [];
+                    const malformed = [];
+                    const unnamed = [];
+                    let anyText = false;
+                    let reasoningSeen = false;
+                    const endedCut = stopReason === "max_tokens" || stopReason == null;
+                    for (const [, acc] of [...blocks.entries()].sort((a, b) => a[0] - b[0])) {
+                        if (acc.type === "thinking") {
+                            if (acc.text.length > 0 || acc.redacted === true)
+                                reasoningSeen = true;
+                            const block = { type: "thinking", thinking: acc.text };
+                            const sig = acc.signature || acc.startSignature;
+                            if (sig)
+                                block.thinkingSignature = sig;
+                            if (acc.redacted)
+                                block.redacted = true;
+                            finalContent.push(block);
+                        }
+                        else if (acc.type === "text") {
+                            const text = acc === degenTextBlock && rep.cut !== undefined ? trimDegenerateTail(acc.text, rep.cut) : acc.text;
+                            if (text) {
+                                finalContent.push({ type: "text", text });
+                                if (text.trim())
+                                    anyText = true;
+                            }
+                        }
+                        else if (acc.type === "tool_use") {
+                            const closed = acc.stopped === true || !endedCut;
+                            if (!acc.toolName) {
+                                (nameMissingCause(closed) === "truncated" ? malformed : unnamed).push(`id="${acc.toolId || "?"}"(${acc.toolJson.slice(0, 200)})`);
+                            }
+                            else {
+                                const tc = closeToolUseBlock(acc, responseIds, closed);
+                                if (tc) {
+                                    toolCalls.push(tc);
+                                    finalContent.push(tc);
+                                }
+                                else {
+                                    malformed.push(`${acc.toolName}(${acc.toolJson.slice(0, 200)})`);
+                                }
+                            }
+                        }
+                    }
+                    const notes = [];
+                    if (malformed.length > 0) {
+                        notes.push({ cause: "truncated", count: malformed.length, text: `\n[note: ${malformed.length} tool call(s) were truncated (stop_reason="${stopReason ?? "?"}") and dropped — re-issue them next turn: ${malformed.join("; ")}]` });
+                    }
+                    if (unnamed.length > 0) {
+                        notes.push({ cause: "unnamed", count: unnamed.length, text: `\n[note: ${unnamed.length} tool call(s) arrived with no tool name and were dropped — re-issue them next turn with an explicit tool name: ${unnamed.join("; ")}]` });
+                    }
+                    if (malformedFrames > 0) {
+                        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(stampOn, finalContent, notes);
+                    return { content: finalContent, toolCalls, malformed, unnamed, anyText, reasoningSeen };
+                };
                 const handleEvent = (evt) => {
+                    if (streamEnded()) {
+                        refuseAfterEnd(evt);
+                        return;
+                    }
                     switch (evt.type) {
                         case "message_start": {
                             const msg = evt.message;
@@ -490,7 +601,7 @@ export function createAnthropicBrain(config = {}) {
                                 out.push({ type: "text_end", contentIndex: idx, content: acc.text, partial: { ...partial } });
                             }
                             else if (acc?.type === "tool_use") {
-                                const tc = closeToolUseBlock(acc, responseIds);
+                                const tc = closeToolUseBlock(acc, responseIds, true);
                                 if (tc) {
                                     out.push({ type: "toolcall_end", contentIndex: idx, toolCall: tc, partial: { ...partial } });
                                 }
@@ -503,21 +614,12 @@ export function createAnthropicBrain(config = {}) {
                                 stopReason = d.stop_reason;
                             if (d?.stop_details)
                                 stopDetails = d.stop_details;
-                            const u = evt.usage;
-                            if (u) {
-                                if (u.output_tokens !== undefined)
-                                    usageRaw.output_tokens = u.output_tokens;
-                                if (u.input_tokens != null && u.input_tokens > 0)
-                                    usageRaw.input_tokens = u.input_tokens;
-                                if (u.cache_read_input_tokens != null && u.cache_read_input_tokens > 0) {
-                                    usageRaw.cache_read_input_tokens = u.cache_read_input_tokens;
-                                }
-                                if (u.cache_creation_input_tokens != null && u.cache_creation_input_tokens > 0) {
-                                    usageRaw.cache_creation_input_tokens = u.cache_creation_input_tokens;
-                                }
-                            }
+                            mergeDeltaUsage(evt.usage);
                             break;
                         }
+                        case "message_stop":
+                            messageStopped = true;
+                            break;
                         case "error": {
                             const rawError = evt.error;
                             const e = typeof rawError === "object" && rawError !== null && !Array.isArray(rawError)
@@ -525,6 +627,7 @@ export function createAnthropicBrain(config = {}) {
                                 : undefined;
                             const inputTooLong = e?.type === "request_too_large" ||
                                 (e?.type === "invalid_request_error" && typeof e.message === "string" && startsWithInputTooLongAnchor(e.message));
+                            ctrl.keepOutput({ content: assembleTurn({}).content, ...reportedUsage() });
                             throw new BrainError(anthropicStreamErrorCode(e?.type), `anthropic stream error (${e?.type ?? "unknown"}): ${e?.message ?? ""}`, undefined, { apiError: true, ...(e === undefined ? {} : inputTooLong ? { inputTooLong: true } : { inputTooLongRuledOut: true }) });
                         }
                         default:
@@ -541,7 +644,7 @@ export function createAnthropicBrain(config = {}) {
                             hasSubstantiveText,
                             hasCompletedToolCall,
                             hasOnlyThinking: hasThinking && !hasSubstantiveText && !hasCompletedToolCall,
-                            terminalFrameSeen: terminalFrameSeen(),
+                            terminalFrameSeen: streamEnded(),
                         };
                     },
                     sealForRetry() {
@@ -571,69 +674,18 @@ export function createAnthropicBrain(config = {}) {
                         handleEvent(evt);
                     },
                     finalize(opts) {
-                        const finalContent = [];
-                        const toolCalls = [];
-                        const malformed = [];
-                        const unnamed = [];
-                        let anyText = false;
-                        let reasoningSeen = false;
-                        for (const [, acc] of [...blocks.entries()].sort((a, b) => a[0] - b[0])) {
-                            if (acc.type === "thinking") {
-                                if (acc.text.length > 0 || acc.redacted === true)
-                                    reasoningSeen = true;
-                                const block = { type: "thinking", thinking: acc.text };
-                                const sig = acc.signature || acc.startSignature;
-                                if (sig)
-                                    block.thinkingSignature = sig;
-                                if (acc.redacted)
-                                    block.redacted = true;
-                                finalContent.push(block);
-                            }
-                            else if (acc.type === "text") {
-                                const text = acc === degenTextBlock && rep.cut !== undefined ? trimDegenerateTail(acc.text, rep.cut) : acc.text;
-                                if (text) {
-                                    finalContent.push({ type: "text", text });
-                                    if (text.trim())
-                                        anyText = true;
-                                }
-                            }
-                            else if (acc.type === "tool_use") {
-                                if (!acc.toolName) {
-                                    unnamed.push(`id="${acc.toolId || "?"}"(${acc.toolJson.slice(0, 200)})`);
-                                }
-                                else {
-                                    const tc = closeToolUseBlock(acc, responseIds);
-                                    if (tc) {
-                                        toolCalls.push(tc);
-                                        finalContent.push(tc);
-                                    }
-                                    else {
-                                        malformed.push(`${acc.toolName}(${acc.toolJson.slice(0, 200)})`);
-                                    }
-                                }
-                            }
-                        }
+                        const { content: finalContent, toolCalls, malformed, unnamed, anyText, reasoningSeen } = assembleTurn(partial);
                         const doneReason = mapStopReason(stopReason, toolCalls.length > 0);
                         const noUsableContent = toolCalls.length === 0 && !anyText;
                         const toolErrorParts = [];
+                        const capFacts = { capStop: stopReason === "max_tokens", outputTokens: usageRaw.output_tokens, capTokens: sentMaxTokens };
                         if (malformed.length > 0) {
-                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, stop_reason="${stopReason ?? "?"}"${truncationCauseClause({ capStop: stopReason === "max_tokens", outputTokens: usageRaw.output_tokens, capTokens: sentMaxTokens, terminalFrameSeen: terminalFrameSeen() })}): ${malformed.join("; ")}`);
+                            toolErrorParts.push(`tool call argument(s) not valid JSON (likely truncated, stop_reason="${stopReason ?? "?"}"${truncationCauseClause({ ...capFacts, terminalFrameSeen: streamEnded() })}): ${malformed.join("; ")}`);
                         }
                         if (unnamed.length > 0) {
                             toolErrorParts.push(`tool call(s) arrived with no tool name and cannot be executed (stop_reason="${stopReason ?? "?"}"): ${unnamed.join("; ")}`);
                         }
                         const toolError = toolErrorParts.length > 0 ? toolErrorParts.join(" | ") : undefined;
-                        const notes = [];
-                        if (malformed.length > 0) {
-                            notes.push({ cause: "truncated", count: malformed.length, text: `\n[note: ${malformed.length} tool call(s) were truncated (stop_reason="${stopReason ?? "?"}") and dropped — re-issue them next turn: ${malformed.join("; ")}]` });
-                        }
-                        if (unnamed.length > 0) {
-                            notes.push({ cause: "unnamed", count: unnamed.length, text: `\n[note: ${unnamed.length} tool call(s) arrived with no tool name and were dropped — re-issue them next turn with an explicit tool name: ${unnamed.join("; ")}]` });
-                        }
-                        if (malformedFrames > 0) {
-                            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);
                         const truncatedEmpty = stopReason === "max_tokens" && noUsableContent && !toolError;
                         const dynamicCut = truncatedEmpty && options?.maxTokensDynamic === true;
                         const staticReasoningCut = truncatedEmpty && !dynamicCut && reasoningSeen && options?.staticReasoningCutDowngrade === true;
@@ -669,7 +721,7 @@ export function createAnthropicBrain(config = {}) {
                             emptyNoFinish ||
                             (toolError !== undefined && noUsableContent) ||
                             (truncatedEmpty && !dynamicCut && !staticReasoningCut);
-                        const tornWithContent = !errored && opts?.truncated !== true && !terminalFrameSeen() && !noUsableContent && !degenerate;
+                        const tornWithContent = !errored && opts?.truncated !== true && !streamEnded() && !noUsableContent && !degenerate;
                         const errorMessageOut = tornWithContent ? (errorMessage ? `${errorMessage}\n${STREAM_TORN_WARNING}` : STREAM_TORN_WARNING) : errorMessage;
                         const errorKind = degenerate
                             ? "degenerate"
@@ -678,20 +730,22 @@ export function createAnthropicBrain(config = {}) {
                                 : !safetyCut && toolError === undefined && truncatedEmpty && !dynamicCut && !staticReasoningCut
                                     ? "length_empty"
                                     : undefined;
+                        const modelOutputInvalid = errored && toolError !== undefined && !degenerate && !safetyCut && !contextWindowExceeded ? modelOutputInvalidOf({ truncated: malformed.length, unnamed: unnamed.length }, capFacts) : undefined;
                         const finalMessage = {
                             ...partial,
                             content: finalContent.length > 0 ? finalContent : [{ type: "text", text: "" }],
                             stopReason: errored ? "error" : doneReason,
-                            usage: computeUsage(model, usageRaw),
-                            ...(Object.keys(usageRaw).length === 0 ? { usageMissing: true } : {}),
+                            ...reportedUsage(),
                             timestamp: Date.now(),
                             ...(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 } : {}) } }
                                 : {}),
                             ...(staticReasoningCut ? { staticReasoningCut: true } : {}),
+                            ...(afterEnd.ignored !== undefined ? { streamEndIgnored: afterEnd.ignored } : {}),
                             ...(stopDetails
                                 ? {
                                     diagnostics: [

package/dist/brain/errors.d.ts

@@ -6,6 +6,7 @@
  * → a transient outage worth retrying. Only `network`/`server`/`rate_limit` are retried by the brains.
  */
 import type { Usage } from "../internal/llm.js";
+import type { ProviderCondition, ProviderConditionSource } from "./provider-dialect.js";
 /** A zeroed `Usage` for synthetic error/short-circuit assistant messages (no tokens spent). Shared by
  *  the circuit-breaker, degradation, and routing brains so the empty-usage shape lives in one place. */
 export declare const ZERO_USAGE: Usage;
@@ -48,7 +49,7 @@ export declare class BrainError extends Error {
      *  suppresses the loop's prose fallback — a reflected "prompt is too long" inside an unrelated
      *  error body must not drive a context-shrinking recovery. Mutually exclusive with
      *  `inputTooLong`; BOTH absent = classification could not establish provenance ("unknown"),
-     *  and the prose fallback keeps its historic reach. */
+     *  and the prose fallback keeps its historic reach unless {@link errorBodyIncomplete} is set. */
     readonly inputTooLongRuledOut?: true;
     /**
      * This failure was produced AT THE PROVIDER BOUNDARY — a transport attempt was made against the
@@ -64,15 +65,33 @@ export declare class BrainError extends Error {
      * conservative reading for every pre-existing and third-party construction site.
      */
     readonly apiError?: true;
-    /** The provider's own word for a REFUSED request (a 4xx answer), read from its JSON error envelope by
-     *  {@link readProviderErrorCode} at the HTTP throw. Lifted onto `AssistantMessage.apiErrorCode` at the terminal-shell
-     *  mint. Absent when the answer was not a 4xx or the envelope stated no word in the echo shape. */
+    /** The provider's own word for the failure it stated, read from its JSON error envelope: a REFUSED request's
+     *  (a 4xx answer, read by {@link readProviderErrorCode} at the HTTP throw) or an in-band error frame's (no status).
+     *  Lifted onto `AssistantMessage.apiErrorCode` at the terminal-shell mint. Absent when neither stated a word in the
+     *  echo shape. */
     readonly providerCode?: string;
+    /** What the provider said about the account or its capacity, judged off the provider dialect table
+     *  (`provider-dialect.ts`) — on every failure the provider stated (an HTTP failure status, an in-band error
+     *  frame). Lifted onto `AssistantMessage.providerCondition` beside {@link providerConditionSource}. */
+    readonly providerCondition?: ProviderCondition;
+    readonly providerConditionSource?: ProviderConditionSource;
+    /** With a `quota_exhausted` condition whose evidence stated it: when the quota lifts, wall-clock epoch ms. */
+    readonly providerResetAtMs?: number;
+    /** The failed response's body did not end (cut at the read bound, torn, unreadable), so it stated nothing: no
+     *  verdict, word or context-limit reading came from it, and the prefix quoted in the message is no evidence
+     *  either. Lifted onto `AssistantMessage.errorBodyIncomplete`. */
+    readonly errorBodyIncomplete?: true;
     constructor(code: BrainErrorCode, detail: string, status?: number, opts?: {
         inputTooLong?: boolean;
         inputTooLongRuledOut?: boolean;
         apiError?: boolean;
         providerCode?: string;
+        verdict?: {
+            condition: ProviderCondition;
+            source: ProviderConditionSource;
+            resetAtMs?: number;
+        };
+        errorBodyIncomplete?: boolean;
     });
 }
 /** The provider's diagnostic object out of a JSON error body, or undefined when the body establishes no provenance
@@ -83,14 +102,42 @@ export declare function providerErrorObject(body: string): {
     code?: unknown;
     type?: unknown;
 } | undefined;
+/** The envelope's WORD — `error.code` when it is a string, else `error.type` when that is — the one reading of "what
+ *  the provider called this failure": the echoed `apiErrorCode` and the dialect table's word rows both read it here. */
+export declare function providerErrorWord(err: {
+    code?: unknown;
+    type?: unknown;
+} | undefined): string | undefined;
 /**
  * The provider's own word for a refused request, from its JSON error envelope: `error.code` when it is a string (the
  * OpenAI-family code, e.g. `context_length_exceeded`), else `error.type` (the Anthropic-family word, e.g.
  * `invalid_request_error`). Read structurally, never from prose. Carried only in the provider echo shape
  * ({@link isProviderEchoShape}); a word outside it is dropped whole — absent, never truncated — and counted as one
- * `echo_dropped` event (`field: "apiErrorCode"`). An envelope that states neither yields nothing.
+ * `echo_dropped` event (`field: "apiErrorCode"`). An envelope that states neither yields nothing, and so does a body
+ * that did not end ({@link statedEnvelope}).
  */
-export declare function readProviderErrorCode(body: string): string | undefined;
+export declare function readProviderErrorCode(body: FailedBody | undefined): string | undefined;
+/** A failed response's body as read. */
+export interface FailedBody {
+    /** Whatever text arrived: the terminal message quotes it, and that is all a prefix is good for. */
+    readonly text: string;
+    /**
+     * Whether the body ENDED on its own, rather than being cut by the byte cap, the time bound, an abort, or a torn
+     * stream. Parseability is NOT a substitute: a stream that emits a complete envelope and never closes leaves valid
+     * JSON in the buffer when the time bound fires, and an envelope followed by padding past the byte cap parses too
+     * (trailing whitespace is legal JSON). A body that did not end states nothing, in any seat.
+     */
+    readonly endedNormally: boolean;
+}
+/** What a failed response's body states — its envelope — and only when the body ended ({@link FailedBody}). Every
+ *  reader of a failed body (the dialect verdict, the echoed word) reads it through here. */
+export declare function statedEnvelope(body: FailedBody | undefined): ReturnType<typeof providerErrorObject>;
+/** The envelope's word as the echo seat carries it ({@link readProviderErrorCode}, for an envelope already in hand —
+ *  an in-band error frame's): carried in the echo shape, else dropped whole and counted once. */
+export declare function carriedProviderWord(err: {
+    code?: unknown;
+    type?: unknown;
+} | undefined): string | undefined;
 export { isProviderEchoShape, PROVIDER_ECHO_SHAPE } from "./provider-echo-shape.js";
 /** How the brains read one provider echo value: a non-string or the empty string states nothing (`absent` — no field,
  *  nothing counted); a string in {@link isProviderEchoShape} is `carried`; any other string is `refused` (dropped and

package/dist/brain/errors.js

@@ -19,6 +19,10 @@ export class BrainError extends Error {
     inputTooLongRuledOut;
     apiError;
     providerCode;
+    providerCondition;
+    providerConditionSource;
+    providerResetAtMs;
+    errorBodyIncomplete;
     constructor(code, detail, status, opts) {
         super(`[${code}] ${detail}`);
         this.name = "BrainError";
@@ -32,6 +36,14 @@ export class BrainError extends Error {
             this.apiError = true;
         if (opts?.providerCode !== undefined)
             this.providerCode = opts.providerCode;
+        if (opts?.verdict !== undefined) {
+            this.providerCondition = opts.verdict.condition;
+            this.providerConditionSource = opts.verdict.source;
+            if (opts.verdict.resetAtMs !== undefined)
+                this.providerResetAtMs = opts.verdict.resetAtMs;
+        }
+        if (opts?.errorBodyIncomplete === true)
+            this.errorBodyIncomplete = true;
     }
 }
 export function providerErrorObject(body) {
@@ -52,9 +64,17 @@ export function providerErrorObject(body) {
         return undefined;
     return err;
 }
+export function providerErrorWord(err) {
+    return typeof err?.code === "string" ? err.code : typeof err?.type === "string" ? err.type : undefined;
+}
 export function readProviderErrorCode(body) {
-    const err = providerErrorObject(body);
-    const word = typeof err?.code === "string" ? err.code : typeof err?.type === "string" ? err.type : undefined;
+    return carriedProviderWord(statedEnvelope(body));
+}
+export function statedEnvelope(body) {
+    return body !== undefined && body.endedNormally ? providerErrorObject(body.text) : undefined;
+}
+export function carriedProviderWord(err) {
+    const word = providerErrorWord(err);
     const reading = providerEchoReading(word);
     if (reading === "carried")
         return word;

package/dist/brain/input-too-long.d.ts

@@ -1,24 +1,45 @@
-/** True when the (provider-authored) diagnostic OPENS with the context-limit refusal family. */
-export declare function startsWithInputTooLongAnchor(diagnostic: string): boolean;
 /**
- * Three-state classification verdict (adversarial-review r1: a binary answer conflated "the
- * provider said something ELSE" with "we could not read the provider", and the loop's prose
- * fallback then re-opened the reflected-text hole for exactly the errors this module HAD
- * examined):
- *  - `"yes"`     — provenance-checked input-too-long; the caller stamps the typed cause.
- *  - `"no"`      — the classification is AUTHORITATIVE-NEGATIVE: either the status can never carry
- *                  this refusal (5xx, auth, rate limit — reflected prose in those bodies must not
- *                  drive a context-shrinking recovery), or the provider's own diagnostic envelope
- *                  parsed and states a different error. The caller marks the terminal shell
- *                  ruled-out, which SUPPRESSES the loop's prose fallback for this message.
- *  - `"unknown"` — a PTL-capable status whose body established no provenance (text/plain gateway,
- *                  truncated read): nothing is stamped either way, and the loop's historic prose
- *                  fallback keeps working for gateways that speak prose only.
+ * design/374 slice 2 — TYPED input-too-long classification for provider refusals.
+ *
+ * "The request INPUT alone exceeds the model's context limit" is recognizable from prose over the
+ * human-facing `errorMessage`, but such a classifier cannot tell a provider's own diagnostic from
+ * caller text a gateway reflected, and breaks the moment a provider rewords. The classification runs
+ * at the BRAIN boundary, where provenance is decidable, and the verdict rides
+ * `BrainError.inputTooLong` → `AssistantMessage.errorKind: "input_too_long"` (the same typed lane
+ * `degenerate`/`length_empty` already use).
+ *
+ * PROVENANCE DISCIPLINE (mirrors `context-overflow.ts`, the sibling classifier for the
+ * input+max_tokens overflow — a DIFFERENT error: there the input fits and lowering the output cap
+ * self-heals; here the input alone does not fit and only shrinking the input helps):
+ *   - The only text source is the provider's diagnostic FIELD: `error.message` of a JSON object
+ *     body whose `error` is itself an object (both the Anthropic `{type:"error",error:{…}}` and
+ *     the OpenAI `{error:{…}}` envelopes reduce to this). A plain-text body, a string `error`, a
+ *     top-level `message` — refused: each is a guess about gateway formatting that would trade a
+ *     hypothetical classification for a field a gateway may fill with caller content.
+ *   - Prose is matched ANCHORED at the start of that field only, against the conservative
+ *     context-limit FAMILY (case-insensitive; the family and its member list live with the rows that
+ *     carry them, `provider-dialect.ts`). A gateway that inlines the offending request ("validation
+ *     failed; offending prompt: prompt is too long…") therefore cannot classify: caller text must
+ *     never steer a retry.
+ *   - Structural signals need no prose at all: a provider's own context-limit CODE (OpenAI-family
+ *     `context_length_exceeded`; an endpoint's declared code such as GLM's `1261`), and HTTP 413 (the
+ *     transport's own "request entity too large"). A code the endpoint declares for something else
+ *     outranks every sentence: the provider named the failure, a sentence beside it cannot rename it.
+ *
+ * The verdict is a column of the provider dialect table (`provider-dialect.ts`): a context-limit
+ * refusal is a row whose `inputTooLong` flag is set, read by the same lookup that names the failure's
+ * `providerCondition`. This module is the reader face for a response no endpoint is known for.
+ *
+ * Misclassification cost: inside a PARSED provider envelope a miss is an AUTHORITATIVE negative
+ * that SUPPRESSES the loop's prose fallback — which is why the family must carry every observed
+ * genuine opening; prose-only bodies keep the fallback reach via the "unknown" arm. A FALSE HIT
+ * costs one bounded recovery attempt, and only on a 400/413/422 the request already failed on.
  */
-export type InputTooLongVerdict = "yes" | "no" | "unknown";
+import { type InputTooLongVerdict } from "./provider-dialect.js";
+export { startsWithInputTooLongAnchor, type InputTooLongVerdict } from "./provider-dialect.js";
 /**
- * Classify an HTTP refusal as input-too-long. `body` is the (bounded) error-body text as read;
- * a truncated read that no longer parses as JSON answers `"unknown"` (413 excepted — the status
- * alone is the provider's statement).
+ * Classify an HTTP refusal as input-too-long against the generic rows (an endpoint no dialect declares).
+ * `body` is the error-body text, read whole; one that does not parse as a JSON envelope answers `"unknown"`
+ * (413 excepted — the status alone is the provider's statement).
  */
 export declare function classifyInputTooLong(status: number, body: string): InputTooLongVerdict;

package/dist/brain/input-too-long.js

@@ -1,18 +1,5 @@
-import { providerErrorObject } from "./errors.js";
-const INPUT_TOO_LONG_ANCHORED_RE = /^(?:prompt is too long|input is too long|this model's maximum context length is |context.{0,3}length|context window (?:limit|exceeded)|reached its context window|too many tokens|maximum context|input length and `max_tokens` exceed context limit|(?:the )?request(?: \([^)]{0,40}\))? exceeds|(?:the )?input token count(?: \([^)]{0,40}\))? exceeds|requested tokens(?: \([^)]{0,40}\))? exceed|your input exceeds|(?:the )?number of tokens in the request exceeds)/i;
-const INPUT_TOO_LONG_STATUSES = new Set([400, 413, 422]);
-export function startsWithInputTooLongAnchor(diagnostic) {
-    return INPUT_TOO_LONG_ANCHORED_RE.test(diagnostic.trimStart());
-}
+import { judgeHttpFailure } from "./provider-dialect.js";
+export { startsWithInputTooLongAnchor } from "./provider-dialect.js";
 export function classifyInputTooLong(status, body) {
-    if (!INPUT_TOO_LONG_STATUSES.has(status))
-        return "no";
-    if (status === 413)
-        return "yes";
-    const err = providerErrorObject(body);
-    if (err === undefined)
-        return "unknown";
-    if (err.code === "context_length_exceeded")
-        return "yes";
-    return typeof err.message === "string" && startsWithInputTooLongAnchor(err.message) ? "yes" : "no";
+    return judgeHttpFailure({ dialect: undefined, status, body: { text: body, endedNormally: true } }).inputTooLong;
 }