@cirvix_ai/agent-control 0.1.3 → 0.2.0

package/src/tui/app.mjs

@@ -0,0 +1,292 @@
+/**
+ * Cirvix console — the primary interactive UX.
+ *
+ * Layout (wide terminals):
+ *   ┌ header ────────────────────────────────┐
+ *   │ CONVERSATION            │ ACTIVITY     │
+ *   │ user asks / cirvix      │ ◐ policy.eval│
+ *   │ responds / policy cards │ ✓ shell.exec │
+ *   ├ composer ──────────────────────────────┤
+ *   │ status bar                             │
+ *   └────────────────────────────────────────┘
+ *
+ * Narrow terminals (<90 cols): the activity pane collapses into the
+ * transcript automatically. No horizontal scrolling, ever.
+ *
+ * Engine separation: the app owns a Pipeline + EventBus. It emits events,
+ * reduces them to state, and renders cards from state. Policy code never
+ * touches the terminal.
+ *
+ * Non-TTY / piped usage: `runOnce(text)` evaluates one line and returns
+ * the rendered output without starting readline — used by tests, CI, and
+ * `echo "…" | cirvix console`.
+ */
+
+import { Pipeline } from "../core/pipeline.mjs";
+import { decideNow } from "../core/journal.mjs";
+import { EventBus, createEvent, initialState, reduce, attachPipeline } from "../core/events.mjs";
+import { header, policyCard, toolCard, blockedCard, heldCard, explainDecision, userRow, cirvixRow, spinnerFrame } from "./cards.mjs";
+import { statusBar } from "./status.mjs";
+import { collapsedFeed } from "./activity.mjs";
+import { paletteBox } from "./palette.mjs";
+import { setTheme, THEME_NAMES, bold, dim, style } from "../core/theme.mjs";
+import { startComposer } from "./composer.mjs";
+
+const VERSION = "0.1.0";
+
+export class ConsoleApp {
+  constructor({ cwd = process.cwd(), rules = [], mode = "enforce", agent = "local", write = (s) => process.stdout.write(s) } = {}) {
+    this.cwd = cwd;
+    this.rules = rules;
+    this.agent = agent;
+    this.write = write;
+    this.bus = new EventBus();
+    this.state = initialState();
+    this.state.status.mode = mode;
+    this.expanded = false;
+    this.overlay = null; // 'palette' | null
+
+    this.pipeline = new Pipeline({ rules, cwd, agent, mode, onEvent: () => {} });
+    attachPipeline(this.pipeline, this.bus);
+    this.bus.onAny((e) => {
+      this.state = reduce(this.state, e);
+    });
+    this.bus.emit(createEvent.sessionStarted({ agent }));
+  }
+
+  /* ---------------------------------------------------------- rendering */
+
+  renderHeader() {
+    return header({ mode: this.state.status.mode === "audit" ? "AUDIT MODE" : "PROTECTED", version: VERSION });
+  }
+
+  renderStatus() {
+    return statusBar(this.state, { version: VERSION });
+  }
+
+  renderActivity() {
+    return collapsedFeed(this.state.activity, { expanded: this.expanded });
+  }
+
+  /** Full re-render of the transcript region (used on clear / toggle). */
+  renderTranscript() {
+    const out = [this.renderHeader(), ``];
+    for (const m of this.state.messages) {
+      out.push(m.role === "user" ? userRow(m.text) : cirvixRow(m.text), ``);
+    }
+    if (this.narrow()) {
+      out.push(`▼ Activity`, this.renderActivity(), ``);
+    }
+    out.push(this.renderStatus());
+    return out.join("\n");
+  }
+
+  narrow() {
+    return (process.stdout.columns ?? 80) < 90;
+  }
+
+  /* ------------------------------------------------------------- events */
+
+  /** Animated "evaluating" line. Resolves with a stop() that clears it. */
+  animate(label) {
+    if (!process.stdout.isTTY) {
+      this.write(`${dim("◐")} ${label}...\n`);
+      return () => {};
+    }
+    let i = 0;
+    const timer = setInterval(() => {
+      process.stdout.write(`\r${dim(spinnerFrame(i++))} ${dim(label)}...`);
+    }, 90);
+    return () => {
+      clearInterval(timer);
+      process.stdout.write("\r" + " ".repeat(label.length + 6) + "\r");
+    };
+  }
+
+  /** Evaluate one free-text line through policy and render the product UI. */
+  async runOnce(input) {
+    const text = String(input ?? "").trim();
+    if (!text) return "";
+    if (text.startsWith("/")) return this.runSlash(text);
+
+    this.bus.emit(createEvent.userMessage(text));
+    const lines = [userRow(text), ``, cirvixRow(`${dim("◐ Evaluating authorization...")}`)];
+    const stop = this.animate("Evaluating policy");
+    const parsed = parseRequest(text, { agent: this.agent });
+    let decision;
+    try {
+      ({ decision } = decideNow({ ...parsed, rules: this.rules, cwd: this.cwd }));
+    } finally {
+      stop();
+    }
+    const event = {
+      decision_id: `dec_local`,
+      request_id: `req_local`,
+      agent: this.agent,
+      tool: parsed.tool,
+      resource: parsed.args.path ?? parsed.args.url ?? parsed.args.command ?? "",
+      risk: decision.risk ?? "medium",
+      decision: decision.decision ?? "deny",
+      policy: decision.rule,
+      reason: decision.reason,
+      latency_ms: 0,
+    };
+    this.bus.emit(createEvent.policyDecision(event));
+    if (event.decision === "require_approval") this.bus.emit(createEvent.approvalRequested({ tool: event.tool, resource: event.resource }));
+    this.bus.emit(createEvent.agentMessage(`Decision: ${event.decision}`));
+
+    return [...lines, ``, this.renderDecision(event, parsed), ``, this.renderStatus()].join("\n");
+  }
+
+  renderDecision(event, parsed = {}) {
+    const d = event.decision;
+    if (d === "deny") {
+      const target = event.resource || parsed.args?.command || "";
+      return [blockedCard({ tool: event.tool, target, policy: event.policy, reason: event.reason }), ``, explainDecision(event)].join("\n");
+    }
+    if (d === "require_approval") {
+      return heldCard({ tool: event.tool, target: event.resource, approvers: event.approvers ?? [], reason: event.reason });
+    }
+    return [
+      policyCard({
+        action: event.tool,
+        risk: event.risk,
+        policy: event.policy ?? "default",
+        identity: `agent:${event.agent}`,
+        reason: event.reason,
+        latencyMs: event.latency_ms,
+      }),
+      ...(d === "sanitize" ? [``, explainDecision(event)] : []),
+    ].join("\n");
+  }
+
+  /* ---------------------------------------------------------------- slash */
+
+  async runSlash(input) {
+    const [cmd, ...rest] = input.trim().split(/\s+/);
+    const arg = rest.join(" ");
+    switch (cmd.toLowerCase()) {
+      case "/help":
+        return paletteBox("/");
+      case "/quit":
+      case "/exit":
+        return "quit";
+      case "/clear":
+        return "\x1b[2J\x1b[0;0H" + this.renderTranscript();
+      case "/expand":
+        this.expanded = true;
+        return this.renderActivity();
+      case "/collapse":
+        this.expanded = false;
+        return this.renderActivity();
+      case "/theme": {
+        if (!arg) return `Usage: /theme <${THEME_NAMES.join("|")}>\nCurrent: ${bold(process.env.CIRVIX_THEME ?? "dark")}`;
+        try {
+          setTheme(arg);
+          process.env.CIRVIX_THEME = arg;
+          return `${style("✓", "allow")} Theme → ${bold(arg)}`;
+        } catch (err) {
+          return `${style("✕", "block")} ${err.message}`;
+        }
+      }
+      case "/audit":
+      case "/logs":
+        return this.renderActivity();
+      case "/policies": {
+        const names = this.rules.map((r) => `  • ${r.name ?? "(unnamed)"}  ${dim(r.effect ?? "")}`).join("\n");
+        return `${bold("Policies")} ${dim(`(${this.rules.length} rules)`)}\n${names || dim("  (no rules loaded)")}`;
+      }
+      case "/sessions":
+        return `${bold("Session")}  ${this.state.session?.id ?? "—"}  ${dim(`agent ${this.state.session?.agent ?? this.agent}`)}\n${dim(`${this.state.status.requests} requests this session`)}`;
+      case "/doctor":
+        return doctor(this.rules, this.state);
+      case "/demo":
+        return dim("Run `cirvix demo` in a fresh terminal for the full live interception demo.");
+      case "/approvals": {
+        if (!this.state.approvals.length) return dim("nothing waiting on a human");
+        return this.state.approvals.map((a) => `  ${bold(a.approval_id ?? a.id ?? "approval")}  ${a.tool ?? ""}  ${dim(a.resource ?? "")}`).join("\n");
+      }
+      case "/config":
+        return `${bold("Config")}\n  ${dim("theme")}  ${process.env.CIRVIX_THEME ?? "dark"}\n  ${dim("agent")}  ${this.agent}\n  ${dim("mode")}   ${this.state.status.mode}`;
+      default: {
+        // Prefix completion: "/pol" → show matches instead of erroring.
+        const { filterCommands } = await import("./palette.mjs");
+        const matches = filterCommands(input);
+        if (matches.length) return paletteBox(input);
+        return dim(`Unknown command "${cmd}". Type / for the palette.`);
+      }
+    }
+  }
+
+  /* ---------------------------------------------------------- interactive */
+
+  async start() {
+    this.write(this.renderTranscript() + "\n\n");
+    this.write(dim("Type / for commands. Ctrl+K palette · Ctrl+O activity · Esc close.\n"));
+    const rl = startComposer({
+      prompt: "> ",
+      onLine: async (line) => {
+        if (!line) return;
+        if (line === "/quit" || line === "/exit") return "quit";
+        const out = await this.runOnce(line);
+        if (out === "quit") return "quit";
+        this.write("\n" + out + "\n\n");
+        if (!this.narrow()) {
+          // Side-pane refresh on wide terminals: reprint compact activity.
+          this.write(dim("─ Activity ─") + "\n" + this.renderActivity() + "\n\n" + this.renderStatus() + "\n");
+        }
+      },
+      onKey: (key) => {
+        if (key === "toggle-activity") {
+          this.expanded = !this.expanded;
+          this.write("\n" + this.renderActivity() + "\n");
+        } else if (key === "palette") {
+          this.write("\n" + paletteBox("/") + "\n");
+        } else if (key === "policies") {
+          this.write("\n" + `Policies: ${this.rules.length} loaded` + "\n");
+        }
+      },
+    });
+    await new Promise((resolve) => rl.on("close", resolve));
+    this.bus.emit(createEvent.sessionEnded({}));
+    this.write("\n" + dim("Session ended. Audit chain intact.") + "\n");
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+
+/**
+ * Heuristic: turn "Can the deploy bot run `rm -rf /`?" into a policy
+ * request. Deliberately conservative — unknown shapes become a low-risk
+ * workspace read that policy will judge on its merits, never an implicit
+ * permit of something dangerous.
+ */
+export function parseRequest(text, { agent = "local" } = {}) {
+  const t = String(text);
+  const url = t.match(/https?:\/\/[^\s"'`]+/i)?.[0];
+  const credPath = t.match(/(~\/\.aws\/credentials|\.env[^\s]*|\.aws[^\s]*)/i)?.[0];
+  const cmd = t.match(/`([^`]+)`/)?.[1] ?? t.match(/run\s+"([^"]+)"/i)?.[1];
+
+  if (credPath) return { tool: "read_file", server: null, args: { path: credPath }, agent };
+  if (url && /collect|attacker|exfil|send|post/i.test(t)) {
+    return { tool: "http_request", server: null, args: { url }, agent };
+  }
+  if (url) return { tool: "http_request", server: null, args: { url }, agent };
+  if (cmd) return { tool: "shell_exec", server: null, args: { command: cmd }, agent };
+  if (/deploy|production/i.test(t)) return { tool: "shell_exec", server: null, args: { command: "deploy production" }, agent };
+  if (/database|db|sql/i.test(t)) return { tool: "db_query", server: null, args: { sql: t.slice(0, 200) }, agent };
+  return { tool: "read_file", server: null, args: { path: "./" + t.slice(0, 60) }, agent };
+}
+
+function doctor(rules, state) {
+  const rows = [
+    ["Engine", style("✓ reachable", "allow")],
+    ["Rules", rules.length ? `${rules.length} loaded` : style("none — run cirvix init", "warning")],
+    ["Session", `${state.status.requests} requests`],
+    ["Blocked", state.status.blocked > 0 ? style(`${state.status.blocked} denied`, "block") : "0"],
+    ["Terminal", `${process.stdout.columns ?? 80} cols ${process.stdout.isTTY ? "(TTY)" : "(piped)"}`],
+  ];
+  return `${bold("Doctor")}\n` + rows.map(([k, v]) => `  ${dim(k.padEnd(9))} ${v}`).join("\n");
+}

package/src/tui/cards.mjs

@@ -0,0 +1,235 @@
+/**
+ * Cirvix TUI cards — every tool call rendered as a visual object.
+ *
+ * Pure functions: (data) → string. No console writes, no engine imports.
+ * The same functions back the interactive console, `cirvix logs --tree`,
+ * and the future React/Ink port (one card = one component).
+ *
+ * Accessibility rule: icon + color + WORD. A ✓/✕ alone is never the only
+ * signal — every card prints ALLOWED / SANITIZED / BLOCKED / HELD as text.
+ */
+
+import { style, bold, dim, roleForDecision, roleForRisk, badgeForDecision } from "../core/theme.mjs";
+
+/* ------------------------------------------------------------------ */
+/*  Box primitives                                                     */
+/* ------------------------------------------------------------------ */
+
+function width() {
+  return Math.max(40, Math.min(process.stdout.columns ?? 80, 100));
+}
+
+function rule(char = "─") {
+  return dim(char.repeat(Math.max(0, width() - 2)));
+}
+
+function frame(title, lines, { tone = "border" } = {}) {
+  const W = Math.max(40, width() - 6);
+  const top = style(`┌─ ${title} ${"─".repeat(Math.max(0, W - title.length - 4))}┐`, tone);
+  const bottom = style(`└${"─".repeat(W)}┘`, tone);
+  const body = lines.map((l) => {
+    const plain = stripAnsi(l);
+    const pad = " ".repeat(Math.max(0, W - 2 - plain.length));
+    return `${style("│", tone)} ${l}${pad} ${style("│", tone)}`;
+  });
+  return [top, ...body, bottom].join("\n");
+}
+
+function stripAnsi(s) {
+  return String(s).replace(/\x1b\[[0-9;]*m/g, "");
+}
+
+function kv(key, value, { keyWidth = 12 } = {}) {
+  return `${dim(String(key).padEnd(keyWidth))} ${value}`;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Header                                                             */
+/* ------------------------------------------------------------------ */
+
+export function header({ mode = "PROTECTED", version = "" } = {}) {
+  const dot = mode === "PROTECTED" ? style("●", "allow") : style("○", "warning");
+  const title = `${bold("◆ CIRVIX")}  ${dim("Runtime Authorization")}`;
+  const right = `${dot} ${bold(mode)}${version ? dim(`  v${version}`) : ""}`;
+  return `${title}${" ".repeat(Math.max(2, width() - stripAnsi(title).length - stripAnsi(right).length))}${right}\n${rule()}`;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Policy decision card — the ALLOWED shape                           */
+/* ------------------------------------------------------------------ */
+
+export function policyCard({ action, risk, policy, identity, reason, latencyMs } = {}) {
+  const badge = badgeForDecision("allow");
+  const lines = [
+    `${style(`✓ ${badge.label}`, "allow")}`,
+    ``,
+    kv("Action", bold(action ?? "—")),
+    kv("Risk", style(String(risk ?? "—").toUpperCase(), roleForRisk(risk))),
+    kv("Policy", policy ?? dim("default-deny")),
+    kv("Identity", identity ?? dim("agent:local")),
+    ...(reason ? [kv("Reason", dim(truncate(reason, 60)))] : []),
+    ...(latencyMs !== undefined ? [kv("Latency", dim(`${latencyMs}ms`))] : []),
+  ];
+  return frame("POLICY DECISION", lines, { tone: "border" });
+}
+
+/* ------------------------------------------------------------------ */
+/*  Tool card — full lifecycle: identity → policy checks → decision    */
+/* ------------------------------------------------------------------ */
+
+export function toolCard({ tool, risk, identity, detail, checks = [], decision, policy, reason } = {}) {
+  const badge = badgeForDecision(decision);
+  const role = roleForDecision(decision);
+  const lines = [
+    ``,
+    kv("Risk", style(String(risk ?? "—").toUpperCase(), roleForRisk(risk))),
+    kv("Identity", identity ?? dim("agent:local")),
+    ...(detail ? [kv(detailLabel(tool), truncate(detail, 64))] : []),
+    ``,
+    dim("Policy evaluation"),
+    ...checks.map((c) => `  ${c.ok ? style("✓", "allow") : style("✕", "block")} ${dim(c.label)}`),
+    ``,
+    kv("Decision", style(`${badge.icon} ${badge.label}`, role)),
+    ...(policy ? [kv("Policy", policy)] : []),
+    ...(reason ? [kv("Why", dim(truncate(reason, 64)))] : []),
+  ];
+  const title = String(tool ?? "TOOL").toUpperCase().replace(/__/g, " · ");
+  return frame(title, lines, { tone: role === "block" ? "block" : "border" });
+}
+
+function detailLabel(tool) {
+  const t = String(tool ?? "");
+  if (/http|egress|fetch|request/i.test(t)) return "URL";
+  if (/read|write|file/i.test(t)) return "Path";
+  if (/shell|exec|command/i.test(t)) return "Command";
+  if (/sql|db|query/i.test(t)) return "Query";
+  return "Target";
+}
+
+/* ------------------------------------------------------------------ */
+/*  Blocked card — the dangerous shape. Human first, fields second.    */
+/* ------------------------------------------------------------------ */
+
+export function blockedCard({ tool, target, policy, reason, detail } = {}) {
+  const lines = [
+    style(`🔴 HIGH-RISK ACTION — BLOCKED`, "block"),
+    ``,
+    bold(tool ?? "unknown tool"),
+    ...(target ? [dim(truncate(target, 72))] : []),
+    ``,
+    ...(policy ? [kv("Policy", policy)] : []),
+    ...(reason ? [kv("Reason", truncate(reason, 72))] : []),
+    ...(detail ? [dim(truncate(detail, 72))] : []),
+    ``,
+    dim("Action was NOT executed. No side effects occurred."),
+  ];
+  return frame("BLOCKED", lines, { tone: "block" });
+}
+
+export function heldCard({ tool, target, approvers = [], reason } = {}) {
+  const lines = [
+    `${style("◷ HELD FOR APPROVAL", "hold")}`,
+    ``,
+    bold(tool ?? "unknown tool"),
+    ...(target ? [dim(truncate(target, 72))] : []),
+    ``,
+    kv("Waits on", approvers.length ? approvers.join(", ") : dim("a human approver")),
+    ...(reason ? [kv("Reason", dim(truncate(reason, 68)))] : []),
+    ``,
+    dim("The call is suspended. Approve it with `cirvix approvals`."),
+  ];
+  return frame("APPROVAL", lines, { tone: "hold" });
+}
+
+/* ------------------------------------------------------------------ */
+/*  Human-readable explanation — security product, not infra dump      */
+/* ------------------------------------------------------------------ */
+
+export function explainDecision(event = {}) {
+  const decision = event.decision ?? event.verdict ?? "deny";
+  const badge = badgeForDecision(decision);
+  const role = roleForDecision(decision);
+  const title = style(`${badge.icon} ${badge.label}`, role);
+
+  if (decision === "deny") {
+    return [
+      title,
+      ``,
+      `Cirvix stopped this request${event.policy ? ` because policy ${bold(`"${event.policy}"`)} matched` : ""}.`,
+      ...(event.resource || event.destination
+        ? [``, `Target:`, `  ${truncate(event.resource || event.destination, 76)}`]
+        : []),
+      ...(event.reason ? [``, dim(wrap(event.reason, 76))] : []),
+      ``,
+      dim("No network request was sent. No file was read. No command ran."),
+      ``,
+      `${dim("[Why?]")} ${dim("cirvix logs --tree " + (event.request_id ?? event.decision_id ?? "<id>"))}   ${dim("[Policy]")} cirvix policy list`,
+    ].join("\n");
+  }
+
+  if (decision === "sanitize") {
+    return [
+      title,
+      ``,
+      `Cirvix forwarded this call after cleaning it.`,
+      ...(event.reason ? [``, dim(wrap(event.reason, 76))] : []),
+      ``,
+      dim("The agent received a safe version — the original never left the runtime."),
+    ].join("\n");
+  }
+
+  if (decision === "require_approval") {
+    return [
+      title,
+      ``,
+      `This call needs a human before it runs.`,
+      ...(event.reason ? [``, dim(wrap(event.reason, 76))] : []),
+    ].join("\n");
+  }
+
+  return [
+    title,
+    ...(event.reason ? [``, dim(wrap(event.reason, 76))] : []),
+  ].join("\n");
+}
+
+/* ------------------------------------------------------------------ */
+/*  Transcript rows                                                    */
+/* ------------------------------------------------------------------ */
+
+export function userRow(text) {
+  return `${bold("You")}\n${dim("─".repeat(27))}\n${text}`;
+}
+
+export function cirvixRow(text) {
+  return `${bold("CIRVIX")}\n${dim("─".repeat(27))}\n${text}`;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Small helpers                                                      */
+/* ------------------------------------------------------------------ */
+
+export function spinnerFrame(i) {
+  return ["◐", "◓", "◑", "◒"][i % 4];
+}
+
+function truncate(s, n) {
+  const v = String(s ?? "");
+  return v.length <= n ? v : `…${v.slice(-(n - 1))}`;
+}
+
+function wrap(text, w) {
+  const words = String(text).split(/\s+/);
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if ((line + " " + word).trim().length > w) {
+      lines.push(line.trim());
+      line = word;
+    } else line += " " + word;
+  }
+  if (line.trim()) lines.push(line.trim());
+  return lines.join("\n");
+}
+
+export { frame, rule, width };

package/src/tui/composer.mjs

@@ -0,0 +1,88 @@
+/**
+ * Composer — the input box. Multiline, history, paste, autocomplete.
+ *
+ * Built on node:readline (zero deps) rather than a bespoke ANSI editor:
+ * - multiline via Shift+Enter semantics: plain Enter sends, and a trailing
+ *   `\` continues the line; pasted multi-line blocks are joined safely.
+ * - ↑↓ history, Ctrl+R reverse search, Ctrl+C cancel, Ctrl+L clear, Tab
+ *   completion come from readline itself.
+ * - `/` prefix triggers the command palette; Tab completes it.
+ * - Ctrl+K opens the palette, Ctrl+O toggles activity, Ctrl+P policies,
+ *   Ctrl+A audit, Ctrl+S session, Esc closes overlays.
+ *
+ * The composer never evaluates policy itself — it emits lines to the app.
+ */
+
+import readline from "node:readline";
+import { filterCommands } from "./palette.mjs";
+import { dim, bold } from "../core/theme.mjs";
+
+export const KEY_HINT = dim("Enter ↵ send   Shift+Enter newline   ↑↓ history   Tab commands   / palette   Ctrl+K palette   Esc close");
+
+export function composerBox() {
+  return `${dim("╭─ CIRVIX ─" + "─".repeat(50) + "╮")}\n${dim("│")}  ${dim("Ask Cirvix anything... type / for commands")}\n${dim("╰" + "─".repeat(60) + "╯")}\n  ${KEY_HINT}`;
+}
+
+function completer(line) {
+  if (!line.startsWith("/")) return [[], line];
+  const matches = filterCommands(line).map((c) => c.name);
+  return [matches, line];
+}
+
+/**
+ * Start the interactive prompt. `onLine` may be async; return "quit" from
+ * it (or type /quit) to exit. Returns a handle with `close()`.
+ */
+export function startComposer({ prompt = "> ", history = [], onLine, onKey }) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+    prompt,
+    completer,
+    history,
+    terminal: Boolean(process.stdin.isTTY),
+  });
+
+  // Extra shortcuts beyond readline's builtins.
+  if (process.stdin.isTTY) {
+    readline.emitKeypressEvents(process.stdin);
+    const onKeypress = (str, key = {}) => {
+      if (key.name === "escape") onKey?.("escape");
+      else if (key.ctrl && key.name === "k") { rl.write("/"); onKey?.("palette"); }
+      else if (key.ctrl && key.name === "o") onKey?.("toggle-activity");
+      else if (key.ctrl && key.name === "p") onKey?.("policies");
+      else if (key.ctrl && key.name === "a") onKey?.("audit");
+      else if (key.ctrl && key.name === "s") onKey?.("session");
+      else if (key.ctrl && key.name === "l") { console.clear(); rl.prompt(); }
+    };
+    process.stdin.on("keypress", onKeypress);
+    rl.on("close", () => process.stdin.removeListener("keypress", onKeypress));
+  }
+
+  // Trailing-backslash continuation = Shift+Enter equivalent for terminals
+  // that cannot distinguish the two.
+  let pending = "";
+  rl.on("line", async (line) => {
+    if (line.endsWith("\\")) {
+      pending += line.slice(0, -1) + "\n";
+      rl.setPrompt("… ");
+      rl.prompt();
+      return;
+    }
+    const full = (pending + line).trim();
+    pending = "";
+    rl.setPrompt(prompt);
+    try {
+      const verdict = await onLine?.(full);
+      if (verdict === "quit") rl.close();
+      else rl.prompt();
+    } catch {
+      rl.prompt();
+    }
+  });
+
+  rl.prompt();
+  return rl;
+}
+
+export { completer };

package/src/tui/palette.mjs

@@ -0,0 +1,48 @@
+/**
+ * Command palette — `/` shows everything. No memorized single letters.
+ *
+ * Each entry: { name, hint, run }. Filtering is prefix + substring so
+ * `/pol` matches `/policies`, `/policy test`, `/policy explain`.
+ */
+
+export const COMMANDS = [
+  { name: "/audit", hint: "View security audit", run: "audit" },
+  { name: "/policies", hint: "Inspect policies", run: "policies" },
+  { name: "/policy test", hint: "Run policy test cases", run: "policy-test" },
+  { name: "/policy explain", hint: "Why would this call be decided that way", run: "policy-explain" },
+  { name: "/logs", hint: "View runtime logs", run: "logs" },
+  { name: "/sessions", hint: "Manage sessions", run: "sessions" },
+  { name: "/approvals", hint: "Calls waiting on a human", run: "approvals" },
+  { name: "/theme", hint: "Change appearance (dark/light/midnight/high-contrast)", run: "theme" },
+  { name: "/config", hint: "Configure Cirvix", run: "config" },
+  { name: "/doctor", hint: "Diagnose runtime", run: "doctor" },
+  { name: "/demo", hint: "Run the live interception demo", run: "demo" },
+  { name: "/expand", hint: "Expand activity feed", run: "expand" },
+  { name: "/collapse", hint: "Collapse activity feed", run: "collapse" },
+  { name: "/clear", hint: "Clear the screen", run: "clear" },
+  { name: "/help", hint: "Show commands", run: "help" },
+  { name: "/quit", hint: "Leave the console", run: "quit" },
+];
+
+export function filterCommands(input) {
+  const q = String(input ?? "").trim().toLowerCase();
+  if (!q || q === "/") return COMMANDS;
+  const needle = q.startsWith("/") ? q : `/${q}`;
+  const bare = needle.slice(1);
+  return COMMANDS.filter(
+    (c) => c.name.toLowerCase().startsWith(needle) || c.name.toLowerCase().includes(bare),
+  );
+}
+
+export function paletteBox(input) {
+  const matches = filterCommands(input);
+  const lines = [
+    `╭─ Commands ─${"─".repeat(24)}╮`,
+    `│ > ${(input ?? "").padEnd(32)} │`,
+    `│${" ".repeat(36)}│`,
+    ...matches.slice(0, 8).map((c) => `│  ${(c.name.padEnd(14))} ${c.hint.slice(0, 18).padEnd(18)} │`),
+    ...(matches.length === 0 ? [`│  (no match)${" ".repeat(24)} │`] : []),
+    `╰${"─".repeat(36)}╯`,
+  ];
+  return lines.join("\n");
+}