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

modules/nexus/schemas/manifest.py

@@ -0,0 +1,223 @@
+"""
+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
+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.utcnow() < 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",
+        }

modules/nexus/schemas/receipt.py

@@ -0,0 +1,206 @@
+"""
+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: SignedReceipt
+    
+    # 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"
+    )

modules/observability/README.md

@@ -0,0 +1,192 @@
+# Agent OS Observability
+
+> **Part of [Agent OS](https://github.com/imran-siddique/agent-os)** - Kernel-level governance for AI agents
+
+Production-ready observability stack for Agent OS kernel.
+
+## Status: Alpha
+
+This package provides metrics, tracing, and dashboards for monitoring Agent OS deployments.
+
+## Features
+
+- **Prometheus Metrics**: Kernel, agent, and CMVK metrics
+- **OpenTelemetry Tracing**: Distributed tracing for agent operations
+- **Grafana Dashboards**: Pre-built dashboards for SOC, ML Ops, and SRE teams
+- **Prometheus Alerts**: Safety, performance, and availability alerts
+
+## Quick Start
+
+### Install Package
+
+```bash
+pip install agent-os-observability
+```
+
+### Basic Usage
+
+```python
+from agent_os_observability import KernelMetrics, KernelTracer
+
+# Initialize metrics
+metrics = KernelMetrics()
+
+# Record policy check
+with metrics.policy_check_latency():
+    result = policy_engine.check(action)
+
+# Record violation
+if not result.allowed:
+    metrics.record_violation(agent_id, action, policy="data-access", severity="high")
+    metrics.record_blocked(agent_id, action)
+
+# CMVK metrics
+metrics.record_cmvk_verification(
+    result="verified",
+    confidence=0.95,
+    drift_score=0.08,
+    duration_seconds=2.3,
+    model_count=3
+)
+
+# Expose /metrics endpoint (FastAPI example)
+from fastapi import FastAPI, Response
+
+app = FastAPI()
+
+@app.get("/metrics")
+def get_metrics():
+    return Response(
+        content=metrics.export(),
+        media_type=metrics.content_type()
+    )
+```
+
+### Full Observability Stack (Docker)
+
+```bash
+cd packages/observability
+docker-compose up -d
+
+# Open dashboards
+open http://localhost:3000  # Grafana (admin/admin)
+open http://localhost:16686 # Jaeger
+open http://localhost:9090  # Prometheus
+```
+
+## Metrics Reference
+
+### Kernel Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `agent_os_violations_total` | Counter | Policy violations by agent, action, policy, severity |
+| `agent_os_violations_blocked_total` | Counter | Violations blocked (SIGKILL issued) |
+| `agent_os_violation_rate` | Gauge | Violations per 1000 requests |
+| `agent_os_policy_check_duration_seconds` | Histogram | Policy check latency |
+| `agent_os_signals_total` | Counter | Signals sent by type and reason |
+| `agent_os_sigkill_total` | Counter | SIGKILL signals by agent and reason |
+| `agent_os_mttr_seconds` | Histogram | Mean Time To Recovery |
+| `agent_os_kernel_uptime_seconds` | Gauge | Kernel uptime |
+
+### CMVK Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `agent_os_cmvk_verifications_total` | Counter | Verifications by result (verified/flagged/rejected) |
+| `agent_os_cmvk_consensus_ratio` | Gauge | Current model agreement (0.0-1.0) |
+| `agent_os_cmvk_model_disagreements_total` | Counter | Disagreements by model pair |
+| `agent_os_cmvk_drift_score` | Histogram | Drift score distribution |
+| `agent_os_cmvk_verification_duration_seconds` | Histogram | Verification latency |
+| `agent_os_cmvk_model_latency_seconds` | Histogram | Per-model response latency |
+
+### Agent Metrics
+
+| Metric | Type | Description |
+|--------|------|-------------|
+| `agent_os_agent_llm_calls_total` | Counter | LLM API calls by agent and model |
+| `agent_os_agent_errors_total` | Counter | Errors by agent and type |
+| `agent_os_agent_execution_duration_seconds` | Histogram | Task execution time |
+
+## Dashboards
+
+### agent-os-overview (10 panels)
+Main dashboard for SOC teams: violation rate, SIGKILL count, latency, throughput.
+
+### agent-os-cmvk (12 panels)
+ML Ops dashboard: consensus rate, drift scores, model latency, verification results.
+
+### agent-os-amb (13 panels)
+AMB (Agent Message Bus): throughput, queue depth, backpressure, delivery latency.
+
+### agent-os-safety (1 panel)
+CISO dashboard: 30-day violation count.
+
+### Export Dashboards
+
+```bash
+python scripts/export_dashboards.py
+```
+
+This creates JSON files in `grafana/dashboards/` for Grafana provisioning.
+
+## Alerts
+
+Alert rules are defined in `alerts/agent-os-alerts.yaml`:
+
+### Critical Alerts (Page Immediately)
+- `AgentOSHighViolationRate`: Violation rate >1%
+- `AgentOSSIGKILLSpike`: >5 SIGKILL in 5 minutes
+- `AgentOSKernelCrash`: Kernel panic
+
+### Warning Alerts
+- `AgentOSHighPolicyLatency`: p99 latency >10ms
+- `CMVKLowConsensus`: Consensus <80%
+- `CMVKHighDrift`: p95 drift >0.25
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    Your Application                          │
+│  ┌──────────────────┐  ┌──────────────────┐                 │
+│  │   Agent OS       │  │   KernelMetrics  │                 │
+│  │   Kernel         │──│   .export()      │───► /metrics    │
+│  └──────────────────┘  └──────────────────┘                 │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│                 Docker Compose Stack                         │
+│  ┌────────────┐  ┌────────────┐  ┌────────────┐            │
+│  │ Prometheus │─►│  Grafana   │  │   Jaeger   │            │
+│  │   :9090    │  │   :3000    │  │  :16686    │            │
+│  └────────────┘  └────────────┘  └────────────┘            │
+│         │               ▲               ▲                   │
+│         ▼               │               │                   │
+│  ┌────────────┐        │        ┌────────────┐             │
+│  │AlertManager│        │        │   OTEL     │             │
+│  │   :9093    │        │        │ Collector  │             │
+│  └────────────┘        │        └────────────┘             │
+│         │              │               ▲                    │
+│         ▼              │               │                    │
+│  [Slack/PagerDuty]     └───────────────┘                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Development
+
+```bash
+# Install in development mode
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Export dashboards
+python scripts/export_dashboards.py
+```
+
+## License
+
+MIT