Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

51.7 KB
Raw Blame
/**
 * Base class for API format implementations (Layer 1) and model dialect
 * implementations (Layer 2).
 *
 * Different models have different quirks that need translation:
 * - Grok: XML function calls instead of JSON tool_calls
 * - Deepseek: May have its own format
 * - Others: Future model-specific behaviors
 */

import type { ModelPricing } from "../handlers/shared/remote-provider-types.js";
import { getModelPricing } from "../handlers/shared/remote-provider-types.js";
import { log } from "../logger.js";
import type { StreamFormat } from "../providers/transport/types.js";
import type { APIFormat } from "./api-format.js";
import {
  type ReasoningCapability,
  lookupModel,
  lookupModelReasoning,
  lookupModelReasoningStatus,
} from "./model-catalog.js";
import type { ModelDialect } from "./model-dialect.js";
import { rejectedOptionalParams } from "./optional-param-rejection.js";
import {
  type ToolNameBindings,
  encodeToolName,
  newToolNameBindings,
  wireDecodesToolNames,
} from "./tool-name-utils.js";

/**
 * The OPTIONAL parameters {@link BaseAPIFormat.applyOpenAISamplingParams} adds
 * speculatively, and therefore the only ones
 * {@link BaseAPIFormat.recoverFromRejection} will remove. Anything else in the
 * payload is either required or owned by a dialect that must recover it itself.
 */
const OPTIONAL_SAMPLING_PARAMS: readonly string[] = ["stop", "top_p"];

/**
 * OpenAI validates a function name against `^[a-zA-Z0-9_-]{1,64}$` on both the
 * Chat Completions and the Responses shape. 64 is that limit, not a guess about
 * any one model.
 */
const OPENAI_TOOL_NAME_LIMIT = 64;

/**
 * Match a model ID against a model family name, handling vendor-prefixed IDs.
 *
 * Matches: "grok-beta", "x-ai/grok-beta", "openrouter/x-ai/grok-beta"
 * Does NOT match: "qwen-grok-hybrid" (grok is not at a family boundary)
 *
 * @param modelId - The full model ID (may include vendor prefix)
 * @param family - The family name to match (e.g., "grok", "deepseek", "qwen")
 */
export function matchesModelFamily(modelId: string, family: string): boolean {
  const lower = modelId.toLowerCase();
  const fam = family.toLowerCase();
  return lower.startsWith(fam) || lower.includes(`/${fam}`);
}
import { convertMessagesToOpenAI } from "../handlers/shared/format/openai-messages.js";
import {
  convertToolsToOpenAI,
  mapToolChoiceToOpenAI,
} from "../handlers/shared/format/openai-tools.js";

export interface ToolCall {
  id: string;
  name: string;
  arguments: Record<string, any>;
}

/**
 * Canonical reasoning-effort levels emitted by Claude Code via
 * `output_config.effort`. Every dialect maps these onto its provider's native
 * reasoning knob (or strips, when the provider has none).
 */
export type EffortLevel = "none" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";

/** The seven canonical levels, ascending — also the membership set for validation. */
const EFFORT_ORDER: EffortLevel[] = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];

/**
 * The canonical levels in ascending order. Exported so dialects can CLAMP a
 * requested level into whatever subset a model actually advertises (the slim
 * catalog's `reasoning.efforts`) instead of sending a level the model has no
 * mode for.
 */
export const EFFORT_LEVELS: readonly EffortLevel[] = EFFORT_ORDER;

/** Narrow an arbitrary catalog/config string to a canonical {@link EffortLevel}. */
export function isEffortLevel(value: unknown): value is EffortLevel {
  return typeof value === "string" && EFFORT_ORDER.includes(value as EffortLevel);
}

/**
 * Reasoning knobs that belong to an OpenAI-shaped wire and must never ride an
 * Anthropic Messages request.
 *
 * Two of them (`enable_thinking`, `thinking_budget`) are DashScope's; the third
 * (`reasoning_effort`) is OpenAI's and is also accepted by DeepSeek's and xAI's
 * own APIs. Measured against Alibaba Token Plan's Anthropic endpoint on 2026-08-02:
 * a top-level `reasoning_effort` of `"max"` AND of `"banana"` both return 200,
 * i.e. the field is silently ignored — a dialect emitting it there believes it
 * set the depth and did nothing.
 */
const NON_ANTHROPIC_REASONING_FIELDS = [
  "reasoning_effort",
  "enable_thinking",
  "thinking_budget",
] as const;

/**
 * Smallest reasoning budget a provider will accept.
 *
 * Anthropic's Messages API documents `budget_tokens >= 1024`, and the
 * Anthropic-compatible endpoints claudish speaks to inherit it. Below this a
 * budget is not "small", it is invalid, so the correct move is to stop
 * expressing depth as a budget rather than to send a smaller number.
 */
export const MIN_THINKING_BUDGET = 1024;

/**
 * Output tokens reserved for the answer itself when a budget is clamped.
 *
 * A budget equal to the ceiling is rejected outright (`max_completion_tokens
 * [32000] must be greater than thinking_budget [38912]` is the same rule seen
 * from the other side), and a budget one token under it leaves a model that has
 * thought and cannot speak. Reserving a real slice keeps a clamped request
 * useful rather than merely legal.
 */
export const ANSWER_TOKEN_RESERVE = 1024;

/**
 * The output ceiling a reasoning budget must fit under.
 *
 * Read from the ORIGINAL Claude-format request first, because `max_tokens` is
 * the field every wire derives its own ceiling from and the only one guaranteed
 * to be present before the payload is built. The payload is consulted second,
 * under all three names the wires use, so a dialect that runs after its
 * converter still sees the number actually being sent.
 *
 * Deliberately NOT the catalog's `maxOutputTokens`: the provider validates the
 * budget against the ceiling in the request, so that is the number that decides
 * whether the pair is legal.
 */
export function outputCeilingOf(originalRequest: any, payload?: any): number | undefined {
  const candidates = [
    originalRequest?.max_tokens,
    payload?.max_tokens,
    payload?.max_completion_tokens,
    payload?.max_output_tokens,
  ];
  for (const value of candidates) {
    if (typeof value === "number" && Number.isFinite(value) && value > 0) return value;
  }
  return undefined;
}

/**
 * Fit a reasoning budget under an output ceiling.
 *
 * Returns:
 * - the budget unchanged when it already fits,
 * - a smaller budget when the ceiling requires one,
 * - `undefined` when there is no budget to send in the first place (effort
 *   `max` omits it so the model uses its own maximum), or when no ceiling is
 *   known and the caller's number therefore stands,
 * - `"no-room"` when the ceiling cannot hold a legal budget AND leave room to
 *   answer. That is a distinct outcome from "no budget": the caller must stop
 *   expressing depth as a budget, not send the request without one.
 */
export function clampThinkingBudget(
  budget: number | undefined,
  ceiling: number | undefined
): number | undefined | "no-room" {
  if (budget === undefined) return undefined;
  if (ceiling === undefined) return budget;

  const allowed = ceiling - ANSWER_TOKEN_RESERVE;
  if (allowed < MIN_THINKING_BUDGET) return "no-room";
  return Math.min(budget, allowed);
}

export interface AdapterResult {
  /** Cleaned text content (with XML/special formats removed) */
  cleanedText: string;
  /** Extracted tool calls from special formats */
  extractedToolCalls: ToolCall[];
  /** Whether any transformation was done */
  wasTransformed: boolean;
}

export abstract class BaseAPIFormat implements APIFormat, ModelDialect {
  protected modelId: string;

  /**
   * The WIRE FORMAT this instance is composed with — i.e. the shape of the
   * payload a Layer 2 dialect is being handed, which is decided by the Layer 1
   * FormatConverter, not by the model's name.
   *
   * A dialect is auto-selected by model name (see DialectManager), so on its
   * own it cannot tell whether the same model is being reached over the
   * OpenAI/Chat-Completions wire or the Anthropic Messages wire. Providers do
   * exist that serve one model family over both (Qwen: DashScope
   * OpenAI-compatible vs. Alibaba Token Plan's /apps/anthropic/v1/messages), and their
   * reasoning knobs are named differently on each.
   *
   * DIALECTS SHOULD NOT READ THIS. It is consumed by {@link prepareRequest}'s
   * template and by {@link shouldFilterThinking}, which is what makes the
   * Anthropic-wire behaviour automatic for every dialect — including ones
   * written before the endpoint existed. A dialect that branches on it is
   * re-creating the bug this replaced (see the qwen-token-plan session log).
   *
   * `undefined` means "not composed / caller didn't say" — treat it as the
   * historical OpenAI default so nothing changes for existing call sites.
   */
  protected readonly wireFormat?: StreamFormat;

  /**
   * The parser the RESPONSE will actually be fed to, as ComposedHandler
   * resolves it — `provider.overrideStreamFormat()` first, then the adapters.
   *
   * Distinct from {@link wireFormat}, which is the REQUEST shape. They are
   * usually the same and are not always: a custom endpoint may declare
   * `{transport:"openai", streamFormat:"anthropic-sse"}`, and then the payload
   * is OpenAI-shaped (so the encoder arms) while the parser is the Anthropic
   * passthrough (which has no decode map). Only {@link getToolNameLimit} reads
   * this; nothing else should branch on it.
   *
   * Set ONCE, from the ComposedHandler constructor. It is a property of the
   * composition, not of the request — `resolveStreamFormat()` does not look at
   * the request at all — so this carries none of the per-request race that made
   * {@link toolNameBindings} per-request.
   */
  private responseWireFormat?: StreamFormat;

  /**
   * Tell this adapter which parser will read the response it is helping build.
   *
   * Called once per handler, at construction. A delegating adapter that runs an
   * inner adapter's `prepareRequest` MUST override this and pass it on, or the
   * inner adapter encodes names into a wire that cannot decode them
   * (OpenRouterAPIFormat and LocalAdapter both do).
   */
  setResponseWireFormat(format: StreamFormat | undefined): void {
    this.responseWireFormat = format;
  }

  /**
   * This request's tool-name bindings, in both directions.
   *
   * PER REQUEST, and REPLACED rather than cleared — never mutated after it has
   * been handed out. Handlers are cached one per model while `claudish serve`
   * hosts several conversations, so the instance is shared: clearing the map
   * that request A's parser is still decoding with, because request B started,
   * turns A's tool calls into names nothing recognises — and `keepOnlyRealTools`
   * then drops them with no error anywhere. `adapters.md` records the same
   * hazard class for `getHeaders`. `reset()` mints a new pair; the old one stays
   * whole for whoever is still reading it.
   */
  protected toolNameBindings: ToolNameBindings = newToolNameBindings();

  constructor(modelId: string, wireFormat?: StreamFormat) {
    this.modelId = modelId;
    this.wireFormat = wireFormat;
  }

  /** The model ID this format/dialect was constructed for. */
  getModelId(): string {
    return this.modelId;
  }

  /** The composed wire format, or undefined when none was supplied. */
  getWireFormat(): StreamFormat | undefined {
    return this.wireFormat;
  }

  /**
   * Process text content and extract any model-specific tool call formats
   * @param textContent - The raw text content from the model
   * @param accumulatedText - The accumulated text so far (for multi-chunk parsing)
   * @returns Cleaned text and any extracted tool calls
   */
  abstract processTextContent(textContent: string, accumulatedText: string): AdapterResult;

  /**
   * Check if this format/dialect should be used for the given model
   */
  abstract shouldHandle(modelId: string): boolean;

  /**
   * Get name for logging
   */
  abstract getName(): string;

  /**
   * Repair a request that a provider rejected because of an OPTIONAL parameter
   * this format/dialect added speculatively. See `ModelDialect` for the full
   * rationale; ComposedHandler calls it at most once per request.
   *
   * The base implementation covers the sampling controls
   * {@link applyOpenAISamplingParams} forwards. A dialect that overrides this
   * for its own parameter MUST end by delegating to `super`, or it silently
   * removes that cover for its own models (GrokModelDialect does).
   */
  recoverFromRejection(payload: any, errorText: string): { payload: any; note: string } | null {
    return this.recoverFromSamplingParamRejection(payload, errorText);
  }

  /**
   * Drop whichever of {@link OPTIONAL_SAMPLING_PARAMS} this 4xx named, or
   * return null when it named none.
   *
   * Narrow on purpose: a missed recovery is a visible failed request, while a
   * wrong one silently strips a parameter the model did accept.
   */
  protected recoverFromSamplingParamRejection(
    payload: any,
    errorText: string
  ): { payload: any; note: string } | null {
    if (!payload) return null;
    const present = OPTIONAL_SAMPLING_PARAMS.filter((p) => payload[p] !== undefined);
    if (present.length === 0) return null;

    const rejected = rejectedOptionalParams(errorText, present);
    if (rejected.length === 0) return null;

    const next = { ...payload };
    for (const p of rejected) delete next[p];
    return { payload: next, note: `dropped ${rejected.join(", ")} for ${this.modelId}` };
  }

  /**
   * Forward the two sampling controls Claude Code sends that every
   * OpenAI-shaped builder in this tree used to drop: `stop_sequences` → `stop`,
   * and `top_p`.
   *
   * `stop` matters more than it looks. Claude Code's own classifier requests
   * carry stop sequences, and a relay that never receives them keeps generating
   * past the point the caller said to stop — which reads as a slow, rambling
   * model rather than as a dropped parameter. `anthropic-api-format.ts` already
   * forwards `stop_sequences` on the Anthropic wire, so this closes the
   * OpenAI-shaped half only.
   *
   * Both are OPTIONAL parameters sent speculatively:
   * {@link recoverFromRejection} drops whichever one a strict relay rejects and
   * the request is retried once.
   *
   * No cap is applied to the sequence count. OpenAI documents a limit of four,
   * but capping here would silently discard the fifth sequence — the failure
   * mode this repo keeps paying for — whereas sending all of them fails loudly
   * and recovers.
   *
   * @param payload - the provider payload being built (mutated in place)
   * @param claudeRequest - the inbound Anthropic-shaped request
   */
  protected applyOpenAISamplingParams(payload: any, claudeRequest: any): void {
    if (!payload || !claudeRequest) return;

    const sequences = claudeRequest.stop_sequences;
    if (Array.isArray(sequences)) {
      // An empty string is not a stop sequence anywhere, and strict relays 400
      // on one. Dropping the empty entries keeps the real ones.
      const usable = sequences.filter((s: unknown) => typeof s === "string" && s.length > 0);
      if (usable.length > 0) payload.stop = usable;
    }

    if (claudeRequest.top_p !== undefined && claudeRequest.top_p !== null) {
      payload.top_p = claudeRequest.top_p;
    }
  }

  /**
   * Maximum tool name length this request's wire accepts, or null for no limit.
   *
   * THE QUESTION IS "CAN THE RESPONSE BE DECODED", NOT "IS THE REQUEST
   * OpenAI-SHAPED". Those come apart, and when they do the encoder runs with no
   * decoder behind it and Claude Code receives a tool name it never advertised.
   * `wireDecodesToolNames` is the one list of parsers that are handed this
   * request's map; a wire absent from it gets null and nothing is encoded. The
   * cost of not encoding is a loud 400 on a >64-char name; the cost of encoding
   * without a decoder is a silently dropped tool call.
   *
   * OpenAI validates a function name against `^[a-zA-Z0-9_-]{1,64}$` on both of
   * its shapes, so 64 is that limit and not a guess about any one model. Before
   * item 7 this method returned null on every adapter except Xiaomi, so nothing
   * truncated at all — and a real 65-character MCP name
   * (`mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent`) failed
   * the WHOLE request, not just that tool.
   */
  getToolNameLimit(): number | null {
    // Precedence mirrors ComposedHandler.resolveStreamFormat(), which is what
    // actually picks the parser: the provider's RESPONSE override first, then
    // the composed request wire, then the dialect's own guess. A dialect
    // self-selects by model name and its `getStreamFormat()` answers
    // "openai-sse" whatever it was composed into, so it is the last word, never
    // the first.
    const wire = this.responseWireFormat ?? this.wireFormat ?? this.getStreamFormat();
    return wireDecodesToolNames(wire) ? OPENAI_TOOL_NAME_LIMIT : null;
  }

  /**
   * Maximum number of tools this API accepts in a single request. Returns null
   * if no limit (default). OpenAI's Chat Completions API hard-caps the `tools`
   * array at 128 — exceeding it fails the whole request with HTTP 400
   * "Invalid 'tools': array too long". The ComposedHandler head-slices the
   * converted tools to this count so a session with many MCP tools still works
   * (Claude Code's built-in tools come first and are preserved).
   */
  getMaxToolCount(): number | null {
    return null;
  }

  /**
   * This request's decode map (encoded → original).
   *
   * Read it ONCE, immediately after `prepareRequest`, and thread that reference
   * onward — do not re-read it after an `await`. `reset()` replaces the
   * bindings, so a later read on a shared handler returns the NEXT request's
   * map.
   */
  getToolNameMap(): Map<string, string> {
    return this.toolNameBindings.byEncoded;
  }

  /**
   * Restore a possibly-encoded tool name to its original.
   */
  restoreToolName(name: string): string {
    return this.toolNameBindings.byEncoded.get(name) || name;
  }

  /**
   * Handle any request preparation before sending to the model.
   *
   * TEMPLATE METHOD — do NOT override this in a dialect or format. Override
   * {@link prepareRequestCommon} (wire-agnostic work: tool-name truncation,
   * temperature clamping, …) and/or {@link applyNativeReasoning} (the reasoning
   * knob of the model's OWN provider API) instead.
   *
   * The split exists because WHICH reasoning knob a request must carry is a
   * property of the WIRE, not of the model family — and dialects are selected
   * by model NAME (see DialectManager), so a dialect cannot know the wire.
   * Alibaba's Alibaba Token Plan is the worked example: one Anthropic-compatible
   * endpoint serving qwen3.x AND glm-5.2 AND deepseek-v4-*, i.e. three
   * different dialects reaching the SAME wire. Before this hoist only
   * QwenModelDialect had been taught the wire, so glm/deepseek on that endpoint
   * emitted their own APIs' knobs — which that endpoint silently ignores — and
   * leaked their reasoning into the chat as prose.
   *
   * On the Anthropic wire the base therefore has the LAST WORD: the dialect's
   * native reasoning emission is skipped, OpenAI-shaped knobs are stripped even
   * if some other hook set them, and {@link applyAnthropicWireReasoning}
   * (catalog-driven) supplies the knob. Every other wire is byte-identical to
   * the pre-hoist behaviour.
   *
   * @param request - The provider payload being prepared
   * @param originalRequest - The original Claude-format request
   * @returns The modified request payload
   */
  prepareRequest(request: any, originalRequest: any): any {
    const prepared = this.prepareRequestCommon(request, originalRequest) ?? request;

    // Tool-name encoding lives in the TEMPLATE, not in the hook, so that every
    // adapter gets it exactly once and no subclass can lose it by overriding
    // `prepareRequestCommon` without calling super — which is how it came to be
    // on OpenAIAPIFormat and Xiaomi alone. One call site for the whole tree.
    this.encodeToolNames(prepared);

    if (!this.isAnthropicWire()) {
      return this.applyNativeReasoning(prepared, originalRequest) ?? prepared;
    }

    this.stripNonAnthropicReasoningFields(prepared);
    return this.applyAnthropicWireReasoning(prepared, originalRequest) ?? prepared;
  }

  /**
   * Wire-agnostic request preparation — runs on EVERY wire.
   *
   * This is where non-reasoning quirks belong: tool-name truncation, tool-count
   * caps, temperature clamping, delegation to an inner adapter. Anything that
   * emits a reasoning knob belongs in {@link applyNativeReasoning} instead, so
   * the Anthropic wire can substitute its own.
   */
  protected prepareRequestCommon(request: any, _originalRequest: any): any {
    return request;
  }

  /**
   * The reasoning knob of the model's OWN provider API (DashScope's
   * `enable_thinking`, OpenAI/xAI/DeepSeek's `reasoning_effort`, GLM's
   * `thinking` toggle, …). Runs on every wire EXCEPT `anthropic-sse`.
   *
   * Override this in a dialect. Do not branch on the wire inside it — that is
   * precisely the coupling this split removes.
   */
  protected applyNativeReasoning(request: any, _originalRequest: any): any {
    return request;
  }

  /** True when this instance was composed with the Anthropic Messages wire. */
  protected isAnthropicWire(): boolean {
    return this.wireFormat === "anthropic-sse";
  }

  /**
   * Remove reasoning knobs that only exist on OpenAI-shaped wires.
   *
   * Belt-and-braces: with the hook split nothing should set them here, but a
   * dialect that puts its reasoning emission in the wrong hook (or an inner
   * adapter reached through delegation) would otherwise ship a field the
   * Anthropic endpoint ignores while believing depth was set.
   */
  protected stripNonAnthropicReasoningFields(request: any): void {
    if (!request) return;
    for (const field of NON_ANTHROPIC_REASONING_FIELDS) {
      if (request[field] !== undefined) delete request[field];
    }
  }

  /**
   * Reasoning knob for the Anthropic Messages wire — the SINGLE place to tune
   * it, for every dialect.
   *
   * The SHAPE of the knob is a PER-MODEL fact read from the slim catalog's
   * `reasoning` record, never from a table here. The Alibaba Token Plan's membership is
   * why a fixed ladder is wrong: `qwen3.7-plus` is `control: "toggle"` (it
   * exposes no depth parameter at all, so a `budget_tokens` would be an
   * invented field), while `glm-5.2` and `deepseek-v4-pro` on the SAME endpoint
   * are `control: "effort"` with their own restricted level sets
   * (`["xhigh","high"]`, `["max","high"]`) that do not contain every claudish
   * level.
   *
   * `output_config.effort` is the field Claude Code itself sends to an
   * Anthropic Messages endpoint and which AnthropicAPIFormat drops when
   * rebuilding the payload. Restoring it (clamped) is how a discrete level
   * reaches a model whose only other knob is `budget_tokens`, which these
   * models do not accept. Verified live 2026-08-02 against Alibaba Token Plan:
   * `output_config.effort: "high"` → 200, `"banana"` → 400 naming the seven
   * accepted levels, so the field IS read.
   *
   * Fail-soft by construction: an unknown model / cold cache yields `undefined`
   * metadata and falls through to the generic budget ladder. No path throws and
   * no request is ever blocked on catalog data.
   *
   * Override only for an endpoint whose enable value is outside the Anthropic
   * vocabulary (MiniMax answers `adaptive`, not `enabled`).
   */
  protected applyAnthropicWireReasoning(request: any, originalRequest: any): any {
    // ── Truthful unknown ────────────────────────────────────────────────────
    //
    // Checked FIRST, before the request's own effort signal, because an unknown
    // control makes every downstream branch a guess regardless of what was
    // asked for.
    //
    // There is no generic fallback here any more. The one that used to sit at
    // the bottom of this method emitted the effort ladder's token budget for any
    // model the catalog did not describe, which is how `qwen3.8-max` was sent
    // `budget_tokens: 38912` against a `max_tokens` of 32000 and rejected with
    // "max_completion_tokens [32000] must be greater than thinking_budget
    // [38912]" — a 400 before any inference, on a model the provider serves
    // perfectly well.
    //
    // A guessed knob is not a safe default. It is a claim about a wire contract
    // we have not read, and the failure lands on the newest models, which are
    // exactly the ones the catalog has not caught up with yet.
    //
    // `supportsThinking` is deliberately NOT consulted as a substitute. The
    // catalog publishes that flag even while reporting the status unknown
    // (`query-handler.ts` sets `reasoningStatus: "unknown"` and can still emit
    // `supportsThinking` from coarse capability data), so it is present exactly
    // where it proves nothing about the knob.
    const status = this.lookupReasoningStatus();
    if (status !== "known") {
      log(
        `[${this.getName()}] ${this.modelId} reasoning control ${status === "unknown" ? "unknown" : "absent from the catalog"} -> no reasoning parameter emitted`
      );
      return request;
    }

    const reasoning = this.lookupReasoningCapability();

    // Catalog is explicit that the model cannot reason — never switch it on.
    // This is a KNOWN answer, and the opposite instruction to the unknown case
    // above: there we say nothing, here we say off.
    if (reasoning?.supported === false) {
      request.thinking = { type: "disabled" };
      log(`[${this.getName()}] ${this.modelId} reports no reasoning support -> thinking: disabled`);
      return request;
    }

    const effort = this.resolveEffortLevel(originalRequest);
    // No effort signal at all: leave whatever Claude Code sent untouched. The
    // endpoint's own default is a better answer than a level we invented.
    if (!effort) return request;

    if (this.meansReasoningOff(effort, reasoning)) {
      request.thinking = { type: "disabled" };
      log(`[${this.getName()}] effort ${effort} -> thinking.type: disabled for ${this.modelId}`);
      return request;
    }
    // `none`/`minimal` that survived {@link meansReasoningOff} is a request for
    // the LEAST thinking this model offers, not for none: a mandatory model, or
    // `minimal` where a depth control exists. Both fall through to the
    // control-driven dispatch below, which clamps to the advertised ladder.

    // ── Control-driven dispatch ─────────────────────────────────────────────
    //
    // `control` is authoritative and is read BEFORE `supportsBudgetTokens`.
    // That order is the rule: a model may advertise discrete levels AND accept a
    // budget, and in that case the levels are the control the vendor documents.
    // The previous code tested `control === "budget" || supportsBudgetTokens`,
    // so an optional budget capability silently overrode an effort control and
    // sent a token count to a model whose knob is a level.
    const control = reasoning?.control;
    const advertisesEfforts = (reasoning?.efforts?.length ?? 0) > 0;

    if (control === "effort" || (control === undefined && advertisesEfforts)) {
      return this.enableAnthropicEffort(request, effort, reasoning, "catalog: effort-controlled");
    }

    if (control === "budget" || (control === undefined && reasoning?.supportsBudgetTokens)) {
      return this.enableAnthropicBudget(request, effort, originalRequest, reasoning);
    }

    // `toggle`, `adaptive`, or a control this build does not recognise:
    // reasoning is on/off only. Emit the switch and no depth.
    request.thinking = { type: "enabled" };
    this.stripAnthropicEffortField(request);
    log(
      `[${this.getName()}] effort ${effort} -> thinking: enabled (no depth knob; catalog control=${control ?? "unspecified"}) for ${this.modelId}`
    );
    return request;
  }

  /**
   * Emit a discrete level, clamped into what the model advertises.
   *
   * Never also emits a budget: on this wire `output_config.effort` and
   * `thinking.budget_tokens` are two spellings of the same intent, and sending
   * both is a self-contradicting payload.
   */
  private enableAnthropicEffort(
    request: any,
    effort: EffortLevel,
    reasoning: ReasoningCapability | undefined,
    why: string
  ): any {
    const level = reasoning ? this.clampToAdvertisedEffort(effort, reasoning) : undefined;
    request.thinking = { type: "enabled" };
    if (level) {
      request.output_config = { ...(request.output_config ?? {}), effort: level };
    }
    log(
      `[${this.getName()}] effort ${effort} -> thinking: enabled, output_config.effort: ${level ?? "(none advertised)"} for ${this.modelId} (${why}; advertised: ${reasoning?.efforts?.join("/") ?? "none"})`
    );
    return request;
  }

  /**
   * Emit a token budget, clamped to fit under the request's output ceiling.
   *
   * The ceiling is the REQUEST's `max_tokens`, not the catalog's
   * `maxOutputTokens`, because `max_tokens` is the number the provider
   * validates the budget against — it is the one we are about to send.
   */
  private enableAnthropicBudget(
    request: any,
    effort: EffortLevel,
    originalRequest: any,
    reasoning: ReasoningCapability | undefined
  ): any {
    const requested = this.effortToThinkingTokenBudget(effort);
    const ceiling = outputCeilingOf(originalRequest, request);
    const budget = clampThinkingBudget(requested, ceiling);

    if (budget === "no-room") {
      // The ceiling cannot hold a legal budget AND leave room for an answer.
      // A mandatory-reasoning model still has to reason, so send the plain
      // on-switch and let the provider pick its own depth; anything else is a
      // payload it must reject.
      if (reasoning?.mandatory) {
        request.thinking = { type: "enabled" };
      } else {
        request.thinking = { type: "disabled" };
      }
      this.stripAnthropicEffortField(request);
      log(
        `[${this.getName()}] effort ${effort} -> budget ${requested ?? "(model max)"} does not fit under max_tokens ${ceiling}; sent thinking.type: ${request.thinking.type} for ${this.modelId}`
      );
      return request;
    }

    request.thinking =
      budget === undefined ? { type: "enabled" } : { type: "enabled", budget_tokens: budget };
    // A budget and a level are mutually exclusive expressions of depth.
    this.stripAnthropicEffortField(request);
    log(
      `[${this.getName()}] effort ${effort} -> thinking: enabled, budget_tokens: ${budget ?? "(model max)"}${
        budget !== undefined && budget !== requested
          ? ` (clamped from ${requested} under max_tokens ${ceiling})`
          : ""
      } for ${this.modelId} (catalog: budget-controlled)`
    );
    return request;
  }

  /**
   * Remove `output_config.effort` from a payload that expresses depth another
   * way, dropping the container when it is left empty.
   */
  private stripAnthropicEffortField(request: any): void {
    if (!request?.output_config || typeof request.output_config !== "object") return;
    if (request.output_config.effort === undefined) return;
    delete request.output_config.effort;
    if (Object.keys(request.output_config).length === 0) delete request.output_config;
  }

  /**
   * Clamp a requested level into the set a model actually advertises.
   *
   * - Advertised exactly → send it.
   * - Otherwise → the nearest advertised level, ties resolved UPWARD so a model
   *   is never silently under-driven (asking `low` of a model whose floor is
   *   `high` must get `high`, not nothing).
   * - No usable level list → the catalog's `defaultEffort`, else undefined
   *   (caller then sends the plain on-switch).
   *
   * Levels the catalog reports but claudish has no name for are ignored rather
   * than passed through — the vocabulary is {@link EFFORT_LEVELS}.
   *
   * ## Why clamping is load-bearing, not cosmetic (GLM-5.2)
   *
   * An endpoint ACCEPTING a level is not the same as the model DISTINGUISHING
   * it. Verified 2026-08-02 against the Z.AI coding endpoint: every one of the
   * seven canonical levels (`none`…`max`) is accepted — `reasoning_effort:
   * "banana"` returns a 400 that lists all seven — yet GLM-5.2 documents
   * exactly TWO (https://docs.z.ai/guides/llm/glm-5.2): `max` and `high`, with
   * `max` the default, and explicitly states that **any value other than
   * `high` runs at Max**.
   *
   * So the model's real behaviour is a one-bit test — "is this string `high`?"
   * — and passing an unadvertised level through unchanged INVERTS the user's
   * intent: a request for `low` is not `high`, therefore it runs at Max, and
   * asking for less thinking buys the most. Clamping `low → high` is what keeps
   * "less effort" from meaning "maximum effort". This is also why ties resolve
   * upward rather than downward: the failure mode of guessing too high is a
   * slower turn, the failure mode of falling off the advertised set entirely is
   * a silent jump to the endpoint's default.
   *
   * ## Known catalog discrepancy (fix belongs in models-index, not here)
   *
   * The slim catalog currently reports `efforts: ["xhigh","high"]`,
   * `defaultEffort: "high"` for glm-5.2, while the vendor docs say
   * `["max","high"]` with default `max`. `xhigh` is harmless TODAY only by
   * accident — anything that isn't `high` means Max, so `xhigh` and `max`
   * produce the same behaviour. It is still wrong data. The correction belongs
   * in the models-index catalog; do NOT hardcode a per-model override here, or
   * claudish stops reflecting the catalog it is supposed to be driven by.
   */
  /**
   * Does this effort level mean "send the OFF switch" for THIS model?
   *
   * One rule, shared by every wire, because the same mistake was made on four of
   * them independently: `effort === "none" || effort === "minimal"` → emit the
   * provider's disable value. That collapses two of claudish's seven levels into
   * one, and it is wrong twice over.
   *
   * **`minimal` is not `none`.** claudish publishes both. `none` means do not
   * reason; `minimal` means reason as little as possible. Where the model has a
   * depth control, "as little as possible" is its lowest rung — that is what the
   * word asks for, and {@link clampToAdvertisedEffort} already computes it.
   * Sending the off-switch instead throws away the distinction the two level
   * names exist to express.
   *
   * **Some models cannot be switched off at all.** The catalog says so with
   * `mandatory: true`, and the provider enforces it. Measured on Z.AI 2026-09-21:
   * `{"thinking":{"type":"disabled"}}` for glm-5.3 → `400 code 1210 "This model
   * always engages in thinking and cannot be disabled"`, while the same request
   * with the switch on and `reasoning_effort: "low"` → 200. The catalog publishes
   * `mandatory: true` for glm-5.3 and glm-5.3-flash, so this never needed a guess.
   *
   * The remaining case is a model with an on/off switch and no depth control and
   * no mandate. There "as little as possible" and "none" really are the same
   * request, because the wire has no third value to send — so both disable, and
   * behaviour for those models is unchanged.
   */
  protected meansReasoningOff(
    effort: EffortLevel,
    reasoning: ReasoningCapability | undefined
  ): boolean {
    if (effort !== "none" && effort !== "minimal") return false;
    if (reasoning?.mandatory) return false;
    if (effort === "none") return true;
    // `minimal` is off only where "as little as possible" IS off: the model has
    // no depth control at all, or the lowest rung it advertises is `none`. The
    // second case was missed: `sakana-namazu` advertises `["high","none"]` under
    // a toggle control, and `minimal` fell through and sent reasoning ON at full
    // depth although its floor is off.
    const advertised = (reasoning?.efforts ?? []).filter(isEffortLevel);
    if (advertised.length === 0) return true;
    const lowest = advertised.reduce((a, b) =>
      EFFORT_ORDER.indexOf(a) <= EFFORT_ORDER.indexOf(b) ? a : b
    );
    return lowest === "none";
  }

  protected clampToAdvertisedEffort(
    requested: EffortLevel,
    reasoning: ReasoningCapability
  ): EffortLevel | undefined {
    // `--effort` pins the level VERBATIM — skip the clamp entirely. This is an
    // escape hatch, and it can produce a 400: the clamp is what normally keeps
    // a level the model does not advertise off the wire. Asking for it anyway
    // is the user's explicit choice.
    //
    // Except `none` and `minimal`. Those two are DIRECTIONS — "off" and "the
    // least there is" — and `meansReasoningOff` has already decided they reach
    // this clamp only where the model cannot honour them literally. Sent
    // verbatim they mean the opposite: GLM-5.2 runs any value other than `high`
    // at Max, so a pinned `--effort minimal` bought maximum reasoning. Before
    // `meansReasoningOff` existed, a pinned minimal never got here — it became
    // the off switch first. Caught in release review for v10.0.2.
    if (this.pinnedEffort && this.pinnedEffort !== "none" && this.pinnedEffort !== "minimal") {
      return this.pinnedEffort;
    }
    const advertised = (reasoning.efforts ?? []).filter(isEffortLevel);
    if (advertised.length === 0) {
      return isEffortLevel(reasoning.defaultEffort) ? reasoning.defaultEffort : undefined;
    }
    if (advertised.includes(requested)) return requested;

    const target = EFFORT_ORDER.indexOf(requested);
    let best = advertised[0];
    let bestDistance = Number.POSITIVE_INFINITY;
    for (const candidate of advertised) {
      const distance = Math.abs(EFFORT_ORDER.indexOf(candidate) - target);
      // `<=` semantics: break ties toward the later (higher) level, since
      // `advertised` is scanned in catalog order which is not guaranteed sorted.
      if (
        distance < bestDistance ||
        (distance === bestDistance && EFFORT_ORDER.indexOf(candidate) > EFFORT_ORDER.indexOf(best))
      ) {
        best = candidate;
        bestDistance = distance;
      }
    }
    return best;
  }

  /** Slim-catalog reasoning metadata for this model, or undefined. Never throws. */
  protected lookupReasoningCapability(): ReasoningCapability | undefined {
    try {
      return lookupModelReasoning(this.modelId);
    } catch {
      // lookupModelReasoning throws only on a provider-routed id, which a
      // dialect should never see. Stay fail-soft regardless.
      return undefined;
    }
  }

  /**
   * Whether the catalog KNOWS this model's reasoning control.
   *
   * Fail-soft to `undefined`, which callers must treat exactly like
   * `"unknown"`: emit no reasoning parameter. A lookup that threw has told us
   * nothing, and "nothing" must never become a guessed knob.
   */
  protected lookupReasoningStatus(): "known" | "unknown" | undefined {
    try {
      return lookupModelReasoningStatus(this.modelId);
    } catch {
      return undefined;
    }
  }

  /**
   * Effort → token budget (claudish convention), shared by DashScope's
   * `thinking_budget` and Anthropic's `thinking.budget_tokens`. `max` omits the
   * budget so the model uses its full max CoT length.
   */
  protected effortToThinkingTokenBudget(effort: EffortLevel): number | undefined {
    switch (effort) {
      case "low":
        return 2048;
      case "medium":
        return 8192;
      case "high":
        return 24576;
      case "xhigh":
        return 38912;
      case "max":
        return undefined; // omit → model max
      case "none":
      case "minimal":
        // The FLOOR, not the default. These two levels only reach a budget when
        // the model cannot switch reasoning off (`mandatory`) or when `minimal`
        // has a depth control to turn down, and in both cases the request is for
        // the least thinking available. They used to fall to `default`'s 8192 —
        // four times `low`'s 2048 — so asking for less bought more. Measured on
        // the DashScope wire for qwen3.8-flash-next and qwen3.8-max-0902, caught
        // in release review for v10.0.2.
        return MIN_THINKING_BUDGET;
      default:
        return 8192;
    }
  }

  /**
   * `--effort <level>`: a user-pinned effort that bypasses BOTH the request's
   * own signal and the per-model catalog clamp.
   *
   * Safe as instance state because every ComposedHandler owns its dialect —
   * `resolveModelDialect()` builds a fresh object per call and never caches —
   * so a pin set for one model cannot leak into another.
   *
   * Only the seven canonical levels are accepted. A provider-specific value
   * that is not one of them cannot flow through the `EffortLevel`-typed
   * pipeline at all; `--model-params reasoning_effort=<value>` is the tool for
   * that, and it lands on the payload after every adapter has finished.
   */
  protected pinnedEffort?: EffortLevel;

  /**
   * The upstream model's vendor from its catalog connection (`""` when the
   * catalog names none); undefined without a connection. Set by the handler
   * that owns a connection, so upstream-family behaviour reads data, not the
   * model name.
   */
  protected upstreamVendor?: string;

  setUpstreamVendor(vendor: string): void {
    this.upstreamVendor = vendor;
  }

  /** Install the `--effort` override for this handler. undefined clears it. */
  setEffortOverride(level: EffortLevel | undefined): void {
    this.pinnedEffort = level;
  }

  /**
   * Normalize Claude Code's effort signal to a canonical {@link EffortLevel}
   * (or undefined when the request carries no effort hint).
   *
   * Priority:
   *  1. `output_config.effort` — the modern string level Claude Code (Opus
   *     4.7/4.8) sends (none/minimal/low/medium/high/xhigh/max).
   *  2. Legacy `thinking.budget_tokens` — older clients sent a token budget;
   *     bucket it into a canonical level.
   *
   * Every dialect calls this, then clamps the result to its provider's
   * accepted value set (or strips, when the provider has no reasoning knob).
   */
  protected resolveEffortLevel(originalRequest: any): EffortLevel | undefined {
    // `--effort` wins over anything the request carries. Checked first so the
    // legacy budget_tokens fallback below cannot override an explicit pin.
    if (this.pinnedEffort) return this.pinnedEffort;
    const lvl = originalRequest?.output_config?.effort;
    if (typeof lvl === "string") {
      const lower = lvl.toLowerCase();
      if (EFFORT_ORDER.includes(lower as EffortLevel)) {
        return lower as EffortLevel;
      }
    }

    // Legacy fallback: thinking.budget_tokens → bucketed effort.
    const budget = originalRequest?.thinking?.budget_tokens;
    if (typeof budget === "number") {
      if (budget <= 0) return "none";
      if (budget < 4000) return "low";
      if (budget < 16000) return "medium";
      if (budget < 32000) return "high";
      return "xhigh";
    }

    return undefined;
  }

  /**
   * Reset internal state between requests (prevents state contamination)
   */
  reset(): void {
    // REPLACE, never clear: a parser from the previous request may still be
    // decoding with the old map. See {@link toolNameBindings}.
    this.toolNameBindings = newToolNameBindings();
  }

  // ─── ComposedHandler integration (Phase 1c) ───────────────────────
  // These methods have sensible defaults so existing implementations continue
  // to work unchanged. Override in specific classes as needed.

  /**
   * Convert Claude-format messages to the target API format.
   * Default: delegates to convertMessagesToOpenAI.
   * Override for non-OpenAI formats (e.g., Gemini parts-based format).
   */
  convertMessages(claudeRequest: any, filterIdentityFn?: (s: string) => string): any[] {
    return convertMessagesToOpenAI(
      claudeRequest,
      this.modelId,
      filterIdentityFn,
      false,
      this.upstreamVendor
    );
  }

  /**
   * Convert Claude tools to the target API format.
   * Default: OpenAI function-calling format.
   */
  convertTools(claudeRequest: any, summarize = false): any[] {
    return convertToolsToOpenAI(claudeRequest, summarize);
  }

  /**
   * Build the full request payload for the target API.
   * Default: OpenAI Chat Completions format.
   * Override for Gemini (generateContent), Anthropic passthrough, etc.
   */
  buildPayload(claudeRequest: any, messages: any[], tools: any[]): any {
    const payload: any = {
      model: this.modelId,
      messages,
      stream: true,
    };
    if (tools.length > 0) {
      payload.tools = tools;

      // This builder had no tool_choice handling at ALL, which is easy to miss
      // because it holds no copy of the mapping to grep for. It is not dead:
      // `ComposedHandler.getAdapter()` is `explicitAdapter || resolvedDialect`,
      // so every provider profile that supplies no explicit Layer-1 format
      // builds its payload here — and dropped the caller's tool_choice
      // entirely, not just `any`.
      const toolChoice = mapToolChoiceToOpenAI(claudeRequest.tool_choice);
      if (toolChoice !== undefined) {
        payload.tool_choice = toolChoice;
      }
    }
    if (claudeRequest.max_tokens) {
      payload.max_tokens = claudeRequest.max_tokens;
    }
    if (claudeRequest.temperature !== undefined) {
      payload.temperature = claudeRequest.temperature;
    }
    this.applyOpenAISamplingParams(payload, claudeRequest);
    return payload;
  }

  /**
   * The stream format this format's target API returns.
   * Default: "openai-sse" (most common format).
   * Override for Anthropic passthrough ("anthropic-sse"), Gemini ("gemini-sse"), etc.
   */
  getStreamFormat(): StreamFormat {
    return "openai-sse";
  }

  /**
   * Context window size for this model (tokens).
   * Used for token tracking and context-left-percent calculation.
   */
  getContextWindow(): number {
    return lookupModel(this.modelId)?.contextWindow ?? 0;
  }

  /**
   * Pricing info for this model. Used by TokenTracker.
   * Default: delegates to the centralized getModelPricing.
   */
  getPricing(providerName: string): ModelPricing {
    return getModelPricing(providerName, this.modelId);
  }

  /**
   * Whether this model supports vision/image input.
   */
  supportsVision(): boolean {
    return true;
  }

  /**
   * Whether thinking blocks should be filtered from the SSE response.
   *
   * TRUE ON THE ANTHROPIC WIRE, for every dialect — unsigned thinking is a
   * property of the ENDPOINT, not of any model family.
   *
   * An Anthropic `thinking` block carries a cryptographic `signature` that
   * Claude Code verifies and round-trips on later turns. A third-party
   * Anthropic-compatible endpoint cannot produce one: captured live from Qwen
   * Plan (/apps/anthropic/v1/messages) for qwen3.8-max-preview and
   * qwen3.7-plus,
   *
   *     content_block_start: (index 0, type 'thinking', signature '')
   *     signature_delta count: 1, total signature length: 0
   *
   * so block[0] is a structurally valid thinking block with an EMPTY signature.
   * Claude Code cannot treat that as a first-class thinking block, so the
   * reasoning degrades into ordinary inline prose in the chat. We cannot forge a
   * signature, so the only correct move is to drop the block:
   * `createAnthropicPassthroughStream` strips it and RE-INDEXES the remaining
   * content blocks to a contiguous 0,1,2… sequence.
   *
   * Gating on the WIRE rather than a model list is deliberate — a hardcoded
   * list would silently miss the next model added to a multi-vendor plan, which
   * is exactly how `[email protected]` and `qtoken@deepseek-v4-pro` kept leaking after
   * `[email protected]` was fixed. `wireFormat` is the composition hint
   * ComposedHandler supplies from `explicitAdapter.getStreamFormat()`.
   *
   * NOTE this is keyed on the composed `wireFormat`, which is supplied ONLY by
   * DialectManager (to every adapter it builds, Layer 1 formats included).
   * AnthropicAPIFormat is never built there — the provider profiles construct
   * it explicitly — so it keeps `false`, and a genuinely Anthropic backend
   * reached through it (Vertex serving real `claude-*`, whose signatures are
   * valid) is untouched.
   *
   * Override to force `true` on a provider that is only ever reached over this
   * wire and therefore need not depend on the hint being supplied (MiniMax).
   */
  shouldFilterThinking(): boolean {
    return this.isAnthropicWire();
  }

  /**
   * Rewrite every tool name in this payload into what the wire accepts, and
   * record the way back.
   *
   * THREE places carry a tool name, and all three must agree or the request is
   * worse than it was before:
   *
   *   1. `tools[]` — what the model may call. Both shapes: Chat Completions
   *      `{type:"function", function:{name}}` and the Responses API's flat
   *      `{type:"function", name}`.
   *   2. The HISTORY — `messages[]` assistant `tool_calls`, and the Responses
   *      API's `input[]` `function_call` items. A history naming a tool that is
   *      not in `tools[]` is rejected by strict endpoints and confuses every
   *      other one.
   *   3. `tool_choice` — pointing at a name the model was never offered is a
   *      400 on the first forced-tool turn.
   *
   * Encoding runs on the BUILT payload rather than inside each builder because
   * that is where all three live, and because the map has to be minted
   * somewhere both the payload and the parser can see.
   *
   * Idempotent: an already-encoded name transforms to itself and is bound to
   * itself, so a delegating adapter that runs this after its inner adapter
   * already did changes nothing.
   */
  protected encodeToolNames(request: any): void {
    const limit = this.getToolNameLimit();
    if (!limit || !request) return;

    const encode = (name: string) => encodeToolName(name, limit, this.toolNameBindings);

    if (Array.isArray(request.tools)) {
      for (const tool of request.tools) {
        if (tool?.function?.name) {
          tool.function.name = encode(tool.function.name);
        } else if (tool?.name) {
          tool.name = encode(tool.name);
        }
      }
    }

    if (Array.isArray(request.messages)) {
      for (const msg of request.messages) {
        if (msg?.role !== "assistant" || !Array.isArray(msg.tool_calls)) continue;
        for (const tc of msg.tool_calls) {
          if (tc?.function?.name) tc.function.name = encode(tc.function.name);
        }
      }
    }

    // Responses API history. `input` holds `function_call` items rather than an
    // assistant message with `tool_calls`, so the branch above cannot see them.
    if (Array.isArray(request.input)) {
      for (const item of request.input) {
        if (item?.type === "function_call" && item.name) item.name = encode(item.name);
      }
    }

    const choice = request.tool_choice;
    if (choice && typeof choice === "object") {
      // `{type:"function", function:{name}}` (chat) and `{type:"function", name}`
      // (responses). The string forms — "auto"/"none"/"required" — name nothing.
      if (choice.function?.name) {
        choice.function.name = encode(choice.function.name);
      } else if (choice.name) {
        choice.name = encode(choice.name);
      }
    }
  }
}

/**
 * Default format/dialect that does no transformation
 */
export class DefaultAPIFormat extends BaseAPIFormat {
  processTextContent(textContent: string, _accumulatedText: string): AdapterResult {
    return {
      cleanedText: textContent,
      extractedToolCalls: [],
      wasTransformed: false,
    };
  }

  shouldHandle(_modelId: string): boolean {
    return false; // Default is fallback
  }

  getName(): string {
    return "DefaultAPIFormat";
  }
}

// ─── Backward-compatible aliases ──────────────────────────────────────────────
// Keep old names as aliases so legacy code referencing them still compiles
// during the transition. These can be removed in a future cleanup pass.

/** @deprecated Use BaseAPIFormat */
export const BaseModelAdapter = BaseAPIFormat;
export type BaseModelAdapter = BaseAPIFormat;

/** @deprecated Use DefaultAPIFormat */
export const DefaultAdapter = DefaultAPIFormat;
export type DefaultAdapter = DefaultAPIFormat;