Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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<Buiopts.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[] = processeddiff --git a/test/context.test.ts b/test/context.test.tsindex 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.tsindex 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;+ }+}