@vigent/cli 0.2.2 → 0.3.0

package/dist/app.js

@@ -6,7 +6,7 @@
  *   │ statusline           │
  *   └ cmdline              ┘
  */
-import { truncateToWidth, visibleWidth, wrapTextWithAnsi, } from "@mariozechner/pi-tui";
+import { truncateToWidth, visibleWidth, wrapTextWithAnsi, } from "./tui.js";
 import { applySetCommand, CONFIG_TEMPLATE, configPath, DEFAULT_UI } from "./config.js";
 import { setTomlValue, tomlValue } from "./config-edit.js";
 import { SettingsFloat } from "./settings.js";
@@ -15,9 +15,16 @@ import { ACTIONS, formatKeys, KEY_MODES, KeySequencer, Keymap, keyFromInput, par
 import * as path from "node:path";
 import * as fs from "node:fs";
 import { setDetached } from "./agents.js";
+import { dropPatch, parseDiff, restorePatch } from "./hunks.js";
+import { HunkReview } from "./hunk-review.js";
+import { listFiles, MENTION, mentionable } from "./attach.js";
+import { allTemplates, fillTemplate, needsTask } from "./templates.js";
+import { startServer } from "./serve.js";
+import { didYouMean } from "./suggest.js";
+import { alertSequence, NOTIFY_MODES } from "./notify.js";
 import { VERSION_TEXT } from "./version.js";
 import { backendName, formatBytes, riftriBackends, RIFTRI_INSTALL } from "./riftri.js";
-import { ENGINE_NAMES, isEngineId } from "./engines.js";
+import { defaultEngine as defaultEngineFor, ENGINE_NAMES, isEngineId } from "./engines.js";
 import { copyToClipboard } from "./clipboard.js";
 import { splitView, unifiedView } from "./diffview.js";
 import { TREE_GLYPHS } from "./tree.js";
@@ -55,6 +62,8 @@ const ICONS = {
         queued: "⧗",
         open_agent: "▸",
         here: "●",
+        unread: "◆",
+        serve: "⇄ ",
         ok: "●",
         warn: "◐",
         off: "○",
@@ -76,6 +85,8 @@ const ICONS = {
         queued: NERD.clock,
         open_agent: "▸",
         here: NERD.circle,
+        unread: NERD.bell,
+        serve: "\uf10b ",
         ok: NERD.check,
         warn: NERD.warning,
         off: NERD.circleO,
@@ -97,6 +108,8 @@ const ICONS = {
         queued: "+",
         open_agent: ">",
         here: "*",
+        unread: "!",
+        serve: "~ ",
         ok: "+",
         warn: "~",
         off: "-",
@@ -147,6 +160,8 @@ export class App {
     /** model and effort for new agents, per engine ([engines.<id>] in config.toml, :model / :effort with no agent) */
     newAgentModel = {};
     newAgentEffort = {};
+    /** yours, from [templates] in config.toml (the built-in ones are added to these) */
+    templates = {};
     /** save an agent's settings (model, effort) so they survive a restart */
     persist = () => { };
     /** `engine` from config.toml or :settings; "auto" lets defaultEngine() pick */
@@ -197,8 +212,13 @@ export class App {
         return this.sessions[this.focusIdx];
     }
     addSession(s, focus = true) {
+        if ("extensionStatus" in s)
+            s.uiHost = this.piUiHost(s);
+        queueMicrotask(() => this.server?.sync());
         this.sessions.push(s);
+        this.lastState.set(s, s.state);
         s.onChange(() => {
+            this.watchState(s);
             this.syncSpinner();
             this.tui.requestRender();
         });
@@ -218,9 +238,36 @@ export class App {
         this.syncSpinner();
         this.tui.requestRender();
     }
+    /** agents that finished, failed or wait for you while you looked elsewhere */
+    unread = new Set();
+    /** the terminal window has focus (from focus reporting; assumed until told otherwise) */
+    terminalFocused = true;
+    lastState = new WeakMap();
+    /** where notifications go (replaced in tests) */
+    alert = (bytes) => this.terminal.write(bytes);
+    /** An agent stopped running: if you're not looking at it, say so (bell, desktop notification, sidebar mark). */
+    watchState(s) {
+        const before = this.lastState.get(s);
+        this.lastState.set(s, s.state);
+        if (before === "running" && s.state !== "running")
+            this.persist(s); // its usage totals, for after a restart
+        if (before !== "running" || s.state === "running" || s.state === "paused")
+            return;
+        const visible = s === this.focusedSession && this.terminalFocused;
+        if (visible)
+            return;
+        this.unread.add(s);
+        const n = this.sessions.indexOf(s) + 1;
+        const what = s.state === "error" ? "failed" : s.state === "waiting" ? "needs you" : "finished";
+        if (s !== this.focusedSession) {
+            this.setMessage(`'${s.name}' ${what} · ${n <= 9 ? `${n} or ` : ""}]s to open it`, s.state === "error" ? "ErrorMsg" : "ModeMsg");
+        }
+        this.alert(alertSequence(`vigent: '${s.name}' ${what}`, this.ui.notify));
+    }
     focusSession(idx) {
         if (idx < 0 || idx >= this.sessions.length || idx === this.focusIdx)
             return;
+        this.unread.delete(this.sessions[idx]);
         this.altIdx = this.focusIdx;
         this.focusIdx = idx;
         this.scrollOffset = 0;
@@ -278,17 +325,28 @@ export class App {
         this.painter.setTransparency(this.ui.transparent ?? "auto");
     }
     /** Ask a y/n question in the command line, like vim's confirm prompts. */
-    ask(question, onYes) {
+    ask(question, onYes, onNo) {
         this.seq.reset();
-        this.confirm = { question, onYes };
+        this.confirm?.onNo?.(); // a newer question replaces an unanswered one: that one is a no
+        this.confirm = { question, onYes, onNo };
     }
     handleInput(data) {
+        // focus reporting: the terminal window gained or lost focus (never an answer to a question)
+        if (data === "\x1b[I" || data === "\x1b[O") {
+            this.terminalFocused = data === "\x1b[I";
+            if (this.terminalFocused && this.focusedSession)
+                this.unread.delete(this.focusedSession);
+            this.tui.requestRender();
+            return;
+        }
         if (this.confirm) {
-            const { onYes } = this.confirm;
+            const { onYes, onNo } = this.confirm;
             this.confirm = undefined;
             this.message = "";
             if (data === "y" || data === "Y")
                 onYes();
+            else
+                onNo?.();
             this.tui.requestRender();
             return;
         }
@@ -327,6 +385,11 @@ export class App {
         return ["<Esc>", ...parseKeys([...rest].length === 1 ? rest : `<${rest}>`)];
     }
     typeText(text) {
+        if (this.mode === "INSERT" && text === "@" && (this.inputBuf === "" || /\s$/.test(this.inputBuf))) {
+            this.inputBuf += text;
+            this.openAttach();
+            return;
+        }
         if (this.mode === "INSERT")
             this.inputBuf += text;
         else if (this.mode === "COMMAND" || this.mode === "SEARCH")
@@ -669,6 +732,17 @@ export class App {
             case "dashboard":
                 this.openDashboard();
                 return;
+            case "cost":
+            case "usage":
+                this.openUsage();
+                return;
+            case "pi":
+            case "extensions":
+                this.openPiResources();
+                return;
+            case "serve":
+                void this.execServe(arg);
+                return;
             case "tree":
                 this.openTree();
                 return;
@@ -692,17 +766,36 @@ export class App {
             case "new!": {
                 const modelFlag = /(?:^|\s)--model[= ](\S+)/.exec(arg);
                 const engineFlag = /(?:^|\s)(?:--engine|-e)[= ](\S+)/.exec(arg);
-                const name = arg
+                const templateFlag = /(?:^|\s)(?:--template|-t)[= ](\S+)/.exec(arg);
+                const rest = arg
                     .replace(/(?:^|\s)--model[= ]\S+/, "")
                     .replace(/(?:^|\s)(?:--engine|-e)[= ]\S+/, "")
-                    .trim() || `agent-${this.sessions.length + 1}`;
-                this.startAgent(name, { worktree: cmd === "new", model: modelFlag?.[1], engine: engineFlag?.[1] });
+                    .replace(/(?:^|\s)(?:--template|-t)[= ]\S+/, "")
+                    .trim();
+                if (templateFlag) {
+                    this.startFromTemplate(templateFlag[1], rest, { worktree: cmd === "new" ? undefined : false, model: modelFlag?.[1], engine: engineFlag?.[1] });
+                    return;
+                }
+                this.startAgent(rest || `agent-${this.sessions.length + 1}`, { worktree: cmd === "new", model: modelFlag?.[1], engine: engineFlag?.[1] });
+                return;
+            }
+            case "templates":
+            case "template":
+            case "tpl": {
+                if (!arg)
+                    this.openTemplatePicker();
+                else
+                    this.exec(`new -t ${arg}`);
                 return;
             }
             case "kill":
             case "kill!":
                 this.killFocused(cmd === "kill!");
                 return;
+            case "review":
+            case "hunks":
+                this.openReview();
+                return;
             case "diff":
                 this.openDiff(/^(split|vert|vertical|side)$/.test(arg));
                 return;
@@ -756,6 +849,13 @@ export class App {
                 else
                     this.openModelPicker();
                 return;
+            case "engine":
+            case "eng":
+                if (arg)
+                    this.chooseEngine(arg);
+                else
+                    this.openEnginePicker();
+                return;
             case "effort":
             case "think":
                 if (arg)
@@ -996,6 +1096,37 @@ export class App {
             this.tui.requestRender();
         });
     }
+    /** `:engine`: which engine new agents run on, with what's ready on this machine. */
+    openEnginePicker() {
+        const ids = ["auto", "pi", "claude", "codex", "opencode"];
+        const items = ids.map((id) => ({ value: id, note: this.engineNote(id) }));
+        this.openChoices("Engine for new agents", items, this.preferredEngine, false, (v) => this.chooseEngine(v));
+    }
+    /** "Claude Code · ready", "Codex · not signed in: codex login", "auto: … (now Claude Code)" */
+    engineNote(id) {
+        if (id === "auto")
+            return `pick for me (now ${ENGINE_NAMES[defaultEngineFor(this.engines)]})`;
+        const e = this.engines?.find((x) => x.id === id);
+        if (!e)
+            return ENGINE_NAMES[id];
+        const status = e.connected ? "ready" : !e.installed ? "not installed" : e.connect ? `not signed in: ${e.connect}` : "not signed in";
+        return `${ENGINE_NAMES[id]} · ${status}`;
+    }
+    /** `:engine <name>`: new agents run on it. Agents already open keep theirs (their conversation lives there). */
+    chooseEngine(value) {
+        if (value !== "auto" && !isEngineId(value)) {
+            this.setMessage("engines: auto, pi, claude, codex, opencode", "ErrorMsg");
+            return;
+        }
+        this.preferredEngine = value;
+        const now = this.defaultEngine();
+        const e = this.engines?.find((x) => x.id === now);
+        const warn = e && !e.connected ? ` (${e.installed ? `not signed in${e.connect ? `: run ${e.connect}` : ""}` : "not installed"})` : "";
+        const s = this.focusedSession;
+        const open = s && s.engine !== now ? ` · '${s.name}' stays on ${ENGINE_NAMES[s.engine]}; :new <task> starts one on ${ENGINE_NAMES[now]}` : "";
+        this.setMessage(`new agents run on ${ENGINE_NAMES[now]}${value === "auto" ? " (auto)" : ""}${warn}${open} · :settings, w keeps it`, warn ? "WarningMsg" : "ModeMsg");
+        this.repaint();
+    }
     /** `:model`: pick from what the engine offers, or type any name. */
     openModelPicker(t = this.modelTarget()) {
         const current = t.session
@@ -1016,20 +1147,110 @@ export class App {
             return this.newAgentModel[t.engine];
         return "chosenModel" in t.session ? t.session.chosenModel : t.session.model;
     }
+    /** Every template: the built-in ones, then yours. */
+    allTemplates() {
+        return allTemplates(this.templates);
+    }
+    /**
+     * `:new -t <template> [task]`: start an agent with the template's engine,
+     * model and effort, and send it the template's prompt. Flags you type
+     * (--engine, --model) win over the template's.
+     */
+    startFromTemplate(name, task, opts = {}) {
+        const all = this.allTemplates();
+        const t = all.find((x) => x.name === name);
+        if (!t) {
+            this.setMessage(`no template '${name}'${didYouMean(name, all.map((x) => x.name))} · :templates lists them`, "ErrorMsg");
+            return undefined;
+        }
+        if (needsTask(t) && !task && !(t.builtin && t.name === "review")) {
+            this.setMessage(`template '${t.name}' needs a task: :new -t ${t.name} <what>`, "ErrorMsg");
+            this.mode = "COMMAND";
+            this.cmdBuf = `new -t ${t.name} `;
+            return undefined;
+        }
+        const engine = opts.engine ?? t.engine;
+        const s = this.startAgent(task ? agentNameFrom(task) : t.name, {
+            worktree: opts.worktree ?? t.worktree,
+            model: opts.model ?? (engine === t.engine || !t.engine ? t.model : undefined),
+            engine,
+            effort: !opts.engine || opts.engine === t.engine ? t.effort : undefined,
+        });
+        if (!s)
+            return undefined;
+        s.submit(fillTemplate(t, task));
+        this.setMessage(`${this.message} · template ${t.name}`, this.messageGroup);
+        return s;
+    }
+    /** `:templates`: pick one; the command line then takes the task. */
+    openTemplatePicker() {
+        const items = this.allTemplates().map((t) => {
+            const how = [t.engine ? ENGINE_NAMES[t.engine] : "", t.model ?? "", t.effort ?? ""].filter(Boolean).join(" · ");
+            const what = t.description ?? t.prompt.split("\n")[0];
+            return { value: t.name, note: `${what}${how ? ` (${how})` : ""}${t.builtin ? "" : " · yours"}` };
+        });
+        const place = { width: Math.min(96, this.terminal.columns - 4), anchor: "center" };
+        this.openChoices("Start an agent from a template", items, "", false, (name) => {
+            const t = this.allTemplates().find((x) => x.name === name);
+            if (t && !needsTask(t)) {
+                this.startFromTemplate(name, "");
+                return;
+            }
+            this.mode = "COMMAND";
+            this.cmdBuf = `new -t ${name} `;
+            this.setMessage(t?.builtin && t.name === "review" ? "what to focus on (optional), then Enter" : "what it's for, then Enter", "Comment");
+        }, {}, place);
+    }
     /** where effort levels come from (replaced in tests) */
     effortChoices = (engine, model) => effortChoicesFor(engine, model);
     /** where model lists come from (replaced in tests) */
     modelChoices = (engine) => modelChoices(engine);
-    openChoices(title, items, current, custom, done) {
+    /** where `@` finds files to attach (replaced in tests) */
+    listFiles = (cwd) => listFiles(cwd);
+    /** the folder the focused agent works in: its worktree, or this checkout */
+    attachDir() {
+        const s = this.focusedSession;
+        return s?.cwd ?? s?.worktree?.path ?? this.workspace.root ?? process.cwd();
+    }
+    /**
+     * `@` in the prompt: pick a file from the agent's folder. Enter writes
+     * `@path `, Esc keeps a plain `@`, Backspace takes the `@` back.
+     */
+    openAttach() {
+        const dir = this.attachDir();
+        const items = this.listFiles(dir).then((files) => files.filter(mentionable).map((value) => ({ value })));
+        const takeBack = () => {
+            if (this.inputBuf.endsWith("@"))
+                this.inputBuf = this.inputBuf.slice(0, -1);
+        };
+        this.openChoices(`Attach a file · ${path.basename(dir)}`, items, "", false, (v) => {
+            takeBack();
+            this.inputBuf += `@${v} `;
+        }, { search: true, onBackOut: takeBack, rows: 8 }, 
+        // a completion menu: just above the prompt, where you're typing
+        { anchor: "bottom-left", col: this.sidebarWidth(this.terminal.columns) + 2, offsetY: -2, width: Math.min(64, this.terminal.columns - 2) });
+    }
+    openChoices(title, items, current, custom, done, opts = {}, place = { width: Math.min(72, this.terminal.columns - 4), anchor: "center" }) {
         this.seq.reset();
         let handle;
         const picker = new ChoicePicker(this.painter, PICKER_ICONS[this.ui.icons], title, items, current, custom, (v) => {
             handle?.hide();
             if (v !== null)
                 done(v);
+            else
+                opts.onCancel?.();
             this.repaint();
-        }, () => this.tui.requestRender());
-        handle = this.tui.showOverlay(picker, { width: Math.min(72, this.terminal.columns - 4), anchor: "center" });
+        }, () => this.tui.requestRender(), {
+            ...opts,
+            onBackOut: opts.onBackOut
+                ? () => {
+                    handle?.hide();
+                    opts.onBackOut?.();
+                    this.repaint();
+                }
+                : undefined,
+        });
+        handle = this.tui.showOverlay(picker, place);
         this.tui.requestRender();
     }
     /** `:settings`: theme, look, agents and keys in one float; w saves them to config.toml. */
@@ -1089,7 +1310,7 @@ export class App {
                 change: (d) => {
                     this.preferredEngine = cycle(["auto", "pi", "claude", "codex", "opencode"], this.preferredEngine, d);
                 },
-                hint: "auto: pi with an API key, else the first signed-in CLI · :checkhealth shows which are ready",
+                hint: "auto: the first signed-in CLI, else pi with an API key · :engine picks it from anywhere",
             },
             {
                 section: "Agents",
@@ -1124,6 +1345,13 @@ export class App {
                 change: (d) => (wt.backend = cycle(["auto", "riftri", "git"], wt.backend ?? "auto", d)),
                 hint: "riftri: copy-on-write worktrees that share unchanged files (riftri.dev)",
             },
+            {
+                section: "Agents",
+                label: "Notify when an agent finishes",
+                value: () => ({ auto: "auto (bell, and a desktop notification where the terminal shows one)", bell: "bell", desktop: "desktop notification", off: "off" })[ui.notify],
+                change: (d) => (ui.notify = cycle(NOTIFY_MODES, ui.notify, d)),
+                hint: "when an agent finishes, fails or needs you while you're looking at another one (or another window)",
+            },
             {
                 section: "Keys",
                 label: "which-key popup",
@@ -1205,7 +1433,7 @@ export class App {
             set(undefined, "theme", this.painter.theme.name);
             set(undefined, "engine", this.preferredEngine);
             set(undefined, "leader", this.keymap.leader);
-            for (const k of ["sidebar", "sidebar_width", "number", "tilde", "icons", "termguicolors", "transparent", "whichkey"])
+            for (const k of ["sidebar", "sidebar_width", "number", "tilde", "icons", "termguicolors", "transparent", "whichkey", "notify"])
                 set("ui", k, ui[k]);
             set("worktree", "enabled", this.workspace.config.enabled);
             set("worktree", "backend", this.workspace.config.backend ?? "auto");
@@ -1234,10 +1462,15 @@ export class App {
             this.setMessage(`${info.name} isn't installed: ${info.install} · :checkhealth`, "ErrorMsg");
             return undefined;
         }
+        // auto lands on an engine that isn't ready only when none is; an agent started there could never answer
+        if (!opts.engine && this.preferredEngine === "auto" && info && !info.connected && !info.checking) {
+            this.setMessage(this.noEngineReady(), "ErrorMsg");
+            return undefined;
+        }
         const withWorktree = opts.worktree !== false && this.workspace.config.enabled;
         try {
             const model = opts.model ?? this.newAgentModel[engine];
-            const effort = this.newAgentEffort[engine];
+            const effort = opts.effort ?? this.newAgentEffort[engine];
             const s = this.newSession(name, { worktree: withWorktree, model, engine, ...(effort ? { effort } : {}) });
             this.addSession(s);
             const wt = s.worktree;
@@ -1262,6 +1495,14 @@ export class App {
             return undefined;
         }
     }
+    /** "no engine is signed in: run claude auth login or codex login, or for pi export ANTHROPIC_API_KEY=… · :checkhealth" */
+    noEngineReady() {
+        const engines = this.engines ?? [];
+        const logins = engines.filter((e) => e.id !== "pi" && e.installed && e.connect).map((e) => e.connect);
+        const pi = engines.find((e) => e.id === "pi")?.connect;
+        const ways = [logins.length > 0 ? `run ${logins.join(" or ")}` : "", pi ? `for pi ${pi}` : ""].filter(Boolean).join(", or ");
+        return `no engine is signed in${ways ? `: ${ways}` : ""} · :checkhealth`;
+    }
     /**
      * `:theme save <name>`: what's on screen (the theme, your :hi changes,
      * transparency) as ~/.config/vigent/themes/<name>.toml, then switch to it.
@@ -1409,7 +1650,9 @@ export class App {
                 [stateGroup(s.state), s.state.padEnd(8)],
                 ["Comment", ` ${truncateToWidth(s.worktree ? `${I.worktree}${s.worktree.branch}` : s.model, 34, "…")}`],
                 ...stat,
+                ["Comment", s.tokens ? `  ${formatUsage(s)}` : ""],
                 ["Comment", s.queue.length ? `  ${I.queued}${s.queue.length}` : ""],
+                [s.state === "error" ? "ErrorMsg" : "WarningMsg", this.unread.has(s) ? `  ${I.unread} new` : ""],
             ]);
             lines.push([
                 ["NormalFloat", "      "],
@@ -1418,13 +1661,217 @@ export class App {
         });
         const running = this.sessions.filter((s) => s.state === "running").length;
         lines.push([]);
-        lines.push([["Comment", `${this.sessions.length} agents · ${running} running · j/k move · Enter open`]]);
+        const total = totalUsage(this.sessions);
+        lines.push([
+            ["Comment", `${this.sessions.length} agents · ${running} running · `],
+            ["NormalFloat", `${formatUsage(total)} in all`],
+            ["Comment", " · j/k move · Enter open · :cost for more"],
+        ]);
         this.openFloat("Dashboard", lines, Math.min(110, this.terminal.columns - 4), {
             selectable: rows,
             onSelect: (lineIdx) => this.focusSession(rows.indexOf(lineIdx)),
             initial: rows[this.focusIdx],
         });
     }
+    /**
+     * Where a pi agent's extensions talk to you: confirm() is a y/n question in
+     * the command line, select() and input() are pickers, notify() goes to the
+     * transcript and the message line. Each names the agent it's from.
+     */
+    piUiHost(s) {
+        const who = () => `'${s.name}'`;
+        // one line, and emoji in text style (U+FE0F makes terminals disagree on their width)
+        const oneLine = (t) => t.replace(/\uFE0F/g, "").replace(/\s+/g, " ").trim();
+        const lookHere = () => {
+            if (s !== this.focusedSession || !this.terminalFocused)
+                this.alert(alertSequence(`vigent: ${who()} asks you something`, this.ui.notify));
+        };
+        return {
+            select: (title, options) => new Promise((resolve) => {
+                lookHere();
+                this.openChoices(`${who()} · ${oneLine(title)}`, options.map((value) => ({ value })), "", false, resolve, {
+                    onCancel: () => resolve(undefined),
+                    rows: Math.max(3, Math.min(10, options.length)),
+                });
+            }),
+            confirm: (title, message) => new Promise((resolve) => {
+                lookHere();
+                const text = [title, message].filter(Boolean).map(oneLine).join(": ");
+                this.ask(`${who()} ${text} (y/n)`, () => resolve(true), () => resolve(false));
+                this.tui.requestRender();
+            }),
+            input: (title, placeholder) => new Promise((resolve) => {
+                lookHere();
+                this.openChoices(`${who()} · ${oneLine(title)}${placeholder ? ` (${oneLine(placeholder)})` : ""}`, [], "", true, resolve, { search: true, rows: 3, onCancel: () => resolve(undefined) });
+            }),
+            notify: (message, type) => {
+                s.pushInfo(message);
+                this.setMessage(`${who()}: ${message}`, type === "error" ? "ErrorMsg" : type === "warning" ? "WarningMsg" : "ModeMsg");
+                this.tui.requestRender();
+            },
+            setStatus: (key, text) => s.setExtensionStatus?.(key, text),
+        };
+    }
+    /** `:pi`: what pi loaded for the focused agent. Enter on a command, skill or prompt starts a prompt with it. */
+    openPiResources() {
+        const s = this.focusedSession;
+        if (!s || !("resources" in s)) {
+            this.setMessage(s ? `:pi lists a pi agent's extensions; '${s.name}' runs on ${ENGINE_NAMES[s.engine]}` : "no agent yet", "Comment");
+            return;
+        }
+        const r = s.resources();
+        if (!r) {
+            this.setMessage(`'${s.name}' is still starting`, "Comment");
+            return;
+        }
+        const lines = [];
+        const rows = [];
+        const typed = [];
+        const home = process.env.HOME ?? "";
+        const short = (p) => (home && p.startsWith(home) ? `~${p.slice(home.length)}` : this.shortPath(p));
+        const section = (title, n) => {
+            if (lines.length)
+                lines.push([]);
+            lines.push([["Title", title], ["Comment", `  ${n}`]]);
+        };
+        const item = (name, note, insert) => {
+            if (insert) {
+                rows.push(lines.length);
+                typed.push(insert);
+            }
+            lines.push([
+                ["Identifier", `  ${name.padEnd(24)}`],
+                ["Comment", note ? ` ${truncateToWidth(note.replace(/\s+/g, " "), 60, "…")}` : ""],
+            ]);
+        };
+        section("Extensions", r.extensions.length);
+        if (!r.extensions.length)
+            lines.push([["Comment", "  none (~/.pi/agent/extensions/ or .pi/extensions/)"]]);
+        for (const e of r.extensions)
+            lines.push(e.error ? [["ErrorMsg", `  ${short(e.path)}`], ["Comment", `  ${e.error}`]] : [["NormalFloat", `  ${short(e.path)}`]]);
+        section("Commands", r.commands.length);
+        for (const c of r.commands)
+            item(`/${c.name}`, c.description, `/${c.name} `);
+        section("Skills", r.skills.length);
+        for (const k of r.skills)
+            item(`/skill:${k.name}`, k.description, `/skill:${k.name} `);
+        section("Prompt templates", r.prompts.length);
+        for (const p of r.prompts)
+            item(`/${p.name}`, p.description, `/${p.name} `);
+        section("Context files", r.contextFiles.length);
+        for (const f of r.contextFiles)
+            lines.push([["NormalFloat", `  ${short(f)}`]]);
+        lines.push([]);
+        lines.push([["Comment", "Enter starts a prompt with it · pi loads these itself, as in pi"]]);
+        this.openFloat(`pi · ${s.name}`, lines, Math.min(96, this.terminal.columns - 4), {
+            selectable: rows.length ? rows : undefined,
+            onSelect: (lineIdx) => {
+                const text = typed[rows.indexOf(lineIdx)];
+                if (!text)
+                    return;
+                this.mode = "INSERT";
+                this.inputBuf = text;
+            },
+        });
+    }
+    /** the `:serve` server, while it runs */
+    server;
+    /** starts it (replaced in tests) */
+    startServer = startServer;
+    /** `:serve [local] [port]` starts it (or shows where it is), `:serve stop` stops it. */
+    async execServe(arg) {
+        const words = arg.split(/\s+/).filter(Boolean);
+        if (words[0] === "stop") {
+            if (!this.server)
+                return this.setMessage(":serve isn't running", "Comment");
+            await this.server.close();
+            this.server = undefined;
+            this.notify(":serve stopped", "Comment");
+            return;
+        }
+        if (this.server)
+            return this.openServeInfo();
+        const port = Number(words.find((w) => /^\d+$/.test(w)) ?? 8377);
+        const local = words.includes("local");
+        try {
+            this.server = await this.startServer(this.serveHost(), { port, host: local ? "127.0.0.1" : "0.0.0.0" });
+        }
+        catch (err) {
+            const why = err?.code === "EADDRINUSE" ? `port ${port} is taken (:serve ${port + 1})` : String(err?.message ?? err);
+            return this.notify(`:serve couldn't start: ${why}`, "ErrorMsg");
+        }
+        this.openServeInfo();
+    }
+    serveHost() {
+        return {
+            sessions: () => this.sessions,
+            project: () => path.basename(this.workspace.root ?? process.cwd()),
+            palette: () => extractPalette(this.painter.theme),
+            isUnread: (s) => this.unread.has(s),
+            startAgent: (task) => this.startAgent(agentNameFrom(task)),
+            notify: (text) => this.notify(text, "ModeMsg"),
+        };
+    }
+    /** Where to open it and the access code. */
+    openServeInfo() {
+        const sv = this.server;
+        if (!sv)
+            return;
+        const lines = [];
+        lines.push([["Comment", "On your phone, open"]]);
+        for (const u of sv.urls.slice(0, sv.urls.length > 1 ? -1 : undefined))
+            lines.push([["Title", `  ${u}`]]);
+        lines.push([["Comment", "and type the access code"]]);
+        lines.push([["String", `  ${sv.code}`]]);
+        lines.push([]);
+        lines.push([["Comment", "Or open it with the code in the link:"]]);
+        lines.push([["NormalFloat", `  ${sv.urls[0]}#${sv.code}`]]);
+        lines.push([]);
+        if (sv.host === "127.0.0.1")
+            lines.push([["WarningMsg", "This machine only (:serve local). :serve stop, then :serve, for your phone."]]);
+        else
+            lines.push([["Comment", "Same Wi-Fi as this machine, or a VPN like Tailscale. Plain HTTP:"], ["WarningMsg", " not on public Wi-Fi."]]);
+        lines.push([["Comment", "The page lists your agents, follows a reply as it streams, and sends prompts."]]);
+        lines.push([["Comment", ":serve shows this again · :serve stop ends it (and the code)"]]);
+        this.openFloat("Follow from your phone", lines, Math.min(84, this.terminal.columns - 4));
+    }
+    /** `:cost`: what each agent has used (tokens, and money where the engine reports it) and the total. */
+    openUsage() {
+        if (this.sessions.length === 0) {
+            this.setMessage("no agents yet (:new <task> starts one)", "Comment");
+            return;
+        }
+        const lines = [];
+        const rows = [];
+        const cell = (s, w) => truncateToWidth(s, w - 1, "…").padEnd(w);
+        lines.push([["Comment", `${cell("agent", 30)}${cell("engine", 13)}${"tokens".padStart(11)}${"cost".padStart(10)}`]]);
+        this.sessions.forEach((s) => {
+            rows.push(lines.length);
+            lines.push([
+                ["Title", cell(s.name, 30)],
+                ["Comment", cell(ENGINE_NAMES[s.engine], 13)],
+                ["NormalFloat", formatTokens(s.tokens).replace(/ tok$/, "").padStart(11)],
+                [s.cost === undefined ? "Comment" : "String", (s.cost === undefined ? "—" : formatCost(s.cost)).padStart(10)],
+            ]);
+        });
+        const total = totalUsage(this.sessions);
+        lines.push([["FloatBorder", "─".repeat(64)]]);
+        lines.push([
+            ["Title", cell("all agents", 43)],
+            ["NormalFloat", formatTokens(total.tokens).replace(/ tok$/, "").padStart(11)],
+            ["String", (total.cost === undefined ? "—" : formatCost(total.cost)).padStart(10)],
+        ]);
+        lines.push([]);
+        lines.push([["Comment", "Costs are as each engine reports them. Claude Code prices its"]]);
+        lines.push([["Comment", "tokens at API rates, even on a subscription."]]);
+        if (total.unpriced)
+            lines.push([["Comment", "Codex reports no price (—); its tokens are counted."]]);
+        this.openFloat("Usage", lines, Math.min(72, this.terminal.columns - 4), {
+            selectable: rows,
+            onSelect: (lineIdx) => this.focusSession(rows.indexOf(lineIdx)),
+            initial: rows[this.focusIdx],
+        });
+    }
     // ---------------------------------------------------------------- visual & yank
     /** First and last+1 pane lines on screen. */
     viewRange(total) {
@@ -1479,6 +1926,7 @@ export class App {
         s.abort();
         s.dispose();
         this.sessions.splice(this.focusIdx, 1);
+        this.server?.sync();
         this.focusIdx = Math.max(0, Math.min(this.focusIdx, this.sessions.length - 1));
         const wt = s.worktree;
         if (!wt?.path || !this.workspace.root) {
@@ -1596,6 +2044,49 @@ export class App {
         this.openFloat("Worktrees", lines, 112);
     }
     /** `:diff`: what the focused agent changed since its worktree was created. */
+    /** `:review`: keep or drop the focused agent's changes hunk by hunk. */
+    openReview() {
+        const s = this.focusedSession;
+        const wt = s?.worktree;
+        if (!s || !wt?.path) {
+            this.setMessage(s ? `'${s.name}' has no worktree to review` : "no agent", "ErrorMsg");
+            return;
+        }
+        if (s.state === "running") {
+            this.setMessage(`'${s.name}' is still working; review it when it's done (or :pause it)`, "WarningMsg");
+            return;
+        }
+        const load = async () => parseDiff(await diffText(wt, Number.POSITIVE_INFINITY));
+        load()
+            .then((files) => {
+            if (files.length === 0) {
+                this.setMessage(`no changes on ${wt.branch} yet`, "Comment");
+                this.tui.requestRender();
+                return;
+            }
+            this.seq.reset();
+            let handle;
+            const after = async () => {
+                s.refreshStat(0);
+                return load();
+            };
+            const review = new HunkReview(this.painter, PICKER_ICONS[this.ui.icons], `Review ${wt.branch} vs ${wt.base ?? "base"}`, files, () => this.terminal.rows - 2, {
+                drop: (patch) => dropPatch(wt.path, patch).then(after),
+                restore: (patch) => restorePatch(wt.path, patch).then(after),
+                close: () => {
+                    handle?.hide();
+                    this.repaint();
+                },
+                requestRender: () => this.tui.requestRender(),
+            });
+            handle = this.tui.showOverlay(review, { width: this.terminal.columns - 4, anchor: "center" });
+            this.tui.requestRender();
+        })
+            .catch((err) => {
+            this.setMessage(`git diff failed: ${err.message.split("\n")[0]}`, "ErrorMsg");
+            this.tui.requestRender();
+        });
+    }
     openDiff(split = false) {
         const s = this.focusedSession;
         const wt = s?.worktree;
@@ -1974,9 +2465,15 @@ export class App {
             case "e":
                 this.openEffortPicker();
                 return true;
+            case "E":
+                this.openEnginePicker();
+                return true;
             case "c":
                 this.openHealth();
                 return true;
+            case "T":
+                this.openTemplatePicker();
+                return true;
             case "?":
                 this.openHelp();
                 return true;
@@ -2053,7 +2550,8 @@ export class App {
         const left = s ? ` ${this.icons.open_agent} ${s.name}` : ` ${this.icons.open_agent} [no agent]`;
         const model = s ? `  ${s.engine !== "pi" && s.model !== ENGINE_NAMES[s.engine] ? `${ENGINE_NAMES[s.engine]} · ` : ""}${s.model}${s.effort ? ` · ${s.effort}` : ""}` : "";
         const where = s?.worktree?.path ? `${this.shortPath(s.worktree.path)}${s.worktree.riftri ? " · riftri" : ""}` : s ? "this checkout" : "";
-        const status = s?.state === "paused" ? "  paused" : s?.queue.length ? `  ${this.icons.queued}${s.queue.length} queued` : "";
+        const ext = s && "extensionStatus" in s ? [...s.extensionStatus.values()].join(" · ") : "";
+        const status = (s?.state === "paused" ? "  paused" : s?.queue.length ? `  ${this.icons.queued}${s.queue.length} queued` : "") + (ext ? `  ${ext}` : "");
         // the path gives way first (from its start: the end names the worktree), always two spaces before it
         const pathRoom = w - visibleWidth(left) - visibleWidth(model) - visibleWidth(status) - 3;
         const shownWhere = !where ? "" : visibleWidth(where) <= pathRoom ? where : pathRoom > 4 ? `…${where.slice(where.length - pathRoom + 1)}` : "";
@@ -2177,6 +2675,7 @@ export class App {
                 [glyphGroup, `${glyph} `],
                 [focused ? "Title" : "VigentSidebar", s.name],
                 ["Comment", s.queue.length > 0 ? ` ${I.queued}${s.queue.length}` : ""],
+                [s.state === "error" ? "ErrorMsg" : "WarningMsg", this.unread.has(s) ? ` ${I.unread}` : ""],
             ], rowBg));
             const model = s.model.replace(/^claude-/, "");
             const indent = [
@@ -2217,7 +2716,7 @@ export class App {
                         ? e.id === def
                             ? "default"
                             : ""
-                        : e.id === "pi"
+                        : e.id === "pi" && e.installed
                             ? "no API key"
                             : e.installed
                                 ? (e.connect ?? "not signed in")
@@ -2264,7 +2763,14 @@ export class App {
                 case "user": {
                     push("", "");
                     wrapTextWithAnsi(item.text, paneW - 2).forEach((l, i) => {
-                        push(P.p("VigentUser", I.prompt) + P.s("Normal") + P.p("Keyword", l), I.prompt + stripAnsi(l), {
+                        const painted = l
+                            .replace(MENTION, (m) => `\0${m}\0`)
+                            .split("\0")
+                            .map((part, i) => (!part ? "" : P.p(i % 2 ? "VigentMention" : "Keyword", part)))
+                            .join("");
+                        // the ❯ marks where a prompt starts; its other lines hang under it
+                        const lead = i === 0 ? I.prompt : " ".repeat(visibleWidth(I.prompt));
+                        push(P.p("VigentUser", lead) + P.s("Normal") + painted, lead + stripAnsi(l), {
                             item: n,
                             start: i === 0,
                         });
@@ -2318,8 +2824,10 @@ export class App {
         const changes = st && (st.added || st.removed) ? ` +${st.added} ${this.icons.minus}${st.removed}` : "";
         const worktree = s?.worktree ? `${this.icons.worktree}${s.worktree.branch}${changes} ` : "";
         const right = s
-            ? ` ${s.model}  ${formatTokens(s.tokens)}  ${running}/${this.sessions.length}${running > 0 ? ` ${this.spinner()}` : ""} `
-            : "";
+            ? ` ${this.server ? this.icons.serve : ""}${s.model}  ${formatUsage(s)}  ${running}/${this.sessions.length}${running > 0 ? ` ${this.spinner()}` : ""} `
+            : this.server
+                ? ` ${this.icons.serve}serving `
+                : "";
         const plainLen = visibleWidth(` ${this.mode} `) + (this.demo ? 6 : 0) + visibleWidth(leftText) + visibleWidth(worktree) + visibleWidth(right);
         const fill = Math.max(0, width - plainLen);
         return (modeBadge +
@@ -2429,19 +2937,25 @@ function describeRhs(rhs) {
 }
 const EX_HELP = [
     [":new [task]", "start an agent in its own worktree"],
+    [":new -t <template> <task>", "start one from a template and send it (:templates picks)"],
     [":kill  /  :kill!", "stop the agent (keep / remove its worktree)"],
     [":new! [name]", "agent in this checkout, no worktree"],
     [":diff  /  :diff split", "the agent's changes, unified / side by side (s switches)"],
+    [":review", "keep or drop the agent's changes hunk by hunk"],
     [":merge [--no-squash]", "squash-merge the agent's branch into yours"],
     [":pr", "push the branch and open a pull request"],
     [":queue <prompt>", "send after the current run (:queue lists)"],
     [":pause  /  :resume", "hold the agent and its queue / continue"],
     [":dash", "all agents at a glance"],
+    [":cost", "tokens and money each agent has used, and the total"],
+    [":pi", "a pi agent's extensions, commands, skills and prompt templates"],
+    [":serve  /  :serve stop", "follow and prompt your agents from your phone (local: this machine only)"],
     [":tree", "the conversation's branches; go back and branch"],
     [":new [task] --engine claude", "run the agent with Claude Code, codex, opencode or pi"],
     [":checkhealth", "which engines are installed and signed in"],
     [":model [name]", "pick the agent's model (no agent: for new agents)"],
     [":effort [level]", "pick its reasoning effort: low … max (pi: thinking level)"],
+    [":engine [name]", "pick the engine new agents run on: auto, pi, claude, codex, opencode"],
     [":settings", "theme, look, engine, worktrees and keys in one place (w saves)"],
     [":w [file]", "save the transcript as Markdown"],
     [":worktrees", "list agent worktrees"],
@@ -2485,11 +2999,39 @@ function describeAttr(a) {
         parts.push(`gui=${flags.join(",")}`);
     return parts.join(" ") || "cleared";
 }
-function formatTokens(n) {
+export function formatTokens(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M tok`;
     if (n >= 1000)
         return `${(n / 1000).toFixed(1)}k tok`;
     return `${n} tok`;
 }
+/** US dollars: cents, or a tenth of a cent below one cent */
+export function formatCost(usd) {
+    if (usd > 0 && usd < 0.01)
+        return `$${usd.toFixed(3)}`;
+    return `$${usd.toFixed(2)}`;
+}
+/** "12.4k tok · $0.31", or just the tokens when the engine reports no price */
+export function formatUsage(u) {
+    return u.cost === undefined ? formatTokens(u.tokens) : `${formatTokens(u.tokens)} · ${formatCost(u.cost)}`;
+}
+/** every agent's usage added up; cost counts the agents that report one */
+export function totalUsage(sessions) {
+    let tokens = 0;
+    let cost;
+    let unpriced = 0;
+    for (const s of sessions) {
+        tokens += s.tokens;
+        if (s.cost === undefined) {
+            if (s.tokens)
+                unpriced++;
+        }
+        else
+            cost = (cost ?? 0) + s.cost;
+    }
+    return { tokens, cost, unpriced };
+}
 /** A short agent name from a prompt: its first words, without punctuation ("Fix the flaky checkout test, please" -> "fix the flaky checkout test"). */
 export function agentNameFrom(prompt) {
     const words = prompt
@@ -2516,10 +3058,12 @@ const LOGO = [
 const DASHBOARD = [
     ["i", "✎", "New agent: type a task, Enter", NERD.pencil],
     ["n", "+", "New agent by name", NERD.plus],
+    ["T", "▤", "New agent from a template", NERD.fileText],
     ["t", "◐", "Theme", NERD.palette],
     ["s", "⚙", "Settings", NERD.gear],
     ["m", "◆", "Model", NERD.chip],
     ["e", "↯", "Effort", NERD.bolt],
+    ["E", "⚑", "Engine: pi, Claude Code, Codex, OpenCode", NERD.wrench],
     ["c", "✓", "Check engines", NERD.check],
     ["?", "⌘", "Keys", NERD.keyboard],
     ["q", "×", "Quit", NERD.power],