Skip to content

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

feat(routing): build catalog requests from the connection's wire

Jack Rudenkob16dbd4b707a
diff --git a/packages/cli/src/adapters/codex-api-format.ts b/packages/cli/src/adapters/codex-api-format.ts
index 9cf96d67..c336c7ff 100644
--- a/packages/cli/src/adapters/codex-api-format.ts
+++ b/packages/cli/src/adapters/codex-api-format.ts
@@ -46,6 +46,21 @@ export function normalizeCodexModel(modelId: string | undefined): string {
}
export class CodexAPIFormat extends BaseAPIFormat {
+ /**
+ * `false` builds the GENERIC Responses body every Responses connection
+ * accepts (catalog 3.7.0 R8): no `store`, no `include`. Those two are ChatGPT
+ * Codex behaviour and stay on the Codex subscription only. The output limit,
+ * reasoning and verbosity are not this body's business on a catalog
+ * connection either: the wire shaper (`ComposedHandler` step 5w) removes what
+ * is written here and writes what the connection publishes.
+ */
+ private readonly codexExtras: boolean;
+
+ constructor(modelId: string, wireFormat?: StreamFormat, options: { codexExtras?: boolean } = {}) {
+ super(modelId, wireFormat);
+ this.codexExtras = options.codexExtras ?? true;
+ }
+
processTextContent(textContent: string, _accumulatedText: string): AdapterResult {
return {
cleanedText: textContent,
@@ -98,8 +113,7 @@ export class CodexAPIFormat extends BaseAPIFormat {
model: normalizedModel,
input: strippedMessages,
stream: true,
- store: false,
- include: ["reasoning.encrypted_content"],
+ ...(this.codexExtras ? { store: false, include: ["reasoning.encrypted_content"] } : {}),
reasoning: {
effort,
summary: "auto",
diff --git a/packages/cli/src/handlers/composed-handler-wire.test.ts b/packages/cli/src/handlers/composed-handler-wire.test.ts
new file mode 100644
index 00000000..7b97a0d6
--- /dev/null
+++ b/packages/cli/src/handlers/composed-handler-wire.test.ts
@@ -0,0 +1,157 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Hono } from "hono";
+import { OpenAIAPIFormat } from "../adapters/openai-api-format.js";
+import type { DiskCacheV3 } from "../providers/all-models-cache.js";
+import { resolveConnection } from "../providers/connection-resolver.js";
+import { getProviderByName, toRemoteProvider } from "../providers/provider-definitions.js";
+import type { ProfileContext } from "../providers/provider-profiles.js";
+import { OpenAIProviderTransport } from "../providers/transport/openai.js";
+import { buildKnownWireHandler } from "../providers/wire-handler.js";
+import { wireMarkerContext } from "../providers/wire-markers.js";
+import { ComposedHandler } from "./composed-handler.js";
+import type { ModelHandler } from "./types.js";
+const cachePath = new URL(
+ "../test-fixtures/catalog-v3/wire-g-20261012101007285-7770c36e.json",
+ import.meta.url
+).pathname;
+const realFetch = globalThis.fetch;
+const handlers: ModelHandler[] = [];
+const dirs: string[] = [];
+afterEach(async () => {
+ globalThis.fetch = realFetch;
+ for (const handler of handlers.splice(0)) await handler.shutdown();
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+function context(
+ provider: string,
+ model: string,
+ sharedOpts: ProfileContext["sharedOpts"] = {}
+): ProfileContext {
+ const def = getProviderByName(provider);
+ return {
+ provider: def
+ ? toRemoteProvider(def)
+ : { name: provider, baseUrl: "", apiPath: "", apiKeyEnvVar: "", prefixes: [] },
+ modelName: model,
+ targetModel: `${provider}@${model}`,
+ apiKey: "sk-test-not-a-key",
+ port: 0,
+ catalogCachePath: cachePath,
+ sharedOpts,
+ };
+}
+function resolved(provider: string, model: string, path = cachePath) {
+ const r = resolveConnection(provider, model, path);
+ if (!r.ok || r.connection.wire.status !== "known") throw new Error("missing fixture");
+ return { ...structuredClone(r.connection), wire: structuredClone(r.connection.wire) };
+}
+function request(handler: ModelHandler) {
+ const app = new Hono();
+ app.post("/", (c) =>
+ handler.handle(c, {
+ model: "x",
+ stream: true,
+ max_tokens: 32000,
+ messages: [{ role: "user", content: "hello" }],
+ output_config: { effort: "high" },
+ })
+ );
+ return app.request("/", { method: "POST" });
+}
+function capture(error: string) {
+ const calls: Array<{ body: any; headers: Headers }> = [];
+ globalThis.fetch = (async (_url, init) => {
+ calls.push({ body: JSON.parse(String(init?.body)), headers: new Headers(init?.headers) });
+ // Returning the same rejection again proves recovery is attempted only once.
+ return new Response(JSON.stringify({ error: { message: error } }), { status: 400 });
+ }) as typeof fetch;
+ return calls;
+}
+test("borrowed field rejection retries exactly once and preserves other decisions", async () => {
+ const c = resolved("opencode-zen", "minimax-m3");
+ const handler = buildKnownWireHandler(
+ context("opencode-zen", "minimax-m3"),
+ "opencode-zen",
+ c,
+ c.wire
+ )!;
+ handlers.push(handler);
+ const calls = capture("Unsupported parameter: 'max_completion_tokens'");
+ await request(handler);
+ expect(calls).toHaveLength(2);
+ expect(calls[0]!.body.max_completion_tokens).toBe(32000);
+ expect(calls[1]!.body).not.toHaveProperty("max_completion_tokens");
+ expect(calls[1]!.body.thinking).toEqual({ type: "adaptive" });
+ const first = structuredClone(calls[0]!.body);
+ delete first.max_completion_tokens;
+ expect(calls[1]!.body).toEqual(first);
+});
+test("wire beta header survives parameter recovery header refresh", async () => {
+ const original = resolved("anthropic", "claude-opus-5-5");
+ // One unknown sub-field enables borrowing; all encodings and headers remain
+ // those of the real fixture. Pass its original wire as the owner test seam.
+ const cache: DiskCacheV3 = JSON.parse(readFileSync(cachePath, "utf8"));
+ const published = cache.entries
+ .find((e) => e.modelId === original.modelId)!
+ .aggregators!.find(
+ (c) => c.route?.routeId === "anthropic" && c.route.routeProfileId === "direct-api"
+ )!;
+ if (published.wire?.status !== "known") throw new Error("missing fixture wire");
+ published.wire.tokenParam = { status: "unknown" };
+ const dir = mkdtempSync(join(tmpdir(), "composed-wire-"));
+ dirs.push(dir);
+ const path = join(dir, "catalog.json");
+ writeFileSync(path, JSON.stringify(cache));
+ const c = resolved("anthropic", "claude-opus-5-5", path);
+ c.ownerWire = original.wire;
+ const handler = buildKnownWireHandler(
+ context("anthropic", "claude-opus-5-5", { wireSpeed: "fast" }),
+ "anthropic",
+ c,
+ c.wire
+ )!;
+ handlers.push(handler);
+ const calls = capture("Unsupported parameter: 'max_tokens'");
+ await request(handler);
+ expect(calls).toHaveLength(2);
+ expect(calls[0]!.body.max_tokens).toBe(32000);
+ expect(calls[1]!.body).not.toHaveProperty("max_tokens");
+ for (const call of calls) {
+ expect(call.headers.get("anthropic-beta")?.split(",")).toContain("fast-mode-2026-02-01");
+ expect(call.body.speed).toBe("fast");
+ expect(call.body.output_config.effort).toBe("high");
+ }
+});
+test("marker without connection refuses before fetch", async () => {
+ const ctx = context("openai", "gpt-6.1-sol");
+ const handler = new ComposedHandler(
+ new OpenAIProviderTransport(ctx.provider, ctx.modelName, ctx.apiKey),
+ ctx.targetModel,
+ ctx.modelName,
+ 0,
+ { adapter: new OpenAIAPIFormat(ctx.modelName) }
+ );
+ handlers.push(handler);
+ const calls = capture("unexpected fetch");
+ const response = await wireMarkerContext.run({ spec: ctx.targetModel, speed: "fast" }, () =>
+ request(handler)
+ );
+ expect(response.status).toBe(400);
+ expect(await response.text()).toContain("has no catalog wire");
+ expect(calls).toHaveLength(0);
+});
+test("request marker context sends priority on OpenAI", async () => {
+ const c = resolved("openai", "gpt-6.1-sol");
+ const handler = buildKnownWireHandler(context("openai", "gpt-6.1-sol"), "openai", c, c.wire)!;
+ handlers.push(handler);
+ const calls = capture("invalid value");
+ await wireMarkerContext.run({ spec: "[email protected]", speed: "fast" }, () =>
+ request(handler)
+ );
+ expect(calls).toHaveLength(1);
+ expect(calls[0]!.body.service_tier).toBe("priority");
+ expect(wireMarkerContext.getStore()).toBeUndefined();
+});
diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.ts
index f9694841..c1f4406c 100644
--- a/packages/cli/src/handlers/composed-handler.ts
+++ b/packages/cli/src/handlers/composed-handler.ts
@@ -43,8 +43,20 @@ import {
} from "../logger.js";
import { GeminiThoughtSignatureMiddleware, MiddlewareManager } from "../middleware/index.js";
import { deepMergeParams } from "../model-params.js";
+import type { ResolvedConnection } from "../providers/connection-resolver.js";
+import type { WireHeader } from "../providers/connection-wire.js";
import { describeSiblingKeys, getProviderByName } from "../providers/provider-definitions.js";
import { isTerminal429 } from "../providers/transport/openai.js";
+import { wireMarkerContext } from "../providers/wire-markers.js";
+import {
+ type WireChoices,
+ type WireMode,
+ type WireSpeed,
+ mergeWireHeaders,
+ recoverBorrowedWireFields,
+ shapeRequestFromWire,
+ wireChoicesFromClaudeRequest,
+} from "../providers/wire-request.js";
import { recoveryClock } from "../recovery/clock.js";
import {
type RecoveryOutcome,
@@ -59,7 +71,7 @@ import {
describeImages,
} from "../services/vision-proxy.js";
import { type SessionEventRegistry, extractSessionId } from "../session-events/index.js";
-import { applyProInjection } from "../session-events/pro-injection.js";
+import { applyProInjection, isUltracodeMainTurn } from "../session-events/pro-injection.js";
import type { StatsEvent } from "../stats-otlp.js";
import { recordStats } from "../stats.js";
import { classifyError, reportError } from "../telemetry.js";
@@ -199,6 +211,16 @@ export interface ComposedHandlerOptions {
* Defaults to ~/.claudish/cloud-models-catalog-v3.json. Only tests should pass this.
*/
catalogCachePath?: string;
+ /**
+ * The catalog connection this handler calls, with its `wire` (catalog 3.7.0).
+ * When its wire is known, step 5w shapes the output limit, reasoning, mode and
+ * speed from it alone, after every adapter and dialect has run.
+ */
+ connection?: ResolvedConnection;
+ /** `+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. */
+ wireSpeed?: WireSpeed;
}
export class ComposedHandler implements ModelHandler {
@@ -1102,7 +1124,72 @@ export class ComposedHandler implements ModelHandler {
// (transformPayload) on purpose: after, so they beat every adapter default;
// before, so they write into the payload itself rather than into a
// provider envelope that 5c may wrap around it.
- if (this.options.proOnUltracode) {
+ // 5w. A known catalog wire decides the output limit, reasoning, mode and
+ // speed — nothing else does. It runs after every adapter and dialect (it
+ // removes whatever they emitted for those decisions) and before
+ // --model-params, which stays the user's last word.
+ let wireHeaders: WireHeader[] = [];
+ let wireBorrowed: string[] = [];
+ const wire = this.options.connection?.wire;
+ if (wire?.status === "known") {
+ const choices: WireChoices = {
+ ...wireChoicesFromClaudeRequest(claudeRequest, this.options.effortOverride),
+ };
+ const markers = wireMarkerContext.getStore();
+ const wireMode = this.options.wireMode ?? markers?.mode;
+ const wireSpeed = this.options.wireSpeed ?? markers?.speed;
+ if (wireMode) {
+ choices.mode = { value: wireMode, explicit: true };
+ } else if (
+ this.options.proOnUltracode &&
+ isUltracodeMainTurn({
+ enabled: true,
+ sessionId: extractSessionId(claudeRequest?.metadata),
+ outputConfig: claudeRequest?.output_config,
+ registry: this.options.sessionEventRegistry,
+ })
+ ) {
+ choices.mode = { value: "pro", explicit: false };
+ }
+ if (wireSpeed) choices.speed = { value: wireSpeed, explicit: true };
+
+ const shaped = shapeRequestFromWire(
+ requestPayload,
+ wire,
+ choices,
+ this.options.connection?.ownerWire
+ );
+ wireBorrowed = shaped.borrowed;
+ const where = `${this.options.connection?.route.routeId}/${this.options.connection?.route.routeProfileId} · ${this.options.connection?.externalModelId}`;
+ for (const note of shaped.notes) log(`[Wire] ${where}: ${note}`);
+ if (shaped.refusal) {
+ return c.json(
+ wrapAnthropicError(
+ 400,
+ `claudish: ${shaped.refusal} (${where})`,
+ "invalid_request_error"
+ ),
+ 400 as any
+ );
+ }
+ wireHeaders = shaped.headers;
+ } else if (
+ this.options.wireMode ||
+ this.options.wireSpeed ||
+ wireMarkerContext.getStore()?.mode ||
+ wireMarkerContext.getStore()?.speed
+ ) {
+ // A marker asks for something only a connection's wire can grant; without
+ // one there is nothing that says how, or whether, to send it.
+ return c.json(
+ wrapAnthropicError(
+ 400,
+ `claudish: ${this.targetModel} has no catalog wire, so a +mode or #speed marker cannot be applied`,
+ "invalid_request_error"
+ ),
+ 400 as any
+ );
+ } else if (this.options.proOnUltracode) {
applyProInjection(requestPayload, {
enabled: true,
sessionId: extractSessionId(claudeRequest?.metadata),
@@ -1256,9 +1343,16 @@ export class ComposedHandler implements ModelHandler {
// no FallbackHandler exists — `proxy-server.ts`'s bare 500.
//
// The touch is refresh-conditional, which makes this rare, not safe.
+ // Every header fetch below goes through this, so a header the wire requires
+ // (a beta token next to the field it wrote) survives the auth retries too.
+ const fetchHeaders = async (): Promise<Record<string, string>> => {
+ const fetched = await this.provider.getHeaders(payload);
+ mergeWireHeaders(fetched, wireHeaders);
+ return fetched;
+ };
let headers: Record<string, string>;
try {
- headers = await this.provider.getHeaders(payload);
+ headers = await fetchHeaders();
} catch (err: any) {
const conn = classifyConnectionError(err);
if (!conn) {
@@ -1270,7 +1364,7 @@ export class ComposedHandler implements ModelHandler {
err,
conn,
this.connectionEndpointFor(err, endpoint),
- () => this.provider.getHeaders(),
+ fetchHeaders,
{
startTime,
// An auth site with the unclamped primary fetch still ahead of it —
@@ -1474,9 +1568,18 @@ export class ComposedHandler implements ModelHandler {
const candidates = [this.modelAdapter, this.getAdapter()].filter(
(a, i, all): a is BaseModelAdapter => !!a?.recoverFromRejection && all.indexOf(a) === i
);
- const errorText = candidates.length > 0 ? await response.clone().text() : "";
- let recovery: { payload: any; note: string } | null = null;
- for (const candidate of candidates) {
+ const errorText =
+ candidates.length > 0 || wireBorrowed.length > 0 ? await response.clone().text() : "";
+ // Fields borrowed from the owner's connection (this connection's own
+ // value is unknown) are the first suspects: tried in turn, dropped on the
+ // 400 that names them. Only those fields — never one the wire published.
+ let recovery: { payload: any; note: string } | null = recoverBorrowedWireFields(
+ requestPayload,
+ wireBorrowed,
+ errorText
+ );
+ if (recovery) wireBorrowed = [];
+ for (const candidate of recovery ? [] : candidates) {
recovery = candidate.recoverFromRejection(requestPayload, errorText);
if (recovery) break;
}
@@ -1499,7 +1602,7 @@ export class ComposedHandler implements ModelHandler {
// UNCLASSIFIED throw is rethrown unchanged, so the existing 500 route
// out of here is untouched.
const doParamRetry = async (sig?: AbortSignal): Promise<Response> => {
- const retryHeaders = await this.provider.getHeaders(payload);
+ const retryHeaders = await fetchHeaders();
retryHeaders["Content-Type"] = retrySerialized?.contentType ?? "application/json";
return fetch(
endpoint,
@@ -1565,7 +1668,7 @@ export class ComposedHandler implements ModelHandler {
// leave the other exactly as exposed as it was.
const doAuthRetry = async (sig?: AbortSignal): Promise<Response> => {
await this.provider.forceRefreshAuth!();
- const retryHeaders = await this.provider.getHeaders(payload);
+ const retryHeaders = await fetchHeaders();
// Same serialization as the primary request — this is a separate call
// site and the easy one to forget, which is why both are pinned by
// the same assertion.
diff --git a/packages/cli/src/providers/model-parser.test.ts b/packages/cli/src/providers/model-parser.test.ts
new file mode 100644
index 00000000..786bbee0
--- /dev/null
+++ b/packages/cli/src/providers/model-parser.test.ts
@@ -0,0 +1,28 @@
+import { expect, test } from "bun:test";
+import { parseModelChain, parseModelSpec } from "./model-parser.js";
+
+test.each([
+ ["cx@gpt-6-sol+pro", ["cx@gpt-6-sol+pro"]],
+ ["a@x+pro#fast+b@y", ["a@x+pro#fast", "b@y"]],
+ ["a@x+standard:3+b@y", ["a@x+standard:3", "b@y"]],
+ ["a@x+b@y", ["a@x", "b@y"]],
+ [" a@x + b@y + ", ["a@x", "b@y"]],
+ ["a@x", ["a@x"]],
+ ["", [""]],
+] as const)("parses chain %s", (input, expected) =>
+ expect(parseModelChain(input)).toEqual([...expected])
+);
+test("parses provider shortcut and strips mode and speed", () => {
+ expect(parseModelSpec("oai@gpt-6-sol+pro#fast")).toMatchObject({
+ provider: "openai",
+ model: "gpt-6-sol",
+ mode: "pro",
+ speed: "fast",
+ });
+});
+test("invalid marker remains part of the model", () => {
+ const parsed = parseModelSpec("oai@gpt-6-sol+typo");
+ expect(parsed.model).toBe("gpt-6-sol+typo");
+ expect(parsed.mode).toBeUndefined();
+ expect(parsed.speed).toBeUndefined();
+});
diff --git a/packages/cli/src/providers/model-parser.ts b/packages/cli/src/providers/model-parser.ts
index b9c3b038..8e4c0686 100644
--- a/packages/cli/src/providers/model-parser.ts
+++ b/packages/cli/src/providers/model-parser.ts
@@ -66,6 +66,10 @@ export interface ParsedModel {
isLegacySyntax: boolean;
/** Whether provider was explicitly specified (vs auto-detected) */
isExplicitProvider: boolean;
+ /** `+pro` / `+standard` on the spec (removed from `model`). See `wire-markers.ts`. */
+ mode?: WireMode;
+ /** `#<speed>` on the spec (removed from `model`). */
+ speed?: WireSpeed;
}
/**
@@ -80,6 +84,8 @@ import {
isDirectApiProvider as _isDirectApiProvider,
isLocalTransport,
} from "./provider-definitions.js";
+import { type WireMarkers, splitWireMarkers } from "./wire-markers.js";
+import type { WireMode, WireSpeed } from "./wire-request.js";
export const PROVIDER_SHORTCUTS: Record<string, string> = _getShortcuts();
@@ -148,9 +154,23 @@ export function parseModelChain(modelSpec: string): string[] {
.split(MODEL_CHAIN_SEPARATOR)
.map((s) => s.trim())
.filter(Boolean);
- return parts.length > 0 ? parts : [modelSpec];
+ // `+` also marks a request mode (`cx@gpt-6-sol+pro`, see `wire-markers.ts`).
+ // A segment that is ONLY a mode word, optionally followed by `#<speed>` or
+ // `:N`, is that marker on the spec before it, never a chain element: every
+ // element a chain carries is an explicit `provider@model` spec.
+ const merged: string[] = [];
+ for (const part of parts) {
+ if (merged.length > 0 && MODE_MARKER_SEGMENT.test(part)) {
+ merged[merged.length - 1] = `${merged[merged.length - 1]}+${part}`;
+ } else {
+ merged.push(part);
+ }
+ }
+ return merged.length > 0 ? merged : [modelSpec];
}
+const MODE_MARKER_SEGMENT = /^(pro|standard)(#[a-z]+)?(:\d+)?$/i;
+
/**
* Parse a model specification string
*
@@ -166,6 +186,29 @@ export function parseModelChain(modelSpec: string): string[] {
* @returns Parsed model information
*/
export function parseModelSpec(modelSpec: string): ParsedModel {
+ // Mode and speed markers are not part of any model id: strip them first, so
+ // every consumer (routing, --probe, validation) sees the model alone. An
+ // invalid marker is left in place and fails as an unknown model, or is
+ // refused with its own message by the proxy, which splits markers strictly.
+ let markers: WireMarkers | undefined;
+ try {
+ markers = splitWireMarkers(modelSpec);
+ } catch {
+ markers = undefined;
+ }
+ if (markers && (markers.mode || markers.speed)) {
+ const parsed = parseModelSpecWithoutMarkers(markers.spec);
+ return {
+ ...parsed,
+ original: modelSpec,
+ ...(markers.mode ? { mode: markers.mode } : {}),
+ ...(markers.speed ? { speed: markers.speed } : {}),
+ };
+ }
+ return parseModelSpecWithoutMarkers(modelSpec);
+}
+
+function parseModelSpecWithoutMarkers(modelSpec: string): ParsedModel {
const original = modelSpec;
// Check for URL-style model (http:// or https://)
diff --git a/packages/cli/src/providers/provider-profiles.ts b/packages/cli/src/providers/provider-profiles.ts
index 742b6f2a..3b9f3841 100644
--- a/packages/cli/src/providers/provider-profiles.ts
+++ b/packages/cli/src/providers/provider-profiles.ts
@@ -50,6 +50,7 @@ import { OpenAIProviderTransport } from "./transport/openai.js";
import { OpenCodeZenMessagesTransport, OpenCodeZenTransport } from "./transport/opencode-zen.js";
import { PoeProvider } from "./transport/poe.js";
import { VertexProviderTransport, parseVertexModel } from "./transport/vertex-oauth.js";
+import { RefusingHandler, buildWireHandler } from "./wire-handler.js";
// ---------------------------------------------------------------------------
// Types
@@ -91,7 +92,13 @@ export interface ProfileContext {
*/
sharedOpts: Pick<
ComposedHandlerOptions,
- "isInteractive" | "invocationMode" | "effortOverride" | "modelParams" | "proOnUltracode"
+ | "isInteractive"
+ | "invocationMode"
+ | "effortOverride"
+ | "modelParams"
+ | "proOnUltracode"
+ | "wireMode"
+ | "wireSpeed"
>;
}
@@ -593,5 +600,17 @@ export async function createHandlerForProvider(ctx: ProfileContext): Promise<Mod
}
log(`[Proxy] Handler: provider=${ctx.provider.name}, model=${ctx.modelName}`);
+ // A catalog connection is built from its wire and the route registry; the
+ // provider's own profile only for providers the catalog does not route.
+ const wired = await buildWireHandler(ctx, definitionName);
+ switch (wired.kind) {
+ case "handler":
+ return wired.handler;
+ case "refused":
+ return new RefusingHandler(wired.message);
+ case "not-wire-routed":
+ break;
+ }
+
return factory(ctx);
}
diff --git a/packages/cli/src/providers/transport/openai-codex.ts b/packages/cli/src/providers/transport/openai-codex.ts
index 485337f5..225af8b0 100644
--- a/packages/cli/src/providers/transport/openai-codex.ts
+++ b/packages/cli/src/providers/transport/openai-codex.ts
@@ -121,6 +121,14 @@ export class OpenAICodexTransport extends OpenAIProviderTransport {
prompt_cache_key:
normalizedPayload.prompt_cache_key ?? this.resolvePromptCacheKey(claudeRequest),
};
+ // The reasoning summary is what Claude Code shows as thinking. The
+ // catalog wire does not publish it, so the wire shaper drops it with the
+ // rest of `reasoning`; it is a Codex display field, restored here only
+ // where reasoning was actually sent.
+ const reasoning = normalizedPayload.reasoning;
+ if (reasoning && typeof reasoning === "object" && reasoning.summary === undefined) {
+ normalizedPayload = { ...normalizedPayload, reasoning: { ...reasoning, summary: "auto" } };
+ }
}
// Auth-derived store:false / include reasoning bits, only under OAuth.
return this.cachedAuth?.transformPayload?.(normalizedPayload) ?? normalizedPayload;
diff --git a/packages/cli/src/providers/wire-handler.test.ts b/packages/cli/src/providers/wire-handler.test.ts
new file mode 100644
index 00000000..0f62d6eb
--- /dev/null
+++ b/packages/cli/src/providers/wire-handler.test.ts
@@ -0,0 +1,421 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Hono } from "hono";
+import type { DiskCacheV3 } from "./all-models-cache.js";
+import { connectionRequestUrl, resolveConnection } from "./connection-resolver.js";
+import { getProviderByName, toRemoteProvider } from "./provider-definitions.js";
+import type { ProfileContext } from "./provider-profiles.js";
+import { RefusingHandler, buildWireHandler, effectiveBaseUrl } from "./wire-handler.js";
+import { TryInTurnHandler } from "./wire-try-in-turn.js";
+const cachePath = new URL(
+ "../test-fixtures/catalog-v3/wire-g-20261012101007285-7770c36e.json",
+ import.meta.url
+).pathname;
+const fixture: DiskCacheV3 = JSON.parse(readFileSync(cachePath, "utf8"));
+const realFetch = globalThis.fetch;
+const dirs: string[] = [];
+afterEach(() => {
+ globalThis.fetch = realFetch;
+ for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+function context(
+ provider: string,
+ model: string,
+ sharedOpts: ProfileContext["sharedOpts"] = {},
+ path = cachePath
+): ProfileContext {
+ const def = getProviderByName(provider);
+ return {
+ provider: def
+ ? toRemoteProvider(def)
+ : { name: provider, baseUrl: "", apiPath: "", apiKeyEnvVar: "", prefixes: [] },
+ modelName: model,
+ targetModel: `${provider}@${model}`,
+ apiKey: "sk-test-not-a-key",
+ port: 0,
+ catalogCachePath: path,
+ sharedOpts,
+ };
+}
+function request(over: Record<string, unknown> = {}) {
+ return {
+ model: "x",
+ max_tokens: 32000,
+ stream: true,
+ messages: [{ role: "user", content: "Read README.md" }],
+ tools: [
+ {
+ name: "Read",
+ description: "Read a file",
+ input_schema: {
+ type: "object",
+ properties: { path: { type: "string" } },
+ required: ["path"],
+ },
+ },
+ ],
+ thinking: { type: "adaptive" },
+ output_config: { effort: "high" },
+ ...over,
+ };
+}
+function temporary(cache: DiskCacheV3) {
+ const dir = mkdtempSync(join(tmpdir(), "wire-handler-"));
+ dirs.push(dir);
+ const path = join(dir, "catalog.json");
+ writeFileSync(path, JSON.stringify(cache));
+ return path;
+}
+const cases = [
+ {
+ provider: "openai",
+ model: "gpt-6.1-sol",
+ url: "https://api.openai.com/v1/responses",
+ expected: {
+ max_output_tokens: 32000,
+ reasoning: {
+ effort: "high",
+ },
+ },
+ absent: ["store", "include", "text", "reasoning_effort"],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "openai",
+ model: "gpt-6.1-sol",
+ url: "https://api.openai.com/v1/responses",
+ expected: {
+ max_output_tokens: 32000,
+ reasoning: {
+ effort: "high",
+ mode: "pro",
+ },
+ service_tier: "priority",
+ },
+ absent: ["store", "include", "text", "reasoning_effort"],
+ opts: {
+ wireMode: "pro",
+ wireSpeed: "fast",
+ },
+ req: {},
+ },
+ {
+ provider: "openai",
+ model: "gpt-6.1-sol",
+ url: "https://api.openai.com/v1/responses",
+ expected: {
+ reasoning: {
+ effort: "low",
+ },
+ max_output_tokens: 32000,
+ },
+ absent: ["reasoning_effort"],
+ opts: {},
+ req: {
+ output_config: {
+ effort: "minimal",
+ },
+ },
+ },
+ {
+ provider: "openrouter",
+ model: "openai/gpt-6.1-sol",
+ url: "https://openrouter.ai/api/v1/chat/completions",
+ expected: {
+ max_tokens: 32000,
+ reasoning: {
+ enabled: true,
+ effort: "high",
+ },
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "opencode-zen-go",
+ model: "grok-4.7",
+ url: "https://opencode.ai/zen/go/v1/responses",
+ expected: {
+ max_output_tokens: 32000,
+ reasoning: {
+ effort: "high",
+ },
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "opencode-zen-go",
+ model: "minimax-m3",
+ url: "https://opencode.ai/zen/go/v1/messages",
+ expected: {
+ max_tokens: 32000,
+ },
+ absent: ["thinking"],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "opencode-zen",
+ model: "minimax-m3",
+ url: "https://opencode.ai/zen/v1/chat/completions",
+ expected: {
+ max_completion_tokens: 32000,
+ thinking: {
+ type: "adaptive",
+ },
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "z-ai",
+ model: "glm-5.3",
+ url: "https://api.z.ai/api/paas/v4/chat/completions",
+ expected: {
+ max_tokens: 32000,
+ thinking: {
+ type: "enabled",
+ },
+ reasoning_effort: "high",
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "kimi-coding",
+ model: "k3",
+ url: "https://api.kimi.ai/coding/v1/chat/completions",
+ expected: {
+ max_completion_tokens: 32000,
+ reasoning_effort: "low",
+ },
+ absent: [],
+ opts: {},
+ req: {
+ thinking: {
+ type: "disabled",
+ },
+ output_config: null,
+ },
+ },
+ {
+ provider: "ollamacloud",
+ model: "kimi-k3",
+ url: "https://ollama.com/v1/chat/completions",
+ expected: {
+ max_tokens: 32000,
+ reasoning_effort: "high",
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "qwen-token-plan",
+ model: "qwen3.7-plus",
+ url: "https://token-plan.maas.qwencloudapi.com/compatible-mode/v1/chat/completions",
+ expected: {
+ max_completion_tokens: 32000,
+ enable_thinking: true,
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "fireworks",
+ model: "accounts/fireworks/models/qwen3p8-max",
+ url: "https://api.fireworks.ai/inference/v1/chat/completions",
+ expected: {
+ max_tokens: 32000,
+ },
+ absent: ["reasoning", "reasoning_effort", "thinking", "enable_thinking"],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "google",
+ model: "gemini-3.8-flash",
+ url: "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse",
+ expected: {
+ "generationConfig.maxOutputTokens": 32000,
+ },
+ absent: ["generationConfig.thinkingConfig", "thinkingConfig"],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "anthropic",
+ model: "claude-opus-5-5",
+ url: "https://api.anthropic.com/v1/messages",
+ expected: {
+ max_tokens: 32000,
+ "output_config.effort": "high",
+ speed: "fast",
+ },
+ absent: ["thinking"],
+ opts: {
+ wireSpeed: "fast",
+ },
+ req: {},
+ },
+];
+
+for (const [index, tc] of cases.entries())
+ test(`capture ${index}: ${tc.provider}@${tc.model}`, async () => {
+ const captures: Array<{ url: string; body: any; headers: Headers }> = [];
+ globalThis.fetch = (async (url: Parameters<typeof fetch>[0], init?: RequestInit) => {
+ captures.push({
+ url: String(url),
+ body: JSON.parse(String(init?.body)),
+ headers: new Headers(init?.headers),
+ });
+ return new Response("capture complete", { status: 599 });
+ }) as unknown as typeof fetch;
+ const resolved = resolveConnection(tc.provider, tc.model, cachePath);
+ if (!resolved.ok || resolved.connection.wire.status !== "known")
+ throw new Error("fixture connection missing");
+ expect(connectionRequestUrl(resolved.connection, resolved.connection.wire.api)).toBe(tc.url);
+ const outcome = await buildWireHandler(
+ context(tc.provider, tc.model, tc.opts as ProfileContext["sharedOpts"]),
+ tc.provider
+ );
+ if (outcome.kind !== "handler") throw new Error(JSON.stringify(outcome));
+ try {
+ const app = new Hono();
+ app.post("/", async (c) => outcome.handler.handle(c, await c.req.json()));
+ await app.request("/", {
+ method: "POST",
+ body: JSON.stringify(request(tc.req)),
+ headers: { "content-type": "application/json" },
+ });
+ expect(captures).toHaveLength(1);
+ const capture = captures[0]!;
+ expect(capture.url).toBe(tc.url);
+ for (const [key, value] of Object.entries(tc.expected))
+ expect(capture.body).toHaveProperty(key, value);
+ for (const key of tc.absent) expect(capture.body).not.toHaveProperty(key);
+ for (const key of ["max_tokens", "max_completion_tokens", "max_output_tokens"]) {
+ if (!(key in tc.expected)) expect(capture.body).not.toHaveProperty(key);
+ }
+ if (tc.provider.startsWith("opencode"))
+ expect(capture.headers.get("x-opencode-session")).toBeTruthy();
+ if (tc.provider === "opencode-zen-go" && tc.model === "minimax-m3") {
+ expect(capture.headers.get("x-api-key")).toBe("sk-test-not-a-key");
+ expect(capture.headers.get("anthropic-version")).toBe("2023-06-01");
+ }
+ if (tc.provider === "anthropic")
+ expect(capture.headers.get("anthropic-beta")?.split(",")).toContain("fast-mode-2026-02-01");
+ if (tc.provider === "ollamacloud") {
+ expect(capture.body.model).toBe("kimi-k3");
+ expect(capture.body.tools).toHaveLength(1);
+ }
+ } finally {
+ await outcome.handler.shutdown();
+ }
+ });
+test("xAI refuses fast with offered values before fetch", async () => {
+ let calls = 0;
+ globalThis.fetch = (async () => {
+ calls++;
+ return new Response("unexpected", { status: 599 });
+ }) as unknown as typeof fetch;
+ const outcome = await buildWireHandler(
+ context("x-ai", "grok-4.7", { wireSpeed: "fast" }),
+ "x-ai"
+ );
+ if (outcome.kind !== "handler") throw new Error("expected handler");
+ try {
+ const app = new Hono();
+ app.post("/", (c) => outcome.handler.handle(c, request()));
+ const response = await app.request("/", { method: "POST" });
+ expect(response.status).toBe(400);
+ expect(await response.text()).toContain("standard, priority");
+ expect(calls).toBe(0);
+ } finally {
+ await outcome.handler.shutdown();
+ }
+});
+test("unsupported realtime wire refuses with its protocol", async () => {
+ // No claudish provider binds realtime-websocket. Move only this connection's
+ // binding to the token-plan test route so the real resolver can select it.
+ const cache = structuredClone(fixture);
+ const entry = cache.entries.find((e) => e.modelId === "qwen3.8-omni-flash-realtime")!;
+ const connection = entry.aggregators!.find((c) => c.wire?.status === "unsupported")!;
+ expect(connection.wire).toMatchObject({
+ status: "unsupported",
+ protocol: "dashscope-realtime-websocket",
+ });
+ connection.route = { routeId: "qwen", routeProfileId: "qwencloud-token-plan" };
+ const path = temporary(cache);
+ const resolved = resolveConnection("qwen-token-plan", entry.modelId, path);
+ expect(resolved).toMatchObject({ ok: true, connection: { wire: connection.wire } });
+ const result = await buildWireHandler(
+ context("qwen-token-plan", entry.modelId, {}, path),
+ "qwen-token-plan"
+ );
+ expect(result).toMatchObject({ kind: "refused" });
+ if (result.kind !== "refused") throw new Error("expected refusal");
+ expect(result.message).toContain("dashscope-realtime-websocket");
+});
+test("unknown mai wire builds TryInTurnHandler", async () => {
+ expect(resolveConnection("openrouter", "mai-voice-2.1", cachePath)).toMatchObject({
+ ok: true,
+ connection: { wire: { status: "unknown" } },
+ });
+ const result = await buildWireHandler(context("openrouter", "mai-voice-2.1"), "openrouter");
+ if (result.kind !== "handler") throw new Error("expected handler");
+ expect(result.handler).toBeInstanceOf(TryInTurnHandler);
+ await result.handler.shutdown();
+});
+test("provider with no route binding is not wire routed", async () => {
+ expect(await buildWireHandler(context("ollama", "local-model"), "ollama")).toEqual({
+ kind: "not-wire-routed",
+ });
+});
+test("explicit cache without registry refuses without refreshing or fetching", async () => {
+ let calls = 0;
+ globalThis.fetch = (async () => {
+ calls++;
+ return new Response("unexpected", { status: 599 });
+ }) as unknown as typeof fetch;
+ const cache = structuredClone(fixture);
+ delete cache.routeRegistry;
+ const result = await buildWireHandler(
+ context("openai", "gpt-6.1-sol", {}, temporary(cache)),
+ "openai"
+ );
+ expect(result.kind).toBe("refused");
+ if (result.kind !== "refused") throw new Error("expected refusal");
+ expect(result.message).toContain("route registry");
+ expect(calls).toBe(0);
+});
+test.each([
+ [undefined, { baseUrl: "https://registry.test/anthropic/v1", overridden: false }],
+ [
+ "https://definition.test/v1",
+ { baseUrl: "https://registry.test/anthropic/v1", overridden: false },
+ ],
+ ["https://override.test", { baseUrl: "https://override.test/anthropic/v1", overridden: true }],
+ ["https://override.test/custom/", { baseUrl: "https://override.test/custom", overridden: true }],
+] as const)("effective base URL %s", (override, expected) =>
+ expect(
+ effectiveBaseUrl("https://registry.test/anthropic/v1", "https://definition.test/v1", override)
+ ).toEqual(expected)
+);
+test("RefusingHandler returns 400 and supplied message", async () => {
+ const response = await new RefusingHandler("unsupported protocol").handle();
+ expect(response.status).toBe(400);
+ expect(await response.json()).toMatchObject({
+ type: "error",
+ error: { type: "invalid_request_error", message: "claudish: unsupported protocol" },
+ });
+});
diff --git a/packages/cli/src/providers/wire-handler.ts b/packages/cli/src/providers/wire-handler.ts
new file mode 100644
index 00000000..3ede4d29
--- /dev/null
+++ b/packages/cli/src/providers/wire-handler.ts
@@ -0,0 +1,293 @@
+/**
+ * Build the handler for a catalog connection from its `wire` and the route
+ * registry (catalog 3.7.0): the API comes from `wire.api`, the URL from the
+ * registry, and each request's output limit, reasoning, mode and speed from the
+ * wire (`ComposedHandler` step 5w). A provider's own transport is kept only for
+ * what is the provider's: authentication, identity headers and extra fields.
+ *
+ * Out of scope, and left to their own profiles: the dynamic subscriptions
+ * (`gk@`, `ag@`, `dv@`), whose account decides what they serve and whose
+ * connections the catalog publishes as `unknown`; Vertex, whose project is the
+ * user's; and every provider without a route binding (local, LiteLLM, custom
+ * endpoints).
+ */
+import { AnthropicAPIFormat } from "../adapters/anthropic-api-format.js";
+import type { BaseAPIFormat } from "../adapters/base-api-format.js";
+import { CodexAPIFormat } from "../adapters/codex-api-format.js";
+import { GeminiAPIFormat } from "../adapters/gemini-api-format.js";
+import { OpenAIAPIFormat } from "../adapters/openai-api-format.js";
+import { ComposedHandler } from "../handlers/composed-handler.js";
+import { wrapAnthropicError } from "../handlers/shared/anthropic-error.js";
+import type { RemoteProvider } from "../handlers/shared/remote-provider-types.js";
+import type { ModelHandler } from "../handlers/types.js";
+import { log } from "../logger.js";
+import { ensureRouteRegistryReady } from "./catalog-client.js";
+import {
+ type ResolvedConnection,
+ connectionBaseUrl,
+ resolveConnection,
+ resolveRouteProfile,
+} from "./connection-resolver.js";
+import { type KnownWire, type WireApi, wireRequestUrl } from "./connection-wire.js";
+import { getProviderByName } from "./provider-definitions.js";
+import type { ProfileContext } from "./provider-profiles.js";
+import { AnthropicProviderTransport } from "./transport/anthropic-compat.js";
+import { GeminiProviderTransport } from "./transport/gemini-apikey.js";
+import { OpenAICodexTransport } from "./transport/openai-codex.js";
+import { OpenAIProviderTransport } from "./transport/openai.js";
+import { OpenCodeZenMessagesTransport, OpenCodeZenTransport } from "./transport/opencode-zen.js";
+import { OpenRouterProviderTransport } from "./transport/openrouter.js";
+import { PoeProvider } from "./transport/poe.js";
+import type { ProviderTransport } from "./transport/types.js";
+import { TryInTurnHandler, apiOnlyWire } from "./wire-try-in-turn.js";
+
+/** Providers whose requests are NOT built from catalog wires (see the header). */
+const NOT_WIRE_ROUTED = new Set(["grok-subscription", "antigravity", "devin", "vertex"]);
+
+const OPENCODE = new Set(["opencode-zen", "opencode-zen-go"]);
+
+/**
+ * The base URL a request goes to: the registry's, unless the user overrode the
+ * provider's base URL (env or config), which is kept and logged. An override
+ * with no path keeps the registry's path (`https://api.minimaxi.com` +
+ * `/anthropic/v1`); one with a path is used as the whole base.
+ */
+export function effectiveBaseUrl(
+ registryBaseUrl: string,
+ definitionBaseUrl: string | undefined,
+ resolvedBaseUrl: string | undefined
+): { baseUrl: string; overridden: boolean } {
+ if (!resolvedBaseUrl || !definitionBaseUrl || resolvedBaseUrl === definitionBaseUrl) {
+ return { baseUrl: registryBaseUrl, overridden: false };
+ }
+ try {
+ const override = new URL(resolvedBaseUrl);
+ if (override.pathname === "/" || override.pathname === "") {
+ return {
+ baseUrl: `${override.origin}${new URL(registryBaseUrl).pathname}`,
+ overridden: true,
+ };
+ }
+ } catch {
+ return { baseUrl: registryBaseUrl, overridden: false };
+ }
+ return { baseUrl: resolvedBaseUrl.replace(/\/+$/, ""), overridden: true };
+}
+
+/** Pin a transport's endpoint to `url`, delegating everything else to it. */
+function withEndpoint(inner: ProviderTransport, url: string): ProviderTransport {
+ return new Proxy(inner, {
+ get(target, property, receiver) {
+ if (property === "getEndpoint") return () => url;
+ const value = Reflect.get(target, property, receiver);
+ return typeof value === "function" ? value.bind(target) : value;
+ },
+ });
+}
+
+function adapterFor(
+ api: WireApi,
+ modelName: string,
+ providerName: string,
+ definitionName: string
+): BaseAPIFormat {
+ switch (api) {
+ case "chat-completions":
+ return new OpenAIAPIFormat(modelName);
+ case "responses":
+ return new CodexAPIFormat(modelName, undefined, {
+ codexExtras: definitionName === "openai-codex",
+ });
+ case "anthropic-messages":
+ return new AnthropicAPIFormat(modelName, providerName);
+ case "gemini":
+ return new GeminiAPIFormat(modelName);
+ }
+}
+
+/**
+ * The provider's own transport for `api`: who signs, which identity headers,
+ * which extra fields. Its endpoint is replaced by the registry URL, except
+ * Codex, whose host is decided by the credential that signs (OAuth →
+ * chatgpt.com, API key → api.openai.com; `routing.md`).
+ */
+function transportFor(
+ definitionName: string,
+ api: WireApi,
+ ctx: ProfileContext,
+ url: string
+): ProviderTransport {
+ if (definitionName === "openai-codex") {
+ return new OpenAICodexTransport(ctx.provider, ctx.modelName, ctx.apiKey);
+ }
+ let inner: ProviderTransport;
+ if (api === "anthropic-messages") {
+ const provider: RemoteProvider = OPENCODE.has(definitionName)
+ ? { ...ctx.provider, authScheme: "x-api-key" }
+ : ctx.provider;
+ inner = OPENCODE.has(definitionName)
+ ? new OpenCodeZenMessagesTransport(provider, ctx.apiKey)
+ : new AnthropicProviderTransport(provider, ctx.apiKey);
+ } else if (api === "gemini" && definitionName === "google") {
+ inner = new GeminiProviderTransport(ctx.provider, ctx.modelName, ctx.apiKey);
+ } else if (OPENCODE.has(definitionName)) {
+ inner = new OpenCodeZenTransport(ctx.provider, ctx.modelName, ctx.apiKey);
+ } else if (definitionName === "openrouter") {
+ inner = new OpenRouterProviderTransport(ctx.apiKey, ctx.modelName);
+ } else if (definitionName === "poe") {
+ inner = new PoeProvider();
+ } else {
+ inner = new OpenAIProviderTransport(ctx.provider, ctx.modelName, ctx.apiKey);
+ }
+ return withEndpoint(inner, url);
+}
+
+/**
+ * A handler that sends nothing and answers every request with `message`.
+ *
+ * Returned for a connection that must not be called, instead of `null`: a null
+ * handler falls through to the OpenRouter fallback, which is exactly the
+ * silent substitution the wire reader exists to end. 400 because the request,
+ * not the network, is what cannot be served.
+ */
+export class RefusingHandler implements ModelHandler {
+ constructor(private readonly message: string) {}
+
+ async handle(): Promise<Response> {
+ log(`[Wire] refused: ${this.message}`);
+ return new Response(
+ JSON.stringify(wrapAnthropicError(400, `claudish: ${this.message}`, "invalid_request_error")),
+ { status: 400, headers: { "Content-Type": "application/json" } }
+ );
+ }
+
+ async shutdown(): Promise<void> {}
+}
+
+export type WireHandlerOutcome =
+ /** Built from the wire, or a {@link TryInTurnHandler} when the wire is unknown. */
+ | { kind: "handler"; handler: ModelHandler }
+ /** Not a wire-routed provider: the caller builds its handler as before. */
+ | { kind: "not-wire-routed" }
+ /** The request must not be sent; `message` says why. */
+ | { kind: "refused"; message: string };
+
+export async function buildWireHandler(
+ ctx: ProfileContext,
+ definitionName: string
+): Promise<WireHandlerOutcome> {
+ if (NOT_WIRE_ROUTED.has(definitionName)) return { kind: "not-wire-routed" };
+
+ let resolution = resolveConnection(definitionName, ctx.modelName, ctx.catalogCachePath);
+ if (resolution.ok === false && resolution.reason === "not-catalog-routed") {
+ return { kind: "not-wire-routed" };
+ }
+ if (
+ resolution.ok === false &&
+ (resolution.reason === "no-catalog" || resolution.reason === "no-registry") &&
+ // A cache path is the test seam: a fixture is never refreshed from the network.
+ !ctx.catalogCachePath
+ ) {
+ await ensureRouteRegistryReady();
+ resolution = resolveConnection(definitionName, ctx.modelName, ctx.catalogCachePath);
+ }
+ if (resolution.ok === false) {
+ if (resolution.reason === "no-catalog" || resolution.reason === "no-registry") {
+ return {
+ kind: "refused",
+ message:
+ `the cloud models catalog (with its route registry) is not available, so ${definitionName}@${ctx.modelName} ` +
+ "cannot be called: claudish sends catalog providers nothing it was not told. Run `claudish --models-refresh`; local models still work.",
+ };
+ }
+ // The catalog does not publish this model on this provider (a model newer
+ // than the generation, or one only the account knows). The route profile
+ // still says which APIs the host serves: try them in turn.
+ const profile = resolveRouteProfile(definitionName, ctx.catalogCachePath);
+ if (!profile) return { kind: "not-wire-routed" };
+ const unpublished: ResolvedConnection = {
+ provider: definitionName,
+ modelId: ctx.modelName,
+ route: profile.route,
+ externalModelId: ctx.modelName,
+ wire: { status: "unknown", evidence: [] },
+ profile: profile.profile,
+ generationId: profile.generationId,
+ };
+ return tryInTurn(ctx, definitionName, unpublished, "not published for this provider");
+ }
+
+ const connection = resolution.connection;
+ const { wire } = connection;
+ if (wire.status === "unsupported") {
+ return {
+ kind: "refused",
+ message:
+ `${connection.route.routeId}/${connection.route.routeProfileId} · ${connection.externalModelId} speaks ` +
+ `${wire.protocol}, which claudish does not implement`,
+ };
+ }
+ if (wire.status === "unknown") return tryInTurn(ctx, definitionName, connection, "wire unknown");
+
+ const handler = buildKnownWireHandler(ctx, definitionName, connection, wire);
+ return handler
+ ? { kind: "handler", handler }
+ : tryInTurn(ctx, definitionName, connection, `no base URL for ${wire.api}`);
+}
+
+function tryInTurn(
+ ctx: ProfileContext,
+ definitionName: string,
+ connection: ResolvedConnection,
+ why: string
+): WireHandlerOutcome {
+ const label = `${connection.route.routeId}/${connection.route.routeProfileId} · ${connection.externalModelId}`;
+ const apis = Object.keys(connection.profile.apis) as WireApi[];
+ if (apis.length === 0) {
+ return { kind: "refused", message: `${label}: ${why}, and its route profile publishes no API` };
+ }
+ log(`[Wire] ${label}: ${why} — trying ${apis.join(", ")} in turn (a catalog gap)`);
+ const key = `${connection.generationId}|${label}`;
+ return {
+ kind: "handler",
+ handler: new TryInTurnHandler(key, label, apis, (api) => {
+ const wire = apiOnlyWire(api);
+ return buildKnownWireHandler(ctx, definitionName, { ...connection, wire }, wire);
+ }),
+ };
+}
+
+export function buildKnownWireHandler(
+ ctx: ProfileContext,
+ definitionName: string,
+ connection: ResolvedConnection,
+ wire: KnownWire
+): ModelHandler | null {
+ const registryBase = connectionBaseUrl(connection, wire.api);
+ if (!registryBase) return null;
+ const definition = getProviderByName(definitionName);
+ const { baseUrl, overridden } = effectiveBaseUrl(
+ registryBase,
+ definition?.baseUrl,
+ ctx.provider.baseUrl
+ );
+ const url = wireRequestUrl(baseUrl, wire.api, connection.externalModelId);
+ if (overridden) log(`[Wire] ${definitionName}: base URL overridden by user config → ${baseUrl}`);
+
+ const transport = transportFor(definitionName, wire.api, ctx, url);
+ const adapter = adapterFor(wire.api, ctx.modelName, ctx.provider.name, definitionName);
+ const handler = new ComposedHandler(transport, ctx.targetModel, ctx.modelName, ctx.port, {
+ adapter,
+ ...(wire.api === "chat-completions" || wire.api === "responses"
+ ? { tokenStrategy: "delta-aware" as const }
+ : {}),
+ ...ctx.sharedOpts,
+ connection,
+ });
+ log(
+ `[Wire] ${definitionName}@${ctx.modelName} → ${connection.route.routeId}/${connection.route.routeProfileId} · ` +
+ `${connection.externalModelId}: ${wire.api} ${definitionName === "openai-codex" ? "(credential-decided host)" : url} ` +
+ `[generation ${connection.generationId}]`
+ );
+ return handler;
+}
diff --git a/packages/cli/src/providers/wire-markers.test.ts b/packages/cli/src/providers/wire-markers.test.ts
new file mode 100644
index 00000000..ac930bc9
--- /dev/null
+++ b/packages/cli/src/providers/wire-markers.test.ts
@@ -0,0 +1,58 @@
+import { expect, test } from "bun:test";
+import { Hono } from "hono";
+import {
+ WireMarkerError,
+ WireMarkerHandler,
+ formatWireMarkers,
+ splitWireMarkers,
+ wireMarkerContext,
+} from "./wire-markers.js";
+
+test.each([
+ ["cx@gpt+pro", { spec: "cx@gpt", mode: "pro" }],
+ ["cx@gpt#fast", { spec: "cx@gpt", speed: "fast" }],
+ ["cx@gpt+pro#fast:3", { spec: "cx@gpt:3", mode: "pro", speed: "fast" }],
+ ["cx@gpt#FAST+PRO:3", { spec: "cx@gpt:3", mode: "pro", speed: "fast" }],
+ ["cx@gpt+standard", { spec: "cx@gpt", mode: "standard" }],
+ ["cx@gpt:3", { spec: "cx@gpt:3" }],
+] as const)("splits %s", (input, expected) => {
+ expect(splitWireMarkers(input)).toEqual(expected);
+ expect(splitWireMarkers(formatWireMarkers(expected))).toEqual(expected);
+});
+test.each(["x+pro+standard", "x#fast#flex", "x+pro-middle", "x#fast-middle"])(
+ "rejects misplaced or duplicate %s",
+ (input) => {
+ expect(() => splitWireMarkers(input)).toThrow(WireMarkerError);
+ }
+);
+test.each([
+ ["x+typo", "modes: +standard, +pro"],
+ ["x#typo", "speeds: #standard, #fast, #priority, #flex, #ultrafast"],
+])("lists valid values for %s", (input, list) => {
+ expect(() => splitWireMarkers(input)).toThrow(list);
+});
+test("handler scopes markers to the asynchronous request and forwards shutdown", async () => {
+ const markers = { spec: "x", mode: "pro" as const, speed: "fast" as const };
+ let shutdown = false;
+ const handler = new WireMarkerHandler(
+ {
+ async handle(_c, payload) {
+ await Promise.resolve();
+ expect(wireMarkerContext.getStore()).toEqual(markers);
+ expect(payload).toEqual({ hello: true });
+ return new Response("ok");
+ },
+ async shutdown() {
+ shutdown = true;
+ },
+ },
+ markers
+ );
+ const app = new Hono();
+ app.post("/", (c) => handler.handle(c, { hello: true }));
+ expect(wireMarkerContext.getStore()).toBeUndefined();
+ expect(await (await app.request("/", { method: "POST" })).text()).toBe("ok");
+ expect(wireMarkerContext.getStore()).toBeUndefined();
+ await handler.shutdown();
+ expect(shutdown).toBe(true);
+});
diff --git a/packages/cli/src/providers/wire-markers.ts b/packages/cli/src/providers/wire-markers.ts
new file mode 100644
index 00000000..adb007e0
--- /dev/null
+++ b/packages/cli/src/providers/wire-markers.ts
@@ -0,0 +1,109 @@
+/**
+ * Request-mode and speed markers on a model spec: `+pro` and `#<speed>`.
+ *
+ * cx@gpt-6-sol+pro reasoning mode pro
+ * oai@gpt-6-sol#fast speed fast (also: priority, flex, ultrafast, standard)
+ * oai@gpt-6-sol+pro#flex both, in either order
+ *
+ * The characters are chosen because no catalog id contains `+` or `#`
+ * (2,080 ids, generation g-20261012101007285-7770c36e), while `-pro` (102 ids)
+ * and `-fast` (22) are real, different models; `:` is concurrency; `>>` and `|`
+ * are shell operators (an unquoted `>>fast` silently redirects to a file).
+ * `#` mid-word is literal in bash and default zsh, and with zsh's
+ * `extendedglob` it fails loudly rather than silently.
+ *
+ * A marker only REQUESTS a value. Whether it is sent is the connection's
+ * `wire.reasoning.mode` / `wire.speed` (catalog 3.7.0 R13); an explicit request
+ * the connection does not publish is refused with the values it offers.
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+import type { Context } from "hono";
+import type { ModelHandler } from "../handlers/types.js";
+import { WIRE_SPEEDS, type WireMode, type WireSpeed } from "./wire-request.js";
+
+/**
+ * The markers of the request being served, for `ComposedHandler` step 5w.
+ *
+ * Carried per request rather than baked into a handler: handlers are cached
+ * per model, a fallback chain shares them, and a marker must never reach a
+ * request body (the native passthrough forwards the body verbatim).
+ */
+export const wireMarkerContext = new AsyncLocalStorage<WireMarkers>();
+
+/** Serve `inner` with `markers` in {@link wireMarkerContext}. */
+export class WireMarkerHandler implements ModelHandler {
+ constructor(
+ private readonly inner: ModelHandler,
+ private readonly markers: WireMarkers
+ ) {}
+
+ handle(c: Context, payload: any): Promise<Response> {
+ return wireMarkerContext.run(this.markers, () => this.inner.handle(c, payload));
+ }
+
+ shutdown(): Promise<void> {
+ return this.inner.shutdown();
+ }
+}
+
+const MODES: readonly WireMode[] = ["standard", "pro"];
+
+export interface WireMarkers {
+ /** The spec with every marker removed, `:N` concurrency kept. */
+ spec: string;
+ mode?: WireMode;
+ speed?: WireSpeed;
+}
+
+export class WireMarkerError extends Error {}
+
+/**
+ * Split the markers off a model spec. Markers sit at the end of the model
+ * part, before an optional `:N` concurrency suffix. Throws
+ * {@link WireMarkerError} for an unknown value or a repeated marker, so a typo
+ * never silently becomes "no marker".
+ */
+export function splitWireMarkers(input: string): WireMarkers {
+ const concurrency = /:\d+$/.exec(input)?.[0] ?? "";
+ let rest = concurrency ? input.slice(0, -concurrency.length) : input;
+ let mode: WireMode | undefined;
+ let speed: WireSpeed | undefined;
+
+ for (;;) {
+ const match = /([+#])([A-Za-z]+)$/.exec(rest);
+ if (!match) break;
+ const [whole, sigil, raw] = match;
+ const value = raw.toLowerCase();
+ if (sigil === "+") {
+ if (!(MODES as readonly string[]).includes(value)) {
+ throw new WireMarkerError(
+ `unknown mode "+${raw}" in "${input}" (modes: +${MODES.join(", +")})`
+ );
+ }
+ if (mode) throw new WireMarkerError(`more than one mode marker in "${input}"`);
+ mode = value as WireMode;
+ } else {
+ if (!(WIRE_SPEEDS as readonly string[]).includes(value)) {
+ throw new WireMarkerError(
+ `unknown speed "#${raw}" in "${input}" (speeds: #${WIRE_SPEEDS.join(", #")})`
+ );
+ }
+ if (speed) throw new WireMarkerError(`more than one speed marker in "${input}"`);
+ speed = value as WireSpeed;
+ }
+ rest = rest.slice(0, -whole.length);
+ }
+ if (/[+#]/.test(rest)) {
+ throw new WireMarkerError(
+ `"${input}": "+" and "#" mark a mode or speed at the end of the model name only`
+ );
+ }
+ return { spec: `${rest}${concurrency}`, ...(mode ? { mode } : {}), ...(speed ? { speed } : {}) };
+}
+
+/** Put markers back on a spec (for display and handler cache keys). */
+export function formatWireMarkers(markers: WireMarkers): string {
+ const concurrency = /:\d+$/.exec(markers.spec)?.[0] ?? "";
+ const base = concurrency ? markers.spec.slice(0, -concurrency.length) : markers.spec;
+ return `${base}${markers.mode ? `+${markers.mode}` : ""}${markers.speed ? `#${markers.speed}` : ""}${concurrency}`;
+}
diff --git a/packages/cli/src/providers/wire-request.test.ts b/packages/cli/src/providers/wire-request.test.ts
new file mode 100644
index 00000000..d92afc0c
--- /dev/null
+++ b/packages/cli/src/providers/wire-request.test.ts
@@ -0,0 +1,532 @@
+import { afterEach, expect, test } from "bun:test";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { DiskCacheV3 } from "./all-models-cache.js";
+import { resolveConnection } from "./connection-resolver.js";
+import type { KnownWire } from "./connection-wire.js";
+import {
+ clampEffort,
+ deletePointer,
+ mergeWireHeaders,
+ recoverBorrowedWireFields,
+ setPointer,
+ shapeRequestFromWire,
+ stripWireDecisions,
+ wireChoicesFromClaudeRequest,
+} from "./wire-request.js";
+const cachePath = new URL(
+ "../test-fixtures/catalog-v3/wire-g-20261012101007285-7770c36e.json",
+ import.meta.url
+).pathname;
+function connection(provider = "openai", model = "gpt-6.1-sol", path = cachePath) {
+ const r = resolveConnection(provider, model, path);
+ if (!r.ok || r.connection.wire.status !== "known") throw new Error("missing fixture wire");
+ return { ...r.connection, wire: structuredClone(r.connection.wire) };
+}
+const tempDirs: string[] = [];
+afterEach(() => {
+ for (const dir of tempDirs.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+// Negative fixtures change one property of an actual published wire and are
+// round-tripped through a temporary cache, never assembled as invented rows.
+function changedWire(provider: string, model: string, change: (wire: KnownWire) => void) {
+ const selected = connection(provider, model);
+ const cache: DiskCacheV3 = JSON.parse(readFileSync(cachePath, "utf8"));
+ const entry = cache.entries.find((e) => e.modelId === selected.modelId)!;
+ const published = entry.aggregators!.find(
+ (c) =>
+ c.route?.routeId === selected.route.routeId &&
+ c.route?.routeProfileId === selected.route.routeProfileId &&
+ c.externalModelId === selected.externalModelId
+ )!;
+ if (published.wire?.status !== "known") throw new Error("missing known wire");
+ change(published.wire);
+ const dir = mkdtempSync(join(tmpdir(), "wire-request-"));
+ tempDirs.push(dir);
+ const path = join(dir, "catalog.json");
+ writeFileSync(path, JSON.stringify(cache));
+ return connection(provider, model, path);
+}
+test("JSON pointers create objects, overwrite non-objects and decode escapes", () => {
+ const body: Record<string, unknown> = { a: 3 };
+ setPointer(body, "/a/~0/~1/~01", 7);
+ expect(body).toEqual({ a: { "~": { "/": { "~1": 7 } } } });
+ deletePointer(body, "/a/~0/~1/~01");
+ expect(body).toEqual({});
+});
+test.each([{ value: null }, { value: [] }, { value: "scalar" }])(
+ "overwrites intermediate %j",
+ ({ value }) => {
+ const body: Record<string, unknown> = { a: value };
+ setPointer(body, "/a/b/c", true);
+ expect(body).toEqual({ a: { b: { c: true } } });
+ }
+);
+test("delete preserves nonempty parents and ignores absent paths", () => {
+ const body: Record<string, unknown> = { a: { keep: 1, drop: 2 } };
+ deletePointer(body, "/a/drop");
+ deletePointer(body, "/missing/x");
+ expect(body).toEqual({ a: { keep: 1 } });
+ expect(() => setPointer(body, "", 1)).toThrow("root");
+ expect(() => setPointer(body, "invalid", 1)).toThrow("invalid JSON pointer");
+});
+test("strips every decision while preserving structured output and unrelated fields", () => {
+ const body: Record<string, unknown> = {
+ max_tokens: 1,
+ max_completion_tokens: 2,
+ max_output_tokens: 3,
+ reasoning_effort: "high",
+ reasoning: {},
+ thinking: {},
+ enable_thinking: true,
+ thinking_budget: 5,
+ include_reasoning: true,
+ output_config: { effort: "high", format: { type: "json_schema" } },
+ text: { verbosity: "high" },
+ generationConfig: { thinkingConfig: {}, maxOutputTokens: 42 },
+ service_tier: "priority",
+ speed: "fast",
+ messages: [],
+ };
+ stripWireDecisions(body, "responses");
+ expect(body).toEqual({
+ output_config: { format: { type: "json_schema" } },
+ generationConfig: { maxOutputTokens: 42 },
+ messages: [],
+ });
+});
+test.each([
+ ["high", ["low", "high"], "high"],
+ ["minimal", ["low", "high"], "low"],
+ ["medium", ["low", "high"], "high"],
+ ["mystery", ["low"], undefined],
+ ["mystery", ["mystery"], "mystery"],
+ ["high", [], undefined],
+] as const)("clamps %s against %j", (value, values, expected) =>
+ expect(clampEffort(value, [...values])).toBe(expected)
+);
+test("pinned effort wins over output config and budget", () =>
+ expect(
+ wireChoicesFromClaudeRequest(
+ {
+ output_config: { effort: "low" },
+ thinking: { budget_tokens: 1 },
+ tools: [{}],
+ max_tokens: 12,
+ },
+ "high"
+ )
+ ).toEqual({ effort: "high", reasoningOff: false, hasTools: true, maxTokens: 12 }));
+test("output config wins over legacy budget", () =>
+ expect(
+ wireChoicesFromClaudeRequest({
+ output_config: { effort: "HIGH" },
+ thinking: { budget_tokens: 1 },
+ }).effort
+ ).toBe("high"));
+test.each([
+ [0, undefined],
+ [1, "low"],
+ [3999, "low"],
+ [4000, "medium"],
+ [15999, "medium"],
+ [16000, "high"],
+ [31999, "high"],
+ [32000, "xhigh"],
+] as const)("budget %s maps to %s", (budget, effort) => {
+ const result = wireChoicesFromClaudeRequest({ thinking: { budget_tokens: budget } });
+ expect(result.effort).toBe(effort);
+ expect(result.reasoningOff).toBe(budget === 0);
+});
+test.each([{ thinking: { type: "disabled" } }, { output_config: { effort: "none" } }])(
+ "off intent %j",
+ (request) =>
+ expect(wireChoicesFromClaudeRequest(request)).toMatchObject({
+ reasoningOff: true,
+ effort: undefined,
+ })
+);
+test("tools requiring Responses drop reasoning", () => {
+ const { wire } = changedWire("openrouter", "gpt-6.1-sol", (wire) => {
+ wire.toolsWithReasoning = "requires-responses";
+ });
+ const body: Record<string, unknown> = { reasoning: { effort: "high" } };
+ shapeRequestFromWire(body, wire, { hasTools: true, effort: "high" });
+ expect(body).toEqual({});
+});
+test.each([true, false])("tools requiring effort none (published=%s)", (published) => {
+ const { wire } = changedWire("openrouter", published ? "gpt-5.5" : "gpt-6.1-sol", (wire) => {
+ wire.toolsWithReasoning = "requires-effort-none";
+ });
+ const body: any = {};
+ const result = shapeRequestFromWire(body, wire, { hasTools: true, effort: "high" });
+ expect(body.reasoning).toEqual(published ? { enabled: true, effort: "none" } : { enabled: true });
+ expect(result.sentEffort).toBe(published ? "none" : undefined);
+});
+test("not applicable disable keeps enable and least effort with a note", () => {
+ const body = {};
+ const result = shapeRequestFromWire(body, connection("openrouter", "gpt-6.1-sol").wire, {
+ reasoningOff: true,
+ });
+ expect(body).toEqual({ reasoning: { enabled: true, effort: "low" } });
+ expect(result.notes.join(" ")).toContain("disable not_applicable");
+});
+test.each([false, true])("served-model warning accepted=%s", (accepted) => {
+ const body = {};
+ const result = shapeRequestFromWire(body, connection("kimi-coding", "k3").wire, {
+ reasoningOff: true,
+ acceptServedModelChange: accepted,
+ });
+ expect(body).toEqual({ reasoning_effort: accepted ? "none" : "low" });
+ expect(result.notes.join(" ")).toContain("served_model_changes");
+});
+test.each([true, false])("unoffered explicit=%s controls", (explicit) => {
+ const body = {};
+ const result = shapeRequestFromWire(body, connection("x-ai", "grok-4.7").wire, {
+ speed: { value: "fast", explicit },
+ });
+ expect(result.refusal !== undefined).toBe(explicit);
+ expect(result.refusal ?? result.notes.join(" ")).toContain("standard, priority");
+ expect(body).not.toHaveProperty("service_tier");
+ const mode = shapeRequestFromWire({}, connection("openrouter", "gpt-5.5").wire, {
+ mode: { value: "pro", explicit },
+ });
+ expect(mode.refusal !== undefined).toBe(explicit);
+ if (!explicit) expect(mode.notes.join(" ")).toContain("mode");
+});
+test("standard with no explicit standard value omits the control", () => {
+ const body = {};
+ const result = shapeRequestFromWire(body, connection("openrouter", "gpt-5.5").wire, {
+ speed: { value: "standard", explicit: true },
+ });
+ expect(result.refusal).toBeUndefined();
+ expect(body).not.toHaveProperty("service_tier");
+ expect(result.notes.join(" ")).toContain("field omitted");
+});
+test("unknown fields borrow only same-API owner token and reasoning pointers", () => {
+ const c = connection("opencode-zen", "minimax-m3");
+ expect(c.ownerWire?.api).toBe("chat-completions");
+ expect(c.ownerWire?.tokenParam).toBe("max_completion_tokens");
+ const body = {};
+ const result = shapeRequestFromWire(
+ body,
+ c.wire,
+ { maxTokens: 32000, effort: "high" },
+ c.ownerWire
+ );
+ expect(body).toEqual({ max_completion_tokens: 32000, thinking: { type: "adaptive" } });
+ expect(result.borrowed).toEqual(["/max_completion_tokens", "/thinking/type"]);
+});
+test("different API owner cannot lend any fields", () => {
+ const c = connection("opencode-zen", "minimax-m3");
+ const body = {};
+ const result = shapeRequestFromWire(
+ body,
+ c.wire,
+ { maxTokens: 32000, effort: "high" },
+ connection().wire
+ );
+ expect(body).toEqual({});
+ expect(result.borrowed).toEqual([]);
+});
+test("mode and speed are never borrowed", () => {
+ const c = connection("opencode-zen", "gpt-5.5");
+ const owner = connection().wire;
+ const body = {};
+ const result = shapeRequestFromWire(
+ body,
+ c.wire,
+ { mode: { value: "pro", explicit: true }, speed: { value: "fast", explicit: true } },
+ owner
+ );
+ expect(body).not.toHaveProperty("service_tier");
+ expect(body).not.toHaveProperty("reasoning.mode");
+ expect(result.borrowed).toEqual(["/reasoning/effort"]);
+ expect(result.refusal).toBeDefined();
+});
+test.each([
+ ["Unsupported parameter: max_tokens", { reasoning: { effort: "high" }, keep: true }],
+ ["Unknown parameter", { keep: true }],
+] as const)("recovery drops borrowed fields for %s without mutation", (error, expected) => {
+ const body = { max_tokens: 42, reasoning: { effort: "high" }, keep: true };
+ const original = structuredClone(body);
+ expect(
+ recoverBorrowedWireFields(body, ["/max_tokens", "/reasoning/effort"], error)?.payload
+ ).toEqual(expected);
+ expect(body).toEqual(original);
+});
+test("recovery declines unrelated errors and empty borrowed list", () => {
+ expect(
+ recoverBorrowedWireFields({ reasoning_effort: "high" }, ["/reasoning_effort"], "quota exceeded")
+ ).toBeNull();
+ expect(recoverBorrowedWireFields({ x: 1 }, [], "Unknown parameter x")).toBeNull();
+});
+test("wire headers append case-insensitively without duplicate tokens", () => {
+ const headers = { "Anthropic-Beta": "oauth, fast" };
+ mergeWireHeaders(headers, [
+ { name: "anthropic-beta", value: "fast", merge: "append-comma" },
+ { name: "ANTHROPIC-BETA", value: "new", merge: "append-comma" },
+ ]);
+ expect(headers).toEqual({ "Anthropic-Beta": "oauth, fast,new" });
+});
+const cases = [
+ {
+ provider: "openai",
+ model: "gpt-6.1-sol",
+ url: "https://api.openai.com/v1/responses",
+ expected: {
+ max_output_tokens: 32000,
+ reasoning: {
+ effort: "high",
+ },
+ },
+ absent: ["store", "include", "text", "reasoning_effort"],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "openai",
+ model: "gpt-6.1-sol",
+ url: "https://api.openai.com/v1/responses",
+ expected: {
+ max_output_tokens: 32000,
+ reasoning: {
+ effort: "high",
+ mode: "pro",
+ },
+ service_tier: "priority",
+ },
+ absent: ["store", "include", "text", "reasoning_effort"],
+ opts: {
+ wireMode: "pro",
+ wireSpeed: "fast",
+ },
+ req: {},
+ },
+ {
+ provider: "openai",
+ model: "gpt-6.1-sol",
+ url: "https://api.openai.com/v1/responses",
+ expected: {
+ reasoning: {
+ effort: "low",
+ },
+ max_output_tokens: 32000,
+ },
+ absent: ["reasoning_effort"],
+ opts: {},
+ req: {
+ output_config: {
+ effort: "minimal",
+ },
+ },
+ },
+ {
+ provider: "openrouter",
+ model: "openai/gpt-6.1-sol",
+ url: "https://openrouter.ai/api/v1/chat/completions",
+ expected: {
+ max_tokens: 32000,
+ reasoning: {
+ enabled: true,
+ effort: "high",
+ },
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "opencode-zen-go",
+ model: "grok-4.7",
+ url: "https://opencode.ai/zen/go/v1/responses",
+ expected: {
+ max_output_tokens: 32000,
+ reasoning: {
+ effort: "high",
+ },
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "opencode-zen-go",
+ model: "minimax-m3",
+ url: "https://opencode.ai/zen/go/v1/messages",
+ expected: {
+ max_tokens: 32000,
+ },
+ absent: ["thinking"],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "opencode-zen",
+ model: "minimax-m3",
+ url: "https://opencode.ai/zen/v1/chat/completions",
+ expected: {
+ max_completion_tokens: 32000,
+ thinking: {
+ type: "adaptive",
+ },
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "z-ai",
+ model: "glm-5.3",
+ url: "https://api.z.ai/api/paas/v4/chat/completions",
+ expected: {
+ max_tokens: 32000,
+ thinking: {
+ type: "enabled",
+ },
+ reasoning_effort: "high",
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "kimi-coding",
+ model: "k3",
+ url: "https://api.kimi.ai/coding/v1/chat/completions",
+ expected: {
+ max_completion_tokens: 32000,
+ reasoning_effort: "low",
+ },
+ absent: [],
+ opts: {},
+ req: {
+ thinking: {
+ type: "disabled",
+ },
+ output_config: null,
+ },
+ },
+ {
+ provider: "ollamacloud",
+ model: "kimi-k3",
+ url: "https://ollama.com/v1/chat/completions",
+ expected: {
+ max_tokens: 32000,
+ reasoning_effort: "high",
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "qwen-token-plan",
+ model: "qwen3.7-plus",
+ url: "https://token-plan.maas.qwencloudapi.com/compatible-mode/v1/chat/completions",
+ expected: {
+ max_completion_tokens: 32000,
+ enable_thinking: true,
+ },
+ absent: [],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "fireworks",
+ model: "accounts/fireworks/models/qwen3p8-max",
+ url: "https://api.fireworks.ai/inference/v1/chat/completions",
+ expected: {
+ max_tokens: 32000,
+ },
+ absent: ["reasoning", "reasoning_effort", "thinking", "enable_thinking"],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "google",
+ model: "gemini-3.8-flash",
+ url: "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:streamGenerateContent?alt=sse",
+ expected: {
+ "generationConfig.maxOutputTokens": 32000,
+ },
+ absent: ["generationConfig.thinkingConfig", "thinkingConfig"],
+ opts: {},
+ req: {},
+ },
+ {
+ provider: "anthropic",
+ model: "claude-opus-5-5",
+ url: "https://api.anthropic.com/v1/messages",
+ expected: {
+ max_tokens: 32000,
+ "output_config.effort": "high",
+ speed: "fast",
+ },
+ absent: ["thinking"],
+ opts: {
+ wireSpeed: "fast",
+ },
+ req: {},
+ },
+];
+
+for (const [index, tc] of cases.entries())
+ test(`fixture decisions ${index}: ${tc.provider}@${tc.model}`, () => {
+ const c = connection(tc.provider, tc.model);
+ const body: Record<string, unknown> =
+ c.wire.api === "gemini"
+ ? { generationConfig: { maxOutputTokens: 32000, thinkingConfig: {} } }
+ : {};
+ const choices = wireChoicesFromClaudeRequest({
+ max_tokens: 32000,
+ tools: [{}],
+ output_config: { effort: "high" },
+ ...tc.req,
+ });
+ shapeRequestFromWire(
+ body,
+ c.wire,
+ {
+ ...choices,
+ ...(tc.opts.wireMode ? { mode: { value: "pro", explicit: true } as const } : {}),
+ ...(tc.opts.wireSpeed ? { speed: { value: "fast", explicit: true } as const } : {}),
+ },
+ c.ownerWire
+ );
+ for (const [key, value] of Object.entries(tc.expected)) expect(body).toHaveProperty(key, value);
+ for (const key of tc.absent) expect(body).not.toHaveProperty(key);
+ for (const key of ["max_tokens", "max_completion_tokens", "max_output_tokens"])
+ if (!(key in tc.expected)) expect(body).not.toHaveProperty(key);
+ });
+
+test("recovery does not mistake a pointer token substring for a named field", () => {
+ expect(recoverBorrowedWireFields({ x: 1 }, ["/x"], "quota exceeded")).toBeNull();
+});
+
+test("recovery preserves an unborrowed field even when the error names it too", () => {
+ expect(
+ recoverBorrowedWireFields(
+ { max_tokens: 42, speed: "fast" },
+ ["/max_tokens"],
+ "Unknown parameters: max_tokens, speed"
+ )?.payload
+ ).toEqual({ speed: "fast" });
+});
+test("headers are created when no prior header exists", () => {
+ const headers = {};
+ mergeWireHeaders(headers, [
+ { name: "anthropic-beta", value: "fast-mode-2026-02-01", merge: "append-comma" },
+ ]);
+ expect(headers).toEqual({ "anthropic-beta": "fast-mode-2026-02-01" });
+});
+
+test("not-applicable token limit cannot borrow the owner's parameter", () => {
+ const c = changedWire("opencode-zen", "minimax-m3", (wire) => {
+ wire.tokenParam = { status: "not_applicable" };
+ });
+ const body = {};
+ const result = shapeRequestFromWire(body, c.wire, { maxTokens: 32000 }, c.ownerWire);
+ expect(body).not.toHaveProperty("max_completion_tokens");
+ expect(result.borrowed).toEqual(["/thinking/type"]);
+});
diff --git a/packages/cli/src/providers/wire-request.ts b/packages/cli/src/providers/wire-request.ts
new file mode 100644
index 00000000..21b0ceab
--- /dev/null
+++ b/packages/cli/src/providers/wire-request.ts
@@ -0,0 +1,492 @@
+/**
+ * Shape a request body from a connection's `wire` (catalog 3.7.0).
+ *
+ * The adapters convert messages and tools: that is protocol work and stays
+ * theirs. Everything a connection decides — the output-limit field, the
+ * reasoning encoding, the request mode and the speed tier — is written HERE,
+ * from the wire alone, after every adapter and dialect has run. First every
+ * field any of them may have emitted for those decisions is removed, so nothing
+ * a name rule or a model-level field chose can survive onto the wire.
+ *
+ * Pure: no I/O, no catalog reads. The caller passes the resolved wire and the
+ * user's choices, and logs the returned notes.
+ */
+import type {
+ KnownWire,
+ WireAssignment,
+ WireControl,
+ WireHeader,
+ WireReasoningWarning,
+ WireValue,
+} from "./connection-wire.js";
+
+/** Catalog effort names, lowest to highest. */
+export const WIRE_EFFORT_ORDER = [
+ "none",
+ "minimal",
+ "low",
+ "medium",
+ "high",
+ "xhigh",
+ "max",
+] as const;
+
+export type WireSpeed = "standard" | "fast" | "priority" | "flex" | "ultrafast";
+export const WIRE_SPEEDS: readonly WireSpeed[] = [
+ "standard",
+ "fast",
+ "priority",
+ "flex",
+ "ultrafast",
+];
+export type WireMode = "standard" | "pro";
+
+export interface WireChoices {
+ /** The catalog effort name the user asked for (request signal or `--effort`), if any. */
+ effort?: string;
+ /** The user turned reasoning off (`thinking.type: "disabled"`, effort `none`). */
+ reasoningOff?: boolean;
+ /** The request carries function tools. */
+ hasTools?: boolean;
+ /** The output limit to write at `wire.tokenParam`. */
+ maxTokens?: number;
+ /** `+pro` on the model spec, or pro turned on by `proOnUltracode`. */
+ mode?: { value: WireMode; explicit: boolean };
+ /** `#<speed>` on the model spec. */
+ speed?: { value: WireSpeed; explicit: boolean };
+ /** The user accepted a `served_model_changes` warning for this connection. */
+ acceptServedModelChange?: boolean;
+}
+
+export interface WireShapeResult {
+ /** Headers the wire requires alongside a field it wrote (append-comma merged by the caller). */
+ headers: WireHeader[];
+ /** One line per decision worth logging. */
+ notes: string[];
+ /** Set when an explicit user choice cannot be honoured on this connection: do not send. */
+ refusal?: string;
+ /** The effort name actually sent, after clamping. */
+ sentEffort?: string;
+ /**
+ * Pointers written from the OWNER's connection because this connection's own
+ * value is unknown (try in turn). A 400 that names one of them is answered by
+ * resending without them; nothing else may be dropped on that basis.
+ */
+ borrowed: string[];
+}
+
+// ─── RFC 6901 JSON Pointer ─────────────────────────────────────────────────
+
+function pointerTokens(path: string): string[] {
+ if (path === "") return [];
+ if (!path.startsWith("/")) throw new Error(`invalid JSON pointer "${path}"`);
+ return path
+ .slice(1)
+ .split("/")
+ .map((token) => token.replace(/~1/g, "/").replace(/~0/g, "~"));
+}
+
+/**
+ * Write `value` at `path` in `body`, creating intermediate objects and
+ * overwriting whatever is at the target (or in the way of it).
+ */
+export function setPointer(body: Record<string, unknown>, path: string, value: unknown): void {
+ const tokens = pointerTokens(path);
+ if (tokens.length === 0) throw new Error("cannot replace the body root");
+ let node: Record<string, unknown> = body;
+ for (const token of tokens.slice(0, -1)) {
+ const next = node[token];
+ if (next === null || typeof next !== "object" || Array.isArray(next)) node[token] = {};
+ node = node[token] as Record<string, unknown>;
+ }
+ node[tokens[tokens.length - 1]] = value;
+}
+
+/** Remove the value at `path`, then any objects left empty above it. */
+export function deletePointer(body: Record<string, unknown>, path: string): void {
+ const tokens = pointerTokens(path);
+ const trail: Array<Record<string, unknown>> = [body];
+ let node: unknown = body;
+ for (const token of tokens.slice(0, -1)) {
+ if (node === null || typeof node !== "object") return;
+ node = (node as Record<string, unknown>)[token];
+ if (node === null || typeof node !== "object" || Array.isArray(node)) return;
+ trail.push(node as Record<string, unknown>);
+ }
+ delete trail[trail.length - 1][tokens[tokens.length - 1]];
+ for (let i = trail.length - 1; i > 0; i--) {
+ if (Object.keys(trail[i]).length > 0) break;
+ delete trail[i - 1][tokens[i - 1]];
+ }
+}
+
+// ─── Stripping ─────────────────────────────────────────────────────────────
+
+const TOKEN_LIMIT_FIELDS = ["max_tokens", "max_completion_tokens", "max_output_tokens"];
+
+/**
+ * Every field an adapter or dialect may emit for reasoning, mode or speed, on
+ * any of the four APIs. Removed before the wire writes its own, so a value a
+ * name rule chose never reaches the upstream.
+ */
+const DECISION_POINTERS = [
+ "/reasoning_effort",
+ "/reasoning",
+ "/thinking",
+ "/enable_thinking",
+ "/thinking_budget",
+ "/include_reasoning",
+ "/output_config/effort",
+ "/text/verbosity",
+ "/generationConfig/thinkingConfig",
+ "/service_tier",
+ "/speed",
+];
+
+export function stripWireDecisions(body: Record<string, unknown>, api: KnownWire["api"]): void {
+ if (api !== "gemini") for (const field of TOKEN_LIMIT_FIELDS) delete body[field];
+ for (const path of DECISION_POINTERS) deletePointer(body, path);
+}
+
+// ─── Effort ────────────────────────────────────────────────────────────────
+
+function effortRank(name: string): number {
+ return (WIRE_EFFORT_ORDER as readonly string[]).indexOf(name);
+}
+
+/**
+ * The published effort name nearest to `requested` (Jack's C2: clamp, never
+ * refuse). Ties go to the higher level. A name outside the catalog vocabulary
+ * is not clamped: it is returned only if published verbatim.
+ */
+export function clampEffort(requested: string, published: string[]): string | undefined {
+ if (published.includes(requested)) return requested;
+ const target = effortRank(requested);
+ if (target < 0) return undefined;
+ let best: string | undefined;
+ let bestDistance = Number.POSITIVE_INFINITY;
+ for (const candidate of published) {
+ const rank = effortRank(candidate);
+ if (rank < 0) continue;
+ const distance = Math.abs(rank - target);
+ if (
+ distance < bestDistance ||
+ (distance === bestDistance && best !== undefined && rank > effortRank(best))
+ ) {
+ best = candidate;
+ bestDistance = distance;
+ }
+ }
+ return best;
+}
+
+// ─── Controls ──────────────────────────────────────────────────────────────
+
+function applyControl(
+ body: Record<string, unknown>,
+ control: WireControl,
+ requested: string,
+ label: string,
+ explicit: boolean,
+ result: WireShapeResult
+): void {
+ if (control.status !== "supported") {
+ const message = `${label} "${requested}" is not available on this connection (${control.status})`;
+ if (explicit && requested !== "standard") result.refusal = message;
+ else result.notes.push(message);
+ return;
+ }
+ if (requested === "standard" && control.values.standard === undefined) {
+ // "Standard means the default": leave the field out.
+ result.notes.push(`${label} standard: field omitted (connection default)`);
+ return;
+ }
+ const native = control.values[requested];
+ if (native === undefined) {
+ const offered = Object.keys(control.values).join(", ");
+ const message = `${label} "${requested}" is not offered on this connection (offered: ${offered || "none"})`;
+ if (explicit) result.refusal = message;
+ else result.notes.push(message);
+ return;
+ }
+ setPointer(body, control.path, native);
+ result.headers.push(...control.headers);
+ result.notes.push(
+ `${label} ${requested}: ${control.path} = ${JSON.stringify(native)}${control.access !== "open" ? ` (access: ${control.access})` : ""}`
+ );
+}
+
+// ─── Reasoning ─────────────────────────────────────────────────────────────
+
+/** Writes into the body, recording each pointer when the values are borrowed. */
+type PointerWriter = (path: string, value: unknown) => void;
+
+function writeAssignments(put: PointerWriter, assignments: WireAssignment[]): void {
+ for (const assignment of assignments) put(assignment.path, assignment.value);
+}
+
+function warningFor(
+ warnings: WireReasoningWarning[] | undefined,
+ part: "enable" | "disable"
+): WireReasoningWarning | undefined {
+ return warnings?.find((warning) => warning.part === part);
+}
+
+function applyReasoning(
+ put: PointerWriter,
+ reasoning: KnownWire["reasoning"],
+ toolsWithReasoning: KnownWire["toolsWithReasoning"],
+ choices: WireChoices,
+ result: WireShapeResult
+): void {
+ if (reasoning.status !== "supported") {
+ result.notes.push(`reasoning ${reasoning.status}: no reasoning field sent`);
+ return;
+ }
+
+ // Tools plus reasoning on a Chat connection that serves them together only
+ // over Responses: send the request without reasoning rather than switch APIs,
+ // because the other API's fields are not part of this wire.
+ if (choices.hasTools && toolsWithReasoning === "requires-responses") {
+ result.notes.push(
+ "tools with reasoning require Responses on this connection: reasoning not sent"
+ );
+ return;
+ }
+
+ let off = choices.reasoningOff === true;
+ if (off) {
+ if (Array.isArray(reasoning.disable)) {
+ const warning = warningFor(reasoning.warnings, "disable");
+ if (warning && !choices.acceptServedModelChange) {
+ result.notes.push(
+ `turning reasoning off is served by ${warning.servedModel} on this connection; reasoning kept on (${warning.code})`
+ );
+ off = false;
+ } else {
+ writeAssignments(put, reasoning.disable);
+ result.notes.push(
+ warning
+ ? `reasoning off: served by ${warning.servedModel} (${warning.code}, accepted)`
+ : "reasoning off"
+ );
+ return;
+ }
+ } else {
+ result.notes.push(
+ `reasoning cannot be turned off on this connection (disable ${reasoning.disable.status})`
+ );
+ off = false;
+ }
+ }
+
+ if (Array.isArray(reasoning.enable)) {
+ const warning = warningFor(reasoning.warnings, "enable");
+ if (warning && !choices.acceptServedModelChange) {
+ result.notes.push(
+ `enabling reasoning is served by ${warning.servedModel} on this connection; enable not sent (${warning.code})`
+ );
+ } else {
+ writeAssignments(put, reasoning.enable);
+ }
+ }
+
+ const effort = reasoning.effort;
+ if (!("path" in effort)) return;
+ const published = Object.keys(effort.values);
+ let name: string | undefined;
+ if (choices.hasTools && toolsWithReasoning === "requires-effort-none") {
+ name = published.includes("none") ? "none" : undefined;
+ if (!name) {
+ result.notes.push(
+ "tools require effort none on this connection, which publishes none: effort omitted"
+ );
+ return;
+ }
+ } else if (choices.reasoningOff) {
+ // Reasoning could not be turned off: the least published effort is the
+ // closest honest answer to "off".
+ name = clampEffort("none", published);
+ } else if (choices.effort) {
+ name = clampEffort(choices.effort, published);
+ if (name !== choices.effort) {
+ result.notes.push(
+ `effort ${choices.effort} → ${name ?? "omitted"} (published: ${published.join(", ")})`
+ );
+ }
+ } else if (typeof effort.default === "string") {
+ name = effort.default;
+ }
+ if (!name) return;
+ put(effort.path, effort.values[name] as WireValue);
+ result.sentEffort = name;
+}
+
+// ─── The user's choices, read from Claude Code's request ──────────────────
+
+/**
+ * The catalog effort name and on/off intent Claude Code's request carries.
+ *
+ * `--effort` (pinned) wins. Then `output_config.effort`, the level Claude Code
+ * sends. A legacy `thinking.budget_tokens` is translated into a catalog effort
+ * name — the only use a budget ladder may still have; it never picks a wire
+ * field. `thinking.type: "disabled"` or effort `none` means reasoning off.
+ */
+export function wireChoicesFromClaudeRequest(
+ claudeRequest: any,
+ pinnedEffort?: string
+): Pick<WireChoices, "effort" | "reasoningOff" | "hasTools" | "maxTokens"> {
+ let effort: string | undefined = pinnedEffort;
+ if (!effort) {
+ const level = claudeRequest?.output_config?.effort;
+ if (typeof level === "string" && effortRank(level.toLowerCase()) >= 0)
+ effort = level.toLowerCase();
+ }
+ if (!effort) {
+ const budget = claudeRequest?.thinking?.budget_tokens;
+ if (typeof budget === "number") {
+ effort =
+ budget <= 0
+ ? "none"
+ : budget < 4000
+ ? "low"
+ : budget < 16000
+ ? "medium"
+ : budget < 32000
+ ? "high"
+ : "xhigh";
+ }
+ }
+ const reasoningOff = claudeRequest?.thinking?.type === "disabled" || effort === "none";
+ return {
+ effort: effort === "none" ? undefined : effort,
+ reasoningOff,
+ hasTools: Array.isArray(claudeRequest?.tools) && claudeRequest.tools.length > 0,
+ maxTokens: typeof claudeRequest?.max_tokens === "number" ? claudeRequest.max_tokens : undefined,
+ };
+}
+
+// ─── Entry point ───────────────────────────────────────────────────────────
+
+/**
+ * Shape `body` from `wire`.
+ *
+ * `owner` is the wire of the model owner's own direct connection, when the
+ * catalog knows it. It fills ONLY a sub-field this connection publishes as
+ * `unknown`, ONLY on the same API (a different API's fields mean nothing here),
+ * and never mode or speed, which carry entitlement and price. Every pointer so
+ * written is returned in `borrowed`, so a 400 naming it is retried without it:
+ * try in turn, never a silent guess (Jack's decision B1).
+ */
+export function shapeRequestFromWire(
+ body: Record<string, unknown>,
+ wire: KnownWire,
+ choices: WireChoices,
+ owner?: KnownWire
+): WireShapeResult {
+ const result: WireShapeResult = { headers: [], notes: [], borrowed: [] };
+ stripWireDecisions(body, wire.api);
+ const own: PointerWriter = (path, value) => setPointer(body, path, value);
+ const borrow: PointerWriter = (path, value) => {
+ setPointer(body, path, value);
+ if (!result.borrowed.includes(path)) result.borrowed.push(path);
+ };
+ const sameApiOwner = owner && owner !== wire && owner.api === wire.api ? owner : undefined;
+
+ if (typeof wire.tokenParam === "string") {
+ if (typeof choices.maxTokens === "number") body[wire.tokenParam] = choices.maxTokens;
+ } else if (wire.api !== "gemini") {
+ // Only an UNKNOWN field is tried from the owner; `not_applicable` is an
+ // answer (this connection takes no limit field), not a gap.
+ if (
+ wire.tokenParam.status === "unknown" &&
+ sameApiOwner &&
+ typeof sameApiOwner.tokenParam === "string" &&
+ typeof choices.maxTokens === "number"
+ ) {
+ borrow(`/${sameApiOwner.tokenParam}`, choices.maxTokens);
+ result.notes.push(
+ `tokenParam ${wire.tokenParam.status}: trying the owner's ${sameApiOwner.tokenParam}`
+ );
+ } else {
+ result.notes.push(`tokenParam ${wire.tokenParam.status}: no output limit sent`);
+ }
+ }
+
+ if (wire.reasoning.status === "unknown" && sameApiOwner?.reasoning.status === "supported") {
+ result.notes.push("reasoning unknown: trying the owner's encoding");
+ const toolsWithReasoning =
+ typeof wire.toolsWithReasoning === "string"
+ ? wire.toolsWithReasoning
+ : sameApiOwner.toolsWithReasoning;
+ applyReasoning(borrow, sameApiOwner.reasoning, toolsWithReasoning, choices, result);
+ } else {
+ applyReasoning(own, wire.reasoning, wire.toolsWithReasoning, choices, result);
+ }
+
+ if (choices.mode) {
+ const control = wire.reasoning.status === "supported" ? wire.reasoning.mode : wire.reasoning;
+ applyControl(body, control, choices.mode.value, "mode", choices.mode.explicit, result);
+ }
+ if (choices.speed) {
+ applyControl(body, wire.speed, choices.speed.value, "speed", choices.speed.explicit, result);
+ }
+ return result;
+}
+
+/**
+ * The resend for a 4xx when the request carried fields borrowed from the
+ * owner's connection: without the borrowed fields the error names (by the
+ * pointer's last segment, e.g. `reasoning_effort`, `max_completion_tokens`),
+ * or without all of them when a 400 rejects a parameter without naming which.
+ * `null` when nothing was borrowed or the error is not about a parameter.
+ * Returns a new payload; the original is not mutated.
+ */
+export function recoverBorrowedWireFields(
+ payload: Record<string, unknown>,
+ borrowed: string[],
+ errorText: string
+): { payload: Record<string, unknown>; note: string } | null {
+ if (borrowed.length === 0 || !errorText) return null;
+ // A field is named only as a whole identifier: `max_tokens` in "Unknown
+ // parameter: 'max_tokens'", never `x` inside "exceeded".
+ const named = borrowed.filter((path) =>
+ pointerTokens(path).some((token) =>
+ new RegExp(
+ `(^|[^A-Za-z0-9_])${token.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}($|[^A-Za-z0-9_])`
+ ).test(errorText)
+ )
+ );
+ const generic =
+ /unknown|unrecognized|unsupported|not supported|not allowed|not permitted|extra (inputs|fields)|invalid (param|field|argument)/i.test(
+ errorText
+ );
+ const drop = named.length > 0 ? named : generic ? borrowed : [];
+ if (drop.length === 0) return null;
+ const next = structuredClone(payload);
+ for (const path of drop) deletePointer(next, path);
+ return {
+ payload: next,
+ note: `dropped ${drop.join(", ")} (borrowed from the owner's connection; this connection's value is unknown)`,
+ };
+}
+
+/**
+ * Merge wire headers into a header map: each value is appended to an existing
+ * comma-separated header, never duplicated, never replacing what is there
+ * (Anthropic fast mode's beta token sits next to the OAuth beta).
+ */
+export function mergeWireHeaders(headers: Record<string, string>, extra: WireHeader[]): void {
+ for (const header of extra) {
+ const key =
+ Object.keys(headers).find((name) => name.toLowerCase() === header.name.toLowerCase()) ??
+ header.name;
+ const existing = headers[key];
+ if (!existing) {
+ headers[key] = header.value;
+ continue;
+ }
+ const tokens = existing.split(",").map((token) => token.trim());
+ if (!tokens.includes(header.value)) headers[key] = `${existing},${header.value}`;
+ }
+}
diff --git a/packages/cli/src/providers/wire-try-in-turn.test.ts b/packages/cli/src/providers/wire-try-in-turn.test.ts
new file mode 100644
index 00000000..b5ccb37b
--- /dev/null
+++ b/packages/cli/src/providers/wire-try-in-turn.test.ts
@@ -0,0 +1,94 @@
+import { beforeEach, expect, test } from "bun:test";
+import { Hono } from "hono";
+import type { WireApi } from "./connection-wire.js";
+import {
+ TryInTurnHandler,
+ _clearTryInTurnMemory,
+ apiOnlyWire,
+ isProtocolMismatch,
+ tryInTurnOrder,
+} from "./wire-try-in-turn.js";
+
+beforeEach(_clearTryInTurnMemory);
+test.each([
+ [404, "missing", true],
+ [405, "method", true],
+ [400, "wrong protocol", true],
+ [400, "Use the v1/responses endpoint", true],
+ [400, "Unsupported parameter: 'messages'", true],
+ [400, '{"error":{"upstream_status":404}}', true],
+ [401, "protocol", false],
+ [403, "endpoint", false],
+ [429, "protocol", false],
+ [500, "endpoint", false],
+ [400, "invalid value", false],
+] as const)("mismatch %s %s", (status, body, expected) =>
+ expect(isProtocolMismatch(status, body)).toBe(expected)
+);
+test("orders only published APIs", () =>
+ expect(tryInTurnOrder(["gemini", "chat-completions", "responses"], "key")).toEqual([
+ "responses",
+ "chat-completions",
+ "gemini",
+ ]));
+function harness(statuses: Partial<Record<WireApi, number>>) {
+ const calls: WireApi[] = [];
+ const handler = new TryInTurnHandler(
+ "key",
+ "fixture connection",
+ Object.keys(statuses) as WireApi[],
+ (api) => ({
+ async handle(_c, payload) {
+ expect(payload).toEqual({ original: true });
+ payload.original = false;
+ calls.push(api);
+ return new Response(api, { status: statuses[api] });
+ },
+ async shutdown() {},
+ })
+ );
+ const app = new Hono();
+ app.post("/", (c) => handler.handle(c, { original: true }));
+ return { calls, request: () => app.request("/", { method: "POST" }) };
+}
+test("advances on mismatch and remembers success for the second request", async () => {
+ const h = harness({ responses: 404, "chat-completions": 200 });
+ expect((await h.request()).status).toBe(200);
+ expect(h.calls).toEqual(["responses", "chat-completions"]);
+ expect(tryInTurnOrder(["responses", "chat-completions"], "key")).toEqual([
+ "chat-completions",
+ "responses",
+ ]);
+ await h.request();
+ expect(h.calls).toEqual(["responses", "chat-completions", "chat-completions"]);
+ expect(tryInTurnOrder(["responses", "chat-completions"], "other-generation")).toEqual([
+ "responses",
+ "chat-completions",
+ ]);
+});
+test.each([400, 401, 403, 429, 500])("stops at non-mismatch %s", async (status) => {
+ const h = harness({ responses: status, "chat-completions": 200 });
+ expect((await h.request()).status).toBe(status);
+ expect(h.calls).toEqual(["responses"]);
+});
+test("returns last mismatch when all APIs fail", async () => {
+ const h = harness({ responses: 404, "chat-completions": 405 });
+ const response = await h.request();
+ expect(response.status).toBe(405);
+ expect(await response.text()).toBe("chat-completions");
+ expect(h.calls).toEqual(["responses", "chat-completions"]);
+});
+test.each(["responses", "chat-completions", "anthropic-messages", "gemini"] as const)(
+ "API-only %s has no guessed decisions",
+ (api) => {
+ expect(apiOnlyWire(api)).toEqual({
+ status: "known",
+ api,
+ tokenParam: { status: api === "gemini" ? "not_applicable" : "unknown" },
+ toolsWithReasoning: { status: "unknown" },
+ reasoning: { status: "unknown" },
+ speed: { status: "unknown" },
+ evidence: [],
+ });
+ }
+);
diff --git a/packages/cli/src/providers/wire-try-in-turn.ts b/packages/cli/src/providers/wire-try-in-turn.ts
new file mode 100644
index 00000000..7e3981ef
--- /dev/null
+++ b/packages/cli/src/providers/wire-try-in-turn.ts
@@ -0,0 +1,132 @@
+/**
+ * A connection whose wire nobody established — `wire.status: "unknown"`, or a
+ * model the catalog does not publish on this provider at all — is not guessed
+ * at. Its route profile still publishes which APIs the host serves, so each is
+ * tried in turn (catalog 3.7.0 R4; Jack's decision 3.2):
+ *
+ * - order: `responses`, `anthropic-messages`, `chat-completions`, `gemini`,
+ * restricted to the profile's `apis`, with the API that last worked first;
+ * - advance ONLY on a protocol mismatch: 404, 405, or a 400 whose body says the
+ * endpoint or protocol is wrong. Never on 401, 403, 429, 5xx or a network
+ * error, which say nothing about the API;
+ * - no output limit and no reasoning field is sent while trying, because no
+ * source established either for this connection;
+ * - what worked is remembered per connection until the next catalog
+ * generation, and every fallback is logged: each one is a gap Models Index
+ * should close.
+ */
+import type { Context } from "hono";
+import { extractUpstreamStatus } from "../handlers/shared/anthropic-error.js";
+import type { ModelHandler } from "../handlers/types.js";
+import { log } from "../logger.js";
+import type { KnownWire, WireApi } from "./connection-wire.js";
+
+export const TRY_IN_TURN_ORDER: readonly WireApi[] = [
+ "responses",
+ "anthropic-messages",
+ "chat-completions",
+ "gemini",
+];
+
+/** A wire that establishes the API and nothing else. */
+export function apiOnlyWire(api: WireApi): KnownWire {
+ return {
+ status: "known",
+ api,
+ tokenParam: api === "gemini" ? { status: "not_applicable" } : { status: "unknown" },
+ toolsWithReasoning: { status: "unknown" },
+ reasoning: { status: "unknown" },
+ speed: { status: "unknown" },
+ evidence: [],
+ };
+}
+
+/**
+ * Whether an error answer says "wrong API for this model". The status is the
+ * upstream's own, recovered from the body when the handler remapped it to 400.
+ */
+export function isProtocolMismatch(status: number, body: string): boolean {
+ const upstream = extractUpstreamStatus(body) ?? status;
+ if (upstream === 404 || upstream === 405) return true;
+ if (upstream !== 400) return false;
+ return /protocol|endpoint|unsupported api|use the v1\/\w+|has moved to 'input'|unsupported parameter: 'messages'|unknown (field|parameter)[^.]{0,20}'(messages|input|contents)'/i.test(
+ body
+ );
+}
+
+const remembered = new Map<string, WireApi>();
+
+export function _clearTryInTurnMemory(): void {
+ remembered.clear();
+}
+
+export function tryInTurnOrder(apis: WireApi[], key: string): WireApi[] {
+ const ordered = TRY_IN_TURN_ORDER.filter((api) => apis.includes(api));
+ const winner = remembered.get(key);
+ return winner && ordered.includes(winner)
+ ? [winner, ...ordered.filter((a) => a !== winner)]
+ : ordered;
+}
+
+export class TryInTurnHandler implements ModelHandler {
+ private readonly handlers = new Map<WireApi, ModelHandler | null>();
+
+ /**
+ * @param key Connection identity plus generation: what worked is remembered under it.
+ * @param label `route · wire id`, for the log.
+ * @param apis The route profile's published APIs.
+ * @param build Builds the handler for one API (an {@link apiOnlyWire} connection).
+ */
+ constructor(
+ private readonly key: string,
+ private readonly label: string,
+ private readonly apis: WireApi[],
+ private readonly build: (api: WireApi) => ModelHandler | null
+ ) {}
+
+ private handlerFor(api: WireApi): ModelHandler | null {
+ if (!this.handlers.has(api)) this.handlers.set(api, this.build(api));
+ return this.handlers.get(api) ?? null;
+ }
+
+ async handle(c: Context, payload: any): Promise<Response> {
+ let last: Response | undefined;
+ for (const api of tryInTurnOrder(this.apis, this.key)) {
+ const handler = this.handlerFor(api);
+ if (!handler) continue;
+ const response = await handler.handle(c, structuredClone(payload));
+ if (response.ok) {
+ if (remembered.get(this.key) !== api) {
+ remembered.set(this.key, api);
+ log(
+ `[Wire] ${this.label}: wire unknown — ${api} answered; remembered until the next generation`
+ );
+ }
+ return response;
+ }
+ const body = await response.clone().text();
+ if (!isProtocolMismatch(response.status, body)) return response;
+ log(
+ `[Wire] ${this.label}: wire unknown — ${api} is not this model's API (${response.status}); trying the next`
+ );
+ last = response;
+ }
+ return (
+ last ??
+ new Response(
+ JSON.stringify({
+ type: "error",
+ error: {
+ type: "invalid_request_error",
+ message: `claudish: ${this.label} has no API in its route profile that claudish can call`,
+ },
+ }),
+ { status: 400, headers: { "Content-Type": "application/json" } }
+ )
+ );
+ }
+
+ async shutdown(): Promise<void> {
+ for (const handler of this.handlers.values()) await handler?.shutdown();
+ }
+}
diff --git a/packages/cli/src/proxy-server.ts b/packages/cli/src/proxy-server.ts
index b85cf008..6791aca3 100644
--- a/packages/cli/src/proxy-server.ts
+++ b/packages/cli/src/proxy-server.ts
@@ -34,6 +34,7 @@ import {
resolveTargetForCatalog,
warmCatalog,
} from "./providers/catalog-client.js";
+import { type ResolvedConnection, resolveConnection } from "./providers/connection-resolver.js";
import { getEndpointUnavailableReason } from "./providers/endpoint-diagnostics.js";
import {
ensureEndpointsRegistered,
@@ -62,6 +63,13 @@ import { LocalTransport } from "./providers/transport/local.js";
import { OpenRouterProviderTransport } from "./providers/transport/openrouter.js";
import { PoeProvider } from "./providers/transport/poe.js";
import type { ProviderTransport } from "./providers/transport/types.js";
+import { RefusingHandler } from "./providers/wire-handler.js";
+import {
+ WireMarkerError,
+ WireMarkerHandler,
+ type WireMarkers,
+ splitWireMarkers,
+} from "./providers/wire-markers.js";
import { closeAllEpisodes } from "./recovery/coordinator.js";
import { warmPricingCache } from "./services/pricing-cache.js";
import type { ProxyServer } from "./types.js";
@@ -321,6 +329,33 @@ export async function createProxyServer(
const remoteProviderHandlers = new Map<string, ModelHandler>(); // Map from Target Model ID -> Gemini/OpenAI Handler
const poeHandlers = new Map<string, ModelHandler>(); // Map from Target Model ID -> Poe Handler
+ // The catalog connection behind a gateway handler built here rather than by
+ // a profile (OpenRouter, the legacy `poe:` prefix). Both speak Chat
+ // Completions only, so a known wire on another API — or an unsupported one —
+ // is refused rather than sent a chat body; an unknown wire keeps the
+ // gateway's own handler.
+ const chatWireConnection = (
+ provider: string,
+ modelId: string
+ ): { connection?: ResolvedConnection; refusal?: string } => {
+ const resolution = resolveConnection(provider, modelId);
+ if (!resolution.ok) return {};
+ const { connection } = resolution;
+ const where = `${connection.route.routeId}/${connection.route.routeProfileId} · ${connection.externalModelId}`;
+ if (connection.wire.status === "unsupported") {
+ return {
+ refusal: `${where} speaks ${connection.wire.protocol}, which claudish does not implement`,
+ };
+ }
+ if (connection.wire.status !== "known") return {};
+ if (connection.wire.api !== "chat-completions") {
+ return {
+ refusal: `${where} is published on ${connection.wire.api}, which this gateway handler does not speak`,
+ };
+ }
+ return { connection };
+ };
+
// Helper to get or create OpenRouter handler for a target model
const getOpenRouterHandler = (
targetModel: string,
@@ -334,6 +369,11 @@ export async function createProxyServer(
const modelId = targetModel.includes("@") ? parsed.model : targetModel;
if (!openRouterHandlers.has(modelId)) {
+ const wired = chatWireConnection("openrouter", modelId);
+ if (wired.refusal) {
+ openRouterHandlers.set(modelId, new RefusingHandler(wired.refusal));
+ return openRouterHandlers.get(modelId)!;
+ }
// The OpenRouter key is resolved through the credential authority inside
// the transport's getHeaders() (single source of truth) — the legacy
// openrouterApiKey param is no longer the signing source.
@@ -346,6 +386,7 @@ export async function createProxyServer(
isInteractive: options.isInteractive,
invocationMode,
...requestShapingOpts,
+ connection: wired.connection,
})
);
}
@@ -365,6 +406,11 @@ export async function createProxyServer(
// Strip "poe:" prefix to get the actual model name for the API
const modelId = targetModel.replace(/^poe:/, "");
if (!poeHandlers.has(modelId)) {
+ const wired = chatWireConnection("poe", modelId);
+ if (wired.refusal) {
+ poeHandlers.set(modelId, new RefusingHandler(wired.refusal));
+ return poeHandlers.get(modelId)!;
+ }
// The transport resolves its key through the authority in getHeaders().
const poeTransport = new PoeProvider();
poeHandlers.set(
@@ -373,6 +419,7 @@ export async function createProxyServer(
isInteractive: options.isInteractive,
invocationMode,
...requestShapingOpts,
+ connection: wired.connection,
})
);
}
@@ -628,7 +675,23 @@ export async function createProxyServer(
return "auto-route";
};
+ // `+mode` / `#speed` markers ride on the model spec (`oai@gpt-6-sol+pro#fast`).
+ // They are split off the resolved target once, here: everything below sees
+ // the model alone, and the markers travel with the REQUEST
+ // (`wireMarkerContext`), never with a cached handler or in a body.
const getHandlerForRequest = async (requestedModel: string): Promise<ModelHandler> => {
+ const out: { markers?: WireMarkers; refusal?: string } = {};
+ const handler = await resolveHandlerForRequest(requestedModel, out);
+ if (out.refusal) return new RefusingHandler(out.refusal);
+ return out.markers && (out.markers.mode || out.markers.speed)
+ ? new WireMarkerHandler(handler, out.markers)
+ : handler;
+ };
+
+ const resolveHandlerForRequest = async (
+ requestedModel: string,
+ out: { markers?: WireMarkers; refusal?: string }
+ ): Promise<ModelHandler> => {
// 1. Monitor Mode Override
if (monitorMode) return nativeHandler;
@@ -681,6 +744,20 @@ export async function createProxyServer(
target = model;
}
+ try {
+ const markers = splitWireMarkers(target);
+ if (markers.mode || markers.speed) {
+ out.markers = markers;
+ target = markers.spec;
+ }
+ } catch (err) {
+ if (err instanceof WireMarkerError) {
+ out.refusal = err.message;
+ return nativeHandler;
+ }
+ throw err;
+ }
+
const invocationMode = detectInvocationMode(target, wasFromModelMap);
// 2a-chain. A PINNED CHAIN from a parent process.
diff --git a/packages/cli/src/session-events/pro-injection.ts b/packages/cli/src/session-events/pro-injection.ts
index d66a2f71..5e0c5fe5 100644
--- a/packages/cli/src/session-events/pro-injection.ts
+++ b/packages/cli/src/session-events/pro-injection.ts
@@ -102,6 +102,31 @@ export interface ProInjectionOptions {
export function applyProInjection(
requestPayload: Record<string, any>,
opts: ProInjectionOptions
+): boolean {
+ try {
+ if (!isUltracodeMainTurn(opts)) return false;
+ // Capability gate LAST: it is the only gate that touches the filesystem.
+ const resolved = resolveVariantPreset(opts.bareModelName, opts.provider, opts.cachePath);
+ if (!resolved) return false;
+ deepMergeParams(requestPayload, resolved.params);
+ log(
+ `[SessionEvents] ultracode active → preset ${resolved.preset} for ${opts.targetModel} ` +
+ `(catalog ${resolved.sourceLabel}, session ${opts.sessionId})`
+ );
+ return true;
+ } catch {
+ return false;
+ }
+}
+
+/**
+ * Whether this request is an ultracode main-loop turn with `proOnUltracode` on:
+ * the gates of {@link applyProInjection} without the capability lookup. A
+ * catalog connection asks this, then sends pro only where its own
+ * `wire.reasoning.mode` publishes it. Never throws.
+ */
+export function isUltracodeMainTurn(
+ opts: Pick<ProInjectionOptions, "enabled" | "sessionId" | "outputConfig" | "registry">
): boolean {
try {
if (!opts.enabled || !opts.sessionId) return false;
@@ -131,16 +156,7 @@ export function applyProInjection(
registry.ensureSession(opts.sessionId);
registry.sync(opts.sessionId);
const state = registry.getState(opts.sessionId);
- if (!state?.ultracodeActive) return false;
- // Capability gate LAST: it is the only gate that touches the filesystem.
- const resolved = resolveVariantPreset(opts.bareModelName, opts.provider, opts.cachePath);
- if (!resolved) return false;
- deepMergeParams(requestPayload, resolved.params);
- log(
- `[SessionEvents] ultracode active → preset ${resolved.preset} for ${opts.targetModel} ` +
- `(catalog ${resolved.sourceLabel}, session ${opts.sessionId})`
- );
- return true;
+ return state?.ultracodeActive === true;
} catch {
return false;
}