确定性代理控制协议

flowchart LR
    A["Agent"] -->|"action request"| CP["Control Protocol"]
    CP -->|"evaluate against policy"| D{"Decision"}
    D -->|"allow"| E["Agent Executes Action"]
    D -->|"deny"| F["Blocked + Reason Logged"]
    D -->|"gate"| G["Human Approval Required"]
    E -->|"record result"| L["Evidence Ledger"]
    G -->|"approved"| E

npm i @det-acp/core

npx det-acp init cursor        # Cursor
npx det-acp init codex         # Codex CLI
npx det-acp init claude-code   # Claude Code

# Use your own policy instead of the default
npx det-acp init cursor --policy ./my-policy.yaml

version: "1.0"
name: "my-agent"

capabilities:
  - tool: "file:read"
    scope:
      paths: ["./src/**"]
  - tool: "file:write"
    scope:
      paths: ["./src/**"]
  - tool: "command:run"
    scope:
      binaries: ["npm", "node", "tsc"]

limits:
  max_runtime_ms: 1800000
  max_files_changed: 50

gates:
  - action: "file:delete"
    approval: "human"
    risk_level: "high"

evidence:
  require: ["checksums", "diffs"]
  format: "jsonl"

forbidden:
  - pattern: "**/.env"
  - pattern: "rm -rf"

session:
  max_actions: 100
  max_denials: 10
  rate_limit:
    max_per_minute: 30
  escalation:
    - after_actions: 50
      require: human_checkin
    - after_minutes: 15
      require: human_checkin

import { AgentGateway } from '@det-acp/core';

const gateway = await AgentGateway.create({
  ledgerDir: './ledgers',
  onStateChange: (sessionId, from, to) => console.log(`${from} -> ${to}`),
});

// Create a session
const session = await gateway.createSession('./agent.policy.yaml', {
  agent: 'my-coding-agent',
});

// Evaluate an action (does NOT execute it)
const verdict = await gateway.evaluate(session.id, {
  tool: 'file:read',
  input: { path: './src/index.ts' },
});

if (verdict.decision === 'allow') {
  // Execute the action yourself
  const content = fs.readFileSync('./src/index.ts', 'utf-8');

  // Record the result
  await gateway.recordResult(session.id, verdict.actionId, {
    success: true,
    output: content,
    durationMs: 5,
  });
}

// Terminate and get report
const report = await gateway.terminateSession(session.id, 'task complete');
console.log(`Allowed: ${report.allowed}, Denied: ${report.denied}`);

npx det-acp proxy --policy ./policy.yaml
npx det-acp proxy --policy ./policy.yaml --dir /path/to/project

npx det-acp exec ./agent.policy.yaml echo "hello"    # Allowed
npx det-acp exec ./agent.policy.yaml rm -rf /tmp      # Denied (forbidden)

npx det-acp serve --port 3100

npx det-acp init <agent>                  # Set up governance (cursor, codex, claude-code)
npx det-acp init <agent> --policy <file>  # Use custom policy
npx det-acp validate <policy-file>        # Validate a policy
npx det-acp proxy --policy <policy-file>  # Start MCP proxy (simplified)
npx det-acp proxy --policy <policy-file> --evolve  # With policy self-evolution
npx det-acp proxy <config-file>           # Start MCP proxy (full config)
npx det-acp exec <policy-file> <command>  # Execute via shell proxy
npx det-acp report <ledger-file>          # View audit report
npx det-acp serve [--port <port>]         # Start HTTP session server

sequenceDiagram
    participant User
    participant Agent as Agent (Cursor / Claude Code)
    participant Proxy as MCP Proxy
    participant GW as Gateway

    Agent->>Proxy: callTool("read_text_file", path)
    Proxy->>GW: evaluate()
    GW-->>Proxy: deny
    Proxy->>Proxy: suggestPolicyChange()
    Proxy-->>Agent: Denied + suggestion + suggestionId

    Agent->>User: "read_text_file denied. Add capability for path X?"
    User-->>Agent: "Yes, add to policy"

    Agent->>Proxy: callTool("policy_evolution_approve", suggestionId, "add-to-policy")
    Proxy->>Proxy: applyPolicyChange + writePolicyToFile
    Proxy-->>Agent: "Policy updated"

    Agent->>Proxy: callTool("read_text_file", path)
    Proxy->>GW: evaluate()
    GW-->>Proxy: allow
    Proxy-->>Agent: file contents

npx det-acp proxy --policy ./policy.yaml --evolve

import { AgentGateway, createCliEvolutionHandler } from '@det-acp/core';

const gateway = await AgentGateway.create({
  ledgerDir: './ledgers',
  policyEvolution: {
    policyPath: './agent.policy.yaml',
    handler: createCliEvolutionHandler(),
    timeoutMs: 30_000,
  },
});

flowchart LR
    subgraph Denial["On Deny"]
        A["Action Denied"] --> B["Suggestion Engine"]
        B --> C{"Suggestible?"}
        C -->|No| D["Keep Deny"]
        C -->|Yes| E["PolicySuggestion + ID"]
    end
    E --> F["Agent presents to user"]
    F --> G{"User Decision"}
    G -->|Add to policy| H["policy_evolution_approve → Apply + Write YAML"]
    G -->|Allow once| I["policy_evolution_approve → Apply in-memory"]
    G -->|Deny| D
    H --> J["Retry original tool call"]
    I --> J
    J --> K{"Verdict"}
    K -->|allow| L["Proceed"]
    K -->|deny| D

graph TB
    subgraph External["External Systems"]
        BackendMCP["Backend MCP Servers"]
        Approvers["Human / Webhook Approvers"]
    end

    subgraph Integration["Integration Layer"]
        subgraph MCPProxyGroup["MCP Proxy Server"]
            MCPProxy["MCP Proxy"]
            subgraph McpEvo["MCP Evolution (optional)"]
                McpEvoHandler["MCP Evolution Handler"]
                EvoTool["policy_evolution_approve tool"]
            end
        end
        ShellProxy["Shell Proxy"]
        HTTPServer["HTTP Server"]
        LibrarySDK["Library SDK"]
    end

    subgraph Core["Core Engine"]
        Gateway["Agent Gateway"]
        SessionMgr["Session Manager"]
        PolicyEval["Policy Evaluator"]
        GateMgr["Gate Manager"]
        ActionReg["Action Registry"]
        subgraph Evolution["Policy Self-Evolution (optional)"]
            EvolutionMgr["Policy Evolution Manager"]
            SuggestionEngine["Suggestion Engine"]
        end
    end

    subgraph Infra["Infrastructure"]
        Ledger["Evidence Ledger<br/>(JSONL + SHA-256)"]
        Rollback["Rollback Manager"]
    end

    subgraph Tools["Tool Adapters"]
        subgraph FileTools["File Operations"]
            FR["file:read"]
            FW["file:write"]
            FD["file:delete"]
            FM["file:move"]
            FC["file:copy"]
        end
        subgraph DirTools["Directory Operations"]
            DL["directory:list"]
            DC["directory:create"]
        end
        subgraph GitTools["Git Operations"]
            GD["git:diff"]
            GA["git:apply"]
            GC["git:commit"]
            GS["git:status"]
        end
        subgraph NetTools["Network & System"]
            CR["command:run"]
            HR["http:request"]
            ND["network:dns"]
            ER["env:read"]
            AE["archive:extract"]
        end
    end

    MCPProxy --> Gateway
    ShellProxy --> Gateway
    HTTPServer --> Gateway
    LibrarySDK --> Gateway

    Gateway --> SessionMgr
    Gateway --> ActionReg
    Gateway --> GateMgr

    SessionMgr --> PolicyEval
    SessionMgr --> GateMgr
    SessionMgr --> Ledger
    SessionMgr -->|on deny| EvolutionMgr
    EvolutionMgr --> SuggestionEngine

    MCPProxy -->|on deny| McpEvoHandler
    McpEvoHandler --> SuggestionEngine
    EvoTool -->|apply change| SessionMgr

    ActionReg --> FileTools
    ActionReg --> DirTools
    ActionReg --> GitTools
    ActionReg --> NetTools

    Rollback --> ActionReg
    Rollback --> Ledger

    MCPProxy --> BackendMCP
    GateMgr --> Approvers

sequenceDiagram
    participant Agent
    participant Integration
    participant Gateway as Agent Gateway
    participant Session as Session Manager
    participant Policy as Policy Evaluator
    participant Gate as Gate Manager
    participant Ledger as Evidence Ledger

    Agent ->> Integration: Action request (tool, input)
    Integration ->> Gateway: evaluate(sessionId, action)
    Gateway ->> Session: evaluate(sessionId, action)

    Session ->> Policy: evaluateSessionAction(action)

    Note right of Policy: 1. Session state check<br/>2. Rate limits & escalation<br/>3. Forbidden patterns<br/>4. Capability & scope match<br/>5. Budget limits<br/>6. Gate lookup

    Policy -->> Session: allow / deny / gate

    Session ->> Ledger: append(action:evaluate)

    alt Gate required
        Session ->> Gate: requestApproval(action, gate)
        alt Approved
            Gate -->> Session: approved
        else Pending
            Gate -->> Session: pending
            Note over Agent, Gate: Session paused until resolved
        end
    end

    Session -->> Gateway: EvaluateResponse
    Gateway -->> Integration: decision + reasons
    Integration -->> Agent: allow / deny / gate

    alt Allowed
        Note over Agent: Executes action externally
        Agent ->> Integration: recordResult(actionId, result)
        Integration ->> Gateway: recordResult(sessionId, actionId, result)
        Gateway ->> Session: recordResult(result)
        Session ->> Session: Update budget tracking
        Session ->> Ledger: append(action:result)
    end

    opt Session complete
        Agent ->> Integration: terminateSession()
        Integration ->> Gateway: terminate(sessionId)
        Gateway ->> Session: terminate(sessionId)
        Session ->> Ledger: append(session:terminate)
        Session -->> Agent: Session Report
    end

stateDiagram-v2
    [*] --> Created: createSession()
    Created --> Evaluating: evaluate(action)
    Evaluating --> Allowed: policy allows
    Evaluating --> Denied: policy denies
    Evaluating --> Gated: gate required
    Gated --> Allowed: approved
    Gated --> Denied: rejected
    Allowed --> Recording: recordResult()
    Recording --> Evaluating: next action
    Denied --> Evaluating: next action
    Recording --> Terminated: terminateSession()
    Evaluating --> Terminated: terminateSession()
    Terminated --> [*]

{"seq":1,"ts":"...","hash":"sha256:abc...","prev":"sha256:000...","type":"session:start","data":{...}}
{"seq":2,"ts":"...","hash":"sha256:def...","prev":"sha256:abc...","type":"action:evaluate","data":{...}}
{"seq":3,"ts":"...","hash":"sha256:ghi...","prev":"sha256:def...","type":"action:result","data":{...}}

import { ToolAdapter } from '@det-acp/core';
import { z } from 'zod';

class MyCustomTool extends ToolAdapter {
  readonly name = 'custom:mytool';
  readonly description = 'My custom tool';
  readonly inputSchema = z.object({
    target: z.string().min(1),
    options: z.record(z.string()).optional(),
  });

  validate(input, policy) { /* ... */ }
  async dryRun(input, ctx) { /* ... */ }
  async execute(input, ctx) { /* ... */ }
  async rollback(input, ctx) { /* ... */ }
}

// Register it
gateway.getRegistry().register(new MyCustomTool());

npm install          # Install dependencies
npm run lint         # Type check (TypeScript strict)
npm test             # Run tests (Vitest)
npm run build        # Build