GitHub - DeadpxlStudio/ModelActionProtocol: MAP (Model Action Protocol) — Cryptographic provenance, self-healing critic, and state rollback for autonomous AI agents. 2.5k lines of TypeScript, 60+ tests, MIT.

npx -p @model-action-protocol/cli map verify ./agent.ledger.json
# or pipe a ledger from your agent:
your-agent | jq '.ledger' | npx -p @model-action-protocol/cli map verify -

# install TS workspaces (core + cli + verifier)
npm install

# build core + cli
npm run build && npm run build:cli

# run the verifier locally on http://localhost:4040
npm run dev:verifier

{
  agentId: string;
  ownerId: string;           // org/user that owns this agent
  ownerDomain: string;       // e.g., "customer.com"
  capabilities: string[];    // what this agent can do
  credentialHash: string;    // SHA-256 of auth credential
}

{
  grantor: AgentIdentity;    // Agent A (requesting)
  grantee: AgentIdentity;    // Agent B (executing)
  scope: string[];           // specific actions authorized
  constraints: {};           // e.g., max amount, time window
  expiresAt?: string;        // when this grant expires
  parentGrantId?: string;    // delegation chain
  hash: string;              // tamper-evident
}

{
  agentId: string;
  parentAgentId?: string;    // who spawned this agent
  spawnedAt: string;
  terminatedAt?: string;     // null if still alive
  purpose: string;           // why this agent exists
  isEphemeral: boolean;      // auto-terminate when done
  childAgentIds: string[];   // sub-agents spawned
}

npm install @model-action-protocol/core

pip install model-action-protocol
# or with extras:
pip install "model-action-protocol[anthropic,sqlite,postgres,fastapi]"

import { MAP } from '@model-action-protocol/core';
import { PostgresLedgerStore } from '@model-action-protocol/core/postgres';

const store = new PostgresLedgerStore({
  connectionString: process.env.DATABASE_URL,
  tableName: 'ledger_entries', // optional, default: 'ledger_entries'
  sessionId: 'default',        // optional, for multi-tenant isolation
});

const map = await MAP.load({ ...config, store }, critic);

npm install better-sqlite3

import { MAP } from '@model-action-protocol/core';
import { SQLiteLedgerStore } from '@model-action-protocol/core/sqlite';

const store = new SQLiteLedgerStore('./ledger.db');

const map = await MAP.load({ ...config, store }, critic);

import { MAP, createRuleCritic } from '@model-action-protocol/core';
import { z } from 'zod';

// Your state
const database: Record<string, any> = {
  acme:   { id: "acme", name: "Acme Corp", price: 500 },
  globex: { id: "globex", name: "Globex Inc", price: 500 },
};

// 1. Create a critic
const critic = createRuleCritic([
  {
    name: 'no-zero-prices',
    check: ({ stateAfter }) => {
      const state = stateAfter as Record<string, any>;
      const bad = Object.values(state).find((c) => c.price === 0);
      if (bad) {
        return {
          verdict: 'CORRECTED',
          reason: `${bad.name} price was set to $0`,
          correction: { tool: 'updatePrice', input: { customerId: bad.id, price: 299 } },
        };
      }
      return null;
    },
  },
]);

// 2. Initialize MAP
const map = new MAP(
  { executor: 'claude-sonnet-4.6', critic: 'claude-haiku-4.5' },
  critic
);

// 3. Register tools
map.registerTool(
  'updatePrice', 'Update a customer price',
  z.object({ customerId: z.string(), price: z.number() }),
  async ({ customerId, price }) => {
    database[customerId].price = price;
    return { updated: customerId, newPrice: price };
  }
);

// 4. Connect state
map.connectState(
  () => JSON.parse(JSON.stringify(database)),
  (state) => Object.assign(database, state),
);

// 5. Execute with full provenance
await map.execute('Migrate pricing', 'updatePrice', { customerId: 'acme', price: 299 });

// 6. Rollback if needed
const ledger = map.getLedger();
await map.rollbackTo(ledger[0].id);

// 7. Export for audit
const audit = map.exportLedger();
// → { protocol: 'map', version: '0.1.0', entries: [...], stats: {...} }

// 8. Verify chain integrity
map.verifyIntegrity(); // → { valid: true }

from map import Action, CriticResult, Map, rule_critic, verify_chain

# Your state — a tiny "orders database" stand-in for a real backend.
ORDERS: dict[str, dict] = {}

def place_order(item_id: str, quantity: int) -> dict:
    order_id = f"O-{item_id}-{quantity}-{len(ORDERS)}"
    record = {"orderId": order_id, "item_id": item_id, "quantity": quantity, "status": "open"}
    ORDERS[order_id] = record
    return record

def cancel_order(action: Action, output) -> dict:
    ORDERS[output["orderId"]]["status"] = "cancelled"
    return {"orderId": output["orderId"], "cancelled": True}

# 1. Critic — flag any order over 100 units
def disallow_huge(action, sb, sa):
    if action.input.get("quantity", 0) > 100:
        return CriticResult(verdict="FLAGGED", reason="quantity over 100 needs approval")
    return None

# 2. Wire up MAP with critic + reverser
m = Map()
m.set_critic(rule_critic([disallow_huge]))
decorated = m.reversible(reverser=cancel_order)(place_order)

# 3. Execute — every call is a verifiable ledger entry
output = decorated(item_id="SKU-A", quantity=2)
entry = m.execute(Action(tool="place_order", input={"item_id": "SKU-A", "quantity": 2}, output=output))
# → entry.critic.verdict == "PASS"

# 4. Roll back — reverser fires, world state flips
m.rollback_to(entry.id)
assert ORDERS["O-SKU-A-2-0"]["status"] == "cancelled"

# 5. Audit export + chain verification
chain = [e.model_dump(by_alias=True, exclude_none=True) for e in m.get_entries()]
assert verify_chain(chain) == {"valid": True}

// TypeScript — Open Source/src/snapshot.ts
import { computeEntryHash, sha256, serializeState } from "@model-action-protocol/core";

const stateHash = sha256(serializeState(null));
const entryHash = computeEntryHash(
  0,
  { tool: "ping", input: {}, output: "pong" },
  stateHash, stateHash,
  "0".repeat(64),
  { verdict: "PASS", reason: "ok" }
);
// → "25d29bc25a183ebdb29b70b6a03ed2ad8d31033d1fb6347f656b21d7e9efb650"

# Python — same inputs, same output, byte-identical
from map import GENESIS_HASH, compute_entry_hash, state_hash

null_hash = state_hash(None)
entry_hash = compute_entry_hash(
    sequence=0,
    action={"tool": "ping", "input": {}, "output": "pong"},
    state_before=null_hash, state_after=null_hash,
    parent_hash=GENESIS_HASH,
    critic={"verdict": "PASS", "reason": "ok"},
)
# → "25d29bc25a183ebdb29b70b6a03ed2ad8d31033d1fb6347f656b21d7e9efb650"

// Example pattern — see examples/tools-stripe in this repo for the full implementation
import { stripeTools } from './tools-stripe';
stripeTools.forEach(tool => map.addTool(tool));

import { defineRestoreTool, defineCompensateTool, defineEscalateTool } from '@model-action-protocol/core';

// RESTORE: auto-capture state before write, restore on rollback
const updateCustomer = defineRestoreTool({
  name: 'updateCustomer', description: 'Update customer record',
  inputSchema: z.object({ id: z.string(), email: z.string() }),
  execute: async (input) => api.updateCustomer(input),
  capture: async (input) => api.getCustomer(input.id),
  restore: async (captured) => api.updateCustomer(captured),
});

// COMPENSATE: map forward action to compensating action
const chargeCard = defineCompensateTool({
  name: 'chargeCard', description: 'Charge a credit card',
  inputSchema: z.object({ amount: z.number() }),
  execute: async (input) => stripe.charges.create(input),
  compensate: async (input, output) => stripe.refunds.create({ charge: output.id }),
});

// ESCALATE: require human approval for irreversible actions
const wireTransfer = defineEscalateTool({
  name: 'wireTransfer', description: 'Send a wire transfer',
  inputSchema: z.object({ amount: z.number(), to: z.string() }),
  execute: async (input) => bank.sendWire(input),
  approver: 'treasury@company.com',
});

import { MAP, createLLMCritic } from '@model-action-protocol/core';
import { generateText } from 'ai';

const critic = createLLMCritic({
  model: 'claude-haiku-4.5',
  generateText,
});

const map = new MAP(
  { executor: 'claude-sonnet-4.6', critic: 'claude-haiku-4.5' },
  critic
);

import { LearningEngine } from '@model-action-protocol/core';

const engine = new LearningEngine();

// Analyze the ledger for repeated correction patterns
const patterns = engine.analyzePatterns(map.getLedger());
// → [{ tool: "reclassifyTransaction", count: 5, summary: "CORRECTED: SOX violation..." }]

// Propose rules from patterns observed 3+ times
const proposals = engine.proposeRules(map.getLedger(), 3);
// → [{ id: "rule_corrected:reclassify...", description: "Auto-proposed: ...", approved: false }]

// Human reviews and approves the rule
proposals.forEach(r => engine.addProposedRule(r));
engine.approveRule(proposals[0].id);

// Use learned rules as the fast tier in the tiered critic
const learnedCritic = engine.toRuleCritic();

// Plug into tiered critic — learned rules run first (microseconds),
// LLM only fires for patterns the rules haven't seen yet
import { createTieredCritic } from '@model-action-protocol/core';

const tieredCritic = createTieredCritic({
  low: learnedCritic,                                                  // μs — learned rules
  medium: createLLMCritic({ model: 'claude-haiku-4.5', generateText }), // 200ms
  high: createLLMCritic({ model: 'claude-sonnet-4.6', generateText }),  // 1-2s
});

const trainingData = engine.exportFineTuningData(map.getLedger());
// → [{
//   input: { action, stateBefore, stateAfter },
//   output: { verdict: "CORRECTED", reason: "SOX violation...", correction: {...} },
//   humanApproval: "approved"
// }]

const memory = engine.exportAgentMemory(map.getLedger(), 'agent-compliance-checker');
// → [{
//   tool: "closeAccount",
//   whatHappened: "Called closeAccount with { accountId: '1200-004' }",
//   verdict: "FLAGGED",
//   lesson: "This action was FLAGGED and required human review: regulatory hold violation.
//            Do not attempt this without explicit approval."
// }]

// Inject into agent's system prompt as learned context
const agentPrompt = `
  You are a compliance agent. Here are lessons from your past actions:
  ${memory.map(m => `- ${m.lesson}`).join('\n')}
`;

map.on((event) => {
  switch (event.type) {
    case 'action:start':       // Before tool execution
    case 'action:complete':    // After execution + logging
    case 'critic:verdict':     // After critic review
    case 'correction:applied': // After auto-correction
    case 'flagged':            // Dangerous action detected
    case 'rollback:start':     // Before rollback
    case 'rollback:complete':  // After rollback
    case 'session:complete':   // Sequence finished
    case 'agent:spawned':      // New agent in the fleet
    case 'agent:terminated':   // Agent finished its work
    case 'authorization:granted': // KYA grant issued
    case 'authorization:revoked': // KYA grant revoked
    case 'error':              // Unrecoverable error
  }
});

{
  id: string;                    // UUID
  sequence: number;               // Position in chain
  timestamp: string;              // ISO 8601
  action: {
    tool: string;
    input: Record<string, unknown>;
    output: unknown;
    reversalStrategy?: "COMPENSATE" | "RESTORE" | "ESCALATE";
  };
  stateBefore: string;            // SHA-256 hash
  stateAfter: string;             // SHA-256 hash
  snapshots: { before, after };   // Full serialized state
  parentHash: string;             // Previous entry's hash
  hash: string;                   // SHA-256 of this entry
  critic: {
    verdict: "PASS" | "CORRECTED" | "FLAGGED";
    reason: string;
    correction?: { tool, input };
    cost?: { inputTokens, outputTokens, model, latencyMs, costUsd };
  };
  status: "ACTIVE" | "ROLLED_BACK";
  approval?: "pending" | "approved" | "rejected";
  // Multi-agent provenance
  agentId?: string;               // Which agent acted
  parentEntryId?: string;         // Upstream agent's entry
  lineage?: string[];             // Root → current agent chain
  stateVersion?: number;          // Optimistic concurrency
}

Human Supervisor (one person, many agents)
    │
    ▼
┌──────────────────────────────────────────────────┐
│               @model-action-protocol/core                 │
│                                                  │
│  ┌──────────┐  ┌────────┐  ┌────────────────┐   │
│  │ Executor │→ │ Critic │→ │    Ledger      │   │
│  │ Harness  │  │ (fast) │  │ (SHA-256 chain)│   │
│  └──────────┘  └────────┘  └────────────────┘   │
│       │                          │               │
│  ┌──────────┐  ┌────────────────┐│               │
│  │ Rollback │  │ KYA (Know Your ││               │
│  │ Engine   │  │    Agent)      ││               │
│  └──────────┘  └────────────────┘│               │
│                                  │               │
│  ┌──────────────────────────────┐│               │
│  │  Agent Lifecycle Tracking    ││               │
│  │  (spawn trees, ephemeral)    ││               │
│  └──────────────────────────────┘│               │
└──────────────────────────────────────────────────┘
    │              │              │
    ▼              ▼              ▼
  Agent A      Agent B       Agent C
 (Stripe)    (Salesforce)   (NetSuite)

# TypeScript (146 tests)
npm test
npm run test:fixtures                    # spec/fixtures/v0.1/ conformance
npm run test:python-output-conformance   # TS verifies Python-written ledgers

# Python (108 tests + 3 skipped on missing env vars)
cd python
pip install -e ".[dev]"
pytest                                   # everything except gated suites
pytest -m postgres                       # requires DB_HOST
pytest -m live_api                       # requires ANTHROPIC_API_KEY