Claude Code. Any Model. The most powerful AI coding agent now speaks every language.
fix(adapters): a reversible 64-char tool-name codec on every OpenAI wire (item 7)
Jack Rudenko2e18042c6750
diff --git a/packages/cli/src/adapters/base-api-format.ts b/packages/cli/src/adapters/base-api-format.tsindex b6b31ef8..80643738 100644--- a/packages/cli/src/adapters/base-api-format.ts+++ b/packages/cli/src/adapters/base-api-format.ts@@ -16,7 +16,7 @@ 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";+import { type ToolNameBindings, encodeToolName, newToolNameBindings } from "./tool-name-utils.js";/*** The OPTIONAL parameters {@link BaseAPIFormat.applyOpenAISamplingParams} adds@@ -26,6 +26,13 @@ import { truncateToolName } from "./tool-name-utils.js";*/const OPTIONAL_SAMPLING_PARAMS: readonly string[] = ["stop", "top_p"];+/**+ * OpenAI validates a function name against `^[a-zA-Z0-9_-]{1,64}$` on both the+ * Chat Completions and the Responses shape. 64 is that limit, not a guess about+ * any one model.+ */+const OPENAI_TOOL_NAME_LIMIT = 64;+/*** Match a model ID against a model family name, handling vendor-prefixed IDs.*@@ -128,10 +135,18 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {protected readonly wireFormat?: StreamFormat;/**- * Map of truncated tool names back to original names.- * Populated during prepareRequest() when tool names are truncated.+ * This request's tool-name bindings, in both directions.+ *+ * PER REQUEST, and REPLACED rather than cleared — never mutated after it has+ * been handed out. Handlers are cached one per model while `claudish serve`+ * hosts several conversations, so the instance is shared: clearing the map+ * that request A's parser is still decoding with, because request B started,+ * turns A's tool calls into names nothing recognises — and `keepOnlyRealTools`+ * then drops them with no error anywhere. `adapters.md` records the same+ * hazard class for `getHeaders`. `reset()` mints a new pair; the old one stays+ * whole for whoever is still reading it.*/- protected toolNameMap: Map<string, string> = new Map();+ protected toolNameBindings: ToolNameBindings = newToolNameBindings();constructor(modelId: string, wireFormat?: StreamFormat) {this.modelId = modelId;@@ -244,11 +259,30 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {}/**- * Maximum tool name length allowed by this model's API.- * Returns null if no limit (default).+ * Maximum tool name length this request's wire accepts, or null for no limit.+ *+ * A RULE about the wire, not a roster of adapters. OpenAI validates a function+ * name against `^[a-zA-Z0-9_-]{1,64}$` on both of its shapes, so every+ * OpenAI-shaped wire gets 64 and everything else gets null. Before this, the+ * method returned null on every adapter except Xiaomi, so nothing else+ * truncated at all — and a real 65-character MCP name+ * (`mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent`) fails+ * the WHOLE request, not just that tool.+ *+ * The Anthropic-wire check comes FIRST and is load-bearing: a dialect is+ * selected by model name and cannot know its wire, so `getStreamFormat()`+ * still answers "openai-sse" for a dialect reached over Qwen Plan's+ * Anthropic-compatible endpoint. Encoding there would rewrite names the+ * anthropic-sse parser has no map to decode.*/getToolNameLimit(): number | null {- return null;+ // The COMPOSED wire wins when it was supplied. A dialect self-selects by+ // model name and its own `getStreamFormat()` answers "openai-sse" whatever+ // it was composed into — so a dialect running under Ollama's JSONL wire, or+ // Qwen Plan's Anthropic one, would otherwise encode names that wire's parser+ // has no map to decode.+ const wire = this.wireFormat ?? this.getStreamFormat();+ return wire === "openai-sse" || wire === "openai-responses-sse" ? OPENAI_TOOL_NAME_LIMIT : null;}/**@@ -264,18 +298,22 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {}/**- * Get the tool name map (truncated -> original).- * Use after prepareRequest() to get the mapping for response processing.+ * This request's decode map (encoded → original).+ *+ * Read it ONCE, immediately after `prepareRequest`, and thread that reference+ * onward — do not re-read it after an `await`. `reset()` replaces the+ * bindings, so a later read on a shared handler returns the NEXT request's+ * map.*/getToolNameMap(): Map<string, string> {- return this.toolNameMap;+ return this.toolNameBindings.byEncoded;}/**- * Restore a potentially truncated tool name to its original.+ * Restore a possibly-encoded tool name to its original.*/restoreToolName(name: string): string {- return this.toolNameMap.get(name) || name;+ return this.toolNameBindings.byEncoded.get(name) || name;}/**@@ -309,6 +347,12 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {prepareRequest(request: any, originalRequest: any): any {const prepared = this.prepareRequestCommon(request, originalRequest) ?? request;+ // Tool-name encoding lives in the TEMPLATE, not in the hook, so that every+ // adapter gets it exactly once and no subclass can lose it by overriding+ // `prepareRequestCommon` without calling super — which is how it came to be+ // on OpenAIAPIFormat and Xiaomi alone. One call site for the whole tree.+ this.encodeToolNames(prepared);+if (!this.isAnthropicWire()) {return this.applyNativeReasoning(prepared, originalRequest) ?? prepared;}@@ -631,7 +675,9 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {* Reset internal state between requests (prevents state contamination)*/reset(): void {- this.toolNameMap.clear();+ // REPLACE, never clear: a parser from the previous request may still be+ // decoding with the old map. See {@link toolNameBindings}.+ this.toolNameBindings = newToolNameBindings();}// ─── ComposedHandler integration (Phase 1c) ───────────────────────@@ -765,52 +811,73 @@ export abstract class BaseAPIFormat implements APIFormat, ModelDialect {}/**- * Truncate tool names in the request payload if the model has a name length limit.- * Handles both Chat Completions format ({type:"function", function:{name}})- * and Responses API format ({type:"function", name}).- * Stores the mapping in this.toolNameMap for reverse mapping in responses.+ * Rewrite every tool name in this payload into what the wire accepts, and+ * record the way back.+ *+ * THREE places carry a tool name, and all three must agree or the request is+ * worse than it was before:+ *+ * 1. `tools[]` — what the model may call. Both shapes: Chat Completions+ * `{type:"function", function:{name}}` and the Responses API's flat+ * `{type:"function", name}`.+ * 2. The HISTORY — `messages[]` assistant `tool_calls`, and the Responses+ * API's `input[]` `function_call` items. A history naming a tool that is+ * not in `tools[]` is rejected by strict endpoints and confuses every+ * other one.+ * 3. `tool_choice` — pointing at a name the model was never offered is a+ * 400 on the first forced-tool turn.+ *+ * Encoding runs on the BUILT payload rather than inside each builder because+ * that is where all three live, and because the map has to be minted+ * somewhere both the payload and the parser can see.+ *+ * Idempotent: an already-encoded name transforms to itself and is bound to+ * itself, so a delegating adapter that runs this after its inner adapter+ * already did changes nothing.*/- protected truncateToolNames(request: any): void {+ protected encodeToolNames(request: any): void {const limit = this.getToolNameLimit();- if (!limit || !request.tools) return;-- for (const tool of request.tools) {- const originalName = tool.function?.name || tool.name;- if (originalName && originalName.length > limit) {- const truncated = truncateToolName(originalName, limit);- this.toolNameMap.set(truncated, originalName);- if (tool.function?.name) {- tool.function.name = truncated;- } else if (tool.name) {- tool.name = truncated;+ if (!limit || !request) return;++ const encode = (name: string) => encodeToolName(name, limit, this.toolNameBindings);++ if (Array.isArray(request.tools)) {+ for (const tool of request.tools) {+ if (tool?.function?.name) {+ tool.function.name = encode(tool.function.name);+ } else if (tool?.name) {+ tool.name = encode(tool.name);}}}- }-- /**- * Truncate tool names in assistant message history (for messages array).- * This is needed because historical tool_use blocks in the conversation- * may contain names that exceed the model's limit.- */- protected truncateToolNamesInMessages(messages: any[]): void {- const limit = this.getToolNameLimit();- if (!limit) return;- for (const msg of messages) {- if (msg.role === "assistant" && Array.isArray(msg.tool_calls)) {+ if (Array.isArray(request.messages)) {+ for (const msg of request.messages) {+ if (msg?.role !== "assistant" || !Array.isArray(msg.tool_calls)) continue;for (const tc of msg.tool_calls) {- const name = tc.function?.name;- if (name && name.length > limit) {- const truncated = truncateToolName(name, limit);- tc.function.name = truncated;- if (!this.toolNameMap.has(truncated)) {- this.toolNameMap.set(truncated, name);- }- }+ if (tc?.function?.name) tc.function.name = encode(tc.function.name);}}}++ // Responses API history. `input` holds `function_call` items rather than an+ // assistant message with `tool_calls`, so the branch above cannot see them.+ if (Array.isArray(request.input)) {+ for (const item of request.input) {+ if (item?.type === "function_call" && item.name) item.name = encode(item.name);+ }+ }++ const choice = request.tool_choice;+ if (choice && typeof choice === "object") {+ // `{type:"function", function:{name}}` (chat) and `{type:"function", name}`+ // (responses). The string forms — "auto"/"none"/"required" — name nothing.+ if (choice.function?.name) {+ choice.function.name = encode(choice.function.name);+ } else if (choice.name) {+ choice.name = encode(choice.name);+ }+ }}}diff --git a/packages/cli/src/adapters/grok-model-dialect.ts b/packages/cli/src/adapters/grok-model-dialect.tsindex 5da3d92c..034a8f4f 100644--- a/packages/cli/src/adapters/grok-model-dialect.ts+++ b/packages/cli/src/adapters/grok-model-dialect.ts@@ -288,9 +288,15 @@ export class GrokModelDialect extends BaseAPIFormat {}/**- * Reset internal state (useful between requests)+ * Reset internal state (useful between requests).+ *+ * `super.reset()` is load-bearing: it mints this request's tool-name+ * bindings. Without it they accumulate for the life of the process, because+ * this override used to replace the base entirely — harmless while nothing+ * encoded names, not harmless now.*/- reset(): void {+ override reset(): void {+ super.reset();this.xmlBuffer = "";}}diff --git a/packages/cli/src/adapters/local-adapter.ts b/packages/cli/src/adapters/local-adapter.tsindex 621e794f..adeb8f49 100644--- a/packages/cli/src/adapters/local-adapter.ts+++ b/packages/cli/src/adapters/local-adapter.ts@@ -138,14 +138,14 @@ export class LocalModelAdapter extends BaseAPIFormat {// ─── Request post-processing ────────────────────────────────────────protected override prepareRequestCommon(request: any, originalRequest: any): any {- // Delegate to inner adapter (Qwen tool name truncation, etc.)+ // Delegate to inner adapter (Qwen tool name encoding, etc.). The inner+ // adapter's template encodes the names into ITS bindings; this adapter's+ // template then runs over an already-encoded payload and changes nothing.+ // `getToolNameMap()` below merges both, so there is no eager copy here —+ // copying into this instance's bindings would also mean mutating a map the+ // previous request's parser may still be holding.this.innerAdapter.prepareRequest(request, originalRequest);- // Merge inner adapter's tool name map- for (const [k, v] of this.innerAdapter.getToolNameMap()) {- this.toolNameMap.set(k, v);- }-// Strip cloud-only thinking params that local providers don't understanddelete request.enable_thinking;delete request.thinking_budget;diff --git a/packages/cli/src/adapters/openai-api-format.ts b/packages/cli/src/adapters/openai-api-format.tsindex 6070905c..6a377089 100644--- a/packages/cli/src/adapters/openai-api-format.ts+++ b/packages/cli/src/adapters/openai-api-format.ts@@ -40,15 +40,9 @@ export class OpenAIAPIFormat extends BaseAPIFormat {return 128;}- /** Tool name truncation — a wire-agnostic API constraint. */- protected override prepareRequestCommon(request: any, _originalRequest: any): any {- this.truncateToolNames(request);- if (request.messages) {- this.truncateToolNamesInMessages(request.messages);- }-- return request;- }+ // Tool-name encoding used to live here, and here ONLY, which is why no other+ // OpenAI-shaped adapter did it. It is now in `prepareRequest`'s template, so+ // this hook has nothing left to do./*** OpenAI's own reasoning knob. Not called on the Anthropic wire.diff --git a/packages/cli/src/adapters/tool-name-codec.test.ts b/packages/cli/src/adapters/tool-name-codec.test.tsnew file mode 100644index 00000000..9b8ec4e1--- /dev/null+++ b/packages/cli/src/adapters/tool-name-codec.test.ts@@ -0,0 +1,210 @@+/**+ * Item 7 — the reversible 64-char tool-name codec, and the one pass that+ * applies it.+ *+ * ## Provenance of the inputs+ *+ * REQUEST-side. `test-fixtures/sse-responses/` holds response streams, not+ * inbound bodies, so no capture in the tree can reach a payload builder or+ * `prepareRequest`. The payloads below are constructed inline and assert only+ * this tree's own contract. No `.sse` fixture was invented. The decode half,+ * which IS response-side, is exercised in+ * `handlers/shared/stream-parsers/tool-name-mangling.test.ts`.+ */++import { expect, test } from "bun:test";+import { AnthropicAPIFormat } from "./anthropic-api-format.js";+import { DefaultAPIFormat } from "./base-api-format.js";+import { CodexAPIFormat } from "./codex-api-format.js";+import { GeminiAPIFormat } from "./gemini-api-format.js";+import { OpenAIAPIFormat } from "./openai-api-format.js";+import { TOOL_NAME_SHAPE, encodeToolName, newToolNameBindings } from "./tool-name-utils.js";++/** A real one, from the magus browser-use MCP server. 65 characters. */+const REAL_LONG_NAME = "mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent";++const WIRE_CHARSET = /^[A-Za-z0-9_-]{1,64}$/;++test("the motivating name is genuinely over the limit", () => {+ expect(REAL_LONG_NAME.length).toBeGreaterThan(64);+});++test("a name that already fits the wire is returned untouched", () => {+ const b = newToolNameBindings();+ expect(encodeToolName("Read", 64, b)).toBe("Read");+ expect(encodeToolName("mcp__magus__team", 64, b)).toBe("mcp__magus__team");+});++test("an over-long name becomes exactly 64 wire-legal characters, and decodes", () => {+ const b = newToolNameBindings();+ const encoded = encodeToolName(REAL_LONG_NAME, 64, b);++ expect(encoded.length).toBe(64);+ expect(encoded).toMatch(WIRE_CHARSET);+ // It must also satisfy the ONE definition of a tool name's shape, or the+ // recovery path and the stats recorder will reject what we ourselves sent.+ expect(TOOL_NAME_SHAPE.test(encoded)).toBe(true);+ expect(b.byEncoded.get(encoded)).toBe(REAL_LONG_NAME);+});++test("characters the wire refuses are mapped out", () => {+ const b = newToolNameBindings();+ const encoded = encodeToolName("server.tool:v2", 64, b);+ expect(encoded).toBe("server_tool_v2");+ expect(encoded).toMatch(WIRE_CHARSET);+ expect(b.byEncoded.get(encoded)).toBe("server.tool:v2");+});++test("SHORT names that transform onto each other do not collide", () => {+ // The defect this closes: `a.b` and `a_b` both charset-map to `a_b`, at a+ // length no truncation rule would ever look at. Whichever registered last+ // used to own the name, so the model's call went to the wrong tool.+ const b = newToolNameBindings();+ const first = encodeToolName("a_b", 64, b);+ const second = encodeToolName("a.b", 64, b);++ expect(first).toBe("a_b");+ expect(second).not.toBe(first);+ expect(second).toMatch(WIRE_CHARSET);+ expect(b.byEncoded.get(first)).toBe("a_b");+ expect(b.byEncoded.get(second)).toBe("a.b");+});++test("an identity encoding still CLAIMS the name, whichever order they arrive in", () => {+ const b = newToolNameBindings();+ // Reverse order of the previous test: the dotted one goes first and takes+ // `a_b`; the literal `a_b` must then be moved, not silently overwritten.+ const dotted = encodeToolName("a.b", 64, b);+ const literal = encodeToolName("a_b", 64, b);++ expect(dotted).toBe("a_b");+ expect(literal).not.toBe(dotted);+ expect(b.byEncoded.get(dotted)).toBe("a.b");+ expect(b.byEncoded.get(literal)).toBe("a_b");+});++test("encoding is stable within a request", () => {+ const b = newToolNameBindings();+ const once = encodeToolName(REAL_LONG_NAME, 64, b);+ const twice = encodeToolName(REAL_LONG_NAME, 64, b);+ expect(twice).toBe(once);+ // …and deterministic across requests, so a name in HISTORY encodes to the+ // same thing as the same name in `tools[]`.+ expect(encodeToolName(REAL_LONG_NAME, 64, newToolNameBindings())).toBe(once);+});++test("encoding an already-encoded name is the identity — the pass is idempotent", () => {+ const first = newToolNameBindings();+ const encoded = encodeToolName(REAL_LONG_NAME, 64, first);+ const second = newToolNameBindings();+ expect(encodeToolName(encoded, 64, second)).toBe(encoded);+});++// ─── The limit is a rule about the wire ─────────────────────────────────────++test("64 on OpenAI-shaped wires, null on every other", () => {+ expect(new OpenAIAPIFormat("gpt-4o").getToolNameLimit()).toBe(64);+ expect(new CodexAPIFormat("gpt-5.1-codex").getToolNameLimit()).toBe(64);+ expect(new DefaultAPIFormat("anything").getToolNameLimit()).toBe(64);++ expect(new GeminiAPIFormat("gemini-3-pro").getToolNameLimit()).toBeNull();+ expect(new AnthropicAPIFormat("claude-x").getToolNameLimit()).toBeNull();+});++test("the COMPOSED wire wins over a dialect's own default", () => {+ // A dialect self-selects by model name and always answers "openai-sse" for+ // itself. Under a wire whose parser holds no map, it must not encode.+ expect(new DefaultAPIFormat("anything", "anthropic-sse").getToolNameLimit()).toBeNull();+ expect(new DefaultAPIFormat("anything", "ollama-jsonl").getToolNameLimit()).toBeNull();+ expect(new DefaultAPIFormat("anything", "gemini-sse").getToolNameLimit()).toBeNull();+ expect(new DefaultAPIFormat("anything", "openai-sse").getToolNameLimit()).toBe(64);+});++// ─── One pass, all three places a name lives ────────────────────────────────++test("tools, history and tool_choice are encoded, and they agree", () => {+ const fmt = new OpenAIAPIFormat("gpt-4o");+ fmt.reset();+ const payload = {+ model: "gpt-4o",+ tools: [{ type: "function", function: { name: REAL_LONG_NAME } }],+ messages: [+ { role: "user", content: "go" },+ {+ role: "assistant",+ tool_calls: [{ id: "c1", type: "function", function: { name: REAL_LONG_NAME } }],+ },+ { role: "tool", tool_call_id: "c1", content: "done" },+ ],+ tool_choice: { type: "function", function: { name: REAL_LONG_NAME } },+ };++ fmt.prepareRequest(payload, { messages: [] });++ const onTheWire = payload.tools[0].function.name;+ expect(onTheWire.length).toBe(64);+ expect(onTheWire).not.toBe(REAL_LONG_NAME);+ // All three agree — a history or a tool_choice naming something absent from+ // tools[] is a 400 on strict endpoints and confusion everywhere else.+ expect((payload.messages[1] as any).tool_calls[0].function.name).toBe(onTheWire);+ expect(payload.tool_choice.function.name).toBe(onTheWire);+ expect(fmt.getToolNameMap().get(onTheWire)).toBe(REAL_LONG_NAME);+ expect(fmt.restoreToolName(onTheWire)).toBe(REAL_LONG_NAME);+});++test("the Responses API's own two shapes are encoded too", () => {+ const fmt = new CodexAPIFormat("gpt-5.1-codex");+ fmt.reset();+ const payload = {+ model: "gpt-5.1-codex",+ // Flat tools, and history as `input` items rather than assistant messages.+ tools: [{ type: "function", name: REAL_LONG_NAME }],+ input: [+ { type: "function_call", call_id: "c1", name: REAL_LONG_NAME, arguments: "{}" },+ { type: "function_call_output", call_id: "c1", output: "ok" },+ ],+ tool_choice: { type: "function", name: REAL_LONG_NAME },+ };++ fmt.prepareRequest(payload, { messages: [] });++ const onTheWire = payload.tools[0].name;+ expect(onTheWire.length).toBe(64);+ expect(payload.input[0].name).toBe(onTheWire);+ expect(payload.tool_choice.name).toBe(onTheWire);+ expect(fmt.getToolNameMap().get(onTheWire)).toBe(REAL_LONG_NAME);+});++test("a wire with no limit leaves every name alone", () => {+ const fmt = new GeminiAPIFormat("gemini-3-pro");+ fmt.reset();+ const payload = {+ tools: [{ function: { name: REAL_LONG_NAME } }],+ tool_choice: { type: "function", function: { name: REAL_LONG_NAME } },+ };+ fmt.prepareRequest(payload, { messages: [] });+ expect(payload.tools[0].function.name).toBe(REAL_LONG_NAME);+ expect(payload.tool_choice.function.name).toBe(REAL_LONG_NAME);+});++// ─── The map is per request ─────────────────────────────────────────────────++test("reset() mints a new map instead of clearing the one already handed out", () => {+ const fmt = new OpenAIAPIFormat("gpt-4o");+ fmt.reset();+ fmt.prepareRequest({ tools: [{ type: "function", function: { name: REAL_LONG_NAME } }] }, {});++ // What request A's parser is holding.+ const mapA = fmt.getToolNameMap();+ const encodedA = [...mapA.keys()][0];+ expect(mapA.get(encodedA)).toBe(REAL_LONG_NAME);++ // Request B starts on the same cached handler.+ fmt.reset();+ fmt.prepareRequest({ tools: [{ type: "function", function: { name: "Read" } }] }, {});++ // A's map still decodes. Clearing it here would have turned A's tool calls+ // into names nothing recognises, and the allowlist drops those in silence.+ expect(mapA.get(encodedA)).toBe(REAL_LONG_NAME);+ expect(fmt.getToolNameMap()).not.toBe(mapA);+});diff --git a/packages/cli/src/adapters/tool-name-utils.ts b/packages/cli/src/adapters/tool-name-utils.tsindex 12e5a154..e73bd422 100644--- a/packages/cli/src/adapters/tool-name-utils.ts+++ b/packages/cli/src/adapters/tool-name-utils.ts@@ -57,3 +57,100 @@ export function truncateToolName(name: string, maxLength: number): string {);return truncated;}++// ─── The wire codec ─────────────────────────────────────────────────────────++/**+ * Characters an OpenAI-shaped wire accepts in a function name.+ *+ * This is a DIFFERENT question from {@link TOOL_NAME_SHAPE}, and the two must+ * not be merged. `TOOL_NAME_SHAPE` answers "may this string occupy a tool-name+ * slot in something we parsed" — it stays the single definition of that, and it+ * deliberately admits `.`, because a name we READ may legally contain one.+ * This charset answers "what will the endpoint accept", and OpenAI's function+ * name is validated against `^[a-zA-Z0-9_-]{1,64}$`, which admits no dot.+ *+ * Anything outside it is mapped to `_`, and the map records the way back.+ */+const UNWIRABLE_CHARACTER = /[^A-Za-z0-9_-]/g;++/** The two directions of one request's codec. Both are per-request; see reset(). */+export interface ToolNameBindings {+ /** encoded → original. This is the map the stream parser decodes with. */+ byEncoded: Map<string, string>;+ /** original → encoded. Makes the encoding stable within a request. */+ byOriginal: Map<string, string>;+}++/** A fresh, empty pair of bindings. */+export function newToolNameBindings(): ToolNameBindings {+ return { byEncoded: new Map(), byOriginal: new Map() };+}++/** `prefix` + `_` + 8 hex, exactly `limit` characters. */+function hashedForm(transformed: string, original: string, limit: number, salt: number): string {+ const seed = salt === 0 ? original : `${original}#${salt}`;+ const prefix = transformed.slice(0, Math.max(0, limit - 9));+ return `${prefix}_${hashToolName(seed)}`;+}++/**+ * Encode a tool name for an OpenAI-shaped wire, reversibly.+ *+ * Two transformations, in this order:+ *+ * 1. **Charset.** Every character outside {@link UNWIRABLE_CHARACTER}'s+ * complement becomes `_`.+ * 2. **Length and collisions.** A transformed name longer than `limit`, OR one+ * already bound to a DIFFERENT original, becomes+ * `prefix + "_" + hash8(original)`.+ *+ * Step 2's collision arm is not an optimisation. Charset-mapping makes `a.b`+ * and `a_b` the same string, so two different tools can claim one encoded name+ * at ANY length — and the map would then decode every call to whichever of them+ * was registered last, silently handing the model's call to the wrong tool.+ * Length was never the only way to collide.+ *+ * Every binding is recorded, identity ones included, because an identity+ * encoding CLAIMS that name: without the record, a later `a.b` would transform+ * onto an unregistered `a_b` and win it from the real `a_b`.+ *+ * The hash is the collision GUARD, not an inverse. A codec cannot be reversible+ * from an arbitrary-length name into a 64-character slot — the map is+ * authoritative, and that is why it must reach the parser intact.+ */+export function encodeToolName(+ original: string,+ limit: number,+ bindings: ToolNameBindings+): string {+ const already = bindings.byOriginal.get(original);+ if (already !== undefined) return already;++ const transformed = original.replace(UNWIRABLE_CHARACTER, "_");+ const takenByAnother = (name: string) => {+ const owner = bindings.byEncoded.get(name);+ return owner !== undefined && owner !== original;+ };++ let encoded =+ transformed.length <= limit ? transformed : hashedForm(transformed, original, limit, 0);+ if (takenByAnother(encoded)) {+ // Salt only ever advances on a hash8 collision between two DIFFERENT+ // originals, which is vanishingly rare — but "vanishingly rare" and+ // "silently hands the model's call to another tool" is the wrong pair.+ let salt = 0;+ do {+ encoded = hashedForm(transformed, original, limit, salt++);+ } while (takenByAnother(encoded));+ }++ bindings.byEncoded.set(encoded, original);+ bindings.byOriginal.set(original, encoded);+ if (encoded !== original) {+ log(+ `[ToolName] Encoded: "${original}" -> "${encoded}" (${original.length} -> ${encoded.length})`+ );+ }+ return encoded;+}diff --git a/packages/cli/src/adapters/xiaomi-model-dialect.ts b/packages/cli/src/adapters/xiaomi-model-dialect.tsindex 553fff8f..89789352 100644--- a/packages/cli/src/adapters/xiaomi-model-dialect.ts+++ b/packages/cli/src/adapters/xiaomi-model-dialect.ts@@ -19,19 +19,11 @@ export class XiaomiModelDialect extends BaseAPIFormat {};}- override getToolNameLimit(): number {- return 64;- }-- protected override prepareRequestCommon(request: any, _originalRequest: any): any {- // Truncate tool names to 64 chars — a wire-agnostic API constraint.- this.truncateToolNames(request);- if (request.messages) {- this.truncateToolNamesInMessages(request.messages);- }-- return request;- }+ // The 64-char limit and the truncation call that used to stand here are gone:+ // `BaseAPIFormat.getToolNameLimit()` now returns 64 for every OpenAI-shaped+ // wire, and `prepareRequest`'s template applies it. Xiaomi enforces the limit+ // strictly, which is why this dialect was the only adapter in the tree that+ // ever truncated at all — it is no longer special.protected override applyNativeReasoning(request: any, originalRequest: any): any {// Xiaomi's own API doesn't support thinking params.diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.tsindex fc0ac8d7..6fd015d2 100644--- a/packages/cli/src/handlers/composed-handler.ts+++ b/packages/cli/src/handlers/composed-handler.ts@@ -1488,7 +1488,11 @@ export class ComposedHandler implements ModelHandler {return createResponsesStreamHandler(c, response, {modelName: this.bareModelName,onTokenUpdate,- toolNameMap: adapter.getToolNameMap(),+ // The map THIS request captured right after prepareRequest — not a+ // fresh read. This runs after an awaited fetch, and on a handler+ // shared by two conversations the adapter's own map may already+ // belong to the next request by now.+ toolNameMap,contextWindow: lookupModelForProvider(this.bareModelName, this.provider.name),onApiError,priorInputTokens,diff --git a/packages/cli/src/handlers/shared/format/openai-tools.ts b/packages/cli/src/handlers/shared/format/openai-tools.tsindex ed1aea68..2b2c8e9b 100644--- a/packages/cli/src/handlers/shared/format/openai-tools.ts+++ b/packages/cli/src/handlers/shared/format/openai-tools.ts@@ -317,6 +317,12 @@ export type ResponsesToolChoice = string | { type: "function"; name: string };* @param choice - the inbound `tool_choice`, if any* @param encodeName - applied to the named tool, so a wire that renames tools* names the SAME tool here as in `tools[]`. Identity when omitted.+ *+ * NOTE on `encodeName`: production does not pass it. Tool-name encoding runs as+ * a post-pass over the BUILT payload (`BaseAPIFormat.encodeToolNames`), because+ * the name also lives in the message history, which no `tool_choice` mapper can+ * reach — and because the codec's map is minted there. The hook stays for a+ * builder that ever has the bindings in hand before it builds.*/export function mapToolChoiceToOpenAI(choice: ClaudeToolChoice | null | undefined,diff --git a/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts b/packages/cli/src/handlers/shared/stream-parsers/openai-sse.tsindex 45ddaee9..75d231fb 100644--- a/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts+++ b/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts@@ -420,7 +420,11 @@ export function createStreamingResponseHandler(// The `<function=NAME><parameter=P>` envelope carries no// types, so every value arrives as a string. The schemas are// what turn `"5"` back into 5 and `"true"` into true.- toolSchemas as ToolSchema[] | undefined+ toolSchemas as ToolSchema[] | undefined,+ // Recovery reads the name the MODEL wrote, which is the+ // encoded one. The allowlist is built from the client's+ // originals, so an undecoded name is dropped in silence.+ toolNameMap ? (name: string) => toolNameMap.get(name) ?? name : undefined);if (state.tools.size > 0 && state.accumulatedText.length > 0) {log(@@ -835,13 +839,14 @@ export function createStreamingResponseHandler(const accumulatedName =(state.pendingToolName.get(idx) ?? "") + tc.function.name;state.pendingToolName.set(idx, accumulatedName);+ // THIS IS THE DECODE POINT: it reads the accumulated name,+ // never a single chunk's fragment. Decoding a fragment+ // misses the map, and the allowlist then drops the call+ // in silence.+ const restoredName = toolNameMap?.get(accumulatedName) || accumulatedName;if (!t) {// The hand-written "close thinking, then close text"// pair that used to stand here is `openTool`'s job now.- // Restore truncated tool name to original if mapping exists.- // THIS IS THE DECODE POINT: it reads the accumulated name,- // never a single chunk's fragment.- const restoredName = toolNameMap?.get(accumulatedName) || accumulatedName;t = {id: tc.id || `tool_${Date.now()}_${idx}`,name: restoredName,@@ -871,6 +876,28 @@ export function createStreamingResponseHandler(if (isWebSearchToolCall(restoredName)) {warnWebSearchUnsupported(restoredName, target);}+ } else if (t.name !== restoredName) {+ // A LATER fragment completed the name. The tool was+ // created from the first fragment, so its name is a+ // prefix — and a prefix of an encoded name decodes to+ // nothing, which is how a call gets dropped without a+ // word anywhere.+ if (t.started) {+ // The block is already on the wire under the short+ // name; it cannot be recalled. "error" is deliberate+ // — it is what carries this to the structural log.+ log(+ `[Streaming] error: tool block ${t.blockIndex} was started as "${t.name}" but the full name is "${restoredName}" — the client sees the wrong name`+ );+ } else {+ t.name = restoredName;+ t.buffered =+ (!!toolSchemas && toolSchemas.length > 0) ||+ behavior?.shouldBufferTool?.(restoredName) === true;+ if (isWebSearchToolCall(restoredName)) {+ warnWebSearchUnsupported(restoredName, target);+ }+ }}// Only send content_block_start immediately if NOT bufferingif (!t.started && !t.buffered) {diff --git a/packages/cli/src/handlers/shared/stream-parsers/tool-name-mangling.test.ts b/packages/cli/src/handlers/shared/stream-parsers/tool-name-mangling.test.tsindex 93777ace..f8216d45 100644--- a/packages/cli/src/handlers/shared/stream-parsers/tool-name-mangling.test.ts+++ b/packages/cli/src/handlers/shared/stream-parsers/tool-name-mangling.test.ts@@ -1,5 +1,6 @@import { describe, expect, it } from "bun:test";+import { encodeToolName, newToolNameBindings } from "../../../adapters/tool-name-utils.js";import { createStreamingResponseHandler } from "./openai-sse.js";const ctx: any = {@@ -154,3 +155,162 @@ describe("openai-sse tool-name recovery", () => {expect(unadvertised.observed).toEqual([]);});});++// ─── Item 7: decoding the encoded name back ─────────────────────────────────+//+// These frames are CONSTRUCTED, as every frame in this file always has been:+// the decode paths below cannot be reached from any capture in the tree (no+// capture carries a >64-char tool name, and none splits `function.name` across+// chunks). Nothing here is a `.sse` fixture, and no capture was invented.++/** A real 65-char MCP name, and what the codec sends in its place. */+const ORIGINAL = "mcp__plugin_browser-use_browser-use__retry_with_browser_use_agent";+const ENCODED = encodeToolName(ORIGINAL, 64, newToolNameBindings());++const longNameAdapter = {+ getToolNameMap: () => new Map([[ENCODED, ORIGINAL]]),+ processTextContent: (text: string) => ({+ cleanedText: text,+ extractedToolCalls: [],+ wasTransformed: false,+ }),+};++const longNameSchemas = [+ {+ name: ORIGINAL,+ input_schema: {+ type: "object",+ properties: { task: { type: "string" } },+ required: ["task"],+ },+ },+];++async function parseWithLongName(frames: string[]) {+ const observed: string[] = [];+ const response = createStreamingResponseHandler(+ ctx,+ sseResponse(frames),+ longNameAdapter,+ "test-model",+ null,+ undefined,+ longNameSchemas,+ longNameAdapter.getToolNameMap(),+ undefined,+ { onToolCallObserved: (name) => observed.push(name) }+ );+ const wire = await response.text();+ return { observed, toolUses: toolUseStarts(wire), argumentJson: inputJson(wire) };+}++/** The `input_json_delta` payload, concatenated — where a tool's arguments land. */+function inputJson(wire: string): string {+ let json = "";+ for (const frame of wire.split("\n\n")) {+ const dataLine = frame.split("\n").find((line) => line.startsWith("data: "));+ if (!dataLine || dataLine === "data: [DONE]") continue;+ try {+ const data = JSON.parse(dataLine.slice(6));+ if (data.type === "content_block_delta" && data.delta?.type === "input_json_delta") {+ json += data.delta.partial_json ?? "";+ }+ } catch {}+ }+ return json;+}++describe("openai-sse: the 64-char tool-name codec, decoded", () => {+ it("decodes a name the model returned whole", async () => {+ const result = await parseWithLongName([+ dataFrame({+ choices: [+ {+ delta: {+ tool_calls: [+ {+ index: 0,+ id: "call_0",+ type: "function",+ function: { name: ENCODED, arguments: '{"task":"x"}' },+ },+ ],+ },+ finish_reason: null,+ },+ ],+ }),+ finishFrame("tool_calls"),+ "data: [DONE]\n\n",+ ]);++ expect(result.toolUses).toHaveLength(1);+ expect(result.toolUses[0].name).toBe(ORIGINAL);+ expect(result.observed).toEqual([ORIGINAL]);+ });++ it("decodes a name that arrived in FRAGMENTS across chunks", async () => {+ // The defect: the tool is created from the first fragment, and a prefix of+ // an encoded name decodes to nothing — so the call is dropped with no error+ // anywhere. Decoding must happen against the ACCUMULATED name, and the tool+ // created early must be revised when the rest arrives.+ const head = ENCODED.slice(0, 7);+ const mid = ENCODED.slice(7, 40);+ const tail = ENCODED.slice(40);++ const result = await parseWithLongName([+ dataFrame({+ choices: [+ {+ delta: {+ tool_calls: [{ index: 0, id: "call_0", type: "function", function: { name: head } }],+ },+ finish_reason: null,+ },+ ],+ }),+ dataFrame({+ choices: [+ { delta: { tool_calls: [{ index: 0, function: { name: mid } }] }, finish_reason: null },+ ],+ }),+ dataFrame({+ choices: [+ { delta: { tool_calls: [{ index: 0, function: { name: tail } }] }, finish_reason: null },+ ],+ }),+ dataFrame({+ choices: [+ {+ delta: { tool_calls: [{ index: 0, function: { arguments: '{"task":"x"}' } }] },+ finish_reason: null,+ },+ ],+ }),+ finishFrame("tool_calls"),+ "data: [DONE]\n\n",+ ]);++ expect(result.toolUses).toHaveLength(1);+ expect(result.toolUses[0].name).toBe(ORIGINAL);+ // The arguments that arrived after the name survived the revision.+ expect(result.argumentJson).toBe('{"task":"x"}');+ expect(result.observed).toEqual([ORIGINAL]);+ });++ it("decodes a call RECOVERED from prose", async () => {+ // The model writes the name it was given — the encoded one — while the+ // recovery allowlist is built from the client's originals. Undecoded, the+ // allowlist drops it and nothing says so.+ const result = await parseWithLongName([+ textFrame(`<function=${ENCODED}><parameter=task>x`),+ finishFrame("stop"),+ "data: [DONE]\n\n",+ ]);++ expect(result.toolUses).toHaveLength(1);+ expect(result.toolUses[0].name).toBe(ORIGINAL);+ expect(result.observed).toEqual([ORIGINAL]);+ });+});diff --git a/packages/cli/src/handlers/shared/tool-call-recovery.ts b/packages/cli/src/handlers/shared/tool-call-recovery.tsindex ad48feb0..e24e5cef 100644--- a/packages/cli/src/handlers/shared/tool-call-recovery.ts+++ b/packages/cli/src/handlers/shared/tool-call-recovery.ts@@ -76,15 +76,24 @@ export function hasExtractableFunctionTag(text: string): boolean {/*** Drop extracted calls that are not real tools.*- * Two gates. The shape gate rejects a name that is not an identifier, which is- * how a swallowed argument value is caught. The allowlist gate rejects a- * well-shaped name the client never advertised, which is how a hallucinated tool- * is caught. The allowlist is the request's own tool list, so it is exact rather- * than a hardcoded roster.+ * Three steps, and the ORDER is the design:+ *+ * 1. **Shape.** Reject a name that is not an identifier — this is how a+ * swallowed argument value is caught. It runs on the name as it came off+ * the WIRE, which is the only name `TOOL_NAME_SHAPE`'s 64-character bound+ * describes.+ * 2. **Decode.** On a wire that renames tools, the model wrote the encoded+ * name; the client's own name may legitimately be longer than the wire+ * allows. Decoding before step 1 would fail a real 65-character MCP name on+ * a shape rule that was never about it.+ * 3. **Allowlist.** Reject a well-shaped name the client never advertised —+ * this is how a hallucinated tool is caught. The allowlist is the request's+ * own tool list, so it is exact rather than a hardcoded roster.*/function keepOnlyRealTools(extracted: ExtractedToolCall[],- knownToolNames?: string[]+ knownToolNames?: string[],+ decodeToolName?: (name: string) => string): ExtractedToolCall[] {const kept: ExtractedToolCall[] = [];for (const call of extracted) {@@ -96,16 +105,18 @@ function keepOnlyRealTools();continue;}+ const decoded = decodeToolName ? decodeToolName(call.name) : call.name;+ const named = decoded === call.name ? call : { ...call, name: decoded };if (!knownToolNames || knownToolNames.length === 0) {- kept.push(call);+ kept.push(named);continue;}- const canonical = knownToolNames.find((t) => t.toLowerCase() === call.name.toLowerCase());+ const canonical = knownToolNames.find((t) => t.toLowerCase() === named.name.toLowerCase());if (!canonical) {- log(`[ToolRecovery] Dropped extracted call for unadvertised tool: ${call.name}`);+ log(`[ToolRecovery] Dropped extracted call for unadvertised tool: ${named.name}`);continue;}- kept.push(canonical === call.name ? call : { ...call, name: canonical });+ kept.push(canonical === named.name ? named : { ...named, name: canonical });}return kept;}@@ -226,18 +237,24 @@ function normalizeAgainstSchema(** `toolSchemas`, when supplied, types the extracted values: the envelope format* carries no types, so every value arrives as a string.+ *+ * `decodeToolName`, when supplied, turns the name the MODEL wrote back into the+ * client's own. The model was given the encoded roster, so on a renaming wire+ * every recovered call carries an encoded name that `knownToolNames` — built+ * from the client's originals — would otherwise reject in silence.*/export function extractToolCallsFromText(text: string,knownToolNames?: string[],- toolSchemas?: ToolSchema[]+ toolSchemas?: ToolSchema[],+ decodeToolName?: (name: string) => string): ExtractedToolCall[] {// Tried FIRST, and short-circuits: a response that is nothing but function// tags is unambiguous, and reading it as a delimited envelope beats six// regexes scanning for fragments of one.const envelope = parseFunctionTagEnvelope(text);if (envelope) {- return keepOnlyRealTools(envelope, knownToolNames).map((call) =>+ return keepOnlyRealTools(envelope, knownToolNames, decodeToolName).map((call) =>normalizeAgainstSchema(call, toolSchemas));}@@ -460,7 +477,7 @@ export function extractToolCallsFromText(}}- return keepOnlyRealTools(extracted, knownToolNames);+ return keepOnlyRealTools(extracted, knownToolNames, decodeToolName);}/**