@sema-agent/core 7.54.1 → 7.55.0

package/dist/brain/open-responses.js

@@ -8,6 +8,7 @@ import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNot
 import { OUTPUT_CAP_KEYS, RESPONSES_RESERVED, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
 import { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
+import { NAMES_AS_WRITTEN, resolveProviderDialect, endpointToolNames } from "./provider-dialect.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
@@ -64,7 +65,7 @@ function toUserParts(content, supportsVision) {
         parts.push({ type: "input_text", text: imagesOmittedNoVisionNote(images.length) });
     return parts;
 }
-function toResponsesInput(ctx, model, replayReasoning) {
+function toResponsesInput(ctx, model, replayReasoning, toolNames) {
     const supportsVision = modelSupportsVision(model);
     const out = [];
     let pendingImages = [];
@@ -116,7 +117,7 @@ function toResponsesInput(ctx, model, replayReasoning) {
             if (text !== "")
                 out.push({ type: "message", role: "assistant", content: [{ type: "output_text", text }] });
             for (const tc of toolCalls) {
-                out.push({ type: "function_call", call_id: providerToolCallId(tc), name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) });
+                out.push({ type: "function_call", call_id: providerToolCallId(tc), name: toolNames.sent(tc.name), arguments: JSON.stringify(tc.arguments ?? {}) });
             }
         }
         else if (m.role === "toolResult") {
@@ -145,12 +146,12 @@ function toResponsesInput(ctx, model, replayReasoning) {
     flushImages();
     return out;
 }
-function toResponsesTools(ctx) {
+function toResponsesTools(ctx, toolNames) {
     if (!ctx.tools || ctx.tools.length === 0)
         return undefined;
     return ctx.tools.map((t) => ({
         type: "function",
-        name: t.name,
+        name: toolNames.sent(t.name),
         description: t.description,
         parameters: t.parameters,
         strict: false,
@@ -231,6 +232,7 @@ export function createOpenResponsesBrain(given = {}) {
         let sentEffort;
         let builtMaxTokens;
         let builtMaxTokensLane = "unset";
+        let sentToolNames = NAMES_AS_WRITTEN;
         return runStreamingBrain({
             model,
             doFetch,
@@ -245,6 +247,8 @@ export function createOpenResponsesBrain(given = {}) {
                 if (!root) {
                     throw new Error("createOpenResponsesBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
                 }
+                const url = joinRequestUrl(root, "/responses");
+                const builtToolNames = endpointToolNames(resolveProviderDialect(url, model.api), model.api, (context.tools ?? []).map((t) => t.name));
                 const modelHeaders = headerBagOnce(model.headers);
                 const optionsHeaders = headerBagOnce(options?.headers);
                 const routeCredential = resolveRouteCredential({
@@ -265,12 +269,12 @@ export function createOpenResponsesBrain(given = {}) {
                 const effort = resolveWireEffort(model, options?.reasoning);
                 const body = {
                     model: model.id,
-                    input: toResponsesInput(context, model, config.replayReasoning !== false),
+                    input: toResponsesInput(context, model, config.replayReasoning !== false, builtToolNames),
                     stream: true,
                 };
                 if (context.systemPrompt)
                     body.instructions = context.systemPrompt;
-                const tools = toResponsesTools(context);
+                const tools = toResponsesTools(context, builtToolNames);
                 if (tools)
                     body.tools = tools;
                 if (options?.temperature !== undefined)
@@ -293,9 +297,9 @@ export function createOpenResponsesBrain(given = {}) {
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     lockHeader(headers, OPEN_RESPONSES_KEY_HEADER, `Bearer ${apiKey}`);
-                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, RESPONSES_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model, RESPONSES_RESERVED);
                 return {
-                    url: joinRequestUrl(root, "/responses"),
+                    url,
                     headers,
                     body: JSON.stringify(wire),
                     extraBodyDropped,
@@ -307,6 +311,7 @@ export function createOpenResponsesBrain(given = {}) {
                         sentMaxTokens = builtMaxTokens;
                         sentMaxTokensLane = builtMaxTokensLane;
                         sentEffort = effort;
+                        sentToolNames = builtToolNames;
                     },
                 };
             },
@@ -457,7 +462,7 @@ export function createOpenResponsesBrain(given = {}) {
                             else if (itemType === "function_call") {
                                 const acc = openItem(index, "function_call", itemId);
                                 acc.callId = frame.item?.call_id ?? "";
-                                acc.name = frame.item?.name ?? "";
+                                acc.name = sentToolNames.called(frame.item?.name ?? "");
                                 if (frame.item?.arguments)
                                     acc.args += frame.item.arguments;
                             }
@@ -546,7 +551,7 @@ export function createOpenResponsesBrain(given = {}) {
                                 if (!acc.callId && frame.item?.call_id)
                                     acc.callId = frame.item.call_id;
                                 if (!acc.name && frame.item?.name)
-                                    acc.name = frame.item.name;
+                                    acc.name = sentToolNames.called(frame.item.name);
                                 if (acc.args === "" && frame.item?.arguments)
                                     acc.args = frame.item.arguments;
                             }

package/dist/brain/openai.js

@@ -7,7 +7,7 @@ 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, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
 import { BrainError, providerErrorWord } from "./errors.js";
-import { inBandProviderError } from "./provider-dialect.js";
+import { NAMES_AS_WRITTEN, inBandProviderError, resolveProviderDialect, endpointToolNames } from "./provider-dialect.js";
 import { admitRouteRequest, applyRouteCredentialHeaders, assertServableRequestRoot, brainConfigSnapshot, createBrainRouteJudge, joinRequestUrl, resolveRequestRootOf, resolveRouteCredential } from "./route-adjudicator.js";
 import { requestRouteOf } from "./request-route.js";
 import { declaredOffSpelling, mintEffortWireValue, reasoningRequestCarried } from "./reasoning.js";
@@ -155,7 +155,7 @@ function applyThinking(body, model, reasoning) {
         }
     }
 }
-function toOpenAIMessages(ctx, replayThinking = true, model) {
+function toOpenAIMessages(ctx, replayThinking = true, model, toolNames) {
     const supportsVision = modelSupportsVision(model);
     const out = [];
     const needsEmptyReasoningField = !!model?.reasoning && thinkingCompat(model).requiresReasoningContentOnAssistantMessages === true;
@@ -206,7 +206,7 @@ function toOpenAIMessages(ctx, replayThinking = true, model) {
                 msg.tool_calls = toolCalls.map((tc) => ({
                     id: providerToolCallId(tc),
                     type: "function",
-                    function: { name: tc.name, arguments: JSON.stringify(tc.arguments ?? {}) },
+                    function: { name: toolNames.sent(tc.name), arguments: JSON.stringify(tc.arguments ?? {}) },
                 }));
             }
             out.push(msg);
@@ -244,13 +244,13 @@ function toolResultText(text, hasCarriedImages, original) {
         return "(image attached below)";
     return Array.isArray(original) && original.length > 0 ? "(non-text tool result omitted)" : "";
 }
-function toOpenAITools(ctx) {
+function toOpenAITools(ctx, toolNames) {
     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: { name: toolNames.sent(t.name), description: t.description, parameters: t.parameters },
     }));
 }
 const FINISH_REASON_READINGS = Object.freeze({
@@ -334,6 +334,7 @@ export function createOpenAIBrain(given = {}) {
         let sentMaxTokensLane = "unset";
         let builtMaxTokens;
         let builtMaxTokensLane = "unset";
+        let sentToolNames = NAMES_AS_WRITTEN;
         return runStreamingBrain({
             model,
             doFetch,
@@ -348,6 +349,8 @@ export function createOpenAIBrain(given = {}) {
                 if (!root) {
                     throw new Error("createOpenAIBrain: no baseUrl configured (set config.baseUrl or model.baseUrl)");
                 }
+                const url = joinRequestUrl(root, "/chat/completions");
+                const builtToolNames = endpointToolNames(resolveProviderDialect(url, model.api), model.api, (context.tools ?? []).map((t) => t.name));
                 const modelHeaders = headerBagOnce(model.headers);
                 const optionsHeaders = headerBagOnce(options?.headers);
                 const routeCredential = resolveRouteCredential({
@@ -362,11 +365,11 @@ export function createOpenAIBrain(given = {}) {
                 const apiKey = routeCredential.apiKey;
                 const body = {
                     model: model.id,
-                    messages: toOpenAIMessages(context, config.replayThinking, model),
+                    messages: toOpenAIMessages(context, config.replayThinking, model, builtToolNames),
                     stream: true,
                     stream_options: { include_usage: true },
                 };
-                const tools = toOpenAITools(context);
+                const tools = toOpenAITools(context, builtToolNames);
                 if (tools)
                     body.tools = tools;
                 if (options?.temperature !== undefined)
@@ -393,9 +396,9 @@ export function createOpenAIBrain(given = {}) {
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     lockHeader(headers, OPENAI_KEY_HEADER, `Bearer ${apiKey}`);
-                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model.extraBody, OPENAI_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model, OPENAI_RESERVED);
                 return {
-                    url: joinRequestUrl(root, "/chat/completions"),
+                    url,
                     headers,
                     body: JSON.stringify(wire),
                     extraBodyDropped,
@@ -406,6 +409,7 @@ export function createOpenAIBrain(given = {}) {
                         routeAdmission();
                         sentMaxTokens = builtMaxTokens;
                         sentMaxTokensLane = builtMaxTokensLane;
+                        sentToolNames = builtToolNames;
                     },
                 };
             },
@@ -577,7 +581,7 @@ export function createOpenAIBrain(given = {}) {
                                 if (tc.id)
                                     acc.id = tc.id;
                                 if (tc.function?.name)
-                                    acc.name = tc.function.name;
+                                    acc.name = sentToolNames.called(tc.function.name);
                                 if (tc.function?.arguments && !acc.closedTc)
                                     acc.args += tc.function.arguments;
                                 toolAccum.set(idx, acc);
@@ -619,7 +623,7 @@ export function createOpenAIBrain(given = {}) {
                             }
                         }
                         if (config.repairTextToolCalls && toolCalls.length === 0 && textFace && context.tools && context.tools.length > 0) {
-                            const names = new Set(context.tools.flatMap((t) => [t.name, ...(t.aliases ?? [])]));
+                            const names = new Set(context.tools.flatMap((t) => [t.name, sentToolNames.sent(t.name), ...(t.aliases ?? [])]));
                             const repaired = repairTextToolCalls(textFace, names);
                             if (repaired.toolCalls.length > 0) {
                                 finalContent.length = 0;
@@ -627,7 +631,8 @@ export function createOpenAIBrain(given = {}) {
                                     finalContent.push({ type: "thinking", thinking: accumReasoning });
                                 if (repaired.cleanedText)
                                     finalContent.push({ type: "text", text: repaired.cleanedText });
-                                for (const tc of repaired.toolCalls) {
+                                for (const repairedCall of repaired.toolCalls) {
+                                    const tc = { ...repairedCall, name: sentToolNames.called(repairedCall.name) };
                                     finalContent.push(tc);
                                     toolCalls.push(tc);
                                 }

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

@@ -1,6 +1,7 @@
 /**
- * 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.
+ * The provider dialect table — what each provider endpoint MEANS by the way it fails and by the tool names it is
+ * sent, declared once per endpoint and read by every seat that reports a provider failure or names a tool on the
+ * wire.
  *
  * 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
@@ -14,7 +15,9 @@
  * 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.
+ * and "this 400 is something else the provider named" are read off one row and cannot disagree. `toolNames` is
+ * the tool-name column: names the endpoint gives a meaning of its own on one wire ({@link ToolNameRow}), read by
+ * {@link endpointToolNames} — the one projection every brain sends tool names through and reads call names back by.
  *
  * ONE VERDICT, TWO SEATS. {@link judgeHttpFailure} answers once per failed response; the retry decision, the
  * retry frame (`BrainStatus.providerCondition`) and the terminal (`BrainError` → `AssistantMessage` →
@@ -142,11 +145,24 @@ export interface DialectKey {
     /** A path prefix, matched at a segment boundary. Absent = every path on the host. */
     readonly path?: string;
 }
+/**
+ * One row of the tool-name column. On `wire`, the endpoint treats a tool sent under `name` as a feature of its own
+ * rather than as the tool the request declares, so a tool by that name travels as `sentAs` instead, and a call the
+ * model makes to `sentAs` is a call to `name`. The name inside the engine, the prompts that mention it and the
+ * tool's parameters do not change; only the spelling on this wire does.
+ */
+export interface ToolNameRow {
+    readonly wire: Model["api"];
+    readonly name: string;
+    readonly sentAs: string;
+}
 /** One endpoint's declared dialect: its key and its columns. */
 export interface ProviderDialect {
     readonly name: string;
     readonly key: DialectKey;
     readonly failures: readonly FailureRow[];
+    /** Absent = the endpoint gives no tool name a meaning of its own: every name travels as written. */
+    readonly toolNames?: readonly ToolNameRow[];
 }
 /**
  * The declared dialects. Each row's source is the provider's own error documentation as collected in the
@@ -172,6 +188,26 @@ export declare const GENERIC_FAILURES: readonly FailureRow[];
 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;
+/**
+ * How one request's tool names travel. Both halves read the one set the request declares: `sent` spells a declared
+ * tool's name, in the tool table and in every replayed call to it; `called` reads a call name the model sends back as
+ * the declared tool that travels under it. A name the request does not declare travels and comes back as written —
+ * a replayed call to a tool no longer mounted keeps its name, and a model that calls a tool by the name the prompts
+ * use still reaches it. A brain builds one with each request and keeps the one the engine commits; its parser reads
+ * call names through it.
+ */
+export interface EndpointToolNames {
+    readonly sent: (name: string) => string;
+    readonly called: (sentName: string) => string;
+}
+/** Every name travels as written: the projection of an endpoint whose dialect has no tool-name row on the wire. */
+export declare const NAMES_AS_WRITTEN: EndpointToolNames;
+/**
+ * The tool-name projection of one request: the dialect's rows for this wire, applied to the tools the request
+ * declares. Two declared tools that would travel under one name are refused before anything is sent — the model
+ * could not tell them apart, and neither could the call that comes back.
+ */
+export declare function endpointToolNames(dialect: ProviderDialect | undefined, wire: Model["api"], declared: readonly string[]): EndpointToolNames;
 /** One failure's reading off the table. */
 export interface ProviderVerdict {
     readonly condition: ProviderCondition;

package/dist/brain/provider-dialect.js

@@ -87,6 +87,7 @@ export const PROVIDER_DIALECTS = Object.freeze([
             { status: [429], word: ["1311", "1313"], condition: "stop_other" },
             { status: [400], word: ["1261"], condition: "stop_other", inputTooLong: true },
         ],
+        toolNames: [{ wire: ANTHROPIC, name: "ToolSearch", sentAs: "ToolFinder" }],
     },
     {
         name: "openai",
@@ -120,6 +121,33 @@ export function resolveProviderDialect(url, wire) {
         d.key.hosts.some((h) => host === h || host.endsWith(`.${h}`)) &&
         (d.key.path === undefined || path === d.key.path || path.startsWith(`${d.key.path}/`)));
 }
+export const NAMES_AS_WRITTEN = Object.freeze({ sent: (name) => name, called: (sentName) => sentName });
+export function endpointToolNames(dialect, wire, declared) {
+    const rows = (dialect?.toolNames ?? []).filter((r) => r.wire === wire);
+    if (rows.length === 0)
+        return NAMES_AS_WRITTEN;
+    const sentAs = new Map(rows.map((r) => [r.name, r.sentAs]));
+    const holderOf = new Map();
+    const forward = new Map();
+    const back = new Map();
+    for (const name of new Set(declared)) {
+        const onWire = sentAs.get(name) ?? name;
+        const holder = holderOf.get(onWire);
+        if (holder !== undefined) {
+            const moved = rows.filter((r) => r.sentAs === onWire).map((r) => JSON.stringify(r.name)).join(" / ");
+            const asWritten = [holder, name].find((n) => n === onWire);
+            throw new BrainError("invalid_request", `the request was not sent: the tools ${JSON.stringify(holder)} and ${JSON.stringify(name)} would both travel as ${JSON.stringify(onWire)}. ` +
+                `This endpoint gives the tool name ${moved} a meaning of its own on this wire, so a tool by that name is sent as ${JSON.stringify(onWire)}, ` +
+                `and two tools cannot share one name on the wire — rename ${asWritten === undefined ? "one of them" : `the tool named ${JSON.stringify(asWritten)}`}.`);
+        }
+        holderOf.set(onWire, name);
+        if (onWire !== name) {
+            forward.set(name, onWire);
+            back.set(onWire, name);
+        }
+    }
+    return { sent: (name) => forward.get(name) ?? name, called: (sentName) => back.get(sentName) ?? sentName };
+}
 function statementOf(err) {
     if (err === undefined)
         return undefined;

package/dist/brain/reasoning.d.ts

@@ -53,7 +53,7 @@ export declare const DEFAULT_EFFORT_LEVELS: readonly ThinkingLevel[];
  * here so {@link resolveReasoning} can report ONE endpoint discriminant across both brain families.
  */
 export type ReasoningFormat = "openai" | "openrouter" | "deepseek" | "together" | "zai" | "qwen" | "qwen-chat-template" | "budget"
-/** Anthropic `output_config.effort` (CC 2.1.198 / Fable-5 class, design/119): the tier is a named
+/** Anthropic `output_config.effort` (Fable-5 class, design/119): the tier is a named
  *  effort string, clamped to `compat.effortLevels` — the anthropic-side twin of the OpenAI
  *  `reasoning_effort` path (thinking FORM is `thinkingMode`; effort carries the intensity). */
  | "effort"

package/dist/brain/request-params.d.ts

@@ -1,3 +1,4 @@
+import type { Model } from "../internal/llm.js";
 /** OpenAI request-body keys core owns; `extraBody` cannot override these. */
 export declare const OPENAI_RESERVED: ReadonlySet<string>;
 /** Anthropic request-body keys core owns; `extraBody` cannot override these. (Note the asymmetry vs
@@ -13,17 +14,66 @@ export declare const ANTHROPIC_RESERVED: ReadonlySet<string>;
  * wire and the drop announced, never a silently server-linked turn.
  */
 export declare const RESPONSES_RESERVED: ReadonlySet<string>;
+/** What {@link judgeExtraBody} refuses: the code, the one sentence, and (on `config.invalid_argument`) the member it names.
+ *  Not an engine notice (a refusal is thrown, never delivered), so it carries none of a notice's members. */
+export interface ExtraBodyRefusal {
+    readonly code: "config.invalid_argument" | "config.extra_body_output_cap";
+    readonly sentence: string;
+    readonly field?: "Model.extraBody";
+}
 /**
- * Merge `extraBody` into a brain's already-built request `body`, dropping any key the brain owns so core
+ * {@link judgeExtraBody}'s answer: the refusal, or — admitted — the model's keys as ONE copy (`undefined` when the model
+ * carries no `extraBody` at all). The copy is what was judged, and it is what the merge walks: nothing is read from the
+ * object a second time.
+ */
+export type ExtraBodyVerdict = {
+    readonly refused: ExtraBodyRefusal;
+    readonly entries?: undefined;
+} | {
+    readonly refused?: undefined;
+    readonly entries: ReadonlyArray<readonly [string, unknown]> | undefined;
+};
+/**
+ * THE admission law for a model's `extraBody`, asked at both seats that can hand a request a model spec: the prepare step
+ * (the task's own model, before the session is acquired — a refused request never touches the session) and the request
+ * build ({@link applyExtraBody} — a model spec a host brain swapped in for one request, the compaction model, any other
+ * call of the leg). One judge, one sentence per refusal, whichever seat asks. Absent is admitted; otherwise the value must
+ * be a plain object of request-body keys, and it must not carry `max_completion_tokens`.
+ *
+ * The keys are read ONCE (`Object.entries`, one walk of the object): the refusal is decided on that copy and an admitted
+ * verdict hands the same copy to the merge, so an object that answers differently the second time it is asked (a getter, a
+ * Proxy trap) cannot pass one answer and send another.
+ *
+ * - A value that is not a plain object is refused as `config.invalid_argument` (`detail.field` = `Model.extraBody`). It is
+ *   never read as keys: a string or an array would spread into the body as numbered keys, a number or `false` would be
+ *   ignored without a word.
+ * - `max_completion_tokens` is refused as `config.extra_body_output_cap` on every wire: it is a spelling of the output cap, and
+ *   the engine owns the output cap (it writes the per-request cap itself), so a cap is never taken from `extraBody` and the key
+ *   is refused rather than stripped-and-announced like the keys in a wire's reserved set. On the OpenAI wire the spelling is
+ *   also one the endpoint reads and the overflow retry lowers (stripping it would silently un-cap a deployment that used it as
+ *   its only bound; passing it on would let a constant fight the retry); the other two wires' endpoints do not read it, and the
+ *   refusal was never wire-dependent at the task's own model, so it is not made so here. (The sibling spelling `max_tokens` IS
+ *   reserved: the adapter always writes it, so a stray copy never survives.)
+ *
+ * The sentence names the kind of a refused value and reads none of its members: it never echoes the value (an `extraBody`
+ * can hold a credential-bearing template).
+ */
+export declare function judgeExtraBody(extraBody: unknown, modelId: string): ExtraBodyVerdict;
+/**
+ * Merge a model's `extraBody` into a brain's already-built request `body`, dropping any key the brain owns so core
  * always wins. `body` is a NEW object (passthrough keys first, then core keys) when `extraBody` is set; the
  * exact `body` reference (no allocation, byte-identical serialization) when it isn't — so an existing
  * deployment with no `extraBody` is unaffected.
  *
+ * The request seat of {@link judgeExtraBody}: an `extraBody` it refuses ends the build with a `BrainError`
+ * (`invalid_request`, the sentence led by the refusal's code — the shape a pre-flight route refusal has) before anything is
+ * merged or sent. The three wire adapters reach this function and nothing else; none of them judges the value itself.
+ *
  * `dropped` is the keys of `extraBody` that were stripped, in `extraBody`'s insertion order, names only (a
  * value never leaves this function except inside `body`). It is a property of the same walk that strips, so
  * what is said and what is dropped cannot disagree; empty when nothing was stripped.
  */
-export declare function applyExtraBody(body: Record<string, unknown>, extraBody: Record<string, unknown> | undefined, reserved: ReadonlySet<string>): {
+export declare function applyExtraBody(body: Record<string, unknown>, model: Pick<Model, "id" | "extraBody">, reserved: ReadonlySet<string>): {
     body: Record<string, unknown>;
     dropped: readonly string[];
 };
@@ -94,8 +144,8 @@ export declare const OUTPUT_CAP_KEYS: Readonly<Record<"openai" | "anthropic" | "
  * of the lane's cap keys that is present and usable, or `undefined` when none is.
  *
  * Read off the merged body rather than off the knob the adapter set, because those are not the same
- * thing: `extraBody` can contribute a cap under a spelling the adapter did not choose, and a
- * consumer that treats the adapter's own number as "the cap on the wire" would be wrong about a
- * request that carries two. Smallest wins so a consumer reasoning about the bound stays conservative.
+ * thing: what is on the wire is the only cap the provider enforces, and the adapter's own number can differ
+ * from it (the Anthropic lane raises `max_tokens` to fit a thinking budget). Smallest wins so a consumer
+ * reasoning about the bound stays conservative.
  */
 export declare function effectiveOutputCap(body: Record<string, unknown>, keys: readonly string[]): number | undefined;

package/dist/brain/request-params.js

@@ -1,4 +1,6 @@
 import { isCredentialHeaderName } from "../core/secret-env.js";
+import { isPlainRecord } from "../core/mods/kernel/receive.js";
+import { BrainError } from "./errors.js";
 export const OPENAI_RESERVED = new Set([
     "model",
     "messages",
@@ -40,12 +42,42 @@ export const RESPONSES_RESERVED = new Set([
     "conversation",
 ]);
 const NO_KEYS = Object.freeze([]);
-export function applyExtraBody(body, extraBody, reserved) {
-    if (!extraBody)
+const extraBodyKind = (v) => (v === null ? "null" : Array.isArray(v) ? "an array" : typeof v === "object" ? "an object that is not plain (a class instance, a Map, …)" : `a ${typeof v}`);
+export function judgeExtraBody(extraBody, modelId) {
+    if (extraBody === undefined)
+        return { entries: undefined };
+    const whose = `Model.extraBody of model ${JSON.stringify(modelId)}`;
+    if (!isPlainRecord(extraBody)) {
+        return {
+            refused: {
+                code: "config.invalid_argument",
+                field: "Model.extraBody",
+                sentence: `${whose} is ${extraBodyKind(extraBody)} — it must be a plain object of request-body keys, or absent; any other value is refused rather than spread into the request body as numbered keys or left out without a word. Write a plain object, or remove it.`,
+            },
+        };
+    }
+    const entries = Object.entries(extraBody);
+    if (entries.some(([k]) => k === "max_completion_tokens")) {
+        return {
+            refused: {
+                code: "config.extra_body_output_cap",
+                sentence: `${whose} supplies "max_completion_tokens" — an output-cap spelling the engine owns: it writes the per-request cap ` +
+                    `itself, so a cap is never taken from extraBody. Set it via limits.maxOutputTokens (per request) or Model.maxTokens; ` +
+                    `on the OpenAI wire Model.compat.maxTokensField picks the spelling.`,
+            },
+        };
+    }
+    return { entries };
+}
+export function applyExtraBody(body, model, reserved) {
+    const verdict = judgeExtraBody(model.extraBody, model.id);
+    if (verdict.refused !== undefined)
+        throw new BrainError("invalid_request", `${verdict.refused.code}: ${verdict.refused.sentence}`);
+    if (verdict.entries === undefined)
         return { body, dropped: NO_KEYS };
     const passthrough = {};
     const dropped = [];
-    for (const [k, v] of Object.entries(extraBody)) {
+    for (const [k, v] of verdict.entries) {
         if (reserved.has(k))
             dropped.push(k);
         else

package/dist/brain/retry.d.ts

@@ -1,5 +1,5 @@
 /**
- * Transient-failure retry backoff (RB-420-b, CC 2.1.220 parity).
+ * Transient-failure retry backoff (RB-420-b).
  *
  * The shape is **increasing exponential + light additive jitter**, not full jitter:
  * `min(base * 2^attempt, 32s)` plus up to 25% of that. Full jitter (`random(0, exp)`) made the Nth

package/dist/brain/route-adjudicator.d.ts

@@ -375,3 +375,18 @@ export declare function unroutableSeatNotice(args: {
     sessionId?: string;
     runId?: string;
 }): EngineNotice;
+/**
+ * The third twin, for a seat with nothing to fall back TO and nothing worth keeping (the advisor tool: serving it with
+ * the primary model would advise the agent with itself, and keeping it would refuse every call the model makes): the
+ * pairing is broken, so the seat is DETACHED for this run — not mounted, no model swapped. Same `detail` keys as
+ * {@link unroutableSeatNotice}; `action: "detached"` is the discriminator.
+ */
+export declare function seatDetachedNotice(args: {
+    seat: string;
+    from: string;
+    verdict: Extract<RouteAdjudication, {
+        ok: false;
+    }>;
+    sessionId?: string;
+    runId?: string;
+}): EngineNotice;

package/dist/brain/route-adjudicator.js

@@ -531,3 +531,18 @@ export function unroutableSeatNotice(args) {
         },
     };
 }
+export function seatDetachedNotice(args) {
+    return {
+        code: "route.seat_detached",
+        message: `derived model "${args.from}" (${args.seat}) is not routable (${args.verdict.code}) — the seat is detached for this run and nothing serves it in its place. ${args.verdict.detail.fixHint}`,
+        detail: {
+            seat: args.seat,
+            from: args.from,
+            cause: args.verdict.code,
+            fixHint: args.verdict.detail.fixHint,
+            action: "detached",
+            ...(args.sessionId !== undefined ? { sessionId: args.sessionId } : {}),
+            ...(args.runId !== undefined ? { runId: args.runId } : {}),
+        },
+    };
+}

package/dist/brain/stream-engine.js

@@ -1,7 +1,7 @@
 import { createAssistantMessageEventStream, } from "../internal/llm.js";
 import { STREAM_TORN_WARNING } from "./stream-shared.js";
 import { FLOOR_OUTPUT_TOKENS, parseContextOverflow, planOutputCapAdjustment } from "./context-overflow.js";
-import { abortLikeName, BrainError, brainErrorCodeOf, classifyFetchThrow, classifyHttp, describeNetworkError, isProviderEchoShape, namesTheFailure, proxyTunnelRefusedSentence, readConnectFailure, readProviderErrorCode, readProviderRequestId, refusedTheRequest } from "./errors.js";
+import { abortLikeName, BrainError, brainErrorCodeOf, classifyFetchThrow, classifyHttp, describeNetworkError, isProviderEchoShape, namesTheFailure, proxyTunnelRefusedSentence, readConnectFailure, readProviderErrorCode, readProviderRequestId, refusedTheRequest, thrownBrainFailure } from "./errors.js";
 import { stripUrlCredentials } from "./route-adjudicator.js";
 import { admittedRequestRoute } from "./request-route.js";
 import { isTransientStatus, isProviderCondition, isProviderConditionSource, judgeHttpFailure, PROVIDER_CONDITION_TRAITS, resolveProviderDialect, } from "./provider-dialect.js";
@@ -314,10 +314,11 @@ export function runStreamingBrain(args) {
         }
         errorMsg.stopReason = aborted ? "aborted" : "error";
         errorMsg.errorMessage = thrownText(err);
-        if (!aborted && brainErrorCodeOf(err) !== undefined) {
-            if (readMember(err, "inputTooLong") === true)
-                errorMsg.errorKind = "input_too_long";
-            else if (readMember(err, "inputTooLongRuledOut") === true)
+        const failure = aborted ? {} : thrownBrainFailure(err);
+        if (failure.code !== undefined) {
+            if (failure.errorKind !== undefined)
+                errorMsg.errorKind = failure.errorKind;
+            else if (failure.inputTooLongRuledOut === true)
                 errorMsg.inputTooLongRuledOut = true;
             if (readMember(err, "errorBodyIncomplete") === true)
                 errorMsg.errorBodyIncomplete = true;

package/dist/brain/stream-shared.d.ts

@@ -14,7 +14,7 @@ import { type AssistantMessage, type ModelOutputInvalid, type StreamDropCause }
  *
  * Internal module: not re-exported from `src/index.ts`.
  */
-/** The warning (CC 2.1.220's words; gone from 2.1.245 on — 2.1.296 asks for a resume instead) stamped beside `partialFinalized` when a stream ended before its close — by the
+/** The warning (the reference's former words; later replaced by a resume request) stamped beside `partialFinalized` when a stream ended before its close — by the
  *  mid-stream promotion (the body threw) and by the parsers' own finalize (content arrived, no finish frame). */
 export declare const STREAM_TORN_WARNING = "Connection closed mid-response. The response above may be incomplete.";
 /** A provider word as a stream-end seat carries it: the word in the provider echo shape, else `?` — the fact that a