wispy-cli 2.7.27 → 2.7.29

package/lib/wispy-tui-v3.mjs

@@ -0,0 +1,1236 @@
+#!/usr/bin/env node
+/**
+ * wispy-tui-v3.mjs — pi-tui based TUI for Wispy
+ *
+ * Replaces the Ink/React TUI with @mariozechner/pi-tui for proper CJK/Korean IME support.
+ * pi-tui uses differential rendering and positions the hardware cursor via CURSOR_MARKER
+ * so the OS IME candidate window appears at the correct location.
+ */
+
+import {
+  TUI, Container, Box, Text, Editor, Markdown, Loader,
+  Spacer, ProcessTerminal, Key, matchesKey, isKeyRelease,
+} from "@mariozechner/pi-tui";
+
+import chalk from "chalk";
+import path from "node:path";
+import { readFile, writeFile, readdir, stat, mkdir } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+
+import {
+  WispyEngine,
+  CONVERSATIONS_DIR,
+  PROVIDERS,
+  WISPY_DIR,
+  MEMORY_DIR,
+} from "../core/index.mjs";
+
+// ─── Version ──────────────────────────────────────────────────────────────────
+
+let PKG_VERSION = "?";
+try {
+  const __dirname = path.dirname(fileURLToPath(import.meta.url));
+  const pkgPath = path.join(__dirname, "..", "package.json");
+  PKG_VERSION = JSON.parse(await readFile(pkgPath, "utf8")).version ?? "?";
+} catch {}
+
+// ─── CLI args ─────────────────────────────────────────────────────────────────
+
+const rawArgs = process.argv.slice(2);
+const wsIdx = rawArgs.findIndex((a) => a === "-w" || a === "--workstream");
+const INITIAL_WORKSTREAM =
+  process.env.WISPY_WORKSTREAM ??
+  (wsIdx !== -1 ? rawArgs[wsIdx + 1] : null) ??
+  "default";
+
+// ─── Constants ────────────────────────────────────────────────────────────────
+
+const VIEWS = ["chat", "overview", "agents", "memory", "audit", "settings"];
+const SIDEBAR_WIDTH = 20;
+
+const TOOL_ICONS = {
+  read_file: "[file]", write_file: "[edit]", file_edit: "[edit]",
+  run_command: "[exec]", git: "[git]", web_search: "[search]",
+  web_fetch: "[web]", list_directory: "[dir]", spawn_subagent: "[sub]",
+  spawn_agent: "[agent]", memory_save: "[save]", memory_search: "[find]",
+  memory_list: "[list]", delete_file: "[delete]", node_execute: "[run]",
+  update_work_context: "[update]",
+};
+
+// ─── Theme ────────────────────────────────────────────────────────────────────
+
+const C = {
+  green:   (s) => chalk.green(s),
+  cyan:    (s) => chalk.cyan(s),
+  yellow:  (s) => chalk.yellow(s),
+  red:     (s) => chalk.red(s),
+  blue:    (s) => chalk.blue(s),
+  magenta: (s) => chalk.magenta(s),
+  white:   (s) => chalk.white(s),
+  dim:     (s) => chalk.dim(s),
+  bold:    (s) => chalk.bold(s),
+  bgGreen: (s) => chalk.bgGreen.black(s),
+  bgYellow:(s) => chalk.bgYellow.black(s),
+};
+
+const editorTheme = {
+  borderColor: (s) => chalk.dim(s),
+  selectList: {
+    itemText: (s, selected) => selected ? chalk.bold(chalk.cyan(s)) : s,
+    selectedText: (s) => chalk.bold(chalk.cyan(s)),
+    description: (s) => chalk.dim(s),
+    matchHighlight: (s) => chalk.bold(chalk.yellow(s)),
+    cursor: chalk.cyan("→ "),
+    scrollInfo: (s) => chalk.dim(s),
+    noMatch: (s) => chalk.dim(s),
+    filterLabel: (s) => chalk.dim(s),
+    searchPrompt: (s) => chalk.dim(s),
+    searchInput: (s) => s,
+  },
+};
+
+const markdownTheme = {
+  heading:        (s) => chalk.bold(chalk.cyan(s)),
+  link:           (s) => chalk.cyan(s),
+  linkUrl:        (s) => chalk.dim(s),
+  code:           (s) => chalk.yellow(s),
+  codeBlock:      (s) => chalk.white(s),
+  codeBlockBorder:(s) => chalk.dim(s),
+  quote:          (s) => chalk.dim(s),
+  quoteBorder:    (s) => chalk.dim(s),
+  hr:             (s) => chalk.dim(s),
+  listBullet:     (s) => chalk.green(s),
+  bold:           (s) => chalk.bold(s),
+  italic:         (s) => chalk.italic(s),
+  strikethrough:  (s) => chalk.strikethrough(s),
+  underline:      (s) => chalk.underline(s),
+};
+
+// ─── Utilities ────────────────────────────────────────────────────────────────
+
+function fmtTime(iso) {
+  if (!iso) return "";
+  try {
+    return new Date(iso).toLocaleTimeString("en-US", {
+      hour12: false, hour: "2-digit", minute: "2-digit",
+    });
+  } catch { return ""; }
+}
+
+function fmtRelTime(iso) {
+  if (!iso) return "";
+  try {
+    const diff = Date.now() - new Date(iso).getTime();
+    if (diff < 60_000)     return "just now";
+    if (diff < 3_600_000)  return `${Math.floor(diff / 60_000)}min ago`;
+    if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}hr ago`;
+    return "yesterday";
+  } catch { return ""; }
+}
+
+function fmtDuration(ms) {
+  if (!ms || ms < 0) return "";
+  if (ms < 1000)     return `${ms}ms`;
+  if (ms < 60_000)   return `${(ms / 1000).toFixed(1)}s`;
+  return `${Math.floor(ms / 60_000)}m${Math.floor((ms % 60_000) / 1000)}s`;
+}
+
+function truncate(str, n) {
+  if (!str) return "";
+  return str.length > n ? str.slice(0, n - 1) + "…" : str;
+}
+
+function padRight(str, n) {
+  // visible-width pad (naive, good enough for ASCII+labels)
+  const visible = str.replace(/\x1b\[[^m]*m/g, "").replace(/\x1b_pi:c\x07/g, "");
+  const need = n - visible.length;
+  return str + (need > 0 ? " ".repeat(need) : "");
+}
+
+// ─── Persistence helpers ──────────────────────────────────────────────────────
+
+async function loadConversation(workstream) {
+  const file = path.join(CONVERSATIONS_DIR, `${workstream}.json`);
+  try {
+    const raw = await readFile(file, "utf8");
+    return JSON.parse(raw);
+  } catch { return []; }
+}
+
+async function saveConversation(workstream, messages) {
+  await mkdir(CONVERSATIONS_DIR, { recursive: true });
+  const file = path.join(CONVERSATIONS_DIR, `${workstream}.json`);
+  await writeFile(
+    file,
+    JSON.stringify(messages.slice(-50), null, 2) + "\n",
+    "utf8"
+  );
+}
+
+// ─── Data loaders ─────────────────────────────────────────────────────────────
+
+async function loadWorkstreams() {
+  try {
+    const wsDir = path.join(WISPY_DIR, "workstreams");
+    const dirs = await readdir(wsDir);
+    const result = [];
+    for (const d of dirs) {
+      try {
+        const s = await stat(path.join(wsDir, d));
+        if (s.isDirectory()) result.push(d);
+      } catch {}
+    }
+    return result.length ? result : ["default"];
+  } catch { return ["default"]; }
+}
+
+async function loadMemoryFiles() {
+  try {
+    const files = await readdir(MEMORY_DIR);
+    const result = [];
+    for (const f of files) {
+      if (!f.endsWith(".md")) continue;
+      const fp = path.join(MEMORY_DIR, f);
+      try {
+        const s = await stat(fp);
+        const raw = await readFile(fp, "utf8");
+        result.push({
+          key: f.replace(".md", ""),
+          preview: raw.split("\n").find(l => l.trim() && !l.startsWith("_")) ?? "",
+          size: s.size,
+          updatedAt: s.mtime.toISOString(),
+        });
+      } catch {}
+    }
+    return result;
+  } catch { return []; }
+}
+
+async function loadOverviewData(workstreams) {
+  const result = {};
+  for (const ws of workstreams) {
+    try {
+      const convFile = path.join(CONVERSATIONS_DIR, `${ws}.json`);
+      const raw = await readFile(convFile, "utf8");
+      const conv = JSON.parse(raw);
+      const lastMsg = conv.filter(m => m.role === "assistant").pop();
+      const fileStat = await stat(convFile).catch(() => null);
+      result[ws] = {
+        lastActivity: fileStat?.mtime?.toISOString() ?? null,
+        lastMessage: lastMsg?.content?.slice(0, 80) ?? null,
+        agents: 0,
+      };
+    } catch {
+      result[ws] = { lastActivity: null, lastMessage: null, agents: 0 };
+    }
+    try {
+      const workMdPath = path.join(WISPY_DIR, "workstreams", ws, "work.md");
+      const wmd = await readFile(workMdPath, "utf8");
+      result[ws].workMd = wmd.split("\n").find(l => l.trim())?.slice(0, 60);
+    } catch {}
+  }
+  return result;
+}
+
+async function loadAgents() {
+  try {
+    const agentsFile = path.join(WISPY_DIR, "agents.json");
+    const raw = await readFile(agentsFile, "utf8");
+    const all = JSON.parse(raw);
+    return all.filter(a =>
+      ["running","pending","completed","done"].includes(a.status)
+    ).slice(-10);
+  } catch { return []; }
+}
+
+// ─── Custom components ────────────────────────────────────────────────────────
+
+/**
+ * A simple component that renders pre-built lines (strings[]).
+ */
+class RawLines {
+  constructor() {
+    this._lines = [];
+  }
+  setLines(lines) { this._lines = lines; }
+  invalidate() {}
+  render(_width) { return this._lines; }
+}
+
+/**
+ * ScrollableContent — wraps a Container-like set of lines with vertical scrolling.
+ * We render the full content and then slice to visible height.
+ */
+class ScrollableContent {
+  constructor() {
+    this._lines = [];
+    this._scrollTop = 0;
+    this._height = 20;
+  }
+
+  setLines(lines) {
+    this._lines = lines;
+    // Auto-scroll to bottom
+    this._scrollTop = Math.max(0, this._lines.length - this._height);
+  }
+
+  setHeight(h) {
+    this._height = h;
+    this._scrollTop = Math.max(0, this._lines.length - this._height);
+  }
+
+  scrollUp()   { this._scrollTop = Math.max(0, this._scrollTop - 3); }
+  scrollDown() { this._scrollTop = Math.min(Math.max(0, this._lines.length - this._height), this._scrollTop + 3); }
+
+  invalidate() {}
+
+  render(width) {
+    const visible = this._lines.slice(this._scrollTop, this._scrollTop + this._height);
+    // Pad to height
+    while (visible.length < this._height) visible.push("");
+    return visible;
+  }
+}
+
+// ─── WispyTUI — main class ────────────────────────────────────────────────────
+
+class WispyTUI {
+  constructor() {
+    this.terminal = new ProcessTerminal();
+    this.tui = new TUI(this.terminal, true); // true = show hardware cursor
+
+    this.engine = null;
+    this.messages = [];         // { role: "user"|"assistant"|"system_info", content }
+    this.timeline = [];         // tool call events
+    this.loading = false;
+    this.view = "chat";
+
+    // Sidebar state
+    this.workstreams = [INITIAL_WORKSTREAM];
+    this.activeWorkstream = INITIAL_WORKSTREAM;
+    this.memoryFiles = [];
+    this.agents = [];
+    this.budgetSpent = 0;
+    this.maxBudget = null;
+    this.browserStatus = null;
+
+    // Overview
+    this.overviewData = {};
+
+    // Conversation ref for persistence
+    this._conversation = [];
+
+    // Pending approval
+    this._approvalResolver = null;
+    this._pendingApproval = null;
+
+    // Components
+    this.statusBarText = null;
+    this.sidebarLines = null;
+    this.mainContent = null;
+    this.inputEditor = null;
+    this.loaderComp = null;
+    this.mainScrollable = null;
+
+    // Refresh intervals
+    this._intervals = [];
+  }
+
+  // ─── Init ──────────────────────────────────────────────────────────────────
+
+  async init() {
+    this.engine = new WispyEngine({ workstream: this.activeWorkstream });
+    const ok = await this.engine.init();
+    if (!ok) {
+      console.error("No API key found. Run `wispy setup` first.");
+      process.exit(1);
+    }
+
+    // Load initial conversation
+    this._conversation = await loadConversation(this.activeWorkstream);
+    this.messages = this._conversation.map(m => ({ ...m }));
+
+    // Load sidebar data
+    await this._refreshSidebarData();
+
+    // Build UI
+    this._buildUI();
+
+    // Wire engine events
+    this._wireEngineEvents();
+
+    // Set up approval handler
+    this.engine.permissions.setApprovalHandler(async (action) => {
+      return new Promise((resolve) => {
+        this._approvalResolver = resolve;
+        this._pendingApproval = action;
+        this._updateMainContent();
+        this.tui.requestRender();
+      });
+    });
+
+    // Periodic refresh
+    const sid1 = setInterval(() => this._refreshSidebarData().then(() => this.tui.requestRender()), 15_000);
+    const sid2 = setInterval(() => this._refreshAgents().then(() => this.tui.requestRender()), 10_000);
+    this._intervals.push(sid1, sid2);
+
+    // Initial render
+    this._updateAll();
+    this.tui.requestRender();
+  }
+
+  // ─── UI build ─────────────────────────────────────────────────────────────
+
+  _buildUI() {
+    const tui = this.tui;
+
+    // Root container (vertical stack)
+    const root = new Container();
+
+    // 1. Status bar
+    this.statusBarText = new Text("", 0, 0, (line) => chalk.bgGreen.black(line));
+    root.addChild(this.statusBarText);
+
+    // 2. Content area (sidebar + main)
+    // We'll render it as a custom component that does column layout
+    this.contentArea = new ContentArea(this);
+    root.addChild(this.contentArea);
+
+    // 3. Loader (hidden by default, shown when loading)
+    this.loaderComp = new Loader(
+      tui,
+      (s) => chalk.yellow(s),
+      (s) => chalk.dim(s),
+      " thinking..."
+    );
+
+    // 4. Input editor
+    this.inputEditor = new WispyEditor(tui, editorTheme, this);
+
+    // Initially loader is not added — we add/remove dynamically
+    root.addChild(this.inputEditor);
+
+    tui.addChild(root);
+    tui.setFocus(this.inputEditor);
+
+    this._root = root;
+    this._loaderActive = false;
+  }
+
+  _setLoaderActive(active) {
+    if (active === this._loaderActive) return;
+    this._loaderActive = active;
+    const root = this._root;
+    // Remove all except statusBar and contentArea
+    root.clear();
+    root.addChild(this.statusBarText);
+    root.addChild(this.contentArea);
+    if (active) {
+      this.loaderComp.start();
+      root.addChild(this.loaderComp);
+    } else {
+      this.loaderComp.stop();
+    }
+    root.addChild(this.inputEditor);
+  }
+
+  // ─── Data refresh ─────────────────────────────────────────────────────────
+
+  async _refreshSidebarData() {
+    const [wsList, memFiles] = await Promise.all([
+      loadWorkstreams(),
+      loadMemoryFiles(),
+    ]);
+    const wsSet = new Set(wsList);
+    wsSet.add(this.activeWorkstream);
+    this.workstreams = Array.from(wsSet);
+    this.memoryFiles = memFiles;
+
+    try {
+      this.browserStatus = this.engine?.browser?.status?.() ?? null;
+    } catch {}
+    try {
+      const bud = this.engine?.budget;
+      if (bud) {
+        this.budgetSpent = bud.sessionSpend ?? 0;
+        this.maxBudget = bud.maxBudgetUsd ?? null;
+      }
+    } catch {}
+  }
+
+  async _refreshAgents() {
+    this.agents = await loadAgents();
+  }
+
+  // ─── Engine events ─────────────────────────────────────────────────────────
+
+  _wireEngineEvents() {
+    const harness = this.engine?.harness;
+    if (!harness) return;
+
+    harness.on("tool:start", ({ toolName, args }) => {
+      const primaryArg = args?.path ?? args?.command ?? args?.query ?? args?.task ?? args?.key ?? "";
+      this.timeline.push({
+        toolName, args, primaryArg,
+        timestamp: new Date().toISOString(),
+        success: null, denied: false,
+      });
+      this._updateMainContent();
+      this.tui.requestRender();
+    });
+
+    harness.on("tool:complete", ({ toolName, receipt }) => {
+      for (let i = this.timeline.length - 1; i >= 0; i--) {
+        if (this.timeline[i].toolName === toolName && this.timeline[i].success === null) {
+          this.timeline[i] = { ...this.timeline[i], success: receipt?.success ?? true };
+          break;
+        }
+      }
+      this._updateMainContent();
+      this.tui.requestRender();
+    });
+
+    harness.on("tool:denied", ({ toolName }) => {
+      for (let i = this.timeline.length - 1; i >= 0; i--) {
+        if (this.timeline[i].toolName === toolName && this.timeline[i].success === null) {
+          this.timeline[i] = { ...this.timeline[i], success: false, denied: true };
+          break;
+        }
+      }
+      this._updateMainContent();
+      this.tui.requestRender();
+    });
+  }
+
+  // ─── Content rendering ─────────────────────────────────────────────────────
+
+  _updateAll() {
+    this._updateStatusBar();
+    this._updateMainContent();
+  }
+
+  _updateStatusBar() {
+    const ws = this.activeWorkstream;
+    const model = this.engine?.model ?? "?";
+    const permMode = this.engine?.permissions?.getPolicy?.("run_command") ?? "approve";
+    const cost = this.budgetSpent;
+    const costStr = cost > 0 ? `  $${cost.toFixed(4)}` : "";
+    const viewStr = `[${this.view.toUpperCase()}]  ? for help`;
+    this.statusBarText.setText(
+      ` Wispy ─ ${ws} ─ ${truncate(model, 20)} ─ ${permMode}${costStr}  ${viewStr}`
+    );
+  }
+
+  /**
+   * Build sidebar lines (returns string[])
+   */
+  _buildSidebarLines(sidebarWidth) {
+    const lines = [];
+    const w = sidebarWidth;
+
+    const div = "─".repeat(w);
+
+    // WORKSTREAMS
+    lines.push(C.dim(" WORKSTREAMS"));
+    for (const ws of this.workstreams) {
+      const isActive = ws === this.activeWorkstream;
+      const indicator = isActive ? C.green("●") : C.dim("◯");
+      const label = truncate(ws, w - 3);
+      const line = ` ${indicator} ${isActive ? C.bold(label) : C.dim(label)}`;
+      lines.push(line);
+    }
+
+    lines.push(C.dim(div));
+
+    // AGENTS
+    lines.push(`${C.dim(" AGENTS  ")}${this.agents.length > 0 ? C.yellow(String(this.agents.length)) : C.dim("0")}`);
+    if (this.agents.length === 0) {
+      lines.push(C.dim("  (none)"));
+    } else {
+      for (const a of this.agents.slice(0, 3)) {
+        const isRunning = a.status === "running";
+        const dot = isRunning ? C.green("●") : C.dim("◯");
+        lines.push(` ${dot} ${truncate(a.label ?? a.role ?? "agent", w - 4)}`);
+      }
+    }
+
+    lines.push(C.dim(div));
+
+    // MEMORY
+    lines.push(`${C.dim(" MEMORY  ")}${C.cyan(String(this.memoryFiles.length))}`);
+
+    lines.push(C.dim(div));
+
+    // BROWSER
+    lines.push(C.dim(" BROWSER"));
+    if (this.browserStatus?.session) {
+      lines.push(` ${C.green("●")} ${truncate(this.browserStatus.session.browser ?? "connected", w - 4)}`);
+    } else {
+      lines.push(C.dim(" ◯ off"));
+    }
+
+    lines.push(C.dim(div));
+
+    // BUDGET
+    lines.push(C.dim(" BUDGET"));
+    lines.push(
+      this.budgetSpent > 0
+        ? ` ${C.yellow(`$${this.budgetSpent.toFixed(3)}${this.maxBudget ? `/$${this.maxBudget.toFixed(2)}` : ""}`)}`
+        : C.dim(" $0.000")
+    );
+
+    return lines;
+  }
+
+  /**
+   * Build main content lines for current view (returns string[])
+   */
+  _buildMainContentLines(mainWidth) {
+    switch (this.view) {
+      case "chat":     return this._buildChatLines(mainWidth);
+      case "overview": return this._buildOverviewLines(mainWidth);
+      case "agents":   return this._buildAgentsLines(mainWidth);
+      case "memory":   return this._buildMemoryLines(mainWidth);
+      case "audit":    return this._buildAuditLines(mainWidth);
+      case "settings": return this._buildSettingsLines(mainWidth);
+      default:         return this._buildChatLines(mainWidth);
+    }
+  }
+
+  _buildChatLines(width) {
+    const lines = [];
+
+    if (this._pendingApproval) {
+      return this._buildApprovalLines(width);
+    }
+
+    if (this.messages.length === 0) {
+      lines.push("");
+      lines.push(C.dim("  Wispy — AI workspace assistant"));
+      lines.push(C.dim("  Type a message to start. ? for help."));
+      return lines;
+    }
+
+    const display = this.messages.slice(-30);
+    for (const msg of display) {
+      if (msg.role === "user") {
+        lines.push("");
+        lines.push(` ${C.green(C.bold("you ›"))} ${msg.content}`);
+      } else if (msg.role === "assistant") {
+        lines.push("");
+        lines.push(C.cyan(C.bold(" wispy ›")));
+        // Simple markdown rendering using plain text (full Markdown component used in content area)
+        const msgLines = msg.content.split("\n");
+        for (const l of msgLines) {
+          if (l.startsWith("# "))       lines.push(`  ${C.bold(C.cyan(l.slice(2)))}`);
+          else if (l.startsWith("## ")) lines.push(`  ${C.bold(C.blue(l.slice(3)))}`);
+          else if (l.startsWith("### "))lines.push(`  ${C.bold(l.slice(4))}`);
+          else if (l.startsWith("- ") || l.startsWith("* ")) lines.push(`  ${C.green("•")} ${l.slice(2)}`);
+          else if (l.startsWith("```")) lines.push(`  ${C.dim(l)}`);
+          else if (l.includes("**"))    lines.push("  " + l.replace(/\*\*([^*]+)\*\*/g, (_, t) => C.bold(t)));
+          else if (l === "")            lines.push("");
+          else                          lines.push("  " + l);
+        }
+      } else if (msg.role === "tool_call") {
+        const icon = TOOL_ICONS[msg.name] ?? "[tool]";
+        const status = msg.receipt
+          ? (msg.receipt.success ? C.green("✓") : C.red("✗"))
+          : C.yellow("●");
+        const arg = msg.args?.path ?? msg.args?.command ?? msg.args?.query ?? "";
+        lines.push(`   ${status} ${C.cyan(`${icon} ${msg.name}`)}${arg ? C.dim(` → ${truncate(arg, 35)}`) : ""}`);
+      } else if (msg.role === "system_info") {
+        lines.push(C.dim(`  ℹ ${msg.content}`));
+      }
+    }
+
+    return lines;
+  }
+
+  _buildApprovalLines(width) {
+    const action = this._pendingApproval;
+    const lines = [];
+    lines.push("");
+    lines.push(C.yellow("  ! Permission Required"));
+    lines.push("");
+    lines.push(`  ${C.dim("Tool:   ")} ${C.bold(action.toolName ?? "?")}`);
+    const arg = action.args?.command ?? action.args?.path ?? JSON.stringify(action.args ?? {}).slice(0, 50);
+    if (arg) lines.push(`  ${C.dim("Action: ")} ${truncate(arg, width - 14)}`);
+    lines.push("");
+    lines.push(`  ${C.green(C.bold("[Y] Approve"))}  ${C.red(C.bold("[N] Deny"))}  ${C.cyan(C.bold("[D] Dry-run"))}`);
+    lines.push("");
+    return lines;
+  }
+
+  _buildOverviewLines(mainWidth) {
+    const lines = [];
+    lines.push(`  ${C.bold(C.green("Workstream Overview"))}`);
+    lines.push("");
+    lines.push(`  ${C.bold(C.cyan("Browser"))}`);
+    if (this.browserStatus?.session) {
+      lines.push(`    ${C.green("●")} Connected — ${this.browserStatus.session.browser ?? "unknown"}`);
+    } else {
+      lines.push(C.dim("    ◯ Not connected"));
+    }
+    lines.push("");
+    lines.push("  " + C.dim("─".repeat(Math.min(40, mainWidth - 4))));
+    lines.push("");
+    for (const ws of this.workstreams) {
+      const data = this.overviewData[ws] ?? {};
+      const isActive = ws === this.activeWorkstream;
+      const dot = isActive ? C.green("●") : C.dim("◯");
+      const wsLabel = isActive ? C.bold(C.green(ws)) : ws;
+      const rel = data.lastActivity ? C.dim(`  ${fmtRelTime(data.lastActivity)}`) : "";
+      lines.push(`  ${dot} ${wsLabel}${rel}`);
+      if (data.lastMessage) {
+        lines.push(`    ${C.dim("└── ")}${truncate(data.lastMessage, mainWidth - 10)}`);
+      }
+      if (data.workMd) {
+        lines.push(`    ${C.dim("└── ")}${C.dim(`"${truncate(data.workMd, mainWidth - 20)}"`)}`);
+      }
+      lines.push("");
+    }
+    return lines;
+  }
+
+  _buildAgentsLines(mainWidth) {
+    const lines = [];
+    lines.push(`  ${C.bold(C.green("Sub-Agents"))}`);
+    lines.push("");
+    if (this.agents.length === 0) {
+      lines.push(C.dim("  No sub-agents recorded."));
+      return lines;
+    }
+    const running = this.agents.filter(a => a.status === "running");
+    const done = this.agents.filter(a => ["completed","done"].includes(a.status));
+    lines.push(`  ${running.length} running, ${done.length} completed`);
+    lines.push("");
+    for (const a of this.agents) {
+      const color = a.status === "running" ? C.green : a.status === "pending" ? C.yellow : C.dim;
+      const icon = a.status === "running" ? "●" : a.status === "completed" || a.status === "done" ? "✓" : "◯";
+      lines.push(`  ${color(icon + " " + truncate(a.label ?? a.id ?? "agent", 20))}  ${C.dim(`[${a.model ?? "?"}]`)}`);
+      if (a.task) lines.push(`     ${C.dim(truncate(a.task, 60))}`);
+      lines.push("");
+    }
+    return lines;
+  }
+
+  _buildMemoryLines(mainWidth) {
+    const lines = [];
+    lines.push(`  ${C.bold(C.green("Memory Files"))} ${C.dim(`(${this.memoryFiles.length})`)}`);
+    lines.push("");
+    if (this.memoryFiles.length === 0) {
+      lines.push(C.dim("  No memory files found."));
+      return lines;
+    }
+    for (const f of this.memoryFiles.slice(0, 20)) {
+      const size = f.size ? C.dim(`  (${(f.size / 1024).toFixed(1)}KB)`) : "";
+      const rel = f.updatedAt ? C.dim(`  ${fmtRelTime(f.updatedAt)}`) : "";
+      lines.push(`  ${C.cyan(f.key)}${size}${rel}`);
+      if (f.preview) lines.push(`    ${C.dim(truncate(f.preview, mainWidth - 6))}`);
+    }
+    return lines;
+  }
+
+  _buildAuditLines(mainWidth) {
+    const lines = [];
+    lines.push(`  ${C.bold(C.green("Action Timeline"))}`);
+    lines.push("");
+    if (this.timeline.length === 0) {
+      lines.push(C.dim("  No actions recorded yet."));
+      return lines;
+    }
+    for (const evt of [...this.timeline].reverse().slice(0, 30)) {
+      const icon = TOOL_ICONS[evt.toolName] ?? "[tool]";
+      const statusIcon = evt.denied ? "✗" : evt.success ? "✓" : "●";
+      const color = evt.denied ? C.red : evt.success ? C.green : C.yellow;
+      const ts = fmtTime(evt.timestamp);
+      const arg = evt.primaryArg ? C.dim(` → ${truncate(evt.primaryArg, 25)}`) : "";
+      lines.push(`  ${C.dim(ts)} ${C.dim(icon)} ${C.cyan(evt.toolName)}${arg} ${color(statusIcon)}`);
+    }
+    return lines;
+  }
+
+  _buildSettingsLines(mainWidth) {
+    const lines = [];
+    lines.push(`  ${C.bold(C.green("Settings"))}`);
+    lines.push("");
+    lines.push(`  ${C.bold(C.cyan("General"))}`);
+    const entries = [
+      ["Version",    PKG_VERSION],
+      ["Config dir", path.join(process.env.HOME ?? "~", ".wispy")],
+      ["Provider",   this.engine?.provider ?? "?"],
+      ["Model",      this.engine?.model ?? "?"],
+      ["Security",   this.engine?.permissions?.getPolicy?.("run_command") ?? "approve"],
+      ["Workstream", this.activeWorkstream],
+    ];
+    for (const [k, v] of entries) {
+      lines.push(`    ${C.dim(k.padEnd(14))} ${v ?? "?"}`);
+    }
+    lines.push("");
+    lines.push(`  ${C.bold(C.cyan("Budget"))}`);
+    lines.push(`    ${C.dim("Spent".padEnd(14))} ${this.budgetSpent > 0 ? C.yellow(`$${this.budgetSpent.toFixed(4)}`) : "$0.0000"}${this.maxBudget ? ` / $${this.maxBudget.toFixed(2)}` : ""}`);
+    lines.push("");
+    lines.push(`  ${C.bold(C.cyan("Browser"))}`);
+    if (this.browserStatus?.session) {
+      lines.push(`    ${C.green("●")} connected (${this.browserStatus.session.browser ?? "unknown"})`);
+    } else {
+      lines.push(C.dim("    ◯ disconnected"));
+    }
+    lines.push("");
+    lines.push(C.dim("  Commands: /model <n>  /trust <level>  /agent <n>  /cost  /clear"));
+    return lines;
+  }
+
+  _buildHelpLines() {
+    return [
+      "",
+      `  ${C.bold(C.cyan("Wispy — Keyboard Shortcuts"))}`,
+      "",
+      `  ${C.yellow("Tab")}           Switch view`,
+      `  ${C.yellow("1-6")}           Jump to view (1=chat 2=overview 3=agents 4=memory 5=audit 6=settings)`,
+      `  ${C.yellow("Ctrl+C")}        Quit`,
+      `  ${C.yellow("Ctrl+L")}        Clear chat`,
+      `  ${C.yellow("PgUp/PgDn")}     Scroll content`,
+      "",
+      `  ${C.yellow("/help")}         Show this help`,
+      `  ${C.yellow("/model <n>")}    Change model`,
+      `  ${C.yellow("/trust <lvl>")}  Change security level`,
+      `  ${C.yellow("/agent <n>")}    Switch agent`,
+      `  ${C.yellow("/cost")}         Show budget`,
+      `  ${C.yellow("/clear")}        Clear conversation`,
+      `  ${C.yellow("/ws <name>")}    Switch workstream`,
+      `  ${C.yellow("/quit")}         Quit`,
+      "",
+      `  ${C.dim("Press Esc or type /help again to close")}`,
+    ];
+  }
+
+  _updateMainContent() {
+    // Signal to ContentArea that content needs rebuild on next render
+    this.contentArea?.invalidate();
+  }
+
+  // ─── Submit / command handling ─────────────────────────────────────────────
+
+  async handleSubmit(text) {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+
+    // Handle pending approval
+    if (this._pendingApproval) {
+      const ch = trimmed.toLowerCase();
+      if (ch === "y" || ch === "yes") {
+        this._approvalResolver?.(true);
+        this._approvalResolver = null;
+        this._pendingApproval = null;
+        this._updateMainContent();
+        this.tui.requestRender();
+      } else if (ch === "n" || ch === "no") {
+        this._approvalResolver?.(false);
+        this._approvalResolver = null;
+        this._pendingApproval = null;
+        this._updateMainContent();
+        this.tui.requestRender();
+      } else if (ch === "d") {
+        // dry run
+        const action = this._pendingApproval;
+        this._approvalResolver?.(false);
+        this._approvalResolver = null;
+        this._pendingApproval = null;
+        this.messages.push({
+          role: "assistant",
+          content: `**Dry-run preview**\n\nWould execute: \`${action.toolName}\`\n\`\`\`\n${JSON.stringify(action.args, null, 2).slice(0, 300)}\n\`\`\`\n*(Approve to run.)*`,
+        });
+        this._updateMainContent();
+        this.tui.requestRender();
+      }
+      return;
+    }
+
+    // Slash commands
+    if (trimmed.startsWith("/")) {
+      await this._handleSlashCommand(trimmed);
+      return;
+    }
+
+    if (this.loading) return;
+
+    // Switch to chat view
+    if (this.view !== "chat") {
+      this.view = "chat";
+      this._updateStatusBar();
+    }
+
+    // Add user message
+    this.messages.push({ role: "user", content: trimmed });
+    this._conversation.push({ role: "user", content: trimmed });
+    this.loading = true;
+    this._setLoaderActive(true);
+    this._updateMainContent();
+    this.tui.requestRender();
+
+    try {
+      const result = await this.engine.processMessage(null, trimmed, {
+        onToolCall: (name, args) => {
+          this.messages.push({ role: "tool_call", name, args, receipt: null });
+          this._updateMainContent();
+          this.tui.requestRender();
+        },
+        onToolResult: (name, toolResult) => {
+          // Find and update the last tool_call for this name
+          for (let i = this.messages.length - 1; i >= 0; i--) {
+            if (this.messages[i].role === "tool_call" && this.messages[i].name === name) {
+              this.messages[i] = { ...this.messages[i], result: toolResult };
+              break;
+            }
+          }
+          this._updateMainContent();
+          this.tui.requestRender();
+        },
+        onReceipt: (receipt) => {
+          if (!receipt?.toolName) return;
+          for (let i = this.messages.length - 1; i >= 0; i--) {
+            if (this.messages[i].role === "tool_call" && this.messages[i].name === receipt.toolName) {
+              this.messages[i] = { ...this.messages[i], receipt };
+              break;
+            }
+          }
+          this._updateMainContent();
+          this.tui.requestRender();
+        },
+        noSave: true,
+      });
+
+      const responseText = result.content;
+      this.messages.push({ role: "assistant", content: responseText });
+      this._conversation.push({ role: "assistant", content: responseText });
+
+      // Update budget
+      try {
+        const bud = this.engine?.budget;
+        if (bud) {
+          this.budgetSpent = bud.sessionSpend ?? 0;
+          this.maxBudget = bud.maxBudgetUsd ?? null;
+        }
+      } catch {}
+
+      await saveConversation(this.activeWorkstream, this._conversation.filter(m => m.role !== "system"));
+    } catch (err) {
+      const errMsg = `Error: ${err.message.slice(0, 200)}`;
+      this.messages.push({ role: "assistant", content: errMsg });
+    } finally {
+      this.loading = false;
+      this._setLoaderActive(false);
+    }
+
+    this._updateAll();
+    this.tui.requestRender();
+  }
+
+  async _handleSlashCommand(input) {
+    const parts = input.split(/\s+/);
+    const cmd = parts[0].toLowerCase();
+
+    const sysMsg = (text) => {
+      this.messages.push({ role: "system_info", content: text });
+      if (this.view !== "chat") { this.view = "chat"; this._updateStatusBar(); }
+      this._updateMainContent();
+      this.tui.requestRender();
+    };
+
+    if (cmd === "/quit" || cmd === "/exit") {
+      await this.shutdown();
+      return;
+    }
+
+    if (cmd === "/clear") {
+      this._conversation = [];
+      this.messages = [{ role: "system_info", content: "Conversation cleared." }];
+      await saveConversation(this.activeWorkstream, []);
+      this._updateMainContent();
+      this.tui.requestRender();
+      return;
+    }
+
+    if (cmd === "/cost") {
+      const bud = this.engine?.budget;
+      const spent = bud?.sessionSpend ?? this.budgetSpent;
+      const max = bud?.maxBudgetUsd;
+      sysMsg(`Budget: $${spent.toFixed(4)}${max ? ` / $${max.toFixed(2)}` : ""}`);
+      return;
+    }
+
+    if (cmd === "/model" && parts[1]) {
+      this.engine.providers?.setModel?.(parts[1]);
+      sysMsg(`Model → ${parts[1]}`);
+      return;
+    }
+
+    if ((cmd === "/ws" || cmd === "/workstream") && parts[1]) {
+      await this._switchWorkstream(parts[1]);
+      return;
+    }
+
+    if (cmd === "/trust" && parts[1]) {
+      try {
+        this.engine.permissions.setPolicy("run_command", parts[1]);
+        sysMsg(`Security level → ${parts[1]}`);
+      } catch (e) {
+        sysMsg(`Error: ${e.message}`);
+      }
+      return;
+    }
+
+    if (cmd === "/agent" && parts[1]) {
+      sysMsg(`Agent → ${parts[1]} (restart TUI to apply)`);
+      return;
+    }
+
+    if (cmd === "/help") {
+      // Toggle to help view
+      this.view = "help";
+      this._updateStatusBar();
+      this._updateMainContent();
+      this.tui.requestRender();
+      return;
+    }
+
+    if (cmd === "/overview" || cmd === "/o") { this.view = "overview"; this._updateAll(); this.tui.requestRender(); return; }
+    if (cmd === "/agents" || cmd === "/a")  { this.view = "agents";   this._updateAll(); this.tui.requestRender(); return; }
+    if (cmd === "/memory" || cmd === "/m")  { this.view = "memory";   this._updateAll(); this.tui.requestRender(); return; }
+    if (cmd === "/audit"  || cmd === "/u")  { this.view = "audit";    this._updateAll(); this.tui.requestRender(); return; }
+    if (cmd === "/settings"|| cmd === "/s") { this.view = "settings"; this._updateAll(); this.tui.requestRender(); return; }
+    if (cmd === "/chat")                    { this.view = "chat";     this._updateAll(); this.tui.requestRender(); return; }
+
+    // Unknown slash command — send to engine as chat
+    await this.handleSubmit(input.slice(1)); // strip /
+  }
+
+  async _switchWorkstream(ws) {
+    if (ws === this.activeWorkstream) return;
+    this.activeWorkstream = ws;
+    this.messages = [];
+    this._conversation = await loadConversation(ws);
+    this.messages = this._conversation.map(m => ({ ...m }));
+    this.view = "chat";
+    if (this.engine) {
+      this.engine._activeWorkstream = ws;
+      this.engine._workMdLoaded = false;
+      this.engine._workMdContent = null;
+    }
+    this._updateAll();
+    this.tui.requestRender();
+  }
+
+  // ─── Global key handling (called from WispyEditor) ─────────────────────────
+
+  handleGlobalKey(data) {
+    if (isKeyRelease(data)) return false;
+
+    // Approval mode: handle y/n/d via submit only
+
+    if (this._pendingApproval) return false;
+
+    // Tab — cycle view
+    if (matchesKey(data, Key.tab)) {
+      const idx = VIEWS.indexOf(this.view);
+      this.view = VIEWS[(idx + 1) % VIEWS.length];
+      if (this.view === "overview") {
+        loadOverviewData(this.workstreams).then(d => { this.overviewData = d; this._updateMainContent(); this.tui.requestRender(); });
+      }
+      this._updateAll();
+      this.tui.requestRender();
+      return true;
+    }
+
+    // Number keys 1-6 — jump to view
+    if (!this.loading && /^[1-6]$/.test(data)) {
+      const idx = parseInt(data) - 1;
+      this.view = VIEWS[idx] ?? this.view;
+      if (this.view === "overview") {
+        loadOverviewData(this.workstreams).then(d => { this.overviewData = d; this._updateMainContent(); this.tui.requestRender(); });
+      }
+      this._updateAll();
+      this.tui.requestRender();
+      return true;
+    }
+
+    // ? — help
+    if (data === "?" && !this.loading) {
+      this.view = this.view === "help" ? "chat" : "help";
+      this._updateAll();
+      this.tui.requestRender();
+      return true;
+    }
+
+    // Ctrl+C — quit
+    if (matchesKey(data, Key.ctrl("c"))) {
+      this.shutdown();
+      return true;
+    }
+
+    // Ctrl+L — clear
+    if (matchesKey(data, Key.ctrl("l"))) {
+      this._conversation = [];
+      this.messages = [{ role: "system_info", content: "Conversation cleared." }];
+      saveConversation(this.activeWorkstream, []).catch(() => {});
+      this._updateMainContent();
+      this.tui.requestRender();
+      return true;
+    }
+
+    return false;
+  }
+
+  // ─── Shutdown ──────────────────────────────────────────────────────────────
+
+  async shutdown() {
+    for (const id of this._intervals) clearInterval(id);
+    this.loaderComp?.stop();
+    this.tui.stop();
+    this.engine?.destroy?.();
+    process.exit(0);
+  }
+}
+
+// ─── WispyEditor — custom Editor that intercepts global keys ─────────────────
+
+class WispyEditor extends Editor {
+  constructor(tui, theme, wispyTUI) {
+    super(tui, theme);
+    this._wispy = wispyTUI;
+
+    // Handle submit via Editor's onSubmit
+    this.onSubmit = (text) => {
+      this._wispy.handleSubmit(text).catch(err => {
+        console.error("Submit error:", err.message);
+      });
+    };
+  }
+
+  handleInput(data) {
+    if (isKeyRelease(data)) return;
+
+    // Let WispyTUI handle global keys first (Tab, Ctrl+C, 1-6, ?, Ctrl+L)
+    // But only if editor is empty (to allow typing numbers normally)
+    const currentText = this.getText();
+    if (currentText.length === 0 || matchesKey(data, Key.tab) || matchesKey(data, Key.ctrl("c")) || matchesKey(data, Key.ctrl("l"))) {
+      if (this._wispy.handleGlobalKey(data)) return;
+    }
+
+    // Enter to submit (when no shift)
+    if (matchesKey(data, Key.enter) && !matchesKey(data, Key.shift("enter"))) {
+      const text = this.getText().trim();
+      if (text) {
+        this.onSubmit(text);
+        this.setText("");
+      }
+      return;
+    }
+
+    // Default: pass to Editor (handles typing, backspace, CJK, undo, etc.)
+    super.handleInput(data);
+  }
+}
+
+// ─── ContentArea — custom component for sidebar + main layout ─────────────────
+
+class ContentArea {
+  constructor(wispyTUI) {
+    this._wispy = wispyTUI;
+    this._cachedLines = null;
+    this._dirty = true;
+  }
+
+  invalidate() {
+    this._dirty = true;
+    this._cachedLines = null;
+  }
+
+  render(width) {
+    const wispy = this._wispy;
+    const terminal = wispy.terminal;
+    const height = (terminal.rows ?? 24) - 3; // reserve status bar (1) + input (1) + border (1)
+    const contentHeight = Math.max(5, height);
+
+    const useSidebar = width >= 80;
+    const sidebarWidth = useSidebar ? SIDEBAR_WIDTH : 0;
+    const mainWidth = useSidebar ? width - sidebarWidth - 1 : width;
+
+    // Build sidebar
+    let sidebarLines = [];
+    if (useSidebar) {
+      sidebarLines = wispy._buildSidebarLines(sidebarWidth);
+    }
+
+    // Build main content
+    let mainLines;
+    if (wispy.view === "help") {
+      mainLines = wispy._buildHelpLines();
+    } else {
+      mainLines = wispy._buildMainContentLines(mainWidth);
+    }
+
+    // Truncate/pad to contentHeight
+    const sidebarPadded = [];
+    for (let i = 0; i < contentHeight; i++) {
+      const line = sidebarLines[i] ?? "";
+      // Visible width pad
+      const visLen = line.replace(/\x1b\[[^m]*m/g, "").replace(/\x1b_pi:c\x07/g, "").length;
+      const pad = " ".repeat(Math.max(0, sidebarWidth - visLen));
+      sidebarPadded.push(line + pad);
+    }
+
+    // Scroll main lines to show bottom
+    const startIdx = Math.max(0, mainLines.length - contentHeight);
+    const mainPadded = [];
+    for (let i = 0; i < contentHeight; i++) {
+      const line = mainLines[startIdx + i] ?? "";
+      // Truncate to mainWidth
+      const visLen = line.replace(/\x1b\[[^m]*m/g, "").replace(/\x1b_pi:c\x07/g, "").length;
+      if (visLen > mainWidth) {
+        // Naive truncate
+        mainPadded.push(line.slice(0, mainWidth));
+      } else {
+        mainPadded.push(line);
+      }
+    }
+
+    // Combine sidebar + divider + main into rows
+    const result = [];
+    if (useSidebar) {
+      const divider = C.dim("│");
+      for (let i = 0; i < contentHeight; i++) {
+        result.push(sidebarPadded[i] + divider + (mainPadded[i] ?? ""));
+      }
+    } else {
+      for (let i = 0; i < contentHeight; i++) {
+        result.push(mainPadded[i] ?? "");
+      }
+    }
+
+    this._dirty = false;
+    return result;
+  }
+}
+
+// ─── Entry point ──────────────────────────────────────────────────────────────
+
+async function main() {
+  if (!process.stdin.isTTY) {
+    console.error("Error: wispy tui requires a TTY terminal");
+    process.exit(1);
+  }
+
+  const wispyTUI = new WispyTUI();
+  await wispyTUI.init();
+
+  // Keep process alive — TUI manages exit
+  await new Promise(() => {});
+}
+
+main().catch(err => {
+  console.error("TUI error:", err.message);
+  if (process.env.WISPY_DEBUG) console.error(err.stack);
+  process.exit(1);
+});