@det-acp/core 0.2.0

package/examples/coding-agent.policy.yaml

@@ -0,0 +1,80 @@
+version: "1.0"
+name: "coding-agent"
+description: "Policy for AI coding agents (Cursor, Claude Code, Codex) operating on a project"
+
+capabilities:
+  - tool: "file:read"
+    scope:
+      paths:
+        - "./src/**"
+        - "./tests/**"
+        - "./package.json"
+        - "./tsconfig.json"
+        - "./README.md"
+  - tool: "file:write"
+    scope:
+      paths:
+        - "./src/**"
+        - "./tests/**"
+  - tool: "command:run"
+    scope:
+      binaries:
+        - "npm"
+        - "npx"
+        - "node"
+        - "tsc"
+        - "git"
+        - "echo"
+        - "cat"
+        - "ls"
+  - tool: "git:diff"
+    scope:
+      repos: ["."]
+  - tool: "git:apply"
+    scope:
+      repos: ["."]
+
+limits:
+  max_runtime_ms: 1800000    # 30 minutes
+  max_files_changed: 30
+  max_output_bytes: 10485760  # 10MB
+  max_cost_usd: 5.0
+
+gates:
+  - action: "command:run"
+    approval: "human"
+    risk_level: "high"
+    condition: "outside_scope"
+
+evidence:
+  require: ["checksums", "diffs"]
+  format: "jsonl"
+
+forbidden:
+  - pattern: "**/.env"
+  - pattern: "**/.env.*"
+  - pattern: "**/credentials*"
+  - pattern: "**/secrets*"
+  - pattern: "curl | sh"
+  - pattern: "wget | sh"
+  - pattern: "npm publish"
+  - pattern: "git push --force"
+
+session:
+  max_actions: 200
+  max_denials: 20
+  rate_limit:
+    max_per_minute: 60
+  escalation:
+    - after_actions: 50
+      require: human_checkin
+    - after_minutes: 15
+      require: human_checkin
+
+remediation:
+  rules:
+    - match: "ENOENT"
+      action: "retry"
+    - match: "EACCES"
+      action: "abort"
+  fallback_chain: ["retry", "skip", "abort"]

package/examples/devops-deploy.policy.yaml

@@ -0,0 +1,107 @@
+# DevOps Deployment Agent Policy
+# Constrains a deployment agent to operate within safe boundaries.
+
+version: "1.0"
+name: "devops-deploy"
+description: "Policy for a deployment agent that builds, tests, and deploys application code."
+
+capabilities:
+  - tool: "file:read"
+    scope:
+      paths:
+        - "/app/**"
+        - "/config/**"
+
+  - tool: "file:write"
+    scope:
+      paths:
+        - "/app/dist/**"
+        - "/tmp/deploy-work/**"
+
+  - tool: "command:run"
+    scope:
+      binaries:
+        - "npm"
+        - "node"
+        - "docker"
+        - "kubectl"
+        - "git"
+        - "curl"
+
+  - tool: "git:diff"
+    scope:
+      repos:
+        - "/app"
+
+  - tool: "git:apply"
+    scope:
+      repos:
+        - "/app"
+
+  - tool: "http:request"
+    scope:
+      domains:
+        - "registry.npmjs.org"
+        - "api.github.com"
+        - "k8s.internal.yourcompany.com"
+      methods:
+        - "GET"
+        - "POST"
+
+limits:
+  max_runtime_ms: 600000       # 10 minutes
+  max_output_bytes: 1073741824 # 1 GB
+  max_files_changed: 200
+  max_retries: 2
+  max_cost_usd: 5.0
+
+gates:
+  - action: "command:run"
+    approval: "human"
+    risk_level: "high"
+    condition: "outside_scope"
+
+  - action: "http:request"
+    approval: "human"
+    risk_level: "high"
+
+  - action: "file:delete"
+    approval: "human"
+    risk_level: "critical"
+
+evidence:
+  require:
+    - "diffs"
+    - "checksums"
+    - "exit_codes"
+    - "logs"
+  format: "jsonl"
+
+forbidden:
+  - pattern: "rm -rf /"
+  - pattern: "**/.env"
+  - pattern: "**/credentials*"
+  - pattern: "**/secrets/**"
+  - pattern: "kubectl delete namespace"
+
+session:
+  max_actions: 100
+  max_denials: 10
+  rate_limit:
+    max_per_minute: 30
+  escalation:
+    - after_actions: 30
+      require: human_checkin
+    - after_minutes: 5
+      require: human_checkin
+
+remediation:
+  rules:
+    - match: "npm ERR!"
+      action: "retry"
+    - match: "docker: Error"
+      action: "abort"
+    - match: "kubectl error"
+      action: "abort"
+    - match: "ECONNREFUSED"
+      action: "retry"

package/examples/mcp-proxy.config.yaml

@@ -0,0 +1,34 @@
+# MCP Proxy Configuration
+#
+# This config file tells the MCP proxy how to connect to backend MCP servers
+# and which policy to enforce on all tool calls.
+#
+# Usage: det-acp proxy ./mcp-proxy.config.yaml
+
+# Policy to enforce on all proxied tool calls
+policy: ./coding-agent.policy.yaml
+
+# Directory for evidence ledger files
+ledger_dir: ./.det-acp/ledgers
+
+# Transport to expose to the agent (stdio for local, sse for remote)
+transport: stdio
+
+# Backend MCP servers to proxy tool calls to
+backends:
+  - name: filesystem
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-filesystem", "./src"]
+
+  - name: github
+    transport: stdio
+    command: npx
+    args: ["-y", "@modelcontextprotocol/server-github"]
+    env:
+      GITHUB_TOKEN: "${GITHUB_TOKEN}"
+
+# Optional metadata attached to every session
+session_metadata:
+  source: mcp-proxy
+  project: my-project

package/examples/simple-session.ts

@@ -0,0 +1,161 @@
+/**
+ * Example: Simple Session Gateway Usage
+ *
+ * Demonstrates the core gateway API — creating a session, evaluating actions,
+ * recording results, and terminating with a report.
+ *
+ * Run: npx tsx examples/simple-session.ts
+ */
+
+import { AgentGateway } from '../src/index.js';
+
+const POLICY_YAML = `
+version: "1.0"
+name: "simple-session-example"
+
+capabilities:
+  - tool: "file:read"
+    scope:
+      paths: ["/tmp/det-acp-demo/**"]
+  - tool: "file:write"
+    scope:
+      paths: ["/tmp/det-acp-demo/**"]
+  - tool: "command:run"
+    scope:
+      binaries: ["echo", "ls", "cat"]
+
+limits:
+  max_runtime_ms: 60000
+  max_files_changed: 10
+
+gates: []
+
+evidence:
+  require: ["checksums"]
+  format: "jsonl"
+
+forbidden:
+  - pattern: "**/.env"
+  - pattern: "rm -rf"
+
+session:
+  max_actions: 20
+  max_denials: 5
+`;
+
+async function main() {
+  // 1. Create the gateway
+  const gateway = await AgentGateway.create({
+    ledgerDir: '/tmp/det-acp-demo/ledgers',
+    onStateChange: (sessionId, from, to) => {
+      console.log(`  [${sessionId.slice(0, 8)}] ${from} → ${to}`);
+    },
+  });
+
+  console.log('=== Deterministic Agent Control Protocol — Session Gateway Demo ===\n');
+
+  // 2. Create a session
+  const session = await gateway.createSession(POLICY_YAML, {
+    agent: 'demo-agent',
+    purpose: 'demonstrate session API',
+  });
+  console.log(`Session created: ${session.id}`);
+  console.log(`Policy: ${session.policy.name}\n`);
+
+  // 3. Evaluate some actions
+  console.log('--- Evaluating actions ---\n');
+
+  // Allowed: read within scope
+  const read = await gateway.evaluate(session.id, {
+    tool: 'file:read',
+    input: { path: '/tmp/det-acp-demo/data.txt' },
+  });
+  console.log(`file:read /tmp/det-acp-demo/data.txt → ${read.decision}`);
+
+  // Record result (simulating external execution)
+  if (read.decision === 'allow') {
+    await gateway.recordResult(session.id, read.actionId, {
+      success: true,
+      output: 'Hello from data.txt',
+      durationMs: 5,
+    });
+    console.log(`  Result recorded: success\n`);
+  }
+
+  // Allowed: write within scope
+  const write = await gateway.evaluate(session.id, {
+    tool: 'file:write',
+    input: { path: '/tmp/det-acp-demo/output.txt', content: 'Agent wrote this' },
+  });
+  console.log(`file:write /tmp/det-acp-demo/output.txt → ${write.decision}`);
+
+  if (write.decision === 'allow') {
+    await gateway.recordResult(session.id, write.actionId, {
+      success: true,
+      output: { path: '/tmp/det-acp-demo/output.txt', bytesWritten: 15 },
+      durationMs: 3,
+    });
+    console.log(`  Result recorded: success\n`);
+  }
+
+  // Denied: read outside scope
+  const deniedRead = await gateway.evaluate(session.id, {
+    tool: 'file:read',
+    input: { path: '/etc/passwd' },
+  });
+  console.log(`file:read /etc/passwd → ${deniedRead.decision}`);
+  console.log(`  Reasons: ${deniedRead.reasons.join('; ')}\n`);
+
+  // Denied: forbidden command
+  const deniedCmd = await gateway.evaluate(session.id, {
+    tool: 'command:run',
+    input: { command: 'rm -rf /tmp' },
+  });
+  console.log(`command:run "rm -rf /tmp" → ${deniedCmd.decision}`);
+  console.log(`  Reasons: ${deniedCmd.reasons.join('; ')}\n`);
+
+  // Allowed: safe command
+  const echoCmd = await gateway.evaluate(session.id, {
+    tool: 'command:run',
+    input: { command: 'echo "hello from agent"' },
+  });
+  console.log(`command:run "echo hello" → ${echoCmd.decision}`);
+
+  if (echoCmd.decision === 'allow') {
+    await gateway.recordResult(session.id, echoCmd.actionId, {
+      success: true,
+      output: 'hello from agent',
+      durationMs: 10,
+    });
+    console.log(`  Result recorded: success\n`);
+  }
+
+  // 4. Get intermediate report
+  console.log('--- Session Report ---\n');
+  const report = gateway.getSessionReport(session.id);
+  console.log(`Total actions: ${report.totalActions}`);
+  console.log(`  Allowed: ${report.allowed}`);
+  console.log(`  Denied: ${report.denied}`);
+  console.log(`  Gated: ${report.gated}`);
+  console.log(`Budget used:`);
+  console.log(`  Actions evaluated: ${report.budgetUsed.actionsEvaluated}`);
+  console.log(`  Actions denied: ${report.budgetUsed.actionsDenied}`);
+  console.log('');
+
+  // 5. Terminate the session
+  const finalReport = await gateway.terminateSession(session.id, 'Demo complete');
+  console.log(`Session terminated: ${finalReport.state}`);
+  console.log(`Duration: ${finalReport.durationMs}ms`);
+
+  // 6. Verify ledger integrity
+  const ledger = gateway.getSessionLedger(session.id);
+  if (ledger) {
+    const { EvidenceLedger } = await import('../src/ledger/ledger.js');
+    const integrity = EvidenceLedger.verifyIntegrity(ledger.getFilePath());
+    console.log(`\nLedger integrity: ${integrity.valid ? 'VALID' : 'BROKEN'}`);
+    console.log(`Ledger entries: ${integrity.totalEntries}`);
+    console.log(`Ledger path: ${ledger.getFilePath()}`);
+  }
+}
+
+main().catch(console.error);

package/examples/video-upscaler.policy.yaml

@@ -0,0 +1,86 @@
+# Video Upscaler Agent Policy
+# This policy constrains a video upscaling agent to operate safely.
+
+version: "1.0"
+name: "video-upscaler"
+description: "Policy for a video upscaling agent that reads input video files, runs upscaling binaries, and writes output files."
+
+capabilities:
+  - tool: "file:read"
+    scope:
+      paths:
+        - "/data/in/**"
+        - "/data/models/**"
+
+  - tool: "file:write"
+    scope:
+      paths:
+        - "/data/out/**"
+        - "/tmp/agent-work/**"
+
+  - tool: "command:run"
+    scope:
+      binaries:
+        - "ffmpeg"
+        - "realesrgan-ncnn-vulkan"
+        - "video2x"
+        - "ffprobe"
+
+  - tool: "http:request"
+    scope:
+      domains:
+        - "downloads.yourcompany.com"
+        - "models.yourcompany.com"
+      methods:
+        - "GET"
+
+limits:
+  max_runtime_ms: 1800000      # 30 minutes
+  max_output_bytes: 5368709120  # 5 GB
+  max_files_changed: 50
+  max_retries: 3
+
+gates:
+  - action: "file:delete"
+    approval: "human"
+    risk_level: "high"
+
+  - action: "command:run"
+    approval: "auto"
+    risk_level: "medium"
+
+evidence:
+  require:
+    - "diffs"
+    - "checksums"
+    - "exit_codes"
+  format: "jsonl"
+
+forbidden:
+  - pattern: "rm -rf"
+  - pattern: "**/.env"
+  - pattern: "**/secrets/**"
+  - pattern: "/etc/**"
+  - pattern: "/usr/**"
+
+session:
+  max_actions: 50
+  max_denials: 5
+  escalation:
+    - after_minutes: 15
+      require: human_checkin
+
+remediation:
+  rules:
+    - match: "CUDA out of memory"
+      action: "fallback:vulkan"
+    - match: "Vulkan device not found"
+      action: "fallback:cpu"
+    - match: "disk full"
+      action: "abort"
+    - match: "permission denied"
+      action: "abort"
+  fallback_chain:
+    - "cuda"
+    - "vulkan"
+    - "cpu"

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@det-acp/core",
+  "version": "0.2.0",
+  "description": "Agent Governance Gateway — bounded, auditable, session-aware control for AI agents with MCP proxy, shell proxy, and HTTP API",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./policy": {
+      "types": "./dist/policy/loader.d.ts",
+      "import": "./dist/policy/loader.js"
+    },
+    "./server": {
+      "types": "./dist/server/server.d.ts",
+      "import": "./dist/server/server.js"
+    }
+  },
+  "bin": {
+    "det-acp": "dist/cli/index.js"
+  },
+  "files": [
+    "dist/",
+    "schemas/",
+    "examples/",
+    "LICENSE",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "start:server": "node dist/server/server.js",
+    "generate:schema": "node dist/schemas/generate.js",
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm run test"
+  },
+  "keywords": [
+    "agent",
+    "governance",
+    "safety",
+    "control-protocol",
+    "audit",
+    "policy",
+    "mcp",
+    "cursor",
+    "claude-code",
+    "gateway",
+    "session",
+    "ai-agent",
+    "model-context-protocol",
+    "deterministic"
+  ],
+  "author": "det-acp",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/det-acp/agent-control-plane.git"
+  },
+  "homepage": "https://github.com/det-acp/agent-control-plane#readme",
+  "bugs": {
+    "url": "https://github.com/det-acp/agent-control-plane/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "commander": "^14.0.3",
+    "fastify": "^5.7.4",
+    "js-yaml": "^4.1.1",
+    "minimatch": "^10.1.2",
+    "nanoid": "^3.3.11",
+    "pino": "^10.3.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^25.2.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18",
+    "zod-to-json-schema": "^3.25.1"
+  }
+}

package/schemas/generate.ts

@@ -0,0 +1,18 @@
+/**
+ * Generate JSON Schema from Zod policy schema.
+ * Run: npx tsx schemas/generate.ts
+ */
+
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { PolicySchema } from '../src/policy/schema.js';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const jsonSchema = zodToJsonSchema(PolicySchema, {
+  name: 'AgentPolicy',
+  $refStrategy: 'none',
+});
+
+const outputPath = path.resolve(import.meta.dirname, 'policy.schema.json');
+fs.writeFileSync(outputPath, JSON.stringify(jsonSchema, null, 2) + '\n');
+console.log(`Generated JSON Schema at ${outputPath}`);

package/schemas/policy.schema.json

@@ -0,0 +1,7 @@
+{
+  "$ref": "#/definitions/AgentPolicy",
+  "definitions": {
+    "AgentPolicy": {}
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}