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(crux): match echoed target ids against the requested ids and name the miss (#492)
Antônio Froz25b64523c533
diff --git a/src/ai/crux.ts b/src/ai/crux.tsindex dd90d3c8..b23c7b74 100644--- a/src/ai/crux.ts+++ b/src/ai/crux.ts@@ -47,11 +47,19 @@ export interface CruxSummarizer {}/** Why a crux call produced no usable summaries (#235). */-export type CruxMissKind = "empty-toolCalls" | "unparseable" | "truncated" | "empty-parsed";+export type CruxMissKind =+ | "empty-toolCalls"+ | "unparseable"+ | "truncated"+ | "empty-parsed"+ | "id-mismatch";export interface CruxMiss {kind: CruxMissKind;finishReason: string | null;+ /** `id-mismatch` only: how many entries came back, and the first one's raw id. */+ returned?: number;+ firstId?: string;}function isTruncatedStop(reason: string | null): boolean {@@ -60,11 +68,24 @@ function isTruncatedStop(reason: string | null): boolean {return r === "length" || r === "max_tokens";}-/** Classify an empty/unusable crux reply. `null` means at least one usable summary. */-export function classifyCruxMiss(res: ChatResponse, parsed: NodeCrux[]): CruxMiss | null {+/**+ * Classify an empty/unusable crux reply. `null` means at least one usable summary.+ * With `requested`, a summary only counts when its id is one we asked for: enrich+ * looks results up by node id, so a summary under any other id is never applied.+ */+export function classifyCruxMiss(+ res: ChatResponse,+ parsed: NodeCrux[],+ requested?: readonly string[],+): CruxMiss | null {const finishReason = res.stopReason;- if (parsed.some((p) => p.summary.trim())) return null;+ const wanted = requested ? new Set(requested) : undefined;+ const matched = wanted ? parsed.filter((p) => wanted.has(p.id)) : parsed;+ if (matched.some((p) => p.summary.trim())) return null;if (isTruncatedStop(finishReason)) return { kind: "truncated", finishReason };+ if (parsed.length > 0 && matched.length === 0) {+ return { kind: "id-mismatch", finishReason, returned: parsed.length, firstId: parsed[0].id };+ }if (parsed.length > 0) return { kind: "empty-parsed", finishReason };const emptyTools = res.toolCalls.length === 0;const emptyText = !res.text?.trim();@@ -75,9 +96,29 @@ export function classifyCruxMiss(res: ChatResponse, parsed: NodeCrux[]): CruxMis/** Per-file error text: miss class + the provider's finish_reason (#235). */export function formatCruxMiss(kind: CruxMissKind, finishReason: string | null): string {const fr = finishReason == null || finishReason === "" ? "null" : finishReason;+ if (kind === "id-mismatch") {+ return `model returned summaries but no id matched a requested target [${kind}, finish_reason=${fr}]`;+ }return `model returned no usable symbol summaries [${kind}, finish_reason=${fr}]`;}+/** Longest echoed id shown in an error; a whole echoed row can carry a long signature. */+const MAX_SHOWN_ID_CHARS = 200;++/**+ * The model's text for an `id-mismatch`, kept apart from {@link formatCruxMiss}:+ * the failure gate matches words like "quota" in the error message, and a+ * returned id can carry any source text, so it must never reach the gate.+ */+export function formatCruxMissDetail(miss: CruxMiss | null | undefined): string {+ if (miss?.kind !== "id-mismatch" || miss.firstId === undefined) return "";+ const id =+ miss.firstId.length > MAX_SHOWN_ID_CHARS+ ? `${miss.firstId.slice(0, MAX_SHOWN_ID_CHARS)}…`+ : miss.firstId;+ return `first of ${miss.returned ?? 1} returned id(s): ${JSON.stringify(id)}`;+}+const SYSTEM_PROMPT = `You explain code definitions for a code graph that helps engineers navigate a codebase.You are given ONE source file with 1-based line numbers, and a list of TARGET definitions in it. Describe EVERY target via the record_symbols tool.@@ -122,27 +163,73 @@ function numberLines(source: string): string {.join("\n");}+/**+ * `id=` is the LAST field of a target line, so the id ends where the line does.+ * With the id first nothing terminated it, and models asked for the id+ * "verbatim" copied the whole row — `a.cs#Level | variable | lines L58-L58 | sig`+ * — into `id` (#259). {@link resolveTargetId} still repairs echoes of either layout.+ */function userContent(input: FileCruxInput): string {const targets = input.nodes.map((n) =>- `- id=${n.id} | ${n.kind} | lines L${n.startLine}-L${n.endLine}` +- (n.signature ? ` | ${n.signature}` : ""),+ `- ${n.kind} | lines L${n.startLine}-L${n.endLine}` ++ (n.signature ? ` | ${n.signature}` : "") ++ ` | id=${n.id}`,).join("\n");const n = input.nodes.length;return `FILE: ${input.path}\n\n${numberLines(input.source)}\n\nTARGETS (${n} — return all ${n}, one entry per id):\n${targets}`;}-/** Normalize the tool's parsed argument object into a {@link NodeCrux} list. */-function parseResults(obj: { symbols?: unknown } | undefined): NodeCrux[] {+/** The longest requested id `test` accepts, or null. */+function longestMatch(requested: readonly string[], test: (id: string) => boolean): string | null {+ let best: string | null = null;+ for (const id of requested) if (test(id) && (best === null || id.length > best.length)) best = id;+ return best;+}++/**+ * Map an id the model returned onto one of the ids we asked for, or null.+ *+ * Models echo decorated target rows instead of the bare id (#259, #298, #486).+ * Rather than cut the string at a guessed delimiter, every rule compares against+ * the requested ids, so the result is always an id we asked for — never a+ * fragment of a hallucinated one — and no rule assumes which characters an id+ * may contain. In order:+ * 1. exact match;+ * 2. a requested id followed by ` | ` (the row echoed from the id onwards);+ * 3. the same two with a leading `id=` removed;+ * 4. a row ending in ` | id=<requested id>` (the current layout echoed whole).+ * When several requested ids qualify, the longest wins.+ */+export function resolveTargetId(raw: string, requested: readonly string[]): string | null {+ const id = raw.trim();+ if (requested.includes(id)) return id;+ const echoed = longestMatch(requested, (r) => id.startsWith(`${r} | `));+ if (echoed) return echoed;+ if (id.startsWith("id=")) {+ const bare = id.slice(3).trim();+ if (requested.includes(bare)) return bare;+ const bareEchoed = longestMatch(requested, (r) => bare.startsWith(`${r} | `));+ if (bareEchoed) return bareEchoed;+ }+ return longestMatch(requested, (r) => id.endsWith(` | id=${r}`));+}++/**+ * Normalize the tool's parsed argument object into a {@link NodeCrux} list. Ids+ * are resolved against `requested`; one that matches nothing keeps its raw text+ * so {@link classifyCruxMiss} can report what the model actually sent.+ */+function parseResults(obj: { symbols?: unknown } | undefined, requested: readonly string[]): NodeCrux[] {if (!obj || !Array.isArray(obj.symbols)) return [];const num = (v: unknown) => (typeof v === "number" && Number.isFinite(v) ? Math.trunc(v) : 0);return obj.symbols.map((s) => s as Record<string, unknown>).filter((s) => typeof s.id === "string").map((s) => ({- id: s.id as string,+ id: resolveTargetId(s.id as string, requested) ?? (s.id as string),summary: typeof s.summary === "string" ? s.summary.trim() : "",crux_start: num(s.crux_start),crux_end: num(s.crux_end),@@ -196,8 +283,9 @@ export class ChatCruxSummarizer implements CruxSummarizer {{ role: "user", content: userContent(input) },],});- const parsed = parseResults(argsFromResponse(res));- this.lastMiss = classifyCruxMiss(res, parsed);+ const requested = input.nodes.map((n) => n.id);+ const parsed = parseResults(argsFromResponse(res), requested);+ this.lastMiss = classifyCruxMiss(res, parsed, requested);return parsed;}}diff --git a/src/graph/enrich.ts b/src/graph/enrich.tsindex f18a3b2c..8f8a6635 100644--- a/src/graph/enrich.ts+++ b/src/graph/enrich.ts@@ -19,7 +19,7 @@* once, to cut `crux.code` verbatim from the source. `crux.span` is a pointer* only and is never used to re-slice.*/-import { formatCruxMiss, type CruxMissKind, type CruxSummarizer, type NodeCrux, type NodeRef } from "../ai/crux.js";+import { formatCruxMiss, formatCruxMissDetail, type CruxMissKind, type CruxSummarizer, type NodeCrux, type NodeRef } from "../ai/crux.js";import { LlmFailureGate } from "../ai/failure.js";import type { Crux, NodeV1 } from "./types.js";@@ -171,7 +171,7 @@ export async function enrichGraph(const { results, error, quality } = await collectFileCrux(summarizer, path, source, refs);let fileError = error;if (fileError) {- stats.errors.push(`${path}: ${fileError}`);+ stats.errors.push(`${path}: ${fileError}${cruxMissDetail(summarizer)}`);gate.record(fileError, { quality });}@@ -198,7 +198,7 @@ export async function enrichGraph(// collectFileCrux already labels a total miss; this catches "got entries// but every summary was blank" so the CLI's #127 degraded-exit path fires.fileError = cruxMissMessage(summarizer, "empty-parsed");- stats.errors.push(`${path}: ${fileError}`);+ stats.errors.push(`${path}: ${fileError}${cruxMissDetail(summarizer)}`);gate.record(fileError, { quality: true });} else if (!fileError) {gate.succeeded();@@ -245,6 +245,12 @@ function cruxMissMessage(summarizer: CruxSummarizer, fallback: CruxMissKind): streturn formatCruxMiss(miss?.kind ?? fallback, miss?.finishReason ?? null);}+/** The echoed id behind an `id-mismatch`, as an indented second line; "" otherwise. */+function cruxMissDetail(summarizer: CruxSummarizer): string {+ const detail = formatCruxMissDetail(summarizer.lastMiss);+ return detail ? `\n ${detail}` : "";+}+/*** Describe every requested definition in a file, re-asking for any the model* omits (it sometimes drops entries from a batch). Returns whatever it collecteddiff --git a/test/graph-enrich-quality.test.ts b/test/graph-enrich-quality.test.tsindex 1e09a24f..cee3257a 100644--- a/test/graph-enrich-quality.test.ts+++ b/test/graph-enrich-quality.test.ts@@ -184,3 +184,29 @@ test("#235: blank parsed summaries name empty-parsed and stay pending", async ()assert.equal(nodes[0].summary_state, "pending");assert.equal(nodes[0].summary, null);});++test("#259: unmatched ids name id-mismatch with the returned id, and never reach the gate", async () => {+ // A returned id can hold any source text; "Quota" here must not read as a quota error.+ const invented = "f0.ts#Quota | function | lines L1-L3";+ const summarizer = new ChatCruxSummarizer(+ new CannedModel({+ toolCalls: [+ {+ id: "1",+ name: "record_symbols",+ args: { symbols: [{ id: invented, summary: "runs it", crux_start: 0, crux_end: 0 }] },+ },+ ],+ stopReason: "tool_calls",+ }),+ );+ const { stats, nodes } = await oneFile(summarizer);+ assert.equal(stats.failedFiles, 1);+ assert.equal(stats.fatal, undefined);+ assert.equal(+ stats.errors[0],+ "f0.ts: model returned summaries but no id matched a requested target [id-mismatch, finish_reason=tool_calls]" ++ `\n first of 1 returned id(s): ${JSON.stringify(invented)}`,+ );+ assert.equal(nodes[0].summary_state, "pending");+});diff --git a/test/llm-ops.test.ts b/test/llm-ops.test.tsindex 560623cd..4483b3b8 100644--- a/test/llm-ops.test.ts+++ b/test/llm-ops.test.ts@@ -8,7 +8,12 @@ import { test } from "node:test";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 {+ ChatCruxSummarizer,+ formatCruxMiss,+ formatCruxMissDetail,+ resolveTargetId,+} 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";@@ -68,6 +73,96 @@ test("ChatCruxSummarizer forces record_symbols and normalizes numbers", async ()assert.deepEqual(out, [{ id: "sym1", summary: "does x", crux_start: 3, crux_end: 5 }]);});+/** A crux reply carrying one entry per id in `ids`, in order. */+function cruxReply(ids: string[]): FakeChatModel {+ const symbols = ids.map((id, i) => ({ id, summary: `summary ${i}`, crux_start: 0, crux_end: 0 }));+ return new FakeChatModel({ toolCalls: [{ id: "1", name: "record_symbols", args: { symbols } }] });+}++const CRUX_INPUT = {+ path: "Runtime/Core/Ctx.cs",+ source: "l1\nl2\nl3\nl4\nl5\n",+ nodes: [+ { id: "Runtime/Core/Ctx.cs", kind: "file" as const, signature: null, startLine: 1, endLine: 5 },+ {+ id: "Runtime/Core/Ctx.cs#Level",+ kind: "variable" as const,+ signature: "public int Level { get; }",+ startLine: 3,+ endLine: 3,+ },+ ],+};++test("crux target lines end with the id, so the id field is terminated (#259)", async () => {+ const m = cruxReply(["Runtime/Core/Ctx.cs", "Runtime/Core/Ctx.cs#Level"]);+ await new ChatCruxSummarizer(m).describeFile(CRUX_INPUT);+ const user = m.last?.messages.find((x) => x.role === "user")?.content ?? "";+ const rows = user.split("\n").filter((l) => l.startsWith("- "));+ assert.deepEqual(rows, [+ "- file | lines L1-L5 | id=Runtime/Core/Ctx.cs",+ "- variable | lines L3-L3 | public int Level { get; } | id=Runtime/Core/Ctx.cs#Level",+ ]);+});++test("ChatCruxSummarizer keeps an exact id and reports no miss", async () => {+ const s = new ChatCruxSummarizer(cruxReply(["Runtime/Core/Ctx.cs", "Runtime/Core/Ctx.cs#Level"]));+ const out = await s.describeFile(CRUX_INPUT);+ assert.deepEqual(out.map((r) => r.id), ["Runtime/Core/Ctx.cs", "Runtime/Core/Ctx.cs#Level"]);+ assert.equal(s.lastMiss, null);+});++test("ChatCruxSummarizer maps a whole echoed target row back to the requested id (#259)", async () => {+ const s = new ChatCruxSummarizer(+ cruxReply([+ // gpt-5.6-luna on 0.20.0: the old `id=` first row, echoed from the id onwards.+ "Runtime/Core/Ctx.cs | file | lines L1-L5",+ "Runtime/Core/Ctx.cs#Level | variable | lines L3-L3 | public int Level { get; }",+ ]),+ );+ const out = await s.describeFile(CRUX_INPUT);+ assert.deepEqual(out.map((r) => r.id), ["Runtime/Core/Ctx.cs", "Runtime/Core/Ctx.cs#Level"]);+ assert.equal(s.lastMiss, null);+});++test("ChatCruxSummarizer strips a leading id= and repairs an echo of the current layout", async () => {+ const s = new ChatCruxSummarizer(+ cruxReply([+ "id=Runtime/Core/Ctx.cs",+ "- variable | lines L3-L3 | public int Level { get; } | id=Runtime/Core/Ctx.cs#Level",+ ]),+ );+ const out = await s.describeFile(CRUX_INPUT);+ assert.deepEqual(out.map((r) => r.id), ["Runtime/Core/Ctx.cs", "Runtime/Core/Ctx.cs#Level"]);+ assert.equal(s.lastMiss, null);+});++test("an invented id is not repaired and is reported as id-mismatch", async () => {+ const invented = "Runtime/Core/Other.cs#Level | variable | lines L3-L3";+ const s = new ChatCruxSummarizer(cruxReply([invented, "id=Runtime/Core/Nope.cs"]));+ const out = await s.describeFile(CRUX_INPUT);+ assert.deepEqual(out.map((r) => r.id), [invented, "id=Runtime/Core/Nope.cs"]);+ assert.deepEqual(s.lastMiss, {+ kind: "id-mismatch",+ finishReason: "stop",+ returned: 2,+ firstId: invented,+ });+ assert.equal(+ formatCruxMiss("id-mismatch", "stop"),+ "model returned summaries but no id matched a requested target [id-mismatch, finish_reason=stop]",+ );+ assert.equal(formatCruxMissDetail(s.lastMiss), `first of 2 returned id(s): ${JSON.stringify(invented)}`);+});++test("resolveTargetId takes the longest requested id when several qualify", () => {+ const requested = ["a.ts#f", "a.ts#f | g"];+ assert.equal(resolveTargetId("a.ts#f | g | function | lines L1-L2", requested), "a.ts#f | g");+ assert.equal(resolveTargetId("a.ts#f | function | lines L1-L2", requested), "a.ts#f");+ assert.equal(resolveTargetId(" a.ts#f ", requested), "a.ts#f");+ assert.equal(resolveTargetId("a.ts#fg | function", requested), null);+});+test("structured ops degrade gracefully when the model returns no tool call", async () => {const empty = new FakeChatModel({ toolCalls: [] });const { err } = await withCapturedError(async () => {