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
fix(context): charge --max-tokens against the text actually emitted (CL-06)
KageBinary42bb339f2846
diff --git a/ix-cli/src/cli/__tests__/context-investigation.test.ts b/ix-cli/src/cli/__tests__/context-investigation.test.tsindex 8fbf9c40..2b99e49f 100644--- a/ix-cli/src/cli/__tests__/context-investigation.test.ts+++ b/ix-cli/src/cli/__tests__/context-investigation.test.ts@@ -224,6 +224,21 @@ describe("ix context investigation state", () => {expect(loaded?.bundle.evidence).toEqual(bundle.evidence);});+ it("round-trips the format the budget was sized for, and loads a save without one", () => {+ const sized = bundleWith([makeClaim("renders to DOM", 0.9)]);+ sized.budgets = { ...sized.budgets, format: "llm" };+ saveInvestigation("sized-llm", sized);+ expect(loadInvestigation("sized-llm")?.bundle.budgets.format).toBe("llm");++ // A bundle saved before the field existed has none, and --diff sizes it as json.+ const legacy = bundleWith([makeClaim("renders to DOM", 0.9)]);+ delete (legacy.budgets as { format?: string }).format;+ saveInvestigation("sized-legacy", legacy);+ const loaded = loadInvestigation("sized-legacy");+ expect(loaded).toBeDefined();+ expect(loaded?.bundle.budgets.format).toBeUndefined();+ });+it("writes into an investigations subdirectory of IX_HOME, not its root", () => {// IX_HOME is the Ix home itself — it holds config.yaml, bin/, cli/ and// dotfiles like .version-check.json. Saved state belongs in a subdirectory@@ -491,7 +506,7 @@ describe("ix context investigation state", () => {saveInvestigation("widget-check", saved);const stored = loadInvestigation("widget-check")!;const fresh = bundleWith([makeClaim("renders to DOM", 0.9)]);- expect(fresh.budgets).toEqual({ maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000 });+ expect(fresh.budgets).toEqual({ maxEntities: 50, maxRelationships: 100, maxEvidence: 25, maxTokens: 1500, maxChars: 12000, format: "json" });const baselineDiff = diffInvestigations(stored, fresh);expect(baselineDiff.budgets.saved).toEqual({ maxEntities: 5, maxRelationships: 1, maxEvidence: 2, maxTokens: 1500, maxChars: 12000 });diff --git a/ix-cli/src/cli/__tests__/context-pick-validation.test.ts b/ix-cli/src/cli/__tests__/context-pick-validation.test.tsindex b7905786..099fe8f2 100644--- a/ix-cli/src/cli/__tests__/context-pick-validation.test.ts+++ b/ix-cli/src/cli/__tests__/context-pick-validation.test.ts@@ -116,7 +116,7 @@ describe("ix context --max-* validation", () => {for (const [flag, text, fallback, min, max] of [["--max-entities", "Maximum entities in the bundle", 50, 1, 500],["--max-relationships", "Maximum relationships in the bundle", 100, 1, 1000],- ["--max-evidence", "Maximum evidence items in the bundle", 25, 1, 200],+ ["--max-evidence", "Maximum evidence items in the bundle; --max-tokens normally binds first", 200, 1, 200],["--max-tokens", "Maximum tokens of evidence output", 3000, 500, 200000],] as const) {// One assertion per flag, so a failure names which one lost its defaultdiff --git a/ix-cli/src/cli/__tests__/context-token-budget.test.ts b/ix-cli/src/cli/__tests__/context-token-budget.test.tsindex 518c726c..0a85780f 100644--- a/ix-cli/src/cli/__tests__/context-token-budget.test.ts+++ b/ix-cli/src/cli/__tests__/context-token-budget.test.ts@@ -4,7 +4,7 @@ import { Command } from "commander";import { describe, expect, it } from "vitest";import {- BUNDLE_CHARS_PER_TOKEN,+ CHARS_PER_TOKEN,clampBudgets,detectContextModeConflict,registerContextCommand,@@ -14,14 +14,17 @@ describe("--max-tokens", () => {it("is what bounds a default bundle, not 12,000 characters", () => {const budgets = clampBudgets({});expect(budgets.maxTokens).toBe(3000);- expect(budgets.maxChars).toBe(Math.round(3000 * BUNDLE_CHARS_PER_TOKEN));+ expect(budgets.maxChars).toBe(8100);+ expect(clampBudgets({}, "llm").maxChars).toBe(10_500);+ expect(clampBudgets({}, "text").maxChars).toBe(10_500);// The old character default was nearly twice this.expect(budgets.maxChars).toBeLessThan(12_000);});it("moves the character budget with it", () => {- expect(clampBudgets({ maxTokens: 3000 }).maxChars).toBe(Math.round(3000 * BUNDLE_CHARS_PER_TOKEN));- expect(clampBudgets({ maxTokens: 500 }).maxChars).toBe(1070);+ expect(clampBudgets({ maxTokens: 3000 }, "json").maxChars).toBe(Math.round(3000 * CHARS_PER_TOKEN.json));+ expect(clampBudgets({ maxTokens: 500 }, "llm").maxChars).toBe(1750);+ expect(clampBudgets({ maxTokens: 500 }).maxChars).toBe(1350);});it("is clamped to its range before it is converted", () => {@@ -33,8 +36,9 @@ describe("--max-tokens", () => {});it("gives way to an explicit --max-chars", () => {- const budgets = clampBudgets({ maxChars: 40_000 });+ const budgets = clampBudgets({ maxChars: 40_000 }, "llm");expect(budgets.maxChars).toBe(40_000);+ expect(clampBudgets({ maxChars: 40_000 }, "json").maxChars).toBe(40_000);// The token field still reports what it would have been, so --diff can say// which budget the caller had in force.expect(budgets.maxTokens).toBe(3000);diff --git a/ix-cli/src/cli/__tests__/context-usefulness.test.ts b/ix-cli/src/cli/__tests__/context-usefulness.test.tsindex 55c16f8a..544f1d03 100644--- a/ix-cli/src/cli/__tests__/context-usefulness.test.ts+++ b/ix-cli/src/cli/__tests__/context-usefulness.test.ts@@ -138,7 +138,8 @@ function render(fixture: Fixture): { lines: string[]; bundle: ReturnType<typeof} as never,provenance: {},// The budgets a caller gets by default, not generous ones.- budgets: clampBudgets({}),+ budgets: clampBudgets({}, "llm"),+ format: "llm",isStale: () => false,});@@ -180,6 +181,14 @@ describe("ix context usefulness", () => {expect(bundle.evidence.length).toBeLessThanOrEqual(bundle.budgets.maxEvidence);});+ it("emits within 10% of maxChars when evidence was cut", () => {+ const { lines, bundle } = render(fixture);+ if (bundle.truncation.evidenceTruncated === 0) return;+ const out = lines.join("\n").length;+ expect(out).toBeLessThanOrEqual(bundle.budgets.maxChars);+ expect(out).toBeGreaterThanOrEqual(0.9 * bundle.budgets.maxChars);+ });+it("ends with a read the caller can run", () => {const { lines } = render(fixture);const next = lines.filter((l) => l.startsWith("next "));diff --git a/ix-cli/src/cli/__tests__/context.test.ts b/ix-cli/src/cli/__tests__/context.test.tsindex 4ef2ca22..d17fbb83 100644--- a/ix-cli/src/cli/__tests__/context.test.ts+++ b/ix-cli/src/cli/__tests__/context.test.ts@@ -1,6 +1,6 @@// Copyright 2026 Ix Infrastructure Inc.-import { describe, expect, it } from "vitest";+import { afterEach, describe, expect, it } from "vitest";import type {ConflictReport,@@ -13,7 +13,9 @@ import type {ScoredClaim,} from "../../client/types.js";import type { EntityFacts } from "../explain/facts.js";-import { buildBundle, sanitizeId } from "../commands/context.js";+import {+ buildBundle, bundleFormat, clampBudgets, renderBundle, sanitizeId, textEvidenceLines,+} from "../commands/context.js";function makeFacts(overrides: Partial<EntityFacts> = {}): EntityFacts {return {@@ -441,3 +443,126 @@ describe("ix context bundle", () => {expect(new Set(names).size).toBe(names.length);});});++describe("ix context budget is charged against the emitted text", () => {+ const manyMembers = () => {+ const members = Array.from({ length: 150 }, (_, i) => `member_function_number_${i}`);+ const facts = makeFacts({ members, memberCount: 150 });+ const nodes = Array.from({ length: 150 }, (_, i) => ({+ id: `n-${i}`, kind: "function", name: `callee_${i}`, attrs: {},+ provenance: { sourceUri: `src/file_${i}.ts` }, createdRev: 1,+ createdAt: "2026-01-01T00:00:00Z", updatedAt: "2026-01-01T00:00:00Z",+ })) as GraphNode[];+ const edges = Array.from({ length: 150 }, (_, i) => ({+ id: `e-${i}`, src: "entity-1", dst: `n-${i}`, predicate: "calls", attrs: {}, createdRev: 1,+ })) as GraphEdge[];+ return { ...input(), facts, context: makeContext({ nodes, edges }) };+ };++ const emitted = (bundle: ReturnType<typeof buildBundle>, format: string): string => {+ const lines: string[] = [];+ const orig = console.log;+ console.log = (...a: unknown[]) => void lines.push(a.map(String).join(" "));+ try {+ renderBundle(bundle, format);+ } finally {+ console.log = orig;+ }+ return lines.join("\n");+ };++ const prevCaller = process.env.IX_CALLER;+ afterEach(() => {+ if (prevCaller === undefined) delete process.env.IX_CALLER;+ else process.env.IX_CALLER = prevCaller;+ });++ for (const caller of [undefined, "mcp"]) {+ it(`emits within 10% of maxChars in llm when evidence was cut (IX_CALLER=${caller ?? "unset"})`, () => {+ if (caller) process.env.IX_CALLER = caller;+ else delete process.env.IX_CALLER;+ const budgets = clampBudgets({ maxTokens: 600 }, "llm");+ const bundle = buildBundle({ ...manyMembers(), budgets, format: "llm" });+ expect(bundle.truncation.evidenceTruncated).toBeGreaterThan(0);+ const out = emitted(bundle, "llm");+ expect(out.length).toBeLessThanOrEqual(budgets.maxChars);+ expect(out.length).toBeGreaterThanOrEqual(0.9 * budgets.maxChars);+ expect(bundle.budgets.format).toBe("llm");+ });+ }++ // Every budget in a sweep, so some settle within a few characters of+ // maxChars: the header's `truncated_chars` digits must be the ones measured,+ // not a placeholder that grows after the fit was checked.+ it("never emits past maxChars in llm once the truncated_chars header is final", () => {+ delete process.env.IX_CALLER;+ const base = clampBudgets({}, "llm");+ let cut = 0;+ for (let maxChars = 1500; maxChars <= 2500; maxChars += 1) {+ const budgets = { ...base, maxChars };+ const bundle = buildBundle({ ...manyMembers(), budgets, format: "llm" });+ if (bundle.truncation.evidenceTruncated > 0) cut += 1;+ expect(bundle.truncation.charactersTruncated).toBeGreaterThan(0);+ expect(emitted(bundle, "llm").length).toBeLessThanOrEqual(maxChars);+ }+ expect(cut).toBe(1001);+ });++ it("keeps every row when the whole bundle fits exactly (no reserved diagnostic)", () => {+ const big = clampBudgets({ maxChars: 100000 }, "llm");+ const full = buildBundle({ ...manyMembers(), budgets: big, format: "llm" });+ expect(full.truncation.evidenceTruncated).toBe(0);+ const exact = emitted(full, "llm").length;+ const tight = { ...big, maxChars: exact };+ const bundle = buildBundle({ ...manyMembers(), budgets: tight, format: "llm" });+ expect(bundle.evidence.length).toBe(full.evidence.length);+ });++ it("bounds json evidence by its serialization, within 10% when cut", () => {+ const budgets = clampBudgets({ maxTokens: 600 }, "json");+ const bundle = buildBundle({ ...manyMembers(), budgets, format: "json" });+ expect(bundle.truncation.evidenceTruncated).toBeGreaterThan(0);+ const kept = bundle.evidence.reduce((n, e) => n + JSON.stringify(e).length, 0);+ expect(kept).toBeLessThanOrEqual(budgets.maxChars);+ expect(kept).toBeGreaterThanOrEqual(0.9 * budgets.maxChars);+ });++ it("bounds text evidence by the lines it prints, leaving room for the header", () => {+ const budgets = clampBudgets({ maxTokens: 600 }, "text");+ const bundle = buildBundle({ ...manyMembers(), budgets, format: "text" });+ expect(bundle.truncation.evidenceTruncated).toBeGreaterThan(0);+ const kept = bundle.evidence.reduce(+ (n, e) => n + textEvidenceLines(e).reduce((m, l) => m + l.length + 1, 0), 0);+ expect(kept).toBeLessThanOrEqual(budgets.maxChars - 600);+ });++ it("keeps the target row when it alone is larger than the budget", () => {+ for (const format of ["llm", "json", "text"] as const) {+ const bundle = buildBundle({+ ...manyMembers(),+ budgets: { maxEntities: 50, maxRelationships: 100, maxEvidence: 200, maxTokens: 500, maxChars: 10 },+ format,+ });+ expect(bundle.evidence.length).toBe(1);+ expect(bundle.evidence[0]!.kind).toBe("target");+ }+ });++ it("reports charactersTruncated as full minus kept in the format's own unit", () => {+ const budgets = clampBudgets({ maxTokens: 600 }, "json");+ const cut = buildBundle({ ...manyMembers(), budgets, format: "json" });+ const wide = buildBundle({+ ...manyMembers(), format: "json", budgets: { ...budgets, maxChars: 1_000_000 },+ });+ const full = wide.evidence.reduce((n, e) => n + JSON.stringify(e).length, 0);+ const kept = cut.evidence.reduce((n, e) => n + JSON.stringify(e).length, 0);+ expect(cut.truncation.charactersTruncated).toBe(full - kept);+ });++ it("maps formats the way renderBundle does", () => {+ expect(bundleFormat("json")).toBe("json");+ expect(bundleFormat("llm")).toBe("llm");+ expect(bundleFormat("text")).toBe("text");+ expect(bundleFormat(undefined)).toBe("text");+ });+});diff --git a/ix-cli/src/cli/commands/context.ts b/ix-cli/src/cli/commands/context.tsindex 0caa1e32..47d75b7d 100644--- a/ix-cli/src/cli/commands/context.ts+++ b/ix-cli/src/cli/commands/context.ts@@ -84,7 +84,7 @@ const MAX_CONFLICTS = 10;const BUDGETS = [{ key: "maxEntities", flag: "--max-entities", label: "entities", help: "Maximum entities in the bundle", min: 1, max: 500, fallback: 50 },{ key: "maxRelationships", flag: "--max-relationships", label: "relationships", help: "Maximum relationships in the bundle", min: 1, max: 1000, fallback: 100 },- { key: "maxEvidence", flag: "--max-evidence", label: "evidence", help: "Maximum evidence items in the bundle", min: 1, max: 200, fallback: 25 },+ { key: "maxEvidence", flag: "--max-evidence", label: "evidence", help: "Maximum evidence items in the bundle; --max-tokens normally binds first", min: 1, max: 200, fallback: 200 },{ key: "maxTokens", flag: "--max-tokens", label: "tokens", help: "Maximum tokens of evidence output", min: 500, max: 200_000, fallback: 3_000 },{ key: "maxChars", flag: "--max-chars", label: "chars", help: "Maximum characters of evidence output", min: 1000, max: 1_000_000, fallback: 12_000 },] as const satisfies ReadonlyArray<{@@ -131,20 +131,29 @@ function budgetParser(key: keyof BudgetSnapshot): (value: string) => number {return (value: string) => parseBudgetOption(value, example);}+/** The text a bundle is printed as: `--format llm`, `--format json`, or the prose fallthrough. */+export type BundleFormat = "llm" | "json" | "text";++/** Maps a `--format` value the way `renderBundle` does: anything but json and llm is prose. */+export function bundleFormat(fmt: string | undefined): BundleFormat {+ return fmt === "json" ? "json" : fmt === "llm" ? "llm" : "text";+}+/**- * Characters per token in a real bundle.+ * Characters per token, by the format the bundle is printed in.*- * Measured across 41 recorded bundles whose prompts differed only by the- * bundle: 2.14, against the ~4 of ordinary English. A bundle is dense- * `key=value` and JSON with identifiers in it, and identifiers tokenize badly.+ * `--max-tokens` is charged against the text that is actually emitted, so the+ * ratio is per format. Measured with cl100k: llm 3.73 and json 2.69 on the+ * audit fixture; the constants sit just under, so a bundle comes in at or under+ * its budget. `text` measured 4.09 on a live `context.ts` bundle and shares+ * the llm value, which keeps it on the safe side.*- * Conservative on purpose, and it stays conservative as the bundle gets- * cleaner: pulling identifier-heavy rows out raises the real ratio, so an- * estimate pinned at 2.14 over-counts tokens and the bundle comes in under its- * budget rather than over it. Re-measure before lowering it, never raise it to- * make a bundle fit.+ * The 2.14 this replaced was measured across 41 recorded bundles (JSON plus+ * prompt) and is the value legacy saved bundles were sized at; their stored+ * `maxChars` is kept as it is. Re-measure before raising any of these, never+ * raise one to make a bundle fit.*/-export const BUNDLE_CHARS_PER_TOKEN = 2.14;+export const CHARS_PER_TOKEN: Record<BundleFormat, number> = { llm: 3.5, json: 2.7, text: 3.5 };/*** Apply the table's range and default to whatever the caller supplied, and@@ -157,7 +166,7 @@ export const BUNDLE_CHARS_PER_TOKEN = 2.14;* refused up front rather than silently ranked, because which one lost is not* visible in the output.*/-export function clampBudgets(opts: Partial<BudgetSnapshot>): BudgetSnapshot {+export function clampBudgets(opts: Partial<BudgetSnapshot>, format: BundleFormat = "json"): BudgetSnapshot {const out = {} as BudgetSnapshot;for (const b of BUDGETS) {const raw = opts[b.key];@@ -167,7 +176,7 @@ export function clampBudgets(opts: Partial<BudgetSnapshot>): BudgetSnapshot {const chars = budgetField("maxChars");out.maxChars = Math.min(chars.max,- Math.max(chars.min, Math.round(out.maxTokens * BUNDLE_CHARS_PER_TOKEN)),+ Math.max(chars.min, Math.round(out.maxTokens * CHARS_PER_TOKEN[format])),);}return out;@@ -302,7 +311,8 @@ interface ContextBundle {/** Present only for a degraded or empty graph: what is wrong and the fix. */graph?: Record<string, unknown>;evidence: EvidenceItem[];- budgets: BudgetSnapshot;+ /** `format` is the output the budget was sized for; absent on bundles saved before it existed (json sizing). */+ budgets: BudgetSnapshot & { format?: BundleFormat };truncation: {entitiesTruncated: number;relationshipsTruncated: number;@@ -393,6 +403,8 @@ export function registerContextCommand(program: Command): void {reportFailure("mode_conflict", conflict, opts.format);return;}+ // The output the evidence budget is charged against; --out writes JSON.+ const fmt = opts.out ? "json" : bundleFormat(opts.format);if (opts.resume) {renderSavedInvestigation(opts.resume, opts.format);return;@@ -440,7 +452,7 @@ export function registerContextCommand(program: Command): void {return;}if (opts.fromIssue) {- const bundle = await buildIssueBundle(opts.fromIssue, opts, clampBudgets(opts));+ const bundle = await buildIssueBundle(opts.fromIssue, opts, clampBudgets(opts, fmt), fmt);if (bundle) await emitBundle(bundle, opts);return;}@@ -465,7 +477,7 @@ export function registerContextCommand(program: Command): void {}, opts.format);if (!resolved) return;- const budgets = clampBudgets(opts);+ const budgets = clampBudgets(opts, fmt);const asOfRev = opts.asOfRev;const [facts, context, workspaceHealth] = await Promise.all([@@ -496,6 +508,7 @@ export function registerContextCommand(program: Command): void {asOfRev,depth: opts.depth,budgets,+ format: fmt,graphCompleted: hasCompletedSourceGraphBaseline(),graphHealth: bundleGraphHealth(workspaceHealth, resolved, facts),});@@ -568,7 +581,7 @@ async function emitBundle(bundle: ContextBundle, opts: ContextOptions): Promise<async function buildFreshBundle(target: string,opts: { kind?: string; path?: string; pick?: number; depth?: string; asOfRev?: number },- budgets: BudgetSnapshot,+ budgets: BudgetSnapshot & { format?: BundleFormat },format: string,): Promise<ContextBundle | undefined> {const client = createClient({ query: true });@@ -588,6 +601,8 @@ async function buildFreshBundle(return buildBundle({resolved, facts, context, provenance: facts.provenance, asOfRev, depth: opts.depth, budgets,+ // The saved bundle's own sizing format, not the diff's render format, so --diff compares like with like.+ format: budgets.format ?? "json",graphCompleted: hasCompletedSourceGraphBaseline(),graphHealth: bundleGraphHealth(workspaceHealth, resolved, facts),});@@ -1535,6 +1550,11 @@ interface BuildInput {asOfRev?: number;depth?: string;budgets: BudgetSnapshot;+ /**+ * The output the evidence budget is charged against. Defaults to json, the+ * legacy sizing, so injected fixtures and old saved bundles keep their size.+ */+ format?: BundleFormat;/*** Per-entity staleness probe. Injected so buildBundle stays a pure function* under test; production passes nothing and gets the real baseline-backed one.@@ -1672,6 +1692,7 @@ async function buildIssueBundle(arg: string,opts: ContextOptions,budgets: BudgetSnapshot,+ format: BundleFormat,): Promise<ContextBundle | undefined> {const text = await readIssueOrReport(arg, opts.format);if (text === undefined) return undefined;@@ -1720,6 +1741,7 @@ async function buildIssueBundle(asOfRev: opts.asOfRev,depth: opts.depth,budgets,+ format,graphCompleted: hasCompletedSourceGraphBaseline(),graphHealth: bundleGraphHealth(workspaceHealth, resolved, facts),issue: {@@ -1934,6 +1956,7 @@ function bundleGraphHealth(export function buildBundle(input: BuildInput): ContextBundle {const { resolved, facts, context, provenance, asOfRev, depth, budgets } = input;+ const format = input.format ?? "json";const stale = facts.stale;// Three states, not two. Without a completed source graph baseline the@@ -2121,7 +2144,7 @@ export function buildBundle(input: BuildInput): ContextBundle {freshness: { stale, classification },...(degraded ? { graph: graphHealthJson(health) } : {}),evidence: [],- budgets,+ budgets: { ...budgets, format },truncation: {entitiesTruncated: 0,relationshipsTruncated: 0,@@ -2176,24 +2199,81 @@ export function buildBundle(input: BuildInput): ContextBundle {// Evidence is ordered by relevance, so keep the highest-priority prefix and// drop the tail when either the count or the character budget is exceeded.- // maxChars bounds the serialized JSON size of the evidence list exactly as it- // is emitted in the bundle (each item's JSON.stringify length, in the item's- // deterministic key order), so the budget matches the actual representation- // rather than an estimate from metadata lengths.- const sizedEvidence = evidence.map((item) => ({ item, size: JSON.stringify(item).length }));+ // Each item is sized by the text its renderer prints (the llm `evidence`+ // line, the two prose lines, or the item's JSON), so `--max-tokens` is+ // charged for what is emitted rather than for a serialization nobody sees.+ // For llm the header, diagnostics and `next` lines are charged too; for json+ // the budget bounds the evidence list only (entities and relationships have+ // their own count budgets).+ const sizeOf = (item: EvidenceItem): number =>+ format === "llm" ? evidenceRecord(undefined)(item).length + 1+ : format === "text" ? textEvidenceLines(item).reduce((sum, line) => sum + line.length + 1, 0)+ : JSON.stringify(item).length;+ const sizedEvidence = evidence.map((item) => ({ item, size: sizeOf(item) }));+ // keptSize[n] = summed size of the first n items, so a cut at any count knows+ // its `charactersTruncated` (full minus kept, in the sizing unit of the+ // format) without a rescan.+ const keptSize = [0];+ for (const entry of sizedEvidence) keptSize.push(keptSize[keptSize.length - 1]! + entry.size);+ const fullChars = keptSize[sizedEvidence.length]!;+ // Every counter the llm header prints is set here, including+ // `truncated_chars`, so each measurement below sees the digits that will+ // actually be emitted for that cut.+ const applyCut = (count: number): void => {+ bundle.evidence = evidence.slice(0, count);+ bundle.truncation.evidenceTruncated = evidence.length - count;+ bundle.truncation.charactersTruncated = fullChars - keptSize[count]!;+ const cut = summariseCut(evidence.slice(count));+ if (cut.length > 0) bundle.truncation.cut = cut;+ else delete bundle.truncation.cut;+ };+ let overhead = 0;+ if (format === "llm") {+ applyCut(0);+ overhead = bundleLlmLines(bundle).join("\n").length;+ } else if (format === "text") {+ overhead = TEXT_HEADER_ESTIMATE;+ }+ const evidenceBudget = budgets.maxChars - overhead;let chars = 0;let kept = 0;for (const entry of sizedEvidence) {- if (kept >= budgets.maxEvidence || chars + entry.size > budgets.maxChars) break;+ // The first row is the target and always survives, however small the budget.+ if (kept >= budgets.maxEvidence || (kept > 0 && chars + entry.size > evidenceBudget)) break;chars += entry.size;kept += 1;}- 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);+ applyCut(kept);+ if (format === "llm") {+ // The header digits, the bundle_truncated diagnostic and the `next` lines+ // all depend on the cut, so settle it by measuring the real output.+ while (kept > 1 && bundleLlmLines(bundle).join("\n").length > budgets.maxChars) {+ kept -= 1;+ applyCut(kept);+ }+ // The overhead was measured with a truncation diagnostic reserved, which a+ // bundle that fits whole does not carry. Grow back while the real output+ // still fits.+ const limit = Math.min(sizedEvidence.length, budgets.maxEvidence);+ // A complete bundle drops the truncation diagnostic, so it can fit where+ // the nearly-complete ones do not: try the whole list before growing.+ if (kept < limit) {+ applyCut(limit);+ if (bundleLlmLines(bundle).join("\n").length <= budgets.maxChars) {+ kept = limit;+ } else {+ applyCut(kept);+ }+ }+ while (kept < limit) {+ applyCut(kept + 1);+ if (bundleLlmLines(bundle).join("\n").length > budgets.maxChars) {+ applyCut(kept);+ break;+ }+ kept += 1;+ }+ }// `conflicts[]` was the one list with no budget at all, and it is the one the// backend can hand back by the dozen: it reached 12,922 of 23,030 JSON bytes@@ -2457,20 +2537,14 @@ function issueEvidence(issue: IssueBundleInput): EvidenceItem[] {return items;}-export function renderBundle(bundle: ContextBundle, format: string): void {- if (format === "json") {- printJson(bundle);- return;- }- if (format === "llm") {- // Every line through `llmLine`, none through a template literal. This block- // built `target=${name}` and `evidence 30 relationship <title>` by- // interpolation: the first breaks on any name containing a space or an `=`,- // and the second is positional, unquoted, and breaks on every title, which- // is a sentence. `ix context --diff --format llm` emits the keyed form for- // the same record kinds, so a consumer routing on `evidence` from the same- // command was handed two grammars.- printLlmLines([+/**+ * The lines `--format llm` prints, in order. Pure, so `buildBundle` can measure+ * exactly what a budget will be charged for.+ */+export function bundleLlmLines(bundle: ContextBundle): string[] {+ // Every line through `llmLine`, none through a template literal: see the+ // history of this block. Absent sections are null and filtered out.+ const lines: Array<string | null> = [llmLine("context", {target: bundle.target.name,target_kind: bundle.target.kind,@@ -2518,7 +2592,33 @@ export function renderBundle(bundle: ContextBundle, format: string): void {...(forMcp()? nextToolCalls(bundle).map((step) => llmLine("next", { cmd: step.cmd, why: step.why })): nextReads(bundle).map((cmd) => llmLine("next", { cmd }))),- ]);+ ];+ return lines.filter((line): line is string => line !== null);+}++/** The two prose lines `--format text` prints for one evidence item. */+export function textEvidenceLines(item: EvidenceItem): string[] {+ const where = item.location ? `${formatLocation(item.location)} — ` : "";+ return [` [${item.score}] ${item.kind} — ${item.title}`, ` ${where}${item.reason}`];+}++/** Rough size of the prose header, charged before the evidence in `--format text`. */+const TEXT_HEADER_ESTIMATE = 600;++export function renderBundle(bundle: ContextBundle, format: string): void {+ if (format === "json") {+ printJson(bundle);+ return;+ }+ if (format === "llm") {+ // Every line through `llmLine`, none through a template literal. This block+ // built `target=${name}` and `evidence 30 relationship <title>` by+ // interpolation: the first breaks on any name containing a space or an `=`,+ // and the second is positional, unquoted, and breaks on every title, which+ // is a sentence. `ix context --diff --format llm` emits the keyed form for+ // the same record kinds, so a consumer routing on `evidence` from the same+ // command was handed two grammars.+ printLlmLines(bundleLlmLines(bundle));return;}@@ -2556,9 +2656,7 @@ export function renderBundle(bundle: ContextBundle, format: string): void {if (bundle.evidence.length > 0) {renderSection("Evidence (highest relevance first)");for (const item of bundle.evidence) {- console.log(` [${item.score}] ${item.kind} — ${item.title}`);- const where = item.location ? `${formatLocation(item.location)} — ` : "";- console.log(` ${where}${item.reason}`);+ for (const line of textEvidenceLines(item)) console.log(line);}}diff --git a/ix-cli/src/cli/context-bundle-schema.ts b/ix-cli/src/cli/context-bundle-schema.tsindex ba7d85d0..e9fda972 100644--- a/ix-cli/src/cli/context-bundle-schema.ts+++ b/ix-cli/src/cli/context-bundle-schema.ts@@ -161,6 +161,9 @@ function buildSchemas(z: typeof Zod.z) {// instead, which is a worse answer than reporting `tokens=not-given`.maxTokens: z.number().int().positive().optional(),maxChars: z.number().int().positive(),+ // Optional and declared: the output the budget was sized for. Undeclared+ // it would be stripped on save; required it would refuse older files.+ format: z.enum(["llm", "json", "text"]).optional(),}),truncation: z.object({// Optional for the same reason `budgets.maxTokens` is: a bundle saveddiff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.mdindex e2f27d31..2190db2e 100644--- a/skills/ix/references/flags.md+++ b/skills/ix/references/flags.md@@ -48,12 +48,18 @@ surfaces (#575).--limit 50` exits with an error rather than a shorter list. `--detailed`auto-paginates on its own; `--offset` or `--regions` turns that off, and`--limit` only sets the page size.-- **`ix context` budgets the evidence block in tokens, not characters.**- `--max-tokens` defaults to 3,000 and is converted at 2.14 characters per- token, measured across 41 recorded bundles. At 1,500 the evidence block held- about ten items, and for a file target those were its own members: ix-bench- agents were shown 0.59 of the expected files ix had found, against all of- them at 3,000, for about 320 more tokens. `--max-chars` is still there for+- **`ix context` budgets the text it emits, in tokens.** `--max-tokens`+ defaults to 3,000 and is converted to characters per output format: 3.5 per+ token for `--format llm` and text, 2.7 for `--format json` (measured with+ cl100k; the old flat 2.14 was measured on recorded bundles and is what saved+ investigations from before this were sized at). For `llm` the budget covers+ the whole output: header, diagnostics, evidence rows and `next` lines. For+ `json` it bounds the evidence list only; entities and relationships keep+ their own `--max-entities` and `--max-relationships` counts. `--max-evidence`+ defaults to 200 so the token budget normally binds first. A saved+ investigation records the format its budget was sized for, and `--diff`+ rebuilds with it. The ix-bench result that all expected files appear at 3,000+ tokens was measured under the old sizing. `--max-chars` is still there fora caller who needs exact bytes and overrides it; passing both is refusedrather than silently ranked, because the output does not say which one won.- **`ix mcp` advertises five tools by default**, not twenty-six:@@ -244,7 +250,7 @@ Build a bounded, deterministic context bundle for a symbol, file, or entity (or| `--as-of-rev` | `<n>` | — | Historical context as of a graph revision || `--max-entities` | `<n>` | — | Maximum entities in the bundle (default: 50, clamped to 1-500) || `--max-relationships` | `<n>` | — | Maximum relationships in the bundle (default: 100, clamped to 1-1000) |-| `--max-evidence` | `<n>` | — | Maximum evidence items in the bundle (default: 25, clamped to 1-200) |+| `--max-evidence` | `<n>` | — | Maximum evidence items in the bundle; `--max-tokens` normally binds first (default: 200, clamped to 1-200) || `--max-tokens` | `<n>` | `3000` | Maximum tokens of evidence output (clamped to 500-200000) || `--max-chars` | `<n>` | — | Maximum characters of evidence output; overrides `--max-tokens` (clamped to 1000-1000000) || `--format` | `text\|json\|llm` | `text` | Output format — see [output-formats.md](output-formats.md) |