Skip to content

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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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"]);
+});