codemax-cli 0.0.0-stage → 0.1.3

package/src/core/orchestrator.ts

@@ -0,0 +1,352 @@
+import type { Config } from "../config.ts";
+import type { Adapter, AgentId, QuotaStatus, SessionRef } from "../adapters/types.ts";
+import { listAdapters, getAdapter } from "../adapters/index.ts";
+import { Ledger } from "./ledger.ts";
+import { AgentProcess } from "./pty.ts";
+import { Menu, type MenuRow } from "./menu.ts";
+import { OutputScanner, isExhausted } from "./quota.ts";
+import { buildBrief } from "./brief.ts";
+import { diffStat } from "./git.ts";
+import { CLEAR_SEQ, PASTE_END, PASTE_START, RESET_SEQ, out, termSize } from "./terminal.ts";
+import { findHotkey, parseHotkeys, type HotkeySpec } from "./hotkey.ts";
+
+interface Running {
+  adapter: Adapter;
+  /** True while the agent has the alternate screen active (tracked from its output). */
+  altScreen: boolean;
+  proc: AgentProcess;
+  ref: SessionRef | null;
+  scanner: OutputScanner;
+  sessionId?: string;
+  pendingPrompt?: string;
+  lastOutputAt: number;
+  firstOutputAt: number;
+  timers: ReturnType<typeof setInterval>[];
+}
+
+/**
+ * Owns the host terminal. Runs one agent TUI at a time inside a PTY, passes
+ * bytes through, opens the codemax menu on the hotkey, and performs switches.
+ */
+export class Orchestrator {
+  private running: Running | null = null;
+  private menu: Menu | null = null;
+  private detect = new Map<AgentId, { installed: boolean; version?: string }>();
+  private quota = new Map<AgentId, QuotaStatus>();
+  private switching = false;
+  private resolveDone!: () => void;
+  readonly done: Promise<void>;
+  private decoder = new TextDecoder();
+  private hotkeys: HotkeySpec[];
+
+  constructor(
+    private config: Config,
+    private ledger: Ledger,
+    private cwd: string,
+  ) {
+    this.done = new Promise((r) => (this.resolveDone = r));
+    this.hotkeys = parseHotkeys(config.hotkeys);
+    for (const [id, q] of Object.entries(ledger.quota())) this.quota.set(id as AgentId, q);
+  }
+
+  async start(agent: AgentId, fresh: boolean) {
+    this.attachHost();
+    await this.refreshDetect();
+    const first = this.detect.get(agent)?.installed ? agent : this.firstInstalled();
+    if (!first) {
+      this.teardownHost();
+      throw new Error("no supported agent CLI found on PATH");
+    }
+    if (first !== agent) out(`codemax: ${agent} not found, starting ${first}\r\n`);
+    await this.launch(getAdapter(first), { fresh, reason: undefined });
+    return this.done;
+  }
+
+  // ---------- host terminal ----------
+
+  private onStdin = (chunk: Buffer) => {
+    const bytes = new Uint8Array(chunk);
+    if (this.menu) {
+      const action = this.menu.handleKey(bytes);
+      if (action) void this.onMenuAction(action);
+      return;
+    }
+    // The hotkey may share a chunk with other keys when typed quickly: forward
+    // what came before it, open the menu, and let the menu see what followed.
+    const hit = findHotkey(bytes, this.hotkeys);
+    if (hit) {
+      if (hit.index > 0) this.running?.proc.write(bytes.subarray(0, hit.index));
+      this.openMenu("switch agent", true);
+      const rest = bytes.subarray(hit.index + hit.length);
+      const menu = this.menu as Menu | null; // openMenu() just set it; TS keeps the stale null narrowing
+      if (rest.length && menu) {
+        const action = menu.handleKey(rest);
+        if (action) void this.onMenuAction(action);
+      }
+      return;
+    }
+    this.running?.proc.write(bytes);
+  };
+
+  private onResize = () => {
+    const { cols, rows } = termSize();
+    this.running?.proc.resize(cols, rows);
+    this.menu?.render();
+  };
+
+  private attachHost() {
+    process.stdin.setRawMode?.(true);
+    process.stdin.resume();
+    process.stdin.on("data", this.onStdin);
+    process.on("SIGWINCH", this.onResize);
+    process.on("SIGINT", () => {}); // Ctrl+C is forwarded as a byte in raw mode
+  }
+
+  private teardownHost() {
+    process.stdin.off("data", this.onStdin);
+    process.off("SIGWINCH", this.onResize);
+    process.stdin.setRawMode?.(false);
+    process.stdin.pause();
+    out(RESET_SEQ);
+  }
+
+  // ---------- agent lifecycle ----------
+
+  private async launch(adapter: Adapter, o: { fresh: boolean; reason?: string; from?: AgentId }) {
+    const stale = this.quota.get(adapter.id);
+    if (stale?.source === "output") {
+      this.quota.delete(adapter.id);
+      this.ledger.clearQuota(adapter.id);
+    }
+    const saved = this.ledger.sessions()[adapter.id];
+    const resume = !o.fresh && saved ? saved : undefined;
+    const sessionId = resume ? undefined : adapter.newSessionId?.();
+    const hasHistory = this.ledger.turns().length > 0 || !!o.from;
+    const brief = hasHistory ? await buildBrief({ ledger: this.ledger, cwd: this.cwd, to: adapter.id, from: o.from, reason: o.reason, config: this.config }) : undefined;
+
+    const spec = adapter.launch({ cwd: this.cwd, resume, sessionId, prompt: brief, extraArgs: this.config.agentArgs[adapter.id] });
+    out(RESET_SEQ + CLEAR_SEQ);
+
+    const scanner = new OutputScanner(adapter.id, adapter.quotaPatterns, (q) => this.onQuota(q));
+    const run: Running = {
+      adapter,
+      ref: resume ?? null,
+      scanner,
+      sessionId,
+      pendingPrompt: spec.promptConsumed ? undefined : brief,
+      lastOutputAt: 0,
+      firstOutputAt: 0,
+      altScreen: false,
+      timers: [],
+      proc: null as unknown as AgentProcess,
+    };
+    // Subscriptions only: an API key in the environment is never passed to an agent.
+    const dropEnv = adapter.apiKeyEnv.filter((k) => process.env[k]);
+    if (dropEnv.length) out(`codemax: unset ${dropEnv.join(", ")} for ${adapter.name} — codemax only uses subscription logins, never API keys\r\n`);
+    run.proc = new AgentProcess({
+      cmd: spec.cmd,
+      cwd: this.cwd,
+      env: spec.env,
+      dropEnv,
+      onData: (chunk) => {
+        const now = Date.now();
+        if (!run.firstOutputAt) run.firstOutputAt = now;
+        run.lastOutputAt = now;
+        if (!this.menu) process.stdout.write(chunk);
+        const text = this.decoder.decode(chunk, { stream: true });
+        trackAltScreen(run, text);
+        scanner.feed(text);
+      },
+      onExit: (code) => void this.onAgentExit(run, code),
+    });
+    this.running = run;
+    this.ledger.addEvent({ kind: o.from ? "switch" : "start", agent: o.from, to: adapter.id, detail: o.reason });
+
+    run.timers.push(setInterval(() => void this.sync(run), 2000));
+    if (run.pendingPrompt) run.timers.push(setInterval(() => this.maybeTypePrompt(run), 250));
+    void this.locate(run);
+  }
+
+  /** Find the vendor session (transcript) for a freshly launched agent. Polls until the agent exits. */
+  private async locate(run: Running) {
+    if (run.ref) return;
+    while (this.running === run && !run.proc.exited) {
+      const ref = await run.adapter.locateSession({ cwd: this.cwd, startedAt: run.proc.startedAt, sessionId: run.sessionId });
+      if (ref) {
+        run.ref = ref;
+        this.ledger.saveSession(ref);
+        return;
+      }
+      await Bun.sleep(1000);
+    }
+  }
+
+  /** Pull new turns + quota from the vendor transcript into the ledger. */
+  private async sync(run: Running) {
+    if (!run.ref) return;
+    try {
+      if (run.adapter.readTranscript) {
+        const turns = await run.adapter.readTranscript(run.ref);
+        if (this.ledger.addTurns(turns) > 0) {
+          run.ref.lastUsedAt = Date.now();
+          this.ledger.saveSession(run.ref);
+        }
+      }
+      if (run.adapter.probeQuota) {
+        const q = await run.adapter.probeQuota(run.ref);
+        if (q) this.onQuota(q, true);
+      }
+    } catch {
+      /* transcript mid-write; retry next tick */
+    }
+  }
+
+  /** Type the handoff brief into TUIs that do not take a prompt argument. */
+  private maybeTypePrompt(run: Running) {
+    if (!run.pendingPrompt || !run.firstOutputAt) return;
+    const now = Date.now();
+    const quiet = now - run.lastOutputAt > 700;
+    const old = now - run.proc.startedAt > 1500;
+    const timeout = now - run.proc.startedAt > 15_000;
+    if ((quiet && old) || timeout) {
+      const text = run.pendingPrompt;
+      run.pendingPrompt = undefined;
+      run.proc.write(PASTE_START + text + PASTE_END);
+      setTimeout(() => run.proc.write("\r"), 200);
+    }
+  }
+
+  private onQuota(q: QuotaStatus, silent = false) {
+    const prev = this.quota.get(q.agent);
+    this.quota.set(q.agent, q);
+    this.ledger.saveQuota(q);
+    if (isExhausted(q) && !isExhausted(prev)) {
+      this.ledger.addEvent({ kind: "quota", agent: q.agent, detail: q.detail });
+      if (this.config.autoSwitch && !silent) this.offerSwitchWhenIdle(q);
+    }
+  }
+
+  /** Open the menu for a quota hit only once the agent has stopped printing, so a stream is never cut. */
+  private offerSwitchWhenIdle(q: QuotaStatus) {
+    const run = this.running;
+    const tick = setInterval(() => {
+      if (this.running !== run || this.menu) return clearInterval(tick);
+      if (Date.now() - (run?.lastOutputAt ?? 0) < 2000) return;
+      clearInterval(tick);
+      const guess = q.source === "output";
+      this.openMenu(
+        guess ? `${q.agent} may be out of quota — pick the next agent, or Esc if this is a false alarm` : `${q.agent} is out of quota — pick the next agent`,
+        true,
+        `${q.agent}: ${q.detail ?? "limit reached"}${guess ? " (screen text, not confirmed; forgotten in 30 min or when you relaunch it)" : ""}`,
+      );
+    }, 500);
+  }
+
+  private async onAgentExit(run: Running, code: number | null) {
+    run.timers.forEach(clearInterval);
+    if (this.running !== run) return; // killed by a switch; switch handles the rest
+    await this.sync(run);
+    this.ledger.addEvent({ kind: "exit", agent: run.adapter.id, detail: `exit ${code}`, diffStat: await diffStat(this.cwd) });
+    this.running = null;
+    out(RESET_SEQ);
+    if (this.switching) return;
+    this.openMenu(`${run.adapter.name} exited (${code}) — switch agent or quit`, false);
+  }
+
+  // ---------- menu ----------
+
+  private async refreshDetect() {
+    await Promise.all(
+      listAdapters(this.config.order).map(async (a) => {
+        const d = await a.detect();
+        this.detect.set(a.id, { installed: d.installed, version: d.version });
+      }),
+    );
+  }
+
+  private firstInstalled(): AgentId | undefined {
+    return listAdapters(this.config.order).find((a) => this.detect.get(a.id)?.installed)?.id;
+  }
+
+  private rows(): MenuRow[] {
+    const sessions = this.ledger.sessions();
+    return listAdapters(this.config.order).map((a) => ({
+      adapter: a,
+      installed: this.detect.get(a.id)?.installed ?? false,
+      version: this.detect.get(a.id)?.version,
+      session: sessions[a.id],
+      quota: this.quota.get(a.id),
+    }));
+  }
+
+  private openMenu(title: string, canClose: boolean, notice?: string) {
+    if (this.menu) return;
+    this.menu = new Menu({ title, rows: this.rows(), current: this.running?.adapter.id, notice, canClose, hotkeys: this.config.hotkeys });
+    // If the agent already owns the alternate screen, draw over it instead of
+    // nesting another alt-screen switch the terminal cannot unwind cleanly.
+    this.menu.open(!this.running?.altScreen);
+    void this.refreshDetect().then(() => this.menu?.update({ rows: this.rows() }));
+  }
+
+  private closeMenu() {
+    this.menu?.close(!this.running?.altScreen);
+    this.menu = null;
+    this.running?.proc.jiggle();
+  }
+
+  private async onMenuAction(action: { kind: string; agent?: AgentId; fresh?: boolean }) {
+    if (action.kind === "close") return this.closeMenu();
+    if (action.kind === "quit") return this.quit();
+    if (action.kind === "switch" && action.agent) {
+      const target = getAdapter(action.agent);
+      const current = this.running;
+      if (current && current.adapter.id === target.id && !action.fresh) return this.closeMenu();
+      this.menu?.update({ notice: `switching to ${target.name}…` });
+      await this.switchTo(target, !!action.fresh);
+    }
+  }
+
+  private async switchTo(target: Adapter, fresh: boolean) {
+    this.switching = true;
+    const prev = this.running;
+    let from: AgentId | undefined;
+    if (prev) {
+      from = prev.adapter.id;
+      prev.timers.forEach(clearInterval);
+      this.running = null;
+      await prev.proc.kill();
+      await this.sync(prev);
+      this.ledger.addEvent({ kind: "note", agent: from, detail: "stopped for switch", diffStat: await diffStat(this.cwd) });
+    }
+    this.menu?.close(false);
+    this.menu = null;
+    out(RESET_SEQ + CLEAR_SEQ + `codemax: handing off to ${target.name}…\r\n`);
+    const fromQ = from ? this.quota.get(from) : undefined;
+    const reason = fromQ && isExhausted(fromQ) ? (fromQ.source === "output" ? `${from} appeared to hit its usage limit` : `${from} ran out of quota`) : undefined;
+    await this.launch(target, { fresh, from, reason });
+    this.switching = false;
+  }
+
+  private async quit() {
+    this.switching = true;
+    const run = this.running;
+    this.menu?.close(false);
+    this.menu = null;
+    if (run) {
+      run.timers.forEach(clearInterval);
+      this.running = null;
+      await run.proc.kill();
+      await this.sync(run);
+      this.ledger.addEvent({ kind: "exit", agent: run.adapter.id, detail: "codemax quit", diffStat: await diffStat(this.cwd) });
+    }
+    this.teardownHost();
+    out(`codemax: bye. ledger at ${this.ledger.dir}\n`);
+    this.resolveDone();
+  }
+}
+
+const ALT_RE = /\x1b\[\?(?:1049|1047|47)([hl])/g;
+function trackAltScreen(run: Running, text: string) {
+  let m: RegExpExecArray | null;
+  while ((m = ALT_RE.exec(text))) run.altScreen = m[1] === "h";
+}

package/src/core/paths.ts

@@ -0,0 +1,30 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { realpathSync, mkdirSync, existsSync } from "node:fs";
+
+export const HOME = homedir();
+export const CODEMAX_HOME = process.env.CODEMAX_HOME ?? join(HOME, ".codemax");
+
+/** Claude Code's project-dir rule: every non-alphanumeric char becomes '-'. */
+export function escapeCwd(cwd: string): string {
+  return cwd.replace(/[^a-zA-Z0-9]/g, "-");
+}
+
+export function canonicalCwd(cwd: string = process.cwd()): string {
+  try {
+    return realpathSync(cwd);
+  } catch {
+    return cwd;
+  }
+}
+
+export function projectDir(cwd: string): string {
+  const dir = join(CODEMAX_HOME, "projects", escapeCwd(cwd));
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+export function ensureDir(dir: string): string {
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  return dir;
+}

package/src/core/prices-live.ts

@@ -0,0 +1,123 @@
+import { join } from "node:path";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { CODEMAX_HOME, ensureDir } from "./paths.ts";
+import type { Price } from "./pricing.ts";
+
+export interface LivePrices {
+  fetchedAt: number;
+  source: "openrouter" | "litellm";
+  /** Keyed by normalized model id: lowercase, provider prefix and :suffix removed, dots as dashes. */
+  prices: Record<string, Price>;
+}
+
+export const LIVE_PRICES_PATH = join(CODEMAX_HOME, "prices-live.json");
+const OPENROUTER = "https://openrouter.ai/api/v1/models";
+const LITELLM = "https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json";
+const MAX_AGE_MS = 7 * 86_400_000;
+
+/** "anthropic/claude-opus-5.5:batch" → "claude-opus-5-5"; "xai/grok-4.7" → "grok-4-7". */
+export function normalizeModelId(id: string): string {
+  let s = id.toLowerCase().trim();
+  s = s.replace(/:(batch|free|extended|thinking|online)$/, "");
+  s = s.replace(/^(global\.|us\.|eu\.|apac\.)/, "");
+  s = s.replace(/^[a-z0-9_-]+[\/.](?=[a-z])/, ""); // provider prefix: "anthropic/", "anthropic.", "azure/us/" (loop below)
+  while (/^(us|eu|global|apac)\//.test(s)) s = s.replace(/^[a-z]+\//, "");
+  return s.replace(/\./g, "-");
+}
+
+const perM = (perToken: unknown): number | undefined => {
+  const n = Number(perToken);
+  return Number.isFinite(n) ? Math.round(n * 1e6 * 1e6) / 1e6 : undefined;
+};
+
+export function parseOpenRouter(json: any): Record<string, Price> {
+  const out: Record<string, Price> = {};
+  for (const m of json?.data ?? []) {
+    const p = m.pricing ?? {};
+    const input = perM(p.prompt);
+    const output = perM(p.completion);
+    if (input === undefined || output === undefined) continue;
+    const key = normalizeModelId(String(m.id));
+    if (out[key] && /:batch|:free/.test(String(m.id))) continue; // keep the standard variant
+    out[key] = {
+      input,
+      output,
+      cacheRead: p.input_cache_read ? perM(p.input_cache_read) : undefined,
+      cacheWrite: p.input_cache_write ? perM(p.input_cache_write) : undefined,
+    };
+  }
+  return out;
+}
+
+export function parseLiteLlm(json: any): Record<string, Price> {
+  const out: Record<string, Price> = {};
+  for (const [id, v] of Object.entries<any>(json ?? {})) {
+    if (id === "sample_spec" || typeof v?.input_cost_per_token !== "number" || typeof v?.output_cost_per_token !== "number") continue;
+    if (/^(azure|bedrock|vertex|databricks|perplexity|openrouter|fireworks|together)/.test(id)) continue; // partner-priced variants
+    const key = normalizeModelId(id);
+    if (out[key]) continue;
+    out[key] = {
+      input: perM(v.input_cost_per_token)!,
+      output: perM(v.output_cost_per_token)!,
+      cacheRead: typeof v.cache_read_input_token_cost === "number" ? perM(v.cache_read_input_token_cost) : undefined,
+      cacheWrite: typeof v.cache_creation_input_token_cost === "number" ? perM(v.cache_creation_input_token_cost) : undefined,
+    };
+  }
+  return out;
+}
+
+export function loadLivePrices(): LivePrices | null {
+  if (!existsSync(LIVE_PRICES_PATH)) return null;
+  try {
+    const j = JSON.parse(readFileSync(LIVE_PRICES_PATH, "utf8"));
+    return j && typeof j.fetchedAt === "number" && j.prices ? (j as LivePrices) : null;
+  } catch {
+    return null;
+  }
+}
+
+export function livePricesStale(l: LivePrices | null, now = Date.now()): boolean {
+  return !l || now - l.fetchedAt > MAX_AGE_MS;
+}
+
+/** Download the current list (OpenRouter, then LiteLLM) and cache it. Returns null when offline. */
+export async function fetchLivePrices(timeoutMs = 8000): Promise<LivePrices | null> {
+  const get = async (url: string) => {
+    const ctl = new AbortController();
+    const t = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+      const r = await fetch(url, { signal: ctl.signal, headers: { "user-agent": "codemax-cli" } });
+      if (!r.ok) throw new Error(`HTTP ${r.status}`);
+      return await r.json();
+    } finally {
+      clearTimeout(t);
+    }
+  };
+  let result: LivePrices | null = null;
+  try {
+    const prices = parseOpenRouter(await get(OPENROUTER));
+    if (Object.keys(prices).length > 50) result = { fetchedAt: Date.now(), source: "openrouter", prices };
+  } catch {
+    /* try the next source */
+  }
+  if (!result) {
+    try {
+      const prices = parseLiteLlm(await get(LITELLM));
+      if (Object.keys(prices).length > 50) result = { fetchedAt: Date.now(), source: "litellm", prices };
+    } catch {
+      /* offline */
+    }
+  }
+  if (result) {
+    ensureDir(CODEMAX_HOME);
+    writeFileSync(LIVE_PRICES_PATH, JSON.stringify(result));
+  }
+  return result;
+}
+
+/** Refresh in the background when the cache is older than a week. Never throws. */
+export async function refreshLivePricesIfStale(): Promise<LivePrices | null> {
+  const cur = loadLivePrices();
+  if (!livePricesStale(cur)) return cur;
+  return (await fetchLivePrices().catch(() => null)) ?? cur;
+}

package/src/core/pricing.ts

@@ -0,0 +1,162 @@
+import { join } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { CODEMAX_HOME } from "./paths.ts";
+import { loadLivePrices, normalizeModelId, type LivePrices } from "./prices-live.ts";
+
+/** USD per million tokens. cacheWrite defaults to 1.25 × input when omitted. */
+export interface Price {
+  input: number;
+  output: number;
+  cacheRead?: number;
+  cacheWrite?: number;
+}
+
+/**
+ * List prices (USD per 1M tokens) as published on 2026-10-18. Matched by the
+ * first entry whose key is a substring of the model id, so order matters
+ * (more specific first). Override or extend in ~/.codemax/prices.json.
+ */
+export const DEFAULT_PRICES: [string, Price][] = [
+  // Anthropic
+  ["claude-fable-5-1", { input: 10, output: 50, cacheRead: 0.25 }],
+  ["claude-fable-5", { input: 10, output: 50, cacheRead: 1.0 }],
+  ["claude-mythos", { input: 10, output: 50, cacheRead: 0.25 }],
+  ["claude-opus-5-5", { input: 4, output: 20, cacheRead: 0.2 }],
+  ["claude-opus-5", { input: 5, output: 25, cacheRead: 0.5 }],
+  ["claude-opus-4", { input: 5, output: 25, cacheRead: 0.5 }],
+  ["claude-sonnet-5-5", { input: 2, output: 10, cacheRead: 0.2 }],
+  ["claude-sonnet-5", { input: 2, output: 10, cacheRead: 0.2 }],
+  ["claude-sonnet-4-6", { input: 3, output: 15, cacheRead: 0.3 }],
+  ["claude-sonnet-4", { input: 3, output: 15, cacheRead: 0.3 }],
+  ["claude-haiku-5-5", { input: 0.1, output: 0.5, cacheRead: 0.01 }],
+  ["claude-haiku-4-5", { input: 1, output: 5, cacheRead: 0.1 }],
+  ["claude-haiku", { input: 1, output: 5, cacheRead: 0.1 }],
+  ["fable", { input: 10, output: 50, cacheRead: 0.25 }],
+  ["opus", { input: 4, output: 20, cacheRead: 0.2 }],
+  ["sonnet", { input: 2, output: 10, cacheRead: 0.2 }],
+  ["haiku", { input: 0.1, output: 0.5, cacheRead: 0.01 }],
+  // OpenAI
+  ["gpt-6.1-sol", { input: 10, output: 50, cacheRead: 0.5 }],
+  ["gpt-6-astra", { input: 10, output: 50, cacheRead: 1.0 }],
+  ["gpt-5.6-sol", { input: 4, output: 20, cacheRead: 0.4 }],
+  ["gpt-5.6-terra", { input: 2, output: 12, cacheRead: 0.2 }],
+  ["gpt-5.6-luna", { input: 0.2, output: 1.2, cacheRead: 0.02 }],
+  ["gpt-5.5-pro", { input: 30, output: 180 }],
+  ["gpt-5.5", { input: 5, output: 30, cacheRead: 0.5 }],
+  ["gpt-5.4-mini", { input: 0.75, output: 4.5, cacheRead: 0.075 }],
+  ["gpt-5.4", { input: 2.5, output: 15, cacheRead: 0.25 }],
+  ["gpt-5", { input: 2, output: 12, cacheRead: 0.2 }],
+  // xAI
+  ["grok-4.7", { input: 2, output: 6, cacheRead: 0.5 }],
+  ["grok-4.6", { input: 2, output: 6, cacheRead: 0.5 }],
+  ["grok-4.5", { input: 2, output: 6, cacheRead: 0.5 }],
+  ["grok-4.20", { input: 1.25, output: 2.5, cacheRead: 0.2 }],
+  ["grok-4.3", { input: 1.25, output: 2.5, cacheRead: 0.2 }],
+  ["grok", { input: 2, output: 6, cacheRead: 0.5 }],
+  // Google
+  ["gemini-3", { input: 2, output: 12, cacheRead: 0.2 }],
+  ["gemini-2.5-pro", { input: 1.25, output: 10, cacheRead: 0.31 }],
+  ["gemini-2.5-flash", { input: 0.3, output: 2.5, cacheRead: 0.03 }],
+  ["gemini", { input: 1.25, output: 10, cacheRead: 0.31 }],
+  // OpenCode's bundled free models
+  ["big-pickle", { input: 0, output: 0, cacheRead: 0 }],
+  ["opencode/", { input: 0, output: 0, cacheRead: 0 }],
+];
+
+let cached: [string, Price][] | null = null;
+let userCached: [string, Price][] | null = null;
+let liveCached: LivePrices | null | undefined;
+
+/** Forget cached tables (after `codemax prices update` or in tests). */
+export function resetPriceCache() {
+  cached = null;
+  userCached = null;
+  liveCached = undefined;
+}
+
+function userPrices(): [string, Price][] {
+  if (userCached) return userCached;
+  const user: [string, Price][] = [];
+  const p = join(CODEMAX_HOME, "prices.json");
+  if (existsSync(p)) {
+    try {
+      const j = JSON.parse(readFileSync(p, "utf8")) as Record<string, Price>;
+      for (const [k, v] of Object.entries(j)) if (typeof v?.input === "number" && typeof v?.output === "number") user.push([k.toLowerCase(), v]);
+    } catch {
+      /* ignore malformed overrides */
+    }
+  }
+  userCached = user;
+  return user;
+}
+
+function live(): LivePrices | null {
+  if (liveCached === undefined) liveCached = loadLivePrices();
+  return liveCached;
+}
+
+/** Built-in table with the user's ~/.codemax/prices.json entries placed first (no live data). */
+export function priceTable(): [string, Price][] {
+  if (cached) return cached;
+  cached = [...userPrices(), ...DEFAULT_PRICES];
+  return cached;
+}
+
+export type PriceSource = "user" | "openrouter" | "litellm" | "builtin";
+
+/**
+ * Resolve a price: user overrides first, then the downloaded list (exact id,
+ * then the longest id contained in the model name), then the built-in table.
+ */
+export function priceFor(model: string | undefined): { key: string; price: Price; source: PriceSource } | null {
+  if (!model) return null;
+  const m = model.toLowerCase();
+  for (const [key, price] of userPrices()) if (m.includes(key)) return { key, price, source: "user" };
+  const l = live();
+  if (l) {
+    const norm = normalizeModelId(m);
+    if (l.prices[norm]) return { key: norm, price: l.prices[norm]!, source: l.source };
+    let best: string | null = null;
+    for (const k of Object.keys(l.prices)) if (k.length >= 6 && norm.includes(k) && (!best || k.length > best.length)) best = k;
+    if (best) return { key: best, price: l.prices[best]!, source: l.source };
+  }
+  for (const [key, price] of DEFAULT_PRICES) if (m.includes(key)) return { key, price, source: "builtin" };
+  return null;
+}
+
+/** Human description of where prices come from, for /usage and `codemax prices`. */
+export function priceProvenance(): { source: PriceSource; asOf: string } {
+  const l = live();
+  if (l) return { source: l.source, asOf: new Date(l.fetchedAt).toISOString().slice(0, 10) };
+  return { source: "builtin", asOf: "2026-10-18" };
+}
+
+export interface TokenCounts {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+}
+
+/** API-equivalent USD for the given tokens, or null when the model is unknown. */
+export function estimateCost(model: string | undefined, t: TokenCounts): number | null {
+  const hit = priceFor(model);
+  if (!hit) return null;
+  const { price } = hit;
+  const cacheRead = price.cacheRead ?? price.input * 0.1;
+  const cacheWrite = price.cacheWrite ?? price.input * 1.25;
+  return (t.input * price.input + t.output * price.output + t.cacheRead * cacheRead + t.cacheWrite * cacheWrite) / 1_000_000;
+}
+
+export function fmtUsd(n: number | null | undefined): string {
+  if (n === null || n === undefined) return "n/a";
+  if (n === 0) return "$0.00";
+  if (n < 0.01) return `$${n.toFixed(4)}`;
+  return `$${n.toFixed(2)}`;
+}
+
+export function fmtTokens(n: number): string {
+  if (n < 1000) return String(n);
+  if (n < 1_000_000) return `${(n / 1000).toFixed(n < 10_000 ? 1 : 0)}k`;
+  return `${(n / 1_000_000).toFixed(2)}M`;
+}