agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/liability/slashing.py

@@ -0,0 +1,80 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Collateral Penalty Engine — stub implementation.
+
+Public Preview: penalty is not enforced. Penalty calls are logged only.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+
+@dataclass
+class SlashResult:
+    """Result of a penalty operation."""
+
+    slash_id: str
+    vouchee_did: str
+    vouchee_sigma_before: float
+    vouchee_sigma_after: float
+    voucher_clips: list[VoucherClip]
+    reason: str
+    session_id: str
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    cascade_depth: int = 0
+
+
+@dataclass
+class VoucherClip:
+    """A collateral clip applied to a sponsor."""
+
+    voucher_did: str
+    sigma_before: float
+    sigma_after: float
+    risk_weight: float
+    vouch_id: str
+
+
+class SlashingEngine:
+    """
+    Penalty stub (Public Preview: logs penalty events, no penalties applied).
+    """
+
+    MAX_CASCADE_DEPTH = 2
+    SIGMA_FLOOR = 0.05
+
+    def __init__(self, vouching_engine: object) -> None:
+        self._slash_history: list[SlashResult] = []
+
+    def slash(
+        self,
+        vouchee_did: str,
+        session_id: str,
+        vouchee_sigma: float,
+        risk_weight: float,
+        reason: str,
+        agent_scores: dict[str, float],
+        cascade_depth: int = 0,
+    ) -> SlashResult:
+        """Log a penalty event (Public Preview: no penalties applied)."""
+        result = SlashResult(
+            slash_id=f"penalize:{uuid.uuid4()}",
+            vouchee_did=vouchee_did,
+            vouchee_sigma_before=vouchee_sigma,
+            vouchee_sigma_after=vouchee_sigma,
+            voucher_clips=[],
+            reason=reason,
+            session_id=session_id,
+            cascade_depth=0,
+        )
+        self._slash_history.append(result)
+        return result
+
+    @property
+    def history(self) -> list[SlashResult]:
+        return list(self._slash_history)

hypervisor/liability/vouching.py

@@ -0,0 +1,134 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Sponsorship Protocol — stub implementation.
+
+Public Preview: sponsorship is not enforced. All requests are approved.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from hypervisor.constants import (
+    VOUCHING_DEFAULT_BOND_PCT,
+    VOUCHING_DEFAULT_MAX_EXPOSURE,
+    VOUCHING_MIN_VOUCHER_SCORE,
+    VOUCHING_SCORE_SCALE,
+)
+
+
+@dataclass
+class VouchRecord:
+    """A record of one agent sponsorship for another within a session."""
+
+    vouch_id: str
+    voucher_did: str
+    vouchee_did: str
+    session_id: str
+    bonded_sigma_pct: float
+    bonded_amount: float
+    created_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    expiry: datetime | None = None
+    is_active: bool = True
+    released_at: datetime | None = None
+
+    @property
+    def is_expired(self) -> bool:
+        if self.expiry is None:
+            return False
+        return datetime.now(UTC) > self.expiry
+
+
+class VouchingEngine:
+    """
+    Sponsorship stub (Public Preview: approves all, no bonding).
+    """
+
+    SCORE_SCALE = VOUCHING_SCORE_SCALE
+    MIN_VOUCHER_SCORE = VOUCHING_MIN_VOUCHER_SCORE
+    DEFAULT_BOND_PCT = VOUCHING_DEFAULT_BOND_PCT
+    DEFAULT_MAX_EXPOSURE = VOUCHING_DEFAULT_MAX_EXPOSURE
+
+    def __init__(self, max_exposure: float | None = None) -> None:
+        self._vouches: dict[str, VouchRecord] = {}
+        self.max_exposure = max_exposure or self.DEFAULT_MAX_EXPOSURE
+
+    def vouch(
+        self,
+        voucher_did: str,
+        vouchee_did: str,
+        session_id: str,
+        voucher_sigma: float,
+        bond_pct: float | None = None,
+        expiry: datetime | None = None,
+    ) -> VouchRecord:
+        """Create a sponsorship record (Public Preview: always succeeds, no bonding)."""
+        record = VouchRecord(
+            vouch_id=f"sponsor:{uuid.uuid4()}",
+            voucher_did=voucher_did,
+            vouchee_did=vouchee_did,
+            session_id=session_id,
+            bonded_sigma_pct=0.0,
+            bonded_amount=0.0,
+        )
+        self._vouches[record.vouch_id] = record
+        return record
+
+    def compute_eff_score(
+        self,
+        vouchee_did: str,
+        session_id: str,
+        vouchee_sigma: float,
+        risk_weight: float,
+    ) -> float:
+        """Return sponsored agent's own score (Public Preview: no sponsor boost)."""
+        return vouchee_sigma
+
+    def get_vouchers_for(self, agent_did: str, session_id: str) -> list[VouchRecord]:
+        """Get all sponsors for an agent in a session."""
+        return [
+            v for v in self._vouches.values()
+            if v.vouchee_did == agent_did
+            and v.session_id == session_id
+            and v.is_active
+        ]
+
+    def get_total_exposure(self, voucher_did: str, session_id: str) -> float:
+        """Always zero in Public Preview."""
+        return 0.0
+
+    def release_bond(self, vouch_id: str) -> None:
+        """Release a sponsorship bond."""
+        if vouch_id not in self._vouches:
+            raise VouchingError(f"Sponsor {vouch_id} not found")
+        record = self._vouches[vouch_id]
+        record.is_active = False
+        record.released_at = datetime.now(UTC)
+
+    def release_session_bonds(self, session_id: str) -> int:
+        """Release all bonds for a session."""
+        count = 0
+        for v in self._vouches.values():
+            if v.session_id == session_id and v.is_active:
+                v.is_active = False
+                v.released_at = datetime.now(UTC)
+                count += 1
+        return count
+
+    def _active_vouches_for(
+        self, agent_did: str, session_id: str
+    ) -> list[VouchRecord]:
+        return self.get_vouchers_for(agent_did, session_id)
+
+    def _creates_cycle(
+        self, voucher_did: str, vouchee_did: str, session_id: str
+    ) -> bool:
+        return False
+
+
+class VouchingError(Exception):
+    """Raised for sponsorship protocol violations."""

hypervisor/models.py

@@ -0,0 +1,277 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Core data models for the Agent Hypervisor."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+
+from hypervisor.constants import (
+    MAX_AGENT_ID_LENGTH,
+    MAX_API_PATH_LENGTH,
+    MAX_DURATION_LIMIT,
+    MAX_NAME_LENGTH,
+    MAX_PARTICIPANTS_LIMIT,
+    MAX_UNDO_WINDOW,
+    RING_1_TRUST_THRESHOLD,
+    RING_2_TRUST_THRESHOLD,
+    RISK_WEIGHT_FULL,
+    RISK_WEIGHT_NONE,
+    RISK_WEIGHT_PARTIAL,
+    SESSION_DEFAULT_MIN_EFF_SCORE,
+)
+
+# Agent ID: DID format (did:method:id) or simple alphanumeric identifiers.
+# Restrict to safe characters — no @, no consecutive special chars.
+_AGENT_ID_PATTERN = re.compile(r"^[a-zA-Z0-9](?:[a-zA-Z0-9._:-]*[a-zA-Z0-9])?$")
+# Aliases for backward compatibility
+_MAX_AGENT_ID_LENGTH = MAX_AGENT_ID_LENGTH
+_MAX_NAME_LENGTH = MAX_NAME_LENGTH
+_MAX_API_PATH_LENGTH = MAX_API_PATH_LENGTH
+_MAX_PARTICIPANTS_LIMIT = MAX_PARTICIPANTS_LIMIT
+_MAX_DURATION_LIMIT = MAX_DURATION_LIMIT
+_MAX_UNDO_WINDOW = MAX_UNDO_WINDOW
+
+
+class ConsistencyMode(str, Enum):
+    """Session consistency mode. Strong requires consensus; Eventual uses gossip."""
+
+    STRONG = "strong"
+    EVENTUAL = "eventual"
+
+
+class ExecutionRing(int, Enum):
+    """
+    Hardware-inspired execution privilege rings.
+
+    Ring 0 (Root): Hypervisor config & penalty — requires SRE Witness.
+    Ring 1 (Privileged): Non-reversible actions — requires eff_score > 0.95 + consensus.
+    Ring 2 (Standard): Reversible actions — requires eff_score > 0.60.
+    Ring 3 (Sandbox): Read-only / research — default for unknown agents.
+    """
+
+    RING_0_ROOT = 0
+    RING_1_PRIVILEGED = 1
+    RING_2_STANDARD = 2
+    RING_3_SANDBOX = 3
+
+    @classmethod
+    def from_eff_score(cls, eff_score: float, has_consensus: bool = False) -> ExecutionRing:
+        """Derive ring level from effective reputation score."""
+        if eff_score > RING_1_TRUST_THRESHOLD and has_consensus:
+            return cls.RING_1_PRIVILEGED
+        elif eff_score > RING_2_TRUST_THRESHOLD:
+            return cls.RING_2_STANDARD
+        else:
+            return cls.RING_3_SANDBOX
+
+
+class ReversibilityLevel(str, Enum):
+    """How reversible an action is."""
+
+    FULL = "full"
+    PARTIAL = "partial"
+    NONE = "none"
+
+    @property
+    def risk_weight_range(self) -> tuple[float, float]:
+        """Return the (min, max) risk weight ω for this reversibility level."""
+        if self == ReversibilityLevel.FULL:
+            return RISK_WEIGHT_FULL
+        elif self == ReversibilityLevel.PARTIAL:
+            return RISK_WEIGHT_PARTIAL
+        else:
+            return RISK_WEIGHT_NONE
+
+    @property
+    def default_risk_weight(self) -> float:
+        """Return the default ω for this level."""
+        lo, hi = self.risk_weight_range
+        return (lo + hi) / 2
+
+
+class SessionState(str, Enum):
+    """Lifecycle state of a Shared Session."""
+
+    CREATED = "created"
+    HANDSHAKING = "handshaking"
+    ACTIVE = "active"
+    TERMINATING = "terminating"
+    ARCHIVED = "archived"
+
+
+def _validate_identifier(value: str, field_name: str) -> None:
+    """Validate an identifier string (agent DID, action ID, etc.)."""
+    if not isinstance(value, str):
+        raise TypeError(f"{field_name} must be a string, got {type(value).__name__}")
+    if not value or not value.strip():
+        raise ValueError(f"{field_name} must not be empty")
+    if len(value) > _MAX_AGENT_ID_LENGTH:
+        raise ValueError(
+            f"{field_name} exceeds maximum length of {_MAX_AGENT_ID_LENGTH} characters"
+        )
+    if not _AGENT_ID_PATTERN.match(value):
+        raise ValueError(
+            f"{field_name} contains invalid characters: {value!r}. "
+            f"Only alphanumeric, hyphens, underscores, colons, and dots are allowed."
+        )
+
+
+def _validate_api_path(value: str, field_name: str) -> None:
+    """Validate an API path string."""
+    if not isinstance(value, str):
+        raise TypeError(f"{field_name} must be a string, got {type(value).__name__}")
+    if not value or not value.strip():
+        raise ValueError(f"{field_name} must not be empty")
+    if len(value) > _MAX_API_PATH_LENGTH:
+        raise ValueError(
+            f"{field_name} exceeds maximum length of {_MAX_API_PATH_LENGTH} characters"
+        )
+
+
+@dataclass
+class SessionConfig:
+    """Configuration for a new Shared Session."""
+
+    consistency_mode: ConsistencyMode = ConsistencyMode.EVENTUAL
+    max_participants: int = 10
+    max_duration_seconds: int = 3600
+    min_eff_score: float = SESSION_DEFAULT_MIN_EFF_SCORE
+    enable_audit: bool = True
+    enable_blockchain_commitment: bool = False
+
+    def __post_init__(self) -> None:
+        if not isinstance(self.max_participants, int):
+            raise TypeError(
+                f"max_participants must be an integer, got {type(self.max_participants).__name__}"
+            )
+        if self.max_participants < 1:
+            raise ValueError(
+                f"max_participants must be at least 1, got {self.max_participants}"
+            )
+        if self.max_participants > _MAX_PARTICIPANTS_LIMIT:
+            raise ValueError(
+                f"max_participants must not exceed {_MAX_PARTICIPANTS_LIMIT}, "
+                f"got {self.max_participants}"
+            )
+        if not isinstance(self.max_duration_seconds, int):
+            raise TypeError(
+                f"max_duration_seconds must be an integer, "
+                f"got {type(self.max_duration_seconds).__name__}"
+            )
+        if self.max_duration_seconds < 1:
+            raise ValueError(
+                f"max_duration_seconds must be at least 1, got {self.max_duration_seconds}"
+            )
+        if self.max_duration_seconds > _MAX_DURATION_LIMIT:
+            raise ValueError(
+                f"max_duration_seconds must not exceed {_MAX_DURATION_LIMIT} (7 days), "
+                f"got {self.max_duration_seconds}"
+            )
+        if not isinstance(self.min_eff_score, (int, float)):
+            raise TypeError(
+                f"min_eff_score must be a number, got {type(self.min_eff_score).__name__}"
+            )
+        if not (0.0 <= self.min_eff_score <= 1.0):
+            raise ValueError(
+                f"min_eff_score must be between 0.0 and 1.0, got {self.min_eff_score}"
+            )
+
+
+@dataclass
+class SessionParticipant:
+    """An agent participating in a session."""
+
+    agent_did: str
+    ring: ExecutionRing = ExecutionRing.RING_3_SANDBOX
+    sigma_raw: float = 0.0
+    eff_score: float = 0.0
+    joined_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    is_active: bool = True
+
+    def __post_init__(self) -> None:
+        _validate_identifier(self.agent_did, "agent_did")
+        if not isinstance(self.ring, ExecutionRing):
+            try:
+                self.ring = ExecutionRing(self.ring)
+            except (ValueError, KeyError):
+                raise ValueError(
+                    f"ring must be a valid ExecutionRing (0-3), got {self.ring!r}"
+                )
+        if not isinstance(self.sigma_raw, (int, float)):
+            raise TypeError(
+                f"sigma_raw must be a number, got {type(self.sigma_raw).__name__}"
+            )
+        if not (0.0 <= self.sigma_raw <= 1.0):
+            raise ValueError(
+                f"sigma_raw must be between 0.0 and 1.0, got {self.sigma_raw}"
+            )
+        if not isinstance(self.eff_score, (int, float)):
+            raise TypeError(
+                f"eff_score must be a number, got {type(self.eff_score).__name__}"
+            )
+        if not (0.0 <= self.eff_score <= 1.0):
+            raise ValueError(
+                f"eff_score must be between 0.0 and 1.0, got {self.eff_score}"
+            )
+
+
+@dataclass
+class ActionDescriptor:
+    """Describes an action from an IATP Capability Manifest."""
+
+    action_id: str
+    name: str
+    execute_api: str
+    undo_api: str | None = None
+    reversibility: ReversibilityLevel = ReversibilityLevel.NONE
+    undo_window_seconds: int = 0
+    compensation_method: str | None = None
+    is_read_only: bool = False
+    is_admin: bool = False
+
+    def __post_init__(self) -> None:
+        _validate_identifier(self.action_id, "action_id")
+        if not isinstance(self.name, str) or not self.name.strip():
+            raise ValueError("name must be a non-empty string")
+        if len(self.name) > _MAX_NAME_LENGTH:
+            raise ValueError(
+                f"name exceeds maximum length of {_MAX_NAME_LENGTH} characters"
+            )
+        _validate_api_path(self.execute_api, "execute_api")
+        if self.undo_api is not None:
+            _validate_api_path(self.undo_api, "undo_api")
+        if not isinstance(self.undo_window_seconds, int):
+            raise TypeError(
+                f"undo_window_seconds must be an integer, "
+                f"got {type(self.undo_window_seconds).__name__}"
+            )
+        if self.undo_window_seconds < 0:
+            raise ValueError(
+                f"undo_window_seconds must not be negative, got {self.undo_window_seconds}"
+            )
+        if self.undo_window_seconds > _MAX_UNDO_WINDOW:
+            raise ValueError(
+                f"undo_window_seconds must not exceed {_MAX_UNDO_WINDOW} (24 hours), "
+                f"got {self.undo_window_seconds}"
+            )
+
+    @property
+    def risk_weight(self) -> float:
+        """Compute ω from reversibility level."""
+        return self.reversibility.default_risk_weight
+
+    @property
+    def required_ring(self) -> ExecutionRing:
+        """Determine minimum ring required for this action."""
+        if self.is_admin:
+            return ExecutionRing.RING_0_ROOT
+        elif self.reversibility == ReversibilityLevel.NONE and not self.is_read_only:
+            return ExecutionRing.RING_1_PRIVILEGED
+        elif self.is_read_only:
+            return ExecutionRing.RING_3_SANDBOX
+        else:
+            return ExecutionRing.RING_2_STANDARD

hypervisor/observability/__init__.py

@@ -0,0 +1,27 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Observability module — structured event bus, causal tracing, and metrics."""
+
+from hypervisor.observability.causal_trace import CausalTraceId
+from hypervisor.observability.event_bus import (
+    EventType,
+    HypervisorEvent,
+    HypervisorEventBus,
+)
+from hypervisor.observability.prometheus_collector import RingMetricsCollector
+from hypervisor.observability.saga_span_exporter import (
+    SagaSpanExporter,
+    SagaSpanRecord,
+    SpanSink,
+)
+
+__all__ = [
+    "EventType",
+    "HypervisorEvent",
+    "HypervisorEventBus",
+    "CausalTraceId",
+    "RingMetricsCollector",
+    "SagaSpanExporter",
+    "SagaSpanRecord",
+    "SpanSink",
+]

hypervisor/observability/causal_trace.py

@@ -0,0 +1,70 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Causal trace IDs for cross-agent distributed tracing.
+
+Unlike simple correlation IDs, causal trace IDs encode the full
+spawn/delegation tree, making distributed traces genuinely readable.
+
+Format: {trace_id}/{span_id}[/{parent_span_id}]
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class CausalTraceId:
+    """Encodes the full spawn/delegation tree for a trace."""
+
+    trace_id: str = field(default_factory=lambda: uuid.uuid4().hex[:12])
+    span_id: str = field(default_factory=lambda: uuid.uuid4().hex[:8])
+    parent_span_id: str | None = None
+    depth: int = 0
+
+    def child(self) -> CausalTraceId:
+        """Create a child span (e.g., when spawning a sub-agent or delegating)."""
+        return CausalTraceId(
+            trace_id=self.trace_id,
+            span_id=uuid.uuid4().hex[:8],
+            parent_span_id=self.span_id,
+            depth=self.depth + 1,
+        )
+
+    def sibling(self) -> CausalTraceId:
+        """Create a sibling span (same parent, different operation)."""
+        return CausalTraceId(
+            trace_id=self.trace_id,
+            span_id=uuid.uuid4().hex[:8],
+            parent_span_id=self.parent_span_id,
+            depth=self.depth,
+        )
+
+    @property
+    def full_id(self) -> str:
+        """Full trace path: trace_id/span_id[/parent_span_id]."""
+        parts = [self.trace_id, self.span_id]
+        if self.parent_span_id:
+            parts.append(self.parent_span_id)
+        return "/".join(parts)
+
+    @classmethod
+    def from_string(cls, s: str) -> CausalTraceId:
+        """Parse a CausalTraceId from its string representation."""
+        parts = s.split("/")
+        if len(parts) < 2:
+            raise ValueError(f"Invalid causal trace ID: {s}")
+        return cls(
+            trace_id=parts[0],
+            span_id=parts[1],
+            parent_span_id=parts[2] if len(parts) > 2 else None,
+        )
+
+    def is_ancestor_of(self, other: CausalTraceId) -> bool:
+        """Check if this trace is an ancestor of another (same trace tree)."""
+        return self.trace_id == other.trace_id and other.depth > self.depth
+
+    def __str__(self) -> str:
+        return self.full_id