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

modules/nexus/escrow.py

@@ -0,0 +1,428 @@
+"""
+Proof of Outcome / Escrow Manager
+
+Implements the "Reward" mechanism where agents bet on task outcomes.
+Credits are escrowed and released based on SCAK validation.
+"""
+
+from datetime import datetime, timedelta
+from typing import Optional, Literal
+import hashlib
+import uuid
+import asyncio
+
+from .schemas.escrow import (
+    EscrowRequest,
+    EscrowReceipt,
+    EscrowStatus,
+    EscrowRelease,
+    EscrowResolution,
+)
+from .schemas.receipt import JobCompletionReceipt, SignedReceipt
+from .reputation import ReputationEngine
+from .exceptions import (
+    EscrowNotFoundError,
+    EscrowExpiredError,
+    EscrowAlreadyResolvedError,
+    InsufficientCreditsError,
+)
+
+
+class EscrowManager:
+    """
+    Manages escrow lifecycle for inter-agent tasks.
+    
+    The "Reward" OS - agents don't just talk, they bet on outcomes.
+    """
+    
+    def __init__(self, reputation_engine: Optional[ReputationEngine] = None):
+        self.reputation_engine = reputation_engine or ReputationEngine()
+        
+        # In-memory storage (would be database in production)
+        self._escrows: dict[str, EscrowReceipt] = {}
+        self._agent_credits: dict[str, int] = {}  # DID -> credits
+        
+        # Configuration
+        self.default_timeout = 3600  # 1 hour
+        self.max_credits_per_escrow = 10000
+    
+    async def create_escrow(
+        self,
+        request: EscrowRequest,
+        requester_signature: str,
+    ) -> EscrowReceipt:
+        """
+        Create an escrow for a task.
+        
+        Locks credits from requester until task completion.
+        """
+        # Check requester has enough credits
+        available = self._agent_credits.get(request.requester_did, 0)
+        if available < request.credits:
+            raise InsufficientCreditsError(
+                request.requester_did,
+                required=request.credits,
+                available=available,
+            )
+        
+        # Generate escrow ID
+        escrow_id = f"escrow_{uuid.uuid4().hex[:16]}"
+        
+        # Create receipt
+        receipt = EscrowReceipt.from_request(
+            escrow_id=escrow_id,
+            request=request,
+            requester_signature=requester_signature,
+        )
+        
+        # Lock credits
+        self._agent_credits[request.requester_did] -= request.credits
+        
+        # Sign from Nexus
+        receipt.nexus_signature = self._sign_escrow(escrow_id, request)
+        
+        # Store
+        self._escrows[escrow_id] = receipt
+        
+        return receipt
+    
+    async def activate_escrow(self, escrow_id: str) -> EscrowReceipt:
+        """Mark escrow as active (task in progress)."""
+        receipt = self._get_escrow(escrow_id)
+        
+        if receipt.status != EscrowStatus.PENDING:
+            raise EscrowAlreadyResolvedError(escrow_id, receipt.status.value)
+        
+        receipt.status = EscrowStatus.ACTIVE
+        receipt.activated_at = datetime.utcnow()
+        
+        return receipt
+    
+    async def complete_task(
+        self,
+        escrow_id: str,
+        output_hash: str,
+        duration_ms: int,
+        provider_signature: str,
+    ) -> EscrowReceipt:
+        """Mark task as complete, awaiting validation."""
+        receipt = self._get_escrow(escrow_id)
+        
+        if receipt.status != EscrowStatus.ACTIVE:
+            raise EscrowAlreadyResolvedError(escrow_id, receipt.status.value)
+        
+        if receipt.is_expired():
+            receipt.status = EscrowStatus.EXPIRED
+            raise EscrowExpiredError(escrow_id, str(receipt.expires_at))
+        
+        receipt.status = EscrowStatus.AWAITING_VALIDATION
+        receipt.completed_at = datetime.utcnow()
+        
+        return receipt
+    
+    async def release_escrow(
+        self,
+        release: EscrowRelease,
+    ) -> EscrowResolution:
+        """
+        Release escrow based on outcome.
+        
+        - success: Credits go to provider, provider reputation +2
+        - failure: Credits return to requester, provider reputation -10
+        - dispute: Escalate to Arbiter
+        """
+        receipt = self._get_escrow(release.escrow_id)
+        
+        if not receipt.is_active():
+            raise EscrowAlreadyResolvedError(release.escrow_id, receipt.status.value)
+        
+        request = receipt.request
+        credits = request.credits
+        
+        # Determine resolution based on outcome
+        if release.outcome == "success":
+            # Validate with SCAK if required
+            if request.require_scak_validation:
+                if not release.scak_validated:
+                    raise ValueError("SCAK validation required but not performed")
+                if not release.scak_passed:
+                    # SCAK failed - treat as failure
+                    return await self._resolve_failure(receipt, release)
+            
+            return await self._resolve_success(receipt, release)
+        
+        elif release.outcome == "failure":
+            return await self._resolve_failure(receipt, release)
+        
+        else:  # dispute
+            return await self._resolve_dispute(receipt, release)
+    
+    async def _resolve_success(
+        self,
+        receipt: EscrowReceipt,
+        release: EscrowRelease,
+    ) -> EscrowResolution:
+        """Resolve escrow as success - credits to provider."""
+        request = receipt.request
+        
+        # Transfer credits to provider
+        self._agent_credits[request.provider_did] = (
+            self._agent_credits.get(request.provider_did, 0) + request.credits
+        )
+        
+        # Update reputation
+        self.reputation_engine.record_task_outcome(request.provider_did, "success")
+        
+        # Update receipt
+        receipt.status = EscrowStatus.RELEASED
+        receipt.resolved_at = datetime.utcnow()
+        
+        return EscrowResolution(
+            escrow_id=receipt.escrow_id,
+            final_status=EscrowStatus.RELEASED,
+            credits_to_provider=request.credits,
+            credits_to_requester=0,
+            provider_reputation_change=2,
+            requester_reputation_change=0,
+            resolution_reason="Task completed successfully",
+            resolved_by="automatic",
+            nexus_signature=self._sign_resolution(receipt.escrow_id, "success"),
+        )
+    
+    async def _resolve_failure(
+        self,
+        receipt: EscrowReceipt,
+        release: EscrowRelease,
+    ) -> EscrowResolution:
+        """Resolve escrow as failure - credits returned to requester."""
+        request = receipt.request
+        
+        # Return credits to requester
+        self._agent_credits[request.requester_did] = (
+            self._agent_credits.get(request.requester_did, 0) + request.credits
+        )
+        
+        # Update reputation
+        self.reputation_engine.record_task_outcome(request.provider_did, "failure")
+        
+        # Update receipt
+        receipt.status = EscrowStatus.REFUNDED
+        receipt.resolved_at = datetime.utcnow()
+        
+        return EscrowResolution(
+            escrow_id=receipt.escrow_id,
+            final_status=EscrowStatus.REFUNDED,
+            credits_to_provider=0,
+            credits_to_requester=request.credits,
+            provider_reputation_change=-10,
+            requester_reputation_change=0,
+            resolution_reason="Task failed",
+            resolved_by="automatic",
+            nexus_signature=self._sign_resolution(receipt.escrow_id, "failure"),
+        )
+    
+    async def _resolve_dispute(
+        self,
+        receipt: EscrowReceipt,
+        release: EscrowRelease,
+    ) -> EscrowResolution:
+        """Mark escrow as disputed - to be resolved by Arbiter."""
+        receipt.status = EscrowStatus.DISPUTED
+        
+        # Credits remain locked until Arbiter decides
+        return EscrowResolution(
+            escrow_id=receipt.escrow_id,
+            final_status=EscrowStatus.DISPUTED,
+            credits_to_provider=0,
+            credits_to_requester=0,
+            provider_reputation_change=0,
+            requester_reputation_change=0,
+            resolution_reason=f"Dispute raised: {release.dispute_reason}",
+            resolved_by="arbiter",
+            nexus_signature=self._sign_resolution(receipt.escrow_id, "dispute"),
+        )
+    
+    async def expire_escrow(self, escrow_id: str) -> EscrowResolution:
+        """Handle escrow expiration - credits returned to requester."""
+        receipt = self._get_escrow(escrow_id)
+        request = receipt.request
+        
+        # Return credits
+        self._agent_credits[request.requester_did] = (
+            self._agent_credits.get(request.requester_did, 0) + request.credits
+        )
+        
+        # Small reputation penalty for provider
+        self.reputation_engine.record_task_outcome(request.provider_did, "failure")
+        
+        receipt.status = EscrowStatus.EXPIRED
+        receipt.resolved_at = datetime.utcnow()
+        
+        return EscrowResolution(
+            escrow_id=escrow_id,
+            final_status=EscrowStatus.EXPIRED,
+            credits_to_provider=0,
+            credits_to_requester=request.credits,
+            provider_reputation_change=-5,
+            requester_reputation_change=0,
+            resolution_reason="Escrow expired without completion",
+            resolved_by="timeout",
+            nexus_signature=self._sign_resolution(escrow_id, "expired"),
+        )
+    
+    def get_escrow(self, escrow_id: str) -> EscrowReceipt:
+        """Get escrow by ID (public method)."""
+        return self._get_escrow(escrow_id)
+    
+    def get_agent_credits(self, agent_did: str) -> int:
+        """Get credit balance for an agent."""
+        return self._agent_credits.get(agent_did, 0)
+    
+    def add_credits(self, agent_did: str, amount: int) -> int:
+        """Add credits to an agent's balance."""
+        self._agent_credits[agent_did] = self._agent_credits.get(agent_did, 0) + amount
+        return self._agent_credits[agent_did]
+    
+    def list_escrows(
+        self,
+        agent_did: Optional[str] = None,
+        status: Optional[EscrowStatus] = None,
+    ) -> list[EscrowReceipt]:
+        """List escrows with optional filtering."""
+        results = list(self._escrows.values())
+        
+        if agent_did:
+            results = [
+                e for e in results
+                if e.request.requester_did == agent_did or e.request.provider_did == agent_did
+            ]
+        
+        if status:
+            results = [e for e in results if e.status == status]
+        
+        return results
+    
+    def _get_escrow(self, escrow_id: str) -> EscrowReceipt:
+        """Get escrow by ID or raise error."""
+        if escrow_id not in self._escrows:
+            raise EscrowNotFoundError(escrow_id)
+        return self._escrows[escrow_id]
+    
+    def _sign_escrow(self, escrow_id: str, request: EscrowRequest) -> str:
+        """Generate Nexus signature for escrow."""
+        data = f"{escrow_id}:{request.task_hash}:{request.credits}"
+        return f"nexus_escrow_{hashlib.sha256(data.encode()).hexdigest()[:32]}"
+    
+    def _sign_resolution(self, escrow_id: str, outcome: str) -> str:
+        """Generate Nexus signature for resolution."""
+        data = f"{escrow_id}:{outcome}:{datetime.utcnow().isoformat()}"
+        return f"nexus_res_{hashlib.sha256(data.encode()).hexdigest()[:32]}"
+
+
+class ProofOfOutcome:
+    """
+    High-level API for the Proof-of-Outcome mechanism.
+    
+    Wraps EscrowManager with SCAK validation integration.
+    """
+    
+    def __init__(
+        self,
+        escrow_manager: Optional[EscrowManager] = None,
+        scak_validator: Optional[any] = None,  # Would be SCAK validator
+    ):
+        self.escrow_manager = escrow_manager or EscrowManager()
+        self.scak_validator = scak_validator
+    
+    async def create_escrow(
+        self,
+        requester_did: str,
+        provider_did: str,
+        task_hash: str,
+        credits: int,
+        timeout_seconds: int = 3600,
+        require_scak: bool = True,
+        drift_threshold: float = 0.15,
+    ) -> EscrowReceipt:
+        """Create an escrow for a task."""
+        request = EscrowRequest(
+            requester_did=requester_did,
+            provider_did=provider_did,
+            task_hash=task_hash,
+            credits=credits,
+            timeout_seconds=timeout_seconds,
+            require_scak_validation=require_scak,
+            scak_drift_threshold=drift_threshold,
+        )
+        
+        # TODO: Generate actual signature
+        signature = f"sig_{requester_did}_{task_hash[:8]}"
+        
+        return await self.escrow_manager.create_escrow(request, signature)
+    
+    async def validate_outcome(
+        self,
+        escrow_id: str,
+        flight_recorder_log: bytes,
+        claimed_outcome: Literal["success", "failure"],
+    ) -> tuple[bool, Optional[float]]:
+        """
+        Validate task outcome using SCAK.
+        
+        Replays the flight recorder log against the Control Plane
+        to deterministically verify the claimed outcome.
+        
+        Returns:
+            Tuple of (passed, drift_score)
+        """
+        receipt = self.escrow_manager.get_escrow(escrow_id)
+        
+        if self.scak_validator is None:
+            # No SCAK validator - assume success
+            return True, 0.0
+        
+        # Validate with SCAK
+        # drift_score = await self.scak_validator.validate(flight_recorder_log)
+        # For now, simulate
+        drift_score = 0.05
+        
+        threshold = receipt.request.scak_drift_threshold
+        passed = drift_score <= threshold
+        
+        return passed, drift_score
+    
+    async def release_escrow(
+        self,
+        escrow_id: str,
+        outcome: Literal["success", "failure", "dispute"],
+        output_hash: Optional[str] = None,
+        duration_ms: Optional[int] = None,
+        scak_drift_score: Optional[float] = None,
+        dispute_reason: Optional[str] = None,
+    ) -> EscrowResolution:
+        """
+        Release escrow based on outcome.
+        
+        - success: Credits go to provider, provider reputation +2
+        - failure: Credits return to requester, provider reputation -10
+        - dispute: Escalate to Arbiter
+        """
+        receipt = self.escrow_manager.get_escrow(escrow_id)
+        
+        # Determine if SCAK passed
+        scak_passed = None
+        if scak_drift_score is not None:
+            scak_passed = scak_drift_score <= receipt.request.scak_drift_threshold
+        
+        release = EscrowRelease(
+            escrow_id=escrow_id,
+            outcome=outcome,
+            output_hash=output_hash,
+            duration_ms=duration_ms,
+            scak_validated=scak_drift_score is not None,
+            scak_drift_score=scak_drift_score,
+            scak_passed=scak_passed,
+            dispute_reason=dispute_reason,
+        )
+        
+        return await self.escrow_manager.release_escrow(release)

modules/nexus/exceptions.py

@@ -0,0 +1,284 @@
+"""
+Nexus Exceptions
+
+Custom exceptions for the Nexus Trust Exchange.
+These exceptions drive the viral loop by directing unverified agents to register.
+"""
+
+from typing import Optional
+
+
+class NexusError(Exception):
+    """Base exception for all Nexus errors."""
+    
+    def __init__(self, message: str, code: Optional[str] = None):
+        self.message = message
+        self.code = code or "NEXUS_ERROR"
+        super().__init__(f"[{self.code}] {message}")
+
+
+class IATPUnverifiedPeerException(NexusError):
+    """
+    Raised when a peer agent is not registered on Nexus.
+    
+    This is THE viral mechanism - the error message includes a registration URL,
+    driving unverified agents to register on Nexus to communicate.
+    """
+    
+    REGISTRATION_BASE_URL = "https://nexus.agent-os.dev/register"
+    
+    def __init__(self, peer_id: str, peer_address: Optional[str] = None):
+        self.peer_id = peer_id
+        self.peer_address = peer_address
+        self.registration_url = f"{self.REGISTRATION_BASE_URL}?agent={peer_id}"
+        
+        message = (
+            f"Agent identity unknown: '{peer_id}' is not registered on Nexus. "
+            f"To establish an IATP handshake, the agent must register at: {self.registration_url}"
+        )
+        super().__init__(message, code="IATP_UNVERIFIED_PEER")
+    
+    def to_iatp_error(self) -> dict:
+        """Convert to IATP error response format."""
+        return {
+            "error": "IATP_UNVERIFIED_PEER",
+            "message": self.message,
+            "peer_id": self.peer_id,
+            "registration_url": self.registration_url,
+            "action_required": "Register the agent on Nexus to enable communication",
+        }
+
+
+class IATPInsufficientTrustException(NexusError):
+    """
+    Raised when a peer's trust score is below the required threshold.
+    
+    Drives agents to improve their reputation through successful task completion.
+    """
+    
+    def __init__(
+        self, 
+        peer_did: str, 
+        current_score: int, 
+        required_score: int,
+        improvement_url: Optional[str] = None
+    ):
+        self.peer_did = peer_did
+        self.current_score = current_score
+        self.required_score = required_score
+        self.improvement_url = improvement_url or f"https://nexus.agent-os.dev/reputation/{peer_did}"
+        self.score_gap = required_score - current_score
+        
+        message = (
+            f"Insufficient trust score for agent '{peer_did}': "
+            f"current={current_score}, required={required_score} (gap: {self.score_gap}). "
+            f"Improve reputation at: {self.improvement_url}"
+        )
+        super().__init__(message, code="IATP_INSUFFICIENT_TRUST")
+    
+    def to_iatp_error(self) -> dict:
+        """Convert to IATP error response format."""
+        return {
+            "error": "IATP_INSUFFICIENT_TRUST",
+            "message": self.message,
+            "peer_did": self.peer_did,
+            "current_score": self.current_score,
+            "required_score": self.required_score,
+            "score_gap": self.score_gap,
+            "improvement_url": self.improvement_url,
+            "action_required": "Complete tasks successfully to improve reputation",
+        }
+
+
+class IATPAttestationExpiredException(NexusError):
+    """Raised when a peer's attestation has expired."""
+    
+    def __init__(self, peer_did: str, expired_at: str):
+        self.peer_did = peer_did
+        self.expired_at = expired_at
+        
+        message = (
+            f"Attestation expired for agent '{peer_did}' at {expired_at}. "
+            f"Agent must renew attestation with Control Plane."
+        )
+        super().__init__(message, code="IATP_ATTESTATION_EXPIRED")
+
+
+class IATPPolicyViolationException(NexusError):
+    """Raised when a peer's policies don't meet requirements."""
+    
+    def __init__(self, peer_did: str, violation: str, required_policy: str):
+        self.peer_did = peer_did
+        self.violation = violation
+        self.required_policy = required_policy
+        
+        message = (
+            f"Policy violation for agent '{peer_did}': {violation}. "
+            f"Required policy: {required_policy}"
+        )
+        super().__init__(message, code="IATP_POLICY_VIOLATION")
+
+
+class EscrowError(NexusError):
+    """Base exception for escrow-related errors."""
+    
+    def __init__(self, message: str, escrow_id: Optional[str] = None):
+        self.escrow_id = escrow_id
+        super().__init__(message, code="ESCROW_ERROR")
+
+
+class EscrowNotFoundError(EscrowError):
+    """Raised when an escrow cannot be found."""
+    
+    def __init__(self, escrow_id: str):
+        super().__init__(f"Escrow not found: {escrow_id}", escrow_id=escrow_id)
+        self.code = "ESCROW_NOT_FOUND"
+
+
+class EscrowExpiredError(EscrowError):
+    """Raised when attempting to operate on an expired escrow."""
+    
+    def __init__(self, escrow_id: str, expired_at: str):
+        self.expired_at = expired_at
+        super().__init__(
+            f"Escrow {escrow_id} expired at {expired_at}",
+            escrow_id=escrow_id
+        )
+        self.code = "ESCROW_EXPIRED"
+
+
+class EscrowAlreadyResolvedError(EscrowError):
+    """Raised when attempting to modify an already-resolved escrow."""
+    
+    def __init__(self, escrow_id: str, resolution_status: str):
+        self.resolution_status = resolution_status
+        super().__init__(
+            f"Escrow {escrow_id} already resolved with status: {resolution_status}",
+            escrow_id=escrow_id
+        )
+        self.code = "ESCROW_ALREADY_RESOLVED"
+
+
+class InsufficientCreditsError(EscrowError):
+    """Raised when an agent doesn't have enough credits for escrow."""
+    
+    def __init__(self, agent_did: str, required: int, available: int):
+        self.agent_did = agent_did
+        self.required = required
+        self.available = available
+        super().__init__(
+            f"Agent {agent_did} has insufficient credits: required={required}, available={available}"
+        )
+        self.code = "INSUFFICIENT_CREDITS"
+
+
+class DisputeError(NexusError):
+    """Base exception for dispute-related errors."""
+    
+    def __init__(self, message: str, dispute_id: Optional[str] = None):
+        self.dispute_id = dispute_id
+        super().__init__(message, code="DISPUTE_ERROR")
+
+
+class DisputeNotFoundError(DisputeError):
+    """Raised when a dispute cannot be found."""
+    
+    def __init__(self, dispute_id: str):
+        super().__init__(f"Dispute not found: {dispute_id}", dispute_id=dispute_id)
+        self.code = "DISPUTE_NOT_FOUND"
+
+
+class DisputeAlreadyResolvedError(DisputeError):
+    """Raised when attempting to modify a resolved dispute."""
+    
+    def __init__(self, dispute_id: str):
+        super().__init__(
+            f"Dispute {dispute_id} has already been resolved",
+            dispute_id=dispute_id
+        )
+        self.code = "DISPUTE_ALREADY_RESOLVED"
+
+
+class DisputeEvidenceError(DisputeError):
+    """Raised when there's an issue with dispute evidence."""
+    
+    def __init__(self, dispute_id: str, issue: str):
+        self.issue = issue
+        super().__init__(
+            f"Evidence issue for dispute {dispute_id}: {issue}",
+            dispute_id=dispute_id
+        )
+        self.code = "DISPUTE_EVIDENCE_ERROR"
+
+
+class RegistryError(NexusError):
+    """Base exception for registry-related errors."""
+    
+    def __init__(self, message: str, agent_did: Optional[str] = None):
+        self.agent_did = agent_did
+        super().__init__(message, code="REGISTRY_ERROR")
+
+
+class AgentAlreadyRegisteredError(RegistryError):
+    """Raised when attempting to register an already-registered agent."""
+    
+    def __init__(self, agent_did: str):
+        super().__init__(
+            f"Agent already registered: {agent_did}",
+            agent_did=agent_did
+        )
+        self.code = "AGENT_ALREADY_REGISTERED"
+
+
+class AgentNotFoundError(RegistryError):
+    """Raised when an agent cannot be found in the registry."""
+    
+    def __init__(self, agent_did: str):
+        super().__init__(
+            f"Agent not found in registry: {agent_did}",
+            agent_did=agent_did
+        )
+        self.code = "AGENT_NOT_FOUND"
+
+
+class InvalidManifestError(RegistryError):
+    """Raised when an agent manifest is invalid."""
+    
+    def __init__(self, agent_did: str, validation_errors: list[str]):
+        self.validation_errors = validation_errors
+        super().__init__(
+            f"Invalid manifest for {agent_did}: {', '.join(validation_errors)}",
+            agent_did=agent_did
+        )
+        self.code = "INVALID_MANIFEST"
+
+
+class DMZError(NexusError):
+    """Base exception for DMZ protocol errors."""
+    
+    def __init__(self, message: str):
+        super().__init__(message, code="DMZ_ERROR")
+
+
+class PolicyNotSignedError(DMZError):
+    """Raised when data handling policy hasn't been signed."""
+    
+    def __init__(self, agent_did: str, policy_hash: str):
+        self.agent_did = agent_did
+        self.policy_hash = policy_hash
+        super().__init__(
+            f"Agent {agent_did} has not signed policy {policy_hash}"
+        )
+        self.code = "POLICY_NOT_SIGNED"
+
+
+class DataClassificationError(DMZError):
+    """Raised when data classification prevents operation."""
+    
+    def __init__(self, classification: str, reason: str):
+        self.classification = classification
+        self.reason = reason
+        super().__init__(
+            f"Data classification '{classification}' blocked: {reason}"
+        )
+        self.code = "DATA_CLASSIFICATION_ERROR"