Skip to content

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

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.ts
index 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.ts
index 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): st
return 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 collected
diff --git a/test/graph-enrich-quality.test.ts b/test/graph-enrich-quality.test.ts
index 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.ts
index 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 () => {