Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
fix(adapters): forward stop_sequences as stop, and top_p (item 11)
Jack Rudenko912031e61128
diff --git a/packages/cli/src/adapters/base-api-format.ts b/packages/cli/src/adapters/base-api-format.tsindex f9212368..abc6f5b8 100644--- a/packages/cli/src/adapters/base-api-format.ts+++ b/packages/cli/src/adapters/base-api-format.ts@@ -15,8 +15,17 @@ import type { StreamFormat } from "../providers/transport/types.js";import type { APIFormat } from "./api-format.js";import { type ReasoningCapability, lookupModel, lookupModelReasoning } from "./model-catalog.js";import type { ModelDialect } from "./model-dialect.js";+import { rejectedOptionalParams } from "./optional-param-rejection.js";import { truncateToolName } from "./tool-name-utils.js";+/**+ * The OPTIONAL parameters {@link BaseAPIFormat.applyOpenAISamplingParams} adds+ * speculatively, and therefore the only ones+ * {@link BaseAPIFormat.recoverFromRejection} will remove. Anything else in the+ * payload is either required or owned by a dialect that must recover it itself.+ */+const OPTIONAL_SAMPLING_PARAMS: readonly string[] = ["stop", "top_p"];+/*** Match a model ID against a model family name, handling vendor-prefixed IDs.*@@ -155,11 +164,81 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {abstract getName(): string;/**- * Optional: repair a request that a provider rejected because of an OPTIONAL- * parameter this dialect added speculatively. See `ModelDialect` for the full+ * Repair a request that a provider rejected because of an OPTIONAL parameter+ * this format/dialect added speculatively. See `ModelDialect` for the full* rationale; ComposedHandler calls it at most once per request.+ *+ * The base implementation covers the sampling controls+ * {@link applyOpenAISamplingParams} forwards. A dialect that overrides this+ * for its own parameter MUST end by delegating to `super`, or it silently+ * removes that cover for its own models (GrokModelDialect does).+ */+ recoverFromRejection(payload: any, errorText: string): { payload: any; note: string } | null {+ return this.recoverFromSamplingParamRejection(payload, errorText);+ }++ /**+ * Drop whichever of {@link OPTIONAL_SAMPLING_PARAMS} this 4xx named, or+ * return null when it named none.+ *+ * Narrow on purpose: a missed recovery is a visible failed request, while a+ * wrong one silently strips a parameter the model did accept.*/- recoverFromRejection?(payload: any, errorText: string): { payload: any; note: string } | null;+ protected recoverFromSamplingParamRejection(+ payload: any,+ errorText: string+ ): { payload: any; note: string } | null {+ if (!payload) return null;+ const present = OPTIONAL_SAMPLING_PARAMS.filter((p) => payload[p] !== undefined);+ if (present.length === 0) return null;++ const rejected = rejectedOptionalParams(errorText, present);+ if (rejected.length === 0) return null;++ const next = { ...payload };+ for (const p of rejected) delete next[p];+ return { payload: next, note: `dropped ${rejected.join(", ")} for ${this.modelId}` };+ }++ /**+ * Forward the two sampling controls Claude Code sends that every+ * OpenAI-shaped builder in this tree used to drop: `stop_sequences` → `stop`,+ * and `top_p`.+ *+ * `stop` matters more than it looks. Claude Code's own classifier requests+ * carry stop sequences, and a relay that never receives them keeps generating+ * past the point the caller said to stop — which reads as a slow, rambling+ * model rather than as a dropped parameter. `anthropic-api-format.ts` already+ * forwards `stop_sequences` on the Anthropic wire, so this closes the+ * OpenAI-shaped half only.+ *+ * Both are OPTIONAL parameters sent speculatively:+ * {@link recoverFromRejection} drops whichever one a strict relay rejects and+ * the request is retried once.+ *+ * No cap is applied to the sequence count. OpenAI documents a limit of four,+ * but capping here would silently discard the fifth sequence — the failure+ * mode this repo keeps paying for — whereas sending all of them fails loudly+ * and recovers.+ *+ * @param payload - the provider payload being built (mutated in place)+ * @param claudeRequest - the inbound Anthropic-shaped request+ */+ protected applyOpenAISamplingParams(payload: any, claudeRequest: any): void {+ if (!payload || !claudeRequest) return;++ const sequences = claudeRequest.stop_sequences;+ if (Array.isArray(sequences)) {+ // An empty string is not a stop sequence anywhere, and strict relays 400+ // on one. Dropping the empty entries keeps the real ones.+ const usable = sequences.filter((s: unknown) => typeof s === "string" && s.length > 0);+ if (usable.length > 0) payload.stop = usable;+ }++ if (claudeRequest.top_p !== undefined && claudeRequest.top_p !== null) {+ payload.top_p = claudeRequest.top_p;+ }+ }/*** Maximum tool name length allowed by this model's API.@@ -593,6 +672,7 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {if (claudeRequest.temperature !== undefined) {payload.temperature = claudeRequest.temperature;}+ this.applyOpenAISamplingParams(payload, claudeRequest);return payload;}diff --git a/packages/cli/src/adapters/grok-model-dialect.ts b/packages/cli/src/adapters/grok-model-dialect.tsindex a5f60a33..5da3d92c 100644--- a/packages/cli/src/adapters/grok-model-dialect.ts+++ b/packages/cli/src/adapters/grok-model-dialect.ts@@ -212,35 +212,41 @@ export class GrokModelDialect extends BaseAPIFormat {* multi-agent models are not served on chat completions at all. Retrying that* without the parameter fails identically, so it must not match here.*/- recoverFromRejection(payload: any, errorText: string): { payload: any; note: string } | null {- if (!payload || payload.reasoning_effort === undefined) return null;-- // Case 1: the model does not take the parameter at all → drop it for good.- if (isReasoningEffortRejection(errorText)) {- rememberReasoningEffortRejected(this.modelId);- const next = { ...payload };- delete next.reasoning_effort;- return { payload: next, note: `dropped reasoning_effort for ${this.modelId}` };- }+ override recoverFromRejection(+ payload: any,+ errorText: string+ ): { payload: any; note: string } | null {+ if (payload?.reasoning_effort !== undefined) {+ // Case 1: the model does not take the parameter at all → drop it for good.+ if (isReasoningEffortRejection(errorText)) {+ rememberReasoningEffortRejected(this.modelId);+ const next = { ...payload };+ delete next.reasoning_effort;+ return { payload: next, note: `dropped reasoning_effort for ${this.modelId}` };+ }- // Case 2: the parameter is fine but this VALUE is not → step down one rung.- const rejected = rejectedReasoningEffortValue(errorText);- if (rejected) {- rememberReasoningEffortValueRejected(this.modelId, rejected);- const fallback = fallbackReasoningEffortValue(rejected);- const next = { ...payload };- if (fallback) {- next.reasoning_effort = fallback;- return {- payload: next,- note: `reasoning_effort "${rejected}" -> "${fallback}" for ${this.modelId}`,- };+ // Case 2: the parameter is fine but this VALUE is not → step down one rung.+ const rejected = rejectedReasoningEffortValue(errorText);+ if (rejected) {+ rememberReasoningEffortValueRejected(this.modelId, rejected);+ const fallback = fallbackReasoningEffortValue(rejected);+ const next = { ...payload };+ if (fallback) {+ next.reasoning_effort = fallback;+ return {+ payload: next,+ note: `reasoning_effort "${rejected}" -> "${fallback}" for ${this.modelId}`,+ };+ }+ delete next.reasoning_effort;+ return { payload: next, note: `dropped unsupported reasoning_effort for ${this.modelId}` };}- delete next.reasoning_effort;- return { payload: next, note: `dropped unsupported reasoning_effort for ${this.modelId}` };}- return null;+ // Not about reasoning_effort (or none was sent): let the base try its own+ // speculative parameters. Dropping this delegation would silently remove+ // stop/top_p recovery for every grok model.+ return super.recoverFromRejection(payload, errorText);}/**diff --git a/packages/cli/src/adapters/litellm-api-format.ts b/packages/cli/src/adapters/litellm-api-format.tsindex 9162f693..55685942 100644--- a/packages/cli/src/adapters/litellm-api-format.ts+++ b/packages/cli/src/adapters/litellm-api-format.ts@@ -119,6 +119,8 @@ export class LiteLLMAPIFormat extends DefaultAPIFormat {}}+ this.applyOpenAISamplingParams(payload, claudeRequest);+return payload;}diff --git a/packages/cli/src/adapters/local-adapter.ts b/packages/cli/src/adapters/local-adapter.tsindex 9bbfad98..ab6d2cef 100644--- a/packages/cli/src/adapters/local-adapter.ts+++ b/packages/cli/src/adapters/local-adapter.ts@@ -127,6 +127,11 @@ export class LocalModelAdapter extends BaseAPIFormat {}}+ // AFTER the literal above, so an explicit caller `top_p` wins over the+ // family default this adapter picked. The default is a guess about the+ // model; the request is a statement about this turn.+ this.applyOpenAISamplingParams(payload, claudeRequest);+return payload;}diff --git a/packages/cli/src/adapters/openai-api-format.ts b/packages/cli/src/adapters/openai-api-format.tsindex f67093d3..f66437cc 100644--- a/packages/cli/src/adapters/openai-api-format.ts+++ b/packages/cli/src/adapters/openai-api-format.ts@@ -349,6 +349,8 @@ export class OpenAIAPIFormat extends BaseAPIFormat {}}+ this.applyOpenAISamplingParams(payload, claudeRequest);+return payload;}}diff --git a/packages/cli/src/adapters/openrouter-api-format.ts b/packages/cli/src/adapters/openrouter-api-format.tsindex 4fa2d0f1..a05ee647 100644--- a/packages/cli/src/adapters/openrouter-api-format.ts+++ b/packages/cli/src/adapters/openrouter-api-format.ts@@ -139,6 +139,8 @@ export class OpenRouterAPIFormat extends BaseAPIFormat {}}+ this.applyOpenAISamplingParams(payload, claudeRequest);+return payload;}diff --git a/packages/cli/src/adapters/optional-param-rejection.ts b/packages/cli/src/adapters/optional-param-rejection.tsnew file mode 100644index 00000000..2b209e27--- /dev/null+++ b/packages/cli/src/adapters/optional-param-rejection.ts@@ -0,0 +1,89 @@+/**+ * Which OPTIONAL request parameters an upstream 4xx is complaining about.+ *+ * ## Why this module exists+ *+ * A dialect that forwards a parameter speculatively needs a way back when the+ * relay does not know it. The alternative — withholding the parameter from+ * every endpoint that cannot be *proven* to accept it — fails silently: the+ * caller's `stop_sequences` simply stop working and nothing says so. Sending it+ * fails loudly, once, and is repaired in a single round-trip+ * (`ComposedHandler` bounds the recovery to one attempt).+ *+ * That is the same trade `grok-effort-support.ts` documents for+ * `reasoning_effort`. This module is its general form, used by+ * {@link BaseAPIFormat.recoverFromRejection} for the parameters the OpenAI-shaped+ * payload builders add.+ *+ * ## The detection is deliberately narrow+ *+ * Two gates must BOTH pass before a parameter is called rejected:+ *+ * 1. the body reads as a complaint about a parameter at all, and+ * 2. the parameter name occupies a *field* position in it — quoted, named as a+ * parameter/argument/field/property, or leading its own message.+ *+ * Gate 2 is what keeps `stop` — an ordinary English word — from matching prose.+ * A body that merely contains the word (`"please stop retrying"`) names no+ * field and is not a rejection. When in doubt this returns nothing: a missed+ * recovery costs one failed request the user can see, while a wrong one silently+ * strips a parameter the model did accept.+ *+ * **Provenance of the shapes below**: they are the documented/known error+ * wordings of OpenAI-compatible relays (OpenAI, vLLM, xAI, Anthropic-shaped+ * validators), written here from the field names they use — NOT captured from a+ * live 4xx in this repo. The tests pin the wordings, not any provider's promise+ * to keep using them.+ */++/**+ * The body reads as a complaint about a request parameter.+ *+ * Checked before any name match so that an unrelated 4xx (rate limit, auth,+ * content filter) can never strip a parameter.+ */+const PARAMETER_COMPLAINT =+ /(unknown|unrecognized|unexpected|unsupported|not supported|does not support|invalid|not permitted|not allowed|extra (fields|inputs))/i;++/** Regex-escape a parameter name so a dotted name cannot act as a wildcard. */+function escapeName(name: string): string {+ return name.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");+}++/**+ * Does `errorText` name `param` in a FIELD position (not as prose)?+ *+ * Three accepted forms, each seen in the wild:+ * · quoted — `Unexpected keyword argument 'stop'`+ * · introduced — `Unrecognized request argument supplied: stop`,+ * `does not support parameter top_p`+ * · leading its own message — `{"message":"stop: Extra inputs are not permitted"}`+ */+function namesParameterField(errorText: string, param: string): boolean {+ const p = escapeName(param);+ const tail = "(?![A-Za-z0-9_])";+ const quoted = new RegExp(`['"\`]${p}['"\`]`);+ // `argument supplied: stop` / `does not support parameter top_p`: the noun,+ // then at most a few connector words, then the name. The connectors are an+ // allowlist rather than "any 40 characters" so that a complaint about some+ // OTHER field cannot reach across into a prose use of ours.+ const introduced = new RegExp(+ "(?:parameter|argument|field|property|key|input)s?\\b" ++ "(?:[^A-Za-z0-9_]|\\b(?:supplied|provided|given|named|name|is|was|of|in|the|for|body|request|json)\\b){0,6}" ++ `${p}${tail}`,+ "i"+ );+ // Start of the body, or start of a quoted JSON string value.+ const leading = new RegExp(`(?:^|["'])\\s*${p}\\s*:`);+ return quoted.test(errorText) || introduced.test(errorText) || leading.test(errorText);+}++/**+ * The subset of `candidates` this error body rejects, in the given order.+ *+ * Empty when the body is not a parameter complaint, or names none of them.+ */+export function rejectedOptionalParams(errorText: string, candidates: readonly string[]): string[] {+ if (!errorText || !PARAMETER_COMPLAINT.test(errorText)) return [];+ return candidates.filter((param) => namesParameterField(errorText, param));+}diff --git a/packages/cli/src/adapters/sampling-params-forwarded.test.ts b/packages/cli/src/adapters/sampling-params-forwarded.test.tsnew file mode 100644index 00000000..1f7c5343--- /dev/null+++ b/packages/cli/src/adapters/sampling-params-forwarded.test.ts@@ -0,0 +1,164 @@+/**+ * Item 11 — `stop_sequences` → `stop`, and `top_p`, on every OpenAI-shaped+ * payload builder.+ *+ * ## Provenance of the inputs+ *+ * These are REQUEST-side assertions, and the repo's fixture rule ("fixtures come+ * from real debug logs") covers RESPONSE captures — `test-fixtures/sse-responses/`+ * holds streams, not inbound bodies, so no capture in the tree can reach a+ * payload builder. The inputs below are therefore constructed Anthropic request+ * bodies written inline, in the same style as the sibling adapter tests, and they+ * assert only this tree's own conversion contract. Nothing here claims a provider+ * accepts or rejects any particular field.+ */++import { expect, test } from "bun:test";+import { DefaultAPIFormat } from "./base-api-format.js";+import { LiteLLMAPIFormat } from "./litellm-api-format.js";+import { LocalModelAdapter } from "./local-adapter.js";+import { OpenAIAPIFormat } from "./openai-api-format.js";+import { OpenRouterAPIFormat } from "./openrouter-api-format.js";+import { rejectedOptionalParams } from "./optional-param-rejection.js";++/** Every OpenAI-shaped payload builder in the tree, by the name it ships under. */+const BUILDERS: [string, () => { buildPayload: (r: any, m: any[], t: any[]) => any }][] = [+ ["BaseAPIFormat", () => new DefaultAPIFormat("some-model")],+ ["OpenAIAPIFormat", () => new OpenAIAPIFormat("gpt-4o")],+ ["LiteLLMAPIFormat", () => new LiteLLMAPIFormat("gpt-4o", "http://localhost:4000")],+ ["OpenRouterAPIFormat", () => new OpenRouterAPIFormat("openai/gpt-4o")],+ ["LocalModelAdapter", () => new LocalModelAdapter("qwen2.5-coder", "ollama")],+];++const MESSAGES = [{ role: "user", content: "hi" }];++test("every OpenAI-shaped builder forwards stop_sequences as stop, and top_p", () => {+ const request = {+ model: "whatever",+ max_tokens: 100,+ stop_sequences: ["</result>", "\n\nHuman:"],+ top_p: 0.4,+ messages: MESSAGES,+ };++ for (const [name, make] of BUILDERS) {+ const payload = make().buildPayload(request, MESSAGES, []);+ expect(`${name}: ${JSON.stringify(payload.stop)}`).toBe(+ `${name}: ["</result>","\\n\\nHuman:"]`+ );+ expect(`${name}: ${payload.top_p}`).toBe(`${name}: 0.4`);+ }+});++test("a request with neither field adds neither key", () => {+ for (const [name, make] of BUILDERS) {+ const payload = make().buildPayload({ max_tokens: 100, messages: MESSAGES }, MESSAGES, []);+ expect(`${name}: ${"stop" in payload}`).toBe(`${name}: false`);+ // LocalModelAdapter carries its own family top_p default; every other+ // builder must add no key at all.+ if (name !== "LocalModelAdapter") {+ expect(`${name}: ${"top_p" in payload}`).toBe(`${name}: false`);+ }+ }+});++test("an explicit top_p overrides the local adapter's family default", () => {+ const local = new LocalModelAdapter("qwen2.5-coder", "ollama");+ const withoutIt = local.buildPayload({ max_tokens: 100, messages: MESSAGES }, MESSAGES, []);+ const withIt = local.buildPayload(+ { max_tokens: 100, top_p: 0.05, messages: MESSAGES },+ MESSAGES,+ []+ );++ expect(typeof withoutIt.top_p).toBe("number");+ expect(withIt.top_p).toBe(0.05);+ expect(withIt.top_p).not.toBe(withoutIt.top_p);+});++test("empty stop sequences are dropped, and an all-empty list adds no key", () => {+ const fmt = new OpenAIAPIFormat("gpt-4o");+ expect(+ fmt.buildPayload({ max_tokens: 10, stop_sequences: ["", "STOP", ""] }, MESSAGES, []).stop+ ).toEqual(["STOP"]);+ expect("stop" in fmt.buildPayload({ max_tokens: 10, stop_sequences: [] }, MESSAGES, [])).toBe(+ false+ );+ expect("stop" in fmt.buildPayload({ max_tokens: 10, stop_sequences: [""] }, MESSAGES, [])).toBe(+ false+ );+});++test("top_p: 0 is forwarded — it is a value, not an absence", () => {+ const payload = new OpenAIAPIFormat("gpt-4o").buildPayload(+ { max_tokens: 10, top_p: 0 },+ MESSAGES,+ []+ );+ expect(payload.top_p).toBe(0);+});++// ─── The recovery half ──────────────────────────────────────────────────────+//+// Both fields are sent speculatively, so a strict relay's 4xx must be repairable+// in one retry. The error wordings below are the documented shapes of+// OpenAI-compatible relays, written here — not captured from a live 4xx.++test("a rejection naming a field drops exactly that field", () => {+ const fmt = new OpenAIAPIFormat("gpt-4o");+ const payload = { model: "gpt-4o", stop: ["X"], top_p: 0.4, temperature: 1 };++ const dropped = fmt.recoverFromRejection(payload, "Unrecognized request argument supplied: stop");+ expect(dropped?.payload).toEqual({ model: "gpt-4o", top_p: 0.4, temperature: 1 });+ expect(dropped?.note).toContain("stop");++ const quoted = fmt.recoverFromRejection(payload, "Unexpected keyword argument 'top_p'");+ expect(quoted?.payload).toEqual({ model: "gpt-4o", stop: ["X"], temperature: 1 });++ const leading = fmt.recoverFromRejection(+ payload,+ '{"error":{"message":"stop: Extra inputs are not permitted"}}'+ );+ expect("stop" in (leading?.payload ?? {})).toBe(false);++ const both = fmt.recoverFromRejection(+ payload,+ "Model gpt-4o does not support parameter stop, parameter top_p"+ );+ expect(both?.payload).toEqual({ model: "gpt-4o", temperature: 1 });+});++test("an unrelated 4xx recovers nothing, and prose using the word does not count", () => {+ const fmt = new OpenAIAPIFormat("gpt-4o");+ const payload = { model: "gpt-4o", stop: ["X"], top_p: 0.4 };++ expect(fmt.recoverFromRejection(payload, "Rate limit exceeded")).toBeNull();+ expect(fmt.recoverFromRejection(payload, "invalid_api_key")).toBeNull();+ // A complaint that names a DIFFERENT field must not strip ours.+ expect(fmt.recoverFromRejection(payload, "Unknown parameter: 'reasoning_effort'")).toBeNull();+ // The complaint gate plus a prose use of the word "stop".+ expect(+ fmt.recoverFromRejection(payload, "Invalid request: the model would not stop generating")+ ).toBeNull();+ // Nothing to drop ⇒ nothing returned, even on a naming rejection.+ expect(fmt.recoverFromRejection({ model: "gpt-4o" }, "Unknown parameter: 'stop'")).toBeNull();+});++test("the grok dialect still recovers stop/top_p after its own cases miss", async () => {+ const { GrokModelDialect } = await import("./grok-model-dialect.js");+ const grok = new GrokModelDialect("grok-4.6");+ const recovered = grok.recoverFromRejection(+ { model: "grok-4.6", stop: ["X"] },+ "Unknown parameter: 'stop'"+ );+ expect(recovered?.payload).toEqual({ model: "grok-4.6" });+});++test("rejectedOptionalParams needs both gates", () => {+ // Gate 1 alone: a field name with no complaint.+ expect(rejectedOptionalParams("the stop parameter was applied", ["stop"])).toEqual([]);+ // Gate 2 alone: a complaint naming nothing of ours.+ expect(rejectedOptionalParams("Invalid request", ["stop", "top_p"])).toEqual([]);+ // Both.+ expect(rejectedOptionalParams("Unknown parameter: 'stop'", ["stop", "top_p"])).toEqual(["stop"]);+});