rovecode 0.4.0-beta.2 → 0.4.0

package/src/cli/account-cmd.ts

@@ -0,0 +1,116 @@
+/** `rovecode login` / `rovecode account` / `rovecode logout` — the CLI half of the site account link.
+ *  `login` runs the RFC 8628 device flow (src/account/login.ts) or takes a pasted token; `account` prints
+ *  what is linked; `logout` removes it. */
+
+import { accountPath, clearAccount, loadAccount } from "../account/store.ts";
+
+const DEFAULT_API = "https://www.rovecode.dev";
+
+function readFlag(name: string): string | undefined {
+  const i = process.argv.indexOf(name);
+  const value = i !== -1 ? process.argv[i + 1] : undefined;
+  return value !== undefined && !value.startsWith("-") ? value : undefined;
+}
+
+export async function cmdLogin(): Promise<number> {
+  const { linkWithToken, runDeviceLogin } = await import("../account/login.ts");
+  const apiBase = readFlag("--api") ?? process.env.ROVECODE_AUTH_API ?? DEFAULT_API;
+  const json = process.argv.includes("--json");
+  const manual = readFlag("--token");
+
+  if (manual) {
+    const account = await linkWithToken(apiBase, manual);
+    if (!account) {
+      console.error(`error: ${apiBase}/api/auth/me rejected the token`);
+      return 1;
+    }
+    if (json) console.log(JSON.stringify({ ok: true, email: account.email, apiBase: account.apiBase }, null, 2));
+    else console.log(`linked ${account.email || "an account"} (${account.apiBase}) — stored in ${accountPath()}`);
+    return 0;
+  }
+
+  const result = await runDeviceLogin({
+    apiBase,
+    onCode: ({ userCode, verificationUri, expiresIn }) => {
+      // a script still needs the code to show its human — stdout stays clean for the final result
+      if (json) {
+        console.error(JSON.stringify({ user_code: userCode, verification_uri: verificationUri, expires_in: expiresIn }));
+        return;
+      }
+      console.log("");
+      console.log(`  your code:  ${userCode}`);
+      console.log(`  open:       ${verificationUri}`);
+      console.log(`  expires in about ${Math.max(1, Math.round(expiresIn / 60))} min — waiting for approval…`);
+      console.log("");
+    },
+  });
+
+  if (!result.ok) {
+    const reasons = {
+      denied: "the request was denied on the site",
+      expired: "the code expired before it was approved",
+      invalid: "the device code was rejected — run rovecode login again",
+      network: `could not reach ${apiBase}`,
+    };
+    console.error(`error: ${reasons[result.reason]}`);
+    return 1;
+  }
+  // the site also minted an inference key — turn it into a working provider, zero key-pasting
+  const { ensureRovecodeProvider, ROVECODE_DEFAULT_MODEL } = await import("../account/provision.ts");
+  const provision = result.account.apiKey ? ensureRovecodeProvider(result.account.apiKey) : undefined;
+  if (json) console.log(JSON.stringify({ ok: true, email: result.account.email, apiBase: result.account.apiBase, provisioned: provision ?? null }, null, 2));
+  else {
+    console.log(`linked ${result.account.email || "your account"} — stored in ${accountPath()}`);
+    if (provision && !provision.error) {
+      console.log(`rovecode provider ready (api.rovecode.dev — key stored hidden, ~/.rovecode/credentials.json)`);
+      if (provision.defaulted) console.log(`default model → rovecode/${ROVECODE_DEFAULT_MODEL}`);
+    } else if (provision?.error) {
+      console.error(`note: provider auto-setup failed (${provision.error}) — run: rovecode setup`);
+    }
+  }
+  return 0;
+}
+
+export async function cmdAccount(): Promise<number> {
+  const account = loadAccount();
+  const json = process.argv.includes("--json");
+  if (!account) {
+    if (json) console.log(JSON.stringify({ linked: false }, null, 2));
+    else console.log(`not linked — run: rovecode login   (looked in ${accountPath()})`);
+    return 1;
+  }
+  if (json) {
+    console.log(JSON.stringify({ linked: true, email: account.email, name: account.name, userId: account.userId, apiBase: account.apiBase, linkedAt: account.linkedAt }, null, 2));
+    return 0;
+  }
+  console.log(`linked account: ${account.email || account.userId || "(unknown)"}`);
+  console.log(`api:            ${account.apiBase}`);
+  console.log(`since:          ${account.linkedAt || "(unknown)"}`);
+  console.log(`file:           ${accountPath()}`);
+  return 0;
+}
+
+export async function cmdLogout(): Promise<number> {
+  const account = loadAccount();
+  if (account) {
+    // best effort: tell the API to revoke the token (proof-of-possession signed with this machine's key);
+    // a dead server or an unbound legacy token must not stop the local unlink
+    try {
+      const { loadOrCreateAccountKey, signProof } = await import("../account/keys.ts");
+      const keys = loadOrCreateAccountKey();
+      const url = `${account.apiBase}/api/auth/token/revoke`;
+      await fetch(url, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${account.token}`,
+          dpop: signProof(keys, { htm: "POST", htu: url, iat: Math.floor(Date.now() / 1000), accessToken: account.token }),
+        },
+      });
+    } catch {
+      /* offline unlink is still an unlink */
+    }
+  }
+  const removed = clearAccount();
+  console.log(removed ? `unlinked — removed ${accountPath()}` : "nothing to unlink (no account stored)");
+  return removed ? 0 : 1;
+}

package/src/cli/connect.ts

@@ -0,0 +1,244 @@
+/** `rovecode connect` — one line from "nothing configured" to "a model answers".
+ *
+ *    rovecode connect                                  the step-by-step wizard (cli/setup.ts)
+ *    rovecode connect anthropic                        a built-in: key from the env, else a hidden prompt
+ *    rovecode connect anthropic --model claude-opus-5  pin the model too
+ *    rovecode connect ollama --no-key                  a local server, nothing to store
+ *    rovecode connect myproxy https://host/v1 --key    any OpenAI-compatible or Anthropic URL
+ *    echo $KEY | rovecode connect groq --key-stdin     scripts and CI: no TTY needed
+ *
+ *  It does what `setup` does — register, store the key, pick the model, one tiny real call, persist the
+ *  default — but takes the answers from argv instead of asking, so it fits in a README, a Dockerfile or
+ *  a CI step. `rovecode connect` with no arguments is exactly `rovecode setup`.
+ *
+ *  The secret is never a flag VALUE: `--key` prompts (hidden, TTY), `--key-stdin` reads one line, and
+ *  `--key-env NAME` names an env var to read at call time. A key passed as argv would sit in the shell
+ *  history and in every `ps` listing on the machine, so there is no `--key <value>` form.
+ *
+ *  Every step reads through an injectable seam (secret / stdin / save / probe / out) so the whole flow
+ *  is unit-testable with no network and no terminal.
+ *
+ *  Exit codes: 0 connected · 1 the test call failed (the config IS written — a script should notice) ·
+ *  2 usage error / no key available and no way to ask · 3 CONNECT_WAITING, only when the caller passed
+ *  `deferKey`: the provider is registered and the flow is parked until the key lands (the TUI, which has
+ *  no masked input, arms a watcher and re-enters). Wording: core/voice.ts — short lines, every problem
+ *  ends with "→ next:". */
+
+import { readSecret, saveCredential } from "../providers/auth.ts";
+import { PROVIDER_ID_RE, inferProtocol, isConfigured, type ProviderProtocol, type ProviderSpec, type ResolvedProvider } from "../providers/provider-config.ts";
+import type { FileScope } from "../providers/provider-config.ts";
+import type { ProviderRegistry } from "../providers/registry.ts";
+import { next } from "../core/voice.ts";
+import type { ProbeResult } from "./setup.ts";
+
+/** returned instead of an error when `deferKey` handles the missing key: nothing failed, the flow is parked */
+export const CONNECT_WAITING = 3;
+
+export const CONNECT_USAGE =
+  "usage: rovecode connect [<id> [<baseUrl>]] [--model <id>] [--key | --key-stdin | --key-env NAME | --no-key] [--protocol openai|anthropic] [--project] [--no-test]";
+
+export interface ConnectArgs {
+  id: string;
+  baseUrl?: string;
+  model?: string;
+  protocol?: ProviderProtocol;
+  /** how the key is obtained; "auto" = stored/env if there is one, else prompt when a TTY allows it */
+  key: "auto" | "prompt" | "stdin" | "none";
+  keyEnv?: string;
+  scope: FileScope;
+  test: boolean;
+}
+
+/** argv → ConnectArgs. Pure: no files, no env, no network — the parser is the half worth pinning. */
+export function parseConnectArgs(words: readonly string[]): ConnectArgs | { error: string } {
+  const pos: string[] = [];
+  let model: string | undefined;
+  let protocol: ProviderProtocol | undefined;
+  let keyEnv: string | undefined;
+  let key: ConnectArgs["key"] = "auto";
+  let scope: FileScope = "user";
+  let test = true;
+  const keyFlags: string[] = [];
+
+  for (let i = 0; i < words.length; i++) {
+    const w = words[i]!;
+    const value = (): string | undefined => { const v = words[i + 1]; if (v === undefined || v.startsWith("-")) return undefined; i++; return v; };
+    switch (w) {
+      case "--model": { const v = value(); if (v === undefined) return { error: `--model needs a value — ${CONNECT_USAGE}` }; model = v; break; }
+      case "--key-env": { const v = value(); if (v === undefined) return { error: `--key-env needs a value — ${CONNECT_USAGE}` }; keyEnv = v; keyFlags.push(w); break; }
+      case "--protocol": {
+        const v = value();
+        if (v !== "openai" && v !== "anthropic") return { error: `--protocol takes openai or anthropic — ${CONNECT_USAGE}` };
+        protocol = v; break;
+      }
+      case "--key": key = "prompt"; keyFlags.push(w); break;
+      case "--key-stdin": key = "stdin"; keyFlags.push(w); break;
+      case "--no-key": key = "none"; keyFlags.push(w); break;
+      case "--project": scope = "project"; break;
+      case "--no-test": test = false; break;
+      default:
+        if (w.startsWith("-")) return { error: `unknown flag ${w} — ${CONNECT_USAGE}` };
+        pos.push(w);
+    }
+  }
+
+  // --key-env names an env var to read; --key/--key-stdin store a secret; --no-key stores nothing.
+  // Two of them together is a contradiction, not a precedence puzzle — say so instead of picking one.
+  if (keyFlags.length > 1) return { error: `${keyFlags.join(" and ")} contradict each other — pick one` };
+  if (pos.length === 0) return { error: `connect needs a provider id — ${CONNECT_USAGE}` };
+  if (pos.length > 2) return { error: `unexpected argument "${pos[2]}" — ${CONNECT_USAGE}` };
+
+  const id = pos[0]!.toLowerCase();
+  if (!PROVIDER_ID_RE.test(id)) return { error: `"${id}" won't work as an id (letters, digits, - _ .)` };
+  const baseUrl = pos[1];
+  if (baseUrl !== undefined && !/^https?:\/\//.test(baseUrl)) return { error: `"${baseUrl}" is not an http(s) URL — ${CONNECT_USAGE}` };
+  if (baseUrl === undefined && protocol !== undefined) return { error: "--protocol only applies when you give a base URL" };
+
+  return { id, ...(baseUrl !== undefined ? { baseUrl } : {}), ...(model !== undefined ? { model } : {}),
+           ...(protocol !== undefined ? { protocol } : {}), ...(keyEnv !== undefined ? { keyEnv } : {}), key, scope, test };
+}
+
+export interface ConnectDeps {
+  registry: ProviderRegistry;
+  /** default console.log */
+  out?: (line: string) => void;
+  /** one secret, masked (default: auth.ts readSecret) */
+  secret?: (prompt: string) => Promise<string>;
+  /** one line of piped stdin, for --key-stdin (default: reads process.stdin to end) */
+  stdin?: () => Promise<string>;
+  /** default auth.ts saveCredential */
+  save?: (id: string, secret: string, keyEnv: string) => void;
+  /** default registry.probe — one tiny real call */
+  probe?: (id: string, model?: string) => Promise<ProbeResult>;
+  /** default process.stdin.isTTY === true; a pipe must never be consumed by a prompt */
+  tty?: boolean;
+  /** a surface with no masked input (the TUI): called instead of failing when the key is missing and
+   *  cannot be asked for. It owns the hand-off wording and the waiting; runConnect returns CONNECT_WAITING. */
+  deferKey?: (spec: ResolvedProvider) => void;
+  /** the closing line(s). Default is the CLI's; the TUI passes its own ("tell me what you want done"). */
+  done?: string;
+  /** which surface the "→ next:" steps are spelled for — `rovecode provider test` on a shell,
+   *  `/provider test` in the TUI (core/voice.ts noModelHint uses the same distinction) */
+  where?: "cli" | "tui";
+}
+
+async function readAllStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const c of process.stdin) chunks.push(c as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+export async function runConnect(args: ConnectArgs, deps: ConnectDeps): Promise<number> {
+  const out = deps.out ?? console.log;
+  const secret = deps.secret ?? ((p: string) => readSecret(p));
+  const stdin = deps.stdin ?? readAllStdin;
+  const save = deps.save ?? saveCredential;
+  const reg = deps.registry;
+  const probe = deps.probe ?? ((id: string, model?: string) => reg.probe(id, model));
+  const tty = deps.tty ?? process.stdin.isTTY === true;
+  const tui = deps.where === "tui";
+
+  // ---- 1. the provider ----
+  // A base URL registers (or re-registers) the endpoint. Without one the id must already be known —
+  // built-in or previously added — and --no-key/--key-env/--model still write a user entry over it,
+  // which is how a built-in row becomes a local keyless server (setup.ts does the same thing).
+  const existing = reg.get(args.id);
+  const patching = args.key === "none" || args.keyEnv !== undefined;
+  if (args.baseUrl !== undefined || patching) {
+    const baseUrl = args.baseUrl ?? existing?.baseUrl;
+    if (baseUrl === undefined) {
+      out(`◆ I don't know a provider called "${args.id}".`);
+      out(`  known: ${reg.ids().join(" ")}`);
+      out(`  ${next(`rovecode connect ${args.id} <baseUrl>`)} to register your own endpoint`);
+      return 2;
+    }
+    const protocol = args.protocol ?? existing?.protocol ?? inferProtocol(baseUrl);
+    const defaultModel = args.model ?? existing?.defaultModel;
+    const spec: ProviderSpec = {
+      id: args.id, baseUrl, protocol,
+      ...(args.keyEnv !== undefined ? { keyEnv: args.keyEnv } : existing?.keyEnv !== undefined && args.baseUrl === undefined ? { keyEnv: existing.keyEnv } : {}),
+      ...(defaultModel !== undefined ? { defaultModel } : {}),
+      ...(args.key === "none" ? { noKey: true } : {}),
+    };
+    const r = reg.add(spec, args.scope);
+    if ("error" in r) { out(`◆ ${r.error}`); out(`  ${next("rovecode connect")} for the step-by-step version`); return 2; }
+    out(`◆ ${r.id} registered (${r.protocol} protocol, ${r.baseUrl}${args.key === "none" ? ", no key" : ""}).`);
+  } else if (existing === undefined) {
+    out(`◆ I don't know a provider called "${args.id}".`);
+    out(`  known: ${reg.ids().join(" ")}`);
+    out(`  ${next(`rovecode connect ${args.id} <baseUrl>`)} to register your own endpoint`);
+    return 2;
+  }
+
+  const spec = reg.get(args.id);
+  if (spec === undefined) { out(`◆ ${args.id} did not survive registration — that is a bug.`); return 2; }
+
+  // ---- 2. the key ----
+  let hasKey = isConfigured(spec);
+  if (!hasKey || args.key === "prompt" || args.key === "stdin") {
+    if (args.key === "stdin") {
+      const s = (await stdin()).split("\n")[0]!.trim();
+      if (s.length === 0) { out(`◆ nothing came in on stdin — no key stored.`); out(`  ${next(`echo $KEY | rovecode connect ${args.id} --key-stdin`)}`); return 2; }
+      save(args.id, s, spec.keyEnv);
+      out(`◆ key stored for ${args.id} (hidden; ~/.rovecode/credentials.json).`);
+      hasKey = true;
+    } else if (args.key === "prompt" || (args.key === "auto" && tty)) {
+      const s = (await secret(`${spec.keyEnv} (hidden): `)).trim();
+      if (s.length === 0) {
+        out(`◆ no key stored — I can't call ${args.id} without one.`);
+        out(`  ${next(`rovecode auth set ${args.id}`)}   (or set ${spec.keyEnv} in your environment)`);
+        return 2;
+      }
+      save(args.id, s, spec.keyEnv);
+      out(`◆ key stored for ${args.id} (hidden; ~/.rovecode/credentials.json).`);
+      hasKey = true;
+    } else if (deps.deferKey !== undefined) {
+      // a surface that cannot prompt (the TUI) takes over: it says how to hand the key over and
+      // finishes this same call once the key lands
+      deps.deferKey(spec);
+      return CONNECT_WAITING;
+    } else {
+      // no key anywhere and no terminal to ask on: a pipe must not be consumed by a prompt
+      out(`◆ ${args.id} has no key, and there is no terminal to ask on.`);
+      out(`  ${next(`set ${spec.keyEnv}, or pipe it: echo $KEY | rovecode connect ${args.id} --key-stdin`)}`);
+      return 2;
+    }
+  } else {
+    out(spec.noKey === true
+      ? `◆ ${args.id} needs no key (local server).`
+      : `◆ ${args.id} already has a key (${spec.keySource === "stored" ? "stored" : `env ${spec.keyEnv}`}).`);
+  }
+  reg.refresh();
+
+  // ---- 3. the model ----
+  const model = args.model ?? reg.get(args.id)?.defaultModel;
+  if (model === undefined) {
+    out(`◆ ${args.id} is connected but has no model yet.`);
+    out(`  ${next(tui ? `/models ${args.id}, then /model ${args.id}/<model> --save` : `rovecode model list ${args.id}, then rovecode model use ${args.id}/<model>`)}`);
+    return 0;
+  }
+
+  // ---- 4. one tiny real call ----
+  let ok = true;
+  if (args.test) {
+    out(`◆ testing ${args.id}/${model} …`);
+    const r = await probe(args.id, model);
+    ok = r.ok;
+    out(`  ${r.detail}`);
+  }
+
+  // ---- 5. the default ----
+  // written even when the probe failed: the config is what the user asked for, and `provider test`
+  // is one command away. The exit code carries the failure instead.
+  const d = reg.setDefault(`${args.id}/${model}`, args.scope);
+  if ("error" in d) { out(`◆ ${d.error}`); out(`  ${next(`rovecode model use ${args.id}/<model>`)}`); return 2; }
+  out(`◆ default → ${d.provider}/${d.model} (${tui ? "this session switched too" : "running TUIs switch live"}).`);
+
+  if (!ok) {
+    out(`  ${next(`check the key and the URL, then ${tui ? "/provider" : "rovecode provider"} test ${args.id} ${model}`)}`);
+    return 1;
+  }
+  out("");
+  out(deps.done ?? 'Done. Try:  rovecode "explain this repo"\n  or open the cockpit:  rovecode');
+  return 0;
+}

package/src/cli/context-cmd.ts

@@ -0,0 +1,199 @@
+/** `rovecode context [session-id]` — what is in the window right now, item by item, and how far our
+ *  arithmetic is from the provider's own count.
+ *
+ *  Reads a saved session from `<cwd>/.rovecode/sessions` (the newest one unless an id is given) and
+ *  prints the breakdown core/context-report.ts computes. The interesting line is `drift`: the estimate
+ *  is o200k, which is exact for OpenAI models and an approximation everywhere else, so the honest thing
+ *  is to print the provider's own number beside ours whenever a turn reported one — and to say plainly
+ *  when the two disagree by more than a twentieth, because compaction fires on the estimate.
+ *
+ *  Offline: the catalog is the bundled snapshot plus rovecode's own table, no fetch. `--json` prints the
+ *  report verbatim for scripts; `--no-runtime` skips building the runtime, and with it the system-prompt
+ *  and tool-schema rows, for a project whose config does not load. */
+
+import { join } from "node:path";
+import { listSessions, SessionStore } from "../core/session.ts";
+import { contextReport, DRIFT_TOLERANCE, type ContextReport } from "../core/context-report.ts";
+import { ModelCatalog } from "../providers/catalog.ts";
+
+export interface ContextCliDeps {
+  cwd?: string;
+  /** overridden in tests; production reads the default model from the provider registry */
+  currentRef?: () => { provider: string; model: string } | null;
+  log?: (line: string) => void;
+  err?: (line: string) => void;
+}
+
+const bar = (fraction: number, width = 24): string => {
+  const filled = Math.max(0, Math.min(width, Math.round(fraction * width)));
+  return "█".repeat(filled) + "·".repeat(width - filled);
+};
+
+const n = (v: number): string => v.toLocaleString("en-US");
+const pct = (v: number): string => `${(v * 100).toFixed(1)}%`;
+
+export function renderContext(r: ContextReport, sessionId: string): string[] {
+  const out: string[] = [];
+  out.push(`session ${sessionId} · ${r.model.provider}/${r.model.model}`);
+  out.push("");
+  if (r.window) {
+    out.push(`context  ${bar(r.fraction ?? 0)}  ~${n(r.corrected)} of ${n(r.window)} (${pct(r.fraction ?? 0)})`);
+    out.push(`         ${n(r.remaining ?? 0)} left${r.nearLimit ? " — near the limit, compaction is due" : ""}`);
+  } else {
+    out.push(`context  ~${n(r.corrected)} tokens — this model's window is not in the catalog`);
+  }
+  // never correct a number silently: say the raw estimate, the factor, and where the factor is from
+  if (r.scale.factor !== 1) {
+    out.push(`         o200k counted ${n(r.estimated)}, scaled by ${r.scale.factor}× — ${r.scale.note}`);
+  } else if (!r.scale.measured) {
+    out.push(`         ${r.scale.note}`);
+  }
+  out.push("");
+  const width = Math.max(...r.slices.map((s) => s.label.length), 10);
+  for (const s of r.slices) {
+    out.push(`  ${s.label.padEnd(width)}  ${n(s.tokens).padStart(9)}  ${pct(s.share).padStart(6)}${s.note ? `  — ${s.note}` : ""}`);
+  }
+  if (r.images > 0) out.push(`  ${"images".padEnd(width)}  ${String(r.images).padStart(9)}         — not estimated; image tokens are provider-specific`);
+  out.push("");
+  if (r.drift) {
+    const d = r.drift;
+    const dir = d.delta > 0 ? "more than we estimate" : "less than we estimate";
+    out.push(`drift    provider counted ${n(d.reported)} for the last turn's prompt, we estimated ${n(d.estimated)}`);
+    out.push(`         ${n(Math.abs(d.delta))} ${dir} (${pct(d.fraction)})${d.beyondTolerance ? ` — beyond the ${pct(DRIFT_TOLERANCE)} tolerance; the meter above reads ${d.delta > 0 ? "low" : "high"} for this model` : ""}`);
+  } else {
+    out.push("drift    no turn reported usage yet — nothing to compare the estimate against");
+  }
+  out.push("");
+  const t = r.totals;
+  out.push(`billed   ${n(t.input)} in · ${n(t.output)} out · ${n(t.cacheRead)} cache read · ${n(t.cacheWrite)} cache written`);
+  // three different silences, and saying the wrong one is a lie about the catalog: nothing has been
+  // billed yet, versus the catalog not pricing this model, versus a partly priced transcript.
+  const billedAnything = t.input + t.output + t.cacheRead + t.cacheWrite > 0;
+  out.push(
+    r.costUsd !== undefined
+      ? `cost     $${r.costUsd.toFixed(4)}${r.unpricedTurns > 0 ? ` — lower bound, ${r.unpricedTurns} turn${r.unpricedTurns > 1 ? "s" : ""} unpriced` : ""}`
+      : billedAnything
+        ? `cost     unknown — no pricing for ${r.model.provider}/${r.model.model}`
+        : "cost     $0.0000 — nothing has been billed in this session yet",
+  );
+  return out;
+}
+
+/** the `--exact` rows: the provider's own count of this prompt, and how far our meter sits from it.
+ *  A refusal prints the reason on the same row — a count nobody could obtain is not a zero. */
+export function renderExact(e: { inputTokens?: number; reason?: string; placeholder?: boolean }, estimated: number): string[] {
+  if (e.inputTokens === undefined) return ["", `exact    not counted — ${e.reason ?? "no reason given"}`];
+  const delta = estimated - e.inputTokens;
+  const fraction = e.inputTokens > 0 ? Math.abs(delta) / e.inputTokens : 0;
+  const verdict =
+    delta === 0
+      ? "our estimate agrees exactly"
+      : `our estimate reads ${delta > 0 ? "high" : "low"} by ${n(Math.abs(delta))} (${pct(fraction)})${fraction > DRIFT_TOLERANCE ? ` — beyond the ${pct(DRIFT_TOLERANCE)} tolerance` : ""}`;
+  const rows = ["", `exact    the provider counted ${n(e.inputTokens)} for this prompt`, `         ${verdict}`];
+  if (e.placeholder) rows.push("         this session has no turns yet — the count includes a one-character placeholder message, which the API requires");
+  return rows;
+}
+
+export async function cmdContext(args: string[], deps: ContextCliDeps = {}): Promise<number> {
+  const log = deps.log ?? ((l: string) => console.log(l));
+  const err = deps.err ?? ((l: string) => console.error(l));
+  const cwd = deps.cwd ?? process.cwd();
+  const json = args.includes("--json");
+  const id = args.find((a) => !a.startsWith("-"));
+
+  // --json is one document on stdout on every exit, the failing ones included — a script that asked for the
+  // report gets `{error}` it can read, not an empty stdout and a 1 (the market commands keep the same rule)
+  const fail = (msg: string): 1 => { err(msg); if (json) log(JSON.stringify({ error: msg })); return 1; };
+
+  const sessionsDir = join(cwd, ".rovecode", "sessions");
+  const sessions = listSessions(sessionsDir);
+  const chosen = id ?? sessions[0]?.id;
+  if (!chosen) return fail("no sessions here — run rovecode in this directory first");
+  if (id && !sessions.some((s) => s.id === id)) return fail(`no session ${id} here — rovecode context lists the newest by default`);
+
+  const messages = new SessionStore(sessionsDir, chosen).messages();
+  const ref = deps.currentRef
+    ? deps.currentRef()
+    : await (async () => {
+        const { ProviderRegistry } = await import("../providers/registry.ts");
+        return new ProviderRegistry(cwd).defaultRef() ?? null;
+      })();
+  if (!ref) return fail("no default model — rovecode model use <provider/model>");
+
+  // The system prompt and the tool schemas are the two rows a transcript cannot tell us, and they are
+  // the largest fixed cost of every turn — so the command builds the same runtime a real run would and
+  // asks it, unless --no-runtime says not to (a broken project config should not stop a token count).
+  // MCP tools are deliberately absent: their schemas exist only after connecting to a server, and
+  // starting other people's processes to print a number is not a trade this command should make.
+  let fixed: { system?: string; toolSchemas?: string; schemas?: unknown[]; note?: string } = {};
+  if (!args.includes("--no-runtime")) {
+    try {
+      const { createRuntime } = await import("./runtime.ts");
+      // sessionId: the one we are reporting on. Without it the runtime opens a NEW session directory,
+      // so merely asking "what is in the window" would leave an empty session behind — and the next
+      // `rovecode context` would report that empty one instead.
+      const rt = createRuntime({ cwd, stream: null, sessionId: chosen });
+      const schemas = rt.registry.list().map((t) => t.schema);
+      // buildDef, not systemPrompt(): the prompt a run actually sends is the base plus the model
+      // profile, the design section and — for a model without native tool calling — the tool block.
+      // Asking for the base alone under-counts the row by everything that makes it big.
+      const def = rt.buildDef({ ...ref, effort: "auto" });
+      const system = typeof def.systemPrompt === "string" ? def.systemPrompt : def.systemPrompt({});
+      fixed = { system, toolSchemas: JSON.stringify(schemas), schemas };
+      await rt.mcp?.close().catch(() => {});
+    } catch (e) {
+      fixed = { note: `the system prompt and tool schemas are not counted — this project's runtime did not build (${e instanceof Error ? e.message : String(e)})` };
+    }
+  }
+
+  const catalog = new ModelCatalog();
+  const report = contextReport({
+    messages,
+    current: ref,
+    ...(fixed.system !== undefined ? { system: fixed.system } : {}),
+    ...(fixed.toolSchemas !== undefined ? { toolSchemas: fixed.toolSchemas } : {}),
+    lookup: (r) => {
+      const info = catalog.lookup(r.provider, r.model);
+      if (!info) return undefined;
+      return {
+        ...(info.contextWindow !== undefined ? { contextWindow: info.contextWindow } : {}),
+        ...(info.pricing ? { pricing: info.pricing } : {}),
+        // the tier travels with the pricing or the report bills a 250k-token xAI turn at half rate
+        ...(info.tier ? { tier: info.tier } : {}),
+      };
+    },
+  });
+
+  // --exact: stop estimating and ask the provider. Anthropic counts the same body a request would carry
+  // and returns the number the window and the bill are computed from; o200k is only our stand-in for it.
+  let exact: { inputTokens?: number; reason?: string; endpoint?: string; placeholder?: true } | undefined;
+  if (args.includes("--exact")) {
+    const { countPromptRemotely } = await import("../core/count-remote.ts");
+    const { ProviderRegistry } = await import("../providers/registry.ts");
+    const p = new ProviderRegistry(cwd).get(ref.provider);
+    if (!p) exact = { reason: `provider "${ref.provider}" is not configured here` };
+    else {
+      const r = await countPromptRemotely({
+        provider: { baseUrl: p.baseUrl, protocol: p.protocol, ...(p.apiKey ? { apiKey: p.apiKey } : {}), ...(p.headers ? { headers: p.headers } : {}) },
+        model: ref.model,
+        messages,
+        ...(fixed.system !== undefined ? { system: fixed.system } : {}),
+        // the same schemas the estimate counted; without them the two numbers would describe
+        // different prompts and the comparison below would be meaningless
+        ...(fixed.schemas ? { tools: fixed.schemas } : {}),
+      });
+      exact = r.ok
+        ? { inputTokens: r.inputTokens, endpoint: r.endpoint, ...(r.placeholder ? { placeholder: true as const } : {}) }
+        : { reason: r.reason };
+    }
+  }
+
+  if (json) log(JSON.stringify({ session: chosen, ...report, ...(exact ? { exact } : {}), ...(fixed.note ? { note: fixed.note } : {}) }, null, 2));
+  else {
+    for (const line of renderContext(report, chosen)) log(line);
+    if (exact) for (const line of renderExact(exact, report.estimated)) log(line);
+    if (fixed.note) log(`note     ${fixed.note}`);
+    else if (fixed.system !== undefined) log("note     MCP tools are not counted — their schemas exist only once a server is connected");
+  }
+  return 0;
+}