melchizedek-agents 1.1.0 → 1.2.0

package/dist/lib/models/capabilities.js

@@ -225,6 +225,23 @@ 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
@@ -347,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.

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

@@ -12,15 +12,43 @@ import type { ReasoningLevel, ReasoningSetting } from './contract.ts';
 /**
  * Thinking tokens per level, for the providers that take a budget (Claude,
  * Gemini 2.x). The same table rounds a `budget_tokens` value up to a level
- * for the providers that take only a level or an effort word.
+ * for the providers that take only a level or an effort word. `xhigh` and
+ * `max` take `high`'s budget (ADR 0117): above it a non-streaming Claude
+ * request passes the Anthropic SDK's ceiling (ADR 0047), so a budget path
+ * sends them as `high`, and a budget never rounds up to either.
  */
 export declare const REASONING_BUDGETS: Readonly<Record<ReasoningLevel, number>>;
+/** The levels in order of how hard they ask the model to think. */
+export declare const REASONING_ORDER: readonly ReasoningLevel[];
+/** The levels above `high`, which only some models take (ADR 0117). */
+export declare const isAboveHigh: (setting: ReasoningSetting | undefined) => setting is 'xhigh' | 'max';
+/**
+ * The highest level the direct adapter for `model` sends as asked (ADR
+ * 0117); a level above it goes as this one. `max` where every level
+ * passes: Claude's adaptive generations (the Claude adapter sends its budget
+ * generations `high`'s budget) and Kimi K3. OpenAI's GPT-5.2 and later and
+ * grok-4.7 stop at `xhigh`; other OpenAI and Grok ids, Gemini and Ollama at
+ * `high`. A gateway stops at `high` whatever the id (gatewayAdapter.ts).
+ */
+export declare function effortCeiling(model: string): ReasoningLevel;
+/**
+ * The effort word an adapter sends for one setting: ADR 0047's word for the
+ * model, held at `ceiling` (default effortCeiling(model)). `weakened` is the
+ * level asked for when the word sent is below it; the adapter marks the span
+ * `llm.reasoning.weakened` with it.
+ */
+export declare function effortWord(model: string, setting: ReasoningSetting, ceiling?: ReasoningLevel): {
+    word: string;
+    weakened?: ReasoningLevel;
+};
 /**
  * The generateContentConfig fields a `reasoning:` setting becomes for one
  * model (ADR 0047). `reasoningEffort` is always set, so the gateway (which
  * may serve any id) carries the level too; the Claude adapter reads it first
  * on the adaptive generations (ADR 0049), and the genai SDK drops it from a
  * Gemini request. Claude and Gemini also get the `thinkingConfig` their
- * adapters read.
+ * adapters read. `xhigh` and `max` are written as asked (Kimi's `xhigh` as
+ * `max`), beside `high`'s thinkingConfig: the adapter holds the word at its
+ * model's ceiling (effortWord), so the setting reaches it intact (ADR 0117).
  */
 export declare function reasoningConfig(model: string, setting: ReasoningSetting): Record<string, unknown>;

package/dist/lib/models/reasoning.js

@@ -2,10 +2,25 @@ import { providerForModel } from './providerMap.js';
 /**
  * Thinking tokens per level, for the providers that take a budget (Claude,
  * Gemini 2.x). The same table rounds a `budget_tokens` value up to a level
- * for the providers that take only a level or an effort word.
+ * for the providers that take only a level or an effort word. `xhigh` and
+ * `max` take `high`'s budget (ADR 0117): above it a non-streaming Claude
+ * request passes the Anthropic SDK's ceiling (ADR 0047), so a budget path
+ * sends them as `high`, and a budget never rounds up to either.
  */
-export const REASONING_BUDGETS = { none: 0, low: 2048, medium: 8192, high: 16384 };
-const GEMINI_THINKING_LEVEL = { none: 'MINIMAL', low: 'LOW', medium: 'MEDIUM', high: 'HIGH' };
+export const REASONING_BUDGETS = { none: 0, low: 2048, medium: 8192, high: 16384, xhigh: 16384, max: 16384 };
+const GEMINI_THINKING_LEVEL = { none: 'MINIMAL', low: 'LOW', medium: 'MEDIUM', high: 'HIGH', xhigh: 'HIGH', max: 'HIGH' };
+/** The levels in order of how hard they ask the model to think. */
+export const REASONING_ORDER = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
+/** The levels above `high`, which only some models take (ADR 0117). */
+export const isAboveHigh = (setting) => setting === 'xhigh' || setting === 'max';
+/** An OpenAI id that takes `xhigh`: GPT-5.2 and later (the o-series and GPT-5 and 5.1 stop at `high`). */
+function openAiTakesXhigh(model) {
+    const m = /^gpt-(\d{1,3})(?:\.(\d{1,3}))?/.exec(model);
+    if (!m)
+        return false;
+    const major = Number(m[1]);
+    return major > 5 || (major === 5 && Number(m[2] ?? 0) >= 2);
+}
 /** The smallest level whose budget covers the setting: never less thought than asked. */
 function reasoningLevel(setting) {
     if (typeof setting === 'string')
@@ -29,18 +44,54 @@ function reasoningEffort(model, level) {
         case 'xai':
             return level === 'none' ? 'low' : level; // Grok 4.5/4.7 cannot stop reasoning
         case 'moonshot':
-            return level === 'medium' ? 'high' : level; // K3 has low | high | max
+            // K3 has low | high | max: a missing word rounds up.
+            return level === 'medium' ? 'high' : level === 'xhigh' ? 'max' : level;
         default:
             return level;
     }
 }
+/**
+ * The highest level the direct adapter for `model` sends as asked (ADR
+ * 0117); a level above it goes as this one. `max` where every level
+ * passes: Claude's adaptive generations (the Claude adapter sends its budget
+ * generations `high`'s budget) and Kimi K3. OpenAI's GPT-5.2 and later and
+ * grok-4.7 stop at `xhigh`; other OpenAI and Grok ids, Gemini and Ollama at
+ * `high`. A gateway stops at `high` whatever the id (gatewayAdapter.ts).
+ */
+export function effortCeiling(model) {
+    switch (providerForModel(model)) {
+        case 'anthropic':
+        case 'moonshot':
+            return 'max';
+        case 'openai':
+            return openAiTakesXhigh(model) ? 'xhigh' : 'high';
+        case 'xai':
+            return /^grok-4\.7(?!\d)/.test(model) ? 'xhigh' : 'high';
+        default:
+            return 'high';
+    }
+}
+/**
+ * The effort word an adapter sends for one setting: ADR 0047's word for the
+ * model, held at `ceiling` (default effortCeiling(model)). `weakened` is the
+ * level asked for when the word sent is below it; the adapter marks the span
+ * `llm.reasoning.weakened` with it.
+ */
+export function effortWord(model, setting, ceiling = effortCeiling(model)) {
+    const word = reasoningConfig(model, setting).reasoningEffort;
+    if (!isAboveHigh(setting) || REASONING_ORDER.indexOf(word) <= REASONING_ORDER.indexOf(ceiling))
+        return { word };
+    return { word: ceiling, weakened: setting };
+}
 /**
  * The generateContentConfig fields a `reasoning:` setting becomes for one
  * model (ADR 0047). `reasoningEffort` is always set, so the gateway (which
  * may serve any id) carries the level too; the Claude adapter reads it first
  * on the adaptive generations (ADR 0049), and the genai SDK drops it from a
  * Gemini request. Claude and Gemini also get the `thinkingConfig` their
- * adapters read.
+ * adapters read. `xhigh` and `max` are written as asked (Kimi's `xhigh` as
+ * `max`), beside `high`'s thinkingConfig: the adapter holds the word at its
+ * model's ceiling (effortWord), so the setting reaches it intact (ADR 0117).
  */
 export function reasoningConfig(model, setting) {
     const level = reasoningLevel(setting);