agent_os_kernel 3.1.0__py3-none-any.whl

nexus/schemas/manifest.py

@@ -0,0 +1,225 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Agent Manifest Schema
+
+Defines the complete identity and capability manifest for Nexus registration.
+Extends the IATP manifest (RFC-001) with Nexus-specific fields.
+"""
+
+from datetime import datetime, timezone
+from typing import Literal, Optional
+from pydantic import BaseModel, Field, field_validator
+import re
+
+
+class AgentIdentity(BaseModel):
+    """Decentralized identity for an agent."""
+    
+    did: str = Field(
+        ...,
+        description="Decentralized Identifier (did:nexus:...)",
+        examples=["did:nexus:carbon-auditor-v1.2.0"]
+    )
+    verification_key: str = Field(
+        ...,
+        description="Ed25519 public key (base64 encoded)",
+        examples=["ed25519:abc123..."]
+    )
+    owner_id: str = Field(
+        ...,
+        description="Developer/Organization ID"
+    )
+    display_name: Optional[str] = Field(
+        None,
+        description="Human-readable agent name"
+    )
+    contact: Optional[str] = Field(
+        None,
+        description="Contact email for security issues"
+    )
+    
+    @field_validator("did")
+    @classmethod
+    def validate_did(cls, v: str) -> str:
+        """Validate DID format."""
+        if not v.startswith("did:nexus:"):
+            raise ValueError("DID must start with 'did:nexus:'")
+        return v
+    
+    @field_validator("verification_key")
+    @classmethod
+    def validate_key(cls, v: str) -> str:
+        """Validate verification key format."""
+        if not v.startswith("ed25519:"):
+            raise ValueError("Verification key must be Ed25519 format")
+        return v
+
+
+class AgentCapabilities(BaseModel):
+    """What this agent can do."""
+    
+    domains: list[str] = Field(
+        default_factory=list,
+        description="Capability domains (e.g., 'data-analysis', 'code-generation')"
+    )
+    tools: list[str] = Field(
+        default_factory=list,
+        description="Available tool names"
+    )
+    max_concurrency: int = Field(
+        default=10,
+        ge=1,
+        le=1000,
+        description="Maximum concurrent requests"
+    )
+    sla_latency_ms: int = Field(
+        default=5000,
+        ge=100,
+        le=300000,
+        description="SLA latency in milliseconds"
+    )
+    idempotency: bool = Field(
+        default=False,
+        description="Whether operations are idempotent"
+    )
+    reversibility: Literal["full", "partial", "none"] = Field(
+        default="partial",
+        description="Level of operation reversibility"
+    )
+    undo_window_seconds: Optional[int] = Field(
+        default=3600,
+        description="Time window for undo operations (if reversible)"
+    )
+
+
+class AgentPrivacy(BaseModel):
+    """Privacy and data handling policies."""
+    
+    retention_policy: Literal["ephemeral", "session", "permanent"] = Field(
+        default="ephemeral",
+        description="How long data is retained"
+    )
+    pii_handling: Literal["reject", "anonymize", "accept"] = Field(
+        default="reject",
+        description="How PII is handled"
+    )
+    human_in_loop: bool = Field(
+        default=False,
+        description="Whether human review is part of processing"
+    )
+    training_consent: bool = Field(
+        default=False,
+        description="Whether data may be used for training"
+    )
+    data_residency: Optional[str] = Field(
+        default=None,
+        description="Required data residency region (e.g., 'us', 'eu')"
+    )
+
+
+class MuteRules(BaseModel):
+    """Agent OS Mute Agent rules attached to this agent."""
+    
+    rule_hashes: list[str] = Field(
+        default_factory=list,
+        description="SHA-256 hashes of attached mute rules"
+    )
+    last_validated: Optional[datetime] = Field(
+        default=None,
+        description="When rules were last validated by Control Plane"
+    )
+    control_plane_signature: Optional[str] = Field(
+        default=None,
+        description="Control Plane signature of rule validation"
+    )
+
+
+class AgentManifest(BaseModel):
+    """
+    Complete manifest for Nexus registration.
+    
+    This extends the IATP manifest (RFC-001) with Nexus-specific fields
+    for the Trust Exchange.
+    """
+    
+    schema_version: str = Field(
+        default="1.0",
+        description="Schema version for forward compatibility"
+    )
+    identity: AgentIdentity
+    capabilities: AgentCapabilities = Field(default_factory=AgentCapabilities)
+    privacy: AgentPrivacy = Field(default_factory=AgentPrivacy)
+    mute_rules: MuteRules = Field(default_factory=MuteRules)
+    
+    # Nexus-specific fields
+    verification_level: Literal["verified_partner", "verified", "registered", "unknown"] = Field(
+        default="registered",
+        description="Verification tier on Nexus"
+    )
+    registered_at: Optional[datetime] = Field(
+        default=None,
+        description="When agent was registered on Nexus"
+    )
+    last_seen: Optional[datetime] = Field(
+        default=None,
+        description="Last activity timestamp"
+    )
+    trust_score: int = Field(
+        default=400,
+        ge=0,
+        le=1000,
+        description="Current trust score (0-1000)"
+    )
+    
+    # Attestation
+    codebase_hash: Optional[str] = Field(
+        default=None,
+        description="SHA-256 hash of agent codebase"
+    )
+    config_hash: Optional[str] = Field(
+        default=None,
+        description="SHA-256 hash of agent configuration"
+    )
+    attestation_signature: Optional[str] = Field(
+        default=None,
+        description="Control Plane signature of attestation"
+    )
+    attestation_expires: Optional[datetime] = Field(
+        default=None,
+        description="When attestation expires"
+    )
+    
+    def is_attestation_valid(self) -> bool:
+        """Check if attestation is present and not expired."""
+        if not self.attestation_signature or not self.attestation_expires:
+            return False
+        return datetime.now(timezone.utc) < self.attestation_expires
+    
+    def to_iatp_manifest(self) -> dict:
+        """Convert to IATP-compatible manifest format."""
+        return {
+            "$schema": "https://agent-os.dev/iatp/v1/manifest.schema.json",
+            "identity": {
+                "agent_id": self.identity.did.replace("did:nexus:", ""),
+                "verification_key": self.identity.verification_key,
+                "owner": self.identity.owner_id,
+                "contact": self.identity.contact,
+            },
+            "trust_level": self.verification_level,
+            "capabilities": {
+                "idempotency": self.capabilities.idempotency,
+                "max_concurrency": self.capabilities.max_concurrency,
+                "sla_latency_ms": self.capabilities.sla_latency_ms,
+            },
+            "reversibility": {
+                "level": self.capabilities.reversibility,
+                "undo_window_seconds": self.capabilities.undo_window_seconds,
+            },
+            "privacy": {
+                "retention_policy": self.privacy.retention_policy,
+                "human_in_loop": self.privacy.human_in_loop,
+                "training_consent": self.privacy.training_consent,
+            },
+            "protocol_version": "1.0",
+        }

nexus/schemas/receipt.py

@@ -0,0 +1,208 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Job Receipt Schemas
+
+Defines receipts for job completion and outcome verification.
+"""
+
+from datetime import datetime
+from typing import Literal, Optional, Any
+from pydantic import BaseModel, Field
+import hashlib
+import json
+
+
+class JobReceipt(BaseModel):
+    """Base receipt for a job/task between agents."""
+    
+    receipt_id: str = Field(
+        ...,
+        description="Unique receipt identifier"
+    )
+    task_id: str = Field(
+        ...,
+        description="ID of the task being receipted"
+    )
+    requester_did: str = Field(
+        ...,
+        description="DID of the requesting agent"
+    )
+    provider_did: str = Field(
+        ...,
+        description="DID of the providing agent"
+    )
+    task_hash: str = Field(
+        ...,
+        description="SHA-256 hash of the task specification"
+    )
+    created_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="When the receipt was created"
+    )
+    
+    def compute_hash(self) -> str:
+        """Compute deterministic hash of receipt."""
+        data = {
+            "receipt_id": self.receipt_id,
+            "task_id": self.task_id,
+            "requester_did": self.requester_did,
+            "provider_did": self.provider_did,
+            "task_hash": self.task_hash,
+            "created_at": self.created_at.isoformat(),
+        }
+        canonical = json.dumps(data, sort_keys=True)
+        return hashlib.sha256(canonical.encode()).hexdigest()
+
+
+class JobCompletionReceipt(JobReceipt):
+    """Receipt issued when a job is completed."""
+    
+    outcome: Literal["success", "failure", "partial", "timeout"] = Field(
+        ...,
+        description="Outcome of the job"
+    )
+    completed_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="When the job completed"
+    )
+    duration_ms: int = Field(
+        ...,
+        ge=0,
+        description="Duration of job execution in milliseconds"
+    )
+    output_hash: Optional[str] = Field(
+        default=None,
+        description="SHA-256 hash of the output (if any)"
+    )
+    error_code: Optional[str] = Field(
+        default=None,
+        description="Error code if outcome is failure"
+    )
+    error_message: Optional[str] = Field(
+        default=None,
+        description="Error message if outcome is failure"
+    )
+    
+    # SCAK validation
+    scak_validated: bool = Field(
+        default=False,
+        description="Whether output was validated by SCAK"
+    )
+    scak_drift_score: Optional[float] = Field(
+        default=None,
+        ge=0.0,
+        le=1.0,
+        description="SCAK drift score (0=no drift, 1=complete drift)"
+    )
+    scak_threshold: Optional[float] = Field(
+        default=None,
+        description="Drift threshold used for validation"
+    )
+
+
+class SignedReceipt(BaseModel):
+    """A receipt with cryptographic signatures from both parties."""
+    
+    receipt: JobCompletionReceipt
+    receipt_hash: str = Field(
+        ...,
+        description="SHA-256 hash of the receipt"
+    )
+    
+    # Signatures
+    requester_signature: Optional[str] = Field(
+        default=None,
+        description="Ed25519 signature from requester"
+    )
+    requester_signed_at: Optional[datetime] = Field(
+        default=None,
+        description="When requester signed"
+    )
+    provider_signature: Optional[str] = Field(
+        default=None,
+        description="Ed25519 signature from provider"
+    )
+    provider_signed_at: Optional[datetime] = Field(
+        default=None,
+        description="When provider signed"
+    )
+    
+    # Nexus attestation
+    nexus_witnessed: bool = Field(
+        default=False,
+        description="Whether Nexus has witnessed this receipt"
+    )
+    nexus_signature: Optional[str] = Field(
+        default=None,
+        description="Nexus signature witnessing the receipt"
+    )
+    nexus_witnessed_at: Optional[datetime] = Field(
+        default=None,
+        description="When Nexus witnessed"
+    )
+    
+    def is_fully_signed(self) -> bool:
+        """Check if both parties have signed."""
+        return bool(self.requester_signature and self.provider_signature)
+    
+    def is_nexus_witnessed(self) -> bool:
+        """Check if Nexus has witnessed this receipt."""
+        return self.nexus_witnessed and bool(self.nexus_signature)
+
+
+class DisputeReceipt(BaseModel):
+    """Receipt for a disputed job outcome."""
+    
+    dispute_id: str = Field(
+        ...,
+        description="Unique dispute identifier"
+    )
+    original_receipt: Optional[SignedReceipt] = None
+    
+    # Dispute details
+    disputing_party: Literal["requester", "provider"] = Field(
+        ...,
+        description="Which party raised the dispute"
+    )
+    dispute_reason: str = Field(
+        ...,
+        description="Reason for the dispute"
+    )
+    claimed_outcome: Literal["success", "failure", "partial"] = Field(
+        ...,
+        description="Outcome claimed by disputing party"
+    )
+    
+    # Evidence
+    requester_logs_hash: Optional[str] = Field(
+        default=None,
+        description="Hash of requester's flight recorder logs"
+    )
+    provider_logs_hash: Optional[str] = Field(
+        default=None,
+        description="Hash of provider's flight recorder logs"
+    )
+    
+    # Resolution
+    resolved: bool = Field(
+        default=False,
+        description="Whether dispute has been resolved"
+    )
+    resolution_outcome: Optional[Literal["requester_wins", "provider_wins", "split"]] = Field(
+        default=None,
+        description="Resolution outcome"
+    )
+    arbiter_decision: Optional[str] = Field(
+        default=None,
+        description="Arbiter's decision explanation"
+    )
+    resolved_at: Optional[datetime] = Field(
+        default=None,
+        description="When dispute was resolved"
+    )
+    
+    created_at: datetime = Field(
+        default_factory=datetime.utcnow,
+        description="When dispute was raised"
+    )

nexus/tests/conftest.py

@@ -0,0 +1,146 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Shared fixtures for Nexus tests."""
+
+import os
+import sys
+from datetime import datetime, timedelta, timezone
+
+import pytest
+
+# Add parent of nexus package to path so 'nexus' is importable
+_nexus_parent = os.path.join(os.path.dirname(__file__), "..", "..")
+if _nexus_parent not in sys.path:
+    sys.path.insert(0, _nexus_parent)
+
+from nexus.reputation import ReputationEngine, ReputationHistory, TrustScore, TrustTier
+from nexus.escrow import EscrowManager
+from nexus.schemas.manifest import (
+    AgentIdentity,
+    AgentCapabilities,
+    AgentPrivacy,
+    MuteRules,
+    AgentManifest,
+)
+from nexus.schemas.escrow import EscrowRequest, EscrowReceipt, EscrowStatus
+
+
+@pytest.fixture
+def reputation_engine():
+    """Create a ReputationEngine with default threshold."""
+    return ReputationEngine(trust_threshold=500)
+
+
+@pytest.fixture
+def escrow_manager(reputation_engine):
+    """Create an EscrowManager with a reputation engine."""
+    return EscrowManager(reputation_engine=reputation_engine)
+
+
+@pytest.fixture
+def sample_identity():
+    """Create a sample AgentIdentity."""
+    return AgentIdentity(
+        did="did:nexus:test-agent-v1",
+        verification_key="ed25519:testkey123abc",
+        owner_id="org-test-corp",
+        display_name="Test Agent",
+        contact="test@example.com",
+    )
+
+
+@pytest.fixture
+def sample_capabilities():
+    """Create sample AgentCapabilities."""
+    return AgentCapabilities(
+        domains=["data-analysis", "code-generation"],
+        tools=["python", "sql"],
+        max_concurrency=10,
+        sla_latency_ms=5000,
+        idempotency=True,
+        reversibility="full",
+    )
+
+
+@pytest.fixture
+def sample_privacy():
+    """Create sample AgentPrivacy."""
+    return AgentPrivacy(
+        retention_policy="ephemeral",
+        pii_handling="reject",
+        human_in_loop=False,
+        training_consent=False,
+    )
+
+
+@pytest.fixture
+def sample_manifest(sample_identity, sample_capabilities, sample_privacy):
+    """Create a sample AgentManifest."""
+    return AgentManifest(
+        identity=sample_identity,
+        capabilities=sample_capabilities,
+        privacy=sample_privacy,
+        verification_level="registered",
+    )
+
+
+@pytest.fixture
+def sample_history():
+    """Create a sample ReputationHistory."""
+    return ReputationHistory(
+        agent_did="did:nexus:test-agent-v1",
+        successful_tasks=10,
+        failed_tasks=1,
+        total_tasks=11,
+        disputes_won=2,
+        disputes_lost=0,
+        uptime_days=30,
+        last_activity=datetime.now(timezone.utc),
+    )
+
+
+@pytest.fixture
+def sample_escrow_request():
+    """Create a sample EscrowRequest."""
+    return EscrowRequest(
+        requester_did="did:nexus:requester-agent",
+        provider_did="did:nexus:provider-agent",
+        task_hash="abc123def456",
+        credits=100,
+        timeout_seconds=3600,
+        require_scak_validation=False,
+    )
+
+
+def make_manifest(
+    did: str = "did:nexus:test-agent-v1",
+    owner_id: str = "org-test-corp",
+    verification_level: str = "registered",
+    domains: list[str] | None = None,
+    retention_policy: str = "ephemeral",
+    pii_handling: str = "reject",
+    training_consent: bool = False,
+    idempotency: bool = False,
+    reversibility: str = "partial",
+    trust_score: int = 400,
+) -> AgentManifest:
+    """Helper to create manifests with custom parameters."""
+    return AgentManifest(
+        identity=AgentIdentity(
+            did=did,
+            verification_key="ed25519:testkey123abc",
+            owner_id=owner_id,
+        ),
+        capabilities=AgentCapabilities(
+            domains=domains or ["data-analysis"],
+            idempotency=idempotency,
+            reversibility=reversibility,
+        ),
+        privacy=AgentPrivacy(
+            retention_policy=retention_policy,
+            pii_handling=pii_handling,
+            training_consent=training_consent,
+        ),
+        verification_level=verification_level,
+        trust_score=trust_score,
+    )