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
/**
* How the concept pass cuts its synthesis batches, and what each one is cached under.
*
* Every batch is one LLM call, and its result is cached under a key derived from the
* files the call saw. So a boundary that moves is a re-synthesis — a metered call the
* user pays for again — which makes the cut rule, not the call itself, the thing that
* decides what a `--deep` build costs after an edit.
*
* The cut is a function of the file PATHS: a batch ends at the first file whose own
* path hash matches a mask, never at a size. Cut by running size, one summary growing
* by a sentence moves every later boundary, every later batch lands on a different set
* of files, and so every later key changes and the next build re-synthesizes most of
* the graph. Sizes are consulted in exactly two places, neither of which is a
* boundary: the stride (how many files to expect per batch) and a batch that
* overshoots the budget anyway, which is cut inside itself.
*/
import { contentHash } from "../util/id.js";
import type { FileSummary } from "../ai/synthesize.js";
/** Char budget of summary text per synthesis call (keeps each call in-context). */
export const BATCH_CHAR_BUDGET = 48_000;
/**
* Smallest share of the stride a batch may be cut at: a mask hit sooner than this is
* ignored, so a lucky pair of adjacent paths cannot turn a repo into one call per two
* files. An eighth keeps a stray hit to one small batch in a long tail of them,
* without moving a well-behaved boundary at all.
*/
const BATCH_MIN_SHARE = 1 / 8;
/** One synthesis call: the batch of summaries it sees, and the key it is cached under. */
export interface SynthesisBatch {
files: FileSummary[];
/** Stable key for this batch: its files and their content hashes. */
key: string;
}
/**
* The batches phase 2 calls, in the order the merge consumes them. `summaries` is
* expected path-sorted, which is what makes the plan reproducible.
*
* Exported together with their cache keys because those keys are the phase's whole
* cost model: a boundary that moves is a re-synthesis. How these keys survive an edit
* is what the batching tests pin down.
*/
export function planSynthesis(summaries: FileSummary[], hashByPath: ReadonlyMap<string, string>): SynthesisBatch[] {
return batchSummaries(summaries).map((files) => ({ files, key: batchKey(files, hashByPath) }));
}
/**
* Cut the per-file summaries into batches, each under `budget` unless it is a single
* file too big for one.
*
* A batch ENDS at the first file whose own path hash matches a mask, past a small
* floor (see {@link BATCH_MIN_SHARE}) — so the end of a batch is decided by the files
* inside it and by nothing else, and an edit to one file cannot move a boundary it is
* not part of.
*/
export function batchSummaries(files: FileSummary[], budget: number = BATCH_CHAR_BUDGET): FileSummary[][] {
if (files.length === 0) return [];
const stride = filesPerBatch(files, budget);
const minFiles = Math.max(1, Math.round(stride * BATCH_MIN_SHARE));
const batches: FileSummary[][] = [];
let cur: FileSummary[] = [];
let size = 0;
for (const f of files) {
cur.push(f);
size += summaryChars(f);
if (cur.length >= minFiles && isBoundary(f.path, stride)) {
batches.push(...withinBudget(cur, size, budget));
cur = [];
size = 0;
}
}
if (cur.length > 0) batches.push(...withinBudget(cur, size, budget));
return batches;
}
/** Chars a file costs its batch: its label, its summary, and the blank line the
* synthesizer's prompt puts between entries. */
function summaryChars(f: FileSummary): number {
return f.path.length + f.summary.length + 8;
}
/**
* Files to aim for per batch: as many as fit in roughly one budget's worth of summary
* text, rounded DOWN to a power of two.
*
* The mean is the one statistic that can size a batch across repos whose summaries
* differ in length by an order of magnitude. The power of two is what makes it safe
* to derive from a number that moves: editing one summary of n shifts the mean by
* ~1/n, and the ladder is wide enough that a shift that small cannot re-stride —
* while re-striding is the one change that does move every boundary, so it should
* take a real change in the repo to happen.
*/
function filesPerBatch(files: FileSummary[], budget: number): number {
const total = files.reduce((n, f) => n + summaryChars(f), 0);
const mean = Math.max(1, Math.round(total / files.length));
return 2 ** Math.floor(Math.log2(Math.max(1, Math.floor(budget / mean))));
}
/** Does a batch end here? One path in `stride` does, by its own hash. */
function isBoundary(path: string, stride: number): boolean {
if (stride <= 1) return true;
return parseInt(contentHash(path).slice(-8), 16) % stride === 0;
}
/** A batch that outgrew the budget on its own is cut by size, greedily. Overshooting
* takes a longer gap between two mask hits than the stride asks for, so it is the
* tail rather than the rule — and it is cut inside that one batch, which is why a
* split is a local edit and not a re-plan. A single file over the budget is left
* whole: the synthesizer truncates its input either way, and half a file is not a
* batch. */
function withinBudget(batch: FileSummary[], size: number, budget: number): FileSummary[][] {
return size <= budget || batch.length < 2 ? [batch] : batchBySize(batch, budget);
}
/** Greedily pack file summaries into batches under a char budget (≥1 file each). */
function batchBySize(files: FileSummary[], budget: number): FileSummary[][] {
const batches: FileSummary[][] = [];
let cur: FileSummary[] = [];
let size = 0;
for (const f of files) {
const len = summaryChars(f);
if (cur.length > 0 && size + len > budget) {
batches.push(cur);
cur = [];
size = 0;
}
cur.push(f);
size += len;
}
if (cur.length > 0) batches.push(cur);
return batches;
}
/** Stable key for a batch: its files and their content hashes. */
function batchKey(batch: FileSummary[], hashByPath: ReadonlyMap<string, string>): string {
return contentHash(
batch
.map((f) => `${f.path}:${hashByPath.get(f.path) ?? ""}`)
.sort()
.join("\n"),
);
}