@sema-agent/core 7.54.1 → 7.56.0

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

@@ -0,0 +1,96 @@
+import { type OffCapabilityModel, type ReasoningWireFacts } from "./reasoning.js";
+/**
+ * THE reasoning WIRE applier — the one place that knows how a requested thinking tier is spelled on each
+ * wire family. The three brains (completions, Responses, Messages) build their requests through
+ * {@link applyReasoningToRequest}, and a host that sends its own request to one of those endpoints (a title
+ * generator, a side query) calls the same function with the same model entry, so the keys it puts on the wire
+ * are the keys the engine would have put there — nothing is re-spelled per caller.
+ *
+ * What is decided elsewhere and only READ here: whether the request carries thinking at all
+ * ({@link reasoningRequestCarried}), the tier clamp and the `thinkingLevelMap` translation
+ * ({@link mintEffortWireValue}), and whether "off" has a deployment-declared spelling ({@link declaredOffSpelling}).
+ */
+/** The tiers a request for the answer alone can ask for: `off` where the wire spells it, `low` where it cannot. */
+export type ReasoningSeat = "off" | "low";
+/**
+ * The lowest reasoning tier a request for the answer alone can take on this model's wire — one predicate: does the wire
+ * spell off ({@link thinkingOffSpelled})? Yes ⇒ `"off"`, and the output cap needs room for the answer only. No ⇒ `"low"`:
+ * a model whose thinking the wire cannot turn off is asked for the least it can grade, and the cap needs room for that
+ * thinking too — `AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS` is the allowance the engine's own side requests add.
+ * A model that declares no reasoning is on the `low` seat as well: its wire carries nothing either way, so the request is
+ * the gateway's default, and a default-on gateway thinks.
+ *
+ * Callers pass the seat as `level` to {@link applyReasoningToRequest}; the classifier's seat tier is this verdict.
+ */
+export declare function lowestReasoningSeat(model: OffCapabilityModel): ReasoningSeat;
+/** The model entry the applier reads. A `Model` satisfies it; `id` only names the model in a refusal. */
+export interface ReasoningRequestModel extends OffCapabilityModel {
+    readonly id?: string;
+}
+/** The Messages-family knobs a host may set (the engine's own lane sets them from its construction config). */
+export interface ReasoningBudgetKnobs {
+    /**
+     * Whether `body.max_tokens` is a bound the caller set. `true` (the default): the cap is never raised, and thinking
+     * is skipped when the cap cannot host a legal budget plus answer room. `false`: the cap is a default the lane
+     * raises to host one.
+     */
+    capIsHard?: boolean;
+    /** The share of `max_tokens` the thinking budget takes; absent = the tier's own share. */
+    share?: number;
+    /** A fixed budget in tokens; overrides `share`. */
+    tokens?: number;
+}
+export interface ApplyReasoningInput {
+    /**
+     * The wire family of the request: `"anthropic-messages"` (Messages), one of the Open Responses apis
+     * (`openai-responses`, `azure-openai-responses`, `openai-chatgpt-responses`), anything else = the chat-completions
+     * family, whose `model.compat.thinkingFormat` picks the dialect. A host passes the model entry's own `api`.
+     */
+    api: string;
+    model: ReasoningRequestModel;
+    /** The requested tier. `"off"` is spelled where the wire has an off spelling; `undefined` and any value that is
+     *  not a {@link ThinkingLevel} write nothing (the provider's default). */
+    level: string | undefined;
+    /** The request body so far. Never mutated — the result carries a copy. */
+    body: Readonly<Record<string, unknown>>;
+    /** Messages family only: a body with no numeric `max_tokens` is refused where the budget needs one. */
+    budget?: ReasoningBudgetKnobs;
+}
+export interface AppliedReasoning {
+    /** A copy of the input body with the thinking keys written (and, on Messages, `temperature` dropped when thinking is on). */
+    body: Record<string, unknown>;
+    /**
+     * The request headers the thinking keys need, to be folded into the request's own with
+     * {@link mergeReasoningHeaders}: the Messages family's `anthropic-beta` list (effort, context management,
+     * interleaved thinking — whichever the model entry declares). `{}` where the wire needs none.
+     */
+    headers: Record<string, string>;
+    /** The effort value the request carries (completions `reasoning_effort`, Responses `reasoning.effort`), or `undefined`. */
+    effort: string | undefined;
+    /** Messages budget form only: the output-cap facts the thinking decision weighed (see {@link ReasoningWireFacts}). */
+    wireFacts: ReasoningWireFacts | undefined;
+}
+/**
+ * Write the thinking keys a requested tier needs onto a request body, in the dialect of the model's wire family, and
+ * say which headers the keys need. A pure function of (api, model entry, level, body): the input body is not mutated,
+ * the result carries the body to send and the headers to fold into the request's own.
+ *
+ * It answers the question a host that builds its own request has — "which keys does THIS model take for THIS tier?" —
+ * from the same table the engine's brains read, so a host never keeps a copy of a dialect. Absence is meaningful:
+ * a model that does not declare `reasoning`, a `level` that is `undefined` or not a real tier, and a tier the wire
+ * cannot carry write nothing, and the provider's default governs.
+ *
+ * @example
+ * const { body, headers } = applyReasoningToRequest({ api: model.api, model, level: "low", body: { model: model.id, max_tokens: 2304, messages } });
+ * mergeReasoningHeaders(requestHeaders, headers);
+ */
+export declare function applyReasoningToRequest(input: ApplyReasoningInput): AppliedReasoning;
+/**
+ * Fold the header patch {@link applyReasoningToRequest} returned into a request's headers, in place. A beta LIST
+ * (`anthropic-beta`) is unioned with whatever the request already sends under that name in any letter case and in any
+ * number of spellings (a spelling that holds no string contributes none and is claimed all the same) — the existing
+ * entries first, as given, then each new entry not already there, written under the lowercase name; any other name
+ * replaces its case variants. Assigning the patch over the headers instead would drop a beta the request already carries.
+ * This is the ONE reading of the beta list: the Messages brain folds its own header layers through it too.
+ */
+export declare function mergeReasoningHeaders(headers: Record<string, string>, patch: Readonly<Record<string, string>>): void;

package/dist/brain/reasoning-request.js

@@ -0,0 +1,174 @@
+import { capabilityHeld } from "./model-capability.js";
+import { headerListEntries, lockHeader, takeHeaderSpellings } from "./request-params.js";
+import { MIN_THINKING_TOKENS, RESPONSES_APIS, budgetCapSkipsThinking, declaredEffortLevels, declaredOffSpelling, mintEffortWireValue, reasoningBudgetShare, reasoningRequestCarried, resolveEffort, thinkingOffSpelled, } from "./reasoning.js";
+export function lowestReasoningSeat(model) {
+    return thinkingOffSpelled(model) ? "off" : "low";
+}
+const BETA_EFFORT = "effort-2025-11-24";
+const BETA_CONTEXT_MANAGEMENT = "context-management-2025-06-27";
+const BETA_INTERLEAVED_THINKING = "interleaved-thinking-2025-05-14";
+function put(body, key, value) {
+    body[key] = value;
+    return undefined;
+}
+function withTemplateKwarg(body, enabled) {
+    const kwargs = (typeof body.chat_template_kwargs === "object" && body.chat_template_kwargs) || {};
+    return put(body, "chat_template_kwargs", { ...kwargs, enable_thinking: enabled });
+}
+function withEffort(body, effort, supportsEffort) {
+    if (!supportsEffort || effort === undefined)
+        return undefined;
+    body.reasoning_effort = effort;
+    return effort;
+}
+const COMPLETIONS_DIALECT = {
+    openai: {
+        off: (body, model) => {
+            const spelling = declaredOffSpelling(model);
+            return spelling === undefined ? undefined : withEffort(body, spelling, true);
+        },
+        on: withEffort,
+    },
+    openrouter: {
+        off: (body) => put(body, "reasoning", { enabled: false }),
+        on: (body, effort) => {
+            put(body, "reasoning", { effort });
+            return effort;
+        },
+    },
+    deepseek: {
+        off: (body) => put(body, "thinking", { type: "disabled" }),
+        on: (body, effort, supportsEffort) => {
+            put(body, "thinking", { type: "enabled" });
+            return withEffort(body, effort, supportsEffort);
+        },
+    },
+    together: {
+        off: (body) => put(body, "reasoning", { enabled: false }),
+        on: (body, effort, supportsEffort) => {
+            put(body, "reasoning", { enabled: true });
+            return withEffort(body, effort, supportsEffort);
+        },
+    },
+    qwen: { off: (body) => put(body, "enable_thinking", false), on: (body) => put(body, "enable_thinking", true) },
+    zai: { off: (body) => put(body, "enable_thinking", false), on: (body) => put(body, "enable_thinking", true) },
+    "qwen-chat-template": { off: (body) => withTemplateKwarg(body, false), on: (body) => withTemplateKwarg(body, true) },
+};
+function completionsDialectOf(format) {
+    return typeof format === "string" && Object.prototype.hasOwnProperty.call(COMPLETIONS_DIALECT, format) ? COMPLETIONS_DIALECT[format] : undefined;
+}
+const bodyOnly = (body, effort) => ({ body, headers: {}, effort, wireFacts: undefined });
+function applyCompletions(input, body) {
+    const { model, level } = input;
+    const compat = (model.compat ?? {});
+    const dialect = completionsDialectOf(compat.thinkingFormat ?? "openai");
+    if (capabilityHeld(model, "reasoning") && level === "off")
+        return bodyOnly(body, dialect?.off(body, model));
+    if (!reasoningRequestCarried(model, level))
+        return bodyOnly(body);
+    const supportsEffort = compat.supportsReasoningEffort ?? true;
+    const wire = mintEffortWireValue(level, model, compat.reasoningEffortLevels).wireValue;
+    return bodyOnly(body, dialect?.on(body, wire, supportsEffort));
+}
+function applyResponses(input, body) {
+    const { model, level } = input;
+    const effort = responsesEffort(model, level);
+    if (effort !== undefined)
+        body.reasoning = { effort };
+    return bodyOnly(body, effort);
+}
+function responsesEffort(model, level) {
+    if (capabilityHeld(model, "reasoning") && level === "off")
+        return declaredOffSpelling(model);
+    const compat = (model.compat ?? {});
+    if (compat.supportsReasoningEffort === false)
+        return undefined;
+    if (!reasoningRequestCarried(model, level))
+        return undefined;
+    return mintEffortWireValue(level, model, compat.reasoningEffortLevels).wireValue;
+}
+function thinkingBudget(maxTokens, share, fixed, hardCap) {
+    const max = hardCap ? maxTokens : Math.max(maxTokens, MIN_THINKING_TOKENS * 2);
+    const want = fixed ?? Math.floor(max * share);
+    const budget = Math.min(Math.max(MIN_THINKING_TOKENS, want), max - 1);
+    return { max, budget };
+}
+function applyMessages(input, body) {
+    const { model, level } = input;
+    const compat = (model.compat ?? {});
+    let wireFacts;
+    let thinkingOn = false;
+    if (reasoningRequestCarried(model, level)) {
+        if (compat.thinkingMode === "adaptive") {
+            body.thinking = { type: "adaptive" };
+            thinkingOn = true;
+        }
+        else {
+            if (body.max_tokens === undefined || body.max_tokens === null) {
+                throw new TypeError("applyReasoningToRequest: the Messages budget form needs a body.max_tokens (it sizes the thinking budget)");
+            }
+            const maxTokens = body.max_tokens;
+            const hardCap = input.budget?.capIsHard ?? true;
+            wireFacts = { outputCapTokens: maxTokens, hardOutputCap: hardCap };
+            if (budgetCapSkipsThinking(wireFacts.outputCapTokens, wireFacts.hardOutputCap)) {
+                delete body.thinking;
+            }
+            else {
+                const share = input.budget?.share ?? reasoningBudgetShare(level);
+                const { max, budget } = thinkingBudget(maxTokens, share, input.budget?.tokens, hardCap);
+                if (!Number.isFinite(Number(max)) || !Number.isFinite(budget)) {
+                    const shown = (value) => (typeof value === "string" ? JSON.stringify(value) : String(value));
+                    throw new TypeError(`applyReasoningToRequest: the Messages budget form cannot size a thinking budget from body.max_tokens ${shown(body.max_tokens)}, ` +
+                        `budget.share ${shown(share)}, budget.tokens ${shown(input.budget?.tokens)} (cap ${shown(max)}, budget ${shown(budget)}); each must read as a finite number`);
+                }
+                body.max_tokens = max;
+                body.thinking = { type: "enabled", budget_tokens: budget };
+                thinkingOn = true;
+            }
+        }
+        if (thinkingOn)
+            delete body.temperature;
+    }
+    else if (capabilityHeld(model, "reasoning") && level === "off" && compat.thinkingMode !== "adaptive") {
+        body.thinking = { type: "disabled" };
+    }
+    const betas = [];
+    let effort;
+    const declaredEffort = declaredEffortLevels(compat.effortLevels);
+    if (declaredEffort !== undefined && reasoningRequestCarried(model, level)) {
+        const { effective } = resolveEffort(level, declaredEffort);
+        effort = effective === "minimal" ? "low" : effective;
+        body.output_config = { effort };
+        betas.push(BETA_EFFORT);
+    }
+    if (compat.contextManagement && thinkingOn) {
+        body.context_management = { edits: [{ type: "clear_thinking_20251015", keep: "all" }] };
+        betas.push(BETA_CONTEXT_MANAGEMENT);
+    }
+    if (compat.interleavedThinking)
+        betas.push(BETA_INTERLEAVED_THINKING);
+    return { body, headers: betas.length > 0 ? { "anthropic-beta": betas.join(",") } : {}, effort, wireFacts };
+}
+export function applyReasoningToRequest(input) {
+    const body = { ...input.body };
+    if (input.api === "anthropic-messages")
+        return applyMessages(input, body);
+    if (RESPONSES_APIS.has(input.api))
+        return applyResponses(input, body);
+    return applyCompletions(input, body);
+}
+export function mergeReasoningHeaders(headers, patch) {
+    for (const [name, value] of Object.entries(patch)) {
+        const lower = name.toLowerCase();
+        if (lower !== "anthropic-beta") {
+            lockHeader(headers, lower, value);
+            continue;
+        }
+        const present = takeHeaderSpellings(headers, lower).flatMap((held) => headerListEntries(held));
+        for (const beta of headerListEntries(value)) {
+            if (!present.includes(beta))
+                present.push(beta);
+        }
+        headers[lower] = present.join(",");
+    }
+}

package/dist/brain/reasoning.d.ts

@@ -18,8 +18,8 @@ export type ReasoningIntensity = ThinkingLevel;
 export declare function isThinkingLevel(v: unknown): v is ThinkingLevel;
 /**
  * THE thinking-request ENTRY predicate — does this request enter an applier's emission path at all?
- * One conjunction, three arms: the model declares reasoning (TRUTHINESS — the adapters' own
- * judgment, see the r5 note in {@link resolveReasoning}), the requested value is a real
+ * One conjunction, three arms: the model holds reasoning (`capabilityHeld`, the one capability reading —
+ * a declaration of the wrong shape throws there instead of reading by truthiness), the requested value is a real
  * {@link ThinkingLevel} (an out-of-contract value — a typo'd tier, a caller's own enum — reads as
  * ABSENCE, never as a declared tier), and it is not the explicit `"off"`.
  *
@@ -29,8 +29,8 @@ export declare function isThinkingLevel(v: unknown): v is ThinkingLevel;
  * their own reporting shape (the `graded:false` intent-echo family, each pinned with its rationale
  * where it lives); this predicate only closes the gate the three appliers used to re-spell.
  *
- * Single-sourced here because every wire applier (openai.ts `applyThinking`, anthropic.ts's thinking
- * + effort arms, open-responses.ts `resolveWireEffort`) would otherwise re-spell the same three
+ * Single-sourced here because every wire applier (the completions, Messages and Responses arms of
+ * `applyReasoningToRequest`, in reasoning-request.ts) would otherwise re-spell the same three
  * conjuncts while the REPORTING resolver ({@link resolveReasoning}) mirrored one of them, so a
  * garbage tier puts ZERO parameters on the wire while the resolution claims a clamped-to-minimal
  * gradient. A predicate the appliers and the reporter both call cannot drift.
@@ -53,12 +53,12 @@ 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"
 /** OpenAI Responses API (`openai-responses` / `azure-openai-responses`, design/163): the tier rides
- *  the NESTED `reasoning: { effort }` request field (open-responses.ts `resolveWireEffort`), clamped
+ *  the NESTED `reasoning: { effort }` request field (the Responses arm of `applyReasoningToRequest`), clamped
  *  by the same {@link resolveEffort} against `compat.reasoningEffortLevels` — NOT the completions
  *  top-level `reasoning_effort` the `"openai"` tag names. #325 review r3: before this member the
  *  resolver fell through to the completions default and labeled Responses resolutions `"openai"`. */
@@ -127,7 +127,7 @@ export declare function declaredOffSpelling(model: OffCapabilityModel): string |
  * `reasoning:{enabled:false}` all spell it; the effort-only wires (stock openai completions, the Responses
  * lane) spell it only through a deployment-declared off spelling ({@link declaredOffSpelling}).
  *
- * A model whose `reasoning` is FALSY spells NOTHING: every applier returns before writing any key for it, so
+ * A model that does not hold reasoning (declared false, or undeclared — `capabilityHeld`) spells NOTHING: every applier returns before writing any key for it, so
  * the request is the gateway's own default — and a default-on gateway thinks regardless (three of four live
  * endpoints, 2026-09-15). This arm used to answer `true` ("a non-reasoning model never thinks"): the engine
  * may size a request by what it SENT, never by what it hopes a gateway does when told nothing. What this
@@ -172,8 +172,8 @@ export interface ReasoningWireFacts {
 export declare function declaredEffortLevels(v: unknown): readonly ThinkingLevel[] | undefined;
 /**
  * The effort-lane WIRE-VALUE mint — clamp ({@link resolveEffort}) + the `Model.thinkingLevelMap`
- * translation in ONE place, consumed by both completions-family appliers (openai.ts `applyThinking`,
- * open-responses.ts `resolveWireEffort`) AND the reporting dispatch ({@link resolveReasoning}'s
+ * translation in ONE place, consumed by both effort-lane arms of `applyReasoningToRequest` (completions,
+ * Responses) AND the reporting dispatch ({@link resolveReasoning}'s
  * arms), so the value that reaches the wire and the resolution a trace/result face claims are two
  * reads of one computation, never parallel re-derivations. Map semantics (the field's contract): a
  * MISSING key ⇒ provider default (the clamped tier name as-is); a STRING ⇒ that provider-specific
@@ -200,7 +200,7 @@ export interface ResolvedReasoning extends ReasoningResolution {
     endpoint: string;
     /**
      * Present (true) only when the request never CARRIES at all: {@link reasoningRequestCarried} false
-     * on a non-"off" request — the model declares NO reasoning capability (`Model.reasoning` falsy),
+     * on a non-"off" request — the model does not hold reasoning (`capabilityHeld`: declared false or undeclared),
      * OR the requested value is not a valid {@link ThinkingLevel} (an out-of-contract tier every wire
      * applier reads as ABSENCE — the same three-conjunct gate all of them share) — or, with
      * {@link ReasoningWireFacts} supplied, the anthropic budget path's cap-wins skip
@@ -212,7 +212,7 @@ export interface ResolvedReasoning extends ReasoningResolution {
      * reason at its own tier — the brains deliberately send no disable key for a model declared
      * non-reasoning, so the engine cannot claim a measured off there; `format` tells a consumer which
      * family applies (on every other format, absence is the closest the wire has to off — see
-     * applyThinking's own contract). `format`/`endpoint` report the family that WOULD have carried the
+     * the completions arm's own contract). `format`/`endpoint` report the family that WOULD have carried the
      * tier (the why-shape a consumer diagnoses with, not a claim about the request). Absent on every
      * reasoning-capable resolution, so existing consumers see byte-identical objects. Loud-bad-values
      * rule: the one arm where the request evaporates must not be the one arm with no report.
@@ -240,7 +240,7 @@ export interface ResolvedReasoning extends ReasoningResolution {
  *   drops the value — trace/result-face drift.
  *
  * - A request that never CARRIES ({@link reasoningRequestCarried} false on a non-"off" value: the model's
- *   `reasoning` capability flag is FALSY, or the requested value is not a valid tier — no brain emits any
+ *   `reasoning` capability is not held, or the requested value is not a valid tier — no brain emits any
  *   thinking parameter for either, whatever the format) → `effective:"off"`, `graded:false`, `clamped:true`,
  *   `dropped:true` — the loud-drop arm. Describing the capability dispatch instead would report a
  *   resolution the request never carried, leaving the one arm where the request evaporates as the one

package/dist/brain/reasoning.js

@@ -1,3 +1,4 @@
+import { capabilityHeld } from "./model-capability.js";
 const RANK = {
     off: 0,
     minimal: 1,
@@ -11,7 +12,7 @@ export function isThinkingLevel(v) {
     return typeof v === "string" && Object.prototype.hasOwnProperty.call(RANK, v);
 }
 export function reasoningRequestCarried(model, reasoning) {
-    return !!model.reasoning && isThinkingLevel(reasoning) && reasoning !== "off";
+    return capabilityHeld(model, "reasoning") && isThinkingLevel(reasoning) && reasoning !== "off";
 }
 export function rankOf(level) {
     return RANK[level];
@@ -31,7 +32,7 @@ export function declaredOffSpelling(model) {
     return typeof mapped === "string" && mapped !== "" ? mapped : undefined;
 }
 export function thinkingOffSpelled(model) {
-    if (!model.reasoning)
+    if (!capabilityHeld(model, "reasoning"))
         return false;
     const compat = (model.compat ?? {});
     if (model.api === "anthropic-messages")
@@ -101,7 +102,7 @@ function dispatchReasoning(requested, model, facts) {
     return { ...mint.resolution, format, endpoint };
 }
 export function reasoningEffortLevelsOf(model) {
-    if (!model.reasoning)
+    if (!capabilityHeld(model, "reasoning"))
         return undefined;
     const compat = (model.compat ?? {});
     if (model.api === "anthropic-messages") {

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[];
 };
@@ -72,12 +122,15 @@ export declare function applyExtraBody(body: Record<string, unknown>, extraBody:
 export declare function lockHeader(headers: Record<string, string>, lowerName: string, value: string): void;
 /**
  * #343 (review r4) — case-fold READ-AND-CLAIM for an AUGMENTABLE structural header (`anthropic-beta`):
- * returns the current value under whatever spelling the user bag carried and deletes that spelling,
- * so the caller's canonical lowercase write REPLACES it instead of duplicating beside it (the
+ * returns the value under EVERY spelling the bag carried, in key order, and deletes them all, so the
+ * caller's canonical lowercase write REPLACES them instead of duplicating beside them (the
  * read-modify-write used to key the read by the exact lowercase name and miss `Anthropic-Beta`,
- * losing the user's betas from the merge AND double-sending the header).
+ * losing the user's betas from the merge AND double-sending the header). A spelling is claimed whatever
+ * it holds — its value is returned as it is, so a spelling holding `undefined` does not end the claim.
  */
-export declare function takeHeaderCasefold(headers: Record<string, string>, lowerName: string): string | undefined;
+export declare function takeHeaderSpellings(headers: Record<string, string>, lowerName: string): unknown[];
+/** The entries of a comma-list header value (`" a , b,,c"` → `a`, `b`, `c`); a value that is not a string carries none. */
+export declare function headerListEntries(value: unknown): string[];
 /** A caller's header bag read ONCE, into a plain copy of its own enumerable entries — what a request build hands both
  *  the route law (which credential rides, and its identity) and the merge (what goes on the wire), so a bag whose getters
  *  or keys answer differently on a second read cannot be judged as one bag and sent as another. */
@@ -94,8 +147,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
@@ -60,15 +92,18 @@ export function lockHeader(headers, lowerName, value) {
     }
     headers[lowerName] = value;
 }
-export function takeHeaderCasefold(headers, lowerName) {
+export function takeHeaderSpellings(headers, lowerName) {
+    const values = [];
     for (const k of Object.keys(headers)) {
         if (k.toLowerCase() === lowerName) {
-            const v = headers[k];
+            values.push(headers[k]);
             delete headers[k];
-            return v;
         }
     }
-    return undefined;
+    return values;
+}
+export function headerListEntries(value) {
+    return typeof value === "string" ? value.split(",").map((entry) => entry.trim()).filter((entry) => entry !== "") : [];
 }
 export function headerBagOnce(bag) {
     return bag === undefined ? undefined : { ...bag };

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 } : {}),
+        },
+    };
+}