codemax-cli 0.0.0-stage → 0.1.3

package/src/core/brief.ts

@@ -0,0 +1,314 @@
+import type { Config } from "../config.ts";
+import type { AgentId, Turn } from "../adapters/types.ts";
+import { diffStat, headLine, recentCommits } from "./git.ts";
+import { checkpointDiff } from "./checkpoint.ts";
+import { BRIEF_MARKER, type Ledger } from "./ledger.ts";
+import type { Step, StepOf } from "./journal.ts";
+
+export interface BriefInput {
+  ledger: Ledger;
+  cwd: string;
+  to: AgentId;
+  from?: AgentId;
+  reason?: string;
+  config: Config;
+  /** "takeover" (default): the agent continues the task. "context": a one-off question (/ask, routes) that must not take the task over. */
+  purpose?: "takeover" | "context";
+}
+
+/**
+ * The handoff prompt the next agent starts with. With a step journal this is a
+ * resume packet: the task, where and why the last agent stopped (including the
+ * step in flight), the plan, every step taken, and the real code diff since the
+ * task began. Without one (an older ledger) it falls back to a turn summary.
+ */
+export async function buildBrief(input: BriefInput): Promise<string> {
+  const steps = input.ledger.journal.steps();
+  if (steps.some((s) => s.kind === "user")) return buildResumePacket(input, steps);
+  return buildTurnBrief(input);
+}
+
+// ---------------------------------------------------------------- resume packet
+
+export async function buildResumePacket(input: BriefInput, steps: Step[]): Promise<string> {
+  const { ledger, cwd, to, from, reason, config } = input;
+  const budget = config.brief.resumeChars;
+  const task = ledger.journal.task(steps);
+  const workSteps = task.steps.filter((s) => s.kind !== "user" || s !== task.request);
+  const lastEnd = [...task.steps].reverse().find((s): s is StepOf<"end"> => s.kind === "end");
+  const plan = [...task.steps].reverse().find((s): s is StepOf<"plan"> => s.kind === "plan");
+  const unfinishedPlan = plan?.entries.some((e) => e.status !== "completed");
+  const stoppedAgent = lastEnd?.agent ?? from;
+  const inProgress = !lastEnd || lastEnd.outcome !== "done" || !!unfinishedPlan;
+  const context = input.purpose === "context";
+
+  const head: string[] = [BRIEF_MARKER];
+  if (context)
+    head.push(
+      "Context only: this is the current state of a coding task in this repository, recorded by codemax while other agents worked on it. " +
+        "Do not take the task over, and do not change files unless the message at the end asks you to. Answer only that message.",
+    );
+  else head.push(
+    `You are taking over a coding task in this repository${stoppedAgent ? ` from ${stoppedAgent}` : ""}${reason ? ` (${reason})` : ""}. ` +
+      "Same user, same repo; only the agent changed. " +
+      (inProgress
+        ? "Resume exactly where it stopped: do not restart and do not redo finished steps. First check the step that was in flight (if any) actually happened, then continue the plan."
+        : "The last task looks finished. Confirm that briefly and ask the user what is next; do not redo the work."),
+  );
+  head.push("", `Repo: ${await headLine(cwd)}`);
+
+  head.push("", "## The task", quoteBlock(task.request?.text ?? "(no request recorded)"));
+  for (const f of task.followUps) head.push("", "Follow-up from the user:", quoteBlock(f.text));
+
+  if (lastEnd || stoppedAgent) head.push("", "## Where it stopped", ...whereItStopped(task.steps, lastEnd));
+
+  if (plan) {
+    head.push("", "## Plan (latest)");
+    let marked = false;
+    for (const e of plan.entries) {
+      const box = e.status === "completed" ? "[x]" : e.status === "in_progress" ? "[~]" : "[ ]";
+      const next = !context && !marked && e.status !== "completed" ? "  ← continue here" : "";
+      if (next) marked = true;
+      head.push(`${box} ${e.content}${next}`);
+    }
+  }
+
+  const fixed = head.join("\n");
+  let room = Math.max(2000, budget - fixed.length);
+
+  // The real code change since the task began: what the next agent most needs to see.
+  const diff = await taskDiff(cwd, task.request?.checkpoint);
+  const diffBudget = Math.floor(room * 0.45);
+  const diffPart = diff.text ? ["", `## Code changes since the task started${diff.vs ? ` (vs snapshot ${diff.vs.slice(0, 8)})` : ""}`, "```diff", cut(diff.text, diffBudget, "diff"), "```"] : ["", "## Code changes since the task started", "(none)"];
+  room -= diffPart.join("\n").length;
+
+  // Steps, newest kept first when space is short.
+  const stepLines = workSteps.map((s) => formatStep(s)).filter((l): l is string => !!l);
+  const stepBudget = Math.floor(room * 0.8);
+  const kept: string[] = [];
+  let used = 0;
+  for (let i = stepLines.length - 1; i >= 0; i--) {
+    const l = stepLines[i]!;
+    if (used + l.length + 1 > stepBudget) {
+      kept.unshift(`… ${i + 1} earlier step${i ? "s" : ""} on this task omitted for space`);
+      break;
+    }
+    kept.unshift(l);
+    used += l.length + 1;
+  }
+  room -= used;
+  const stepsPart = kept.length ? ["", `## Steps taken on this task (oldest first)`, ...kept] : [];
+
+  // Earlier conversation, condensed: previous requests and final answers.
+  // Earlier tasks from the journal; the old turn list only for history recorded before it existed.
+  const preJournal = steps[0] ? ledger.turns().filter((t) => t.ts < steps[0]!.ts) : [];
+  const earlier = condensedHistory(task.earlier, preJournal, Math.max(0, Math.min(room, Math.floor(budget * 0.15))));
+  const summary = ledger.summary();
+
+  const tail: string[] = [];
+  if (earlier) tail.push("", "## Earlier conversation (condensed)", earlier);
+  if (summary) tail.push("", "## Project summary", cut(summary, 1500, "summary"));
+  const commits = await recentCommits(cwd, 3);
+  if (commits) tail.push("", "## Recent commits", commits);
+  if (to && !context) tail.push("", `You are ${to}. Continue now.`);
+
+  return [fixed, ...stepsPart, ...diffPart, ...tail].join("\n");
+}
+
+/**
+ * For an agent whose own session resumes: only what happened while it was away.
+ * Returns null when nobody else did anything since its last turn.
+ */
+export async function buildCatchup(input: BriefInput): Promise<string | null> {
+  const { ledger, cwd, to, config } = input;
+  const steps = ledger.journal.steps();
+  const since = ledger.journal.lastSeen(to, steps);
+  if (since === undefined) return null;
+  const after = steps.filter((s) => s.ts > since && s.kind !== "handoff");
+  const others = after.filter((s) => s.agent !== to && s.kind !== "user");
+  if (!others.length) return null;
+  const users = after.filter((s): s is StepOf<"user"> => s.kind === "user");
+  const plan = [...after].reverse().find((s): s is StepOf<"plan"> => s.kind === "plan");
+  const lastEnd = [...after].reverse().find((s): s is StepOf<"end"> => s.kind === "end");
+  const agents = [...new Set(others.map((s) => s.agent))].join(", ");
+
+  const out: string[] = [BRIEF_MARKER];
+  out.push(
+    `Welcome back. Your own session history is intact. While you were away, ${agents} worked in this repo. ` +
+      "Here is only what changed since your last turn. Continue from the current state; do not undo their work unless it is wrong.",
+  );
+  if (users.length) {
+    out.push("", "## New requests from the user");
+    for (const u of users) out.push(quoteBlock(u.text));
+  }
+  if (lastEnd) out.push("", "## Where it stopped", ...whereItStopped(after, lastEnd));
+  if (plan) {
+    out.push("", "## Plan (latest)");
+    for (const e of plan.entries) out.push(`${e.status === "completed" ? "[x]" : e.status === "in_progress" ? "[~]" : "[ ]"} ${e.content}`);
+  }
+  const budget = Math.floor(config.brief.resumeChars * 0.6);
+  const lines = after.filter((s) => s.agent !== to || s.kind === "user").map((s) => formatStep(s)).filter((l): l is string => !!l);
+  out.push("", "## What happened (oldest first)", ...lastLines(lines, Math.floor(budget * 0.5)));
+  // Diff from the first snapshot taken after this agent stopped: before a user message or a
+  // handoff turn (an agent that took over and edited files snapshots first).
+  const firstSnapshot = steps.find((s) => s.ts > since && (s.kind === "user" || s.kind === "handoff") && s.checkpoint) as { checkpoint?: string } | undefined;
+  const diff = firstSnapshot?.checkpoint ? await checkpointDiff(cwd, firstSnapshot.checkpoint).catch(() => "") : "";
+  if (diff) out.push("", "## Code changes while you were away", "```diff", cut(diff, Math.floor(budget * 0.5), "diff"), "```");
+  else out.push("", "## Uncommitted changes now", await diffStat(cwd));
+  return out.join("\n");
+}
+
+function whereItStopped(steps: Step[], end: StepOf<"end"> | undefined): string[] {
+  const out: string[] = [];
+  if (!end) return ["The last agent had not finished its first turn."];
+  const when = new Date(end.ts).toLocaleTimeString([], { hour: "numeric", minute: "2-digit" });
+  const why =
+    end.outcome === "limit" ? `ran out of its usage limit${end.detail ? ` ("${oneLine(end.detail, 140)}")` : ""}`
+    : end.outcome === "cancelled" ? "was interrupted by the user"
+    : end.outcome === "error" ? `stopped on an error${end.detail ? `: ${oneLine(end.detail, 200)}` : ""}`
+    : "finished its turn";
+  out.push(`${end.agent} ${why} at ${when}.`);
+  const turnSteps = steps.filter((s) => s.turn === end.turn);
+  const tools = new Map(turnSteps.filter((s): s is StepOf<"tool"> => s.kind === "tool").map((t) => [t.id, t]));
+  for (const id of end.inFlight ?? []) {
+    const t = tools.get(id);
+    if (!t) continue;
+    out.push(`In flight when it stopped: ${t.title}${t.input ? ` with input ${oneLine(t.input, 400)}` : ""}. No result was recorded, so check whether it ran before continuing.`);
+  }
+  const lastText = [...turnSteps].reverse().find((s): s is StepOf<"text"> => s.kind === "text");
+  if (lastText) out.push(`Its last words: "${oneLine(lastText.text, 500)}"`);
+  const lastThought = [...turnSteps].reverse().find((s): s is StepOf<"thought"> => s.kind === "thought");
+  if (lastThought && end.outcome !== "done") out.push(`What it was thinking: "${oneLine(lastThought.text, 500)}"`);
+  return out;
+}
+
+export function formatStep(s: Step): string | null {
+  switch (s.kind) {
+    case "user":
+      return `- USER: ${oneLine(s.text, 600)}`;
+    case "text":
+      return `- [${s.agent}] said: ${oneLine(s.text, 600)}`;
+    case "tool": {
+      const status = s.status === "completed" ? "" : ` (${s.status === "failed" ? "FAILED" : s.status === "in_progress" || s.status === "pending" ? "NOT FINISHED" : s.status})`;
+      const lines = [`- [${s.agent}] ${s.title}${status}`];
+      if (s.input) lines.push(`    input: ${oneLine(s.input, 300)}`);
+      if (s.output) lines.push(`    result: ${resultSnippet(s.output)}`);
+      return lines.join("\n");
+    }
+    case "plan":
+      return `- [${s.agent}] updated the plan: ${s.entries.map((e) => `${e.status === "completed" ? "[x]" : e.status === "in_progress" ? "[~]" : "[ ]"} ${e.content}`).join("; ")}`;
+    case "end":
+      return s.outcome === "done" ? null : `- [${s.agent}] turn ended: ${s.outcome}${s.detail ? ` (${oneLine(s.detail, 160)})` : ""}`;
+    case "handoff":
+      return `- handed over to ${s.agent}${s.reason ? ` (${s.reason})` : ""}`;
+    case "thought":
+      return null;
+  }
+}
+
+function condensedHistory(earlier: Step[], turns: Turn[], budget: number): string {
+  if (budget < 200) return "";
+  let lines: string[];
+  if (earlier.some((s) => s.kind === "user")) {
+    lines = [];
+    for (const s of earlier) {
+      if (s.kind === "user") lines.push(`USER: ${oneLine(s.text, 400)}`);
+      else if (s.kind === "text") {
+        // keep only each turn's final words
+        const nextSameTurn = earlier.slice(earlier.indexOf(s) + 1).some((x) => x.turn === s.turn && x.kind === "text");
+        if (!nextSameTurn) lines.push(`ASSISTANT (${s.agent}): ${oneLine(s.text, 400)}`);
+      }
+    }
+  } else {
+    lines = turns.slice(-8).map((t) => `${t.role === "user" ? "USER" : `ASSISTANT (${t.agent})`}: ${oneLine(t.text, 400)}`);
+  }
+  return lastLines(lines, budget).join("\n");
+}
+
+async function taskDiff(cwd: string, checkpoint?: string): Promise<{ text: string; vs?: string }> {
+  if (checkpoint) {
+    const text = await checkpointDiff(cwd, checkpoint).catch(() => "");
+    return { text, vs: checkpoint };
+  }
+  const p = Bun.spawn(["git", "diff", "--no-color", "HEAD"], { cwd, stdout: "pipe", stderr: "ignore" });
+  const text = (await new Response(p.stdout).text()).trimEnd();
+  await p.exited;
+  return { text };
+}
+
+function resultSnippet(output: string): string {
+  const lines = output.trim().split("\n");
+  if (lines.length <= 6) return lines.join("\n      ");
+  return [...lines.slice(0, 3), `… ${lines.length - 6} lines …`, ...lines.slice(-3)].join("\n      ");
+}
+
+function lastLines(lines: string[], budget: number): string[] {
+  const out: string[] = [];
+  let used = 0;
+  for (let i = lines.length - 1; i >= 0; i--) {
+    if (used + lines[i]!.length + 1 > budget) {
+      out.unshift(`… ${i + 1} earlier line${i ? "s" : ""} omitted`);
+      break;
+    }
+    out.unshift(lines[i]!);
+    used += lines[i]!.length + 1;
+  }
+  return out;
+}
+
+function quoteBlock(s: string): string {
+  return s.trim().split("\n").map((l) => `> ${l}`).join("\n");
+}
+
+function oneLine(s: string, max: number): string {
+  const t = s.replace(/\s+/g, " ").trim();
+  return t.length <= max ? t : t.slice(0, max - 1) + "…";
+}
+
+function cut(s: string, max: number, what: string): string {
+  if (s.length <= max) return s;
+  return s.slice(0, max) + `\n… ${what} cut: ${s.length - max} more characters (run git diff to see all)`;
+}
+
+// ---------------------------------------------------------------- legacy brief (no journal)
+
+async function buildTurnBrief(input: BriefInput): Promise<string> {
+  const { ledger, cwd, to, from, reason, config } = input;
+  const { turns: maxTurns, maxChars, turnChars } = config.brief;
+  const all = ledger.turns();
+  const recent = all.slice(-maxTurns);
+  const agentsUsed = [...new Set(all.map((t) => t.agent))].filter((a) => a !== to);
+  const lastUser = [...all].reverse().find((t) => t.role === "user");
+
+  const lines: string[] = [];
+  lines.push(BRIEF_MARKER);
+  lines.push(
+    `You are continuing an existing coding session in this repository${from ? ` that was being handled by ${from}` : ""}${reason ? ` (${reason})` : ""}. ` +
+      "The user has not changed; only the agent has. Read the context below, then continue from where it left off. " +
+      "Do not redo completed work. If the last task looks finished, briefly confirm and ask what is next.",
+  );
+  lines.push("", `Repo: ${await headLine(cwd)}`);
+  if (agentsUsed.length) lines.push(`Previous agents on this project: ${agentsUsed.join(", ")}`);
+  const summary = ledger.summary();
+  if (summary) lines.push("", "## Project summary", summary);
+  if (recent.length) {
+    lines.push("", `## Recent conversation (oldest first, last ${recent.length} turns)`);
+    for (const t of recent) lines.push(`${t.role === "user" ? "USER" : `ASSISTANT (${t.agent})`}${t.tools?.length ? ` [tools: ${t.tools.join(", ")}]` : ""}: ${truncate(t.text.replace(/\s+/g, " ").trim(), turnChars)}`);
+  } else lines.push("", "## Recent conversation", "(no prior turns recorded)");
+  const commits = await recentCommits(cwd, 5);
+  if (commits) lines.push("", "## Recent commits", commits);
+  lines.push("", "## Uncommitted changes", await diffStat(cwd));
+  if (lastUser) lines.push("", "## Last user request", truncate(lastUser.text.trim(), turnChars));
+  return clamp(lines.join("\n"), maxChars);
+}
+
+function truncate(s: string, max: number): string {
+  return s.length <= max ? s : s.slice(0, max - 1) + "…";
+}
+
+function clamp(s: string, max: number): string {
+  if (s.length <= max) return s;
+  const head = Math.floor(max * 0.55);
+  const tail = max - head - 20;
+  return s.slice(0, head) + "\n…[truncated]…\n" + s.slice(-tail);
+}

package/src/core/budget.ts

@@ -0,0 +1,42 @@
+import { join } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import type { AgentId } from "../adapters/types.ts";
+import { CODEMAX_HOME } from "./paths.ts";
+import { Ledger } from "./ledger.ts";
+import { recordCost, type UsageRecord } from "./usage.ts";
+
+export type BudgetKey = AgentId | "all";
+
+export function startOfDay(now = Date.now()): number {
+  const d = new Date(now);
+  d.setHours(0, 0, 0, 0);
+  return d.getTime();
+}
+
+/** Today's API-equivalent spend per agent, across every project codemax has seen. */
+export function spendToday(now = Date.now()): Map<BudgetKey, number> {
+  const since = startOfDay(now);
+  const out = new Map<BudgetKey, number>();
+  const root = join(CODEMAX_HOME, "projects");
+  if (!existsSync(root)) return out;
+  for (const d of readdirSync(root)) {
+    for (const r of new Ledger("/", join(root, d)).usage()) addSpend(out, r, since);
+  }
+  return out;
+}
+
+export function addSpend(map: Map<BudgetKey, number>, r: UsageRecord, since = startOfDay()) {
+  if (r.ts < since) return;
+  const usd = recordCost(r).usd;
+  map.set(r.agent, (map.get(r.agent) ?? 0) + usd);
+  map.set("all", (map.get("all") ?? 0) + usd);
+}
+
+export type BudgetLevel = "ok" | "warn" | "over";
+
+export function budgetLevel(spent: number, limit: number | undefined): BudgetLevel {
+  if (!limit || limit <= 0) return "ok";
+  if (spent >= limit) return "over";
+  if (spent >= limit * 0.8) return "warn";
+  return "ok";
+}

package/src/core/checkpoint.ts

@@ -0,0 +1,139 @@
+import { join } from "node:path";
+import { existsSync, mkdirSync, rmSync, rmdirSync, readdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+/**
+ * Working-tree checkpoints that never touch the user's index, branches or
+ * stash: a private index file snapshots everything git would add (`.gitignore`
+ * respected) into a commit stored under refs/codemax/checkpoints/.
+ */
+
+async function run(cwd: string, args: string[], env: Record<string, string> = {}): Promise<{ code: number; out: string; err: string }> {
+  const p = Bun.spawn(["git", ...args], { cwd, env: { ...process.env, ...env }, stdout: "pipe", stderr: "pipe" });
+  const [out, err] = await Promise.all([new Response(p.stdout).text(), new Response(p.stderr).text()]);
+  return { code: await p.exited, out: out.trimEnd(), err: err.trimEnd() };
+}
+
+async function gitDir(cwd: string): Promise<string | null> {
+  const r = await run(cwd, ["rev-parse", "--absolute-git-dir"]);
+  return r.code === 0 ? r.out : null;
+}
+
+/** Untracked files above this size are left out of snapshots (and so never deleted by /undo). */
+export const MAX_UNTRACKED_BYTES = 5 * 1024 * 1024;
+/** Checkpoint refs kept per repo; older ones are deleted so git can collect their objects. */
+export const KEEP_CHECKPOINTS = 50;
+
+async function largeUntracked(cwd: string): Promise<string[]> {
+  const r = await run(cwd, ["ls-files", "-o", "--exclude-standard", "-z"]);
+  if (r.code !== 0) return [];
+  const { statSync } = await import("node:fs");
+  return r.out.split("\0").filter((f) => {
+    if (!f) return false;
+    try {
+      return statSync(join(cwd, f)).size > MAX_UNTRACKED_BYTES;
+    } catch {
+      return false;
+    }
+  });
+}
+
+async function treeOfWorkingDir(cwd: string, index: string): Promise<string | null> {
+  const env = { GIT_INDEX_FILE: index };
+  await run(cwd, ["read-tree", "--empty"], env);
+  const skip = (await largeUntracked(cwd)).map((f) => `:(exclude,literal)${f}`);
+  if ((await run(cwd, ["add", "-A", "--", ".", ...skip], env)).code !== 0) return null;
+  const t = await run(cwd, ["write-tree"], env);
+  return t.code === 0 ? t.out : null;
+}
+
+export interface Checkpoint {
+  sha: string;
+  label: string;
+  ts: number;
+}
+
+/** Snapshot the working tree. Returns null outside a git repo. */
+export async function createCheckpoint(cwd: string, label: string): Promise<Checkpoint | null> {
+  const dir = await gitDir(cwd);
+  if (!dir) return null;
+  const index = join(dir, "codemax-checkpoint-index");
+  const tree = await treeOfWorkingDir(cwd, index);
+  if (!tree) return null;
+  const head = await run(cwd, ["rev-parse", "--verify", "-q", "HEAD"]);
+  const ident = { GIT_AUTHOR_NAME: "codemax", GIT_AUTHOR_EMAIL: "codemax@localhost", GIT_COMMITTER_NAME: "codemax", GIT_COMMITTER_EMAIL: "codemax@localhost" };
+  const c = await run(cwd, ["commit-tree", tree, ...(head.code === 0 ? ["-p", head.out] : []), "-m", label], ident);
+  if (c.code !== 0) return null;
+  const ts = Date.now();
+  await run(cwd, ["update-ref", `refs/codemax/checkpoints/${ts}`, c.out]);
+  await pruneCheckpoints(cwd);
+  return { sha: c.out, label, ts };
+}
+
+/** Keep the newest KEEP_CHECKPOINTS refs; delete the rest. */
+export async function pruneCheckpoints(cwd: string, keep = KEEP_CHECKPOINTS) {
+  const r = await run(cwd, ["for-each-ref", "--sort=-refname", "--format=%(refname)", "refs/codemax/checkpoints"]);
+  const old = r.out.split("\n").filter(Boolean).slice(keep);
+  for (const ref of old) await run(cwd, ["update-ref", "-d", ref]);
+}
+
+/** Make the working tree match a checkpoint: restore its files, delete files created since. */
+export async function restoreCheckpoint(cwd: string, sha: string): Promise<{ restored: number; removed: string[] }> {
+  const dir = await gitDir(cwd);
+  if (!dir) throw new Error("not a git repository");
+  const index = join(dir, "codemax-restore-index");
+  const now = await treeOfWorkingDir(cwd, index);
+  const list = async (tree: string) => (await run(cwd, ["ls-tree", "-r", "--name-only", tree])).out.split("\n").filter(Boolean);
+  const target = new Set(await list(sha));
+  const current = now ? await list(now) : [];
+  const removed = current.filter((f) => !target.has(f));
+  for (const f of removed) {
+    const abs = join(cwd, f);
+    rmSync(abs, { force: true });
+    // tidy now-empty directories the agent created
+    let d = dirname(abs);
+    while (d.startsWith(cwd) && d !== cwd && existsSync(d) && readdirSync(d).length === 0) {
+      rmdirSync(d);
+      d = dirname(d);
+    }
+  }
+  const env = { GIT_INDEX_FILE: index };
+  await run(cwd, ["read-tree", sha], env);
+  const co = await run(cwd, ["checkout-index", "-a", "-f"], env);
+  if (co.code !== 0) throw new Error(co.err || "checkout-index failed");
+  return { restored: target.size, removed };
+}
+
+export async function listCheckpoints(cwd: string, limit = 20): Promise<Checkpoint[]> {
+  const r = await run(cwd, ["for-each-ref", "--sort=-refname", `--count=${limit}`, "--format=%(objectname) %(refname:lstrip=3) %(contents:subject)", "refs/codemax/checkpoints"]);
+  if (r.code !== 0 || !r.out) return [];
+  return r.out.split("\n").map((l) => {
+    const [sha, ts, ...rest] = l.split(" ");
+    return { sha: sha!, ts: Number(ts), label: rest.join(" ") };
+  });
+}
+
+/** Files that differ between a checkpoint and the working tree now. */
+export async function checkpointDiffStat(cwd: string, sha: string): Promise<string> {
+  const dir = await gitDir(cwd);
+  if (!dir) return "";
+  const now = await treeOfWorkingDir(cwd, join(dir, "codemax-restore-index"));
+  if (!now) return "";
+  return (await run(cwd, ["diff", "--stat", sha, now])).out;
+}
+
+/**
+ * The full code change between a checkpoint and the working tree now, new files
+ * included (the snapshot uses a private index, so the user's staging is untouched).
+ */
+export async function checkpointDiff(cwd: string, sha: string): Promise<string> {
+  const dir = await gitDir(cwd);
+  if (!dir) return "";
+  const now = await treeOfWorkingDir(cwd, join(dir, "codemax-restore-index"));
+  if (!now) return "";
+  return (await run(cwd, ["diff", "--no-color", "--no-ext-diff", "-M", sha, now])).out;
+}
+
+export function ensureDirFor(path: string) {
+  mkdirSync(dirname(path), { recursive: true });
+}

package/src/core/doctor.ts

@@ -0,0 +1,67 @@
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+import type { AgentId } from "../adapters/types.ts";
+
+export interface Finding {
+  agent: AgentId | "all";
+  severity: "block" | "warn";
+  message: string;
+  /** What `codemax doctor --fix` would do, when a safe fix exists. */
+  fix?: { description: string; apply: () => string };
+}
+
+const KEY_VARS = ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"];
+
+/**
+ * Checks that would make an agent bill an API key instead of a subscription,
+ * or act without asking. codemax is subscriptions-only, so "block" findings
+ * stop that agent from launching until fixed.
+ */
+export function diagnose(home: string = homedir(), env: NodeJS.ProcessEnv = process.env): Finding[] {
+  const out: Finding[] = [];
+  const CLAUDE_SETTINGS = join(home, ".claude", "settings.json");
+  const CLAUDE_LOCAL = join(home, ".claude", "settings.local.json");
+  for (const file of [CLAUDE_SETTINGS, CLAUDE_LOCAL]) {
+    if (!existsSync(file)) continue;
+    let json: any;
+    try {
+      json = JSON.parse(readFileSync(file, "utf8"));
+    } catch {
+      out.push({ agent: "claude", severity: "warn", message: `${file} is not valid JSON; Claude Code may ignore it` });
+      continue;
+    }
+    const injected = KEY_VARS.filter((k) => typeof json?.env?.[k] === "string" && json.env[k].length > 0);
+    if (injected.length) {
+      out.push({
+        agent: "claude",
+        severity: "block",
+        message: `${file} sets ${injected.join(", ")} in its "env" block. Claude Code applies that at startup, so every session (codemax or not) bills the API key instead of your claude.ai plan.`,
+        fix: {
+          description: `remove ${injected.join(", ")} from the "env" block of ${file} (a backup is written next to it)`,
+          apply: () => {
+            copyFileSync(file, `${file}.codemax-backup`);
+            for (const k of injected) delete json.env[k];
+            if (json.env && Object.keys(json.env).length === 0) delete json.env;
+            writeFileSync(file, JSON.stringify(json, null, 2) + "\n");
+            return `removed ${injected.join(", ")} from ${file}; backup at ${file}.codemax-backup`;
+          },
+        },
+      });
+    }
+    if (typeof json?.apiKeyHelper === "string" && json.apiKeyHelper) {
+      out.push({ agent: "claude", severity: "block", message: `${file} sets "apiKeyHelper"; Claude Code will fetch an API key from it and bill that key.` });
+    }
+    const mode = json?.permissions?.defaultMode;
+    if (file === CLAUDE_SETTINGS && mode && mode !== "default") {
+      out.push({ agent: "grok", severity: "warn", message: `Grok reads ${file}: permissions.defaultMode is "${mode}", so Grok acts without asking. Set it to "default" there to get prompts (this also changes Claude Code's own default).` });
+    }
+  }
+  const envKeys = KEY_VARS.concat(["OPENAI_API_KEY", "CURSOR_API_KEY", "XAI_API_KEY", "GROK_API_KEY", "GEMINI_API_KEY", "GOOGLE_API_KEY"]).filter((k) => env[k]);
+  if (envKeys.length) out.push({ agent: "all", severity: "warn", message: `${envKeys.join(", ")} set in this shell; codemax strips them for agents, but your plain CLI sessions will bill them.` });
+  return out;
+}
+
+export function blockers(agent: AgentId): Finding[] {
+  return diagnose().filter((f) => f.severity === "block" && (f.agent === agent || f.agent === "all"));
+}

package/src/core/files.ts

@@ -0,0 +1,62 @@
+import { join, relative } from "node:path";
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+
+const SKIP = new Set([".git", "node_modules", "dist", "build", ".next", ".turbo", "target", ".venv", "__pycache__"]);
+
+/** Repo files for @-mentions: git's view when available (ignores respected), else a bounded walk. */
+export async function listProjectFiles(cwd: string, max = 20000): Promise<string[]> {
+  try {
+    const p = Bun.spawn(["git", "ls-files", "-co", "--exclude-standard"], { cwd, stdout: "pipe", stderr: "ignore" });
+    const out = await new Response(p.stdout).text();
+    if ((await p.exited) === 0 && out.trim()) return out.split("\n").filter(Boolean).slice(0, max);
+  } catch {
+    /* fall through */
+  }
+  const files: string[] = [];
+  const walk = (dir: string, depth: number) => {
+    if (depth > 6 || files.length >= max) return;
+    for (const name of readdirSync(dir)) {
+      if (SKIP.has(name) || name.startsWith(".")) continue;
+      const abs = join(dir, name);
+      const st = statSync(abs);
+      if (st.isDirectory()) walk(abs, depth + 1);
+      else files.push(relative(cwd, abs));
+      if (files.length >= max) return;
+    }
+  };
+  walk(cwd, 0);
+  return files;
+}
+
+export const MENTION_RE = /(^|\s)@([^\s@]*)$/;
+
+/** Paths mentioned as @path in a message that exist in the project. */
+export function mentionedFiles(text: string, cwd: string): string[] {
+  const out: string[] = [];
+  for (const m of text.matchAll(/(?:^|\s)@([^\s@]+)/g)) {
+    const p = m[1]!.replace(/[),.;:]+$/, "");
+    if (!out.includes(p) && existsSync(join(cwd, p)) && statSync(join(cwd, p)).isFile()) out.push(p);
+  }
+  return out;
+}
+
+/** Contents block appended to a prompt for the mentioned files (bounded). */
+export function attachFiles(paths: string[], cwd: string, perFile = 30_000, total = 100_000): string {
+  let used = 0;
+  const parts: string[] = [];
+  for (const p of paths) {
+    let body = readFileSync(join(cwd, p), "utf8");
+    if (body.includes("\u0000")) {
+      parts.push(`--- ${p} (binary, not attached) ---`);
+      continue;
+    }
+    if (body.length > perFile) body = body.slice(0, perFile) + `\n… [truncated, ${body.length - perFile} more chars]`;
+    if (used + body.length > total) {
+      parts.push(`--- ${p} (skipped, attachment limit reached) ---`);
+      continue;
+    }
+    used += body.length;
+    parts.push(`--- ${p} ---\n${body}`);
+  }
+  return parts.length ? `\n\n[files the user attached with @]\n${parts.join("\n\n")}` : "";
+}

package/src/core/git.ts

@@ -0,0 +1,36 @@
+export async function git(cwd: string, args: string[]): Promise<string | null> {
+  try {
+    const p = Bun.spawn(["git", ...args], { cwd, stdout: "pipe", stderr: "pipe" });
+    const text = await new Response(p.stdout).text();
+    const code = await p.exited;
+    return code === 0 ? text.trimEnd() : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function isRepo(cwd: string): Promise<boolean> {
+  return (await git(cwd, ["rev-parse", "--is-inside-work-tree"])) === "true";
+}
+
+export async function diffStat(cwd: string): Promise<string> {
+  if (!(await isRepo(cwd))) return "(not a git repo)";
+  const staged = await git(cwd, ["diff", "--cached", "--stat"]);
+  const unstaged = await git(cwd, ["diff", "--stat"]);
+  const untracked = await git(cwd, ["ls-files", "--others", "--exclude-standard"]);
+  const parts: string[] = [];
+  if (staged) parts.push("staged:\n" + staged);
+  if (unstaged) parts.push("unstaged:\n" + unstaged);
+  if (untracked) parts.push("untracked:\n" + untracked.split("\n").slice(0, 30).join("\n"));
+  return parts.length ? parts.join("\n") : "(working tree clean)";
+}
+
+export async function headLine(cwd: string): Promise<string> {
+  const branch = await git(cwd, ["rev-parse", "--abbrev-ref", "HEAD"]);
+  const log = await git(cwd, ["log", "-1", "--format=%h %s"]);
+  return `${branch ?? "?"} @ ${log ?? "(no commits)"}`;
+}
+
+export async function recentCommits(cwd: string, n = 5): Promise<string> {
+  return (await git(cwd, ["log", `-${n}`, "--format=%h %s"])) ?? "";
+}