melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/models/capabilities.js

@@ -20,7 +20,7 @@
 import { PROVIDERS } from './providerMap.js';
 import { planTransport } from './gateway.js';
 import { nativeSearchOn, PLATFORMS_FOR, platformFromEnv } from './endpoints.js';
-import { claudeUrlImagesOn } from './claudeModels.js';
+import { claudeGeneration, claudeUrlImagesOn } from './claudeModels.js';
 /** The platform a direct path uses (ADR 0023); a misconfigured one reads as direct here, the doctor reports it. */
 function directPlatform(provider) {
     try {
@@ -117,6 +117,7 @@ export const CAPABILITIES = [
     'delegation',
     'memory_tools',
     'structured_output',
+    'structured_output_with_tools',
     'thinking_with_tools',
     'streaming',
     'vision',
@@ -126,6 +127,7 @@ export const CAPABILITY_LABELS = {
     delegation: 'delegation (subagents as tools)',
     memory_tools: 'memory tools (load_memory)',
     structured_output: 'structured output (outputSchema)',
+    structured_output_with_tools: 'structured output beside tools (an outputSchema on an agent that calls tools or delegates)',
     thinking_with_tools: 'thinking with tool use',
     streaming: 'token streaming',
     vision: 'image input',
@@ -138,12 +140,14 @@ const nativeSearch = (row) => SERVER_SIDE_TOOLS.web_search.includes(row)
     ? ok()
     : unsupported('no native search on this path; the web_search sentinel is dropped (use web_extract)');
 const responsesReasoningNote = (ids) => `encrypted reasoning items are replayed verbatim within the turn's tool loop, with store: false (ADR 0050); ${ids}`;
+const setModelResponseNote = (why) => `the schema travels as a set_model_response tool beside the agent's tools, so the model is asked, not held, to answer in it: the turn ends when it calls the tool, and its arguments are the answer (${why}; ADR 0109)`;
 const CHAT_THINKING_NOTE = "reasoning: is the lever, sent as reasoning_effort in the model's word, a thinking budget as the level that covers it (ADR 0047); the reasoning is not carried between tool steps, so the model re-reasons each step";
 export const CAPABILITY_MATRIX = {
     gemini: {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok(),
+        structured_output_with_tools: degraded(setModelResponseNote('on the Gemini API; Gemini 2 and later on Vertex AI take responseJsonSchema beside the tools in one request')),
         thinking_with_tools: ok(),
         streaming: ok(),
         vision: ok(),
@@ -153,6 +157,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok('test', 'output_config.format (json_schema) from Opus 4.8, Sonnet 5 and Haiku 5.5 on; a forced tool call on Claude 4.6 and earlier and Opus 4.7, offered under tool_choice auto when thinking is on (ADR 0049)'),
+        structured_output_with_tools: ok('test', 'output_config.format beside the tools in one request from Opus 4.8, Sonnet 5 and Haiku 5.5 on; Claude 4.6 and earlier and Opus 4.7 get a set_model_response tool beside them (ADR 0109)'),
         thinking_with_tools: ok('test', "a thinking budget on Claude 4.6 and earlier, adaptive thinking with output_config.effort after (ADR 0049); signed thinking blocks are replayed verbatim within the turn's tool loop (ADR 0046), and where the model binds them to the conversation (Fable 5.1, Opus 5.5, Sonnet 5.5, Haiku 5.5) under drop_block, so a block whose history changed is dropped rather than rejected; with a budget, a step answering another model's tool call runs without thinking"),
         streaming: ok(),
         vision: ok('test', 'user-turn images only'),
@@ -162,6 +167,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok(),
+        structured_output_with_tools: ok('test', 'text.format (strict json_schema) beside the tools in one request (ADR 0109)'),
         thinking_with_tools: ok('test', responsesReasoningNote('reasoning ids only (o-series, gpt-5*)')),
         streaming: ok(),
         vision: ok('test', 'user-turn images only'),
@@ -171,6 +177,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok(),
+        structured_output_with_tools: degraded(setModelResponseNote('the schema is not yet sent beside tools on xAI')),
         thinking_with_tools: ok('test', responsesReasoningNote('grok-4.5, grok-4.6 and grok-4.7; other grok ids re-reason each step')),
         streaming: ok(),
         vision: ok('test', 'user-turn images only'),
@@ -180,6 +187,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok('test', 'strict json_schema; kimi-k2.6 is documented as unstable on complex schemas ($ref, oneOf)'),
+        structured_output_with_tools: degraded(setModelResponseNote('the schema is not yet sent beside tools on Moonshot')),
         thinking_with_tools: ok('test', "reasoning_content is sent back on the turn's tool-loop assistant messages for the same model (ADR 0046) on kimi-k3, kimi-k2.6 and kimi-k2.7-code; earlier turns' reasoning is not, which K3 and K2.7 Code also ask for; effort travels as reasoning_effort (K3) or a thinking switch (K2.x)"),
         streaming: ok(),
         vision: ok('test', 'user-turn images only, sent as base64 (Moonshot takes no public image URLs)'),
@@ -189,6 +197,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok('test', 'json_schema, enforced by grammar-constrained decoding from Ollama 0.5.0 (an older server ignores it); not enforced on Ollama Cloud (ADR 0096)'),
+        structured_output_with_tools: degraded(setModelResponseNote('grammar-constrained decoding to the schema would hold back the tool calls')),
         thinking_with_tools: degraded(CHAT_THINKING_NOTE),
         streaming: ok(),
         vision: ok('test', 'needs a vision model, e.g. ollama/qwen3-vl:8b'),
@@ -198,6 +207,7 @@ export const CAPABILITY_MATRIX = {
         delegation: ok(),
         memory_tools: ok(),
         structured_output: ok('test', 'strict json_schema; upstream support varies by model'),
+        structured_output_with_tools: degraded(setModelResponseNote('upstream support for a schema beside tools varies by model')),
         thinking_with_tools: degraded(CHAT_THINKING_NOTE),
         streaming: ok(),
         vision: ok('test', 'upstream model must accept images'),
@@ -215,6 +225,62 @@ export function capabilityOf(model, capability, opts = {}) {
     }
     return { row, ...CAPABILITY_MATRIX[row][capability] };
 }
+/**
+ * The reasoning levels above `high` (ADR 0117), per row: what `reasoning:
+ * xhigh` and `reasoning: max` reach the provider as. A level a model lacks
+ * goes as its highest setting, and the request's `llm.request` span carries
+ * `llm.reasoning.weakened` with the level asked for. Asserted against the
+ * request bodies in tests/toolChoiceEffort.test.ts; the direct adapters read
+ * lib/models/reasoning.ts effortCeiling.
+ */
+export const REASONING_ABOVE_HIGH = {
+    gemini: 'xhigh and max go as thinkingLevel HIGH (a 16,384-token budget on Gemini 2.x), weakened',
+    anthropic: 'output_config.effort xhigh and max as asked on the adaptive generations (Opus 4.7 and later, Sonnet 5 and later, Haiku 5.5); a 16,384-token budget, weakened, on Claude 4.6 and earlier',
+    openai: 'xhigh as asked on GPT-5.2 and later, and max goes as xhigh there, weakened; high, weakened, on the o-series, GPT-5 and GPT-5.1',
+    xai: 'xhigh as asked on grok-4.7, and max goes as xhigh there, weakened; high, weakened, on grok-4.5 and grok-4.6',
+    moonshot: 'max as asked on kimi-k3, and xhigh rounds up to max; the K2 generation takes a thinking switch, which these leave on',
+    ollama: 'reasoning_effort high, weakened',
+    gateway: 'reasoning_effort high, weakened, whatever the id: the words above high are not accepted across gateways',
+};
+/**
+ * Whether an outputSchema goes in the same request as the agent's tools, as
+ * the provider's own structured-output field, on the path `model` takes
+ * (ADR 0109). True only where the `structured_output_with_tools` cell is
+ * supported and the model's generation takes it: Claude from Opus 4.8,
+ * Sonnet 5 and Haiku 5.5 on (`output_config.format`), every OpenAI id
+ * (`text.format`), Gemini 2 and later on Vertex AI (`responseJsonSchema`).
+ * Elsewhere the native loop declares set_model_response beside the tools
+ * (lib/runtime/native/request.ts), which works on every path. A path that
+ * cannot be planned (a malformed gateway setting) answers false, the form
+ * that works everywhere.
+ */
+export function outputSchemaBesideTools(model, opts = {}) {
+    let cell;
+    try {
+        cell = capabilityOf(model, 'structured_output_with_tools', opts);
+    }
+    catch {
+        return false;
+    }
+    if (cell.support !== 'supported')
+        return false;
+    switch (cell.row) {
+        case 'anthropic':
+            return claudeGeneration(model).structuredOutput === 'output_format';
+        case 'gemini':
+            return geminiMajorVersion(model) >= 2;
+        default:
+            return true;
+    }
+}
+/** A Gemini id's major version (a Vertex AI resource name's last segment), or 0 when it is not a `gemini-<n>` id. Read without a pattern. */
+function geminiMajorVersion(model) {
+    const name = model.slice(model.lastIndexOf('/') + 1);
+    if (!name.startsWith('gemini-'))
+        return 0;
+    const major = Number.parseInt(name.slice('gemini-'.length), 10);
+    return Number.isFinite(major) ? major : 0;
+}
 export function requiredCapabilities(agent) {
     const tools = agent.tools ?? [];
     const needs = new Set();
@@ -224,6 +290,8 @@ export function requiredCapabilities(agent) {
         needs.add('memory_tools');
     if (agent.outputSchema)
         needs.add('structured_output');
+    if (agent.outputSchema && (tools.length > 0 || agent.delegates))
+        needs.add('structured_output_with_tools');
     const thinking = agent.generateContentConfig?.thinkingConfig;
     const thinks = agent.reasoning !== undefined
         ? agent.reasoning !== 'none' && !(typeof agent.reasoning === 'object' && agent.reasoning.budget_tokens === 0)
@@ -256,6 +324,9 @@ export function capabilityGaps(model, agent, opts = {}) {
 export function platformCell(provider, platform, capability) {
     if (platform === 'direct')
         return undefined;
+    if (capability === 'structured_output_with_tools' && provider === 'gemini' && platform === 'vertex') {
+        return ok('test', 'responseJsonSchema beside the tools in one request on Gemini 2 and later; an earlier id gets set_model_response (ADR 0109)');
+    }
     if (capability === 'vision' && provider === 'anthropic' && !claudeUrlImagesOn(platform)) {
         return degraded(`user-turn images inline (base64) only; an image given by URL is dropped, since ${PLATFORM_LABEL[platform]} takes no URL image source`);
     }
@@ -293,6 +364,13 @@ export function renderCapabilityMatrix() {
     lines.push('');
     notes.forEach((n, i) => lines.push(`${i + 1}. ${n}`));
     lines.push('');
+    lines.push('**Reasoning above high** (ADR 0117): what `reasoning: xhigh` and `reasoning: max` reach each path as. "Weakened" means the model\'s highest setting is sent and the span carries `llm.reasoning.weakened`.');
+    lines.push('');
+    lines.push('| Path | xhigh and max |');
+    lines.push('|---|---|');
+    for (const r of rows)
+        lines.push(`| ${label(r)} | ${REASONING_ABOVE_HIGH[r]} |`);
+    lines.push('');
     lines.push('**Cloud platforms** (ADR 0023): the same adapter and request as the provider\'s own API, except as listed. These paths are tested against mocks, not against the live clouds.');
     lines.push('');
     lines.push('| Path | Differs from the provider row |');

package/dist/lib/models/chatCompletionsAdapter.d.ts

@@ -54,7 +54,7 @@
  *     ADR 0053): llm.transport, llm.finish_reason, llm.http_status,
  *     llm.retries, llm.retry_without_thinking, and the search and drop marks.
  */
-import type { ModelAdapter, ModelRequest, ModelResponse, ReasoningSetting, ToolChoiceMode, Usage } from './contract.ts';
+import type { ModelAdapter, ModelRequest, ModelResponse, ReasoningLevel, ReasoningSetting, ToolChoiceMode, Usage } from './contract.ts';
 type ChatContentPart = {
     type: 'text';
     text: string;
@@ -190,10 +190,18 @@ export declare abstract class ChatCompletionsAdapter implements ModelAdapter {
     /**
      * The body fields for the request's reasoning. Default: `reasoning_effort`
      * as the effort word ADR 0047 gives this model (lib/models/reasoning.ts),
-     * the field every chat-completions provider and gateway reads; nothing
-     * when the request sets no reasoning.
+     * the field every chat-completions provider and gateway reads, held at
+     * `reasoningCeiling(model)`; nothing when the request sets no reasoning.
      */
     protected reasoningFields(model: string, setting: ReasoningSetting | undefined): Record<string, unknown>;
+    /**
+     * The highest reasoning level this adapter sends as asked for `model`
+     * (ADR 0117). Default: the direct provider's (lib/models/reasoning.ts
+     * effortCeiling); the gateway holds every id at `high`.
+     */
+    protected reasoningCeiling(model: string): ReasoningLevel;
+    /** The effort word for one setting, held at reasoningCeiling; a held level is marked on the span (`llm.reasoning.weakened`). */
+    protected effortFor(model: string, setting: ReasoningSetting): string;
     /** Provider-specific body fields, merged last. */
     protected extraBodyFields(_request: ModelRequest): Record<string, unknown>;
     /**

package/dist/lib/models/chatCompletionsAdapter.js

@@ -56,7 +56,7 @@
  */
 import { errorDecision, errorText, statusDecision } from './errorResponse.js';
 import { currentTurnStart, providerStateOf } from './providerState.js';
-import { reasoningConfig } from './reasoning.js';
+import { effortCeiling as effortCeilingOf, effortWord } from './reasoning.js';
 import { fetchWithRetry } from './retry.js';
 import { toStrictJsonSchema } from './schemaNormalize.js';
 import { setLlmSpanAttribute } from '../observability/tracer.js';
@@ -327,12 +327,26 @@ export class ChatCompletionsAdapter {
     /**
      * The body fields for the request's reasoning. Default: `reasoning_effort`
      * as the effort word ADR 0047 gives this model (lib/models/reasoning.ts),
-     * the field every chat-completions provider and gateway reads; nothing
-     * when the request sets no reasoning.
+     * the field every chat-completions provider and gateway reads, held at
+     * `reasoningCeiling(model)`; nothing when the request sets no reasoning.
      */
     reasoningFields(model, setting) {
-        const word = setting !== undefined ? reasoningConfig(model, setting).reasoningEffort : undefined;
-        return word !== undefined ? { reasoning_effort: word } : {};
+        return setting !== undefined ? { reasoning_effort: this.effortFor(model, setting) } : {};
+    }
+    /**
+     * The highest reasoning level this adapter sends as asked for `model`
+     * (ADR 0117). Default: the direct provider's (lib/models/reasoning.ts
+     * effortCeiling); the gateway holds every id at `high`.
+     */
+    reasoningCeiling(model) {
+        return effortCeilingOf(model);
+    }
+    /** The effort word for one setting, held at reasoningCeiling; a held level is marked on the span (`llm.reasoning.weakened`). */
+    effortFor(model, setting) {
+        const { word, weakened } = effortWord(model, setting, this.reasoningCeiling(model));
+        if (weakened)
+            setLlmSpanAttribute('llm.reasoning.weakened', weakened);
+        return word;
     }
     /** Provider-specific body fields, merged last. */
     extraBodyFields(_request) {

package/dist/lib/models/claudeAdapter.js

@@ -46,6 +46,7 @@ import { claudeClientSpec, endpointFromEnv, endpointLabel, instantiateClient, na
 import { currentTurnStart, providerStateOf, withProviderState } from './providerState.js';
 import { errorDecision, errorText } from './errorResponse.js';
 import { adaptiveThinkingFor, claudeGeneration, claudeReasoningOf, claudeUrlImagesOn, THINKING_BINDING_BETA } from './claudeModels.js';
+import { isAboveHigh } from './reasoning.js';
 /** The provider id this adapter reports and writes its state under (lib/models/providerMap.ts). */
 export const ANTHROPIC_PROVIDER = 'anthropic';
 /** The providerState kind this adapter writes: the signed blocks that preceded a part. */
@@ -393,6 +394,9 @@ export class ClaudeAdapter {
         else {
             const requestedBudget = reasoning.budget;
             thinkingConfigured = typeof requestedBudget === 'number' && requestedBudget > 0;
+            // The budget generations stop at `high`'s budget (ADR 0117).
+            if (isAboveHigh(request.reasoning))
+                setLlmSpanAttribute('llm.reasoning.weakened', request.reasoning);
             if (thinkingConfigured && continuesUnsignedToolLoop(messages)) {
                 // The tool call this step answers carries no signed thinking (another
                 // provider or model made it, or its state was lost), and Anthropic

package/dist/lib/models/contract.d.ts

@@ -181,9 +181,12 @@ export type ToolChoice = 'auto' | 'none' | 'required' | {
 /**
  * How hard an agent reasons, on any provider (ADR 0047): a level, or a token
  * budget. A budget of 0 is `none`, and `none` means as little reasoning as
- * the model allows.
+ * the model allows. `xhigh` and `max` are the levels above `high` that some
+ * models take (ADR 0117): an adapter whose model stops lower sends its
+ * highest setting and marks the span `llm.reasoning.weakened`; a budget
+ * never reads as either.
  */
-export type ReasoningLevel = 'none' | 'low' | 'medium' | 'high';
+export type ReasoningLevel = 'none' | 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 export type ReasoningSetting = ReasoningLevel | {
     budget_tokens: number;
 };

package/dist/lib/models/gateway.d.ts

@@ -70,7 +70,8 @@ export interface GatewayConfig {
  */
 export declare function gatewayConfig(): GatewayConfig | null;
 /** A human-readable misconfiguration, or undefined when the gateway is
- *  either off or usable. */
+ *  either off or usable. An unrecognised value is named as such and never
+ *  repeated, since it may be a secret pasted into the wrong variable. */
 export declare function gatewayProblem(): string | undefined;
 /** True when a gateway is configured well enough to serve requests. */
 export declare function gatewayUsable(): boolean;

package/dist/lib/models/gateway.js

@@ -81,14 +81,16 @@ export function gatewayConfig() {
     };
 }
 /** A human-readable misconfiguration, or undefined when the gateway is
- *  either off or usable. */
+ *  either off or usable. An unrecognised value is named as such and never
+ *  repeated, since it may be a secret pasted into the wrong variable. */
 export function gatewayProblem() {
     const id = (process.env[GATEWAY_ENV] ?? '').trim();
     if (!id)
         return undefined;
     const cfg = gatewayConfig();
     if (!cfg) {
-        return `${GATEWAY_ENV}=${id} is not a known gateway (expected one of: ${Object.keys(GATEWAYS).join(', ')})`;
+        // The value is never echoed: a key pasted into the wrong variable is still a secret.
+        return `${GATEWAY_ENV} is set to an unrecognised value (not shown); it must be one of: ${Object.keys(GATEWAYS).join(', ')}`;
     }
     if (!cfg.keyPresent)
         return `${GATEWAY_ENV}=${cfg.gateway.id} is set but ${GATEWAY_KEY_ENV} is not`;

package/dist/lib/models/gatewayAdapter.d.ts

@@ -28,7 +28,7 @@
  *   adapter replays no providerState: a chat-completions wire has no place
  *   for Claude's signed blocks or OpenAI's reasoning items.
  */
-import type { ToolChoiceMode } from './contract.ts';
+import type { ReasoningLevel, ToolChoiceMode } from './contract.ts';
 import { ChatCompletionsAdapter } from './chatCompletionsAdapter.ts';
 import type { ChatFailure } from './chatCompletionsAdapter.ts';
 export interface GatewayAdapterOptions {
@@ -44,6 +44,12 @@ export declare class GatewayAdapter extends ChatCompletionsAdapter {
     protected endpointUrl(): string;
     protected headers(): Record<string, string>;
     protected wireModelName(model: string): string;
+    /**
+     * A gateway reads `reasoning_effort` up to `high` whatever the id: the
+     * words above it (`xhigh`, `max`) are not accepted across gateways, so
+     * they go as `high`, marked on the span (ADR 0117).
+     */
+    protected reasoningCeiling(): ReasoningLevel;
     /** A gateway passes tool_choice to the upstream as asked. */
     protected toolChoiceModes(): readonly ToolChoiceMode[];
     protected missingRequirement(): ChatFailure | undefined;

package/dist/lib/models/gatewayAdapter.js

@@ -52,6 +52,14 @@ export class GatewayAdapter extends ChatCompletionsAdapter {
     wireModelName(model) {
         return this.#cfg ? gatewayWireModel(model, this.#cfg.gateway) : model;
     }
+    /**
+     * A gateway reads `reasoning_effort` up to `high` whatever the id: the
+     * words above it (`xhigh`, `max`) are not accepted across gateways, so
+     * they go as `high`, marked on the span (ADR 0117).
+     */
+    reasoningCeiling() {
+        return 'high';
+    }
     /** A gateway passes tool_choice to the upstream as asked. */
     toolChoiceModes() {
         return ['auto', 'none', 'required', 'named'];

package/dist/lib/models/geminiAdapter.js

@@ -50,7 +50,7 @@ import { endpointFromEnv, endpointProblems, platformModel } from './endpoints.js
 import { CARRIED_PARTS_KIND, GEMINI_PROVIDER, GENAI_PART_KIND, MINTED_CALL_ID_PREFIX, PLACEHOLDER_THOUGHT_SIGNATURE, THOUGHT_SIGNATURE_KIND, isCarriedWirePart, } from './geminiState.js';
 import { currentTurnStart, providerStateOf } from './providerState.js';
 import { classifyError, errorStatus, retryUntilFirstYield } from './retry.js';
-import { reasoningConfig } from './reasoning.js';
+import { isAboveHigh, reasoningConfig } from './reasoning.js';
 import { setLlmSpanAttribute } from '../observability/tracer.js';
 /**
  * The provider id this adapter reports and writes its state under, and the
@@ -445,11 +445,17 @@ function toolConfigFor(request) {
                     : undefined;
     return mode ? { functionCallingConfig: { mode } } : undefined;
 }
-/** ADR 0047's mapping for this model, with the thoughts asked for unless the setting is `none`. */
+/**
+ * ADR 0047's mapping for this model, with the thoughts asked for unless the
+ * setting is `none`. Gemini's top is `HIGH` (or `high`'s budget on 2.x), so
+ * `xhigh` and `max` go as that, marked on the span (ADR 0117).
+ */
 function thinkingConfigFor(model, setting) {
     const mapped = reasoningConfig(model, setting).thinkingConfig;
     if (!mapped)
         return undefined;
+    if (isAboveHigh(setting))
+        setLlmSpanAttribute('llm.reasoning.weakened', setting);
     const none = setting === 'none' || (typeof setting === 'object' && setting.budget_tokens <= 0);
     return none ? { ...mapped } : { ...mapped, includeThoughts: true };
 }

package/dist/lib/models/genaiMapping.d.ts

@@ -271,11 +271,15 @@ export interface ModelRequestOptions {
  *     which every adapter maps to what the budget maps to today (0 included).
  *   - else `reasoningEffort`: a level word is that level, and `minimal` is
  *     `none` (ADR 0047's rendering of it on the first GPT-5 generation).
+ * The words above `high` (`xhigh`, `max`) win over a thinkingConfig that
+ * says `high` (`HIGH`, or `high`'s budget of 16,384), which is what the
+ * compiler writes beside them (ADR 0117); a thinkingConfig that says less
+ * keeps its own reading.
  * Lossy, and absent: a budget of -1 (Gemini's dynamic thinking, which is
- * the provider's default), `THINKING_LEVEL_UNSPECIFIED`, the effort words
- * `xhigh` and `max`, and `includeThoughts`. The compiler writes the effort
- * word beside thinkingConfig from one setting, so preferring thinkingConfig
- * loses nothing it wrote; only the older spelling can set the two apart.
+ * the provider's default), `THINKING_LEVEL_UNSPECIFIED`, and
+ * `includeThoughts`. The compiler writes the effort word beside
+ * thinkingConfig from one setting, so preferring thinkingConfig loses
+ * nothing it wrote; only the older spelling can set the two apart.
  */
 export declare function reasoningOf(config: GenerateContentConfig | undefined): ReasoningSetting | undefined;
 /** The function-calling mode as a ToolChoice, and VALIDATED as strict tools. The native request builder reads an agent's config through it too. */

package/dist/lib/models/genaiMapping.js

@@ -152,7 +152,7 @@
 import { FinishReason, FunctionCallingConfigMode } from '@google/genai';
 import { ERROR_RETRYABLE_KEY, ERROR_STATUS_KEY, errorText, withRetryVerdict } from './errorResponse.js';
 import { CARRIED_PARTS_KIND, GEMINI_PROVIDER, GENAI_PART_KIND, MINTED_CALL_ID_PREFIX, THOUGHT_SIGNATURE_KIND } from './geminiState.js';
-import { reasoningConfig } from './reasoning.js';
+import { REASONING_BUDGETS, reasoningConfig } from './reasoning.js';
 import { contractToolDeclaration, nativeToolOf, toContractJsonSchema } from './schemaNormalize.js';
 import { MAX_VALUE_DEPTH, nestedDeeperThan } from '../runtime/valueDepth.js';
 /**
@@ -473,7 +473,15 @@ export function messagesToContents(history) {
 }
 // Maps, not object literals: a config value such as `constructor` must read as nothing.
 const THINKING_LEVELS = new Map([['MINIMAL', 'none'], ['LOW', 'low'], ['MEDIUM', 'medium'], ['HIGH', 'high']]);
-const EFFORT_LEVELS = new Map([['none', 'none'], ['minimal', 'none'], ['low', 'low'], ['medium', 'medium'], ['high', 'high']]);
+const EFFORT_LEVELS = new Map([
+    ['none', 'none'],
+    ['minimal', 'none'],
+    ['low', 'low'],
+    ['medium', 'medium'],
+    ['high', 'high'],
+    ['xhigh', 'xhigh'],
+    ['max', 'max'],
+]);
 /**
  * The ReasoningSetting a generateContentConfig asks for, where one is exact:
  *   - `thinkingConfig.thinkingLevel`: `MINIMAL` is `none` (ADR 0047's
@@ -482,24 +490,30 @@ const EFFORT_LEVELS = new Map([['none', 'none'], ['minimal', 'none'], ['low', 'l
  *     which every adapter maps to what the budget maps to today (0 included).
  *   - else `reasoningEffort`: a level word is that level, and `minimal` is
  *     `none` (ADR 0047's rendering of it on the first GPT-5 generation).
+ * The words above `high` (`xhigh`, `max`) win over a thinkingConfig that
+ * says `high` (`HIGH`, or `high`'s budget of 16,384), which is what the
+ * compiler writes beside them (ADR 0117); a thinkingConfig that says less
+ * keeps its own reading.
  * Lossy, and absent: a budget of -1 (Gemini's dynamic thinking, which is
- * the provider's default), `THINKING_LEVEL_UNSPECIFIED`, the effort words
- * `xhigh` and `max`, and `includeThoughts`. The compiler writes the effort
- * word beside thinkingConfig from one setting, so preferring thinkingConfig
- * loses nothing it wrote; only the older spelling can set the two apart.
+ * the provider's default), `THINKING_LEVEL_UNSPECIFIED`, and
+ * `includeThoughts`. The compiler writes the effort word beside
+ * thinkingConfig from one setting, so preferring thinkingConfig loses
+ * nothing it wrote; only the older spelling can set the two apart.
  */
 export function reasoningOf(config) {
     const cfg = (config ?? {});
+    const word = EFFORT_LEVELS.get(cfg.reasoningEffort);
+    const above = word === 'xhigh' || word === 'max' ? word : undefined;
     const thinking = cfg.thinkingConfig;
     if (isObject(thinking)) {
         const level = THINKING_LEVELS.get(thinking.thinkingLevel);
         if (level)
-            return level;
+            return above && level === 'high' ? above : level;
         const budget = thinking.thinkingBudget;
         if (typeof budget === 'number' && Number.isInteger(budget) && budget >= 0)
-            return { budget_tokens: budget };
+            return above && budget === REASONING_BUDGETS.high ? above : { budget_tokens: budget };
     }
-    return EFFORT_LEVELS.get(cfg.reasoningEffort);
+    return word;
 }
 function nativeToolsOf(llmRequest) {
     const tools = new Set();

package/dist/lib/models/gptAdapter.d.ts

@@ -187,8 +187,10 @@ export declare class GptAdapter implements ModelAdapter {
      * The `reasoning` request field for one setting (ADR 0047), or undefined to
      * send none. OpenAI's reasoning ids ask for summaries, plus the effort in
      * that model's own word (`reasoningConfig`: `none` is `minimal` on the
-     * first GPT-5 generation and `low` on the o-series). Other ids: nothing. A
-     * 400 on the field is retried once without it.
+     * first GPT-5 generation and `low` on the o-series), held at the model's
+     * ceiling (`xhigh` from GPT-5.2, else `high`; ADR 0117), a held level
+     * marked on the span. Other ids: nothing. A 400 on the field is retried
+     * once without it.
      */
     reasoningParam(setting: ReasoningSetting | undefined, model?: string): Record<string, unknown> | undefined;
     /**

package/dist/lib/models/gptAdapter.js

@@ -45,7 +45,7 @@
 import { endpointFromEnv, entraTokenSource, nativeSearchOn, platformModel } from './endpoints.js';
 import { errorDecision, errorText, statusDecision } from './errorResponse.js';
 import { currentTurnStart, providerStateOf } from './providerState.js';
-import { reasoningConfig } from './reasoning.js';
+import { effortWord } from './reasoning.js';
 import { toContractJsonSchema } from './schemaNormalize.js';
 import { setLlmSpanAttribute } from '../observability/tracer.js';
 /** The providerState kind the Responses adapters write: the reasoning output items that preceded a part (ADR 0046, ADR 0050). */
@@ -423,13 +423,20 @@ export class GptAdapter {
      * The `reasoning` request field for one setting (ADR 0047), or undefined to
      * send none. OpenAI's reasoning ids ask for summaries, plus the effort in
      * that model's own word (`reasoningConfig`: `none` is `minimal` on the
-     * first GPT-5 generation and `low` on the o-series). Other ids: nothing. A
-     * 400 on the field is retried once without it.
+     * first GPT-5 generation and `low` on the o-series), held at the model's
+     * ceiling (`xhigh` from GPT-5.2, else `high`; ADR 0117), a held level
+     * marked on the span. Other ids: nothing. A 400 on the field is retried
+     * once without it.
      */
     reasoningParam(setting, model = this.model) {
         if (!isOpenAiReasoningModel(model))
             return undefined;
-        return { summary: 'auto', ...(setting !== undefined ? { effort: reasoningConfig(model, setting).reasoningEffort } : {}) };
+        if (setting === undefined)
+            return { summary: 'auto' };
+        const { word, weakened } = effortWord(model, setting);
+        if (weakened)
+            setLlmSpanAttribute('llm.reasoning.weakened', weakened);
+        return { summary: 'auto', effort: word };
     }
     /**
      * Whether this id carries its reasoning across the steps of a tool loop

package/dist/lib/models/grokAdapter.d.ts

@@ -63,7 +63,9 @@ export declare class GrokAdapter extends GptAdapter {
      * `high`; xAI's own default is `high`, and reasoning cannot be turned off).
      * The request's setting maps through ADR 0047's table, which sends `none`
      * as `low`; with none set, DEFAULT_GROK_REASONING_EFFORT (medium) is pinned,
-     * since effort is part of the price. Other grok ids take no field.
+     * since effort is part of the price. grok-4.7 also takes `xhigh`; `max`,
+     * and `xhigh` on 4.5 and 4.6, go as the model's highest word, marked on the
+     * span (ADR 0117). Other grok ids take no field.
      */
     reasoningParam(setting: ReasoningSetting | undefined, model?: string): Record<string, unknown> | undefined;
     /**

package/dist/lib/models/grokAdapter.js

@@ -26,8 +26,9 @@
  */
 import { DEFAULT_GROK_REASONING_EFFORT } from '../config.js';
 import { GptAdapter } from './gptAdapter.js';
-import { reasoningConfig } from './reasoning.js';
+import { effortWord } from './reasoning.js';
 import { collectionIdsFromEnv, collectionsMaxResultsFromEnv, xaiWebSearchParamsFromEnv, xSearchParamsFromEnv, } from '../tools/xaiSearchParams.js';
+import { setLlmSpanAttribute } from '../observability/tracer.js';
 export const XAI_BASE_URL = 'https://api.x.ai/v1';
 /**
  * The ids that take a reasoning effort and return encrypted reasoning:
@@ -81,12 +82,19 @@ export class GrokAdapter extends GptAdapter {
      * `high`; xAI's own default is `high`, and reasoning cannot be turned off).
      * The request's setting maps through ADR 0047's table, which sends `none`
      * as `low`; with none set, DEFAULT_GROK_REASONING_EFFORT (medium) is pinned,
-     * since effort is part of the price. Other grok ids take no field.
+     * since effort is part of the price. grok-4.7 also takes `xhigh`; `max`,
+     * and `xhigh` on 4.5 and 4.6, go as the model's highest word, marked on the
+     * span (ADR 0117). Other grok ids take no field.
      */
     reasoningParam(setting, model = this.model) {
         if (!GROK_REASONING_IDS.test(model))
             return undefined;
-        return { effort: setting === undefined ? DEFAULT_GROK_REASONING_EFFORT : reasoningConfig(model, setting).reasoningEffort };
+        if (setting === undefined)
+            return { effort: DEFAULT_GROK_REASONING_EFFORT };
+        const { word, weakened } = effortWord(model, setting);
+        if (weakened)
+            setLlmSpanAttribute('llm.reasoning.weakened', weakened);
+        return { effort: word };
     }
     /**
      * grok-4.5, grok-4.6 and grok-4.7 carry their reasoning across a tool loop

package/dist/lib/models/kimiAdapter.d.ts

@@ -68,7 +68,8 @@
  *   goes as its Kimi word (`medium` → `high`, a budget → the level that
  *   covers it), `none` as `low` since K3 cannot switch thinking off, and a
  *   request with none pins DEFAULT_KIMI_REASONING_EFFORT (lib/config.ts).
- *   `max` has no contract level, so no request sends it.
+ *   `reasoning: max` sends `max`, and `xhigh` rounds up to it (ADR 0117):
+ *   Moonshot's costliest effort, and its default, which the pin avoids.
  *   K2.x models take no reasoning_effort: a `thinking: { type }` switch
  *   instead, so `none` (or a budget of 0) sends `disabled` and any other
  *   setting sends nothing. K2.7 Code (and its highspeed variant) cannot

package/dist/lib/models/kimiAdapter.js

@@ -68,7 +68,8 @@
  *   goes as its Kimi word (`medium` → `high`, a budget → the level that
  *   covers it), `none` as `low` since K3 cannot switch thinking off, and a
  *   request with none pins DEFAULT_KIMI_REASONING_EFFORT (lib/config.ts).
- *   `max` has no contract level, so no request sends it.
+ *   `reasoning: max` sends `max`, and `xhigh` rounds up to it (ADR 0117):
+ *   Moonshot's costliest effort, and its default, which the pin avoids.
  *   K2.x models take no reasoning_effort: a `thinking: { type }` switch
  *   instead, so `none` (or a budget of 0) sends `disabled` and any other
  *   setting sends nothing. K2.7 Code (and its highspeed variant) cannot
@@ -118,7 +119,6 @@
  */
 import { DEFAULT_KIMI_REASONING_EFFORT } from '../config.js';
 import { ChatCompletionsAdapter, reasonsNotAtAll } from './chatCompletionsAdapter.js';
-import { reasoningConfig } from './reasoning.js';
 import { trimTrailingSlashes } from './urls.js';
 export const MOONSHOT_BASE_URL = 'https://api.moonshot.ai/v1';
 /** The flagship takes `reasoning_effort`; the K2 generation takes a `thinking` switch. */
@@ -191,7 +191,7 @@ export class KimiAdapter extends ChatCompletionsAdapter {
         if (isKimiK3(model)) {
             if (setting === undefined)
                 return { reasoning_effort: DEFAULT_KIMI_REASONING_EFFORT };
-            const word = reasoningConfig(model, setting).reasoningEffort;
+            const word = this.effortFor(model, setting);
             return { reasoning_effort: word === 'none' ? 'low' : word }; // K3 cannot switch thinking off
         }
         // K2.7 Code always thinks, and Moonshot refuses `disabled` for it.