cartethyia 2.7.3 → 2.7.5

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;
+}

package/src/protocol/translation/quirks.ts

@@ -32,7 +32,7 @@ export interface ParamQuirk {
 }
 
 /** Per-wire output-token policy, in one table instead of per-builder branches. */
-export interface WireTokenBound {
+interface WireTokenBound {
   /** Default when the caller sent no limit (undefined = leave absent). */
   readonly defaultMaxTokens?: number;
   /** Floor applied to any positive caller value below it (wire minimum). */
@@ -66,6 +66,13 @@ const DEFAULT_OUTPUT_TOKENS = 32_000;
  * Output-token bounds per wire family. Chat has no global ceiling: a model's
  * catalog output limit is the ceiling, and an unknown model passes the
  * caller's value through. Messages keeps its Anthropic floors and OAuth cap.
+ *
+ * The ceiling only ever comes from `options.maxOutputTokens` (the model's
+ * catalog output limit, supplied by the compatible adapter from
+ * `candidate.output_limit`). When it is omitted there is nothing to clamp to,
+ * which is intentional pass-through: a direct codec caller without a catalog
+ * limit is unbounded, and an unknown model passes the caller's value through by
+ * design — the bound table supplies floors/defaults, never an invented ceiling.
  */
 export const WIRE_TOKEN_BOUNDS: Readonly<Record<string, WireTokenBound>> = {
   chat: { minTokens: 16, defaultMaxTokens: DEFAULT_OUTPUT_TOKENS },
@@ -73,7 +80,14 @@ export const WIRE_TOKEN_BOUNDS: Readonly<Record<string, WireTokenBound>> = {
   responses: { minTokens: 16, defaultMaxTokens: DEFAULT_OUTPUT_TOKENS },
 };
 
-/** Resolves the output-token value for one wire from caller controls. */
+/**
+ * Resolves the output-token value for one wire from caller controls.
+ *
+ * Clamping to a ceiling happens only when `options.maxOutputTokens` (the
+ * model's catalog limit) is present. An omitted `maxOutputTokens` means
+ * pass-through by design: a direct codec caller without a catalog limit is
+ * unbounded, and this function never fabricates a ceiling on its own.
+ */
 export function resolveWireMaxTokens(
   wire: string,
   controls: { max_tokens?: number | undefined },
@@ -120,7 +134,7 @@ function modelGeneration(modelId: string): { family: string; major: number; mino
 }
 
 /** True when the model rejects `temperature`/`top_p`/`top_k` at any thinking setting. */
-export function rejectsSamplingParams(modelId: string): boolean {
+function rejectsSamplingParams(modelId: string): boolean {
   const generation = modelGeneration(modelId);
   if (generation === undefined) return false;
   // Opus turns strict at 4.7; the other families at 5.0.
@@ -157,7 +171,7 @@ const PARAM_QUIRKS: readonly ParamQuirk[] = [
 ];
 
 /** Finds the first quirk matching the provider/model pair, or undefined. */
-export function findParamQuirk(
+function findParamQuirk(
   providerId: string,
   modelId: string,
 ): ParamQuirk | undefined {