@cirvix_ai/agent-control 0.1.5 → 0.2.0

package/bin/cirvix.mjs

@@ -66,6 +66,8 @@ const HELP = `
     cirvix <command> [options]
 
   ${bold("GETTING STARTED")}
+    console               Interactive runtime authorization (the product UI)
+    onboard               10-second guided first run
     init                  Detect agents and MCP servers, write a policy, start protecting
     init --apply          Safely wire detected agents with pre-integration backup
     init --dry-run        Preview agent configuration changes without modifying files
@@ -80,6 +82,7 @@ const HELP = `
     prove <decision-id>   Sign a decision into a portable proof artifact
     verify <proof>        Check a proof offline: signature, chain, integrity
     scan                  Inventory what is ungoverned on this machine
+    theme                 Change appearance (dark|light|midnight|high-contrast|monochrome)
 
   ${bold("ENFORCEMENT")}
     gateway               Run the MCP gateway — intercepts and enforces
@@ -1072,6 +1075,55 @@ async function main() {
       return 0;
     }
 
+    /* ------------------------------------------------------------ console */
+    case "console": {
+      if (typeof flags.theme === "string") {
+        const { setTheme } = await import("../src/core/theme.mjs");
+        try {
+          setTheme(flags.theme);
+          process.env.CIRVIX_THEME = flags.theme;
+        } catch (err) {
+          process.stderr.write(red(`  ${err.message}\n`));
+          return 2;
+        }
+      }
+      const rules = await loadRules(flags.policy, cwd);
+      const { consoleCmd } = await import("../src/commands/console.mjs");
+      await consoleCmd({
+        cwd,
+        rules,
+        mode: flags.mode === "audit" ? MODE.AUDIT : MODE.ENFORCE,
+        evalText: typeof flags.eval === "string" ? flags.eval : null,
+        once: Boolean(flags.once ?? flags.eval),
+      });
+      return 0;
+    }
+
+    case "theme": {
+      const { setTheme, THEME_NAMES } = await import("../src/core/theme.mjs");
+      const name = sub ?? flags.set;
+      if (!name) {
+        process.stdout.write(
+          `\n  Current theme: ${process.env.CIRVIX_THEME ?? "dark"}\n  Available: ${THEME_NAMES.join(", ")}\n\n  Usage: cirvix theme <name>\n  Persist it: CIRVIX_THEME=${THEME_NAMES[0]} cirvix console\n\n`,
+        );
+        return 0;
+      }
+      try {
+        setTheme(name);
+        process.stdout.write(`\n  Theme → ${name} (set CIRVIX_THEME=${name} to keep it)\n\n`);
+        return 0;
+      } catch (err) {
+        process.stderr.write(red(`  ${err.message}\n`));
+        return 2;
+      }
+    }
+
+    case "onboard": {
+      const { onboard } = await import("../src/commands/onboard.mjs");
+      await onboard({ cwd, pace: flags.fast ? 0 : 400 });
+      return 0;
+    }
+
     /* ---------------------------------------------------------------- demo */
     case "demo": {
       const rules = flags.policy ? await loadRules(flags.policy, cwd) : null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cirvix_ai/agent-control",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Cirvix AgentControl \u2014 runtime governance for AI agents. Scan what is ungoverned, evaluate policy, and broker tool calls.",
   "license": "Apache-2.0",
   "homepage": "https://cirvix.com/",

package/src/commands/console.mjs

@@ -0,0 +1,58 @@
+/**
+ * `cirvix console` — the primary product interface.
+ *
+ * Interactive when attached to a TTY, one-shot when piped:
+ *   cirvix console                        # full REPL
+ *   echo "read ~/.aws/credentials" | cirvix console --once
+ *   cirvix console --eval "deploy to production"
+ *
+ * `--once` / `--eval` exist so the product UI is scriptable and testable:
+ * the same cards render in CI as in the terminal.
+ */
+
+import { ConsoleApp } from "../tui/app.mjs";
+
+export async function consoleCmd({ cwd = process.cwd(), rules = [], mode = "enforce", evalText = null, once = false, write = (s) => process.stdout.write(s) } = {}) {
+  const app = new ConsoleApp({ cwd, rules, mode, write });
+
+  if (evalText) {
+    const out = await app.runOnce(evalText);
+    if (out && out !== "quit") write(out + "\n");
+    return { app, output: out };
+  }
+
+  if (once || !process.stdin.isTTY) {
+    // Piped: evaluate each line, print cards, exit. Never start readline
+    // on a non-TTY — it would hang waiting for a terminal that is not there.
+    const chunks = await readStdin();
+    const lines = chunks.split("\n").map((l) => l.trim()).filter(Boolean);
+    let output = "";
+    for (const line of lines) {
+      const out = await app.runOnce(line);
+      if (out && out !== "quit") {
+        write(out + "\n");
+        output += out + "\n";
+      }
+    }
+    if (!lines.length) {
+      const help = app.renderTranscript();
+      write(help + "\n");
+      return { app, output: help };
+    }
+    return { app, output };
+  }
+
+  await app.start();
+  return { app, output: "" };
+}
+
+function readStdin() {
+  return new Promise((resolve) => {
+    if (process.stdin.isTTY) return resolve("");
+    let data = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (c) => (data += c));
+    process.stdin.on("end", () => resolve(data));
+    setTimeout(() => resolve(data), 1000);
+  });
+}

package/src/commands/onboard.mjs

@@ -0,0 +1,52 @@
+/**
+ * `cirvix onboard` — the 10-second first run.
+ *
+ * A guided demo, not a man page: it shows one allowed call and one real
+ * blocked credential read, then hands the user the console.
+ */
+
+import { Pipeline } from "../core/pipeline.mjs";
+import { compile } from "../core/policy-dsl.mjs";
+import { STARTER_POLICY } from "./init.mjs";
+import { blockedCard, policyCard } from "../tui/cards.mjs";
+import { bold, dim, style } from "../core/theme.mjs";
+
+export async function onboard({ cwd = process.cwd(), pace = 500, write = (s) => process.stdout.write(s) } = {}) {
+  const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+  const rules = compile(STARTER_POLICY, { cwd, origin: "onboard" }).rules;
+  const pipeline = new Pipeline({ rules, cwd, agent: "you" });
+
+  write("\n");
+  write(`  ${bold("◆ CIRVIX")}\n`);
+  write(`  ${dim("Runtime Authorization Engine")}\n\n`);
+  write(`  ${dim("Cirvix evaluates what your AI agents are allowed to do.")}\n\n`);
+  write(`  ${style("✓", "allow")} ${dim("Identity")}   ${style("✓", "allow")} ${dim("Policy")}   ${style("✓", "allow")} ${dim("Context")}   ${style("✓", "allow")} ${dim("Risk")}\n\n`);
+  await sleep(pace);
+
+  write(`  ${bold("Let's test it.")}\n`);
+  write(`  ${dim("> Read ~/.aws/credentials")}\n\n`);
+  await sleep(pace);
+
+  const { event } = await pipeline.submit({ tool: "read_file", arguments: { path: "~/.aws/credentials" } });
+  write(blockedCard({
+    tool: event.tool,
+    target: "~/.aws/credentials",
+    policy: event.policy ?? "credential-protection",
+    reason: event.reason ?? "This path contains credentials.",
+  }).split("\n").map((l) => "  " + l).join("\n") + "\n\n");
+  write(`  ${style("Cirvix protected your credentials.", "allow")}\n\n`);
+  await sleep(pace);
+
+  const { event: ok } = await pipeline.submit({ tool: "read_file", arguments: { path: "./src/app.ts" } });
+  write(policyCard({
+    action: ok.tool,
+    risk: ok.risk,
+    policy: ok.policy ?? "allow-workspace-read",
+    identity: "agent:you",
+    reason: "Ordinary workspace reads keep working.",
+  }).split("\n").map((l) => "  " + l).join("\n") + "\n\n");
+
+  write(`  ${dim("Next:")}  ${bold("cirvix console")}  ${dim("— the interactive runtime")}\n`);
+  write(`  ${dim("Or:")}    ${bold("cirvix demo")}     ${dim("— the full live interception")}\n\n`);
+  return { ok: true };
+}

package/src/core/events.mjs

@@ -0,0 +1,234 @@
+/**
+ * Cirvix event model — the contract between the engine and every UI.
+ *
+ * The policy engine never prints. It emits typed events on an EventBus.
+ * Every UI (CLI cards, the interactive console, a future web dashboard or
+ * desktop app, CI reporters) is a renderer over this event stream:
+ *
+ *   Policy engine → Event → State reducer → Component
+ *
+ * Event types:
+ *   SESSION_STARTED / SESSION_ENDED
+ *   USER_MESSAGE            the human typed something into the console
+ *   AGENT_MESSAGE           a text answer to show in the conversation pane
+ *   POLICY_EVALUATION_STARTED
+ *   POLICY_DECISION         one tool call decided (carries the audit event)
+ *   TOOL_STARTED / TOOL_OUTPUT / TOOL_FINISHED
+ *   APPROVAL_REQUESTED / APPROVAL_GRANTED / APPROVAL_DENIED
+ *   AUDIT_COMPLETED
+ *   RUNTIME_ERROR
+ *   STATUS_SNAPSHOT       rolling counters for the status bar
+ *
+ * Zero dependencies. Serializable (JSON-safe) by construction so the same
+ * events can cross the UDS socket or be recorded in tests.
+ */
+
+export const EVENT = {
+  SESSION_STARTED: "SESSION_STARTED",
+  SESSION_ENDED: "SESSION_ENDED",
+  USER_MESSAGE: "USER_MESSAGE",
+  AGENT_MESSAGE: "AGENT_MESSAGE",
+  POLICY_EVALUATION_STARTED: "POLICY_EVALUATION_STARTED",
+  POLICY_DECISION: "POLICY_DECISION",
+  TOOL_STARTED: "TOOL_STARTED",
+  TOOL_OUTPUT: "TOOL_OUTPUT",
+  TOOL_FINISHED: "TOOL_FINISHED",
+  APPROVAL_REQUESTED: "APPROVAL_REQUESTED",
+  APPROVAL_GRANTED: "APPROVAL_GRANTED",
+  APPROVAL_DENIED: "APPROVAL_DENIED",
+  AUDIT_COMPLETED: "AUDIT_COMPLETED",
+  RUNTIME_ERROR: "RUNTIME_ERROR",
+  STATUS_SNAPSHOT: "STATUS_SNAPSHOT",
+};
+
+let seq = 0;
+
+function base(type, payload = {}) {
+  return {
+    type,
+    id: `evt_${Date.now().toString(36)}_${(seq++).toString(36)}`,
+    ts: new Date().toISOString(),
+    ...payload,
+  };
+}
+
+export const createEvent = {
+  sessionStarted: (p = {}) => base(EVENT.SESSION_STARTED, p),
+  sessionEnded: (p = {}) => base(EVENT.SESSION_ENDED, p),
+  userMessage: (text, p = {}) => base(EVENT.USER_MESSAGE, { text, ...p }),
+  agentMessage: (text, p = {}) => base(EVENT.AGENT_MESSAGE, { text, ...p }),
+  evaluationStarted: (p = {}) => base(EVENT.POLICY_EVALUATION_STARTED, p),
+  policyDecision: (decision, p = {}) =>
+    base(EVENT.POLICY_DECISION, {
+      decision: decision?.decision ?? decision?.verdict ?? "deny",
+      tool: decision?.tool ?? decision?.action ?? "unknown",
+      resource: decision?.resource ?? "",
+      risk: decision?.risk ?? "low",
+      policy: decision?.policy ?? decision?.rule ?? null,
+      reason: decision?.reason ?? "",
+      latency_ms: decision?.latency_ms ?? 0,
+      raw: decision,
+      ...p,
+    }),
+  toolStarted: (tool, p = {}) => base(EVENT.TOOL_STARTED, { tool, ...p }),
+  toolOutput: (text, p = {}) => base(EVENT.TOOL_OUTPUT, { text, ...p }),
+  toolFinished: (tool, p = {}) => base(EVENT.TOOL_FINISHED, { tool, ...p }),
+  approvalRequested: (p = {}) => base(EVENT.APPROVAL_REQUESTED, p),
+  approvalGranted: (p = {}) => base(EVENT.APPROVAL_GRANTED, p),
+  approvalDenied: (p = {}) => base(EVENT.APPROVAL_DENIED, p),
+  auditCompleted: (p = {}) => base(EVENT.AUDIT_COMPLETED, p),
+  runtimeError: (message, p = {}) => base(EVENT.RUNTIME_ERROR, { message, ...p }),
+  statusSnapshot: (p = {}) => base(EVENT.STATUS_SNAPSHOT, p),
+};
+
+/**
+ * Minimal pub/sub bus. Sync dispatch (the engine is sync-per-decision);
+ * subscribers never throw into the engine — a broken UI listener is
+ * isolated and reported via `onListenerError`.
+ */
+export class EventBus {
+  constructor({ onListenerError = () => {} } = {}) {
+    this.listeners = new Map();
+    this.onListenerError = onListenerError;
+    this.history = [];
+    this.capped = 2000;
+  }
+
+  on(type, fn) {
+    if (!this.listeners.has(type)) this.listeners.set(type, new Set());
+    this.listeners.get(type).add(fn);
+    return () => this.listeners.get(type)?.delete(fn);
+  }
+
+  onAny(fn) {
+    return this.on("*", fn);
+  }
+
+  emit(event) {
+    this.history.push(event);
+    if (this.history.length > this.capped) this.history.shift();
+    const targets = [
+      ...(this.listeners.get(event.type) ?? []),
+      ...(this.listeners.get("*") ?? []),
+    ];
+    for (const fn of targets) {
+      try {
+        fn(event);
+      } catch (err) {
+        this.onListenerError(err, event);
+      }
+    }
+    return event;
+  }
+
+  replay(types, fn) {
+    for (const e of this.history) {
+      if (!types || types.includes(e.type)) fn(e);
+    }
+  }
+}
+
+/**
+ * Adapt a live Pipeline to the bus: wraps `onEvent` so every decision the
+ * engine makes also becomes a POLICY_DECISION (+ approval/tool) event.
+ * Returns an unsubscribe function.
+ */
+export function attachPipeline(pipeline, bus) {
+  const prev = pipeline.onEvent;
+  pipeline.onEvent = (e) => {
+    try {
+      if (e?.kind === "decision") {
+        bus.emit(createEvent.policyDecision(e));
+        if (e.decision === "require_approval") {
+          bus.emit(createEvent.approvalRequested({ approval_id: e.approval_id, tool: e.tool, resource: e.resource }));
+        }
+      } else if (e?.kind === "scrub") {
+        bus.emit(createEvent.toolOutput(`scrubbed ${e.findings?.length ?? 0} finding(s)`, { findings: e.findings }));
+      }
+    } catch {
+      // event translation must never break enforcement
+    }
+    return prev?.(e);
+  };
+  return () => {
+    pipeline.onEvent = prev;
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Reducer — event stream → renderable UI state                       */
+/* ------------------------------------------------------------------ */
+
+export function initialState() {
+  return {
+    session: null,
+    messages: [], // { role: 'user'|'cirvix', text, ts }
+    activity: [], // POLICY_DECISION payloads, newest last
+    approvals: [], // pending approval requests
+    errors: [],
+    status: {
+      mode: "enforce",
+      requests: 0,
+      allowed: 0,
+      sanitized: 0,
+      blocked: 0,
+      held: 0,
+      latencies: [],
+    },
+    evaluating: false,
+  };
+}
+
+export function reduce(state, event) {
+  switch (event.type) {
+    case EVENT.SESSION_STARTED:
+      return { ...state, session: { id: event.sessionId ?? event.id, startedAt: event.ts, agent: event.agent ?? "local" } };
+    case EVENT.SESSION_ENDED:
+      return { ...state, session: state.session ? { ...state.session, endedAt: event.ts } : null, evaluating: false };
+    case EVENT.USER_MESSAGE:
+      return { ...state, messages: [...state.messages, { role: "user", text: event.text, ts: event.ts }] };
+    case EVENT.AGENT_MESSAGE:
+      return { ...state, messages: [...state.messages, { role: "cirvix", text: event.text, ts: event.ts }] };
+    case EVENT.POLICY_EVALUATION_STARTED:
+      return { ...state, evaluating: true };
+    case EVENT.POLICY_DECISION: {
+      const d = event.decision;
+      const status = { ...state.status, requests: state.status.requests + 1 };
+      if (d === "allow") status.allowed++;
+      else if (d === "sanitize") status.sanitized++;
+      else if (d === "deny") status.blocked++;
+      else if (d === "require_approval") status.held++;
+      if (typeof event.latency_ms === "number") {
+        status.latencies = [...status.latencies.slice(-999), event.latency_ms];
+      }
+      return {
+        ...state,
+        evaluating: false,
+        activity: [...state.activity.slice(-499), event],
+        status,
+      };
+    }
+    case EVENT.APPROVAL_REQUESTED:
+      return { ...state, approvals: [...state.approvals, event] };
+    case EVENT.APPROVAL_GRANTED:
+    case EVENT.APPROVAL_DENIED:
+      return {
+        ...state,
+        approvals: state.approvals.filter((a) => a.approval_id !== event.approval_id),
+      };
+    case EVENT.RUNTIME_ERROR:
+      return { ...state, evaluating: false, errors: [...state.errors.slice(-49), event] };
+    case EVENT.STATUS_SNAPSHOT:
+      return { ...state, status: { ...state.status, ...event.snapshot } };
+    default:
+      return state;
+  }
+}
+
+/** P50/P95 over the reducer's latency window. */
+export function latencyStats(latencies) {
+  if (!latencies?.length) return { p50: 0, p95: 0, samples: 0 };
+  const s = [...latencies].sort((a, b) => a - b);
+  const at = (q) => s[Math.min(s.length - 1, Math.floor(q * s.length))];
+  return { p50: Number(at(0.5).toFixed(2)), p95: Number(at(0.95).toFixed(2)), samples: s.length };
+}

package/src/core/format.mjs

@@ -1,15 +1,29 @@
 /**
- * Terminal formatting.
+ * Terminal formatting — thin compatibility layer over the semantic theme.
  *
- * Colour is suppressed when stdout is not a TTY, when `NO_COLOR` is set, or
- * when `TERM=dumb` — so piping to a file or a CI log produces clean text
- * rather than escape sequences. `FORCE_COLOR` overrides for the cases where a
- * CI runner does support colour but does not present as a TTY.
+ * New code should import from `theme.mjs` and use `colors.*` / `style(text,
+ * role)` so meaning stays in one place. This module keeps the historic names
+ * (`green`, `red`, `amber`, `blue`, `cyan`, `gray`, `white`, `bold`, `dim`,
+ * `plural`) working for the existing CLI, gateway logs, the `core/ui`
+ * primitives, and every test that already asserts on them.
  *
- * The palette mirrors the product's chroma rule: green means permitted, red
- * means denied, amber means held. Nothing decorative uses them.
+ * Mapping (the product's chroma rule — green means permitted, red denied,
+ * amber held, blue/cyan sanitized or informational, gray muted):
+ *   green → allow · red → block · amber → hold/warning · blue/cyan → sanitize
+ *   gray → muted · white → text
  */
 
+export { bold, dim, colors, style, setTheme, themeName, THEME_NAMES } from "./theme.mjs";
+import { style } from "./theme.mjs";
+
+export const green = (s) => style(s, "allow");
+export const red = (s) => style(s, "block");
+export const amber = (s) => style(s, "hold");
+export const blue = (s) => style(s, "sanitize");
+export const cyan = (s) => style(s, "sanitize");
+export const gray = (s) => style(s, "muted");
+export const white = (s) => style(s, "text");
+
 const forced = process.env.FORCE_COLOR === "1" || process.env.FORCE_COLOR === "true";
 const disabled =
   !forced &&
@@ -17,22 +31,9 @@ const disabled =
     process.env.TERM === "dumb" ||
     !process.stdout.isTTY);
 
-const wrap = (open, close) => (s) =>
-  disabled ? String(s) : `[${open}m${s}[${close}m`;
-
-export const bold = wrap(1, 22);
-export const dim = wrap(2, 22);
-export const red = wrap(31, 39);
-export const green = wrap(32, 39);
-export const amber = wrap(33, 39);
-export const blue = wrap(34, 39);
-export const cyan = wrap(36, 39);
-export const gray = wrap(90, 39);
-export const white = wrap(97, 39);
-
 /** Strip ANSI escape sequences for width calculation and secret checks. */
 export function stripAnsi(s) {
-  return String(s).replace(/\u001b\[[0-9;]*m/g, "");
+  return String(s).replace(/\[[0-9;]*m/g, "");
 }
 
 /** Visible character width, ignoring ANSI. */