@sema-agent/core 7.55.0 → 7.57.0

package/dist/brain/openai.js

@@ -4,13 +4,14 @@ import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
 import { STREAM_TORN_WARNING, createRepetitionPoll, createStreamEndLedger, echoFoldedWord, modelOutputInvalidOf, noteResponseModel, nameMissingCause, parseStreamedToolArgs, placeTurnNotes, truncationCauseClause } from "./stream-shared.js";
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
-import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
-import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
+import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imageWithholdOf, imagesOmittedNoVisionNote, reportImagesWithheld, sendableImages } from "./media-degrade.js";
+import { capabilityHeld } from "./model-capability.js";
+import { OPENAI_RESERVED, OUTPUT_CAP_KEYS, applyExtraBody, declaredRequestValues, effectiveOutputCap, headerBagOnce, lockHeader, mergeHeaders } from "./request-params.js";
 import { BrainError, providerErrorWord } from "./errors.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";
+import { applyReasoningToRequest } from "./reasoning-request.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
 import { resolveFetch } from "./transport.js";
@@ -38,7 +39,7 @@ function textOf(content) {
 }
 const NO_CONTENT = "(no content)";
 const DOCUMENT_OMITTED = "[PDF document omitted: PDF direct read requires an Anthropic-family model; re-Read the file (the engine will extract text/render pages when possible) or extract the text via Bash instead (e.g. `pdftotext`).]";
-function toUserContent(content, supportsVision = true) {
+function toUserContent(content, withhold) {
     if (typeof content === "string") {
         return content;
     }
@@ -52,9 +53,9 @@ function toUserContent(content, supportsVision = true) {
             return base;
         return base ? `${base}\n${DOCUMENT_OMITTED}` : DOCUMENT_OMITTED;
     }
-    if (!supportsVision) {
+    if (withhold !== undefined) {
         const n = content.filter((c) => c.type === "image").length;
-        emitBrainTelemetry({ kind: "vision_placeholder", count: n });
+        reportImagesWithheld(withhold, n);
         const base = textOf(content);
         const note = imagesOmittedNoVisionNote(n);
         const withNote = base ? `${base}\n${note}` : note;
@@ -80,85 +81,11 @@ function toUserContent(content, supportsVision = true) {
 function thinkingCompat(model) {
     return (model.compat ?? {});
 }
-function applyThinking(body, model, reasoning) {
-    if (model.reasoning && reasoning === "off") {
-        const offCompat = thinkingCompat(model);
-        const offFormat = offCompat.thinkingFormat ?? "openai";
-        switch (offFormat) {
-            case "qwen":
-            case "zai":
-                body.enable_thinking = false;
-                break;
-            case "qwen-chat-template": {
-                const k = (typeof body.chat_template_kwargs === "object" && body.chat_template_kwargs) || {};
-                body.chat_template_kwargs = { ...k, enable_thinking: false };
-                break;
-            }
-            case "deepseek":
-                body.thinking = { type: "disabled" };
-                break;
-            case "openrouter":
-            case "together":
-                body.reasoning = { enabled: false };
-                break;
-            case "openai": {
-                const offSpelling = declaredOffSpelling(model);
-                if (offSpelling !== undefined)
-                    body.reasoning_effort = offSpelling;
-                break;
-            }
-            default: {
-                const _exhaustive = offFormat;
-                void _exhaustive;
-                break;
-            }
-        }
-        return;
-    }
-    if (!reasoningRequestCarried(model, reasoning))
-        return;
-    const compat = thinkingCompat(model);
-    const supportsEffort = compat.supportsReasoningEffort ?? true;
-    const effortWire = mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
-    const format = compat.thinkingFormat ?? "openai";
-    switch (format) {
-        case "openai":
-            if (supportsEffort && effortWire !== undefined)
-                body.reasoning_effort = effortWire;
-            break;
-        case "openrouter":
-            body.reasoning = { effort: effortWire };
-            break;
-        case "deepseek":
-            body.thinking = { type: "enabled" };
-            if (supportsEffort && effortWire !== undefined)
-                body.reasoning_effort = effortWire;
-            break;
-        case "together":
-            body.reasoning = { enabled: true };
-            if (supportsEffort && effortWire !== undefined)
-                body.reasoning_effort = effortWire;
-            break;
-        case "qwen":
-        case "zai":
-            body.enable_thinking = true;
-            break;
-        case "qwen-chat-template": {
-            const k = (typeof body.chat_template_kwargs === "object" && body.chat_template_kwargs) || {};
-            body.chat_template_kwargs = { ...k, enable_thinking: true };
-            break;
-        }
-        default: {
-            const _exhaustive = format;
-            void _exhaustive;
-            break;
-        }
-    }
-}
 function toOpenAIMessages(ctx, replayThinking = true, model, toolNames) {
-    const supportsVision = modelSupportsVision(model);
+    const imageWithhold = imageWithholdOf(model);
+    const supportsVision = imageWithhold === undefined;
     const out = [];
-    const needsEmptyReasoningField = !!model?.reasoning && thinkingCompat(model).requiresReasoningContentOnAssistantMessages === true;
+    const needsEmptyReasoningField = model !== undefined && capabilityHeld(model, "reasoning") && thinkingCompat(model).requiresReasoningContentOnAssistantMessages === true;
     if (ctx.systemPrompt) {
         out.push({ role: "system", content: ctx.systemPrompt });
     }
@@ -181,7 +108,7 @@ function toOpenAIMessages(ctx, replayThinking = true, model, toolNames) {
         if (m.role !== "toolResult")
             flushImages();
         if (m.role === "user") {
-            const uc = toUserContent(m.content, supportsVision);
+            const uc = toUserContent(m.content, imageWithhold);
             const empty = uc === "" || (Array.isArray(uc) && uc.length === 0);
             out.push({ role: "user", content: empty ? NO_CONTENT : uc });
         }
@@ -215,8 +142,8 @@ function toOpenAIMessages(ctx, replayThinking = true, model, toolNames) {
             const mediaImages = sendableImages(Array.isArray(m.content) ? m.content : []);
             const rawImages = m.isError ? [] : mediaImages;
             const images = supportsVision ? rawImages : [];
-            if (!supportsVision && rawImages.length > 0)
-                emitBrainTelemetry({ kind: "vision_placeholder", count: rawImages.length });
+            if (imageWithhold !== undefined)
+                reportImagesWithheld(imageWithhold, rawImages.length);
             const nDocs = Array.isArray(m.content) ? m.content.filter((c) => c.type === "document").length : 0;
             if (nDocs > 0)
                 emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
@@ -390,16 +317,18 @@ export function createOpenAIBrain(given = {}) {
                 }
                 if (options?.stop)
                     body.stop = options.stop;
-                applyThinking(body, model, options?.reasoning);
+                const { body: reasoningBody } = applyReasoningToRequest({ api: "openai-completions", model, level: options?.reasoning, body });
                 const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
                 applyRouteCredentialHeaders(headers, routeCredential);
+                const declaredValues = declaredRequestValues([modelHeaders, config.headers, optionsHeaders, headers], [], apiKey);
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     lockHeader(headers, OPENAI_KEY_HEADER, `Bearer ${apiKey}`);
-                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model, OPENAI_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(reasoningBody, model, OPENAI_RESERVED);
                 return {
                     url,
                     headers,
+                    declared: declaredValues,
                     body: JSON.stringify(wire),
                     extraBodyDropped,
                     route: requestRouteOf(routeCredential, rootOrigin),
@@ -432,7 +361,7 @@ export function createOpenAIBrain(given = {}) {
                 const responseIds = responseToolCallIds();
                 let finishReason = null;
                 let inBandError;
-                const afterEnd = createStreamEndLedger();
+                const afterEnd = createStreamEndLedger(ctrl.providerWords);
                 const terminalFrameSeen = () => finishReason != null || inBandError !== undefined;
                 let usageRaw;
                 let malformedFrames = 0;
@@ -520,7 +449,7 @@ export function createOpenAIBrain(given = {}) {
                         }
                         catch {
                             malformedFrames++;
-                            malformedSample ??= data.slice(0, 160);
+                            malformedSample ??= ctrl.providerWords(data).slice(0, 160);
                             return;
                         }
                         const stated = chunk.error;
@@ -529,7 +458,7 @@ export function createOpenAIBrain(given = {}) {
                                 afterEnd.note("error", providerErrorWord(stated) ?? "?");
                                 return;
                             }
-                            inBandError = inBandProviderError(ctrl.dialect, stated, "gateway");
+                            inBandError = inBandProviderError(ctrl.dialect, stated, "gateway", ctrl.providerWords);
                             ctrl.cancel();
                             return;
                         }
@@ -610,7 +539,7 @@ export function createOpenAIBrain(given = {}) {
                                     emptyPlaceholders++;
                                     continue;
                                 }
-                                (nameMissingCause(!endedCut) === "truncated" ? malformed : unnamed).push(`id="${acc.id || "?"}"(${acc.args.slice(0, 200)})`);
+                                (nameMissingCause(!endedCut) === "truncated" ? malformed : unnamed).push(`id="${ctrl.providerWords(acc.id || "?")}"(${ctrl.providerWords(acc.args).slice(0, 200)})`);
                                 continue;
                             }
                             const tc = closeToolCallAccum(acc, responseIds, !endedCut);
@@ -619,7 +548,7 @@ export function createOpenAIBrain(given = {}) {
                                 finalContent.push(tc);
                             }
                             else {
-                                malformed.push(`${acc.name}(${acc.args.slice(0, 200)})`);
+                                malformed.push(`${ctrl.providerWords(acc.name)}(${ctrl.providerWords(acc.args).slice(0, 200)})`);
                             }
                         }
                         if (config.repairTextToolCalls && toolCalls.length === 0 && textFace && context.tools && context.tools.length > 0) {
@@ -677,8 +606,8 @@ export function createOpenAIBrain(given = {}) {
                         const safetyCut = finishReading?.kind === "refusal";
                         const contextWindowExceeded = finishReading?.kind === "input_too_long";
                         const providerCut = finishReading?.kind === "provider_cut" ? finishReading : undefined;
-                        const finishReasonUnknown = finishReading?.kind === "unrecognized" ? echoFoldedWord(finishReason ?? "") : undefined;
-                        const finishQuoted = JSON.stringify((finishReason ?? "").slice(0, 64));
+                        const finishReasonUnknown = finishReading?.kind === "unrecognized" ? echoFoldedWord(finishReason ?? "", ctrl.providerWords) : undefined;
+                        const finishQuoted = JSON.stringify(ctrl.providerWords(finishReason ?? "").slice(0, 64));
                         const refused = accumRefusal.trim().length > 0;
                         const emptyNoFinish = noUsableContent && finishReason == null && !degenerate;
                         const maxTokensNote = sentMaxTokens !== undefined
@@ -693,7 +622,7 @@ export function createOpenAIBrain(given = {}) {
                             : safetyCut
                                 ? `[refusal] response cut by the provider content filter (finish_reason=${finishQuoted}) — the output was censored/truncated for policy and is unreliable`
                                 : refused
-                                    ? `[refusal] response refused by the model for policy reasons: ${accumRefusal.trim()}`
+                                    ? `[refusal] response refused by the model for policy reasons: ${ctrl.providerWords(accumRefusal.trim())}`
                                     : contextWindowExceeded
                                         ? `[invalid_request] model context window exceeded (finish_reason=${finishQuoted}) — the conversation no longer fits the model's context window`
                                         : providerCut !== undefined

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

@@ -240,11 +240,12 @@ export declare function judgeInBandError(dialect: ProviderDialect | undefined, e
  * The failure an in-band error frame states, as the brain error the stream's terminal carries: the code its
  * condition reads as ({@link PROVIDER_CONDITION_TRAITS}), the provider's word and sentence in the message, the word
  * on the echo seat, the verdict, and the context-limit reading of the same row. A frame the provider sent on its
- * own stream is a provider failure by construction (`apiError`); it states no status.
+ * own stream is a provider failure by construction (`apiError`); it states no status. The message carries the
+ * provider's words as the stream's mint (`providerWords`) renders them; the verdict reads the frame as it came.
  */
 export declare function inBandProviderError(dialect: ProviderDialect | undefined, envelope: {
     message?: unknown;
     code?: unknown;
     type?: unknown;
-}, label: string): BrainError;
+}, label: string, providerWords: (words: string) => string): BrainError;
 export {};

package/dist/brain/provider-dialect.js

@@ -201,11 +201,11 @@ export function judgeHttpFailure(args) {
 export function judgeInBandError(dialect, envelope) {
     return verdictOf(dialect, undefined, statementOf(envelope), true);
 }
-export function inBandProviderError(dialect, envelope, label) {
+export function inBandProviderError(dialect, envelope, label, providerWords) {
     const v = judgeInBandError(dialect, envelope);
     const word = carriedProviderWord(envelope);
     const sentence = typeof envelope.message === "string" ? envelope.message : "";
-    return new BrainError(PROVIDER_CONDITION_TRAITS[v.condition].inBandCode, `${label} stream error (${word ?? "unknown"}): ${sentence}`, undefined, {
+    return new BrainError(PROVIDER_CONDITION_TRAITS[v.condition].inBandCode, `${label} stream error ${providerWords(`(${word ?? "unknown"}): ${sentence}`)}`, undefined, {
         apiError: true,
         ...(v.inputTooLong === "yes" ? { inputTooLong: true } : v.inputTooLong === "no" ? { inputTooLongRuledOut: true } : {}),
         ...(word !== undefined ? { providerCode: word } : {}),

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.
@@ -58,7 +58,7 @@ export type ReasoningFormat = "openai" | "openrouter" | "deepseek" | "together"
  *  `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") {