Skip to content

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

refactor(routing)!: stop picking request dialects by model name

Jack Rudenko10d95160b266
diff --git a/packages/cli/src/adapters/litellm-api-format.test.ts b/packages/cli/src/adapters/litellm-api-format.test.ts
new file mode 100644
index 00000000..b582d0da
--- /dev/null
+++ b/packages/cli/src/adapters/litellm-api-format.test.ts
@@ -0,0 +1,23 @@
+import { expect, test } from "bun:test";
+import { LiteLLMAPIFormat } from "./litellm-api-format.js";
+
+test("MiniMax images remain standard image_url parts on LiteLLM", () => {
+ const format = new LiteLLMAPIFormat("minimax-m3", "https://example.invalid");
+ const messages = format.convertMessages({
+ messages: [
+ {
+ role: "user",
+ content: [
+ { type: "text", text: "Describe this" },
+ { type: "image", source: { type: "base64", media_type: "image/png", data: "aGVsbG8=" } },
+ { type: "image", source: { type: "url", url: "https://example.invalid/image.png" } },
+ ],
+ },
+ ],
+ });
+ expect(messages[0].content).toEqual([
+ { type: "text", text: "Describe this" },
+ { type: "image_url", image_url: { url: "data:image/png;base64,aGVsbG8=" } },
+ { type: "image_url", image_url: { url: "https://example.invalid/image.png" } },
+ ]);
+});
diff --git a/packages/cli/src/adapters/litellm-api-format.ts b/packages/cli/src/adapters/litellm-api-format.ts
index 46a10562..2f528ab3 100644
--- a/packages/cli/src/adapters/litellm-api-format.ts
+++ b/packages/cli/src/adapters/litellm-api-format.ts
@@ -1,21 +1,17 @@
/**
* LiteLLMAPIFormat — Layer 1 wire format for LiteLLM proxy.
*
- * Handles LiteLLM-specific model transforms:
- * - Inline image conversion for MiniMax (LiteLLM doesn't forward image_url properly)
- * - OpenAI-compatible payload with stream_options and tool_choice
+ * An OpenAI-compatible payload with stream_options and tool_choice. Nothing
+ * here is chosen by model name: an image goes as the standard `image_url`
+ * part, and the upstream's own answer is what tells the user it cannot read
+ * one. (A MiniMax-by-name inline-base64 rewrite used to sit here.)
*/
import { mapToolChoiceToOpenAI } from "../handlers/shared/format/openai-tools.js";
-import { log } from "../logger.js";
import { DefaultAPIFormat } from "./base-api-format.js";
-/** Models needing image_url → inline base64 conversion */
-const INLINE_IMAGE_MODEL_PATTERNS = ["minimax"];
-
export class LiteLLMAPIFormat extends DefaultAPIFormat {
private visionSupported: boolean;
- private needsInlineImages: boolean;
// baseUrl is accepted for backwards-compatible call sites (provider-profiles,
// custom-endpoints-loader, tests) but no longer consulted — the cached
@@ -24,9 +20,6 @@ export class LiteLLMAPIFormat extends DefaultAPIFormat {
constructor(modelId: string, _baseUrl: string) {
super(modelId);
this.visionSupported = this.checkVisionSupport();
- this.needsInlineImages = INLINE_IMAGE_MODEL_PATTERNS.some((p) =>
- modelId.toLowerCase().includes(p)
- );
}
getName(): string {
@@ -41,57 +34,6 @@ export class LiteLLMAPIFormat extends DefaultAPIFormat {
return this.visionSupported;
}
- /**
- * Convert messages, then transform image_url blocks to inline base64 text
- * for models where LiteLLM doesn't properly forward image content.
- */
- convertMessages(claudeRequest: any, filterIdentityFn?: (s: string) => string): any[] {
- const messages = super.convertMessages(claudeRequest, filterIdentityFn);
-
- if (!this.needsInlineImages) return messages;
-
- for (const msg of messages) {
- if (!Array.isArray(msg.content)) continue;
-
- const newContent: any[] = [];
- let inlineImages = "";
-
- for (const part of msg.content) {
- if (part.type === "image_url") {
- const url = typeof part.image_url === "string" ? part.image_url : part.image_url?.url;
- if (url?.startsWith("data:")) {
- const base64Match = url.match(/^data:[^;]+;base64,(.+)$/);
- if (base64Match) {
- inlineImages += `\n[Image base64:${base64Match[1]}]`;
- log(`[LiteLLMAPIFormat] Converted image_url to inline base64 for ${this.modelId}`);
- }
- } else if (url) {
- inlineImages += `\n[Image URL: ${url}]`;
- }
- } else {
- newContent.push(part);
- }
- }
-
- if (inlineImages) {
- const lastText = newContent.findLast((p: any) => p.type === "text");
- if (lastText) {
- lastText.text += inlineImages;
- } else {
- newContent.push({ type: "text", text: inlineImages.trim() });
- }
- }
-
- if (newContent.length === 1 && newContent[0].type === "text") {
- msg.content = newContent[0].text;
- } else if (newContent.length > 0) {
- msg.content = newContent;
- }
- }
-
- return messages;
- }
-
/**
* Build LiteLLM-specific request payload.
* Standard OpenAI format with stream_options and tool_choice support.
diff --git a/packages/cli/src/adapters/openrouter-api-format.test.ts b/packages/cli/src/adapters/openrouter-api-format.test.ts
index 16c40f82..165d2267 100644
--- a/packages/cli/src/adapters/openrouter-api-format.test.ts
+++ b/packages/cli/src/adapters/openrouter-api-format.test.ts
@@ -34,10 +34,10 @@ test("google vendor selects Gemini behavior for an opaque id", () => {
])
).toEqual(new Map([["call_1", "signed-thought"]]));
});
-test("without a vendor the existing prompt and include_reasoning rules remain", () => {
- const format = new OpenRouterAPIFormat("grok-reasoning");
- expect(format.convertMessages(request)[0].content).toContain(
- "MUST use the OpenAI tool_calls format with JSON"
- );
- expect(format.buildPayload(request, [], []).include_reasoning).toBe(true);
+test("unknown vendor does not infer prompts or reasoning from the name", () => {
+ const format = new OpenRouterAPIFormat("grok-gemini-o3-reasoning", { vendor: "" });
+ expect(format.convertMessages(request)).toEqual(request.messages);
+ const body = format.buildPayload({ ...request, thinking: { type: "enabled" } }, [], []);
+ expect(body).not.toHaveProperty("include_reasoning");
+ expect(body).not.toHaveProperty("thinking");
});
diff --git a/packages/cli/src/adapters/openrouter-api-format.ts b/packages/cli/src/adapters/openrouter-api-format.ts
index 088a2175..64524421 100644
--- a/packages/cli/src/adapters/openrouter-api-format.ts
+++ b/packages/cli/src/adapters/openrouter-api-format.ts
@@ -16,47 +16,24 @@ import {
} from "../handlers/shared/format/openai-tools.js";
import type { StreamFormat } from "../providers/transport/types.js";
import { type AdapterResult, BaseAPIFormat, DefaultAPIFormat } from "./base-api-format.js";
-import { resolveModelDialect } from "./dialect-manager.js";
import { GeminiAPIFormat } from "./gemini-api-format.js";
export class OpenRouterAPIFormat extends BaseAPIFormat {
private innerAdapter: BaseAPIFormat;
/**
- * The model's vendor from its catalog connection, when there is one. With
- * it, nothing here is chosen by model name: the upstream family's fixes key
- * on this field, and reasoning is the connection wire's (step 5w). Without
- * it (no catalog connection), the name-picked dialect still applies.
+ * The model's vendor, from its catalog connection (`""` when the catalog
+ * names none or the model is not in the catalog). The upstream family's
+ * fixes key on it; nothing here is chosen by the model name, and reasoning
+ * is the connection wire's (step 5w).
*/
- private readonly vendor?: string;
+ private readonly vendor: string;
- constructor(modelId: string, options: { vendor?: string } = {}) {
+ constructor(modelId: string, options: { vendor: string }) {
super(modelId);
this.vendor = options.vendor;
- if (options.vendor !== undefined) this.setUpstreamVendor(options.vendor);
+ this.setUpstreamVendor(options.vendor);
this.innerAdapter =
- options.vendor === undefined
- ? resolveModelDialect(modelId)
- : options.vendor === "google"
- ? new GeminiAPIFormat(modelId)
- : new DefaultAPIFormat(modelId);
- }
-
- private isUpstream(vendor: "google", nameHints: string[]): boolean {
- if (this.vendor !== undefined) return this.vendor === vendor;
- return nameHints.some((hint) => this.modelId.includes(hint));
- }
-
- /** Without a connection only: the old name check, kept for that path. */
- private modelSupportsReasoning(): boolean {
- if (this.vendor !== undefined) return false;
- const id = this.modelId.toLowerCase();
- return (
- id.includes("o1") ||
- id.includes("o3") ||
- id.includes("r1") ||
- id.includes("qwq") ||
- id.includes("reasoning")
- );
+ options.vendor === "google" ? new GeminiAPIFormat(modelId) : new DefaultAPIFormat(modelId);
}
// ─── Text processing delegates to inner adapter ───────────────────
@@ -87,7 +64,7 @@ export class OpenRouterAPIFormat extends BaseAPIFormat {
// The Grok tool-format instruction is added by the shared converter above,
// keyed on the connection's vendor (or the name, without a connection).
- if (this.isUpstream("google", ["gemini", "google/"])) {
+ if (this.vendor === "google") {
const geminiMsg = `CRITICAL INSTRUCTION FOR OUTPUT FORMAT:
1. Keep ALL internal reasoning INTERNAL. Never output your thought process as visible text.
2. Do NOT start responses with phrases like "Wait, I'm...", "Let me think...", "Okay, so...", "First, I need to..."
@@ -138,16 +115,6 @@ export class OpenRouterAPIFormat extends BaseAPIFormat {
payload.tools = tools;
}
- // Include reasoning for models that support it
- if (this.modelSupportsReasoning()) {
- payload.include_reasoning = true;
- }
-
- // Pass through thinking config
- if (claudeRequest.thinking) {
- payload.thinking = claudeRequest.thinking;
- }
-
const toolChoice = mapToolChoiceToOpenAI(claudeRequest.tool_choice);
if (toolChoice !== undefined) {
payload.tool_choice = toolChoice;
diff --git a/packages/cli/src/adapters/sampling-params-forwarded.test.ts b/packages/cli/src/adapters/sampling-params-forwarded.test.ts
index 1f7c5343..2056cf6a 100644
--- a/packages/cli/src/adapters/sampling-params-forwarded.test.ts
+++ b/packages/cli/src/adapters/sampling-params-forwarded.test.ts
@@ -26,7 +26,7 @@ const BUILDERS: [string, () => { buildPayload: (r: any, m: any[], t: any[]) => a
["BaseAPIFormat", () => new DefaultAPIFormat("some-model")],
["OpenAIAPIFormat", () => new OpenAIAPIFormat("gpt-4o")],
["LiteLLMAPIFormat", () => new LiteLLMAPIFormat("gpt-4o", "http://localhost:4000")],
- ["OpenRouterAPIFormat", () => new OpenRouterAPIFormat("openai/gpt-4o")],
+ ["OpenRouterAPIFormat", () => new OpenRouterAPIFormat("openai/gpt-4o", { vendor: "openai" })],
["LocalModelAdapter", () => new LocalModelAdapter("qwen2.5-coder", "ollama")],
];
diff --git a/packages/cli/src/adapters/tool-choice-mapping.test.ts b/packages/cli/src/adapters/tool-choice-mapping.test.ts
index cbbc20a6..d8d36bf7 100644
--- a/packages/cli/src/adapters/tool-choice-mapping.test.ts
+++ b/packages/cli/src/adapters/tool-choice-mapping.test.ts
@@ -41,7 +41,7 @@ const CHAT_BUILDERS: [string, () => { buildPayload: (r: any, m: any[], t: any[])
["BaseAPIFormat", () => new DefaultAPIFormat("some-model")],
["OpenAIAPIFormat", () => new OpenAIAPIFormat("gpt-4o")],
["LiteLLMAPIFormat", () => new LiteLLMAPIFormat("gpt-4o", "http://localhost:4000")],
- ["OpenRouterAPIFormat", () => new OpenRouterAPIFormat("openai/gpt-4o")],
+ ["OpenRouterAPIFormat", () => new OpenRouterAPIFormat("openai/gpt-4o", { vendor: "openai" })],
["LocalModelAdapter", () => new LocalModelAdapter("qwen2.5-coder", "ollama")],
];
diff --git a/packages/cli/src/cli.ts b/packages/cli/src/cli.ts
index 19526246..387df3f4 100644
--- a/packages/cli/src/cli.ts
+++ b/packages/cli/src/cli.ts
@@ -1845,27 +1845,23 @@ async function probeModelRouting(
declaredStreamFormat = "openai-sse";
}
- const { resolveModelDialect } = await import("./adapters/dialect-manager.js");
- const modelTranslator = resolveModelDialect(modelName);
- const modelTranslatorName = modelTranslator.getName();
+ // No dialect is picked by model name any more; the only profile that names
+ // one is the Grok subscription.
+ const modelTranslatorName = providerName === "grok-subscription" ? "GrokModelDialect" : "none";
const TRANSPORT_OVERRIDES: Record<string, string> = {
litellm: "openai-sse",
openrouter: "openai-sse",
};
const transportOverride = TRANSPORT_OVERRIDES[providerName] || null;
-
- const modelTranslatorFormat =
- modelTranslatorName !== "DefaultAPIFormat" ? modelTranslator.getStreamFormat() : null;
- const effectiveStreamFormat =
- transportOverride || modelTranslatorFormat || declaredStreamFormat;
+ const effectiveStreamFormat = transportOverride || declaredStreamFormat;
return {
formatAdapter: formatAdapterName,
declaredStreamFormat,
modelTranslator: modelTranslatorName,
- contextWindow: modelTranslator.getContextWindow(),
- supportsVision: modelTranslator.supportsVision(),
+ contextWindow: lookupModelForProvider(modelName, definitionName) ?? 0,
+ supportsVision: true,
transportOverride,
effectiveStreamFormat,
};
diff --git a/packages/cli/src/format-translation.test.ts b/packages/cli/src/format-translation.test.ts
index 7b68fc56..23ff0aa5 100644
--- a/packages/cli/src/format-translation.test.ts
+++ b/packages/cli/src/format-translation.test.ts
@@ -2898,7 +2898,7 @@ describe("Regression: truncated turns are reported as max_tokens", () => {
async function getOpenRouterAdapter() {
const mod = await import("./adapters/openrouter-api-format.js");
- return new mod.OpenRouterAPIFormat("google/gemini-3.1-pro-preview");
+ return new mod.OpenRouterAPIFormat("google/gemini-3.1-pro-preview", { vendor: "google" });
}
async function getGeminiParser() {
diff --git a/packages/cli/src/handlers/advisor-capture.test.ts b/packages/cli/src/handlers/advisor-capture.test.ts
index b366f1f5..8c1565cc 100644
--- a/packages/cli/src/handlers/advisor-capture.test.ts
+++ b/packages/cli/src/handlers/advisor-capture.test.ts
@@ -54,7 +54,7 @@ function parsedResponse(name: string): Response {
return createStreamingResponseHandler(
createMockContext(),
fixtureToResponse(name),
- new OpenRouterAPIFormat("x-ai/grok-4.6"),
+ new OpenRouterAPIFormat("x-ai/grok-4.6", { vendor: "x-ai" }),
"x-ai/grok-4.6",
null,
undefined,
diff --git a/packages/cli/src/handlers/composed-handler-connection-error.test.ts b/packages/cli/src/handlers/composed-handler-connection-error.test.ts
index b29d3f50..eb6563b6 100644
--- a/packages/cli/src/handlers/composed-handler-connection-error.test.ts
+++ b/packages/cli/src/handlers/composed-handler-connection-error.test.ts
@@ -1,5 +1,6 @@
import { afterEach, beforeAll, describe, expect, test } from "bun:test";
import type { Context } from "hono";
+import { GrokModelDialect } from "../adapters/grok-model-dialect.js";
import type { ProviderTransport } from "../providers/transport/types.js";
import { ComposedHandler } from "./composed-handler.js";
import { FallbackHandler } from "./fallback-handler.js";
@@ -430,8 +431,8 @@ describe("site 2: forceRefreshAuth", () => {
// ---------------------------------------------------------------------------
describe("site 3: parameter-recovery re-fetch", () => {
- // A grok-* name resolves to GrokModelDialect, the one dialect with
- // `recoverFromRejection`. The id is unique to this file on purpose: the
+ // Explicitly supply GrokModelDialect to exercise `recoverFromRejection`.
+ // The id is unique to this file on purpose: the
// dialect memoises "this model rejected reasoning_effort" at module scope,
// and Bun shares that module across test files in a run.
const MODEL = "grok-9-connfail-probe";
@@ -455,7 +456,9 @@ describe("site 3: parameter-recovery re-fetch", () => {
throw CONNECT_FAILURE;
}) as unknown as typeof fetch;
- const handler = makeHandler(makeTransport(), MODEL);
+ const handler = new ComposedHandler(makeTransport(), MODEL, MODEL, 8080, {
+ dialect: new GrokModelDialect(MODEL),
+ });
const { c, captured } = makeContext();
const response = await handler.handle(c, GROK_PAYLOAD);
diff --git a/packages/cli/src/handlers/composed-handler-wire.test.ts b/packages/cli/src/handlers/composed-handler-wire.test.ts
index 83389fc1..1cbc4693 100644
--- a/packages/cli/src/handlers/composed-handler-wire.test.ts
+++ b/packages/cli/src/handlers/composed-handler-wire.test.ts
@@ -295,37 +295,51 @@ test.each([
}
);
-test("a catalog connection bypasses the MiniMax name-picked temperature dialect", async () => {
- const connection = resolved("opencode-zen", "minimax-m3");
- const ctx = context("opencode-zen", "minimax-m3");
- const connected = buildKnownWireHandler(ctx, "opencode-zen", connection, connection.wire)!;
- const offCatalog = new ComposedHandler(
- new OpenAIProviderTransport(ctx.provider, ctx.modelName, ctx.apiKey),
- ctx.targetModel,
- ctx.modelName,
- 0,
- { adapter: new OpenAIAPIFormat(ctx.modelName) }
- );
- handlers.push(connected, offCatalog);
- const bodies: any[] = [];
- globalThis.fetch = (async (_input, init) => {
- bodies.push(JSON.parse(String(init?.body)));
- return new Response("captured", { status: 599 });
- }) as typeof fetch;
- for (const handler of [connected, offCatalog]) {
- const app = new Hono();
- app.post("/", (c) =>
- handler.handle(c, {
- model: "minimax-m3",
- messages: [{ role: "user", content: "hello" }],
- max_tokens: 100,
- temperature: 0,
- stream: true,
- })
- );
- await app.request("/", { method: "POST" });
+test.each([
+ [0, 0.01],
+ [2, 1],
+])(
+ "MiniMax vendor clamps temperature %s while wire reasoning wins",
+ async (temperature, clamped) => {
+ const connection = resolved("opencode-zen-go", "minimax-m3");
+ expect(connection.vendor).toBe("minimax");
+ // This Messages wire has unknown reasoning; its owner uses Chat, so no
+ // reasoning can be borrowed. Step 5w must erase the dialect thinking toggle.
+ expect(connection.wire.reasoning).toEqual({ status: "unknown" });
+ const foreign = structuredClone(connection);
+ foreign.vendor = "openai";
+ const bodies: any[] = [];
+ globalThis.fetch = (async (_input, init) => {
+ bodies.push(JSON.parse(String(init?.body)));
+ return new Response("captured", { status: 418 });
+ }) as typeof fetch;
+ for (const c of [connection, foreign]) {
+ const handler = buildKnownWireHandler(
+ context("opencode-zen-go", "minimax-m3"),
+ "opencode-zen-go",
+ c,
+ c.wire
+ )!;
+ handlers.push(handler);
+ const app = new Hono();
+ app.post("/", (ctx) =>
+ handler.handle(ctx, {
+ model: "minimax-m3",
+ messages: [{ role: "user", content: "hello" }],
+ max_tokens: 100,
+ temperature,
+ stream: true,
+ output_config: { effort: "high" },
+ })
+ );
+ await app.request("/", { method: "POST" });
+ }
+ expect(bodies).toHaveLength(2);
+ expect(bodies[0].temperature).toBe(clamped);
+ expect(bodies[1].temperature).toBe(temperature);
+ for (const body of bodies) {
+ expect(body).not.toHaveProperty("thinking");
+ expect(body).not.toHaveProperty("reasoning_effort");
+ }
}
- expect(bodies).toHaveLength(2);
- expect(bodies[0].temperature).toBe(0);
- expect(bodies[1].temperature).toBe(0.01);
-});
+);
diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.ts
index f5121e43..b60cbc8a 100644
--- a/packages/cli/src/handlers/composed-handler.ts
+++ b/packages/cli/src/handlers/composed-handler.ts
@@ -26,11 +26,11 @@ import {
DefaultAPIFormat,
type EffortLevel,
} from "../adapters/base-api-format.js";
+import { MiniMaxModelDialect } from "../adapters/minimax-model-dialect.js";
import type { ProviderTransport, StreamFormat } from "../providers/transport/types.js";
import type { ModelHandler } from "./types.js";
// Alias for readability within this file
type BaseModelAdapter = BaseAPIFormat;
-import { resolveModelDialect } from "../adapters/dialect-manager.js";
import { lookupModelForProvider } from "../adapters/model-catalog.js";
import type { QuotaAdapter } from "../auth/quota/adapter.js";
import { resolveQuotaAdapter } from "../auth/quota/registry.js";
@@ -221,6 +221,11 @@ export interface ComposedHandlerOptions {
* speed from it alone, after every adapter and dialect has run.
*/
connection?: ResolvedConnection;
+ /**
+ * A model-family dialect the PROFILE chose for a provider that serves one
+ * family (the Grok subscription). Never chosen from the model name.
+ */
+ dialect?: BaseAPIFormat;
/** `+pro` on the model spec: request mode pro, refused where the wire does not publish it. */
wireMode?: WireMode;
/** `#<speed>` on the model spec, refused where the wire does not publish it. */
@@ -280,31 +285,28 @@ export class ComposedHandler implements ModelHandler {
this.explicitAdapter = options.adapter;
this.isInteractive = options.isInteractive ?? false;
- // Initialize dialect manager for automatic dialect/format selection.
- // Always pass the bare modelName — passing routed strings here was the root
- // cause of #102 ([email protected] false-matching GLMModelDialect).
+ // The dialect is never picked by model name. A catalog connection's `wire`
+ // (or a custom endpoint's declared one) decides every reasoning and limit
+ // field (step 5w); a profile that genuinely serves one model family names
+ // its dialect explicitly (`options.dialect`: the Grok subscription). The
+ // name-ordered dialect factory this replaced picked, for example, the GLM
+ // dialect for any id containing "glm", whatever host or API served it.
//
- // The second argument is the REQUEST wire format, which only this class
- // knows: dialects self-select by model name, and the same model can be
- // served over different wires by different providers (Qwen: DashScope
- // OpenAI-compatible vs. Alibaba Token Plan's Anthropic Messages endpoint),
- // each with a differently-named reasoning knob. The Layer 1 FormatConverter
- // decides the request shape, so its getStreamFormat() is the signal — NOT
- // provider.overrideStreamFormat(), which only re-labels the RESPONSE for
- // aggregators. Undefined when no explicit converter was passed (the dialect
- // is then also the converter) → dialects fall back to the OpenAI default.
+ // The dialect gets the REQUEST wire format, which only this class knows:
+ // the Layer 1 converter decides the request shape, so its getStreamFormat()
+ // is the signal — NOT provider.overrideStreamFormat(), which only re-labels
+ // the RESPONSE for aggregators.
//
- // A CATALOG CONNECTION gets no name-picked dialect at all: its `wire`
- // decides every reasoning and limit field (step 5w), and a dialect chosen
- // by model name is exactly the guess the wire replaces. Only a handler
- // without a connection (dynamic subscription, custom or local endpoint)
- // still resolves one.
- this.resolvedDialect = options.connection
- ? new DefaultAPIFormat(this.bareModelName, this.explicitAdapter?.getStreamFormat())
- : resolveModelDialect(this.bareModelName, this.explicitAdapter?.getStreamFormat());
-
- // Always resolve model-specific adapter (GLM, Grok, DeepSeek, etc.)
- // This handles model quirks independent of provider transport (LiteLLM, OpenRouter, etc.)
+ // One quirk is the MODEL's on every host and no wire field describes it:
+ // MiniMax rejects a temperature outside its range. It keys on the catalog's
+ // vendor field (data), and the MiniMax dialect's reasoning fields are then
+ // overwritten by the wire like any other (step 5w runs after it).
+ this.resolvedDialect =
+ options.dialect ??
+ (options.connection?.vendor === "minimax"
+ ? new MiniMaxModelDialect(this.bareModelName, this.explicitAdapter?.getStreamFormat())
+ : new DefaultAPIFormat(this.bareModelName, this.explicitAdapter?.getStreamFormat()));
+
const resolvedModelAdapter = this.resolvedDialect;
if (options.connection) {
for (const adapter of [this.explicitAdapter, this.resolvedDialect]) {
@@ -369,7 +371,7 @@ export class ComposedHandler implements ModelHandler {
// through. getAdapter() picks explicitAdapter or resolvedDialect at request
// time and modelAdapter runs in addition to it, so pinning only one leaves
// the flag working on some models and silently not on others. Safe to
- // mutate: resolveModelDialect() returns a fresh instance per handler, and
+ // mutate: the dialect is built per handler by its profile, and
// an explicit adapter is built per handler by its profile.
if (options.effortOverride) {
for (const dialect of new Set(
diff --git a/packages/cli/src/handlers/param-rejection-recovery.test.ts b/packages/cli/src/handlers/param-rejection-recovery.test.ts
index f463e177..1e619e0b 100644
--- a/packages/cli/src/handlers/param-rejection-recovery.test.ts
+++ b/packages/cli/src/handlers/param-rejection-recovery.test.ts
@@ -1,41 +1,10 @@
-/**
- * `recoverFromRejection` must be reachable for EVERY model, not only the ones a
- * dialect recognises.
- *
- * Item 11 (`b74bab2`) began forwarding `stop_sequences` → `stop` and `top_p` on
- * every OpenAI-shaped builder, and made `recoverFromRejection` concrete on
- * `BaseAPIFormat` so a strict relay's 400 is repaired in one retry. Its commit
- * message claims that wiring landed with it. It did not: the retry gate called
- * `this.modelAdapter.recoverFromRejection` alone, and `ComposedHandler`
- * deliberately leaves `modelAdapter` UNSET when the model resolves to
- * `DefaultAPIFormat` — which `resolveModelDialect` returns for every model no
- * dialect recognises. So the base implementation, written for exactly this case,
- * never ran for it.
- *
- * The population that hurts is the obvious one: a brand-new `vendor/new-model`
- * on a custom OpenAI-compatible endpoint is both the most likely to be
- * unrecognized AND the most likely to meet a relay that rejects `stop`.
- *
- * ## Why these tests drive the HANDLER
- *
- * `adapters/sampling-params-forwarded.test.ts` already pins the adapter method,
- * calling `fmt.recoverFromRejection(...)` directly — and stayed green through
- * the whole gap, because the method was always correct. It was never called.
- * That is the "tests that set up differently from production" shape; the only
- * test that can see this defect is one that goes through `handle()`.
- *
- * ## Provenance of the inputs
- *
- * REQUEST-side, with a stubbed upstream. No capture in the tree is an inbound
- * body or a provider 4xx, so the request and the relay's complaint are written
- * inline. The rejection wording is the documented shape of an OpenAI-compatible
- * relay, NOT captured from a live 4xx — the same labelled limitation
- * `sampling-params-forwarded.test.ts` carries.
+/** Parameter recovery runs both with the default format and an explicit dialect.
+ * Synthetic relay rejections exercise handle(), including its retry gate.
*/
import { afterEach, expect, test } from "bun:test";
import type { Context } from "hono";
-import { resolveModelDialect } from "../adapters/dialect-manager.js";
+import { GrokModelDialect } from "../adapters/grok-model-dialect.js";
import type { ProviderTransport } from "../providers/transport/types.js";
import { ComposedHandler } from "./composed-handler.js";
@@ -105,21 +74,8 @@ function claudeRequest(model: string) {
};
}
-/**
- * A model name no dialect in the tree claims, so `resolveModelDialect` answers
- * `DefaultAPIFormat` and `modelAdapter` stays unset. Asserted below rather than
- * assumed — a future dialect that starts matching this name would turn the test
- * green for the wrong reason.
- */
const UNKNOWN_MODEL = "vendor/new-model";
-test("the premise holds: this model has no dialect, grok-4 does", () => {
- // Without this, a future dialect matching `vendor/*` would set `modelAdapter`
- // and turn the test below green through the path that never broke.
- expect(resolveModelDialect(UNKNOWN_MODEL).getName()).toBe("DefaultAPIFormat");
- expect(resolveModelDialect("grok-4").getName()).not.toBe("DefaultAPIFormat");
-});
-
test("an unrecognized model still recovers from a rejected `stop`", async () => {
const calls = stubUpstream({ status: 400, body: UNKNOWN_STOP }, { status: 200, body: OK_STREAM });
@@ -163,12 +119,12 @@ test("a 4xx about something else is not retried", async () => {
});
test("a model WITH a dialect still recovers — the pre-existing path is intact", async () => {
- // Grok resolves to GrokModelDialect, so `modelAdapter` is set and this is the
- // path that always worked. Kept as the non-regression half: the fix adds a
- // second candidate, it must not displace the first.
+ // A profile-supplied dialect must retain its parameter recovery path.
const calls = stubUpstream({ status: 400, body: UNKNOWN_STOP }, { status: 200, body: OK_STREAM });
- const handler = new ComposedHandler(makeTransport(), "corp@grok-4", "grok-4", 8080, {});
+ const handler = new ComposedHandler(makeTransport(), "corp@grok-4", "grok-4", 8080, {
+ dialect: new GrokModelDialect("grok-4"),
+ });
await handler.handle(makeContext(), claudeRequest("grok-4"));
expect(calls.length).toBe(2);
diff --git a/packages/cli/src/providers/declared-endpoints.test.ts b/packages/cli/src/providers/declared-endpoints.test.ts
new file mode 100644
index 00000000..c6b04084
--- /dev/null
+++ b/packages/cli/src/providers/declared-endpoints.test.ts
@@ -0,0 +1,187 @@
+import { expect, test } from "bun:test";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { CustomEndpoint } from "../config-schema.js";
+
+// Imports that cache HOME, credentials and adapters stay in the isolated child.
+function capture(
+ endpoint?: CustomEndpoint,
+ model = "qwen3-thinking",
+ request: Record<string, unknown> = {},
+ mode = "custom"
+) {
+ const home = mkdtempSync(join(tmpdir(), "declared-endpoint-"));
+ const source = new URL("../", import.meta.url).pathname;
+ try {
+ const child = Bun.spawnSync(
+ [
+ process.execPath,
+ "--eval",
+ `
+ const { Hono } = await import("hono");
+ const { loadCustomEndpoints } = await import(${JSON.stringify(source + "providers/custom-endpoints-loader.ts")});
+ const { getRuntimeProfiles, clearRuntimeRegistry } = await import(${JSON.stringify(source + "providers/runtime-providers.ts")});
+ const { getProviderByName, toRemoteProvider } = await import(${JSON.stringify(source + "providers/provider-definitions.ts")});
+ const { ComposedHandler } = await import(${JSON.stringify(source + "handlers/composed-handler.ts")});
+ const model = ${JSON.stringify(model)};
+ const mode = ${JSON.stringify(mode)};
+ const ctx = { provider: { name: "wire-test", baseUrl: "https://example.invalid/v1", apiPath: "/chat/completions", apiKeyEnvVar: "", prefixes: [] }, modelName: model, targetModel: "wire-test@" + model, port: 0, apiKey: "fake", sharedOpts: {} };
+ let handler;
+ if (mode === "custom") {
+ const result = loadCustomEndpoints({ version: "1.0.0", defaultProfile: "default", profiles: {}, customEndpoints: { "wire-test": ${JSON.stringify(endpoint)} } });
+ if (result.registered !== 1) throw new Error(JSON.stringify(result));
+ ctx.provider = toRemoteProvider(getProviderByName("wire-test"));
+ handler = getRuntimeProfiles().get("wire-test").createHandler(ctx);
+ } else if (mode === "grok") {
+ const { grokSubscriptionProfile } = await import(${JSON.stringify(source + "providers/provider-profiles.ts")});
+ ctx.provider = toRemoteProvider(getProviderByName("grok-subscription"));
+ handler = grokSubscriptionProfile.createHandler(ctx);
+ console.log(JSON.stringify({ adapter: handler.getActiveAdapterName() }));
+ await handler.shutdown();
+ process.exit(0);
+ } else {
+ const options = {};
+ if (mode === "openrouter") {
+ const { OpenRouterAPIFormat } = await import(${JSON.stringify(source + "adapters/openrouter-api-format.ts")});
+ const { declaredWire, declaredConnection } = await import(${JSON.stringify(source + "providers/declared-wire.ts")});
+ options.adapter = new OpenRouterAPIFormat(model, { vendor: "" });
+ options.connection = declaredConnection("openrouter", model, ctx.provider.baseUrl, declaredWire("chat-completions", undefined));
+ }
+ handler = new ComposedHandler({ name: "wire-test", displayName: "Test", streamFormat: "openai-sse", getEndpoint: () => "https://example.invalid/chat/completions", getHeaders: async () => ({}) }, ctx.targetModel, model, 0, options);
+ }
+ const captures = [];
+ const originalFetch = globalThis.fetch;
+ globalThis.fetch = async (url, init) => {
+ captures.push({ url: String(url), method: init.method, body: JSON.parse(init.body) });
+ return new Response("captured", { status: 400 });
+ };
+ try {
+ const app = new Hono();
+ app.post("/", c => handler.handle(c, { model, max_tokens: 512, messages: [{role: "user", content: "hello"}], thinking: { type: "enabled", budget_tokens: 128 }, output_config: { effort: "high" }, ...${JSON.stringify(request)} }));
+ await app.request("/", { method: "POST" });
+ if (captures.length !== 1) throw new Error(JSON.stringify(captures));
+ console.log(JSON.stringify(captures[0]));
+ } finally { globalThis.fetch = originalFetch; await handler.shutdown(); clearRuntimeRegistry(); }
+ `,
+ ],
+ {
+ env: {
+ PATH: process.env.PATH,
+ HOME: home,
+ CLAUDISH_DISABLE_CATALOG_WARM: "1",
+ CLAUDISH_DISABLE_KEYCHAIN: "1",
+ CLAUDISH_DISABLE_OP: "1",
+ },
+ stdout: "pipe",
+ stderr: "pipe",
+ }
+ );
+ expect(child.exitCode, child.stderr.toString()).toBe(0);
+ return JSON.parse(child.stdout.toString());
+ } finally {
+ rmSync(home, { recursive: true, force: true });
+ }
+}
+const simple: CustomEndpoint = {
+ kind: "simple",
+ url: "https://example.invalid/v1",
+ format: "openai",
+ apiKey: "fake",
+};
+const thinkingWire = {
+ reasoning: {
+ enable: [{ path: "/chat_template_kwargs/enable_thinking", value: true }],
+ disable: [{ path: "/chat_template_kwargs/enable_thinking", value: false }],
+ },
+};
+
+test("simple OpenAI endpoint defaults do not infer Qwen reasoning", () => {
+ const { body } = capture(simple);
+ expect(body.max_tokens).toBe(512);
+ for (const field of ["enable_thinking", "chat_template_kwargs", "reasoning_effort", "thinking"])
+ expect(body).not.toHaveProperty(field);
+});
+test.each([true, false])("declared Qwen thinking switch sends %s", (enabled) => {
+ const { body } = capture({ ...simple, wire: thinkingWire }, "qwen3-thinking", {
+ thinking: { type: enabled ? "enabled" : "disabled" },
+ });
+ expect(body.chat_template_kwargs).toEqual({ enable_thinking: enabled });
+ expect(body.max_tokens).toBe(512);
+});
+test("declared effort clamps to a published value", () => {
+ const { body } = capture(
+ {
+ ...simple,
+ wire: {
+ reasoning: {
+ effort: { path: "/reasoning_effort", values: { low: "small", high: "large" } },
+ },
+ },
+ },
+ "qwen3-thinking",
+ { output_config: { effort: "medium" } }
+ );
+ expect(body.reasoning_effort).toBe("large");
+});
+test("simple Responses declaration chooses URL, body and output limit", () => {
+ const result = capture({ ...simple, wire: { api: "responses" } });
+ expect(result.url).toBe("https://example.invalid/v1/responses");
+ expect(result.method).toBe("POST");
+ expect(result.body.input).toBeArray();
+ expect(result.body).not.toHaveProperty("messages");
+ expect(result.body.max_output_tokens).toBe(512);
+ expect(result.body).not.toHaveProperty("max_tokens");
+});
+test.each([undefined, "/custom/responses"])("complex Responses honors apiPath %s", (apiPath) => {
+ const result = capture({
+ kind: "complex",
+ displayName: "Test",
+ transport: "openai",
+ baseUrl: "https://example.invalid",
+ apiKey: "fake",
+ apiPath,
+ wire: { api: "responses" },
+ });
+ expect(result.url).toBe(`https://example.invalid${apiPath ?? "/v1/responses"}`);
+ expect(result.body.max_output_tokens).toBe(512);
+ expect(result.body).toHaveProperty("input");
+ expect(result.body).not.toHaveProperty("messages");
+});
+test("complex Anthropic endpoint uses Messages limit without Qwen dialect", () => {
+ const { body } = capture({
+ kind: "complex",
+ displayName: "Test",
+ transport: "anthropic",
+ baseUrl: "https://example.invalid",
+ apiPath: "/v1/messages",
+ apiKey: "fake",
+ });
+ expect(body.max_tokens).toBe(512);
+ expect(body.messages).toBeArray();
+ for (const field of ["thinking", "enable_thinking", "thinking_budget", "reasoning_effort"])
+ expect(body).not.toHaveProperty(field);
+});
+test.each(["glm-5.3", "qwen3.8-max", "deepseek-v4.1-flash", "minimax-m3"])(
+ "no connection or explicit dialect infers no fields for %s",
+ (model) => {
+ const { body } = capture(undefined, model, {}, "plain");
+ for (const field of [
+ "thinking",
+ "enable_thinking",
+ "chat_template_kwargs",
+ "thinking_budget",
+ "reasoning_effort",
+ ])
+ expect(body).not.toHaveProperty(field);
+ }
+);
+test("Grok subscription profile explicitly composes GrokModelDialect", () => {
+ expect(capture(undefined, "grok-4.7", {}, "grok").adapter).toBe("GrokModelDialect");
+});
+test("unpublished OpenRouter model uses declared defaults without legacy reasoning", () => {
+ const { body } = capture(undefined, "unpublished/o3-grok-reasoning", {}, "openrouter");
+ expect(body.max_tokens).toBe(512);
+ expect(body).not.toHaveProperty("include_reasoning");
+ expect(body).not.toHaveProperty("thinking");
+});
diff --git a/packages/cli/src/providers/provider-profiles.ts b/packages/cli/src/providers/provider-profiles.ts
index c74b5b56..854e6e64 100644
--- a/packages/cli/src/providers/provider-profiles.ts
+++ b/packages/cli/src/providers/provider-profiles.ts
@@ -23,6 +23,7 @@ import { DefaultAPIFormat } from "../adapters/base-api-format.js";
import { CodexAPIFormat } from "../adapters/codex-api-format.js";
import { DevinAPIFormat } from "../adapters/devin-api-format.js";
import { GeminiAPIFormat } from "../adapters/gemini-api-format.js";
+import { GrokModelDialect } from "../adapters/grok-model-dialect.js";
import { LiteLLMAPIFormat } from "../adapters/litellm-api-format.js";
import { OllamaAPIFormat } from "../adapters/ollama-api-format.js";
import { OpenAIAPIFormat } from "../adapters/openai-api-format.js";
@@ -35,6 +36,7 @@ import { ComposedHandler } from "../handlers/composed-handler.js";
import type { ModelHandler } from "../handlers/types.js";
import { log, logStderr } from "../logger.js";
import { formatProvenanceLog, resolveCredentialProvenance } from "./api-key-provenance.js";
+import { declaredConnection, declaredWire } from "./declared-wire.js";
import { getProviderByName } from "./provider-definitions.js";
import { getRuntimeProfiles } from "./runtime-providers.js";
import { AnthropicProviderTransport } from "./transport/anthropic-compat.js";
@@ -205,6 +207,10 @@ export const grokSubscriptionProfile: ProviderProfile = {
const adapter = new OpenAIAPIFormat(ctx.modelName);
const handler = new ComposedHandler(transport, ctx.targetModel, ctx.modelName, ctx.port, {
adapter,
+ // The subscription serves Grok models only and publishes no catalog wire
+ // (its account decides what it serves), so the profile names the Grok
+ // dialect: its effort encoding with learn-on-400 recovery.
+ dialect: new GrokModelDialect(ctx.modelName, adapter.getStreamFormat()),
tokenStrategy: "delta-aware",
...ctx.sharedOpts,
});
@@ -338,9 +344,18 @@ export const litellmProfile: ProviderProfile = {
}
const transport = new LiteLLMProviderTransport(ctx.provider.baseUrl, ctx.apiKey, ctx.modelName);
const adapter = new LiteLLMAPIFormat(ctx.modelName, ctx.provider.baseUrl);
+ // LiteLLM has no catalog connection; the documented default wire applies
+ // (chat, max_tokens, no reasoning field) rather than a name-picked dialect.
+ const connection = declaredConnection(
+ "litellm",
+ ctx.modelName,
+ ctx.provider.baseUrl,
+ declaredWire("chat-completions", undefined)
+ );
const handler = new ComposedHandler(transport, ctx.targetModel, ctx.modelName, ctx.port, {
adapter,
...ctx.sharedOpts,
+ connection,
});
log(`[Proxy] Created LiteLLM handler (composed): ${ctx.modelName} (${ctx.provider.baseUrl})`);
return handler;
diff --git a/packages/cli/src/proxy-server.ts b/packages/cli/src/proxy-server.ts
index 998acb83..800765d3 100644
--- a/packages/cli/src/proxy-server.ts
+++ b/packages/cli/src/proxy-server.ts
@@ -35,6 +35,7 @@ import {
warmCatalog,
} from "./providers/catalog-client.js";
import { type ResolvedConnection, resolveConnection } from "./providers/connection-resolver.js";
+import { declaredConnection, declaredWire } from "./providers/declared-wire.js";
import { getEndpointUnavailableReason } from "./providers/endpoint-diagnostics.js";
import {
ensureEndpointsRegistered,
@@ -378,10 +379,18 @@ export async function createProxyServer(
// the transport's getHeaders() (single source of truth) — the legacy
// openrouterApiKey param is no longer the signing source.
const orProvider = new OpenRouterProviderTransport("", modelId);
- const orAdapter = new OpenRouterAPIFormat(
- modelId,
- wired.connection ? { vendor: wired.connection.vendor ?? "" } : {}
- );
+ // A model the catalog does not publish on OpenRouter still gets a wire:
+ // the documented default (chat, max_tokens, no reasoning field), never
+ // the name-picked dialect.
+ const connection =
+ wired.connection ??
+ declaredConnection(
+ "openrouter",
+ modelId,
+ "https://openrouter.ai/api/v1",
+ declaredWire("chat-completions", undefined)
+ );
+ const orAdapter = new OpenRouterAPIFormat(modelId, { vendor: connection.vendor ?? "" });
openRouterHandlers.set(
modelId,
new ComposedHandler(orProvider, modelId, modelId, port, {
@@ -389,7 +398,7 @@ export async function createProxyServer(
isInteractive: options.isInteractive,
invocationMode,
...requestShapingOpts,
- connection: wired.connection,
+ connection,
})
);
}
@@ -414,6 +423,14 @@ export async function createProxyServer(
poeHandlers.set(modelId, new RefusingHandler(wired.refusal));
return poeHandlers.get(modelId)!;
}
+ const connection =
+ wired.connection ??
+ declaredConnection(
+ "poe",
+ modelId,
+ "https://api.poe.com/v1",
+ declaredWire("chat-completions", undefined)
+ );
// The transport resolves its key through the authority in getHeaders().
const poeTransport = new PoeProvider();
poeHandlers.set(
@@ -422,7 +439,7 @@ export async function createProxyServer(
isInteractive: options.isInteractive,
invocationMode,
...requestShapingOpts,
- connection: wired.connection,
+ connection,
})
);
}