Skip to content

Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.

fix(llm): parse emulated tool calls from content when the gateway ignores tool_choice (#129) (#216)

Frankie-Xudef0cf497380
diff --git a/src/ai/crux.ts b/src/ai/crux.ts
index 125ea50d..924ddd2c 100644
--- a/src/ai/crux.ts
+++ b/src/ai/crux.ts
@@ -15,6 +15,7 @@
* consumed once, at write time, to slice the crux text verbatim from source.
*/
import type { ChatModel } from "./llm/types.js";
+import { recoverToolArgsFromContent, warnToolChoiceIgnored } from "./llm/recover-tool.js";
import type { Kind } from "../graph/types.js";
/** One definition we want described, located by its line span within the file. */
@@ -128,50 +129,12 @@ function argsFromResponse(res: { text: string; toolCalls: { name: string; args:
if (call?.args && typeof call.args === "object" && !Array.isArray(call.args)) {
return call.args as { symbols?: unknown };
}
- return recoverArgsFromContent(res.text);
-}
-
-function recoverArgsFromContent(text: string): { symbols?: unknown } | undefined {
- const raw = text?.trim();
- if (!raw) return undefined;
- const stripped = raw.replace(/^```(?:json)?\s*/i, "").replace(/\s*```$/i, "").trim();
-
- const asSymbols = (value: unknown): { symbols?: unknown } | undefined => {
- if (!value || typeof value !== "object") return undefined;
- if (Array.isArray(value)) {
- for (const item of value) {
- if (!item || typeof item !== "object") continue;
- const rec = item as Record<string, unknown>;
- const name = typeof rec.name === "string" ? rec.name : "";
- // Accept the crux tool, or a generic emit_json wrapper some gateways use.
- if (name && name !== RECORD_TOOL && name !== "emit_json") continue;
- const params = rec.parameters ?? rec.arguments ?? rec.args;
- const hit = asSymbols(params);
- if (hit) return hit;
- }
- return undefined;
- }
- const obj = value as Record<string, unknown>;
- if (Array.isArray(obj.symbols)) return obj as { symbols?: unknown };
- return undefined;
- };
-
- try {
- const hit = asSymbols(JSON.parse(stripped));
- if (hit) return hit;
- } catch {
- /* try bracket slice below */
- }
- const start = stripped.indexOf("{");
- const end = stripped.lastIndexOf("}");
- if (start >= 0 && end > start) {
- try {
- return asSymbols(JSON.parse(stripped.slice(start, end + 1)));
- } catch {
- return undefined;
- }
- }
- return undefined;
+ const recovered = recoverToolArgsFromContent(res.text, {
+ toolNames: [RECORD_TOOL, "emit_json"],
+ payloadKey: "symbols",
+ });
+ if (!recovered) warnToolChoiceIgnored("crux", res.text?.trim() ? "unparsed" : "empty");
+ return recovered as { symbols?: unknown } | undefined;
}
/** Crux summarizer backed by any {@link ChatModel} via forced tool calling. */
diff --git a/src/ai/llm/recover-tool.ts b/src/ai/llm/recover-tool.ts
new file mode 100644
index 00000000..625a91bd
--- /dev/null
+++ b/src/ai/llm/recover-tool.ts
@@ -0,0 +1,103 @@
+/**
+ * Recover a forced-tool payload from assistant `content` when a gateway ignored
+ * `tool_choice` and wrote JSON text instead of `tool_calls` (#129).
+ *
+ * Conservative: only succeeds when `text` parses as JSON matching one of:
+ * - `[{ name, parameters|arguments|args }]`
+ * - `{ name, parameters|arguments|args }`
+ * - a fenced ```json block wrapping either
+ * - a bare object whose `payloadKey` is an array
+ * Anything else (prose, truncated JSON, a guessed shape) returns undefined.
+ * Callers MUST run the same schema validation they use for real tool calls.
+ */
+
+/** Leading/trailing ```json fence, linear in `raw.length` — no quantified-whitespace regex. */
+function unwrapMarkdownFence(raw: string): string {
+ let s = raw;
+ if (s.startsWith("```")) {
+ s = s.slice(3);
+ if (s.length >= 4 && s.slice(0, 4).toLowerCase() === "json") s = s.slice(4);
+ s = s.trimStart();
+ }
+ if (s.endsWith("```")) s = s.slice(0, -3).trimEnd();
+ return s.trim();
+}
+
+export function recoverToolArgsFromContent(
+ text: string,
+ opts: { toolNames: readonly string[]; payloadKey: string },
+): Record<string, unknown> | undefined {
+ const raw = text?.trim();
+ if (!raw) return undefined;
+ const stripped = unwrapMarkdownFence(raw);
+ const accepted = new Set(opts.toolNames);
+
+ const asPayload = (value: unknown): Record<string, unknown> | undefined => {
+ if (!value || typeof value !== "object") return undefined;
+ if (Array.isArray(value)) {
+ for (const item of value) {
+ const hit = asPayload(item);
+ if (hit) return hit;
+ }
+ return undefined;
+ }
+ const obj = value as Record<string, unknown>;
+ const wrapped =
+ typeof obj.name === "string" || "parameters" in obj || "arguments" in obj || "args" in obj;
+ if (wrapped) {
+ const name = typeof obj.name === "string" ? obj.name : "";
+ if (name && !accepted.has(name)) return undefined;
+ let params: unknown = obj.parameters ?? obj.arguments ?? obj.args;
+ if (typeof params === "string") {
+ try {
+ params = JSON.parse(params);
+ } catch {
+ return undefined;
+ }
+ }
+ const hit = asPayload(params);
+ if (hit) return hit;
+ // `{ name, nodes: [...] }` — payload at the same level as the wrapper.
+ if (Array.isArray(obj[opts.payloadKey])) return obj;
+ return undefined;
+ }
+ if (Array.isArray(obj[opts.payloadKey])) return obj;
+ return undefined;
+ };
+
+ try {
+ const hit = asPayload(JSON.parse(stripped));
+ if (hit) return hit;
+ } catch {
+ /* try a bracket slice below */
+ }
+ const objStart = stripped.indexOf("{");
+ const objEnd = stripped.lastIndexOf("}");
+ if (objStart >= 0 && objEnd > objStart) {
+ try {
+ const hit = asPayload(JSON.parse(stripped.slice(objStart, objEnd + 1)));
+ if (hit) return hit;
+ } catch {
+ /* try array slice */
+ }
+ }
+ const arrStart = stripped.indexOf("[");
+ const arrEnd = stripped.lastIndexOf("]");
+ if (arrStart >= 0 && arrEnd > arrStart) {
+ try {
+ return asPayload(JSON.parse(stripped.slice(arrStart, arrEnd + 1)));
+ } catch {
+ return undefined;
+ }
+ }
+ return undefined;
+}
+
+/** One stderr line when a structured op got neither a tool call nor recoverable JSON. */
+export function warnToolChoiceIgnored(op: string, reason: "empty" | "unparsed"): void {
+ const detail =
+ reason === "empty"
+ ? "model returned no tool call and no content (provider may ignore forced tool_choice)"
+ : "model did not honor tool_choice and content is not parseable tool-call JSON";
+ console.error(`⚠ ${op}: ${detail} — this batch is empty`);
+}
diff --git a/src/ai/synthesize.ts b/src/ai/synthesize.ts
index b4638692..59c9515d 100644
--- a/src/ai/synthesize.ts
+++ b/src/ai/synthesize.ts
@@ -7,6 +7,7 @@
* grounded in, so provenance (and staleness) stays exact.
*/
import type { ChatModel } from "./llm/types.js";
+import { recoverToolArgsFromContent, warnToolChoiceIgnored } from "./llm/recover-tool.js";
/** A directed edge to another node, by node name (resolved to a slug later). */
export interface SynthLink {
@@ -146,10 +147,26 @@ export class ChatSynthesizer implements Synthesizer {
{ role: "user", content: userContent(files) },
],
});
- const call = res.toolCalls[0];
- if (!call) return [];
- // `args` is already a parsed object — no JSON.parse.
- return clean((call.args as { nodes?: unknown })?.nodes);
+ return clean(nodesFromResponse(res)?.nodes);
}
}
+/**
+ * Prefer a real tool call; if the gateway ignored `tool_choice` (#129), recover
+ * the same payload from `content`. Recovered args still go through {@link clean}.
+ */
+function nodesFromResponse(res: { text: string; toolCalls: { name: string; args: unknown }[] }): {
+ nodes?: unknown;
+} | undefined {
+ const call = res.toolCalls.find((c) => c.name === RECORD_TOOL) ?? res.toolCalls[0];
+ if (call?.args && typeof call.args === "object" && !Array.isArray(call.args)) {
+ return call.args as { nodes?: unknown };
+ }
+ const recovered = recoverToolArgsFromContent(res.text, {
+ toolNames: [RECORD_TOOL, "emit_json"],
+ payloadKey: "nodes",
+ });
+ if (!recovered) warnToolChoiceIgnored("synthesize", res.text?.trim() ? "unparsed" : "empty");
+ return recovered as { nodes?: unknown } | undefined;
+}
+
diff --git a/src/context/build.ts b/src/context/build.ts
index f6440803..1bfd1625 100644
--- a/src/context/build.ts
+++ b/src/context/build.ts
@@ -216,15 +216,28 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
opts.onProgress?.({ phase: "synthesize", index: b, total: batches.length, file: `batch ${b + 1}` });
const key = batchKey(batches[b], hashByPath);
let nodes = cache.synth[key];
- if (!nodes) {
+ // An empty array is a miss, not a hit: caching [] made a silent empty
+ // synthesis permanent, the same trap #177 closed for the meaning pass (#129).
+ const cached = Array.isArray(nodes) && nodes.length > 0;
+ if (!cached) {
nodes = await opts.synthesizer.synthesize(batches[b]);
- cache.synth[key] = nodes;
+ if (nodes.length > 0) cache.synth[key] = nodes;
+ else delete cache.synth[key];
}
+ const links = nodes.reduce((n, node) => n + node.links.length, 0);
+ console.error(
+ ` synthesis batch ${b + 1}/${batches.length}: ${nodes.length} nodes, ${links} links${cached ? " (cached)" : ""}`,
+ );
synthNodes.push(...nodes);
}
// Drop cache entries for batches we no longer produce, so it can't grow forever.
+ // Skip empty arrays so a failed batch is retried on the next --deep, not frozen.
cache.synth = Object.fromEntries(
- batches.map((batch) => [batchKey(batch, hashByPath), cache.synth[batchKey(batch, hashByPath)] ?? []]),
+ batches.flatMap((batch) => {
+ const k = batchKey(batch, hashByPath);
+ const v = cache.synth[k];
+ return v && v.length > 0 ? [[k, v] as [string, SynthNode[]]] : [];
+ }),
);
saveCache(outDir, cache);
@@ -297,6 +310,13 @@ export async function buildContext(dir: string, opts: BuildOptions): Promise<Bui
}
result.nodes = nodes.length;
result.links = nodes.reduce((n, node) => n + node.links.length, 0);
+ // Failure mode 2 (#129): a model can emit real tool_calls whose quality
+ // collapsed (many batches, zero links) with nothing per-batch in the log.
+ if (result.links === 0 && result.batches > 1) {
+ console.error(
+ `⚠ synthesis produced 0 links across ${result.batches} batches — the model may be degrading; see per-batch counts above`,
+ );
+ }
// Manifest: authoritative file→hash map (every processed file) + node roster.
const fileRefs: SourceRef[] = processed
diff --git a/test/context.test.ts b/test/context.test.ts
index 0bcf73d2..fd0cf02c 100644
--- a/test/context.test.ts
+++ b/test/context.test.ts
@@ -12,7 +12,8 @@ import { buildContext } from "../src/context/build.js";
import { checkContext, indexFreshness, staleBanner } from "../src/context/check.js";
import { contextDirFor, ensureGitignored, ensureSearchable } from "../src/context/node-file.js";
import { writeBuildConfig } from "../src/util/state.js";
-import { fakeProviders } from "./helpers.js";
+import { fakeProviders, PassthroughSummarizer } from "./helpers.js";
+import type { Synthesizer } from "../src/index.js";
// CLI-spawn helper (same pattern as test/graph-traverse-cli.test.ts) — these tests
// exercise the real process boundary (exit codes), which a unit-level call into
@@ -430,3 +431,64 @@ test("ensureSearchable: no-op when the graph dir is outside the repo root", () =
rmSync(dir, { recursive: true, force: true });
}
});
+
+test("#129: an empty synthesis batch is not cached — the next build retries", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "ctx-empty-synth-"));
+ try {
+ writeFileSync(join(dir, "a.ts"), "export const a = 1;\n");
+ let calls = 0;
+ const synthesizer: Synthesizer = {
+ async synthesize() {
+ calls++;
+ return [];
+ },
+ };
+ const opts = { model: "fake", summarizer: new PassthroughSummarizer(), synthesizer };
+ await buildContext(dir, opts);
+ await buildContext(dir, opts);
+ assert.equal(calls, 2, "[] must not become a cache hit the way #177 refused empty meaning replies");
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
+
+test("#129: synthesis logs per-batch counts and warns when a multi-batch run has 0 links", async () => {
+ const dir = mkdtempSync(join(tmpdir(), "ctx-zero-links-"));
+ const blob = (name: string) => `export const ${name} = 1;\n// ${"x".repeat(30_000)}\n`;
+ try {
+ writeFileSync(join(dir, "a.ts"), blob("a"));
+ writeFileSync(join(dir, "b.ts"), blob("b"));
+ const synthesizer: Synthesizer = {
+ async synthesize(files) {
+ return files.map((f) => ({
+ name: f.path,
+ type: "file",
+ summary: "s",
+ sources: [f.path],
+ links: [],
+ }));
+ },
+ };
+ const err: string[] = [];
+ const orig = console.error;
+ console.error = (...args: unknown[]) => {
+ err.push(args.map(String).join(" "));
+ };
+ try {
+ const r = await buildContext(dir, {
+ model: "fake",
+ summarizer: new PassthroughSummarizer(),
+ synthesizer,
+ });
+ assert.ok(r.batches > 1, `need multiple batches to trigger the summary warning, got ${r.batches}`);
+ assert.equal(r.links, 0);
+ assert.ok(err.some((l) => /synthesis batch 1\/\d+: \d+ nodes, 0 links/.test(l)));
+ assert.ok(err.some((l) => /synthesis batch 2\/\d+:/.test(l)));
+ assert.ok(err.some((l) => /0 links across \d+ batches/.test(l)));
+ } finally {
+ console.error = orig;
+ }
+ } finally {
+ rmSync(dir, { recursive: true, force: true });
+ }
+});
diff --git a/test/llm-ops.test.ts b/test/llm-ops.test.ts
index 9ff7d082..560623cd 100644
--- a/test/llm-ops.test.ts
+++ b/test/llm-ops.test.ts
@@ -9,6 +9,7 @@ import assert from "node:assert/strict";
import { ChatSummarizer } from "../src/ai/summarize.js";
import { ChatSynthesizer } from "../src/ai/synthesize.js";
import { ChatCruxSummarizer } from "../src/ai/crux.js";
+import { recoverToolArgsFromContent } from "../src/ai/llm/recover-tool.js";
import type { ChatModel, ChatRequest, ChatResponse, ToolCall } from "../src/ai/llm/types.js";
/** Records the last request and replays a canned response. */
@@ -69,13 +70,112 @@ test("ChatCruxSummarizer forces record_symbols and normalizes numbers", async ()
test("structured ops degrade gracefully when the model returns no tool call", async () => {
const empty = new FakeChatModel({ toolCalls: [] });
- assert.deepEqual(await new ChatSynthesizer(empty).synthesize([{ path: "a.ts", summary: "x" }]), []);
+ const { err } = await withCapturedError(async () => {
+ assert.deepEqual(await new ChatSynthesizer(empty).synthesize([{ path: "a.ts", summary: "x" }]), []);
+ assert.deepEqual(
+ await new ChatCruxSummarizer(empty).describeFile({
+ path: "a.ts",
+ source: "x",
+ nodes: [{ id: "s", kind: "function", signature: null, startLine: 1, endLine: 1 }],
+ }),
+ [],
+ );
+ });
+ assert.ok(err.some((l) => /synthesize:.*no tool call and no content/.test(l)));
+ assert.ok(err.some((l) => /crux:.*no tool call and no content/.test(l)));
+});
+
+const AUTH_NODE = { name: "Auth", type: "system", summary: "s", sources: ["a.ts"], links: [] as [] };
+const AUTH_PAYLOAD = { nodes: [AUTH_NODE] };
+
+test("#129: ChatSynthesizer recovers nodes from content JSON when toolCalls is empty", async () => {
+ const m = new FakeChatModel({
+ text: JSON.stringify([{ name: "emit_json", parameters: AUTH_PAYLOAD }]),
+ toolCalls: [],
+ });
+ const { result: nodes, err } = await withCapturedError(() =>
+ new ChatSynthesizer(m).synthesize([{ path: "a.ts", summary: "x" }]),
+ );
+ assert.equal(nodes.length, 1);
+ assert.equal(nodes[0].name, "Auth");
+ assert.equal(err.length, 0);
+});
+
+test("#129: ChatSynthesizer recovers a single-object wrapper and a fenced JSON payload", async () => {
+ const objectWrap = new FakeChatModel({
+ text: JSON.stringify({ name: "record_graph", parameters: AUTH_PAYLOAD }),
+ toolCalls: [],
+ });
+ assert.equal((await new ChatSynthesizer(objectWrap).synthesize([{ path: "a.ts", summary: "x" }]))[0]?.name, "Auth");
+
+ const fenced = new FakeChatModel({
+ text: "```json\n" + JSON.stringify(AUTH_PAYLOAD) + "\n```",
+ toolCalls: [],
+ });
+ assert.equal((await new ChatSynthesizer(fenced).synthesize([{ path: "a.ts", summary: "x" }]))[0]?.name, "Auth");
+});
+
+test("#129: unparseable content warns and does not throw", async () => {
+ const m = new FakeChatModel({ text: "The architecture is a layered monolith.", toolCalls: [] });
+ const { result: nodes, err } = await withCapturedError(() =>
+ new ChatSynthesizer(m).synthesize([{ path: "a.ts", summary: "x" }]),
+ );
+ assert.deepEqual(nodes, []);
+ assert.ok(err.some((l) => /synthesize:.*not parseable tool-call JSON/.test(l)));
+});
+
+test("#129: a real toolCalls payload is preferred over content JSON", async () => {
+ const m = new FakeChatModel({
+ text: JSON.stringify({ nodes: [{ name: "WRONG", type: "system", summary: "s", sources: ["a.ts"], links: [] }] }),
+ toolCalls: [{ id: "1", name: "record_graph", args: AUTH_PAYLOAD }],
+ });
+ const nodes = await new ChatSynthesizer(m).synthesize([{ path: "a.ts", summary: "x" }]);
+ assert.equal(nodes.length, 1);
+ assert.equal(nodes[0].name, "Auth");
+});
+
+const RECOVER_OPTS = { toolNames: ["record_graph", "emit_json"] as const, payloadKey: "nodes" };
+
+test("#129: recoverToolArgsFromContent accepts the three issue shapes and refuses the rest", () => {
+ const payload = { nodes: [{ name: "Auth" }] };
assert.deepEqual(
- await new ChatCruxSummarizer(empty).describeFile({
- path: "a.ts",
- source: "x",
- nodes: [{ id: "s", kind: "function", signature: null, startLine: 1, endLine: 1 }],
- }),
- [],
+ recoverToolArgsFromContent(JSON.stringify([{ name: "emit_json", parameters: payload }]), RECOVER_OPTS)?.nodes,
+ payload.nodes,
+ );
+ assert.deepEqual(
+ recoverToolArgsFromContent(JSON.stringify({ name: "record_graph", parameters: payload }), RECOVER_OPTS)?.nodes,
+ payload.nodes,
+ );
+ assert.deepEqual(
+ recoverToolArgsFromContent("```json\n" + JSON.stringify(payload) + "\n```", RECOVER_OPTS)?.nodes,
+ payload.nodes,
+ );
+ // CodeQL js/polynomial-redos: spaces around a fence must stay linear and still parse.
+ const padded =
+ " ".repeat(8_000) + "```json" + " ".repeat(8_000) + JSON.stringify(payload) + " ".repeat(8_000) + "```";
+ assert.deepEqual(recoverToolArgsFromContent(padded, RECOVER_OPTS)?.nodes, payload.nodes);
+ assert.equal(recoverToolArgsFromContent("The architecture is a layered monolith.", RECOVER_OPTS), undefined);
+ assert.equal(recoverToolArgsFromContent("", RECOVER_OPTS), undefined);
+ assert.equal(
+ recoverToolArgsFromContent('[{"name":"emit_json","parameters":{"nodes":[', RECOVER_OPTS),
+ undefined,
+ );
+ assert.equal(
+ recoverToolArgsFromContent(JSON.stringify([{ name: "other_tool", parameters: payload }]), RECOVER_OPTS),
+ undefined,
);
});
+
+/** Capture console.error so tests can assert the #129 warnings without leaking them. */
+async function withCapturedError<T>(fn: () => Promise<T>): Promise<{ result: T; err: string[] }> {
+ const err: string[] = [];
+ const orig = console.error;
+ console.error = (...args: unknown[]) => {
+ err.push(args.map((a) => String(a)).join(" "));
+ };
+ try {
+ return { result: await fn(), err };
+ } finally {
+ console.error = orig;
+ }
+}