rovecode 0.4.0-beta.3 → 0.4.0

package/src/core/config.ts

@@ -0,0 +1,289 @@
+/**
+ * Project context inheritance (port #8): auto-import instruction files from
+ * other coding-agent "harnesses" (Claude, Gemini, Cursor, Copilot, plain
+ * AGENTS.md) so rovecode projects don't need to duplicate repo conventions.
+ *
+ * Pattern + precedence order modeled on oh-my-pi's context-file discovery
+ * (research/source_snapshots/can1357-oh-my-pi):
+ *   - docs/context-files.md, "Other supported context conventions" and
+ *     "Load order and shadowing" tables — the provider-priority idea
+ *     (higher priority wins at a shared scope) and the per-tool path
+ *     conventions: AGENTS.md, CLAUDE.md / .claude/CLAUDE.md, GEMINI.md,
+ *     .cursor/rules/*.mdc + legacy .cursorrules, .github/copilot-instructions.md.
+ *   - packages/coding-agent/src/discovery/builtin.ts `getAncestorDirs` — the
+ *     cwd-upward ancestor walk with an optional inclusive stop directory.
+ *   - packages/coding-agent/src/discovery/cursor.ts — `.cursor/rules/*.mdc`
+ *     carries MDC frontmatter that must be separated from the rule body.
+ *
+ * Discovery + precedence (rovecode's documented spec):
+ *   - Ancestor walk: cwd UPWARD via dirname until parent === current (the
+ *     filesystem root). The walk additionally stops — INCLUSIVELY — at the
+ *     first directory containing `.git` (file or directory; worktrees use a
+ *     file), so a repository never inherits context from outside itself.
+ *     `opts.stopAt` bounds the walk at an explicit dir (also inclusive).
+ *   - Precedence: NEARER directories first (nearest wins); within one
+ *     directory, family order rovecode > agents > claude > gemini > cursor >
+ *     copilot (the harvest list in `buildCandidates`). Earlier position wins
+ *     dedupe and total-cap priority.
+ *   - Shadowing (dedupe by depth): the same relative path (e.g. `AGENTS.md`)
+ *     found in a nearer directory completely shadows the farther one — the
+ *     farther file is never read and never listed.
+ *   - Blank files (empty or whitespace-only, after MDC frontmatter stripping)
+ *     are skipped entirely: no section, no dedupe registration, no shadowing.
+ *   - Byte-identical content across surviving candidates is included once;
+ *     the earlier (higher-precedence) occurrence wins and later duplicates
+ *     never reach `sources` — unlike total-cap drops, which keep a stub.
+ *
+ * Budgets (rovecode-specific; OMP has no cap on context-file loading):
+ *   - `maxPerFileChars` caps each file's content. Truncation is fence-safe:
+ *     cut at the last newline inside the window and close an odd ``` fence
+ *     count so the following sections aren't swallowed by an open code block.
+ *   - `maxTotalChars` budgets the FULL rendered section string — the
+ *     `## From <path>` header included, so `text.length` never exceeds it.
+ *   - `maxFiles` bounds how many files are included; further existing
+ *     candidate files are counted in `skippedFiles` but never read.
+ *
+ * Freshness: callers snapshot the result once per runtime (cli/runtime.ts)
+ * so the system prompt stays byte-stable for prompt caching (port #5).
+ * Mid-session edits to config files are intentionally not picked up —
+ * restart rovecode (a new runtime) to refresh.
+ *
+ * Remaining deliberate deviations from OMP: no provider-priority shadowing
+ * table (content dedupe + path shadowing instead); `.cursor/rules/*.mdc`
+ * harvested unconditionally as plain text (frontmatter stripped, never
+ * parsed/acted on) and restricted to `*.mdc`; the character/file budgets are
+ * rovecode's own.
+ */
+
+import { readFileSync, readdirSync, existsSync } from "node:fs";
+import { join, dirname, resolve } from "node:path";
+
+export interface ContextSource {
+  /** Display path relative to cwd, "/"-separated with one "../" segment per
+   *  ancestor level — used verbatim in the rendered "## From <path>" header. */
+  path: string;
+  family: "rovecode" | "agents" | "claude" | "gemini" | "cursor" | "copilot";
+  chars: number;
+  truncated: boolean;
+}
+
+export interface ProjectContext {
+  text: string;
+  sources: ContextSource[];
+  /** Existing candidate files that were NOT read because the `maxFiles`
+   *  bound was already reached (surfaced in /status, never silent). */
+  skippedFiles: number;
+}
+
+export interface LoadOptions {
+  /** Per-file cap in characters. Default 8000. */
+  maxPerFileChars?: number;
+  /** Total cap on the rendered text (headers included). Default 24000. */
+  maxTotalChars?: number;
+  /** Max files included across the walk. Default 24. */
+  maxFiles?: number;
+  /** Inclusive upper bound for the ancestor walk (tests/embedders). */
+  stopAt?: string;
+}
+
+const DEFAULT_MAX_PER_FILE_CHARS = 8000;
+const DEFAULT_MAX_TOTAL_CHARS = 24000;
+const DEFAULT_MAX_FILES = 24;
+const TRUNCATION_MARKER = "…[truncated]";
+
+type Family = ContextSource["family"];
+
+interface Candidate {
+  /** Path relative to its directory, "/"-separated regardless of host OS. */
+  relPath: string;
+  family: Family;
+  /** Strip a leading MDC frontmatter block before treating this as content. */
+  mdc: boolean;
+}
+
+/** Harvest list for ONE directory, in family precedence order (first =
+ *  highest): rovecode > agents > claude > gemini > cursor > copilot. */
+function buildCandidates(dir: string): Candidate[] {
+  const candidates: Candidate[] = [
+    { relPath: ".rovecode/ROVECODE.md", family: "rovecode", mdc: false },
+    { relPath: "ROVECODE.md", family: "rovecode", mdc: false },
+    { relPath: "AGENTS.md", family: "agents", mdc: false },
+    { relPath: "CLAUDE.md", family: "claude", mdc: false },
+    { relPath: ".claude/CLAUDE.md", family: "claude", mdc: false },
+    { relPath: "GEMINI.md", family: "gemini", mdc: false },
+    { relPath: ".cursorrules", family: "cursor", mdc: false },
+  ];
+  for (const name of listCursorRuleFiles(dir)) {
+    candidates.push({ relPath: `.cursor/rules/${name}`, family: "cursor", mdc: true });
+  }
+  candidates.push({ relPath: ".github/copilot-instructions.md", family: "copilot", mdc: false });
+  return candidates;
+}
+
+/** cwd upward: dirname until parent === current (filesystem root), stopping
+ *  inclusively at `stopAt` or at the first dir containing `.git` (file or
+ *  directory — git worktrees use a file). OMP `getAncestorDirs` pattern. */
+function ancestorDirs(cwd: string, stopAt?: string): string[] {
+  const dirs: string[] = [];
+  const stop = stopAt === undefined ? null : resolve(stopAt);
+  let current = resolve(cwd);
+  for (;;) {
+    dirs.push(current);
+    if (stop !== null && current === stop) break;
+    if (hasGitMarker(current)) break; // repo root — inclusive, never above
+    const parent = dirname(current);
+    if (parent === current) break;    // filesystem root
+    current = parent;
+  }
+  return dirs;
+}
+
+/** `.git` presence, or false on any fs error (permissions, bad path, …). */
+function hasGitMarker(dir: string): boolean {
+  try {
+    return existsSync(join(dir, ".git"));
+  } catch {
+    return false;
+  }
+}
+
+/** `.cursor/rules/*.mdc`, sorted by filename. A missing/unreadable directory
+ *  yields no entries — silent skip, never a throw. */
+function listCursorRuleFiles(dir: string): string[] {
+  try {
+    const entries = readdirSync(join(dir, ".cursor", "rules"), { withFileTypes: true });
+    return entries
+      .filter((e) => e.isFile() && e.name.endsWith(".mdc"))
+      .map((e) => e.name)
+      .sort();
+  } catch {
+    return [];
+  }
+}
+
+/** Read a file's content, or null on any failure (missing, unreadable, is a
+ *  directory, …) — every failure mode is a silent skip, never a throw. */
+function tryReadFile(absPath: string): string | null {
+  try {
+    return readFileSync(absPath, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/** existsSync that can never throw (used only for `skippedFiles` counting). */
+function fileExists(absPath: string): boolean {
+  try {
+    return existsSync(absPath);
+  } catch {
+    return false;
+  }
+}
+
+/** Strip a leading `---\n...\n---` MDC frontmatter block, if present. */
+function stripMdcFrontmatter(content: string): string {
+  const lines = content.split("\n");
+  if ((lines[0] ?? "").trim() !== "---") return content;
+  let endIdx = -1;
+  for (let i = 1; i < lines.length; i++) {
+    if ((lines[i] ?? "").trim() === "---") {
+      endIdx = i;
+      break;
+    }
+  }
+  if (endIdx === -1) return content;
+  return lines.slice(endIdx + 1).join("\n").replace(/^\n+/, "");
+}
+
+/** Fence-safe truncation: cut at the last newline inside the window (whole
+ *  lines only; hard cut when the window has no interior newline), close an
+ *  odd ``` fence count so following sections aren't swallowed by an open
+ *  code block, then append the marker. */
+function truncateSafely(full: string, maxChars: number): string {
+  const window = full.slice(0, maxChars);
+  const nl = window.lastIndexOf("\n");
+  const cut = nl > 0 ? window.slice(0, nl) : window;
+  const fences = cut.split("\n").filter((l) => l.trimStart().startsWith("```")).length;
+  return fences % 2 === 1 ? `${cut}${TRUNCATION_MARKER}\n\`\`\`` : cut + TRUNCATION_MARKER;
+}
+
+interface KeptFile {
+  /** cwd-relative display path: "../" per ancestor level + relPath. */
+  displayPath: string;
+  family: Family;
+  /** Content after per-file truncation (includes the marker when truncated). */
+  content: string;
+  truncated: boolean;
+}
+
+/**
+ * Load and merge instruction files from every supported harness convention
+ * found in `cwd` and its ancestors (see module doc for the walk, precedence,
+ * shadowing, and budget rules). Deterministic: identical tree contents always
+ * produce the same `text` and `sources`, in the same order.
+ */
+export function loadProjectContext(cwd: string, opts?: LoadOptions): ProjectContext {
+  const maxPerFileChars = opts?.maxPerFileChars ?? DEFAULT_MAX_PER_FILE_CHARS;
+  const maxTotalChars = opts?.maxTotalChars ?? DEFAULT_MAX_TOTAL_CHARS;
+  const maxFiles = opts?.maxFiles ?? DEFAULT_MAX_FILES;
+
+  const seenContent = new Set<string>();
+  const shadowed = new Set<string>();   // relPaths claimed by a nearer non-blank file
+  const kept: KeptFile[] = [];
+  let skippedFiles = 0;
+
+  const dirs = ancestorDirs(cwd, opts?.stopAt);
+  for (let depth = 0; depth < dirs.length; depth++) {
+    const dir = dirs[depth]!;
+    for (const candidate of buildCandidates(dir)) {
+      if (shadowed.has(candidate.relPath)) continue;   // nearest wins (dedupe by depth)
+      const absPath = join(dir, candidate.relPath);
+      if (kept.length >= maxFiles) {
+        // file-count bound (HIGH-3): count existing candidates, never read them
+        if (fileExists(absPath)) skippedFiles++;
+        continue;
+      }
+      const raw = tryReadFile(absPath);
+      if (raw === null) continue; // missing or unreadable — skip silently
+
+      const full = candidate.mdc ? stripMdcFrontmatter(raw) : raw;
+      if (full.trim() === "") continue; // blank: no section/dedupe/shadow (LOW-6)
+      shadowed.add(candidate.relPath);
+
+      if (seenContent.has(full)) continue; // byte-identical dupe: earlier one won
+      seenContent.add(full);
+
+      let content = full;
+      let truncated = false;
+      if (full.length > maxPerFileChars) {
+        content = truncateSafely(full, maxPerFileChars);
+        truncated = true;
+      }
+      kept.push({
+        displayPath: "../".repeat(depth) + candidate.relPath,
+        family: candidate.family, content, truncated,
+      });
+    }
+  }
+
+  // Total cap enforced in precedence order over the FULL section string —
+  // header included, so `text.length <= maxTotalChars` always holds. A file
+  // that would exceed the budget is dropped from `text` but stays listed in
+  // `sources` as a chars:0/truncated:true stub so callers can see what was
+  // cut, and why the surviving text is short.
+  const sources: ContextSource[] = [];
+  const sections: string[] = [];
+  let total = 0;
+  for (const file of kept) {
+    const section = `\n\n## From ${file.displayPath}\n${file.content}`;
+    if (total + section.length <= maxTotalChars) {
+      sources.push({ path: file.displayPath, family: file.family, chars: file.content.length, truncated: file.truncated });
+      sections.push(section);
+      total += section.length;
+    } else {
+      sources.push({ path: file.displayPath, family: file.family, chars: 0, truncated: true });
+    }
+  }
+
+  return { text: sections.join(""), sources, skippedFiles };
+}

package/src/core/context-report.ts

@@ -0,0 +1,228 @@
+/** What is actually in the context window, item by item — and how far our arithmetic is from what
+ *  the provider says it charged for.
+ *
+ *  Two numbers exist for every turn and they are NOT the same thing:
+ *    - the ESTIMATE: o200k over every part we are about to send. Ours, synchronous, available before
+ *      a request and for a session that never ran. An estimate for anything that is not an OpenAI
+ *      tokenizer — Anthropic's is not public, and its 4.7-generation tokenizer produces materially
+ *      more tokens for the same text, so the estimate reads LOW there.
+ *    - the REPORTED prompt: what the provider itself counted, i.e. `input + cacheRead + cacheWrite`
+ *      of a turn's usage. Cache reads and writes are part of the prompt the model saw; leaving them
+ *      out is the most common way a context meter reads far too low on an agentic session, where
+ *      almost the whole prompt is a cache read.
+ *  drift() compares them at the same point in the transcript, so "how wrong is our meter for this
+ *  provider" becomes a measured number instead of a belief. Beyond DRIFT_TOLERANCE it is worth
+ *  saying out loud: it means compaction fires at the wrong time.
+ *
+ *  Nothing here reads the network or the disk, and nothing throws: a transcript with no usage at all
+ *  still produces a report, with `drift` simply absent. */
+
+import { partsTokenText } from "./loop.ts";
+import type { Message, MessagePart } from "./types.ts";
+import { tokenScaleFor } from "./token-scale.ts";
+import { contextHealth, costUsdTiered, countTokens, type NormalizedUsage, type PricingRow } from "./usage.ts";
+import { ratesFor } from "../providers/catalog.ts";
+import type { PriceTier } from "../providers/catalog-local.ts";
+
+/** past this the estimate is misleading enough to name — the compaction trigger reads the estimate */
+export const DRIFT_TOLERANCE = 0.05;
+
+/** the budget for a model whose window we do not know — the old flat value, kept as the fallback */
+export const DEFAULT_CONTEXT_BUDGET = 200_000;
+/** never plan for less history than this, however small the window says it is */
+export const MIN_CONTEXT_BUDGET = 32_000;
+/** room left beside the history for the system prompt, the tool schemas and the indexes */
+export const PROMPT_OVERHEAD_TOKENS = 24_000;
+/** assumed answer room when the catalog states no output limit */
+const ASSUMED_OUTPUT = 32_000;
+
+/** How much history a run may carry before compaction. A flat 200k spends a fifth of a 1M window and
+ *  overflows a 128k one, so it is derived: the window minus what the answer and the fixed prompt need.
+ *  An explicit override wins (ROVECODE_CONTEXT_BUDGET), an unknown window keeps the old default, and a
+ *  window too small to hold the floor gets a proportional share rather than a budget larger than itself. */
+export function contextBudgetFor(opts: { window?: number; maxOutput?: number; override?: number; scale?: number }): number {
+  const { window, maxOutput, override } = opts;
+  if (override !== undefined && Number.isFinite(override) && override > 0) return Math.floor(override);
+  if (!window || !Number.isFinite(window) || window <= 0) return DEFAULT_CONTEXT_BUDGET;
+  const reserve = (Number.isFinite(maxOutput) && (maxOutput ?? 0) > 0 ? (maxOutput as number) : ASSUMED_OUTPUT) + PROMPT_OVERHEAD_TOKENS;
+  const room = window - reserve;
+  const raw = room < MIN_CONTEXT_BUDGET ? Math.max(1, Math.floor(window * 0.6)) : Math.floor(room);
+  // The budget is compared against an estimate, so a model whose tokenizer counts more than the
+  // estimator must get a smaller budget — dividing here is exactly equivalent to inflating every
+  // estimate at every call site, and there is one of it. See core/token-scale.ts for the measurements.
+  const scale = opts.scale !== undefined && Number.isFinite(opts.scale) && opts.scale > 0 ? opts.scale : 1;
+  return Math.max(1, Math.floor(raw / scale));
+}
+
+export interface ContextSlice {
+  label: string;
+  tokens: number;
+  /** of the estimate, 0..1 — 0 when the estimate is 0 */
+  share: number;
+  /** what the reader should know about this row, when a number alone would mislead */
+  note?: string;
+}
+
+export interface ContextDrift {
+  /** our estimate of the prompt at the last turn that reported usage */
+  estimated: number;
+  /** what that turn says it was given: input + cacheRead + cacheWrite */
+  reported: number;
+  /** reported − estimated; positive means we are UNDER-counting the real window */
+  delta: number;
+  /** |delta| / reported, 0 when reported is 0 */
+  fraction: number;
+  beyondTolerance: boolean;
+}
+
+export interface ContextReport {
+  model: { provider: string; model: string };
+  /** the catalog's context window for the current model, when it knows one */
+  window?: number;
+  /** o200k over the whole transcript — what the next request would carry */
+  estimated: number;
+  /** the estimate corrected towards this model's own tokenizer; equals `estimated` when unmeasured.
+   *  The window rows below are computed from THIS, because it is the number the provider will use. */
+  corrected: number;
+  /** the correction that was applied, and where its number came from */
+  scale: { factor: number; measured: boolean; note: string };
+  slices: ContextSlice[];
+  /** window − corrected, floored at 0; absent when the window is unknown */
+  remaining?: number;
+  /** corrected / window; absent when the window is unknown */
+  fraction?: number;
+  nearLimit?: boolean;
+  drift?: ContextDrift;
+  /** summed over every turn that reported usage */
+  totals: NormalizedUsage;
+  /** USD over the turns that could be priced, and how many could not */
+  costUsd?: number;
+  unpricedTurns: number;
+  /** images carry tokens we do not estimate — say how many rather than pretend they are free */
+  images: number;
+}
+
+export interface ReportInput {
+  messages: readonly Message[];
+  /** the current model, used for the window and for turns with no origin */
+  current: { provider: string; model: string };
+  /** window + pricing for a model, however the caller gets them (catalog, overlay, a test double) */
+  lookup: (ref: { provider: string; model: string }) => { contextWindow?: number; pricing?: PricingRow; tier?: PriceTier } | undefined;
+  /** the system prompt that will be sent, when the caller has it */
+  system?: string;
+  /** the serialized tool schemas that will be sent, when the caller has them */
+  toolSchemas?: string;
+}
+
+const tokensOf = (text: string): number => (text ? countTokens(text) : 0);
+
+function partTokens(parts: readonly MessagePart[], kind: MessagePart["kind"]): number {
+  const only = parts.filter((p) => p.kind === kind);
+  return only.length === 0 ? 0 : tokensOf(partsTokenText(only as MessagePart[]));
+}
+
+/** Roles are grouped the way a reader thinks about them, not the way the wire does: what I sent, what
+ *  the model said, what the tools were asked, what they answered. Tool traffic dominates an agentic
+ *  session and hiding it inside "assistant" is what makes a context meter useless. */
+export function contextReport(input: ReportInput): ContextReport {
+  const { messages, current, lookup } = input;
+  const info = lookup(current);
+
+  const userText = messages.filter((m) => m.role === "user");
+  const assistantText = messages.filter((m) => m.role === "assistant");
+  const systemMsgs = messages.filter((m) => m.role === "system");
+
+  const slices: ContextSlice[] = [];
+  const push = (label: string, tokens: number, note?: string) => {
+    if (tokens > 0) slices.push({ label, tokens, share: 0, ...(note ? { note } : {}) });
+  };
+
+  push("system prompt", tokensOf(input.system ?? "") + partTokens(systemMsgs.flatMap((m) => m.parts), "text"));
+  push("tool schemas", tokensOf(input.toolSchemas ?? ""), input.toolSchemas ? undefined : "not supplied");
+  push("your messages", partTokens(userText.flatMap((m) => m.parts), "text"));
+  push("assistant replies", partTokens(assistantText.flatMap((m) => m.parts), "text"));
+  const allParts = messages.flatMap((m) => m.parts);
+  push("tool calls", partTokens(allParts, "tool_call"));
+  push("tool results", partTokens(allParts, "tool_result"));
+
+  const estimated = slices.reduce((n, s) => n + s.tokens, 0);
+  for (const s of slices) s.share = estimated > 0 ? s.tokens / estimated : 0;
+
+  const totals: NormalizedUsage = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+  let cost = 0;
+  let priced = 0;
+  let unpricedTurns = 0;
+  for (const m of messages) {
+    const u = m.usage;
+    if (!u) continue;
+    const n: NormalizedUsage = { input: u.input, output: u.output, cacheRead: u.cacheRead ?? 0, cacheWrite: u.cacheWrite ?? 0 };
+    totals.input += n.input; totals.output += n.output; totals.cacheRead += n.cacheRead; totals.cacheWrite += n.cacheWrite;
+    if (n.input === 0 && n.output === 0 && n.cacheRead === 0 && n.cacheWrite === 0) continue;
+    const info = lookup(m.origin ?? current);
+    // The prompt this turn carried decides the rate on a tiered model: xAI and Google bill a prompt
+    // over 200k at the upper rate, and xAI applies it to the whole request. Pricing a tiered turn at
+    // the base rate printed roughly HALF the real cost, with no caveat saying so — the TUI's /cost had
+    // this right and this report did not, which is the worst arrangement of the two.
+    const c = info?.pricing
+      ? costUsdTiered(n, ratesFor({ ...(m.origin ?? current), pricing: info.pricing, ...(info.tier ? { tier: info.tier } : {}) }, n.input + n.cacheRead + n.cacheWrite))
+      : undefined;
+    if (c === undefined) unpricedTurns += 1;
+    else { cost += c; priced += 1; }
+  }
+
+  // The window rows are what a reader acts on, so they are computed from the corrected estimate: on
+  // Claude 5 o200k reads up to 1.58x low, and a meter that says 60% of a window already at 95% is worse
+  // than no meter. `estimated` stays raw beside it so the correction is visible, never silent.
+  const sc = tokenScaleFor(current);
+  const corrected = Math.ceil(estimated * sc.scale);
+  const report: ContextReport = {
+    model: current,
+    estimated,
+    corrected,
+    scale: { factor: sc.scale, measured: sc.measured, note: sc.note },
+    slices,
+    totals,
+    unpricedTurns,
+    images: allParts.filter((p) => p.kind === "image").length,
+    ...(priced > 0 ? { costUsd: cost } : {}),
+  };
+  if (info?.contextWindow) {
+    const health = contextHealth(corrected, info.contextWindow);
+    report.window = info.contextWindow;
+    report.fraction = health.fraction;
+    report.nearLimit = health.nearLimit;
+    report.remaining = Math.max(0, info.contextWindow - corrected);
+  }
+  // the two rows the provider counted and the transcript never stored — see drift()
+  const fixedTokens = (slices.find((x) => x.label === "system prompt")?.tokens ?? 0) + (slices.find((x) => x.label === "tool schemas")?.tokens ?? 0);
+  const d = drift(messages, fixedTokens);
+  if (d) report.drift = d;
+  return report;
+}
+
+/** Our estimate against the provider's own count, measured at the last turn that reported one.
+ *  The comparison point matters: a turn's usage describes the prompt BEFORE that turn, so the
+ *  estimate is taken over everything up to it, exclusive. Returns undefined when no turn reported
+ *  a prompt (a fresh session, or a provider that sends no usage).
+ *
+ *  `fixedTokens` is the system prompt plus the tool schemas. They must be included or the comparison
+ *  is not a comparison: neither is ever stored in a transcript — the system message is appended to the
+ *  wire payload and never to history, and tool schemas are a separate wire field entirely — while the
+ *  provider's `reported` count is of a request that always carried both. Leaving them out made every
+ *  session look like it drifted by roughly the size of the fixed prompt, which on a fresh session is
+ *  most of it, and did so even for OpenAI models where the estimator is exact by construction. That is
+ *  a false signal on the one line whose whole job is to say whether the meter can be trusted. */
+export function drift(messages: readonly Message[], fixedTokens = 0): ContextDrift | undefined {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const u = messages[i]?.usage;
+    if (!u) continue;
+    const reported = u.input + (u.cacheRead ?? 0) + (u.cacheWrite ?? 0);
+    if (reported <= 0) continue;
+    const before = messages.slice(0, i);
+    const estimated = fixedTokens + (before.length === 0 ? 0 : tokensOf(before.map((m) => partsTokenText(m.parts)).join("\n")));
+    const delta = reported - estimated;
+    const fraction = reported > 0 ? Math.abs(delta) / reported : 0;
+    return { estimated, reported, delta, fraction, beyondTolerance: fraction > DRIFT_TOLERANCE };
+  }
+  return undefined;
+}

package/src/core/context.ts

@@ -0,0 +1,60 @@
+/** Token accounting + ordered context assembly (ADR-007). */
+
+export interface ContextChunk {
+  name: string;          // "system" | "skills" | "repo-map" | "files" | "history" | "reminder"
+  text: string;
+  /** drop first under pressure; history is compacted not dropped */
+  priority: number;      // higher = keep longer
+  tokens: number;
+}
+
+/** Cheap estimator: ~4 chars/token, clamped. Accurate enough for budgeting;
+ *  providers report exact usage which we feed back via usage accounting. */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+export interface AssemblyResult {
+  chunks: ContextChunk[];      // kept, in prompt order
+  dropped: ContextChunk[];     // non-history chunks evicted to fit budget (lowest priority first)
+  totalTokens: number;         // tokens of kept chunks
+  overBudget: boolean;         // true when even kept chunks exceed budget
+}
+
+/** Order: system > files > repo-map > skills > history > reminder (aider ChatChunks ordering).
+ *  History is never dropped here (compaction owns it); non-history chunks are
+ *  evicted lowest-priority-first until the budget holds — system last-dropped. */
+export function assembleContext(chunks: ContextChunk[], budgetTokens: number): AssemblyResult {
+  const ordered = [...chunks].sort((a, b) => b.priority - a.priority);
+  const nonHistory = ordered.filter((c) => c.name !== "history");
+  const dropped: ContextChunk[] = [];
+  const kept = [...nonHistory];
+  const hist = ordered.find((c) => c.name === "history");
+  const histTokens = hist?.tokens ?? 0;
+  while (kept.length > 0 && kept.reduce((n, c) => n + c.tokens, 0) + histTokens > budgetTokens) {
+    // evict lowest-priority kept chunk (tail after priority sort = system last)
+    const victim = kept.pop()!;
+    dropped.push(victim);
+  }
+  const total = kept.reduce((n, c) => n + c.tokens, 0) + histTokens;
+  const chunksOut = [...kept];              // prompt order: high priority first
+  if (hist) chunksOut.push(hist);
+  return { chunks: chunksOut, dropped, totalTokens: total, overBudget: total > budgetTokens };
+}
+
+/** Head/tail summarization plan (aider history.py:41): keep recent tail under
+ *  half budget, summarize older head. Pure — callers do the LLM summarize. */
+export function planCompaction(history: Message4Plan[], budgetTokens: number): { keep: Message4Plan[]; summarize: Message4Plan[] } {
+  const total = history.reduce((n, m) => n + m.tokens, 0);
+  if (total <= budgetTokens * 0.8) return { keep: history, summarize: [] };
+  const half = Math.floor(budgetTokens / 2);
+  let acc = 0; let cut = history.length;
+  for (let i = history.length - 1; i >= 0; i--) {
+    acc += history[i]!.tokens;
+    if (acc > half) { cut = i + 1; break; }
+    cut = i;
+  }
+  return { keep: history.slice(cut), summarize: history.slice(0, cut) };
+}
+
+export interface Message4Plan { id: string; tokens: number; text: string }