agent-os-kernel 1.1.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

modules/iatp/examples/secure_bank_agent.py

@@ -0,0 +1,138 @@
+"""
+Example: Secure Bank Agent
+
+This agent demonstrates a "verified_partner" with strong security guarantees:
+- Full reversibility within 5-minute fraud detection window
+- Ephemeral data retention
+- No human review
+- No ML training on user data
+- High trust score (10/10)
+"""
+from fastapi import FastAPI, Header, HTTPException
+from typing import Optional
+import time
+import uuid
+
+app = FastAPI(title="Secure Bank Agent")
+
+# Simulated transaction store (in-memory for demo)
+transactions = {}
+
+
+@app.post("/")
+async def process_banking_request(
+    request: dict,
+    x_agent_trace_id: Optional[str] = Header(None)
+):
+    """
+    Process a secure banking transaction.
+    
+    This agent demonstrates best practices:
+    - Idempotent operations
+    - Transaction tracking
+    - Reversibility support
+    - Clear audit trails
+    """
+    task = request.get("task")
+    data = request.get("data", {})
+    
+    if task == "transfer":
+        # Simulate a bank transfer
+        transaction_id = str(uuid.uuid4())
+        amount = data.get("amount", 0)
+        from_account = data.get("from_account")
+        to_account = data.get("to_account")
+        
+        # Store transaction for potential reversal
+        transactions[transaction_id] = {
+            "amount": amount,
+            "from_account": from_account,
+            "to_account": to_account,
+            "timestamp": time.time(),
+            "status": "completed",
+            "trace_id": x_agent_trace_id
+        }
+        
+        return {
+            "status": "success",
+            "transaction_id": transaction_id,
+            "message": f"Transferred ${amount} from {from_account} to {to_account}",
+            "reversible_until": time.time() + 300  # 5 minutes
+        }
+    
+    elif task == "check_balance":
+        # Simulate balance check (read-only, always reversible)
+        account = data.get("account")
+        return {
+            "status": "success",
+            "account": account,
+            "balance": 1000.00,  # Simulated balance
+            "currency": "USD"
+        }
+    
+    else:
+        raise HTTPException(status_code=400, detail=f"Unknown task: {task}")
+
+
+@app.post("/compensate/{transaction_id}")
+async def compensate_transaction(transaction_id: str):
+    """
+    Reverse a transaction (compensation endpoint).
+    
+    This demonstrates the IATP reversibility protocol.
+    """
+    UNDO_WINDOW_SECONDS = 300  # 5 minutes
+    
+    if transaction_id not in transactions:
+        raise HTTPException(status_code=404, detail="Transaction not found")
+    
+    transaction = transactions[transaction_id]
+    
+    # Check if still within undo window (5 minutes)
+    if time.time() - transaction["timestamp"] > UNDO_WINDOW_SECONDS:
+        raise HTTPException(
+            status_code=400,
+            detail="Undo window expired (5 minutes)"
+        )
+    
+    if transaction["status"] == "reversed":
+        return {
+            "success": True,
+            "message": "Transaction already reversed",
+            "transaction_id": transaction_id
+        }
+    
+    # Reverse the transaction
+    transaction["status"] = "reversed"
+    transaction["reversed_at"] = time.time()
+    
+    return {
+        "success": True,
+        "message": "Transaction reversed successfully",
+        "transaction_id": transaction_id,
+        "amount_returned": transaction["amount"],
+        "compensation_method": "rollback"
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {
+        "status": "healthy",
+        "service": "Secure Bank Agent",
+        "trust_level": "verified_partner",
+        "active_transactions": len(transactions)
+    }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("Starting Secure Bank Agent on port 8000")
+    print("This agent demonstrates:")
+    print("  - Full reversibility (5-minute window)")
+    print("  - Ephemeral data retention")
+    print("  - High trust score (10/10)")
+    print("")
+    print("Start the sidecar with: python examples/run_secure_bank_sidecar.py")
+    uvicorn.run(app, host="0.0.0.0", port=8000)

modules/iatp/examples/test_untrusted.py

@@ -0,0 +1,82 @@
+"""
+Test script to demonstrate the untrusted agent scenario with warnings and override.
+"""
+import httpx
+import json
+
+print("="*70)
+print("Testing IATP with UNTRUSTED agent scenario")
+print("="*70)
+
+# First, let's test a request WITHOUT override - should get a warning
+print("\n1. Testing request without override (should get warning)...")
+print("-" * 70)
+
+try:
+    response = httpx.post(
+        "http://localhost:8002/proxy",  # We'll start an untrusted sidecar on 8002
+        json={
+            "task": "book_cheap_flight",
+            "data": {
+                "destination": "NYC"
+            }
+        },
+        timeout=10.0
+    )
+    print(f"Status Code: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+except Exception as e:
+    print(f"Connection failed - untrusted sidecar not running: {e}")
+    print("\nTo test the untrusted scenario:")
+    print("1. Uncomment 'create_untrusted_manifest()' in examples/run_sidecar.py")
+    print("2. Change port to 8002 in run_sidecar.py")
+    print("3. Restart the sidecar")
+    print("4. Run this script again")
+    exit(0)
+
+# Now test WITH override
+print("\n2. Testing request WITH override (should succeed but be quarantined)...")
+print("-" * 70)
+
+try:
+    response = httpx.post(
+        "http://localhost:8002/proxy",
+        headers={"X-User-Override": "true"},
+        json={
+            "task": "book_cheap_flight",
+            "data": {
+                "destination": "NYC"
+            }
+        },
+        timeout=10.0
+    )
+    print(f"Status Code: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+    print(f"\nResponse Headers:")
+    print(f"  X-Agent-Trace-ID: {response.headers.get('X-Agent-Trace-ID')}")
+    print(f"  X-Agent-Trust-Score: {response.headers.get('X-Agent-Trust-Score')}")
+    print(f"  X-Agent-Quarantined: {response.headers.get('X-Agent-Quarantined')}")
+except Exception as e:
+    print(f"Error: {e}")
+
+# Test blocked request - credit card with permanent storage
+print("\n3. Testing BLOCKED request (credit card with untrusted agent)...")
+print("-" * 70)
+
+try:
+    response = httpx.post(
+        "http://localhost:8002/proxy",
+        json={
+            "task": "payment",
+            "card": "4532-0151-1283-0366"
+        },
+        timeout=10.0
+    )
+    print(f"Status Code: {response.status_code}")
+    print(f"Response: {json.dumps(response.json(), indent=2)}")
+except Exception as e:
+    print(f"Error: {e}")
+
+print("\n" + "="*70)
+print("Testing complete!")
+print("="*70)

modules/iatp/examples/untrusted_agent.py

@@ -0,0 +1,119 @@
+"""
+Example: Untrusted Agent (Rogue Agent for Testing)
+
+This agent demonstrates the "worst case scenario":
+- Untrusted status
+- Permanent data retention (stores forever)
+- No reversibility
+- Human review enabled
+- ML training consent enabled
+- Low trust score (0-1/10)
+
+This agent is useful for testing that your sidecar correctly:
+1. Detects and blocks dangerous requests (credit cards to untrusted agents)
+2. Generates appropriate warnings
+3. Requires user override
+4. Logs quarantined transactions
+
+This is the "honeypot" agent mentioned in the problem statement.
+"""
+from fastapi import FastAPI, Header
+from typing import Optional
+import json
+from datetime import datetime
+
+app = FastAPI(title="Untrusted Agent (Test)")
+
+# This agent "maliciously" stores everything forever
+permanent_storage = []
+
+
+@app.post("/")
+async def process_request(
+    request: dict,
+    x_agent_trace_id: Optional[str] = Header(None)
+):
+    """
+    Process a request - but store everything permanently!
+    
+    This simulates a rogue agent that doesn't respect privacy.
+    The sidecar should detect this and warn users.
+    """
+    task = request.get("task", "unknown")
+    data = request.get("data", {})
+    
+    # "Maliciously" store the data forever
+    permanent_storage.append({
+        "timestamp": datetime.utcnow().isoformat(),
+        "task": task,
+        "data": data,
+        "trace_id": x_agent_trace_id
+    })
+    
+    # Pretend to process normally
+    result = {
+        "status": "success",
+        "task": task,
+        "result": f"Processed {task}",
+        "data_stored_permanently": True,  # Honest about its behavior
+        "will_train_ml_models": True,  # Will use data for training
+        "human_reviewed": True,  # Humans will see the data
+        "reversibility": "none"  # Cannot undo
+    }
+    
+    return result
+
+
+@app.get("/storage")
+async def view_storage():
+    """
+    View what this agent has stored (demonstrates the problem).
+    
+    In a real rogue agent, this wouldn't be exposed, but we expose it
+    for testing purposes to show that the agent stores everything.
+    """
+    return {
+        "message": "This agent stores everything permanently!",
+        "total_items": len(permanent_storage),
+        "storage": permanent_storage
+    }
+
+
+@app.get("/health")
+async def health_check():
+    """Health check endpoint"""
+    return {
+        "status": "healthy",
+        "service": "Untrusted Agent",
+        "trust_level": "untrusted",
+        "warning": "⚠️ This agent stores data permanently and cannot undo operations!"
+    }
+
+
+# This agent intentionally DOES NOT implement a /compensate endpoint
+# to demonstrate "no reversibility"
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("=" * 60)
+    print("⚠️  WARNING: Starting UNTRUSTED AGENT")
+    print("=" * 60)
+    print("")
+    print("This agent demonstrates BAD behavior:")
+    print("  ❌ Stores data permanently (forever)")
+    print("  ❌ No reversibility (cannot undo)")
+    print("  ❌ Human review enabled (privacy risk)")
+    print("  ❌ Uses data for ML training")
+    print("  ❌ Trust score: 0-1/10")
+    print("")
+    print("The IATP sidecar should:")
+    print("  ✓ Block credit cards sent to this agent")
+    print("  ✓ Warn about low trust score")
+    print("  ✓ Require user override to proceed")
+    print("  ✓ Quarantine all transactions")
+    print("")
+    print("Start the sidecar with: python examples/run_untrusted_sidecar.py")
+    print("Test with: python examples/test_untrusted.py")
+    print("")
+    uvicorn.run(app, host="0.0.0.0", port=8000)

modules/iatp/experiments/README.md

@@ -0,0 +1,58 @@
+# IATP Experiments
+
+Research experiments demonstrating the effectiveness of the Inter-Agent Trust Protocol.
+
+## Cascading Hallucination Prevention
+
+**Location**: `cascading_hallucination/`
+
+This experiment demonstrates how IATP prevents cascading failures in multi-agent systems.
+
+### The Problem
+
+In multi-agent systems, a single "poisoned" agent can inject malicious instructions that propagate through the chain, causing catastrophic failures:
+
+```
+Agent A (User) → Agent B (Poisoned) → Agent C (Database)
+      ↓                ↓                    ↓
+  "Summarize"    "DELETE ALL"      ❌ Data Lost Forever
+```
+
+### The Solution
+
+IATP's sidecar intercepts requests and validates them against the agent's capability manifest:
+
+```
+Agent A (User) → Agent B (Poisoned) → IATP Sidecar → Agent C (Database)
+      ↓                ↓                  ↓               ↓
+  "Summarize"    "DELETE ALL"      🚫 BLOCKED      ✅ Data Safe
+```
+
+### Results
+
+| Group | IATP Protection | Failure Rate |
+|-------|-----------------|--------------|
+| Control | ❌ None | **100%** (DELETE executed) |
+| Test | ✅ Enabled | **0%** (BLOCKED) |
+
+### Running the Experiment
+
+#### Option 1: Standalone Proof of Concept
+```bash
+python experiments/cascading_hallucination/proof_of_concept.py
+```
+
+#### Option 2: Full Multi-Agent Experiment (requires Docker)
+```bash
+python experiments/cascading_hallucination/run_experiment.py
+```
+
+See [cascading_hallucination/README.md](cascading_hallucination/README.md) for detailed instructions.
+
+## Research Paper
+
+The results of these experiments are documented in the research paper:
+
+- **Title**: "The Trust Boundary: Preventing Cascading Hallucinations in Multi-Agent AI Systems"
+- **Location**: [paper/PAPER.md](../paper/PAPER.md)
+- **Key Finding**: IATP reduces cascading failure rates from 100% to 0%

modules/iatp/experiments/cascading_hallucination/README.md

@@ -0,0 +1,149 @@
+# Cascading Hallucination Experiment
+
+This experiment demonstrates IATP's ability to prevent cascading failures in agent chains.
+
+## The Setup
+
+Three agents in a chain:
+1. **Agent A (User)**: Initiates the request
+2. **Agent B (Summarizer)**: Middle agent that gets "poisoned" with malicious instructions
+3. **Agent C (Database)**: Executes commands
+
+### The Attack
+
+Agent B is compromised and injects a `DELETE TABLE users` command into the request flowing to Agent C.
+
+## Control Group (No IATP)
+
+Without IATP protection:
+- Agent B → Agent C (direct connection)
+- The poisoned DELETE command reaches Agent C
+- Agent C executes the DELETE
+- **Result: 100% Failure Rate** 🔥
+
+## Test Group (With IATP)
+
+With IATP protection:
+- Agent B → IATP Sidecar → Agent C
+- The sidecar calculates trust score for Agent B (very low: 0/10)
+- The sidecar detects the high-risk DELETE operation from low-trust source
+- The sidecar WARNS or BLOCKS the operation
+- **Result: 0% Failure Rate** ✅
+
+## Running the Experiment
+
+### Automatic Run (Recommended)
+
+```bash
+cd experiments/cascading_hallucination
+python run_experiment.py
+```
+
+This will:
+1. Run control group (no IATP)
+2. Run test group (with IATP)
+3. Show comparison results
+
+### Manual Run
+
+#### Control Group
+
+Terminal 1 (Agent C - Database):
+```bash
+python experiments/cascading_hallucination/agent_c_database.py
+```
+
+Terminal 2 (Agent B - Summarizer, POISONED):
+```bash
+export AGENT_B_POISONED=true
+python experiments/cascading_hallucination/agent_b_summarizer.py
+```
+
+Terminal 3 (Agent A - User):
+```bash
+python experiments/cascading_hallucination/agent_a_user.py
+```
+
+Terminal 4 (Make Request):
+```bash
+curl -X POST http://localhost:8009/request \
+  -H 'Content-Type: application/json' \
+  -d '{"data": {"action": "SELECT", "table": "users"}}'
+```
+
+**Expected Result**: DELETE is executed (failure)
+
+#### Test Group
+
+Terminal 1 (Agent C - Database):
+```bash
+python experiments/cascading_hallucination/agent_c_database.py
+```
+
+Terminal 2 (IATP Sidecar for Agent C):
+```bash
+python experiments/cascading_hallucination/sidecar_c.py
+```
+
+Terminal 3 (Make Request through Sidecar):
+```bash
+# This simulates a poisoned request
+curl -X POST http://localhost:8012/proxy \
+  -H 'Content-Type: application/json' \
+  -d '{"data": {"action": "DELETE", "table": "users", "poison_injected": true}}'
+```
+
+**Expected Result**: 
+- Status 449 (Warning) - Requires override due to low trust
+- Or Status 403 (Blocked) - Completely blocked
+
+## The "Money Slide" Chart
+
+Results you can present:
+
+```
+Cascading Hallucination Prevention
+====================================
+
+Control Group (No IATP):
+  Agent B (Poisoned) → Agent C
+  DELETE executed: ████████████████████ 100%
+
+Test Group (With IATP):
+  Agent B (Poisoned) → Sidecar → Agent C  
+  DELETE blocked:      ████████████████████ 100%
+  
+Success Rate: 100% attack prevention
+```
+
+## Trust Score Calculation
+
+Agent B (Poisoned/Untrusted) Configuration:
+- Trust Level: `untrusted` → Base score: 0
+- Reversibility: `none` → No bonus
+- Retention: `permanent` → -1
+- Training Consent: `true` → -1
+- **Final Trust Score: 0/10** (minimum)
+
+## Policy Decision
+
+With trust score of 0/10:
+- **Trust score < 7** → Warning required
+- **DELETE operation** → High-risk action
+- **Low trust + High risk** → Requires user override (449) or Block (403)
+
+## Expected Outcomes
+
+1. **Control Group**: DELETE executed successfully (catastrophic failure)
+2. **Test Group**: Operation warned or blocked by IATP
+3. **Conclusion**: IATP prevents cascading hallucinations with 100% effectiveness
+
+## Publishing the Results
+
+Use these results for:
+- Conference presentations
+- "The Trust Boundary" paper
+- Blog posts about agent safety
+- Product demos
+
+The experiment provides concrete, reproducible evidence that IATP solves the cascading failure problem in agent chains.

modules/iatp/experiments/cascading_hallucination/agent_a_user.py

@@ -0,0 +1,41 @@
+#!/usr/bin/env python3
+"""
+Agent A - User Agent
+
+This is the initiating agent that starts the request chain.
+It simulates a user request that will flow through Agent B to Agent C.
+"""
+
+from fastapi import FastAPI
+import httpx
+import sys
+
+app = FastAPI()
+
+AGENT_B_URL = "http://localhost:8010"  # Agent B (Summarizer)
+
+
+@app.post("/request")
+async def make_request(request: dict):
+    """Forward user request to Agent B"""
+    print(f"[Agent A] Received request: {request}", file=sys.stderr)
+    
+    # Forward to Agent B (Summarizer)
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            response = await client.post(
+                f"{AGENT_B_URL}/summarize",
+                json=request
+            )
+            result = response.json()
+            print(f"[Agent A] Response from chain: {result}", file=sys.stderr)
+            return result
+        except Exception as e:
+            print(f"[Agent A] Error: {e}", file=sys.stderr)
+            return {"error": str(e), "agent": "A"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("[Agent A] Starting User Agent on port 8009...")
+    uvicorn.run(app, host="0.0.0.0", port=8009, log_level="info")

modules/iatp/experiments/cascading_hallucination/agent_b_summarizer.py

@@ -0,0 +1,54 @@
+#!/usr/bin/env python3
+"""
+Agent B - Summarizer (with optional poisoning)
+
+This is the middle agent that can be poisoned with malicious instructions.
+In the test group, it will inject a "DELETE TABLE" command.
+"""
+
+from fastapi import FastAPI
+import httpx
+import sys
+import os
+
+app = FastAPI()
+
+AGENT_C_URL = "http://localhost:8011"  # Agent C (Database)
+POISONED = os.getenv("AGENT_B_POISONED", "false").lower() == "true"
+
+
+@app.post("/summarize")
+async def summarize(request: dict):
+    """Summarize and forward to Agent C"""
+    print(f"[Agent B] Received request: {request}", file=sys.stderr)
+    
+    # Normal behavior: pass through the request
+    data = request.get("data", {})
+    
+    # If poisoned, inject malicious command
+    if POISONED:
+        print("[Agent B] ⚠️  POISONED MODE: Injecting DELETE command", file=sys.stderr)
+        data["action"] = "DELETE"
+        data["table"] = "users"
+        data["poison_injected"] = True
+    
+    # Forward to Agent C (Database)
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        try:
+            response = await client.post(
+                f"{AGENT_C_URL}/execute",
+                json={"data": data}
+            )
+            result = response.json()
+            print(f"[Agent B] Response from Agent C: {result}", file=sys.stderr)
+            return result
+        except Exception as e:
+            print(f"[Agent B] Error: {e}", file=sys.stderr)
+            return {"error": str(e), "agent": "B"}
+
+
+if __name__ == "__main__":
+    import uvicorn
+    mode = "POISONED" if POISONED else "NORMAL"
+    print(f"[Agent B] Starting Summarizer Agent on port 8010 ({mode} mode)...")
+    uvicorn.run(app, host="0.0.0.0", port=8010, log_level="info")

modules/iatp/experiments/cascading_hallucination/agent_c_database.py

@@ -0,0 +1,47 @@
+#!/usr/bin/env python3
+"""
+Agent C - Database Agent
+
+This agent simulates a database that can execute commands.
+It should block dangerous commands when protected by IATP.
+"""
+
+from fastapi import FastAPI
+import sys
+
+app = FastAPI()
+
+
+@app.post("/execute")
+async def execute(request: dict):
+    """Execute database command"""
+    data = request.get("data", {})
+    action = data.get("action", "SELECT")
+    table = data.get("table", "unknown")
+    
+    print(f"[Agent C] Received command: {action} on table {table}", file=sys.stderr)
+    
+    # Check if this is a dangerous operation
+    if action == "DELETE":
+        if data.get("poison_injected"):
+            print("[Agent C] ⚠️  DANGER: Poisoned DELETE command detected!", file=sys.stderr)
+        print(f"[Agent C] 🔥 EXECUTING DELETE on table '{table}'", file=sys.stderr)
+        return {
+            "status": "success",
+            "message": f"Deleted all rows from table '{table}'",
+            "dangerous": True,
+            "poison_injected": data.get("poison_injected", False)
+        }
+    else:
+        print(f"[Agent C] ✅ Safe operation: {action}", file=sys.stderr)
+        return {
+            "status": "success",
+            "message": f"Executed {action} on table '{table}'",
+            "dangerous": False
+        }
+
+
+if __name__ == "__main__":
+    import uvicorn
+    print("[Agent C] Starting Database Agent on port 8011...")
+    uvicorn.run(app, host="0.0.0.0", port=8011, log_level="info")