@cirvix_ai/agent-control 0.1.5 → 0.2.0

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");
+}

package/src/tui/status.mjs

@@ -0,0 +1,42 @@
+/**
+ * Persistent status bar — always on screen, always honest.
+ *
+ * Wide terminal: full breakdown (mode, policy, counts, latency, audit).
+ * Narrow terminal (<72 cols): compact one-liner. The bar adapts; it never
+ * wraps into two unreadable lines.
+ */
+
+import { style, bold, dim } from "../core/theme.mjs";
+import { latencyStats } from "../core/events.mjs";
+
+export function statusBar(state, { version = "", width = process.stdout.columns ?? 80 } = {}) {
+  const s = state.status;
+  const lat = latencyStats(s.latencies);
+  const mode = s.mode === "audit"
+    ? `${style("○", "warning")} ${style("AUDIT", "warning")}`
+    : `${style("●", "allow")} ${bold("PROTECTED")}`;
+
+  if (width < 72) {
+    // Compact: [● PROTECTED] 148 req  21 blocked  P95 18ms
+    return dim("─".repeat(Math.max(0, width - 1))) + "\n" +
+      `${mode}  ${s.requests} req  ${blockedPart(s)}  ${dim(`P95 ${lat.p95}ms`)}`;
+  }
+
+  const line1 = dim("─".repeat(Math.max(0, width - 1)));
+  const cells = [
+    `${mode}   ${dim("│")}  ${dim("Policy:")} ${s.policyName ?? "strict"}   ${dim("│")}  ${dim("Requests:")} ${s.requests}`,
+    `${dim("Allow:")} ${style(String(s.allowed), "allow")}   ${dim("│")}  ${dim("Sanitized:")} ${s.sanitized}   ${dim("│")}  ${dim("Blocked:")} ${blockedCount(s)}`,
+    `${dim(`P50 ${lat.p50}ms`)}   ${dim("│")}  ${dim(`P95 ${lat.p95}ms`)}   ${dim("│")}  ${dim("Audit")} ${style("✓", "allow")}${version ? dim(`  │  v${version}`) : ""}`,
+  ];
+  return line1 + "\n" + cells.join("\n");
+}
+
+function blockedCount(s) {
+  const n = `${s.blocked + s.held}`;
+  return s.blocked + s.held > 0 ? style(n, "block") : n;
+}
+
+function blockedPart(s) {
+  const n = s.blocked + s.held;
+  return n > 0 ? style(`${n} blocked`, "block") : dim("0 blocked");
+}