cartethyia 2.7.4 → 2.7.6

package/src/protocol/translation/dialect/model-thinking.ts

@@ -0,0 +1,89 @@
+/**
+ * Canonical thinking clamp + output-floor helpers, shared by every wire codec.
+ *
+ * `clampThinkingLevelForModel` is the single clamp: it steps a requested
+ * effort down to the highest supported level ≤ the request, or up to the
+ * model's floor when the request is below it. It replaces the old
+ * `clampReasoningEffort` with the same semantics, driven by the data-driven
+ * `ThinkingConfig` from `thinking-ladder.ts`.
+ *
+ * `outputFloorFor` is the clamped-effort output floor (previously
+ * `clampedEffortOutputFloor` in `protocol/reasoning.ts`): when the applied
+ * effort differs from the requested one, the caller sized `max_tokens` for the
+ * effort it asked for, and the applied level spends its budget on reasoning
+ * before writing the answer — so raise the output budget to the model's
+ * catalog ceiling rather than let the answer truncate.
+ */
+import {
+  REASONING_EFFORT_LADDER,
+  type ReasoningEffortLevel,
+} from "../thinking";
+import type { ThinkingConfig } from "./thinking-ladder";
+
+/**
+ * Clamps a requested reasoning effort against a model/wire's resolved
+ * `ThinkingConfig`. Same semantics as the removed `clampReasoningEffort`:
+ * synonyms normalize (`ultra` → `max`, `off` → `none`), unknown strings drop
+ * (no invented fallback), and a request below the floor uses the floor.
+ */
+export function clampThinkingLevelForModel(
+  thinking: ThinkingConfig | undefined,
+  requested: string | undefined,
+): ReasoningEffortLevel | undefined {
+  if (requested === undefined || typeof requested !== "string") return undefined;
+  const raw = requested.toLowerCase().trim();
+  const normalized = raw === "ultra" ? "max" : raw === "off" ? "none" : raw;
+  if (normalized === "none") return undefined;
+  if (thinking === undefined) return normalized as ReasoningEffortLevel;
+
+  const supported = thinking.efforts;
+  if (supported.includes(normalized as ReasoningEffortLevel)) {
+    return normalized as ReasoningEffortLevel;
+  }
+  const requestedIndex = REASONING_EFFORT_LADDER.indexOf(normalized as ReasoningEffortLevel);
+  if (requestedIndex === -1) return undefined;
+
+  let clamped: ReasoningEffortLevel | undefined;
+  for (const level of supported) {
+    if (REASONING_EFFORT_LADDER.indexOf(level) > requestedIndex) break;
+    clamped = level;
+  }
+  // No smaller supported level exists (caller asked below floor): use floor.
+  return clamped ?? supported[0];
+}
+
+const CLAMPED_EFFORT_MIN_OUTPUT_TOKENS = 16_384;
+
+const EFFORT_LEVEL_RANK: Readonly<Record<string, number>> = {
+  off: 0,
+  none: 0,
+  instant: 1,
+  minimal: 2,
+  low: 3,
+  medium: 4,
+  high: 5,
+  xhigh: 6,
+  max: 7,
+};
+
+/**
+ * Minimum output budget for a caller whose requested effort the ladder could
+ * not serve as asked. See the module doc for why both clamp directions need it.
+ * Only ever raises, and only to the model's own catalog limit.
+ */
+export function outputFloorFor(
+  requested: string | undefined,
+  applied: string | undefined,
+  modelOutputLimit: number | undefined,
+): number | undefined {
+  if (requested === undefined || applied === undefined) return undefined;
+  const from = EFFORT_LEVEL_RANK[requested.trim().toLowerCase()];
+  const to = EFFORT_LEVEL_RANK[applied.trim().toLowerCase()];
+  if (from === undefined || to === undefined || from === to) return undefined;
+  if (modelOutputLimit === undefined || !Number.isFinite(modelOutputLimit) || modelOutputLimit <= 0)
+    return undefined;
+  // Leave headroom instead of claiming the whole catalog limit: the caller's
+  // number was a real preference about answer size, and the goal is to stop
+  // truncating, not to spend the model's ceiling on every turn.
+  return Math.max(CLAMPED_EFFORT_MIN_OUTPUT_TOKENS, Math.floor(modelOutputLimit / 2));
+}

package/src/protocol/translation/dialect/qwen.ts

@@ -0,0 +1,114 @@
+/**
+ * Qwen chat-template in-band tool calls.
+ *
+ * Qwen3-family models emit tool calls as JSON blocks inside the text stream
+ * when the server's structured tool parser is not in use:
+ *
+ *   <tool_call>
+ *   {"name": "web_search", "arguments": {"query": "..."}}
+ *   </tool_call>
+ *
+ * The scanner recovers complete blocks into canonical tool calls and leaves the
+ * rest as text, mirroring the DSML/OMP scanners used for other families.
+ */
+import type { InbandScanner, InbandScanResult } from "./inband";
+
+const OPEN_TAG = "<tool_call>";
+const CLOSE_TAG = "</tool_call>";
+
+export class QwenToolCallScanner implements InbandScanner {
+  readonly #allowedNames: ReadonlySet<string>;
+  #pending = "";
+  #sequence = 0;
+
+  constructor(allowedNames: ReadonlySet<string>) {
+    this.#allowedNames = allowedNames;
+  }
+
+  push(chunk: string): InbandScanResult {
+    this.#pending += chunk;
+    let cursor = 0;
+    let text = "";
+    const calls: Array<InbandScanResult["calls"][number]> = [];
+    for (;;) {
+      const open = this.#pending.indexOf(OPEN_TAG, cursor);
+      if (open < 0) {
+        // Hold a possible pending opener at the tail; settle everything before it.
+        text += this.#pending.slice(cursor, this.#settledEnd(this.#pending.length));
+        cursor = this.#settledEnd(this.#pending.length);
+        break;
+      }
+      text += this.#pending.slice(cursor, open);
+      const bodyStart = open + OPEN_TAG.length;
+      const close = this.#pending.indexOf(CLOSE_TAG, bodyStart);
+      if (close < 0) {
+        // Unterminated block: hold from the opener on and settle what preceded it.
+        cursor = open;
+        break;
+      }
+      const inner = this.#pending.slice(bodyStart, close).trim();
+      const parsed = parseToolCall(inner);
+      if (parsed !== undefined) {
+        if (this.#allowedNames.has(parsed.name)) {
+          calls.push({
+            id: `call_qwen_${this.#sequence++}`,
+            name: parsed.name,
+            arguments: parsed.arguments,
+          });
+        } else {
+          // An undeclared tool is model text, not authority to invoke it.
+          text += this.#pending.slice(open, close + CLOSE_TAG.length);
+        }
+      } else {
+        text += this.#pending.slice(open, close + CLOSE_TAG.length);
+      }
+      cursor = close + CLOSE_TAG.length;
+    }
+    this.#pending = this.#pending.slice(cursor);
+    return { text, calls };
+  }
+
+  flush(): InbandScanResult {
+    const pending = this.#pending;
+    this.#pending = "";
+    if (isPossibleOpener(pending)) return { text: "", calls: [] };
+    return { text: pending, calls: [] };
+  }
+
+  #settledEnd(end: number): number {
+    // Keep a trailing fragment that could be the start of an opener.
+    const tail = this.#pending.slice(0, end);
+    const maxPrefix = Math.min(OPEN_TAG.length - 1, tail.length);
+    for (let len = maxPrefix; len > 0; len -= 1) {
+      if (OPEN_TAG.startsWith(tail.slice(-len))) return end - len;
+    }
+    return end;
+  }
+}
+
+function parseToolCall(inner: string): { readonly name: string; readonly arguments: string } | undefined {
+  if (inner.length === 0) return undefined;
+  let value: unknown;
+  try {
+    value = JSON.parse(inner);
+  } catch {
+    return undefined;
+  }
+  if (typeof value !== "object" || value === null) return undefined;
+  const record = value as Record<string, unknown>;
+  const name = typeof record["name"] === "string" ? record["name"] : undefined;
+  if (name === undefined || name.length === 0) return undefined;
+  const args = record["arguments"] ?? record["parameters"] ?? {};
+  let argsText: string;
+  try {
+    argsText = typeof args === "string" ? args : JSON.stringify(args);
+  } catch {
+    argsText = "{}";
+  }
+  return { name, arguments: argsText };
+}
+
+function isPossibleOpener(value: string): boolean {
+  if (value.length < OPEN_TAG.length) return OPEN_TAG.startsWith(value);
+  return value.startsWith(OPEN_TAG) && !value.includes(CLOSE_TAG);
+}

package/src/protocol/translation/dialect/resolver.ts

@@ -0,0 +1,83 @@
+/**
+ * Dialect resolver — pure, never throws, always returns a policy.
+ *
+ * Precedence:
+ *   1. explicit DB override (`models.dialect`; passed as `override`)
+ *   2. explicit `ModelDefinition.dialect` (passed as `declared`)
+ *   3. heuristic rules (`DIALECT_RULES`)
+ *   4. family default (`anthropic` for messages, `openai` otherwise)
+ *
+ * The default policies reproduce today's exact behavior: a request with no
+ * dialect set encodes byte-identically to before this layer existed.
+ */
+import type { WireFamily } from "../../canonical-model";
+import { DEFAULT_DIALECT_POLICIES, DIALECT_RULES } from "./rules";
+import type { DialectId, DialectPolicy } from "./types";
+import { BoundedLruMap } from "../../../transport/routing/bounded-lru";
+
+/** Known dialect ids, for validating loose DB/string overrides. */
+const KNOWN_DIALECT_IDS = new Set<string>(Object.keys(DEFAULT_DIALECT_POLICIES));
+
+/**
+ * Memoization for `resolveDialect` (mirrors THINKING_RESOLVE_CACHE). The key
+ * concatenates every argument, all of which are value types, so it is
+ * collision-safe. The cache is a {@link BoundedLruMap}: the key space is
+ * bounded by the model catalog, but a request can name an arbitrary model
+ * string, so an unbounded map would pin an entry for every miss forever.
+ */
+const DIALECT_RESOLVE_CACHE_MAX_ENTRIES = 1024;
+const DIALECT_RESOLVE_CACHE = new BoundedLruMap<string, DialectPolicy>(
+  DIALECT_RESOLVE_CACHE_MAX_ENTRIES,
+);
+
+export function resolveDialect(
+  modelId: string,
+  providerId: string,
+  wireFamily: WireFamily,
+  override?: string | null,
+  declared?: DialectId,
+): DialectPolicy {
+  const key = `${modelId.toLowerCase()}|${providerId}|${wireFamily}|${override ?? ""}|${declared ?? ""}`;
+  const cached = DIALECT_RESOLVE_CACHE.get(key);
+  if (cached !== undefined) return cached;
+  const policy = resolveDialectUncached(modelId, providerId, wireFamily, override, declared);
+  DIALECT_RESOLVE_CACHE.set(key, policy);
+  return policy;
+}
+
+function resolveDialectUncached(
+  modelId: string,
+  providerId: string,
+  wireFamily: WireFamily,
+  override?: string | null,
+  declared?: DialectId,
+): DialectPolicy {
+  const id = pickDialect(modelId, providerId, wireFamily, override, declared);
+  const policy = DEFAULT_DIALECT_POLICIES[id];
+  if (policy !== undefined) return policy;
+
+  // An unknown dialect id (e.g. from a future DB row) falls back to the
+  // family default — never throw, never invent behavior.
+  return DEFAULT_DIALECT_POLICIES[familyDefault(wireFamily)];
+}
+
+function pickDialect(
+  modelId: string,
+  providerId: string,
+  wireFamily: WireFamily,
+  override?: string | null,
+  declared?: DialectId,
+): DialectId {
+  if (override !== undefined && override !== null && KNOWN_DIALECT_IDS.has(override)) {
+    return override as DialectId;
+  }
+  if (declared !== undefined) return declared;
+  for (const rule of DIALECT_RULES) {
+    if (rule.match(modelId, providerId, wireFamily)) return rule.dialect;
+  }
+  return familyDefault(wireFamily);
+}
+
+function familyDefault(wireFamily: WireFamily): DialectId {
+  return wireFamily === "messages" ? "anthropic" : "openai";
+}

package/src/protocol/translation/dialect/rules.ts

@@ -0,0 +1,93 @@
+/**
+ * Dialect policies & heuristic rules.
+ *
+ * The default policies are frozen to today's behavior — they are the baseline
+ * the golden tests assert against. A dialect not listed here falls back to the
+ * family default in `resolver.ts`.
+ */
+import type { WireFamily } from "../../canonical-model";
+import type { DialectId, DialectPolicy } from "./types";
+
+/** The generic OpenAI-compatible default — mirrors current `chat` wire behavior. */
+const OPENAI_POLICY: DialectPolicy = {
+  reasoningContentField: "reasoning_content",
+  maxTokensField: "max_tokens",
+  stripSpecialTokens: false,
+  supportsMultipleSystemMessages: true,
+  supportsToolChoice: true,
+  requiresAssistantContentForToolCalls: false,
+  allowsSyntheticReasoningContent: true,
+  thinkingFormat: "openai",
+  inband: null,
+};
+
+/** The generic Anthropic/Messages default. */
+const ANTHROPIC_POLICY: DialectPolicy = {
+  maxTokensField: "max_tokens",
+  stripSpecialTokens: false,
+  supportsMultipleSystemMessages: true,
+  supportsToolChoice: true,
+  requiresAssistantContentForToolCalls: false,
+  allowsSyntheticReasoningContent: true,
+  thinkingFormat: "openai",
+  inband: null,
+};
+
+/** DeepSeek: `reasoning_content`, `max_tokens`, no tool_choice, DSML in-band. */
+const DEEPSEEK_POLICY: DialectPolicy = {
+  reasoningContentField: "reasoning_content",
+  maxTokensField: "max_tokens",
+  stripSpecialTokens: "deepseek",
+  supportsMultipleSystemMessages: true,
+  supportsToolChoice: false,
+  requiresAssistantContentForToolCalls: true,
+  allowsSyntheticReasoningContent: false,
+  thinkingFormat: "deepseek",
+  inband: "deepseek",
+};
+
+/** Qwen: `enable_thinking` + `<tool_call>` chat template, strict system cardinality. */
+const QWEN_POLICY: DialectPolicy = {
+  reasoningContentField: "reasoning_content",
+  maxTokensField: "max_tokens",
+  stripSpecialTokens: false,
+  supportsMultipleSystemMessages: false,
+  supportsToolChoice: true,
+  requiresAssistantContentForToolCalls: false,
+  allowsSyntheticReasoningContent: true,
+  thinkingFormat: "qwen",
+  inband: "qwen",
+};
+
+/** Resolved policy per dialect id. A missing id falls back in `resolver.ts`. */
+export const DEFAULT_DIALECT_POLICIES: Readonly<Record<DialectId, DialectPolicy>> = {
+  openai: OPENAI_POLICY,
+  anthropic: ANTHROPIC_POLICY,
+  deepseek: DEEPSEEK_POLICY,
+  qwen: QWEN_POLICY,
+  kimi: OPENAI_POLICY,
+  glm: OPENAI_POLICY,
+  minimax: OPENAI_POLICY,
+  gemini: OPENAI_POLICY,
+};
+
+interface DialectRule {
+  readonly dialect: DialectId;
+  readonly match: (modelId: string, providerId: string, wireFamily: WireFamily) => boolean;
+}
+
+/**
+ * Heuristic rules (used only when no DB override and no explicit
+ * `ModelDefinition.dialect` exists). Declarative and provider/model-id based,
+ * matching the precedent of `src/protocol/translation/quirks.ts`.
+ */
+export const DIALECT_RULES: readonly DialectRule[] = [
+  {
+    dialect: "deepseek",
+    match: (_modelId, providerId) => providerId.toLowerCase() === "deepseek",
+  },
+  {
+    dialect: "qwen",
+    match: (modelId) => /qwen|portal|alibaba|qwq/i.test(modelId),
+  },
+];

package/src/protocol/translation/dialect/thinking-ladder.ts

@@ -0,0 +1,245 @@
+/**
+ * Data-driven thinking/effort ladder for a model + wire family.
+ *
+ * Replaces the old `resolveSupportedReasoningEfforts` if-chain and
+ * `claudeUsesAdaptiveThinking` string matching with a declarative rule table,
+ * following the oh-my-pi pattern: a model's reasoning ladder is data (a
+ * `ThinkingConfig`), not code. Adding a new model generation is a table row,
+ * not another `if (id.includes(...))`.
+ *
+ * Precedence:
+ *   1. explicit declared efforts (catalog `ModelDefinition.reasoningEfforts`)
+ *   2. first matching rule in `THINKING_LADDER_RULES`
+ *   3. family default (extended ladder, per-family transport mode)
+ */
+import type { WireFamily } from "../../canonical-model";
+import {
+  REASONING_EFFORT_LADDER,
+  type ReasoningEffortLevel,
+} from "../thinking";
+import { BoundedLruMap } from "../../../transport/routing/bounded-lru";
+
+/** How a reasoning effort is transported on the wire. */
+export type ThinkingControlMode =
+  | "effort" // OpenAI-style `reasoning_effort` / `reasoning.effort`
+  | "budget" // Anthropic budget-era: `thinking.enabled` + `budget_tokens` (+ `output_config.effort`)
+  | "anthropic-adaptive" // Anthropic adaptive-era: `thinking.adaptive` + `output_config.effort`
+  | "google-level"; // Gemini: effort affects the output floor only
+
+/**
+ * Resolved reasoning config for one model + wire family. The codecs read this
+ * instead of re-deriving ladders from model-id heuristics per request.
+ */
+export interface ThinkingConfig {
+  /** Which wire field/transport the effort rides on. */
+  readonly mode: ThinkingControlMode;
+  /** Supported efforts, canonical ladder order, never empty. */
+  readonly efforts: readonly ReasoningEffortLevel[];
+  /** Default effort when the caller expresses none (e.g. DeepSeek forces high). */
+  readonly defaultLevel?: ReasoningEffortLevel;
+  /** True when the upstream rejects off/omitted efforts → clamp up to the floor. */
+  readonly requiresEffort?: boolean;
+}
+
+/** Optional model-declared thinking override (compile-time, persisted catalog). */
+export interface ThinkingModelDecl {
+  readonly efforts?: readonly string[];
+  readonly mode?: ThinkingControlMode;
+}
+
+/** DeepSeek's default effort, owned here so rule table and helpers agree. */
+export const DEEPSEEK_DEFAULT_EFFORT = "high" as const;
+
+/** Responses-wire default: no `max` tier (OpenAI/OpenCode/Azure). */
+const RESPONSES_WIRE_SUPPORTED_EFFORTS: readonly ReasoningEffortLevel[] = [
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+];
+
+/** Full 6-tier scale (Claude, MiMo, Kimi, DeepSeek). */
+const EXTENDED_SUPPORTED_EFFORTS: readonly ReasoningEffortLevel[] = [
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+/** Standard 4-tier scale (Gemini, Qwen). */
+const BASE_SUPPORTED_EFFORTS: readonly ReasoningEffortLevel[] = [
+  "minimal",
+  "low",
+  "medium",
+  "high",
+];
+
+/** `mimo-v2.6` rejects every effort outside this set (live 500s). */
+const MIMO_V26_SUPPORTED_EFFORTS: readonly ReasoningEffortLevel[] = ["low", "medium", "high"];
+
+/** Mercury chat ladder: `{instant, low, medium, high}` (live 400s outside). */
+const INCEPTION_SUPPORTED_EFFORTS: readonly ReasoningEffortLevel[] = [
+  "instant",
+  "low",
+  "medium",
+  "high",
+];
+
+/** OpenAI 5.6/6/daybreak + new-gen Claude adaptive: `low..max`, no `minimal`. */
+const LOW_TO_MAX_SUPPORTED_EFFORTS: readonly ReasoningEffortLevel[] = [
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+/** `gpt-5.5` rows: neither `minimal` nor `max`. */
+const GPT55_SUPPORTED_EFFORTS: readonly ReasoningEffortLevel[] = [
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+];
+
+/** Claude adaptive 4.6 pair: `low..high`. */
+const CLAUDE_ADAPTIVE_46_SUPPORTED_EFFORTS: readonly ReasoningEffortLevel[] = [
+  "low",
+  "medium",
+  "high",
+];
+
+interface ThinkingLadderRule {
+  readonly id?: RegExp;
+  readonly provider?: RegExp;
+  readonly wireFamily?: WireFamily;
+  readonly efforts: readonly ReasoningEffortLevel[];
+  readonly mode?: ThinkingControlMode;
+  readonly defaultLevel?: ReasoningEffortLevel;
+  readonly requiresEffort?: boolean;
+  /** True when `id` expects the dot → dash normalized id (Claude generations). */
+  readonly normalizeClaudeId?: boolean;
+}
+
+/**
+ * Rule table — the declarative replacement for the previous if-chain.
+ * First match wins; `wireFamily` rules must precede family-agnostic ones so
+ * the Responses wire keeps its cap (`no max`) even over Claude-family model
+ * ids, exactly like the old `wireFamily === "responses"` early return.
+ *
+ * Claude generation rules use `normalizeClaudeId` and match against the
+ * dot-tolerant form (`claude-opus-4.6` → `claude-opus-4-6`), mirroring the
+ * removed `claudeUsesAdaptiveThinking` behavior.
+ */
+export const THINKING_LADDER_RULES: readonly ThinkingLadderRule[] = [
+  // --- Responses wire (cap at `xhigh` unless a generation ladder says otherwise) ---
+  { wireFamily: "responses", id: /gpt-5\.5/, efforts: GPT55_SUPPORTED_EFFORTS },
+  { wireFamily: "responses", id: /gpt-5\.6|gpt-6|daybreak/, efforts: LOW_TO_MAX_SUPPORTED_EFFORTS },
+  { wireFamily: "responses", efforts: RESPONSES_WIRE_SUPPORTED_EFFORTS },
+  // --- Family heuristics (chat/messages/gemini) ---
+  { id: /muse/, efforts: RESPONSES_WIRE_SUPPORTED_EFFORTS },
+  { id: /gemini/, efforts: BASE_SUPPORTED_EFFORTS, mode: "google-level" },
+  { id: /mimo-v2\.6/, efforts: MIMO_V26_SUPPORTED_EFFORTS },
+  {
+    id: /mercury/,
+    wireFamily: "chat",
+    efforts: INCEPTION_SUPPORTED_EFFORTS,
+  },
+  // Claude adaptive 4.6 pair: `low..high`, no `xhigh`/`max`.
+  {
+    id: /opus-4-6|sonnet-4-6/,
+    normalizeClaudeId: true,
+    efforts: CLAUDE_ADAPTIVE_46_SUPPORTED_EFFORTS,
+    mode: "anthropic-adaptive",
+  },
+  // New-gen Claude adaptive: `low..max`.
+  {
+    id: /fable|mythos|opus-5|sonnet-5|opus-4-7|opus-4-8/,
+    normalizeClaudeId: true,
+    efforts: LOW_TO_MAX_SUPPORTED_EFFORTS,
+    mode: "anthropic-adaptive",
+  },
+  // Budget-era Claude rows: `minimal..xhigh`, no `max`.
+  {
+    id: /opus-4-5|sonnet-4-5|haiku-4-5|opus-4-1|opus-4-0|sonnet-4-0/,
+    normalizeClaudeId: true,
+    efforts: RESPONSES_WIRE_SUPPORTED_EFFORTS,
+  },
+  // Any other Claude row: extended ladder, budget-era transport.
+  { id: /claude/, efforts: EXTENDED_SUPPORTED_EFFORTS },
+];
+
+function familyDefaultMode(wireFamily: WireFamily): ThinkingControlMode {
+  if (wireFamily === "messages") return "budget";
+  if (wireFamily === "gemini") return "google-level";
+  return "effort";
+}
+
+/**
+ * Resolves the thinking config for a model + wire family. Pure, never throws,
+ * always returns a config (the family default is the floor).
+ *
+ * The rule table is deterministic and the codecs call this once per encode, so
+ * the no-declared-efforts result (the common case) is memoized per
+ * model/wire/provider key. Declared efforts bypass the cache because the
+ * `declared` object identity changes per call.
+ *
+ * The cache is a {@link BoundedLruMap}: the key space is bounded by the model
+ * catalog, but a request can name an arbitrary model string, so an unbounded
+ * map would pin an entry for every miss forever. The bound keeps memory flat
+ * while hot models stay resident.
+ */
+const THINKING_RESOLVE_CACHE_MAX_ENTRIES = 1024;
+const THINKING_RESOLVE_CACHE = new BoundedLruMap<string, ThinkingConfig>(
+  THINKING_RESOLVE_CACHE_MAX_ENTRIES,
+);
+
+export function resolveThinkingForModel(
+  modelId: string,
+  providerId: string,
+  wireFamily: WireFamily,
+  declared?: ThinkingModelDecl,
+): ThinkingConfig {
+  const id = modelId.toLowerCase();
+
+  // Declared efforts (catalog `reasoningEfforts`) win when present and valid.
+  if (declared?.efforts !== undefined && declared.efforts.length > 0) {
+    const filtered = declared.efforts.filter((e): e is ReasoningEffortLevel =>
+      REASONING_EFFORT_LADDER.includes(e as ReasoningEffortLevel),
+    );
+    if (filtered.length > 0) {
+      return {
+        mode: declared.mode ?? familyDefaultMode(wireFamily),
+        efforts: filtered,
+      };
+    }
+  }
+
+  const cacheKey = `${id}|${providerId}|${wireFamily}`;
+  const cached = THINKING_RESOLVE_CACHE.get(cacheKey);
+  if (cached !== undefined) return cached;
+
+  for (const rule of THINKING_LADDER_RULES) {
+    if (rule.wireFamily !== undefined && rule.wireFamily !== wireFamily) continue;
+    if (rule.id !== undefined) {
+      const source = rule.normalizeClaudeId === true ? id.replaceAll(".", "-") : id;
+      if (!rule.id.test(source)) continue;
+    }
+    if (rule.provider !== undefined && !rule.provider.test(providerId)) continue;
+    const resolved: ThinkingConfig = {
+      mode: rule.mode ?? familyDefaultMode(wireFamily),
+      efforts: rule.efforts,
+      ...(rule.defaultLevel === undefined ? {} : { defaultLevel: rule.defaultLevel }),
+      ...(rule.requiresEffort === undefined ? {} : { requiresEffort: rule.requiresEffort }),
+    };
+    THINKING_RESOLVE_CACHE.set(cacheKey, resolved);
+    return resolved;
+  }
+
+  const fallback: ThinkingConfig = { mode: familyDefaultMode(wireFamily), efforts: EXTENDED_SUPPORTED_EFFORTS };
+  THINKING_RESOLVE_CACHE.set(cacheKey, fallback);
+  return fallback;
+}

package/src/protocol/translation/dialect/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Wire dialect layer — the per-provider dial that sits *below* `WireFamily`.
+ *
+ * `WireFamily` names the transport envelope (chat / responses / messages /
+ * gemini). A dialect names the *dial* that family speaks for one provider or
+ * model family: DeepSeek's `reasoning_content` + DSML in-band tool calls,
+ * Qwen's `enable_thinking` + `<tool_call>` chat template, Anthropic's native
+ * Messages vocabulary, and the generic OpenAI-compatible default.
+ *
+ * The split matters because "canonical forces everything through one general
+ * shape" is what made the pipeline fragile: quirks unique to a family
+ * (reasoning field names, system-message cardinality, tool_choice support,
+ * in-band tool markup) had nowhere to live except ad-hoc `if (providerId ===
+ * …)` branches inside generic codecs. Here they are a resolved policy object
+ * the codecs read, exactly like oh-my-pi's `OpenAICompatPolicy`.
+ */
+
+/** A wire dialect. `"openai"`/`"anthropic"` are the generic defaults for each
+ *  `WireFamily`; the rest are family-specific dialects. */
+export type DialectId =
+  | "openai" // OpenAI-compatible generik (default wire chat)
+  | "anthropic" // Anthropic-compatible/ Claude-native dialect: signature thinking, cache-control
+  | "deepseek" // DSML + reasoning_content + max_tokens + strip tokens
+  | "qwen" // enable_thinking + <tool_call> + strict chat template
+  | "kimi"
+  | "glm"
+  | "minimax"
+  | "gemini"; // extensibel
+
+/** Resolved policy consumed by the wire codecs. Every field has a safe
+ *  default matching today's behavior; absent values fall back to it. */
+export interface DialectPolicy {
+  /** Which wire field carries a previous assistant turn's reasoning. None when
+   *  the wire has no reasoning side-channel (e.g. strict non-reasoning
+   *  upstreams that reject the extra field). Default `"reasoning_content"` —
+   *  the Chat wire's side channel, matching current behavior. */
+  readonly reasoningContentField?: "reasoning_content" | "reasoning" | "reasoning_text";
+  /** Which token-limit field the upstream accepts. Default `"max_tokens"`. */
+  readonly maxTokensField: "max_tokens" | "max_completion_tokens";
+  /** When truthy, strip the named family's special tokens from the stream. */
+  readonly stripSpecialTokens: "deepseek" | false;
+  /** False collapses multiple `system` messages into one (strict chat templates,
+   *  e.g. Qwen Portal / Alibaba / MiniMax). */
+  readonly supportsMultipleSystemMessages: boolean;
+  /** False drops `tool_choice` entirely (DeepSeek rejects it). */
+  readonly supportsToolChoice: boolean;
+  /** True requires every tool-call assistant turn to also carry text content
+   *  (DeepSeek V4 validates the exact content). */
+  readonly requiresAssistantContentForToolCalls: boolean;
+  /** False rejects synthetic reasoning placeholders on a tool-call turn
+   *  (DeepSeek V4 validates the exact value). */
+  readonly allowsSyntheticReasoningContent: boolean;
+  /** How a reasoning effort is encoded on the wire. */
+  readonly thinkingFormat: "openai" | "qwen" | "deepseek" | "chat-template";
+  /** In-band tool-call codec to use (DSML / `<tool_call>` …), or null for
+   *  structured-only tool calls. */
+  readonly inband: DialectId | null;
+}