sequenceDiagram
    autonumber
    actor Agent as Claude Opus 5.5 / GPT-6 Astra
    participant Undo as Agent-Undo Saga Engine
    participant AWS as AWS Cloud MCP
    participant Stripe as Stripe Billing MCP
    participant K8s as Kubernetes MCP
    participant DNS as Route53 DNS MCP

    Note over Agent,Undo: Saga Session Active (saga_prod_01)
    Agent->>Undo: call_tool("provision_aws_vpc", {cidr: "10.0.0.0/16"})
    Undo->>AWS: Execute Create VPC
    AWS-->>Undo: VPC Created (vpc-prod-99)
    Undo->>Undo: Journal Action + Register Compensate: deprovision_aws_vpc
    Undo-->>Agent: Step 1 Success

    Agent->>Undo: call_tool("create_stripe_customer", {email: "c@acme.com"})
    Undo->>Stripe: Execute Create Customer
    Stripe-->>Undo: Customer Created (cus_123)
    Undo->>Undo: Journal Action + Register Compensate: delete_stripe_customer
    Undo-->>Agent: Step 2 Success

    Agent->>Undo: call_tool("register_dns_record", {domain: "api.acme.com"})
    Undo->>DNS: Execute Route53 Update
    DNS-->>Undo: 🚨 AccessDenied: IAM Policy Violation!

    Note over Undo: Failure Detected! Initiating Reverse Compensating Saga
    Undo->>Stripe: Undo Step 2: delete_stripe_customer(cus_123)
    Stripe-->>Undo: Deleted ✓
    Undo->>AWS: Undo Step 1: deprovision_aws_vpc(vpc-prod-99)
    AWS-->>Undo: Deprovisioned ✓
    Undo-->>Agent: Error Handled: State 100% Restored to Clean

flowchart TD
    subgraph AgentRuntime["Agent Orchestration Tier"]
        LLM["Claude Opus 5.5 / GPT-6 Astra"]
        Planner["Autonomous Workflow Loop"]
        LLM --> Planner
    end

    subgraph SagaEngine["Agent-Undo Coordinator"]
        WAL["Write-Ahead Action Journal (WAL)"]
        Registry["Compensating Tool Pair Registry"]
        Unwind["Reverse LIFO Execution Engine"]
        
        Planner -->|Mutating Tool Call| WAL
        Registry --> WAL
        WAL -->|On Failure| Unwind
    end

    subgraph ExternalAPIs["Target SaaS & Infrastructure"]
        S3["AWS S3 / RDS"]
        Payments["Stripe Payments"]
        CloudK8s["Kubernetes Cluster"]
        
        WAL -->|Forward Call| S3
        WAL -->|Forward Call| Payments
        WAL -->|Forward Call| CloudK8s

        Unwind -->|Compensate Undo| CloudK8s
        Unwind -->|Compensate Undo| Payments
        Unwind -->|Compensate Undo| S3
    end

stateDiagram-v2
    [*] --> ACTIVE: start_session()
    ACTIVE --> ACTIVE: execute_action() & Push WAL
    ACTIVE --> COMMITTED: All Steps Verified (commit_saga)
    
    ACTIVE --> COMPENSATING: Exception / Abort Signal
    COMPENSATING --> ROLLED_BACK: All Undo Handlers Passed (<1ms)
    COMPENSATING --> FAILED: Manual Intervention Required

    COMMITTED --> [*]
    ROLLED_BACK --> [*]

git clone https://github.com/AAH20/agent-undo.git
cd agent-undo
pip install -e .

agent-undo demo

============================================================================
  ⏪ AGENT-UNDO: UNIVERSAL TRANSACTIONAL ROLLBACK & COMPENSATING SAGAS
  Model Context Protocol (MCP) Coordinator for Claude Opus 5.5 & GPT-6 Astra
============================================================================
Saga initialized: saga_5011c20e (Agent: agent_opus_infra_01 | Model: claude-opus-5-5)

----------------------------------------------------------------------------
PHASE 1: Agent executing multi-step mutating tool chain
----------------------------------------------------------------------------
▶ [Step 1/5] Invoking: provision_aws_vpc(vpc_id='vpc-prod-us-east-1')
▶ [Step 2/5] Invoking: provision_rds_postgres(db_name='pg-payments-prod')
▶ [Step 3/5] Invoking: create_stripe_customer(email='billing@acme-corp.com')
▶ [Step 4/5] Invoking: deploy_k8s_service(service_name='payment-orchestrator')
▶ [Step 5/5] Invoking: register_dns_record(domain='api.payments.acme.com')

🚨 AGENT EXECUTION CRASHED AT STEP 5: AccessDeniedException: AWS Route53 write policy violation on hosted zone Z10293
Triggering Automatic Reverse Compensating Saga Rollback...

----------------------------------------------------------------------------
PHASE 2: Agent-Undo executing reverse compensating saga (LIFO order)
----------------------------------------------------------------------------
  ✓ Step 4 [deploy_k8s_service] undone by [delete_k8s_service] in 0.01ms
  ✓ Step 3 [create_stripe_customer] undone by [delete_stripe_customer] in 0.00ms
  ✓ Step 2 [provision_rds_postgres] undone by [deprovision_rds_postgres] in 0.00ms
  ✓ Step 1 [provision_aws_vpc] undone by [deprovision_aws_vpc] in 0.00ms

• Total Actions Recorded: 4
• Compensations Executed: 4
• Rollback Duration     : 0.06 ms
• Final Saga Status     : ROLLED_BACK
• Orphaned Cloud Resources Remaining: 0 (100% Clean)

============================================================================
  CTRL+Z FOR THE REAL WORLD: STATE FULLY RESTORED IN <1MS.
============================================================================

from agent_undo import SagaEngine

engine = SagaEngine()

# 1. Bind forward tool with its reverse compensating undo tool
engine.register_compensating_pair(
    execute_tool="create_s3_bucket",
    compensate_tool="delete_s3_bucket",
    execute_handler=lambda args: aws_client.create_bucket(Bucket=args["name"]),
    compensate_handler=lambda args: aws_client.delete_bucket(Bucket=args["name"])
)

# 2. Wrap agent execution session
session = engine.start_session("agent_opus_01")
try:
    engine.execute_action(session.saga_id, "create_s3_bucket", {"name": "prod-logs"})
    # ... more actions ...
    engine.commit_saga(session.saga_id)
except Exception:
    # 3. Unwind all previous actions cleanly
    report = engine.rollback_saga(session.saga_id)
    print(f"Rollback complete: {report.actions_compensated} actions undone in {report.duration_ms:.2f}ms")

python3 -m unittest discover -s tests -p "test_*.py" -v

test_mcp_wrapper_tool_export ... ok
test_saga_commit_lifecycle ... ok
test_saga_rollback_lifo_execution ... ok

Ran 3 tests in 0.000s
OK