@cirvix_ai/agent-control 0.1.3 → 0.2.0

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/evidence.mjs

@@ -0,0 +1,212 @@
+/**
+ * Evidence packs.
+ *
+ * The primitives already existed — prove.mjs signs a decision, the audit chain
+ * verifies, buildPassport describes an agent. What did not exist was the thing
+ * a security reviewer actually asks for: one bundle, for one scope, that
+ * answers "show me this agent was controlled" without the reviewer having to
+ * know which four commands to run.
+ *
+ * THE ONE RULE THIS FILE EXISTS TO ENFORCE
+ * ---------------------------------------
+ * A pack maps controls. It never claims compliance.
+ *
+ * "SOC 2 CC6.1" appearing next to a decision means Cirvix believes this
+ * evidence is relevant to that control. It does not mean the control is met,
+ * that an auditor agreed, or that anybody is certified. The vocabulary below
+ * has no word for "compliant" and a test asserts it never acquires one —
+ * because the moment a generated PDF says "SOC 2 compliant", somebody forwards
+ * it to a customer and the claim is ours.
+ *
+ * WHAT NEVER GOES IN
+ * ------------------
+ * Arguments and results are excluded wholesale rather than redacted. A
+ * redactor is a filter that has to be right every time; an exclusion is right
+ * by construction. The pack carries what was decided, under which rule, and
+ * whether the chain verifies — none of which needs the payload.
+ */
+
+import { createHash } from "node:crypto";
+import { canonicalJson } from "./audit.mjs";
+
+export const EVIDENCE_VERSION = 1;
+
+/**
+ * Coverage vocabulary. Deliberately has no "pass" and no "compliant".
+ *
+ * `mapped` is the strongest word available and it only means evidence exists.
+ * Adding a stronger term is the one change to this file that would turn a
+ * useful artifact into a liability.
+ */
+export const COVERAGE = Object.freeze({
+  MAPPED: "mapped",           // evidence exists and is attached
+  PARTIAL: "partial",         // some evidence, with a stated gap
+  NOT_COVERED: "not_covered", // in scope, nothing found
+  OUT_OF_SCOPE: "out_of_scope",
+});
+
+/**
+ * Control mappings. Intentionally few, and each says what it is evidenced BY.
+ *
+ * A long list of frameworks would look more impressive and mean less: every
+ * row Cirvix cannot actually evidence is a row a reviewer will find empty.
+ */
+const CONTROLS = [
+  { id: "SOC2.CC6.1", framework: "SOC 2", title: "Logical access controls restrict access to protected resources",
+    evidencedBy: "decisions" },
+  { id: "SOC2.CC6.3", framework: "SOC 2", title: "Access is removed or modified when no longer appropriate",
+    evidencedBy: "policyVersions" },
+  { id: "SOC2.CC7.2", framework: "SOC 2", title: "Anomalies are identified and analysed",
+    evidencedBy: "denials" },
+  { id: "SOC2.CC7.3", framework: "SOC 2", title: "Security events are evaluated and acted upon",
+    evidencedBy: "approvals" },
+  { id: "ISO27001.A.8.16", framework: "ISO/IEC 27001:2022", title: "Monitoring activities",
+    evidencedBy: "decisions" },
+  { id: "ISO27001.A.5.15", framework: "ISO/IEC 27001:2022", title: "Access control",
+    evidencedBy: "policyVersions" },
+  { id: "NIST.AI.RMF.MEASURE.2.7", framework: "NIST AI RMF", title: "AI system security and resilience are evaluated",
+    evidencedBy: "denials" },
+  { id: "NIST.AI.RMF.MANAGE.4.1", framework: "NIST AI RMF", title: "Post-deployment monitoring plans are implemented",
+    evidencedBy: "chain" },
+];
+
+/** Fields that may appear on a decision inside a pack. Everything else is dropped. */
+const DECISION_FIELDS = [
+  "decision_id", "ts", "agent", "action", "tool", "resource", "destination",
+  "verdict", "decision", "rule", "reason", "risk", "environment", "run_id", "hash", "prev_hash",
+];
+
+function slimDecision(record) {
+  const out = {};
+  for (const f of DECISION_FIELDS) if (record[f] !== undefined) out[f] = record[f];
+  return out;
+}
+
+/**
+ * Assembles a pack.
+ *
+ * `records` are audit records already read from the chain — this function does
+ * no I/O, so it is testable and so the caller decides what it is allowed to
+ * read.
+ */
+export function buildEvidencePack({
+  records = [],
+  agent = null,
+  org = null,
+  from = null,
+  to = null,
+  passport = null,
+  policyVersions = [],
+  proofs = [],
+  approvals = [],
+  chain = null,
+  now = () => new Date().toISOString(),
+} = {}) {
+  const inWindow = (r) => {
+    const t = r.ts ?? r.timestamp;
+    if (from && t && t < from) return false;
+    if (to && t && t > to) return false;
+    return true;
+  };
+  const scoped = records
+    .filter((r) => (agent ? r.agent === agent : true))
+    .filter(inWindow);
+
+  const decisions = scoped.map(slimDecision);
+  const denials = decisions.filter((d) => d.verdict === "deny" || d.decision === "deny");
+  const held = decisions.filter((d) => d.decision === "require_approval" || d.verdict === "hold");
+
+  const evidence = {
+    decisions: decisions.length,
+    denials: denials.length,
+    approvals: approvals.length,
+    policyVersions: policyVersions.length,
+    chain: chain?.ok === true ? 1 : 0,
+  };
+
+  const coverage = CONTROLS.map((c) => {
+    const n = evidence[c.evidencedBy] ?? 0;
+    return {
+      control: c.id,
+      framework: c.framework,
+      title: c.title,
+      coverage: n > 0 ? COVERAGE.MAPPED : COVERAGE.NOT_COVERED,
+      evidence: `${n} ${c.evidencedBy}`,
+    };
+  });
+
+  const pack = {
+    v: EVIDENCE_VERSION,
+    kind: "evidence_pack",
+    generatedAt: now(),
+    scope: { agent, org, from, to },
+    summary: {
+      decisions: decisions.length,
+      denied: denials.length,
+      heldForApproval: held.length,
+      distinctRules: [...new Set(decisions.map((d) => d.rule).filter(Boolean))].length,
+      chainVerified: chain?.ok === true,
+      chainRecords: chain?.records ?? null,
+      chainHead: chain?.head ?? null,
+    },
+    passport: passport ?? null,
+    policyVersions: policyVersions.map((p) => ({ version: p.version ?? null, hash: p.hash ?? null, publishedAt: p.publishedAt ?? null })),
+    decisions,
+    approvals: approvals.map((a) => ({ id: a.id ?? null, decidedBy: a.decidedBy ?? null, decision: a.decision ?? null, at: a.at ?? null })),
+    proofs: proofs.map((p) => (typeof p === "string" ? { token: p } : { token: p.token ?? null, decisionId: p.decisionId ?? null })),
+    controlMapping: coverage,
+    /* Load-bearing. Read by humans who will forward this onward. */
+    disclaimer:
+      "This pack maps evidence to control identifiers. It is not an audit, a certification, " +
+      "or a statement of compliance. No control is asserted to be met, and no framework " +
+      "listed here has assessed this system. Coverage of 'mapped' means only that relevant " +
+      "evidence is attached.",
+  };
+
+  pack.digest = "sha256:" + createHash("sha256").update(canonicalJson({ ...pack, digest: undefined })).digest("hex");
+  return pack;
+}
+
+/** The human-readable report. Plain text so it survives every pipeline. */
+export function renderEvidenceReport(pack) {
+  const s = pack.summary;
+  const lines = [
+    "CIRVIX EVIDENCE PACK",
+    "",
+    `Generated    ${pack.generatedAt}`,
+    `Agent        ${pack.scope.agent ?? "(all agents)"}`,
+    `Window       ${pack.scope.from ?? "(open)"} → ${pack.scope.to ?? "(open)"}`,
+    `Digest       ${pack.digest}`,
+    "",
+    "SUMMARY",
+    `  Decisions recorded     ${s.decisions}`,
+    `  Denied                 ${s.denied}`,
+    `  Held for approval      ${s.heldForApproval}`,
+    `  Distinct rules applied ${s.distinctRules}`,
+    `  Audit chain            ${s.chainVerified ? `verified, ${s.chainRecords} records` : "NOT VERIFIED"}`,
+    "",
+  ];
+
+  if (pack.passport?.trust) {
+    const t = pack.passport.trust;
+    lines.push("TRUST", `  Score  ${t.score ?? "unscored"}${t.band ? ` (${t.band})` : ""}`, "");
+  }
+
+  lines.push("CONTROL MAPPING", "");
+  for (const c of pack.controlMapping) {
+    lines.push(`  ${c.coverage === COVERAGE.MAPPED ? "▪" : "·"} ${c.control.padEnd(28)} ${c.coverage.padEnd(12)} ${c.evidence}`);
+  }
+  lines.push("", "  " + pack.disclaimer.replace(/(.{1,72})(\s|$)/g, "$1\n  ").trim(), "");
+  return lines.join("\n");
+}
+
+/**
+ * Re-derives the digest.
+ *
+ * A pack that has been edited after generation fails here. The digest is over
+ * the canonical form minus itself, so it is stable across serialisation.
+ */
+export function verifyEvidencePack(pack) {
+  const expected = "sha256:" + createHash("sha256").update(canonicalJson({ ...pack, digest: undefined })).digest("hex");
+  return { ok: expected === pack.digest, expected, actual: pack.digest };
+}

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,17 +31,29 @@ 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);
-/** Motion/informational accent only — verdicts stay green/red/amber. */
-export const cyan = wrap(36, 39);
+/** Strip ANSI escape sequences for width calculation and secret checks. */
+export function stripAnsi(s) {
+  return String(s).replace(/\[[0-9;]*m/g, "");
+}
+
+/** Visible character width, ignoring ANSI. */
+export function visibleWidth(s) {
+  return stripAnsi(String(s)).length;
+}
+
+/** True when output should be decorated (TTY, not NO_COLOR, not dumb, not CI unless forced). */
+export function isInteractive() {
+  if (disabled) return false;
+  if (process.env.CI !== undefined && !forced) return false;
+  return Boolean(process.stdout.isTTY);
+}
+
+/** Whether unicode box-drawing is safe. ASCII fallback when TERM=dumb or CIRVIX_ASCII=1. */
+export function supportsUnicode() {
+  if (process.env.CIRVIX_ASCII === "1") return false;
+  if (process.env.TERM === "dumb") return false;
+  return true;
+}
 
 /** "1 server" / "3 servers" — avoids the "1 servers" that reads as a bug. */
 export function plural(n, noun, pluralForm) {