Understand any codebase instantly. System intelligence for codebases, built for humans and AI.
TypeScript aiai-memoryclaude-codeclicode-analysiscode-mappingcode-memorycodebase-understandingcodexdeveloper-toolsllmopenclawpersistent-memoryprogram-analysissoftware-architecturesystem-intelligencesystem-mapping
feat(context): say what the budget cut, and the cheapest way to get it back
KageBinary7ca29b073bd0
diff --git a/ix-cli/src/cli/__tests__/context-truncation-hint.test.ts b/ix-cli/src/cli/__tests__/context-truncation-hint.test.tsnew file mode 100644index 00000000..2584e91b--- /dev/null+++ b/ix-cli/src/cli/__tests__/context-truncation-hint.test.ts@@ -0,0 +1,76 @@+// Copyright 2026 Ix Infrastructure Inc.++import { describe, expect, it } from "vitest";++import { truncationAdvice } from "../commands/context.js";++function bundle(+ target: { name: string; kind: string },+ cut: Array<{ what: string; count: number }>,+): never {+ return {+ target: { id: "t", resolutionMode: "exact", ...target },+ truncation: {+ entitiesTruncated: 0,+ relationshipsTruncated: 0,+ evidenceTruncated: cut.reduce((n, c) => n + c.count, 0),+ charactersTruncated: 0,+ cut,+ },+ } as never;+}++describe("truncationAdvice", () => {+ it("says nothing when nothing was cut", () => {+ expect(truncationAdvice(bundle({ name: "x", kind: "function" }, []))).toBeUndefined();+ });++ it("names what went, largest first, and pluralises on the count", () => {+ const advice = truncationAdvice(+ bundle({ name: "format.ts", kind: "file" }, [+ { what: "member", count: 36 },+ { what: "import", count: 12 },+ { what: "claim", count: 1 },+ ]),+ );+ expect(advice).toContain("cut: 36 members, 12 imports, 1 claim");+ });++ it("names at most three categories, so the hint stays one line", () => {+ const advice = truncationAdvice(+ bundle({ name: "x", kind: "function" }, [+ { what: "member", count: 4 },+ { what: "import", count: 3 },+ { what: "caller", count: 2 },+ { what: "claim", count: 1 },+ ]),+ );+ expect(advice).not.toContain("claim");+ });++ it("sends a container that lost its members to one of them, not to a bigger budget", () => {+ const advice = truncationAdvice(bundle({ name: "format.ts", kind: "file" }, [{ what: "member", count: 36 }]))!;+ expect(advice).toContain("run ix context on one of them");+ expect(advice).toContain("raise --max-tokens");+ });++ it("sends a symbol to the bounded command that answers the same question", () => {+ const cases: Array<[string, string]> = [+ ["caller", "ix callers verify"],+ ["dependent", "ix impact verify"],+ ["import", "ix imports verify"],+ ["call", "ix callees verify"],+ ["relationship", "ix depends verify"],+ ["claim", "ix conflicts verify"],+ ];+ for (const [what, expected] of cases) {+ const advice = truncationAdvice(bundle({ name: "verify", kind: "function" }, [{ what, count: 9 }]))!;+ expect(advice, what).toContain(expected);+ }+ });++ it("falls back to the one lever that works for anything", () => {+ const advice = truncationAdvice(bundle({ name: "x", kind: "function" }, [{ what: "provenance", count: 1 }]))!;+ expect(advice).toBe("cut: 1 provenance — raise --max-tokens");+ });+});diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex ef284ee0..e5576f3a 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -258,6 +258,15 @@ interface ContextBundle {relationshipsTruncated: number;evidenceTruncated: number;charactersTruncated: number;+ /**+ * What the budget dropped, by category, largest first.+ *+ * The counts above say how much went; this says what it was. "Rerun with+ * larger --max-* budgets" was the same sentence for a file that lost 36 of+ * its own members and for a symbol that lost two claims, and it named the+ * one lever that costs the caller the most to pull.+ */+ cut?: Array<{ what: string; count: number }>;};metadata: {asOfRev?: number;@@ -1639,6 +1648,8 @@ export function buildBundle(input: BuildInput): ContextBundle {}bundle.evidence = evidence.slice(0, kept);bundle.truncation.evidenceTruncated = evidence.length - kept;+ const dropped = summariseCut(evidence.slice(kept));+ if (dropped.length > 0) bundle.truncation.cut = dropped;const fullChars = sizedEvidence.reduce((sum, entry) => sum + entry.size, 0);bundle.truncation.charactersTruncated = Math.max(0, fullChars - chars);@@ -1840,6 +1851,13 @@ export function renderBundle(bundle: ContextBundle, format: string): void {truncated_evidence: bundle.truncation.evidenceTruncated,truncated_chars: bundle.truncation.charactersTruncated,}),+ // What the budget dropped, and the cheapest command that gets it back.+ // The header's `truncated_*` counters say how much went; without this the+ // caller's only move is a bigger budget for the same query, which is the+ // most expensive one available.+ truncationAdvice(bundle)+ ? llmLine("diagnostic", { code: "bundle_truncated", message: truncationAdvice(bundle) })+ : null,// Evidence only, as before. The entity, relationship and claim lists are// deliberately still counts here: `--format llm` is the token-minimal// surface, the ranked evidence is what it exists to deliver, and@@ -1874,13 +1892,96 @@ export function renderBundle(bundle: ContextBundle, format: string): void {const trunc = bundle.truncation;if (trunc.entitiesTruncated + trunc.relationshipsTruncated + trunc.evidenceTruncated > 0) {+ const advice = truncationAdvice(bundle);renderNote(- `Truncated: ${trunc.entitiesTruncated} entities, ${trunc.relationshipsTruncated} relationships, ${trunc.evidenceTruncated} evidence items. Rerun with larger --max-* budgets for more.`,+ `Truncated: ${trunc.entitiesTruncated} entities, ${trunc.relationshipsTruncated} relationships, ${trunc.evidenceTruncated} evidence items.`+ + (advice ? ` ${advice}` : " Raise --max-tokens for more."),);}console.log();}+/**+ * Evidence sources, as the word a hint can put a number in front of.+ *+ * Keyed on `source` rather than `kind`: `kind` is `structural` for members,+ * imports, calls, callers and dependents alike, and "cut: 48 structural" is the+ * uninformative sentence this exists to replace.+ */+const CUT_LABELS: Record<string, string> = {+ "facts.container": "container",+ "facts.members": "member",+ "facts.imports": "import",+ "facts.callees": "call",+ "facts.neighbours": "neighbouring definition",+ "facts.callers": "caller",+ "facts.dependents": "dependent",+ "context.claims": "claim",+ "context.decisions": "decision",+ "context.conflicts": "conflict",+ "context.intents": "intent",+ "context.edges": "relationship",+};++/** Group the evidence a budget dropped by category, largest first. */+function summariseCut(dropped: EvidenceItem[]): Array<{ what: string; count: number }> {+ const counts = new Map<string, number>();+ for (const item of dropped) {+ const what = CUT_LABELS[item.source] ?? item.kind;+ counts.set(what, (counts.get(what) ?? 0) + 1);+ }+ return [...counts.entries()]+ .map(([what, count]) => ({ what, count }))+ .sort((a, b) => b.count - a.count || a.what.localeCompare(b.what));+}++/**+ * The cheapest command that gets back what the budget dropped.+ *+ * Target-specific because the answer is: a file that lost its own members wants+ * one of those members as a target, not a bigger budget for the file; a symbol+ * that lost callers wants `ix callers`, which is bounded and ranked and costs a+ * fraction of a bundle. `--max-tokens` is named last, as the lever that works+ * for anything and pays for everything.+ */+function cutLever(bundle: ContextBundle, top: { what: string }): string {+ const name = bundle.target.name;+ const container = ["file", "module", "class", "object", "trait", "interface"]+ .includes(bundle.target.kind.toLowerCase());+ switch (top.what) {+ case "member":+ return container+ ? `run ix context on one of them, or raise --max-tokens`+ : `ix contains ${name}, or raise --max-tokens`;+ case "caller":+ return `ix callers ${name}, or raise --max-tokens`;+ case "dependent":+ return `ix impact ${name}, or raise --max-tokens`;+ case "import":+ return `ix imports ${name}, or raise --max-tokens`;+ case "call":+ return `ix callees ${name}, or raise --max-tokens`;+ case "relationship":+ return `ix depends ${name}, or raise --max-tokens`;+ case "claim":+ case "conflict":+ return `ix conflicts ${name}, or raise --max-tokens`;+ default:+ return `raise --max-tokens`;+ }+}++/** One sentence naming what was cut and the cheapest way to get it back. */+export function truncationAdvice(bundle: ContextBundle): string | undefined {+ const cut = bundle.truncation.cut ?? [];+ if (cut.length === 0) return undefined;+ const named = cut+ .slice(0, 3)+ .map((c) => `${c.count} ${c.what}${c.count === 1 ? "" : "s"}`)+ .join(", ");+ return `cut: ${named} — ${cutLever(bundle, cut[0])}`;+}+/** Members placed ahead of the backend's context nodes; the evidence shows as many. */const LEADING_MEMBERS = 10;diff --git a/ix-cli/src/cli/context-bundle-schema.ts b/ix-cli/src/cli/context-bundle-schema.tsindex 42394363..de3aecf1 100644--- a/ix-cli/src/cli/context-bundle-schema.ts+++ b/ix-cli/src/cli/context-bundle-schema.ts@@ -116,6 +116,10 @@ export const contextBundleSchema = z.object({maxChars: z.number().int().positive(),}),truncation: z.object({+ // Optional for the same reason `budgets.maxTokens` is: a bundle saved+ // before this field existed carries the counters and nothing else, and an+ // undeclared key would be stripped from every new one on its way to disk.+ cut: z.array(z.object({ what: z.string(), count: z.number().int().positive() })).optional(),entitiesTruncated: z.number().int().nonnegative(),relationshipsTruncated: z.number().int().nonnegative(),evidenceTruncated: z.number().int().nonnegative(),