rovecode 0.3.2

package/src/tui/providers-cmd.ts

@@ -0,0 +1,377 @@
+/** /model · /models · /provider — the TUI's provider surface over the runtime's LIVE registry
+ *  (providers/registry.ts). Nothing here rebuilds the runtime: the registry's dispatching stream
+ *  resolves model.provider per call, so a provider added or a key stored in this session serves the
+ *  very next prompt. Kept out of app.ts (ADR-002 cap) like info-cmd.ts / session-cmd.ts.
+ *
+ *  Secrets: `/provider key <id> <secret>` stores through auth.ts saveCredential and echoes only the
+ *  redacted prefix; slash commands never reach the agent or the session store, so the key is not in
+ *  the transcript. Prefer `--key-env NAME` or `rovecode auth set <id>` (masked prompt) when possible. */
+
+import type { Runtime } from "../cli/runtime.ts";
+import type { ModeManager } from "../core/modes.ts";
+import type { ModelRef } from "../core/types.ts";
+import type { Renderer } from "./renderer.ts";
+import { redactSecret, saveCredential } from "../providers/auth.ts";
+import { isConfigured } from "../providers/provider-config.ts";
+import { ADD_USAGE, formatProviderList, parseAddArgs } from "../providers/registry.ts";
+import { PROVIDER_ID_RE } from "../providers/provider-config.ts";
+import type { PickItem } from "./renderer.ts";
+import { SETUP_PICKS } from "../cli/setup.ts";
+import { CONNECT_WAITING, parseConnectArgs, runConnect } from "../cli/connect.ts";
+import { next } from "../core/voice.ts";
+import { ModelCatalog } from "../providers/catalog.ts"; // port #60: enrich existing picker rows
+import { describeModel } from "../providers/model-list.ts"; // port #60
+
+export interface ProviderCmdCtx {
+  rt: Runtime;
+  modes: ModeManager;
+  state: { provider: string; model: string };
+  renderer: Renderer;
+  pushStatus: () => void;
+  catalog?: Pick<ModelCatalog, "lookup">; // port #60: reuse the app's /cost catalog (offline fallback for other callers)
+}
+
+type NoteLevel = Parameters<Renderer["addSystemNote"]>[1];
+
+export const MODEL_COMMAND = { name: "model", description: "Switch the model I use: /model <provider/model | model> [--save]", group: "model & provider" };
+
+/** every `provider/model` id the configured providers list — the `/model` suggestions in the sextant. A
+ *  provider that errors or lists nothing drops out silently here; `/models` is where the reasons show. */
+export async function listModelIds(reg: Pick<Runtime["providers"], "list" | "models">): Promise<string[]> {
+  const ids = reg.list().filter(isConfigured).map((p) => p.id);
+  const results = await Promise.all(ids.map(async (id) => ({ id, r: await reg.models(id) })));
+  return results.flatMap(({ id, r }) => (r.ok ? r.models.map((m) => `${id}/${m}`) : []));
+}
+export const SETUP_COMMAND = { name: "setup", description: "Connect a model step by step: provider, model, key, one test call", group: "start here" };
+export const CONNECT_COMMAND = { name: "connect", description: "Connect a model: /connect (guided, same as /setup) · /connect <id> [<url>] [--model <id>] [--key-env NAME] [--no-key] [--project] [--no-test]", group: "start here" };
+export const PROVIDER_COMMANDS = [
+  { name: "models", description: "Pick a model from a list: /models [provider] [--save]", group: "model & provider" },
+  { name: "provider", description: "Endpoints I can talk to: /provider list · add <id> <url> [--protocol …] [--key-env …] [--model …] [--no-key] [--project] · remove <id> · use <provider/model> · test <id> [model] · key <id> <secret>", group: "model & provider" },
+];
+/** the last line of a finished /setup */
+export const SETUP_DONE_TUI = "Done. Tell me what you want done — try: explain this repo";
+
+/** `/model …` / `/provider use` write the default themselves and report it — the watcher must not
+ *  announce the same change a second time. Set around the write; refresh() fires synchronously. */
+let localWrite = false;
+
+const note = (ctx: ProviderCmdCtx, text: string, level?: NoteLevel): void => { ctx.renderer.addSystemNote(text, level); };
+
+/** the session's model = the current mode's slot (port #20; mirrored to both when planActSeparateModels is off) */
+function applyRef(ctx: ProviderCmdCtx, ref: ModelRef): void {
+  ctx.modes.setModel({ provider: ref.provider, model: ref.model });
+  const cur = ctx.modes.modelFor();
+  ctx.state.model = cur.model;
+  ctx.state.provider = cur.provider;
+  ctx.pushStatus();
+}
+
+/** /model <provider/model | model> [--save] — switch this session; --save also persists it as the default. */
+export function cmdModel(ctx: ProviderCmdCtx, arg: string): void | Promise<void> {
+  const words = arg.split(/\s+/).filter((w) => w.length > 0);
+  const save = words.includes("--save");
+  const sel = words.filter((w) => w !== "--save").join(" ");
+  if (sel.length === 0) return cmdModels(ctx, save ? "--save" : ""); // port #60: bare /model uses the existing picker
+  const ref = ctx.rt.providers.resolveSelector(sel, ctx.state.provider);
+  if ("error" in ref) { note(ctx, `${ref.error} — add one with /provider add <id> <baseUrl>`, "warn"); return; }
+  const switchedProvider = ref.provider !== ctx.state.provider;
+  applyRef(ctx, ref);
+  let saved = "";
+  if (save) {
+    localWrite = true;
+    try {
+      const r = ctx.rt.providers.setDefault(`${ref.provider}/${ref.model}`);
+      saved = "error" in r ? ` (not saved: ${r.error})` : " (saved as default)";
+    } finally { localWrite = false; }
+  }
+  const p = ctx.rt.providers.get(ref.provider);
+  const keyNote = p !== undefined && !isConfigured(p) ? `\n${ctx.rt.providers.keyHint(p)}` : "";
+  // same provider → the bare model id (the historical `/model <id>` note); a provider switch names both
+  note(ctx, `model → ${switchedProvider ? `${ref.provider}/` : ""}${ref.model}${saved}${ctx.modes.separate ? ` (${ctx.modes.mode} mode)` : ""}${keyNote}`, keyNote.length > 0 ? "warn" : undefined);
+}
+
+/** /models [provider] — ids from providers.json `models` or the endpoint's /models. */
+/** /models [provider] [--all] [--save] — PICK a model, do not read a wall of ids.
+ *
+ *  It used to print up to 60 rows as a note and leave you to retype one into `/model <id>`. The ids
+ *  are long and often differ by a date suffix, so retyping is where the mistakes were. Now the same
+ *  list opens in the picker the setup flow already uses: arrow, Enter, done — and Enter applies it
+ *  to this session immediately.
+ *
+ *  Bare, it lists every CONFIGURED provider's models, so switching vendor is the same gesture as
+ *  switching model; naming a provider narrows it to that one (and reaches an unconfigured one, which
+ *  is how you look before you commit). `--save` also persists the pick as the default.
+ *
+ *  Fetching is per provider and concurrent — a provider whose endpoint is down or keyless reports
+ *  itself as one row instead of failing the whole list. */
+export async function cmdModels(ctx: ProviderCmdCtx, arg: string): Promise<void> {
+  const words = arg.split(/\s+/).filter((w) => w.length > 0);
+  const save = words.includes("--save");
+  const named = words.filter((w) => !w.startsWith("-"))[0];
+  const reg = ctx.rt.providers;
+
+  const ids = named !== undefined ? [named] : reg.list().filter(isConfigured).map((p) => p.id);
+  if (ids.length === 0) { note(ctx, `no provider is configured yet. ${next("/connect")}`, "warn"); return; }
+
+  note(ctx, ids.length === 1 ? `fetching ${ids[0]} models…` : `fetching models from ${ids.length} providers…`);
+  const results = await Promise.all(ids.map(async (id) => ({ id, r: await reg.models(id) })));
+
+  const items: PickItem[] = [];
+  const problems: string[] = [];
+  const catalog = ctx.catalog ?? new ModelCatalog(); // port #60: lookup only, never refresh/fetch metadata
+  const itemFor = (id: string, model: string): PickItem => {
+    const current = ctx.state.provider === id && ctx.state.model === model;
+    const description = [current ? "current" : "", describeModel(catalog.lookup(id, model))].filter(Boolean).join(" · ");
+    return { value: `${id}/${model}`, label: `${current ? "* " : "  "}${id}/${model}`, ...(description ? { description } : {}) };
+  }; // port #60
+  for (const { id, r } of results) {
+    if (!r.ok) { problems.push(`${id}: ${r.error}`); continue; }
+    if (r.models.length === 0) { problems.push(`${id}: the endpoint listed no models (no /models route?) — /model ${id}/<model> still works`); continue; }
+    for (const m of r.models) {
+      items.push(itemFor(id, m)); // port #60: same live ids, optional context/pricing/capabilities
+    }
+  }
+  for (const p of problems) note(ctx, p, "warn");
+  // port #60: never hide the running model just because a provider's list does not know it.
+  const currentRef = `${ctx.state.provider}/${ctx.state.model}`;
+  if (ctx.state.model && ids.includes(ctx.state.provider) && !items.some((item) => item.value === currentRef)) items.unshift(itemFor(ctx.state.provider, ctx.state.model));
+  if (items.length === 0) return;
+
+  // the current model first: the list is long and the answer to "what am I on?" should not need scrolling
+  items.sort((a, b) => Number(b.label.startsWith("*")) - Number(a.label.startsWith("*")));
+  // short on purpose: the box clips its title, and it already draws an `esc` affordance of its own
+  const picked = await ctx.renderer.pickOne(items, `pick a model · ${items.length} from ${ids.length} provider${ids.length === 1 ? "" : "s"}`);
+  if (picked === null || (!save && picked === `${ctx.state.provider}/${ctx.state.model}`)) return; // port #60: cancel/re-pick changes no slot; --save still persists
+  cmdModel(ctx, save ? `${picked} --save` : picked); // ONE path for applying a model, flags and all
+}
+
+/** /provider list|add|remove|use|test|key */
+export async function cmdProvider(ctx: ProviderCmdCtx, arg: string): Promise<void> {
+  const words = arg.split(/\s+/).filter((w) => w.length > 0);
+  const [action, ...rest] = words;
+  const reg = ctx.rt.providers;
+  switch (action) {
+    case undefined:
+    case "list":
+      note(ctx, formatProviderList(reg, { all: rest.includes("--all") }));
+      return;
+    case "add": {
+      const parsed = parseAddArgs(rest);
+      if ("error" in parsed) { note(ctx, parsed.error, "warn"); return; }
+      const r = reg.add(parsed.spec, parsed.scope);
+      if ("error" in r) { note(ctx, r.error, "warn"); return; }
+      const key = isConfigured(r) ? "" : `\nkey: /provider key ${r.id} <secret>  ·  or set ${r.keyEnv} (live, no restart)`;
+      note(ctx, `added ${r.id} (${r.protocol}, ${r.baseUrl}) [${parsed.scope}]${key}\nuse it: /model ${r.id}/${r.defaultModel ?? "<model>"}`);
+      return;
+    }
+    case "remove": {
+      if (rest[0] === undefined) break;
+      const r = reg.remove(rest[0]);
+      if ("error" in r) { note(ctx, r.error, "warn"); return; }
+      note(ctx, r.removed.length > 0 ? `removed ${rest[0]} (${r.removed.join(", ")} providers.json)` : `${rest[0]} was not in any providers.json`);
+      return;
+    }
+    case "use": {
+      if (rest[0] === undefined) break;
+      localWrite = true;
+      let r: ReturnType<typeof reg.setDefault>;
+      try { r = reg.setDefault(rest[0]); } finally { localWrite = false; }
+      if ("error" in r) { note(ctx, r.error, "warn"); return; }
+      applyRef(ctx, r);
+      const p = reg.get(r.provider);
+      const keyNote = p !== undefined && !isConfigured(p) ? `\n${reg.keyHint(p)}` : "";
+      note(ctx, `default → ${r.provider}/${r.model} (saved; this session switched)${keyNote}`, keyNote.length > 0 ? "warn" : undefined);
+      return;
+    }
+    case "test": {
+      if (rest[0] === undefined) break;
+      note(ctx, `testing ${rest[0]}${rest[1] !== undefined ? `/${rest[1]}` : ""}…`);
+      const r = await reg.probe(rest[0], rest[1]);
+      note(ctx, `${rest[0]}/${r.model}: ${r.detail}`, r.ok ? undefined : "warn");
+      return;
+    }
+    case "key": {
+      const [id, secret] = rest;
+      if (id === undefined || secret === undefined) break;
+      const p = reg.get(id);
+      if (p === undefined) { note(ctx, `unknown provider "${id}" — /provider add ${id} <baseUrl> first`, "warn"); return; }
+      saveCredential(id, secret, p.keyEnv);
+      reg.refresh();
+      note(ctx, `stored ${p.keyEnv} for ${id} (${redactSecret(secret)}) — live now`);
+      return;
+    }
+    default:
+      break;
+  }
+  note(ctx, `usage: /provider list [--all] · /provider ${ADD_USAGE} · remove <id> · use <provider/model> · test <id> [model] · key <id> <secret>`, "warn");
+}
+
+// ---------- /setup ----------
+
+/** the watcher + poll an unfinished /setup left armed (one at a time; a new /setup replaces it) */
+let pendingSetup: (() => void) | null = null;
+
+/** /setup — the TUI's guided connect: provider from the picker, model from a question card, then the
+ *  key. The cards have no masked input, so the key is a HAND-OFF: `rovecode auth set <id>` in another
+ *  terminal (masked) or `/provider key` here. The live registry notices the key landing (a 1 s poll keeps
+ *  its mtime check warm while a setup is pending) and this finishes the job — one test call, default,
+ *  session switch — without another command. Wording: core/voice.ts. */
+export async function cmdSetup(ctx: ProviderCmdCtx): Promise<void> {
+  const reg = ctx.rt.providers;
+  pendingSetup?.(); pendingSetup = null;
+  const items = SETUP_PICKS.map((p) => ({ value: p.key, label: p.label }));
+  const key = await ctx.renderer.pickOne(items, "◆ connect a model — which provider? (Esc = cancel)");
+  if (key === null) { note(ctx, "setup cancelled — nothing changed. /setup whenever you like"); return; }
+  const pick = SETUP_PICKS.find((p) => p.key === key);
+  if (pick === undefined) return;
+  const askText = async (question: string): Promise<string | null> => {
+    const a = await ctx.renderer.askQuestion({ question, options: [], allowFreeText: true }).catch(() => null);
+    return a?.text?.trim() ?? null;
+  };
+  let id: string;
+  if (pick.url !== undefined) {
+    const idText = ((await askText("Short name for it? (letters, digits, - _ .)")) ?? "").toLowerCase();
+    if (!PROVIDER_ID_RE.test(idText)) { note(ctx, `setup stopped — "${idText}" won't work as an id. ${next("/setup, and pick a name like myproxy")}`, "warn"); return; }
+    const baseUrl = (await askText(`Base URL for ${idText}? (e.g. https://host/v1)`)) ?? "";
+    if (!/^https?:\/\//.test(baseUrl)) { note(ctx, `setup stopped — "${baseUrl}" is not an http(s) URL. ${next("/setup")}`, "warn"); return; }
+    const keyA = await ctx.renderer.askQuestion({ question: "Does it need an API key?", options: ["yes", "no — it is a local server"], allowFreeText: false }).catch(() => null);
+    const noKey = keyA?.choice === 1;
+    const r = reg.add({ id: idText, baseUrl, protocol: pick.url, ...(noKey ? { noKey: true } : {}) }, "user");
+    if ("error" in r) { note(ctx, `setup stopped — ${r.error}`, "warn"); return; }
+    id = idText;
+    note(ctx, `◆ ${id} registered (${pick.url} protocol, ${baseUrl}).`);
+  } else {
+    id = pick.id ?? "";
+    const known = reg.get(id);
+    if (known === undefined) { note(ctx, `setup stopped — ${id} is missing from the built-in table`, "warn"); return; }
+    if (pick.local === true && known.noKey !== true) {
+      // the built-in row expects a key env; a local server needs none — the user entry says so
+      const r = reg.add({ id, baseUrl: known.baseUrl, protocol: known.protocol, noKey: true, ...(known.defaultModel !== undefined ? { defaultModel: known.defaultModel } : {}) }, "user");
+      if ("error" in r) { note(ctx, `setup stopped — ${r.error}`, "warn"); return; }
+      note(ctx, `◆ ${id} marked as a local server (${known.baseUrl}, no key).`);
+    }
+  }
+  const spec = reg.get(id);
+  if (spec === undefined) return;
+  // A provider that ships a default model does not need a question: taking it is right nearly always,
+  // and `/model <id>/<other> --save` changes it in one line afterwards. Only an endpoint with no
+  // default (a bare proxy, a self-hosted server) still has to be asked — there is nothing to assume.
+  let model = spec.defaultModel;
+  if (model === undefined) {
+    const mA = await ctx.renderer.askQuestion({ question: `Which model id on ${id}?`, options: [], allowFreeText: true }).catch(() => null);
+    model = mA?.text?.trim() || mA?.label;
+    if (model === undefined || model.length === 0) { note(ctx, `◆ ${id} is set up but has no model yet. ${next(`/models ${id}, then /model ${id}/<model> --save`)}`); return; }
+  } else {
+    note(ctx, `◆ model → ${id}/${model}  (change it any time: /model ${id}/<other> --save)`);
+  }
+
+  const finish = async (): Promise<void> => {
+    note(ctx, `◆ testing ${id}/${model} …`);
+    const r = await reg.probe(id, model);
+    if (r.ok) note(ctx, `  ${r.detail}`);
+    else note(ctx, `  that didn't work: ${r.detail}\n  ${next(`check the key and the URL, then /provider test ${id} ${model}`)}`, "warn");
+    localWrite = true;
+    let d: ReturnType<typeof reg.setDefault>;
+    try { d = reg.setDefault(`${id}/${model}`, "user"); } finally { localWrite = false; }
+    if ("error" in d) { note(ctx, `  ${d.error}`, "warn"); return; }
+    applyRef(ctx, d);
+    note(ctx, `◆ default → ${d.provider}/${d.model} — this session switched too.\n${SETUP_DONE_TUI}`);
+  };
+  if (isConfigured(spec)) { await finish(); return; }
+  note(ctx, [
+    `◆ I need the key for ${id}. Paste it hidden in another terminal:`,
+    `    rovecode auth set ${id}`,
+    `  or here (this line only, redacted in the note): /provider key ${id} <secret>`,
+    `  or set ${spec.keyEnv} in your environment.`,
+    "  I'll notice as soon as it lands and finish the setup.",
+  ].join("\n"));
+  armKeyWatch(reg, id, finish);
+}
+
+/** Park until the key for `id` lands, then run `finish` once. The registry's mtime check only runs on
+ *  access, so a 1 s poll keeps it warm while we wait; one watch at a time — a new /setup or /connect
+ *  replaces the one before it. */
+function armKeyWatch(reg: ProviderCmdCtx["rt"]["providers"], id: string, finish: () => Promise<void>): void {
+  const timer = setInterval(() => { reg.snapshot(); }, 1000);
+  timer.unref?.();
+  const off = reg.onChange(() => {
+    const p = reg.get(id);
+    if (p === undefined || !isConfigured(p)) return;
+    stop();
+    void finish();
+  });
+  const stop = (): void => { clearInterval(timer); off(); if (pendingSetup === stop) pendingSetup = null; };
+  pendingSetup = stop;
+}
+
+/** /connect — the same job as /setup, but with the answers on the line instead of in cards, so it is one
+ *  command to paste. Bare, it IS /setup. It runs cli/connect.ts against this session's LIVE registry and
+ *  applies the new default to the session, like /setup does.
+ *
+ *  There is no masked input in here, so `--key` and `--key-stdin` are refused rather than quietly
+ *  ignored: a key typed on this line would sit in the transcript. When a key is simply missing,
+ *  `deferKey` hands over the same way /setup does and the watcher finishes the job when it lands. */
+export async function cmdConnect(ctx: ProviderCmdCtx, arg: string): Promise<void> {
+  const words = arg.split(/\s+/).filter((w) => w.length > 0);
+  if (words.length === 0) { await cmdSetup(ctx); return; }
+  const parsed = parseConnectArgs(words);
+  if ("error" in parsed) { note(ctx, `${parsed.error.replace("usage: rovecode connect", "usage: /connect")}`, "warn"); return; }
+  if (parsed.key === "prompt" || parsed.key === "stdin") {
+    note(ctx, `there is no hidden prompt in here — a key on this line would sit in the transcript.\n  ${next(`rovecode auth set ${parsed.id} in another terminal, or /provider key ${parsed.id} <secret>`)}`, "warn");
+    return;
+  }
+  const reg = ctx.rt.providers;
+  pendingSetup?.(); pendingSetup = null;
+
+  /** the default is written by the time connect returns (even on a failed test call) — bring the
+   *  session with it, the way /setup does. Also runs on the deferred pass, after the key lands. */
+  const follow = (code: number): void => {
+    if (code === CONNECT_WAITING || code === 2) return;
+    const d = reg.defaultRef();
+    if (d !== null && d.provider === parsed.id && d.model.length > 0) applyRef(ctx, d);
+  };
+
+  const run = async (): Promise<number> => {
+    localWrite = true; // the watcher must not announce a default this command already reported
+    try {
+      return await runConnect(parsed, {
+        registry: reg,
+        tty: false, // cards, not a terminal: never let runConnect reach for a prompt or for stdin
+        out: (l) => note(ctx, l),
+        done: SETUP_DONE_TUI,
+        where: "tui", // the "→ next:" steps are slash commands in here, not shell lines
+        deferKey: (spec) => {
+          note(ctx, [
+            `◆ I need the key for ${parsed.id}. Paste it hidden in another terminal:`,
+            `    rovecode auth set ${parsed.id}`,
+            `  or here (this line only, redacted in the note): /provider key ${parsed.id} <secret>`,
+            `  or set ${spec.keyEnv} in your environment.`,
+            "  I'll notice as soon as it lands and finish the job.",
+          ].join("\n"));
+          armKeyWatch(reg, parsed.id, async () => { follow(await run()); });
+        },
+      });
+    } finally { localWrite = false; }
+  };
+
+  follow(await run());
+}
+
+/** Boot-time subscription: when the persisted default changes underneath this session (another
+ *  terminal's `rovecode model use`, the agent's provider_edit use) the session follows it; when the
+ *  first provider appears, say so. In-process slash writes report themselves (localWrite). */
+export function watchProviders(ctx: ProviderCmdCtx): () => void {
+  let lastSelector = ctx.rt.providers.defaultSelector();
+  let hadProvider = ctx.rt.noProviderReason() === null;
+  return ctx.rt.providers.onChange(() => {
+    const sel = ctx.rt.providers.defaultSelector();
+    if (sel !== lastSelector) {
+      lastSelector = sel;
+      const d = ctx.rt.providers.defaultRef();
+      if (d !== null && d.model.length > 0 && !localWrite) { applyRef(ctx, d); note(ctx, `default model changed → ${d.provider}/${d.model}`); }
+    }
+    const has = ctx.rt.noProviderReason() === null;
+    if (has && !hadProvider) note(ctx, "provider configured — ready for the next prompt");
+    hadProvider = has;
+  });
+}

package/src/tui/reasoning-view.ts

@@ -0,0 +1,56 @@
+/** Reasoning blocks on the interactive surfaces (port #60): the app's per-message bookkeeping between
+ *  `reasoning_update` events and a Renderer — ONE collapsed block per assistant message, opened on the
+ *  turn's first reasoning event, settled when the message's text starts, the turn ends or the run ends.
+ *  A renderer with `beginReasoning` (the classic card) gets the settle; one without gets a single system
+ *  note carrying the collapsed label once the block settles.
+ *
+ *  THE DELIBERATE DIFFERENCE FROM AION: rovecode's reasoning_update carries `tokens`, never text —
+ *  the loop drops the thinking text on purpose ("only its estimated size leaves the loop", loop.ts:272),
+ *  so there is nothing to append and this module counts tokens instead of characters. The property that
+ *  matters survives the translation: the thinking text is never rendered and never kept here.
+ *  `reasoningLabel` is the ONE wording every surface prints (the classic card, the fallback note).
+ *  Pure: no clock, no timers, no process. */
+
+import type { RunEvent } from "../core/types.ts";
+import type { AssistantView, Renderer } from "./renderer.ts";
+
+/** `reasoning · 1234 tokens …` while streaming, `reasoning · 1234 tokens · collapsed` once settled */
+export function reasoningLabel(tokens: number, streaming: boolean): string {
+  return `reasoning · ${tokens} tokens${streaming ? " …" : " · collapsed"}`;
+}
+
+/** the `--plain` REPL's one line per block (printed when the message's text starts or the turn ends) */
+export function collapsedReasoningLine(tokens: number): string {
+  return `  ∴ ${reasoningLabel(tokens, false)}`;
+}
+
+interface OpenBlock { id: string; view: AssistantView | null; tokens: number }
+
+export class ReasoningViews {
+  private open: OpenBlock | null = null;
+  constructor(private readonly renderer: Pick<Renderer, "addSystemNote" | "beginReasoning">) {}
+
+  /** feed every RunEvent of the live run (app.ts: right after renderer.onEvent, before the per-event calls).
+   *  `reasoning_update.tokens` is CUMULATIVE for the message (a dropped event costs nothing), so the block
+   *  takes the event's value rather than summing. */
+  onEvent(ev: RunEvent): void {
+    if (ev.type === "reasoning_update") {
+      if (this.open && this.open.id !== ev.messageId) this.settle();
+      if (!this.open) this.open = { id: ev.messageId, view: this.renderer.beginReasoning?.() ?? null, tokens: 0 };
+      this.open.tokens = Math.max(this.open.tokens, ev.tokens);
+      this.open.view?.set?.(`∴ ${reasoningLabel(this.open.tokens, true)}`);
+    } else if (ev.type === "message_update" || ev.type === "turn_end" || ev.type === "run_end") this.settle();
+  }
+
+  /** the open block (if any) is done: the card settles, or the fallback note lands */
+  settle(): void {
+    const o = this.open;
+    if (!o) return;
+    this.open = null;
+    if (o.view) o.view.done();
+    else this.renderer.addSystemNote(`∴ ${reasoningLabel(o.tokens, false)}`);
+  }
+
+  /** tokens of the block still open (tests) */
+  get openTokens(): number { return this.open?.tokens ?? 0; }
+}

package/src/tui/renderer.ts

@@ -0,0 +1,128 @@
+/** The Renderer seam (BLUEPRINT port #1): the TUI app talks only to this interface.
+ *  PiTuiRenderer is today's implementation; OpenTUI or others can slot in later
+ *  without touching the app/loop. House code outside src/tui must not import vendor. */
+
+import type { QuestionAnswer, QuestionPrompt } from "../tools/ask-user.ts";
+import type { PermissionLevel, ThinkingEffort, RunEvent } from "../core/types.ts";
+import type { SextantAttach } from "../sextant/types.ts";
+
+export type { QuestionAnswer, QuestionPrompt, SextantAttach };
+
+/** `all-edits` is offered only on an edit/write card: it answers THIS call and asks the surface to
+ *  drop to accept-edits for the rest of the session (writes inside the workspace stop prompting). */
+export type ApprovalAnswer = "once" | "always" | "all-edits" | "deny";
+
+export interface StatusInfo {
+  provider: string;
+  model: string;
+  yolo: boolean;
+  /** the full permission tier; `yolo` stays for the surfaces that only know two. Optional so a
+   *  renderer that does not paint it needs no change. */
+  permission?: PermissionLevel;
+  /** the thinking dial, painted next to the model when it is on */
+  effort?: ThinkingEffort;
+  turns: number;
+  tokensIn: number;
+  tokensOut: number;
+  /** port #20: plan/act mode indicator (optional — plain surfaces omit it) */
+  mode?: "plan" | "act";
+  /** port #32: "todos done/total" for the status bar; omitted when the session has no list */
+  todos?: string;
+}
+
+export interface RendererHooks {
+  /** user submitted a line from the editor (already trimmed, non-empty) */
+  onSubmit: (text: string) => void;
+  /** user asked to interrupt the in-flight run (Escape on the loader) */
+  onInterrupt: () => void;
+  /** user asked to leave (Ctrl+C) */
+  onExit: () => void;
+}
+
+/** A streaming assistant message in the transcript. */
+export interface AssistantView {
+  append(delta: string): void;
+  /** finalize; no more appends */
+  done(): void;
+  /** port #60 (OPTIONAL): replace the view's content — the reasoning card uses it because a reasoning_update
+   *  carries the cumulative TOKEN count, not deltas, so the card repaints one line per event. A view without
+   *  it (plain transcript appends) is left alone; ReasoningViews skips the update instead of appending counts. */
+  set?(content: string): void;
+}
+
+export interface SlashCommand {
+  name: string;
+  description: string;
+  /** /help topic the command is listed under (info-cmd.ts); the palette ignores it */
+  group?: string;
+  /** the argument values (`/effort` levels; `/model` ids): the sextant lists them as suggestions once
+   *  the command is typed and completes the one picked. A function is read at suggestion time, for a
+   *  set that changes while the TUI runs (the models of the providers that have a key). */
+  choices?: readonly string[] | (() => readonly string[]);
+  /** what Enter does on a picked choice: "submit" (default — `/effort high` runs) or "complete" — the
+   *  choice is a subcommand that wants more words (`/mcp add ` waits for a name) */
+  choicesThen?: "submit" | "complete";
+}
+
+export interface PickItem { value: string; label: string; description?: string }
+
+export interface RendererStartOptions {
+  /** false after a loading intro: reveal the complete layout, not a second panel animation. */
+  animate?: boolean;
+  /** Called once the scene exists but before its first paint, to seed transcript and status. */
+  beforeFirstRender?: () => void;
+  /** Keep the prepared frame offscreen while the loading intro completes. Never reads stdin. */
+  beforeReveal?: () => Promise<void>;
+  /** Last handoff: the frame is laid out, immediately before terminal takeover/output. */
+  onReveal?: () => void;
+}
+
+export interface Renderer {
+  start(hooks: RendererHooks, options?: RendererStartOptions): void | Promise<void>;
+  stop(): void;
+  /** Put the terminal back and nothing else — no settling, no child processes, no async. `stop()` is the
+   *  orderly shutdown and calls this as its last act; this is what the CRASH path calls, because there
+   *  the only thing that still matters is that the person gets their shell back. Separated because
+   *  `stop()` does work that can itself throw, and a throw before the restore is how a crash turns into
+   *  "my terminal is broken": the alt screen never closes and mouse reporting keeps typing escape
+   *  sequences at the prompt. Must be idempotent and must never throw. Optional: a renderer that never
+   *  touched the terminal (the test fake) has nothing to restore. */
+  restoreTerminal?(): void;
+  /** slash commands offered by editor autocomplete; call before start() */
+  setCommands(cmds: SlashCommand[]): void;
+  addUser(text: string): void;
+  addSystemNote(text: string, tone?: "info" | "warn" | "error"): void;
+  beginAssistant(): AssistantView;
+  /** port #60 (OPTIONAL): a collapsed reasoning block for the assistant message being streamed — its view
+   *  settles on done(); surfaces render a SIZE (tokens), never the text. A renderer without it gets one
+   *  system note per block from tui/reasoning-view.ts instead. */
+  beginReasoning?(): AssistantView;
+  toolStart(callId: string, tool: string, argsPreview: string): void;
+  toolUpdate(callId: string, note: string): void;
+  toolEnd(callId: string, ok: boolean, outputPreview: string, durationMs: number): void;
+  /** modal approval; resolves deny on cancel/escape. `detail` (port #24): pre-rendered
+   *  unified diff of a pending edit/write, shown inside the overlay above the verdicts */
+  askApproval(tool: string, argsPreview: string, detail?: string): Promise<ApprovalAnswer>;
+  /** modal picker (session/turn navigators); resolves null on cancel/escape/stop */
+  pickOne(items: PickItem[], title?: string): Promise<string | null>;
+  /** modal question for the ask_user tool (port #33): options + a free-text entry when allowed.
+   *  Resolves the pick/typed text; null when the user declines, `signal` aborts (the run's
+   *  controller — the card must dismiss, never leak), or the UI stops. Implementations may
+   *  reject a SECOND concurrent ask with a clear error (the tool turns it into a failed result). */
+  askQuestion(q: QuestionPrompt, signal?: AbortSignal): Promise<QuestionAnswer | null>;
+  /** remove all transcript items (history replay after rewind/resume) */
+  clearTranscript(): void;
+  /** place text in the editor for edit-and-resubmit (pi sessions.md:106-116) */
+  prefillEditor(text: string): void;
+  setBusy(busy: boolean, label?: string): void;
+  setStatus(info: StatusInfo): void;
+  /** port #44 (OPTIONAL — FakeRenderer/PiTuiRenderer omit it): every RunEvent of the live run, delivered
+   *  as the FIRST statement of the app's event loop, BEFORE the toolStart/beginAssistant/addSystemNote
+   *  calls the same event triggers. A renderer that implements it (sextant) treats the event stream as
+   *  its source of truth for transcript rows and ignores the duplicate per-event calls while busy. */
+  onEvent?(ev: RunEvent): void;
+  /** port #44 (OPTIONAL): the runtime handles the sextant panels read — cwd, sessions dir, the ACTIVE
+   *  store, tasks, model + context window, usage math. Called exactly once by runTui, after runtime
+   *  construction and before start(). */
+  attach?(ctx: SextantAttach): void;
+}

package/src/tui/replay-marker.ts

@@ -0,0 +1,29 @@
+/** Persisted RunEvent annotations → transcript lines (port #25 LOW-4). The loop persists a
+ *  compaction as a `kind: "event"` entry (SessionStore.appendEvent) right where it happened, and
+ *  the live TUI shows it as a system note; a resumed session (--resume, /resume, /sessions)
+ *  replays the SAME line at the same place, so "was this context compacted?" has one answer on
+ *  both paths. ONE wording, built here, used by app.ts (live) and session-cmd.ts replayTranscript
+ *  (replay) — never two strings to keep in step. Any other persisted event type renders nothing:
+ *  the live TUI shows nothing for a bare event either, and replay must never add a line the run
+ *  did not (context-drop compactions are yielded but not persisted — loop.ts:191 — so a resumed
+ *  session cannot show them; nothing to render). */
+
+import type { Entry } from "../core/session.ts";
+import type { Message, RunEvent } from "../core/types.ts";
+
+export type CompactionEvent = Extract<RunEvent, { type: "compaction" }>;
+/** SessionStore.appendEvent's entry shape — the non-message half of Entry */
+export type EventEntry = Exclude<Entry, Message>;
+
+/** the TUI's system note for a compaction — live (app.ts startRun) and replayed alike */
+export function compactionNote(ev: CompactionEvent): string {
+  return `compacted (${ev.strategy}): ${ev.tokensBefore} → ${ev.tokensAfter} tokens`;
+}
+
+/** the transcript line for a persisted event entry, or null when the live TUI shows nothing for
+ *  it. Tolerant of a foreign/corrupt entry (session.ts never throws on shape; neither does replay). */
+export function replayMarkerLine(entry: EventEntry): string | null {
+  const ev = entry.event as RunEvent | undefined;
+  if (!ev || typeof ev !== "object") return null;
+  return ev.type === "compaction" ? compactionNote(ev) : null;
+}