@sema-agent/core 7.55.0 → 7.56.0

package/dist/brain/media-degrade.d.ts

@@ -7,15 +7,26 @@
  * sentence that drifts is a string consumers grep for.
  */
 import type { Model } from "../internal/llm.js";
+import { type CapabilityDeclaration } from "./model-capability.js";
+/** Why a request's images are withheld from the SERVING model: the entry's image declaration, when it is not held
+ *  (the withheld-capability report's `cause`, `status-sink.ts`). */
+export type ImageWithholdCause = Exclude<CapabilityDeclaration, "declared_on">;
+/** A request whose images are withheld: which model, and why. */
+export interface ImageWithhold {
+    readonly modelId: string;
+    readonly cause: ImageWithholdCause;
+}
 /**
- * Whether the SERVING model accepts image input (`Model.input` contains "image").
- *
- * An ABSENT `input` is deliberately permissive (vision on): the field is caller-supplied metadata,
- * and treating "not declared" as "not capable" would silently downgrade every caller who never
- * filled it in. A caller that genuinely serves a text-only endpoint declares `input: ["text"]` and
- * gets the placeholder path — the case a text-only API rejects with a hard 400 on an image part.
+ * The image row of the capability table for one request: `undefined` = images ride as images; otherwise the model and
+ * the declaration that withholds them. Read off the one capability reading (`capabilityHeld` / `capabilityOf`), so an
+ * entry that never declared `input` gets its images exactly as the table says, and an entry that declares a list without
+ * `"image"` gets the placeholder path — the case a text-only API rejects with a hard 400 on an image part. No model =
+ * images ride.
  */
-export declare function modelSupportsVision(model?: Model): boolean;
+export declare function imageWithholdOf(model?: Model): ImageWithhold | undefined;
+/** Report `count` images of one request replaced by placeholders — the one emit for every lane: the operator trace frame
+ *  (telemetry, per request) and the leg's withheld-capability account (the person's notice, once per conversation). */
+export declare function reportImagesWithheld(withhold: ImageWithhold, count: number): void;
 /** Placeholder for an image block dropped because the serving model declares no image input. */
 export declare const IMAGE_OMITTED_NO_VISION = "[image omitted: the serving model does not support image input]";
 /** {@link IMAGE_OMITTED_NO_VISION}, counted — a batch of dropped images states how many were lost. */

package/dist/brain/media-degrade.js

@@ -1,5 +1,16 @@
-export function modelSupportsVision(model) {
-    return model?.input === undefined ? true : model.input.includes("image");
+import { capabilityHeld, capabilityOf } from "./model-capability.js";
+import { emitBrainTelemetry, reportCapabilityWithheld } from "./status-sink.js";
+export function imageWithholdOf(model) {
+    if (model === undefined)
+        return undefined;
+    const declared = capabilityOf(model, "image");
+    return declared === "declared_on" || capabilityHeld(model, "image") ? undefined : { modelId: model.id, cause: declared };
+}
+export function reportImagesWithheld(withhold, count) {
+    if (count === 0)
+        return;
+    emitBrainTelemetry({ kind: "vision_placeholder", count });
+    reportCapabilityWithheld({ modelId: withhold.modelId, capability: "image", cause: withhold.cause, count });
 }
 export const IMAGE_OMITTED_NO_VISION = "[image omitted: the serving model does not support image input]";
 export function imagesOmittedNoVisionNote(count) {

package/dist/brain/model-capability.d.ts

@@ -0,0 +1,37 @@
+/**
+ * The ONE reading of a model's capability declarations — image input and reasoning.
+ *
+ * A `Model` declares each capability in one of three states: on (`reasoning: true`; `input` lists `"image"`), off
+ * (`reasoning: false`; an `input` list without `"image"`), or not at all (the key is absent). Every reader in the engine
+ * (bar the PDF profile's no-metadata shortcut in `pdfModelCapabilitiesOf`, which looks at the absence itself) asks {@link capabilityOf} for the declaration, or {@link capabilityHeld} for "does the engine treat this model as
+ * having it", and what an undeclared capability means is stated once, in {@link UNKNOWN_CAPABILITY_READS} — no caller
+ * decides it for itself. A request never carries a capability declared off; one declared on is never dropped here.
+ *
+ * A declaration of the wrong shape is refused where it is read: a `reasoning` that is not a boolean, or an `input` that
+ * is not a list of strings, throws, naming the model and the key. Reading it some other way (by truthiness, or as
+ * undeclared) would turn a typo into a capability nobody declared.
+ */
+import type { Model } from "../internal/llm.js";
+/** The capabilities a model declares. `image` = accepts image input (`Model.input` lists `"image"`). */
+export declare const MODEL_CAPABILITIES: readonly ["image", "reasoning"];
+export type ModelCapability = (typeof MODEL_CAPABILITIES)[number];
+/** What a model's entry says about one capability. `unknown` = the entry does not say. */
+export declare const CAPABILITY_DECLARATIONS: readonly ["declared_on", "declared_off", "unknown"];
+export type CapabilityDeclaration = (typeof CAPABILITY_DECLARATIONS)[number];
+/**
+ * What the engine does with a capability the entry does not declare, per capability — the only place this is said.
+ * Image input is used (an entry that never filled in `input` keeps the images it was always sent). Reasoning is not:
+ * no thinking keys go out for an entry that does not declare `reasoning` (the request is the provider's default).
+ */
+export declare const UNKNOWN_CAPABILITY_READS: Readonly<Record<ModelCapability, "held" | "not_held">>;
+/** The part of a model this module reads (`id` only names the model in a refusal; the structural readers that take a
+ *  model-shaped object without one still get the same answer). */
+export type CapabilityDeclaringModel = {
+    readonly id?: Model["id"];
+    readonly reasoning?: unknown;
+    readonly input?: unknown;
+};
+/** The entry's declaration of `cap`. Throws a `TypeError` on a declaration of the wrong shape (see the module note). */
+export declare function capabilityOf(model: CapabilityDeclaringModel, cap: ModelCapability): CapabilityDeclaration;
+/** Whether the engine treats the model as having `cap`: declared on, or undeclared where {@link UNKNOWN_CAPABILITY_READS} says held. */
+export declare function capabilityHeld(model: CapabilityDeclaringModel, cap: ModelCapability): boolean;

package/dist/brain/model-capability.js

@@ -0,0 +1,34 @@
+export const MODEL_CAPABILITIES = Object.freeze(["image", "reasoning"]);
+export const CAPABILITY_DECLARATIONS = Object.freeze(["declared_on", "declared_off", "unknown"]);
+export const UNKNOWN_CAPABILITY_READS = Object.freeze({
+    image: "held",
+    reasoning: "not_held",
+});
+function typeWordOf(value) {
+    return value === null ? "null" : Array.isArray(value) ? "array" : typeof value;
+}
+function nameOf(model) {
+    return typeof model.id === "string" ? `"${model.id}"` : "a model with no id";
+}
+export function capabilityOf(model, cap) {
+    if (cap === "reasoning") {
+        const declared = model.reasoning;
+        if (declared === undefined)
+            return "unknown";
+        if (typeof declared !== "boolean") {
+            throw new TypeError(`Model.reasoning of ${nameOf(model)} must be true, false or absent; got ${typeWordOf(declared)}`);
+        }
+        return declared ? "declared_on" : "declared_off";
+    }
+    const input = model.input;
+    if (input === undefined)
+        return "unknown";
+    if (!Array.isArray(input) || !input.every((m) => typeof m === "string")) {
+        throw new TypeError(`Model.input of ${nameOf(model)} must be a list of input kinds or absent; got ${Array.isArray(input) ? "a list holding a non-string" : typeWordOf(input)}`);
+    }
+    return input.includes("image") ? "declared_on" : "declared_off";
+}
+export function capabilityHeld(model, cap) {
+    const declared = capabilityOf(model, cap);
+    return declared === "declared_on" || (declared === "unknown" && UNKNOWN_CAPABILITY_READS[cap] === "held");
+}

package/dist/brain/model-presets.d.ts

@@ -19,16 +19,10 @@ import type { AnthropicMessagesCompat, Model } from "../internal/llm.js";
  * - `supportsTemperature: false` — CC never sends temperature to this class, thinking on OR off.
  */
 export declare const FABLE_5_COMPAT: AnthropicMessagesCompat;
-/**
- * The fable lines the classic prompt shape serves. They are prompt text, so they live with the prompt
- * text; this name stays exported for hosts that read them. The preset below no longer carries them as
- * `promptGuidance`: the prompt composes them itself, once, where they are the only fable text.
- */
-export declare const FABLE_5_PROMPT_GUIDANCE: readonly string[];
 /**
  * A ready-to-use `claude-fable-5` {@link Model} (registry facts: 1M-token native context
  * window, 64k default max output — the 128k tier is opt-in via `maxTokens` override, knowledge
- * cutoff Jan 2026, `default_effort: "high"`). Override anything per deployment; set `cost` for
- * accounting (not baked — see module note).
+ * cutoff Jan 2026, `default_effort: "high"`, prompt capabilities `lean_prompt` + `fable_5_mitigations`).
+ * Override anything per deployment; set `cost` for accounting (not baked — see module note).
  */
 export declare function fable5Model(overrides?: Partial<Model>): Model;

package/dist/brain/model-presets.js

@@ -1,15 +1,9 @@
-import { catalogText } from "../prompt-assembly/catalog/index.js";
 import { ANTHROPIC_DEFAULT_BASE_URL } from "./anthropic.js";
 export const FABLE_5_COMPAT = {
     thinkingMode: "adaptive",
     effortLevels: ["low", "medium", "high", "xhigh", "max"],
     supportsTemperature: false,
 };
-export const FABLE_5_PROMPT_GUIDANCE = [
-    catalogText("core/behavior.fable-classic.final-message"),
-    catalogText("core/behavior.fable-classic.autonomy"),
-    catalogText("core/behavior.fable-classic.tool-json"),
-];
 export function fable5Model(overrides = {}) {
     return {
         id: "claude-fable-5",
@@ -25,6 +19,7 @@ export function fable5Model(overrides = {}) {
         maxTokens: 64_000,
         charsPerToken: 3,
         compat: { ...FABLE_5_COMPAT },
+        promptTraits: ["lean_prompt", "fable_5_mitigations"],
         ...overrides,
     };
 }

package/dist/brain/open-responses.js

@@ -4,12 +4,12 @@ import { DEGENERATE_MESSAGE, trimDegenerateTail } from "./repetition.js";
 import { STREAM_TORN_WARNING, createRepetitionPoll, modelOutputInvalidOf, noteResponseModel, nameMissingCause, parseStreamedToolArgs, placeTurnNotes } from "./stream-shared.js";
 import { admitToolCallId, providerResultIds, providerToolCallId, responseToolCallIds } from "./tool-call-id.js";
 import { emitBrainTelemetry } from "./status-sink.js";
-import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imagesOmittedNoVisionNote, modelSupportsVision, sendableImages } from "./media-degrade.js";
+import { errorResultMediaNote, IMAGE_OMITTED_NO_VISION, imageWithholdOf, imagesOmittedNoVisionNote, reportImagesWithheld, sendableImages } from "./media-degrade.js";
 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 { applyReasoningToRequest } from "./reasoning-request.js";
 import { runStreamingBrain } from "./stream-engine.js";
 import { refuseRetiredTimeoutKnobs } from "./timeout.js";
 import { resolveFetch } from "./transport.js";
@@ -18,9 +18,6 @@ const DEGENERATE_POLL_CHARS = 64;
 const MALFORMED_SAMPLE_CHARS = 160;
 const MALFORMED_ARGS_CHARS = 200;
 const CAPABILITY_DIAGNOSTIC_TYPE = "responses_capability";
-function responsesCompat(model) {
-    return (model.compat ?? {});
-}
 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 textOf(content) {
@@ -38,16 +35,17 @@ function functionCallOutputText(text, hasCarriedImages, original) {
         return "(image attached below)";
     return Array.isArray(original) && original.length > 0 ? "(non-text tool result omitted)" : "";
 }
-function toUserParts(content, supportsVision) {
+function toUserParts(content, withhold) {
     if (typeof content === "string") {
         return content === "" ? [] : [{ type: "input_text", text: content }];
     }
+    const supportsVision = withhold === undefined;
     const nDocs = content.filter((c) => c.type === "document").length;
     if (nDocs > 0)
         emitBrainTelemetry({ kind: "document_placeholder", count: nDocs });
     const images = content.filter((c) => c.type === "image" && c.data !== undefined && c.mimeType !== undefined);
-    if (!supportsVision && images.length > 0)
-        emitBrainTelemetry({ kind: "vision_placeholder", count: images.length });
+    if (withhold !== undefined)
+        reportImagesWithheld(withhold, images.length);
     const parts = [];
     for (const c of content) {
         if (c.type === "text" && typeof c.text === "string" && c.text.length > 0) {
@@ -66,7 +64,8 @@ function toUserParts(content, supportsVision) {
     return parts;
 }
 function toResponsesInput(ctx, model, replayReasoning, toolNames) {
-    const supportsVision = modelSupportsVision(model);
+    const imageWithhold = imageWithholdOf(model);
+    const supportsVision = imageWithhold === undefined;
     const out = [];
     let pendingImages = [];
     const flushImages = () => {
@@ -88,7 +87,7 @@ function toResponsesInput(ctx, model, replayReasoning, toolNames) {
         if (m.role !== "toolResult")
             flushImages();
         if (m.role === "user") {
-            const parts = toUserParts(m.content, supportsVision);
+            const parts = toUserParts(m.content, imageWithhold);
             out.push({
                 type: "message",
                 role: "user",
@@ -124,8 +123,8 @@ function toResponsesInput(ctx, model, replayReasoning, 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 });
@@ -157,16 +156,6 @@ function toResponsesTools(ctx, toolNames) {
         strict: false,
     }));
 }
-function resolveWireEffort(model, reasoning) {
-    if (model.reasoning && reasoning === "off")
-        return declaredOffSpelling(model);
-    const compat = responsesCompat(model);
-    if (compat.supportsReasoningEffort === false)
-        return undefined;
-    if (!reasoningRequestCarried(model, reasoning))
-        return undefined;
-    return mintEffortWireValue(reasoning, model, compat.reasoningEffortLevels).wireValue;
-}
 function computeUsage(model, raw) {
     const input = raw?.input_tokens ?? 0;
     const output = raw?.output_tokens ?? 0;
@@ -266,7 +255,6 @@ export function createOpenResponsesBrain(given = {}) {
                         "remove it, or serve this model through the chat-completions lane, which does support it");
                 }
                 const requestedMaxTokens = overrides?.maxOutputTokens ?? options?.maxTokens ?? model.maxTokens;
-                const effort = resolveWireEffort(model, options?.reasoning);
                 const body = {
                     model: model.id,
                     input: toResponsesInput(context, model, config.replayReasoning !== false, builtToolNames),
@@ -290,14 +278,13 @@ export function createOpenResponsesBrain(given = {}) {
                     builtMaxTokens = undefined;
                     builtMaxTokensLane = "unset";
                 }
-                if (effort !== undefined)
-                    body.reasoning = { effort };
+                const { body: reasoningBody, effort } = applyReasoningToRequest({ api: "openai-responses", model, level: options?.reasoning, body });
                 const headers = mergeHeaders(modelHeaders, config.headers, optionsHeaders);
                 applyRouteCredentialHeaders(headers, routeCredential);
                 lockHeader(headers, "content-type", "application/json");
                 if (apiKey)
                     lockHeader(headers, OPEN_RESPONSES_KEY_HEADER, `Bearer ${apiKey}`);
-                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(body, model, RESPONSES_RESERVED);
+                const { body: wire, dropped: extraBodyDropped } = applyExtraBody(reasoningBody, model, RESPONSES_RESERVED);
                 return {
                     url,
                     headers,

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 { 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, 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,13 +317,13 @@ 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);
                 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,

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;