Skip to content

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

fix(tools): parse the function-tag envelope first, then type its values (item 9)

Jack Rudenko4a0948c45f03
diff --git a/packages/cli/src/handlers/shared/schema-validate.test.ts b/packages/cli/src/handlers/shared/schema-validate.test.ts
new file mode 100644
index 00000000..8361e7ce
--- /dev/null
+++ b/packages/cli/src/handlers/shared/schema-validate.test.ts
@@ -0,0 +1,167 @@
+/**
+ * Unit contract for the minimal schema reader.
+ *
+ * These are assertions about OUR functions, not about any model: no case here
+ * claims that some provider emitted some shape. The one behaviour that DOES rest
+ * on a real model — an empty-string required argument — is gated separately by a
+ * live capture, in `format-translation.test.ts` against
+ * `sse-responses/grok-4.6-openai-edit-empty-new-string.sse`.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+ applySchemaDefaults,
+ coerceToSchema,
+ missingRequired,
+ renameToDeclaredKeys,
+} from "./schema-validate.js";
+
+describe("missingRequired: presence is key presence, not truthiness", () => {
+ const schema = {
+ type: "object",
+ properties: {
+ a: { type: "string" },
+ b: { type: "number" },
+ c: { type: "boolean" },
+ d: { type: "array" },
+ },
+ required: ["a", "b", "c", "d"],
+ };
+
+ test("falsy-but-supplied values are present", () => {
+ expect(missingRequired(schema, { a: "", b: 0, c: false, d: [] })).toEqual([]);
+ });
+
+ test("an absent key is missing", () => {
+ expect(missingRequired(schema, { b: 0, c: false, d: [] })).toEqual(["a"]);
+ });
+
+ test("undefined and null are missing; an explicit empty object is not", () => {
+ expect(missingRequired({ ...schema, required: ["a"] }, { a: undefined })).toEqual(["a"]);
+ expect(missingRequired({ ...schema, required: ["a"] }, { a: null })).toEqual(["a"]);
+ expect(missingRequired({ ...schema, required: ["a"] }, { a: {} })).toEqual([]);
+ });
+
+ test("a schema with no required list demands nothing", () => {
+ expect(missingRequired({ type: "object" }, {})).toEqual([]);
+ expect(missingRequired(undefined, {})).toEqual([]);
+ });
+});
+
+describe("coerceToSchema: declared types, and a failure keeps the value", () => {
+ const schema = {
+ type: "object",
+ properties: {
+ count: { type: "integer" },
+ ratio: { type: "number" },
+ flag: { type: "boolean" },
+ name: { type: "string" },
+ },
+ };
+
+ test("a full numeric string becomes a number", () => {
+ expect(coerceToSchema(schema, { count: "5", ratio: "-1.5e2" }).args).toEqual({
+ count: 5,
+ ratio: -150,
+ });
+ });
+
+ test('"3abc" is NOT 3 — a partial parse would invent an argument', () => {
+ expect(coerceToSchema(schema, { count: "3abc" }).args).toEqual({ count: "3abc" });
+ });
+
+ test("a non-integer string is not forced into an integer field", () => {
+ expect(coerceToSchema(schema, { count: "2.5" }).args).toEqual({ count: "2.5" });
+ });
+
+ test('only exactly "true"/"false" become booleans', () => {
+ expect(coerceToSchema(schema, { flag: "true" }).args).toEqual({ flag: true });
+ expect(coerceToSchema(schema, { flag: "False" }).args).toEqual({ flag: false });
+ expect(coerceToSchema(schema, { flag: "yes" }).args).toEqual({ flag: "yes" });
+ });
+
+ test("a value already of the declared type is untouched", () => {
+ const args = { count: 5, name: "x" };
+ expect(coerceToSchema(schema, args).args).toBe(args);
+ });
+
+ test("an undeclared key is left exactly as it came", () => {
+ expect(coerceToSchema(schema, { whatever: "7" }).args).toEqual({ whatever: "7" });
+ });
+});
+
+describe("applySchemaDefaults: the schema's own value, for required keys only", () => {
+ const schema = {
+ type: "object",
+ properties: {
+ query: { type: "string" },
+ max_results: { type: "integer", default: 5 },
+ verbose: { type: "boolean", default: false },
+ },
+ required: ["query", "max_results"],
+ };
+
+ test("an absent required key takes its declared default", () => {
+ const { args, applied } = applySchemaDefaults(schema, { query: "x" });
+ expect(args).toEqual({ query: "x", max_results: 5 });
+ expect(applied).toEqual(["max_results"]);
+ });
+
+ test("a supplied value always wins, including a falsy one", () => {
+ expect(applySchemaDefaults(schema, { query: "x", max_results: 0 }).args.max_results).toBe(0);
+ });
+
+ test("an OPTIONAL key's default is not applied", () => {
+ // Deliberate: it would flip `repaired` on calls that were already valid, and
+ // `repaired` supersedes an already-streamed tool block in openai-sse.ts.
+ expect(applySchemaDefaults(schema, { query: "x" }).args).not.toHaveProperty("verbose");
+ });
+});
+
+describe("renameToDeclaredKeys: moves a supplied value, never invents one", () => {
+ const schema = {
+ type: "object",
+ properties: { command: { type: "string" } },
+ required: ["command"],
+ };
+
+ test("an undeclared synonym moves onto the declared required key", () => {
+ const { args, renamed } = renameToDeclaredKeys(schema, { cmd: "ls -la" });
+ expect(args).toEqual({ command: "ls -la" });
+ expect(renamed).toEqual(["cmd→command"]);
+ });
+
+ test("a supplied target is never overwritten", () => {
+ expect(renameToDeclaredKeys(schema, { command: "real", cmd: "other" }).args).toEqual({
+ command: "real",
+ cmd: "other",
+ });
+ });
+
+ test("an empty string counts as supplied and blocks the rename", () => {
+ expect(renameToDeclaredKeys(schema, { command: "", cmd: "other" }).args.command).toBe("");
+ });
+
+ test("a synonym the schema ALSO declares means something else and never moves", () => {
+ const declaresBoth = {
+ type: "object",
+ properties: { command: { type: "string" }, script: { type: "string" } },
+ required: ["command"],
+ };
+ expect(renameToDeclaredKeys(declaresBoth, { script: "x" }).args).toEqual({ script: "x" });
+ });
+
+ test("nothing is invented when no synonym was supplied", () => {
+ expect(renameToDeclaredKeys(schema, {}).args).toEqual({});
+ expect(missingRequired(schema, renameToDeclaredKeys(schema, {}).args)).toEqual(["command"]);
+ });
+
+ test("a non-required declared key is not a rename target", () => {
+ const optional = {
+ type: "object",
+ properties: { command: { type: "string" } },
+ required: [],
+ };
+ expect(renameToDeclaredKeys(optional, { cmd: "ls" }).args).toEqual({ cmd: "ls" });
+ });
+});
diff --git a/packages/cli/src/handlers/shared/schema-validate.ts b/packages/cli/src/handlers/shared/schema-validate.ts
index 6d6b8b14..3e1167d7 100644
--- a/packages/cli/src/handlers/shared/schema-validate.ts
+++ b/packages/cli/src/handlers/shared/schema-validate.ts
@@ -57,3 +57,256 @@ export function missingRequired(
return value === undefined || value === null;
});
}
+
+/** Is this key absent by the same rule {@link missingRequired} uses? */
+function isAbsent(args: Record<string, unknown>, key: string): boolean {
+ if (!Object.hasOwn(args, key)) return true;
+ const value = args[key];
+ return value === undefined || value === null;
+}
+
+/** The declared type(s) of one property, normalized to a list. */
+function declaredTypes(node: JsonSchemaNode | undefined): string[] {
+ if (!node) return [];
+ const t = node.type;
+ if (typeof t === "string") return [t];
+ if (Array.isArray(t)) return t.filter((x): x is string => typeof x === "string");
+ // No `type`, but an `enum` — the members' own kinds are the declaration.
+ // That is the ONLY thing `enum` is read for here. A value is never snapped to
+ // a near-matching member: picking "all" for a model that wrote "All" is
+ // choosing a value the model did not write, which is the fabrication this
+ // module exists to have removed.
+ if (Array.isArray(node.enum) && node.enum.length > 0) {
+ const kinds = new Set<string>();
+ for (const member of node.enum) {
+ if (member === null || member === undefined) continue;
+ if (Array.isArray(member)) kinds.add("array");
+ else if (typeof member === "object") kinds.add("object");
+ else if (typeof member === "number")
+ kinds.add(Number.isInteger(member) ? "integer" : "number");
+ else if (typeof member === "boolean") kinds.add("boolean");
+ else if (typeof member === "string") kinds.add("string");
+ }
+ return [...kinds];
+ }
+ return [];
+}
+
+/**
+ * A number literal spelled out in full — never `parseInt`, which reads `"3abc"`
+ * as `3` and would hand a tool an argument the model did not write.
+ */
+const FULL_NUMBER = /^[+-]?(\d+\.?\d*|\.\d+)([eE][+-]?\d+)?$/;
+
+/** Coerce one value to one declared type, or return `undefined` on failure. */
+function coerceOne(value: unknown, type: string, node: JsonSchemaNode | undefined): unknown {
+ switch (type) {
+ case "string":
+ return typeof value === "string"
+ ? value
+ : typeof value === "number" || typeof value === "boolean"
+ ? String(value)
+ : undefined;
+ case "number":
+ case "integer": {
+ if (typeof value === "number") {
+ return type === "integer" && !Number.isInteger(value) ? undefined : value;
+ }
+ if (typeof value !== "string" || !FULL_NUMBER.test(value.trim())) return undefined;
+ const n = Number(value.trim());
+ if (!Number.isFinite(n)) return undefined;
+ return type === "integer" && !Number.isInteger(n) ? undefined : n;
+ }
+ case "boolean": {
+ if (typeof value === "boolean") return value;
+ if (typeof value !== "string") return undefined;
+ const s = value.trim().toLowerCase();
+ return s === "true" ? true : s === "false" ? false : undefined;
+ }
+ case "array": {
+ const arr = Array.isArray(value) ? value : parseJsonOfKind(value, "array");
+ if (!Array.isArray(arr)) return undefined;
+ const items = node?.items;
+ if (!items) return arr;
+ return arr.map((el) => {
+ const target = declaredTypes(items);
+ for (const t of target) {
+ const c = coerceOne(el, t, items);
+ if (c !== undefined) return c;
+ }
+ return el;
+ });
+ }
+ case "object":
+ return value && typeof value === "object" && !Array.isArray(value)
+ ? value
+ : parseJsonOfKind(value, "object");
+ default:
+ return undefined;
+ }
+}
+
+/** JSON-parse a string and keep it only if it decoded to the expected kind. */
+function parseJsonOfKind(value: unknown, kind: "array" | "object"): unknown {
+ if (typeof value !== "string") return undefined;
+ try {
+ const parsed = JSON.parse(value);
+ if (kind === "array") return Array.isArray(parsed) ? parsed : undefined;
+ return parsed && typeof parsed === "object" && !Array.isArray(parsed) ? parsed : undefined;
+ } catch {
+ return undefined;
+ }
+}
+
+/**
+ * Give each supplied argument the type its schema declares.
+ *
+ * Needed because the `<function=NAME><parameter=P>` envelope has no types at
+ * all — every value arrives as a string, so a `number` parameter reaches the
+ * tool as `"5"` and a `boolean` as `"true"`.
+ *
+ * **A failed coercion keeps the original value.** It is never dropped and never
+ * replaced by a guess: the harness re-validates the call on arrival, so a wrong
+ * type is visible to the user while a missing key is not. Undeclared keys are
+ * left exactly as they came.
+ */
+export function coerceToSchema(
+ schema: JsonSchemaNode | undefined,
+ args: Record<string, unknown>
+): { args: Record<string, unknown>; coerced: string[] } {
+ const properties = schema?.properties;
+ if (!properties) return { args, coerced: [] };
+
+ const out: Record<string, unknown> = { ...args };
+ const coerced: string[] = [];
+ for (const [key, value] of Object.entries(args)) {
+ const node = properties[key];
+ if (!node || value === undefined || value === null) continue;
+ const types = declaredTypes(node);
+ if (types.length === 0) continue;
+ if (types.some((t) => matchesType(value, t))) continue;
+ for (const t of types) {
+ const c = coerceOne(value, t, node);
+ if (c !== undefined) {
+ out[key] = c;
+ coerced.push(key);
+ break;
+ }
+ }
+ }
+ return { args: coerced.length > 0 ? out : args, coerced };
+}
+
+/** Does this value already satisfy the declared type? Then leave it alone. */
+function matchesType(value: unknown, type: string): boolean {
+ switch (type) {
+ case "string":
+ return typeof value === "string";
+ case "number":
+ return typeof value === "number";
+ case "integer":
+ return typeof value === "number" && Number.isInteger(value);
+ case "boolean":
+ return typeof value === "boolean";
+ case "array":
+ return Array.isArray(value);
+ case "object":
+ return !!value && typeof value === "object" && !Array.isArray(value);
+ case "null":
+ return value === null;
+ default:
+ return false;
+ }
+}
+
+/**
+ * Fill absent REQUIRED arguments from the schema's own `default`.
+ *
+ * The value comes from the client's declaration of its own tool, so this is the
+ * schema speaking, not us guessing. This is how `ToolSearch.max_results = 5`
+ * survives the deletion of the hardcoded per-tool inference: tool-agnostically,
+ * as a `default` read.
+ *
+ * Scoped to `required` keys ON PURPOSE. An optional parameter with a default
+ * needs no help — Claude Code applies its own when it re-validates — and filling
+ * every optional default would flip `repaired` to true on calls that were
+ * already perfectly valid, which in `openai-sse.ts` supersedes an
+ * already-streamed tool block with a second one. The narrow rule keeps
+ * `repaired` meaning "this call would otherwise have failed".
+ */
+export function applySchemaDefaults(
+ schema: JsonSchemaNode | undefined,
+ args: Record<string, unknown>
+): { args: Record<string, unknown>; applied: string[] } {
+ const properties = schema?.properties;
+ const required = schema?.required;
+ if (!properties || !Array.isArray(required)) return { args, applied: [] };
+
+ const out: Record<string, unknown> = { ...args };
+ const applied: string[] = [];
+ for (const key of required) {
+ if (typeof key !== "string" || !isAbsent(out, key)) continue;
+ const node = properties[key];
+ if (!node || !Object.hasOwn(node, "default") || node.default === undefined) continue;
+ out[key] = node.default;
+ applied.push(key);
+ }
+ return { args: applied.length > 0 ? out : args, applied };
+}
+
+/**
+ * Names a model reaches for when it does not use the one the schema declares.
+ *
+ * This is a synonym vocabulary, not a roster in CLAUDE.md's sense: it is not
+ * per-user, not per-account, not time-varying, and it names no tool and no
+ * agent. Every entry RENAMES A VALUE THE MODEL SUPPLIED; none invents one. The
+ * gate in {@link renameToDeclaredKeys} is what makes that safe.
+ */
+const KEY_SYNONYMS: Record<string, string[]> = {
+ command: ["cmd", "shell", "script"],
+ file_path: ["path", "file", "filename"],
+ content: ["text", "data", "body"],
+ pattern: ["query", "search", "regex", "glob"],
+ query: ["search", "keyword"],
+ prompt: ["query", "task"],
+};
+
+/**
+ * Move a supplied value onto the key the schema actually declares.
+ *
+ * Three conditions, all required, and together they are why this is not the
+ * fabrication that was deleted:
+ *
+ * 1. the SOURCE key is one the schema does **not** declare — so nothing the
+ * tool asked for is ever overwritten or taken away;
+ * 2. the TARGET key **is** declared and **is** required — so this only ever
+ * rescues a call that would otherwise fail;
+ * 3. the target is **absent** — so a value the model did supply always wins.
+ *
+ * The value itself is untouched. A first matching synonym wins, and the source
+ * key is removed so the tool does not receive both spellings.
+ */
+export function renameToDeclaredKeys(
+ schema: JsonSchemaNode | undefined,
+ args: Record<string, unknown>
+): { args: Record<string, unknown>; renamed: string[] } {
+ const properties = schema?.properties;
+ const required = schema?.required;
+ if (!properties || !Array.isArray(required)) return { args, renamed: [] };
+
+ const out: Record<string, unknown> = { ...args };
+ const renamed: string[] = [];
+ for (const target of required) {
+ if (typeof target !== "string") continue;
+ if (!properties[target] || !isAbsent(out, target)) continue;
+ for (const source of KEY_SYNONYMS[target] ?? []) {
+ if (properties[source]) continue; // the schema declares it: it means something else
+ if (isAbsent(out, source)) continue;
+ out[target] = out[source];
+ delete out[source];
+ renamed.push(`${source}→${target}`);
+ break;
+ }
+ }
+ return { args: renamed.length > 0 ? out : args, renamed };
+}
diff --git a/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts b/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
index b7f68eaa..45ddaee9 100644
--- a/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
+++ b/packages/cli/src/handlers/shared/stream-parsers/openai-sse.ts
@@ -416,7 +416,11 @@ export function createStreamingResponseHandler(
? []
: extractToolCallsFromText(
state.accumulatedText,
- toolSchemas?.map((t: any) => t?.name).filter((n: any): n is string => !!n)
+ toolSchemas?.map((t: any) => t?.name).filter((n: any): n is string => !!n),
+ // 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
);
if (state.tools.size > 0 && state.accumulatedText.length > 0) {
log(
diff --git a/packages/cli/src/handlers/shared/tool-call-recovery.test.ts b/packages/cli/src/handlers/shared/tool-call-recovery.test.ts
index b9b74bda..d50ecba9 100644
--- a/packages/cli/src/handlers/shared/tool-call-recovery.test.ts
+++ b/packages/cli/src/handlers/shared/tool-call-recovery.test.ts
@@ -1,6 +1,10 @@
import { describe, expect, it } from "bun:test";
-import { extractToolCallsFromText, hasExtractableFunctionTag } from "./tool-call-recovery.js";
+import {
+ extractToolCallsFromText,
+ hasExtractableFunctionTag,
+ parseFunctionTagEnvelope,
+} from "./tool-call-recovery.js";
describe("extractToolCallsFromText tool-name validation", () => {
it("rejects a swallowed argument value without breaking Qwen-style recovery", () => {
@@ -56,3 +60,62 @@ describe("extractToolCallsFromText tool-name validation", () => {
expect(extractToolCallsFromText(invalid)).toEqual([]);
});
});
+
+/**
+ * The envelope parser runs BEFORE the six loose regex patterns and
+ * short-circuits on success, so its strictness is the only thing keeping that
+ * safe. Every case below is about what it REFUSES.
+ *
+ * No case here claims a model emitted anything — these are the parser's own
+ * contract. The positive cases are the existing Qwen recovery cases above, which
+ * now flow through this path.
+ */
+describe("parseFunctionTagEnvelope strictness", () => {
+ it("refuses text that merely describes the format", () => {
+ expect(parseFunctionTagEnvelope("Use the <function=NAME> format to call a tool.")).toBeNull();
+ expect(parseFunctionTagEnvelope("I'll use the Read tool to read the file.")).toBeNull();
+ expect(parseFunctionTagEnvelope("")).toBeNull();
+ });
+
+ it("refuses an envelope with anything in front of it", () => {
+ expect(parseFunctionTagEnvelope("Let me read it: <function=Read><parameter=file_path>/a")).toBe(
+ null
+ );
+ });
+
+ it("refuses a name that is not an identifier, exactly as the shape gate does", () => {
+ expect(parseFunctionTagEnvelope("<function=not a name!><parameter=x>1")).toBeNull();
+ });
+
+ it("parses two blocks as two calls, each with its own parameters", () => {
+ expect(
+ parseFunctionTagEnvelope(
+ "<function=Read><parameter=file_path>/a\n<function=Bash><parameter=command>ls"
+ )
+ ).toEqual([
+ { name: "Read", arguments: { file_path: "/a" }, source: "xml_text" },
+ { name: "Bash", arguments: { command: "ls" }, source: "xml_text" },
+ ]);
+ });
+
+ it("honours explicit closing tags rather than swallowing them into the value", () => {
+ expect(
+ parseFunctionTagEnvelope("<function=Read><parameter=file_path>/a</parameter></function>")?.[0]
+ ?.arguments
+ ).toEqual({ file_path: "/a" });
+ });
+
+ it("keeps a multi-line value whole", () => {
+ expect(
+ parseFunctionTagEnvelope("<function=Write><parameter=file_path>/a\n<parameter=content>x\ny")
+ ).toEqual([
+ { name: "Write", arguments: { file_path: "/a", content: "x\ny" }, source: "xml_text" },
+ ]);
+ });
+
+ it("still applies the advertised-tool allowlist through the extractor", () => {
+ const envelope = "<function=Unadvertised><parameter=value>x";
+ expect(parseFunctionTagEnvelope(envelope)).not.toBeNull();
+ expect(extractToolCallsFromText(envelope, ["Read"])).toEqual([]);
+ });
+});
diff --git a/packages/cli/src/handlers/shared/tool-call-recovery.ts b/packages/cli/src/handlers/shared/tool-call-recovery.ts
index af40df2f..ad48feb0 100644
--- a/packages/cli/src/handlers/shared/tool-call-recovery.ts
+++ b/packages/cli/src/handlers/shared/tool-call-recovery.ts
@@ -21,7 +21,13 @@
import { TOOL_NAME_SHAPE, TOOL_NAME_SOURCE } from "../../adapters/tool-name-utils.js";
import { log } from "../../logger.js";
-import { type JsonSchemaNode, missingRequired } from "./schema-validate.js";
+import {
+ type JsonSchemaNode,
+ applySchemaDefaults,
+ coerceToSchema,
+ missingRequired,
+ renameToDeclaredKeys,
+} from "./schema-validate.js";
export interface ExtractedToolCall {
name: string;
@@ -104,6 +110,112 @@ function keepOnlyRealTools(
return kept;
}
+/** `<function=NAME>` at exactly the cursor. Sticky, so it cannot skip ahead. */
+const FUNCTION_TAG_AT_CURSOR = new RegExp(`<function=(${TOOL_NAME_SOURCE})>`, "y");
+
+/** `<parameter=NAME>` at exactly the cursor, inside a function block. */
+const PARAMETER_TAG_AT_CURSOR = /<parameter=([^>\s]+)>/y;
+
+/**
+ * Parse a response that is ENTIRELY a `<function=NAME><parameter=P>V` envelope.
+ *
+ * Returns `null` the moment anything else appears, and that strictness is the
+ * whole point: it is what makes running this BEFORE the six loose regex
+ * patterns safe. Prose that merely mentions a function tag — a model explaining
+ * the format, or quoting a previous turn — does not match, so it cannot
+ * short-circuit anything.
+ *
+ * The loose Pattern 0 that still runs afterwards has a different failure mode: it
+ * scans anywhere in the text, so it takes the *last* value of a repeated
+ * parameter and swallows a trailing `</function>` into the value. Parsed as an
+ * envelope, both are handled — the block is delimited rather than guessed at.
+ *
+ * Nothing here relaxes the two gates. The name must be an identifier
+ * (`TOOL_NAME_SOURCE`), and the caller's own advertised tool list still filters
+ * the result through `keepOnlyRealTools`.
+ *
+ * NOT ADOPTED, deliberately: the upstream heuristic that reads a WebSearch call
+ * out of ordinary prose. It dispatches a tool from a sentence that only
+ * describes one.
+ */
+export function parseFunctionTagEnvelope(text: string): ExtractedToolCall[] | null {
+ const body = text.trim();
+ if (body.length === 0) return null;
+ if (!body.startsWith("<function=")) return null;
+
+ const calls: ExtractedToolCall[] = [];
+ let cursor = 0;
+
+ while (cursor < body.length) {
+ FUNCTION_TAG_AT_CURSOR.lastIndex = cursor;
+ const open = FUNCTION_TAG_AT_CURSOR.exec(body);
+ if (!open) return null;
+ cursor = FUNCTION_TAG_AT_CURSOR.lastIndex;
+
+ const args: Record<string, any> = {};
+ // Parameters, until the block ends. A block ends at `</function>`, at the
+ // next `<function=`, or at the end of the text — models emit all three.
+ while (cursor < body.length) {
+ const rest = body.slice(cursor);
+ const closeLen = /^\s*<\/function>/.exec(rest)?.[0].length;
+ if (closeLen !== undefined) {
+ cursor += closeLen;
+ break;
+ }
+ if (/^\s*<function=/.test(rest)) break;
+
+ const lead = /^\s*/.exec(rest)?.[0].length ?? 0;
+ PARAMETER_TAG_AT_CURSOR.lastIndex = cursor + lead;
+ const param = PARAMETER_TAG_AT_CURSOR.exec(body);
+ // Anything that is not a parameter tag means this is not an envelope.
+ if (!param) return null;
+
+ let valueStart = PARAMETER_TAG_AT_CURSOR.lastIndex;
+ // A newline directly after the tag is formatting, not content.
+ if (body[valueStart] === "\n") valueStart += 1;
+
+ const tail = body.slice(valueStart);
+ const end = /<\/parameter>|<\/function>|<parameter=|<function=/.exec(tail);
+ const raw = end ? tail.slice(0, end.index) : tail;
+ args[param[1]] = raw.trim();
+
+ cursor = valueStart + raw.length;
+ const consumedClose = /^<\/parameter>/.exec(body.slice(cursor))?.[0].length;
+ if (consumedClose !== undefined) cursor += consumedClose;
+ }
+
+ calls.push({ name: open[1], arguments: args, source: "xml_text" });
+
+ const gap = /^\s*/.exec(body.slice(cursor))?.[0].length ?? 0;
+ cursor += gap;
+ }
+
+ return calls.length > 0 ? calls : null;
+}
+
+/** Give one extracted call's arguments the shape its own schema declares. */
+function normalizeAgainstSchema(
+ call: ExtractedToolCall,
+ toolSchemas?: ToolSchema[]
+): ExtractedToolCall {
+ const schema = toolSchemas?.find((t) => t.name === call.name)?.input_schema as
+ | JsonSchemaNode
+ | undefined;
+ if (!schema) return call;
+
+ const renamed = renameToDeclaredKeys(schema, call.arguments);
+ const defaulted = applySchemaDefaults(schema, renamed.args);
+ const coerced = coerceToSchema(schema, defaulted.args);
+ if (renamed.renamed.length + defaulted.applied.length + coerced.coerced.length === 0) {
+ return call;
+ }
+ log(
+ `[ToolRecovery] Normalized ${call.name} against its schema: ` +
+ `renamed=[${renamed.renamed}] defaults=[${defaulted.applied}] coerced=[${coerced.coerced}]`
+ );
+ return { ...call, arguments: coerced.args as Record<string, any> };
+}
+
/**
* Extract tool calls from text content
* Many local models output tool calls as JSON in their text rather than using structured tool_calls
@@ -111,11 +223,25 @@ function keepOnlyRealTools(
* `knownToolNames` is the tool list the client advertised on THIS request. Pass
* it whenever it is in hand: every pattern below is then held to it, not just
* the natural-language one.
+ *
+ * `toolSchemas`, when supplied, types the extracted values: the envelope format
+ * carries no types, so every value arrives as a string.
*/
export function extractToolCallsFromText(
text: string,
- knownToolNames?: string[]
+ knownToolNames?: string[],
+ toolSchemas?: ToolSchema[]
): 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) =>
+ normalizeAgainstSchema(call, toolSchemas)
+ );
+ }
+
const extracted: ExtractedToolCall[] = [];
// Pattern 0: Qwen-style function calls <function=NAME><parameter=PARAM>VALUE
@@ -340,11 +466,16 @@ export function extractToolCallsFromText(
/**
* Validate a tool call's arguments against the tool's own JSON Schema.
*
- * `repaired` is reserved for a NON-DESTRUCTIVE transform of what the model
- * supplied — schema `default`s applied, a value moved to the key the schema
- * declares, a string coerced to its declared type. It must never again mean
- * "invented": the inference that used to set it is deleted (see the file header).
- * Nothing in this commit sets it; item 9 re-establishes it with that meaning.
+ * `repaired: true` means, and only means, that a schema `default` was applied or
+ * a supplied value was moved onto the key the schema declares. It must never
+ * again mean "invented": the inference that used to set it is deleted (see the
+ * file header).
+ *
+ * Coercion runs on every call but does NOT set `repaired`. It changes a value's
+ * type, never whether the call would have succeeded, and `repaired` drives a
+ * path in `openai-sse.ts` that supersedes an already-streamed tool block with a
+ * second one — a flag that fires on ordinary valid calls would mint duplicate
+ * blocks for nothing.
*
* `valid: false` therefore means the model genuinely omitted a required
* argument, which the caller surfaces to the user as a visible failure rather
@@ -372,7 +503,11 @@ export function validateAndRepairToolCall(
} catch (e) {
// Try to extract from text if structured parsing failed
if (textContent) {
- const extracted = extractToolCallsFromText(textContent);
+ const extracted = extractToolCallsFromText(
+ textContent,
+ toolSchemas.map((t) => t.name),
+ toolSchemas
+ );
const matching = extracted.find((tc) => tc.name === toolName);
if (matching) {
parsedArgs = matching.arguments;
@@ -381,11 +516,32 @@ export function validateAndRepairToolCall(
}
}
- const missingParams = missingRequired(schema.input_schema as JsonSchemaNode, parsedArgs);
+ const input = schema.input_schema as JsonSchemaNode;
+
+ // Rename first — a value under a synonym has to land on the declared key
+ // before anything asks whether that key is absent. Then defaults, which are
+ // the client's own declaration. Then types, over the final set.
+ const renamed = renameToDeclaredKeys(input, parsedArgs);
+ const defaulted = applySchemaDefaults(input, renamed.args);
+ const coerced = coerceToSchema(input, defaulted.args);
+ const args = coerced.args as Record<string, any>;
+ const repaired = renamed.renamed.length > 0 || defaulted.applied.length > 0;
+
+ if (repaired) {
+ log(
+ `[ToolRecovery] ${toolName}: applied schema defaults [${defaulted.applied}] ` +
+ `and key renames [${renamed.renamed}] — nothing was invented`
+ );
+ }
+ if (coerced.coerced.length > 0) {
+ log(`[ToolRecovery] ${toolName}: coerced to declared types [${coerced.coerced}]`);
+ }
+
+ const missingParams = missingRequired(input, args);
if (missingParams.length === 0) {
- return { valid: true, args: parsedArgs, repaired: false, missingParams: [] };
+ return { valid: true, args, repaired, missingParams: [] };
}
- return { valid: false, args: parsedArgs, repaired: false, missingParams };
+ return { valid: false, args, repaired: false, missingParams };
}