Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

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.ts
index 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.ts
index 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 default
diff --git a/ix-cli/src/cli/__tests__/context-token-budget.test.ts b/ix-cli/src/cli/__tests__/context-token-budget.test.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 saved
diff --git a/skills/ix/references/flags.md b/skills/ix/references/flags.md
index 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 for
a caller who needs exact bytes and overrides it; passing both is refused
rather 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) |