@cirvix_ai/agent-control 0.1.3 → 0.2.0

package/bin/escape-benchmark.mjs

@@ -0,0 +1,67 @@
+#!/usr/bin/env node
+/**
+ * Runs the Agent Escape Benchmark and prints the result.
+ *
+ * Exits non-zero when anything escapes, so it can gate a release. A benchmark
+ * that always exits 0 is a slideshow.
+ *
+ *   node bin/escape-benchmark.mjs             # human-readable
+ *   node bin/escape-benchmark.mjs --json      # machine-readable
+ *   node bin/escape-benchmark.mjs --out FILE  # write JSON evidence
+ */
+import { writeFileSync } from "node:fs";
+import { runBenchmark } from "../src/core/escape-benchmark.mjs";
+
+const argv = process.argv.slice(2);
+const asJson = argv.includes("--json");
+const outAt = argv.indexOf("--out");
+const outFile = outAt === -1 ? null : argv[outAt + 1];
+
+const r = await runBenchmark();
+
+if (outFile) {
+  /* The full results, including every step — the summary alone is a claim,
+     and the steps are what let someone else check it. */
+  writeFileSync(outFile, JSON.stringify(r, null, 2));
+}
+
+if (asJson) {
+  console.log(JSON.stringify(r, null, 2));
+} else {
+  const bar = "─".repeat(58);
+  console.log(bar);
+  console.log(" CIRVIX AGENT ESCAPE BENCHMARK");
+  console.log(bar);
+  console.log(` Scenarios                    ${String(r.scenarios).padStart(5)}`);
+  console.log(` Escape attempts              ${String(r.attempts).padStart(5)}`);
+  console.log(` Blocked                      ${String(r.blocked).padStart(5)}`);
+  console.log(` Successful escapes           ${String(r.escaped).padStart(5)}`);
+  console.log(` Authorization integrity      ${String(r.integrity + "%").padStart(5)}`);
+  console.log(` Controls held                ${String(`${r.controls.held}/${r.controls.total}`).padStart(5)}`);
+  console.log(bar);
+  for (const [k, v] of Object.entries(r.byCategory)) {
+    console.log(` ${k.replace(/_/g, " ").toUpperCase().padEnd(26)} ${String(v.attempts).padStart(4)}`);
+    console.log(`   blocked                  ${String(v.blocked).padStart(4)}${v.escaped ? `   ESCAPED ${v.escaped}` : ""}`);
+  }
+  console.log(bar);
+  if (r.escapes.length) {
+    console.log("\n ESCAPES — investigate before shipping:");
+    for (const e of r.escapes) {
+      console.log(`   ${e.id}  ${e.name}  [${e.category}, level ${e.level}]`);
+      for (const s of e.steps) console.log(`      ${s.tool} → ${s.verdict} (${s.rule})`);
+    }
+  }
+  if (r.brokenControls.length) {
+    console.log("\n BROKEN CONTROLS — the mission cannot do its own job:");
+    for (const b of r.brokenControls) {
+      console.log(`   ${b.id}  ${b.name}`);
+      for (const s of b.steps) console.log(`      ${s.tool} → ${s.verdict} (${s.rule})`);
+    }
+  }
+  if (!r.escapes.length && !r.brokenControls.length) {
+    console.log("\n Every attempt contained; every mission still able to work.");
+  }
+  console.log(`\n ${r.generatedAt}`);
+}
+
+process.exit(r.escaped > 0 || r.brokenControls.length > 0 ? 1 : 0);

package/package.json

@@ -1,27 +1,24 @@
 {
   "name": "@cirvix_ai/agent-control",
-  "version": "0.1.3",
-  "description": "Cirvix AgentControl — runtime governance for AI agents. Scan what is ungoverned, evaluate policy, and broker tool calls.",
+  "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/",
   "type": "module",
-  "homepage": "https://www.cirvix.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/CIRVIX/agent-control.git",
-    "directory": "packages/agent-control"
-  },
-  "bugs": {
-    "url": "https://github.com/CIRVIX/agent-control/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
   "bin": {
     "cirvix": "./bin/cirvix.mjs"
   },
   "engines": {
     "node": ">=20"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/CIRVIX/agent-control"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
   "files": [
     "bin",
     "src",
@@ -36,7 +33,8 @@
     "bench": "node ../../benchmarks/decision.mjs",
     "scan": "node bin/cirvix.mjs scan",
     "demo": "node bin/cirvix.mjs demo",
-    "verify:adversarial": "node test/adversarial/verify.mjs"
+    "verify:adversarial": "node test/adversarial/verify.mjs",
+    "benchmark:escape": "node bin/escape-benchmark.mjs"
   },
   "keywords": [
     "ai",
@@ -55,6 +53,28 @@
     "./audit": "./src/core/audit.mjs",
     "./secrets": "./src/core/secrets.mjs",
     "./guard": "./src/core/guard.mjs",
-    "./testing": "./src/testing.mjs"
+    "./testing": "./src/testing.mjs",
+    "./passport": "./src/core/passport.mjs",
+    "./cost": "./src/core/cost.mjs",
+    "./proof": "./src/core/proof.mjs",
+    "./trifecta": "./src/core/trifecta.mjs",
+    "./packs": "./src/core/packs.mjs",
+    "./graph": "./src/core/graph.mjs",
+    "./evidence": "./src/core/evidence.mjs",
+    "./referral": "./src/core/referral.mjs",
+    "./authority": "./src/core/authority.mjs",
+    "./delegation": "./src/core/delegation.mjs",
+    "./escape-benchmark": "./src/core/escape-benchmark.mjs",
+    "./adapters": "./src/adapters/index.mjs",
+    "./windows": "./src/core/windows.mjs",
+    "./config-store": "./src/core/config-store.mjs",
+    "./intent": "./src/core/intent.mjs",
+    "./session": "./src/core/session.mjs",
+    "./baseline": "./src/core/baseline.mjs",
+    "./kill-switch": "./src/core/kill-switch.mjs",
+    "./sandbox": "./src/core/sandbox.mjs",
+    "./shadow": "./src/core/shadow.mjs",
+    "./redteam": "./src/core/redteam/index.mjs",
+    "./verified": "./src/core/verified.mjs"
   }
 }

package/src/adapters/base.mjs

@@ -0,0 +1,150 @@
+/**
+ * Base Agent Adapter interface and definitions for CIRVIX AgentControl.
+ *
+ * Provides the unified foundation for runtime/editor/framework-agnostic
+ * governance. Each adapter implements detection, configuration lifecycle,
+ * and request/response normalization for a specific agent environment.
+ */
+
+import { access, readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseConfigJson } from "../core/config-store.mjs";
+import { normalizeFsPath, arePathsEqual } from "../core/windows.mjs";
+
+/**
+ * Strict Compatibility Levels.
+ * Never claim "supported" or "enforced" without empirical verification.
+ */
+export const COMPATIBILITY_LEVEL = {
+  /** Config file or executable exists on disk. */
+  DISCOVERED: "DISCOVERED",
+  /** Valid configuration found; CIRVIX adapter can generate an integration plan. */
+  CONFIGURABLE: "CONFIGURABLE",
+  /** Configuration routes agent tool traffic to CIRVIX. */
+  INTEGRATED: "INTEGRATED",
+  /** Gateway or runtime has received protocol handshake/initialize from this agent. */
+  ROUTED: "ROUTED",
+  /** Policy engine has evaluated at least one tool call from this agent. */
+  ENFORCED: "ENFORCED",
+  /** Full end-to-end tool invocation passed through CIRVIX with verified audit entry. */
+  VERIFIED: "VERIFIED",
+};
+
+export class BaseAgentAdapter {
+  /**
+   * @param {object} spec
+   * @param {string} spec.id - Unique ID, e.g. "claude-code", "cursor", "codex"
+   * @param {string} spec.label - Human readable name, e.g. "Claude Code"
+   * @param {string} spec.type - "cli" | "editor" | "extension" | "framework" | "generic"
+   * @param {string} [spec.mcpKey="mcpServers"] - Property holding MCP server definitions
+   */
+  constructor({ id, label, type, mcpKey = "mcpServers" }) {
+    this.id = id;
+    this.label = label;
+    this.type = type;
+    this.mcpKey = mcpKey;
+  }
+
+  /**
+   * Discovers presence of this runtime on the host and in the workspace.
+   *
+   * @param {string} cwd
+   * @returns {Promise<{ detected: boolean, paths: string[], config: object|null, executable: string|null, version: string|null, metadata: object }>}
+   */
+  async detect(cwd) {
+    throw new Error(`detect() not implemented on ${this.id}`);
+  }
+
+  /**
+   * Determines the strict compatibility level of this agent.
+   *
+   * @param {object} detectedInfo
+   * @param {string} [stateDir]
+   * @returns {Promise<string>} One of COMPATIBILITY_LEVEL values
+   */
+  async getCompatibilityLevel(detectedInfo, stateDir) {
+    if (!detectedInfo || !detectedInfo.detected) {
+      return null;
+    }
+
+    const { isIntegrated, hasConfig, hasAuditLogs, hasVerifiedCall } = detectedInfo;
+
+    if (hasVerifiedCall) return COMPATIBILITY_LEVEL.VERIFIED;
+    if (hasAuditLogs) return COMPATIBILITY_LEVEL.ENFORCED;
+    if (detectedInfo.isRouted) return COMPATIBILITY_LEVEL.ROUTED;
+    if (isIntegrated) return COMPATIBILITY_LEVEL.INTEGRATED;
+    if (hasConfig) return COMPATIBILITY_LEVEL.CONFIGURABLE;
+    return COMPATIBILITY_LEVEL.DISCOVERED;
+  }
+
+  /**
+   * Helper to check if a file path exists and is readable.
+   */
+  async fileExists(filePath) {
+    try {
+      await access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * Reads and parses a JSON/JSONC configuration file.
+   */
+  async readJson(filePath) {
+    try {
+      const raw = await readFile(filePath, "utf8");
+      return parseConfigJson(raw);
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Checks if an MCP server definition belongs to CIRVIX.
+   */
+  isCirvixServer(name, def) {
+    if (name === "cirvix") return true;
+    if (typeof def?.command === "string" && def.command.includes("cirvix")) return true;
+    if (Array.isArray(def?.args) && def.args.some((a) => typeof a === "string" && a.includes("cirvix"))) return true;
+    return false;
+  }
+
+  /**
+   * Generates a non-destructive integration plan.
+   *
+   * @param {string} cwd
+   * @param {object} options
+   * @returns {Promise<{ adapterId: string, label: string, targetFile: string, canIntegrate: boolean, currentServers: Record<string, any>, plan: object, reason: string }>}
+   */
+  async generateIntegrationPlan(cwd, options = {}) {
+    throw new Error(`generateIntegrationPlan() not implemented on ${this.id}`);
+  }
+
+  /**
+   * Normalizes a tool call into the universal CIRVIX format.
+   */
+  normalizeRequest(rawRequest, ctx = {}) {
+    const rawArgs = rawRequest.args ?? rawRequest.arguments ?? rawRequest.tool_input ?? rawRequest.toolInput ?? {};
+    return {
+      agent: this.id,
+      runtime: this.label,
+      ...rawRequest,
+      args: rawArgs,
+      arguments: rawArgs,
+    };
+  }
+
+  /**
+   * Formats a CIRVIX decision into the response expected by this runtime.
+   */
+  formatResponse(decision, rawResult) {
+    return {
+      decision: decision.decision,
+      verdict: decision.verdict,
+      reason: decision.reason,
+      rawResult,
+    };
+  }
+}

package/src/adapters/claude-code.mjs

@@ -0,0 +1,161 @@
+/**
+ * Claude Code Adapter for CIRVIX AgentControl.
+ *
+ * Supports:
+ * - ~/.claude/settings.json, ~/.claude.json, workspace .claude/settings.json
+ * - PreToolUse hook bridging for non-MCP built-in tools (Bash, Read, Write, Edit, WebFetch)
+ * - CLAUDE.md instruction integration
+ * - Executable detection (claude / claude.cmd)
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BaseAgentAdapter, COMPATIBILITY_LEVEL } from "./base.mjs";
+import { resolveExecutable } from "../core/windows.mjs";
+
+export class ClaudeCodeAdapter extends BaseAgentAdapter {
+  constructor() {
+    super({
+      id: "claude-code",
+      label: "Claude Code",
+      type: "cli",
+      mcpKey: "mcpServers",
+    });
+  }
+
+  async detect(cwd) {
+    const home = homedir();
+    const candidatePaths = [
+      join(cwd, ".claude", "settings.json"),
+      join(cwd, ".claude.json"),
+      join(home, ".claude", "settings.json"),
+      join(home, ".claude.json"),
+    ];
+
+    const existingPaths = [];
+    const servers = {};
+    let configFound = null;
+
+    for (const p of candidatePaths) {
+      if (await this.fileExists(p)) {
+        existingPaths.push(p);
+        const data = await this.readJson(p);
+        if (data) {
+          if (!configFound) configFound = data;
+          Object.assign(servers, data[this.mcpKey] ?? {});
+        }
+      }
+    }
+
+    const execPath = resolveExecutable("claude", { cwd });
+    const hasInstructions = await this.fileExists(join(cwd, "CLAUDE.md"));
+    const detected = existingPaths.length > 0 || Boolean(execPath) || hasInstructions;
+
+    const isIntegrated = Object.entries(servers).some(([name, def]) => this.isCirvixServer(name, def));
+
+    return {
+      detected,
+      paths: existingPaths,
+      targetConfigPath: existingPaths[0] ?? join(home, ".claude", "settings.json"),
+      config: configFound,
+      servers,
+      serverCount: Object.keys(servers).length,
+      isIntegrated,
+      hasConfig: existingPaths.length > 0,
+      executable: execPath,
+      metadata: {
+        hasInstructions,
+        hookSupported: true,
+      },
+    };
+  }
+
+  async generateIntegrationPlan(cwd, options = {}) {
+    const info = await this.detect(cwd);
+    const targetFile = info.targetConfigPath;
+    const currentServers = { ...info.servers };
+
+    // Upstream servers without cirvix itself
+    const upstreams = {};
+    for (const [k, v] of Object.entries(currentServers)) {
+      if (!this.isCirvixServer(k, v)) upstreams[k] = v;
+    }
+
+    const cirvixServerDef = {
+      command: "cirvix",
+      args: ["gateway", "--servers", targetFile.replace(/\\/g, "/")],
+    };
+
+    const newConfig = {
+      ...(info.config || {}),
+      [this.mcpKey]: {
+        ...currentServers,
+        cirvix: cirvixServerDef,
+      },
+    };
+
+    return {
+      adapterId: this.id,
+      label: this.label,
+      targetFile,
+      canIntegrate: true,
+      currentServers,
+      upstreams,
+      plan: newConfig,
+      snippet: JSON.stringify({ [this.mcpKey]: { cirvix: cirvixServerDef } }, null, 2),
+      reason: "Routes Claude Code MCP tool invocations through the CIRVIX gateway.",
+    };
+  }
+
+  normalizeRequest(rawRequest, ctx = {}) {
+    // Built-in tools mapping if called from PreToolUse hook
+    const name = rawRequest.tool_name ?? rawRequest.toolName ?? rawRequest.tool ?? "";
+    const args = rawRequest.tool_input ?? rawRequest.toolInput ?? rawRequest.arguments ?? {};
+
+    let tool = name;
+    let normalizedArgs = { ...args };
+
+    switch (name) {
+      case "Bash":
+        tool = "shell.exec";
+        normalizedArgs = { command: args.command ?? "" };
+        break;
+      case "Read":
+        tool = "filesystem.read";
+        normalizedArgs = { path: args.file_path ?? args.path ?? "" };
+        break;
+      case "Write":
+        tool = "filesystem.write";
+        normalizedArgs = { path: args.file_path ?? args.path ?? "" };
+        break;
+      case "Edit":
+      case "NotebookEdit":
+        tool = "filesystem.write";
+        normalizedArgs = { path: args.file_path ?? args.notebook_path ?? "" };
+        break;
+      case "Glob":
+        tool = "filesystem.list";
+        normalizedArgs = { path: args.path ?? args.pattern ?? "" };
+        break;
+      case "Grep":
+        tool = "filesystem.search";
+        normalizedArgs = { path: args.path ?? "" };
+        break;
+      case "WebFetch":
+        tool = "network.request";
+        normalizedArgs = { url: args.url ?? "" };
+        break;
+      default:
+        break;
+    }
+
+    return {
+      agent: this.id,
+      runtime: this.label,
+      tool,
+      args: normalizedArgs,
+      arguments: normalizedArgs,
+      source: rawRequest.source ?? "claude-code",
+    };
+  }
+}

package/src/adapters/cline.mjs

@@ -0,0 +1,107 @@
+/**
+ * Cline Adapter for CIRVIX AgentControl.
+ *
+ * Supports:
+ * - VS Code globalStorage cline_mcp_settings.json across Windows, macOS, Linux
+ * - Workspace .cline/mcp_settings.json
+ * - .clinerules
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BaseAgentAdapter } from "./base.mjs";
+
+export class ClineAdapter extends BaseAgentAdapter {
+  constructor() {
+    super({
+      id: "cline",
+      label: "Cline",
+      type: "extension",
+      mcpKey: "mcpServers",
+    });
+  }
+
+  async detect(cwd) {
+    const home = homedir();
+    const candidatePaths = [
+      join(cwd, ".cline", "mcp_settings.json"),
+      // Windows
+      join(home, "AppData", "Roaming", "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
+      // macOS
+      join(home, "Library", "Application Support", "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
+      // Linux
+      join(home, ".config", "Code", "User", "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
+    ];
+
+    const existingPaths = [];
+    const servers = {};
+    let configFound = null;
+
+    for (const p of candidatePaths) {
+      if (await this.fileExists(p)) {
+        existingPaths.push(p);
+        const data = await this.readJson(p);
+        if (data) {
+          if (!configFound) configFound = data;
+          Object.assign(servers, data[this.mcpKey] ?? {});
+        }
+      }
+    }
+
+    const hasRules = await this.fileExists(join(cwd, ".clinerules"));
+    const detected = existingPaths.length > 0 || hasRules;
+
+    const isIntegrated = Object.entries(servers).some(([name, def]) => this.isCirvixServer(name, def));
+
+    return {
+      detected,
+      paths: existingPaths,
+      targetConfigPath: existingPaths[0] ?? candidatePaths[1],
+      config: configFound,
+      servers,
+      serverCount: Object.keys(servers).length,
+      isIntegrated,
+      hasConfig: existingPaths.length > 0,
+      executable: null,
+      metadata: {
+        hasRules,
+      },
+    };
+  }
+
+  async generateIntegrationPlan(cwd, options = {}) {
+    const info = await this.detect(cwd);
+    const targetFile = info.targetConfigPath;
+    const currentServers = { ...info.servers };
+
+    const upstreams = {};
+    for (const [k, v] of Object.entries(currentServers)) {
+      if (!this.isCirvixServer(k, v)) upstreams[k] = v;
+    }
+
+    const cirvixServerDef = {
+      command: "cirvix",
+      args: ["gateway", "--servers", targetFile.replace(/\\/g, "/")],
+    };
+
+    const newConfig = {
+      ...(info.config || {}),
+      [this.mcpKey]: {
+        ...currentServers,
+        cirvix: cirvixServerDef,
+      },
+    };
+
+    return {
+      adapterId: this.id,
+      label: this.label,
+      targetFile,
+      canIntegrate: true,
+      currentServers,
+      upstreams,
+      plan: newConfig,
+      snippet: JSON.stringify({ [this.mcpKey]: { cirvix: cirvixServerDef } }, null, 2),
+      reason: "Binds Cline MCP server actions to CIRVIX policy evaluation.",
+    };
+  }
+}

package/src/adapters/codex.mjs

@@ -0,0 +1,104 @@
+/**
+ * OpenAI Codex CLI Adapter for CIRVIX AgentControl.
+ *
+ * Supports:
+ * - ~/.codex/config.json, codex.json, .codex/mcp.json
+ * - Executable detection (codex / codex.cmd)
+ */
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { BaseAgentAdapter } from "./base.mjs";
+import { resolveExecutable } from "../core/windows.mjs";
+
+export class CodexAdapter extends BaseAgentAdapter {
+  constructor() {
+    super({
+      id: "codex",
+      label: "OpenAI Codex CLI",
+      type: "cli",
+      mcpKey: "mcpServers",
+    });
+  }
+
+  async detect(cwd) {
+    const home = homedir();
+    const candidatePaths = [
+      join(cwd, "codex.json"),
+      join(cwd, ".codex", "config.json"),
+      join(cwd, ".codex", "mcp.json"),
+      join(home, ".codex", "config.json"),
+      join(home, ".codex", "mcp.json"),
+    ];
+
+    const existingPaths = [];
+    const servers = {};
+    let configFound = null;
+
+    for (const p of candidatePaths) {
+      if (await this.fileExists(p)) {
+        existingPaths.push(p);
+        const data = await this.readJson(p);
+        if (data) {
+          if (!configFound) configFound = data;
+          const map = data.mcpServers ?? data.mcp_servers ?? data.servers ?? {};
+          Object.assign(servers, map);
+        }
+      }
+    }
+
+    const execPath = resolveExecutable("codex", { cwd });
+    const detected = existingPaths.length > 0 || Boolean(execPath);
+
+    const isIntegrated = Object.entries(servers).some(([name, def]) => this.isCirvixServer(name, def));
+
+    return {
+      detected,
+      paths: existingPaths,
+      targetConfigPath: existingPaths[0] ?? join(home, ".codex", "config.json"),
+      config: configFound,
+      servers,
+      serverCount: Object.keys(servers).length,
+      isIntegrated,
+      hasConfig: existingPaths.length > 0,
+      executable: execPath,
+      metadata: {},
+    };
+  }
+
+  async generateIntegrationPlan(cwd, options = {}) {
+    const info = await this.detect(cwd);
+    const targetFile = info.targetConfigPath;
+    const currentServers = { ...info.servers };
+
+    const upstreams = {};
+    for (const [k, v] of Object.entries(currentServers)) {
+      if (!this.isCirvixServer(k, v)) upstreams[k] = v;
+    }
+
+    const cirvixServerDef = {
+      command: "cirvix",
+      args: ["gateway", "--servers", targetFile.replace(/\\/g, "/")],
+    };
+
+    const newConfig = {
+      ...(info.config || {}),
+      [this.mcpKey]: {
+        ...currentServers,
+        cirvix: cirvixServerDef,
+      },
+    };
+
+    return {
+      adapterId: this.id,
+      label: this.label,
+      targetFile,
+      canIntegrate: true,
+      currentServers,
+      upstreams,
+      plan: newConfig,
+      snippet: JSON.stringify({ [this.mcpKey]: { cirvix: cirvixServerDef } }, null, 2),
+      reason: "Places CIRVIX policy enforcement between Codex CLI and local execution tools.",
+    };
+  }
+}