@cirvix_ai/agent-control 0.1.0

package/src/commands/scan.mjs

@@ -0,0 +1,210 @@
+/**
+ * `cirvix scan` — the free, read-only inventory.
+ *
+ * This is the command the whole funnel rests on, so it has one job: tell a
+ * developer something true about their machine that they did not already
+ * know, in under five seconds, without an account and without sending
+ * anything anywhere.
+ *
+ * It writes nothing and opens no sockets.
+ */
+
+import {
+  collectMcpServers,
+  detectCredentials,
+  detectFrameworks,
+  detectRuntimes,
+} from "../core/detect.mjs";
+import { bold, dim, green, red, amber, blue, plural } from "../core/format.mjs";
+
+export async function scan({ cwd = process.cwd(), json = false, deep = false } = {}) {
+  const runtimes = await detectRuntimes();
+  const frameworks = await detectFrameworks(cwd);
+  const servers = collectMcpServers(runtimes);
+  const credentials = await detectCredentials(cwd);
+
+  const findings = buildFindings({ runtimes, frameworks, servers, credentials });
+  const counts = tally(findings);
+
+  const result = {
+    scannedAt: new Date().toISOString(),
+    cwd,
+    runtimes: runtimes.map(({ servers: _s, ...r }) => r),
+    frameworks,
+    mcpServers: servers,
+    credentials: credentials.map(({ keys: _k, ...c }) => c),
+    findings,
+    counts,
+  };
+
+  if (json) return { result, output: JSON.stringify(result, null, 2) };
+  return { result, output: render(result, { deep }) };
+}
+
+/* -------------------------------------------------------------------------- */
+
+function buildFindings({ runtimes, frameworks, servers, credentials }) {
+  const findings = [];
+
+  for (const r of runtimes) {
+    if (!r.governed) {
+      findings.push({
+        severity: "high",
+        code: "runtime-ungoverned",
+        subject: r.label,
+        detail: `Tool calls from ${r.label} are not routed through a control plane. Anything it can reach, it can reach unchecked.`,
+        fix: `cirvix gateway --servers ${r.path}`,
+      });
+    }
+  }
+
+  for (const f of frameworks) {
+    findings.push({
+      severity: "medium",
+      code: "framework-uninstrumented",
+      subject: f.label,
+      detail: `${f.label} detected in this project with no Cirvix middleware on its tool boundary.`,
+      fix: "Wrap the executor boundary: guard.wrap(tools, { agent, rules })",
+    });
+  }
+
+  for (const s of servers) {
+    if (s.scope?.broad) {
+      findings.push({
+        severity: "high",
+        code: "mcp-broad-scope",
+        subject: s.name,
+        detail: `Exposes ${s.scope.widest} to any agent that can call it — far wider than a workspace.`,
+        fix: "Narrow the server's path arguments, or scope it per-agent through the gateway.",
+      });
+    }
+    if (s.envKeys.length > 0) {
+      findings.push({
+        severity: "medium",
+        code: "mcp-inline-secrets",
+        subject: s.name,
+        detail: `Configuration carries ${plural(s.envKeys.length, "environment value")} inline (${s.envKeys.slice(0, 3).join(", ")}${s.envKeys.length > 3 ? "…" : ""}). These sit in a plaintext config file.`,
+        fix: "Move to secret handles brokered at the boundary.",
+      });
+    }
+    if (s.runtimes.length > 1) {
+      findings.push({
+        severity: "low",
+        code: "mcp-duplicated",
+        subject: s.name,
+        detail: `Configured separately in ${s.runtimes.join(" and ")} — one trust boundary with ${s.runtimes.length} doors, each updated independently.`,
+        fix: "Register once and route both runtimes through the gateway.",
+      });
+    }
+  }
+
+  for (const c of credentials) {
+    findings.push({
+      severity: c.severity,
+      code: c.kind === "dotenv" ? "env-readable" : "credential-readable",
+      subject: c.label,
+      detail: c.detail,
+      fix: "Route agents through cirvix gateway — the starter policy already denies reads of this path.",
+    });
+  }
+
+  const order = { high: 0, medium: 1, low: 2 };
+  return findings.sort((a, b) => order[a.severity] - order[b.severity]);
+}
+
+function tally(findings) {
+  return findings.reduce(
+    (acc, f) => ({ ...acc, [f.severity]: (acc[f.severity] ?? 0) + 1 }),
+    { high: 0, medium: 0, low: 0 },
+  );
+}
+
+/* -------------------------------------------------------------------------- */
+
+function render(r, { deep }) {
+  const L = [];
+  // padEnd does nothing when the string already exceeds the column, which
+  // collides the label with the next field. Always guarantee one space.
+  const pad = (s, n) => {
+    const v = String(s);
+    return v.length >= n ? v + " " : v.padEnd(n);
+  };
+
+  L.push("");
+  L.push(`  ${bold("Cirvix scan")} ${dim("· read-only · nothing was changed or sent")}`);
+  L.push("");
+
+  // Runtimes
+  L.push(`  ${bold("runtimes")}${dim(pad("", 12))}${r.runtimes.length ? plural(r.runtimes.length, "found") : dim("none detected")}`);
+  for (const rt of r.runtimes) {
+    const state = rt.governed ? green("governed") : red("ungoverned");
+    L.push(`    ${pad(rt.label, 18)}${dim(shorten(rt.path))}`);
+    L.push(`    ${pad("", 18)}${state}${dim(` · ${plural(rt.serverCount, "MCP server")}`)}`);
+  }
+  if (r.frameworks.length) {
+    for (const f of r.frameworks) {
+      L.push(`    ${pad(f.label, 18)}${dim(f.via)}`);
+      L.push(`    ${pad("", 18)}${amber("uninstrumented")}`);
+    }
+  }
+  L.push("");
+
+  // MCP servers
+  L.push(`  ${bold("mcp servers")}${dim(pad("", 9))}${r.mcpServers.length ? plural(r.mcpServers.length, "configured") : dim("none")}`);
+  for (const s of r.mcpServers) {
+    const flags = [];
+    if (s.scope?.broad) flags.push(red("broad scope"));
+    if (s.envKeys.length) flags.push(amber("inline secrets"));
+    if (s.runtimes.length > 1) flags.push(dim(`×${s.runtimes.length} runtimes`));
+    L.push(`    ${pad(s.name, 18)}${pad(s.transport, 8)}${flags.join(dim(" · "))}`);
+    if (deep && s.command) L.push(`    ${pad("", 18)}${dim(s.command + " " + s.args.join(" "))}`);
+  }
+  L.push("");
+
+  // Credentials
+  L.push(`  ${bold("credentials")}${dim(pad("", 9))}${r.credentials.length ? `${plural(r.credentials.length, "path")} reachable from agent context` : dim("none reachable")}`);
+  for (const c of r.credentials) {
+    L.push(`    ${pad(c.label, 18)}${dim(c.detail)}`);
+  }
+  L.push("");
+
+  // Findings
+  const { high, medium, low } = r.counts;
+  const summary = [
+    high ? red(`${high} high`) : null,
+    medium ? amber(`${medium} medium`) : null,
+    low ? dim(`${low} low`) : null,
+  ]
+    .filter(Boolean)
+    .join(dim(" · "));
+
+  L.push(`  ${bold("findings")}${dim(pad("", 12))}${summary || green("nothing ungoverned")}`);
+  L.push("");
+
+  for (const f of r.findings.slice(0, 12)) {
+    const mark = f.severity === "high" ? red("▲") : f.severity === "medium" ? amber("▲") : dim("▪");
+    L.push(`    ${mark} ${bold(f.subject)} ${dim(`(${f.code})`)}`);
+    L.push(`      ${f.detail}`);
+    L.push(`      ${dim("fix:")} ${blue(f.fix)}`);
+    L.push("");
+  }
+  if (r.findings.length > 12) {
+    L.push(`    ${dim(`…and ${r.findings.length - 12} more. Run with --json for the full list.`)}`);
+    L.push("");
+  }
+
+  if (r.findings.length > 0) {
+    L.push(`  ${dim("Nothing was changed. To see how a call would be decided:")}`);
+    L.push(`    ${blue("cirvix check --action fs.read --resource .env")}`);
+  } else {
+    L.push(`  ${green("No ungoverned surfaces found on this machine.")}`);
+  }
+  L.push("");
+
+  return L.join("\n");
+}
+
+function shorten(p) {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  return home && p.startsWith(home) ? "~" + p.slice(home.length) : p;
+}

package/src/commands/status.mjs

@@ -0,0 +1,208 @@
+/**
+ * `cirvix status` — what is protected, right now.
+ *
+ *   CIRVIX AGENTCONTROL
+ *
+ *   Runtime       RUNNING
+ *   Policy        17 rules
+ *   MCP Servers   6
+ *   Protected     4
+ *   Blocked       3
+ *   Approvals     2
+ *   P99 overhead  2.1ms
+ *
+ * EVERY NUMBER HERE IS MEASURED, NOT ASSERTED.
+ *
+ * `Protected` counts runtimes whose MCP traffic actually routes through the
+ * gateway — read out of their config files, not out of ours. `Blocked` and
+ * `Approvals` are counted from the audit chain. `P99 overhead` is computed from
+ * recorded per-decision latencies and shows `—` when there are none, rather
+ * than a plausible-looking default.
+ *
+ * That last one matters more than it sounds. A status screen that prints a
+ * latency figure before anything has been measured is how a design target
+ * becomes a benchmark result in a deck three weeks later.
+ */
+
+import { access, readFile } from "node:fs/promises";
+import { join } from "node:path";
+
+import { collectMcpServers, detectRuntimes } from "../core/detect.mjs";
+import { read as readJournal, summarize } from "../core/journal.mjs";
+import { ApprovalStore } from "../core/approvals.mjs";
+import { UdsClient, defaultEndpoint, tokenPath } from "../core/uds.mjs";
+import { MODE } from "../core/decisions.mjs";
+import { bold, dim, green, red, amber, blue, plural } from "../core/format.mjs";
+
+async function exists(path) {
+  try {
+    await access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Is the runtime actually up?
+ *
+ * Answered by connecting to the control socket, not by checking for a pid file.
+ * A stale pid file is the standard way a status command reports RUNNING for a
+ * process that died an hour ago, and this is a security control — "is it on"
+ * has to be the truth.
+ */
+async function probeRuntime(stateDir) {
+  const endpoint = defaultEndpoint(stateDir);
+  if (!(await exists(tokenPath(stateDir)))) return { running: false, endpoint, reason: "no session token" };
+  let token;
+  try {
+    token = (await readFile(tokenPath(stateDir), "utf8")).trim();
+  } catch {
+    return { running: false, endpoint, reason: "unreadable session token" };
+  }
+  try {
+    const client = new UdsClient({ endpoint, token, timeoutMs: 1500 });
+    const status = await client.call("cirvix/status", {});
+    return { running: true, endpoint, live: status };
+  } catch {
+    return { running: false, endpoint, reason: "nothing listening" };
+  }
+}
+
+/**
+ * @param {object} opts
+ * @param {string} opts.cwd
+ * @param {Array} [opts.rules]      already-loaded rule set
+ * @param {boolean} [opts.json]
+ */
+export async function status({ cwd = process.cwd(), rules = [], json = false, stateDir: dir } = {}) {
+  const stateDir = dir ?? join(cwd, ".cirvix");
+
+  const [runtimes, runtime, records] = await Promise.all([
+    detectRuntimes(),
+    probeRuntime(stateDir),
+    readJournal(join(stateDir, "audit.jsonl")),
+  ]);
+
+  const servers = collectMcpServers(runtimes);
+  const protectedRuntimes = runtimes.filter((r) => r.governed);
+  const stats = summarize(records);
+
+  let approvals = { pending: 0, total: 0 };
+  const approvalsPath = join(stateDir, "approvals.jsonl");
+  if (await exists(approvalsPath)) {
+    const store = await new ApprovalStore(approvalsPath).open();
+    approvals = { pending: store.pending().length, total: store.all().length };
+  }
+
+  const result = {
+    runtime: {
+      running: runtime.running,
+      endpoint: runtime.endpoint,
+      reason: runtime.reason ?? null,
+      mode: runtime.live?.mode ?? MODE.ENFORCE,
+    },
+    policy: {
+      rules: rules.length,
+      // A live runtime is the authority on how many rules are actually loaded;
+      // the file on disk may have been edited since it started.
+      loaded: runtime.live?.rules ?? null,
+    },
+    mcpServers: servers.length,
+    runtimes: runtimes.map((r) => ({
+      id: r.id,
+      label: r.label,
+      governed: r.governed,
+      servers: r.serverCount,
+    })),
+    protected: protectedRuntimes.length,
+    decisions: stats.counts,
+    blocked: stats.counts.deny,
+    approvals,
+    risks: stats.risks,
+    latency: stats.latency,
+    vault: runtime.live?.vault ?? null,
+    records: stats.records,
+    topRules: stats.topRules,
+  };
+
+  if (json) return { result, output: JSON.stringify(result, null, 2) };
+  return { result, output: render(result) };
+}
+
+/* -------------------------------------------------------------------------- */
+
+function render(r) {
+  const rows = [
+    ["Runtime", r.runtime.running ? green(bold("RUNNING")) : dim("STOPPED") + dim(`  ${r.runtime.reason ?? ""}`)],
+    ["Policy", r.policy.rules ? `${plural(r.policy.rules, "rule")}` : dim("no policy loaded")],
+    ["MCP Servers", String(r.mcpServers)],
+    [
+      "Protected",
+      r.protected === 0 && r.runtimes.length > 0
+        ? amber(String(r.protected)) + dim(`  of ${r.runtimes.length} — nothing is routed through the gateway yet`)
+        : `${r.protected}` + dim(r.runtimes.length ? `  of ${r.runtimes.length}` : ""),
+    ],
+    ["Blocked", r.blocked > 0 ? red(String(r.blocked)) : String(r.blocked)],
+    ["Approvals", r.approvals.pending > 0 ? amber(`${r.approvals.pending} pending`) : String(r.approvals.pending)],
+    [
+      "P99 overhead",
+      r.latency.samples
+        ? `${r.latency.p99}ms` + dim(`  over ${plural(r.latency.samples, "decision")}`)
+        : dim("— nothing measured yet"),
+    ],
+  ];
+
+  const width = Math.max(...rows.map(([k]) => k.length));
+  const lines = ["", `  ${bold("CIRVIX AGENTCONTROL")}`, ""];
+  for (const [key, value] of rows) lines.push(`  ${key.padEnd(width + 2)}${value}`);
+
+  if (r.runtime.mode !== MODE.ENFORCE) {
+    lines.push("");
+    lines.push(`  ${amber(bold("AUDIT MODE"))}  ${dim("decisions are recorded and nothing is blocked.")}`);
+  }
+
+  if (r.records > 0) {
+    lines.push("");
+    lines.push(`  ${dim("decisions")}   ` +
+      [
+        green(`${r.decisions.allow} allowed`),
+        r.decisions.sanitize ? blue(`${r.decisions.sanitize} sanitized`) : null,
+        r.decisions.require_approval ? amber(`${r.decisions.require_approval} held`) : null,
+        r.decisions.deny ? red(`${r.decisions.deny} denied`) : null,
+        r.decisions.audit_only ? dim(`${r.decisions.audit_only} audit-only`) : null,
+      ]
+        .filter(Boolean)
+        .join(dim("  ·  ")));
+
+    const risky = r.risks.high + r.risks.critical;
+    if (risky > 0) {
+      lines.push(`  ${dim("risk")}        ` +
+        [
+          r.risks.critical ? red(`${r.risks.critical} critical`) : null,
+          r.risks.high ? amber(`${r.risks.high} high`) : null,
+          r.risks.medium ? `${r.risks.medium} medium` : null,
+          r.risks.low ? dim(`${r.risks.low} low`) : null,
+        ]
+          .filter(Boolean)
+          .join(dim("  ·  ")));
+    }
+  }
+
+  if (r.vault) {
+    lines.push(`  ${dim("vault")}       ${r.vault.held} held` + (r.vault.unscoped ? amber(`  ${r.vault.unscoped} unscoped`) : ""));
+  }
+
+  lines.push("");
+
+  if (!r.runtime.running && r.mcpServers > 0) {
+    lines.push(`  ${dim("Start it:")}  ${blue("cirvix gateway --servers <mcp.json>")}`);
+    lines.push("");
+  }
+  if (r.approvals.pending > 0) {
+    lines.push(`  ${amber(`${plural(r.approvals.pending, "call")} waiting on a human:`)}  ${blue("cirvix approvals")}`);
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}

package/src/commands/upgrade.mjs

@@ -0,0 +1,162 @@
+/**
+ * `cirvix upgrade [tier]` — show where the limits are, and how to lift them.
+ *
+ *   cirvix upgrade            what you are on, what you have used, what is next
+ *   cirvix upgrade pro        the checkout link for a specific tier
+ *   cirvix upgrade --seats 5  Team, priced for a real number of seats
+ *
+ * WHAT THIS DELIBERATELY DOES NOT DO
+ *
+ * It does not take a payment, and it does not write a paid licence. It prints
+ * a URL. The licence file is written by the checkout callback, because a
+ * command that could grant itself Pro is not an entitlement system — and the
+ * one thing worse than honour-system metering is metering with a documented
+ * bypass in its own CLI.
+ *
+ * The tone is deliberately flat. Every prompt this product prints appears in
+ * the middle of somebody's terminal session while they were trying to do
+ * something else, and marketing language in that position reads as an
+ * interruption rather than an offer. State the limit, state the number, give
+ * the command, stop.
+ */
+
+import { TIERS, TIER_ORDER, dailyAllowance, nextTier, tierFor } from "../core/entitlements.mjs";
+import { Meter, readLicence } from "../core/meter.mjs";
+
+/** Published prices. Mirrors the pricing page; pinned by the test suite. */
+export const PRICING = {
+  free: { monthly: 0, annual: 0 },
+  starter: { monthly: 29, annual: 290 },
+  pro: { monthly: 79, annual: 790 },
+  team: { monthly: 149, annual: 1490, perSeat: true, minSeats: 3 },
+  enterprise: { monthly: null, annual: null, custom: true },
+};
+
+const CHECKOUT_BASE = "https://www.cirvix.com/pricing.html";
+
+export function checkoutUrl(tier, { seats } = {}) {
+  const t = tierFor(tier);
+  if (t.id === "free") return CHECKOUT_BASE;
+  const params = new URLSearchParams({ plan: t.id });
+  if (seats && PRICING[t.id]?.perSeat) params.set("seats", String(seats));
+  return `${CHECKOUT_BASE}?${params.toString()}`;
+}
+
+const money = (n) => `$${n.toLocaleString("en-US")}`;
+
+/** One line describing what a tier costs. */
+export function priceLine(tierId, seats) {
+  const p = PRICING[tierId];
+  if (!p) return "";
+  if (p.custom) return "Custom — scoped to your deployment";
+  if (p.monthly === 0) return "Free, forever";
+  if (p.perSeat) {
+    const n = Math.max(Number(seats) || 0, p.minSeats);
+    return `${money(p.monthly)}/seat/mo · ${money(p.monthly * n)}/mo for ${n} seats · ${money(p.annual)}/seat/yr`;
+  }
+  return `${money(p.monthly)}/mo · ${money(p.annual)}/yr (2 months free)`;
+}
+
+/** What a tier lifts, relative to the one below it. Only real differences. */
+function liftsOver(fromId, toId) {
+  const from = tierFor(fromId);
+  const to = tierFor(toId);
+  const out = [];
+
+  const fromAllow = dailyAllowance({ tier: from.id, seats: from.seatsIncluded });
+  const toAllow = dailyAllowance({ tier: to.id, seats: to.seatsIncluded });
+  if (toAllow === null) out.push("Uncapped decisions");
+  else if (fromAllow !== null && toAllow > fromAllow) {
+    out.push(
+      `${toAllow.toLocaleString("en-US")} decisions/day` +
+        (to.perSeat ? ` (${to.decisionsPerDay.toLocaleString("en-US")} per seat)` : "") +
+        ` — up from ${fromAllow.toLocaleString("en-US")}`,
+    );
+  }
+
+  if (to.agents === null && from.agents !== null) out.push("Unlimited concurrent agents");
+  else if (to.agents !== null && from.agents !== null && to.agents > from.agents) {
+    out.push(`${to.agents} concurrent agents — up from ${from.agents}`);
+  }
+
+  if (to.persistentSecrets && !from.persistentSecrets) {
+    out.push("Secret handles survive a restart");
+  }
+  if (to.approvals && !from.approvals) out.push("Human-in-the-loop approvals");
+  if (to.attestation && !from.attestation) out.push("Attestation headers");
+  if (to.sharedPolicy !== false && from.sharedPolicy === false) out.push("Shared policy + RBAC");
+
+  if (to.auditRetentionHours === null && from.auditRetentionHours !== null) {
+    // Hosted retention is a control-plane capability; the local chain itself
+    // is never pruned on any tier ("life of deployment" everywhere). Say what
+    // the tier actually adds rather than implying local history expires.
+    out.push("Hosted audit retention + export");
+  }
+  return out;
+}
+
+/**
+ * @param {string[]} argv  tokens after `upgrade`
+ */
+export async function upgrade(argv = [], { cwd = process.cwd(), write = (s) => process.stdout.write(s) } = {}) {
+  const seatsFlag = argv.indexOf("--seats");
+  const seats = seatsFlag > -1 ? Number(argv[seatsFlag + 1]) || undefined : undefined;
+  const requested = argv.find((a) => !a.startsWith("--") && TIER_ORDER.includes(a.toLowerCase()));
+
+  const licence = readLicence(cwd);
+  const current = tierFor(licence.tier);
+  const meter = new Meter({ cwd });
+  const used = meter.used();
+  const allowance = dailyAllowance(licence);
+
+  const lines = [];
+  lines.push("");
+  lines.push(`  Current plan   ${current.name}`);
+  lines.push(
+    `  Today          ${used.toLocaleString("en-US")}` +
+      (allowance === null ? " decisions (uncapped)" : ` of ${allowance.toLocaleString("en-US")} decisions`),
+  );
+  if (allowance !== null) {
+    const pct = allowance > 0 ? Math.round((used / allowance) * 100) : 0;
+    lines.push(`  Resets         00:00 UTC${pct >= 80 ? `  ·  ${pct}% used` : ""}`);
+  }
+  lines.push("");
+
+  const target = requested ?? nextTier(current.id);
+
+  if (target === current.id) {
+    lines.push(`  ${current.name} is the highest tier. Nothing to upgrade to.`);
+    lines.push("");
+    write(lines.join("\n") + "\n");
+    return { tier: current.id, used, allowance, url: null };
+  }
+
+  const to = tierFor(target);
+  lines.push(`  ${current.name} → ${to.name}`);
+  lines.push(`  ${priceLine(to.id, seats)}`);
+  lines.push("");
+  for (const lift of liftsOver(current.id, to.id)) lines.push(`    · ${lift}`);
+  lines.push("");
+
+  const url = checkoutUrl(to.id, { seats });
+  lines.push(`  ${url}`);
+  lines.push("");
+  // Said once, plainly, because it is true and because a free tier that keeps
+  // implying it is about to end is not a free tier.
+  lines.push("  The local runtime stays free. This lifts the limits on it.");
+  lines.push("");
+
+  write(lines.join("\n") + "\n");
+  return { tier: current.id, target: to.id, used, allowance, url };
+}
+
+/** The one-off notice printed when a limit is actually hit. */
+export function limitNotice(gateResult, { tier, seats } = {}) {
+  const to = nextTier(tier ?? "free");
+  return [
+    `[cirvix] ${gateResult.reason}`,
+    `          ${priceLine(to, seats)} — cirvix upgrade ${to}`,
+  ].join("\n");
+}
+
+export { TIERS };