agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/observability/saga_span_exporter.py

@@ -0,0 +1,341 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+OpenTelemetry-compatible span exporter for Saga orchestration steps.
+
+Subscribes to the HypervisorEventBus for saga lifecycle events and
+produces span records that can be forwarded to any tracing backend
+via the ``SpanSink`` protocol.
+
+No external dependencies — the hypervisor stays standalone.  A concrete
+``OTelSpanSink`` adapter lives in ``agent-sre`` and bridges into the
+existing ``TraceExporter``.
+
+Usage::
+
+    from hypervisor.observability import SagaSpanExporter, HypervisorEventBus
+
+    bus = HypervisorEventBus()
+    exporter = SagaSpanExporter(bus)
+
+    # Optionally attach a sink (e.g. OTelSpanSink from agent-sre)
+    exporter.attach_sink(my_sink)
+
+    # ... saga events flow through the bus ...
+
+    # Or inspect buffered spans directly
+    spans = exporter.completed_spans
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+
+from hypervisor.observability.event_bus import EventType, HypervisorEvent, HypervisorEventBus
+
+# Saga event types we subscribe to
+_SAGA_LIFECYCLE_EVENTS = frozenset({
+    EventType.SAGA_CREATED,
+    EventType.SAGA_STEP_STARTED,
+    EventType.SAGA_STEP_COMMITTED,
+    EventType.SAGA_STEP_FAILED,
+    EventType.SAGA_COMPENSATING,
+    EventType.SAGA_COMPLETED,
+    EventType.SAGA_ESCALATED,
+})
+
+
+# ---------------------------------------------------------------------------
+# SpanSink protocol — no hard OTel dependency in hypervisor
+# ---------------------------------------------------------------------------
+
+
+@runtime_checkable
+class SpanSink(Protocol):
+    """Protocol for receiving completed span records.
+
+    Any object implementing this interface can receive spans from the
+    ``SagaSpanExporter``.  The ``agent-sre`` package ships an
+    ``OTelSpanSink`` adapter that bridges into the native OTel SDK.
+    """
+
+    def record_span(
+        self,
+        name: str,
+        start_time: float,
+        end_time: float,
+        attributes: dict[str, Any],
+        status: str,
+    ) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Span record dataclass
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class SagaSpanRecord:
+    """An immutable record of a completed saga span."""
+
+    name: str
+    saga_id: str
+    step_id: str
+    step_action: str
+    start_time: float
+    end_time: float
+    status: str  # "ok", "error", "compensating"
+    attributes: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def duration_seconds(self) -> float:
+        return self.end_time - self.start_time
+
+
+# ---------------------------------------------------------------------------
+# SagaSpanExporter
+# ---------------------------------------------------------------------------
+
+
+class SagaSpanExporter:
+    """Exports OpenTelemetry-compatible spans for saga orchestration steps.
+
+    Subscribes to the ``HypervisorEventBus`` for saga lifecycle events.
+    On each step completion (committed, failed, escalated), records a span
+    with timing, saga context, and status information.
+
+    Completed spans are:
+    1. Buffered internally in ``completed_spans``
+    2. Forwarded to an attached ``SpanSink`` (if any)
+
+    Attributes:
+        _bus: The event bus this exporter is subscribed to.
+        _sink: Optional SpanSink for forwarding completed spans.
+        _step_starts: Tracks step start times: ``(saga_id, step_id) -> timestamp``.
+        _saga_starts: Tracks saga creation times: ``saga_id -> timestamp``.
+        _completed_spans: Buffer of completed span records.
+    """
+
+    def __init__(self, bus: HypervisorEventBus, sink: SpanSink | None = None) -> None:
+        self._bus = bus
+        self._sink = sink
+
+        # In-flight tracking: (saga_id, step_id) -> start timestamp
+        self._step_starts: dict[tuple[str, str], float] = {}
+
+        # Saga-level tracking: saga_id -> creation timestamp
+        self._saga_starts: dict[str, float] = {}
+
+        # Completed span buffer
+        self._completed_spans: list[SagaSpanRecord] = []
+
+        # Total events processed
+        self._events_processed: int = 0
+
+        # Subscribe to all saga lifecycle events
+        for event_type in _SAGA_LIFECYCLE_EVENTS:
+            bus.subscribe(event_type=event_type, handler=self._handle_event)
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def attach_sink(self, sink: SpanSink) -> None:
+        """Attach a SpanSink to receive completed spans in real time."""
+        self._sink = sink
+
+    def detach_sink(self) -> None:
+        """Detach the current SpanSink."""
+        self._sink = None
+
+    @property
+    def completed_spans(self) -> list[SagaSpanRecord]:
+        """Return a copy of all completed span records."""
+        return list(self._completed_spans)
+
+    @property
+    def events_processed(self) -> int:
+        """Total saga events processed."""
+        return self._events_processed
+
+    def reset(self) -> None:
+        """Reset all internal state (for testing)."""
+        self._step_starts.clear()
+        self._saga_starts.clear()
+        self._completed_spans.clear()
+        self._events_processed = 0
+
+    # ------------------------------------------------------------------
+    # Event handling
+    # ------------------------------------------------------------------
+
+    def _handle_event(self, event: HypervisorEvent) -> None:
+        """Process a saga lifecycle event from the bus."""
+        self._events_processed += 1
+        payload = event.payload
+        saga_id = payload.get("saga_id", event.causal_trace_id or "unknown")
+        step_id = payload.get("step_id", "")
+        step_action = payload.get("action", payload.get("step_action", ""))
+
+        if event.event_type == EventType.SAGA_CREATED:
+            self._saga_starts[saga_id] = event.timestamp.timestamp()
+
+        elif event.event_type == EventType.SAGA_STEP_STARTED:
+            key = (saga_id, step_id or step_action)
+            self._step_starts[key] = event.timestamp.timestamp()
+
+        elif event.event_type == EventType.SAGA_STEP_COMMITTED:
+            self._complete_step(
+                saga_id=saga_id,
+                step_id=step_id or step_action,
+                step_action=step_action,
+                end_time=event.timestamp.timestamp(),
+                status="ok",
+                extra_attrs=payload,
+                agent_did=event.agent_did,
+                session_id=event.session_id,
+            )
+
+        elif event.event_type == EventType.SAGA_STEP_FAILED:
+            self._complete_step(
+                saga_id=saga_id,
+                step_id=step_id or step_action,
+                step_action=step_action,
+                end_time=event.timestamp.timestamp(),
+                status="error",
+                extra_attrs=payload,
+                agent_did=event.agent_did,
+                session_id=event.session_id,
+            )
+
+        elif event.event_type == EventType.SAGA_COMPENSATING:
+            # Compensation is a span in its own right
+            self._record_span(
+                name=f"saga.compensate.{step_action or step_id}",
+                saga_id=saga_id,
+                step_id=step_id or "compensation",
+                step_action=step_action or "compensate",
+                start_time=event.timestamp.timestamp(),
+                end_time=event.timestamp.timestamp(),  # instantaneous marker
+                status="compensating",
+                extra_attrs=payload,
+                agent_did=event.agent_did,
+                session_id=event.session_id,
+            )
+
+        elif event.event_type == EventType.SAGA_COMPLETED:
+            # Record a saga-level span from creation to completion
+            start = self._saga_starts.pop(saga_id, None)
+            if start is not None:
+                self._record_span(
+                    name=f"saga.completed.{saga_id}",
+                    saga_id=saga_id,
+                    step_id="",
+                    step_action="complete",
+                    start_time=start,
+                    end_time=event.timestamp.timestamp(),
+                    status="ok",
+                    extra_attrs=payload,
+                    agent_did=event.agent_did,
+                    session_id=event.session_id,
+                )
+
+        elif event.event_type == EventType.SAGA_ESCALATED:
+            start = self._saga_starts.pop(saga_id, None)
+            if start is not None:
+                self._record_span(
+                    name=f"saga.escalated.{saga_id}",
+                    saga_id=saga_id,
+                    step_id="",
+                    step_action="escalate",
+                    start_time=start,
+                    end_time=event.timestamp.timestamp(),
+                    status="error",
+                    extra_attrs=payload,
+                    agent_did=event.agent_did,
+                    session_id=event.session_id,
+                )
+
+    def _complete_step(
+        self,
+        saga_id: str,
+        step_id: str,
+        step_action: str,
+        end_time: float,
+        status: str,
+        extra_attrs: dict[str, Any],
+        agent_did: str | None = None,
+        session_id: str | None = None,
+    ) -> None:
+        """Complete an in-flight step span."""
+        key = (saga_id, step_id)
+        start_time = self._step_starts.pop(key, None)
+        if start_time is None:
+            # Step started before we subscribed, use end_time as fallback
+            start_time = end_time
+
+        self._record_span(
+            name=f"saga.step.{step_action or step_id}",
+            saga_id=saga_id,
+            step_id=step_id,
+            step_action=step_action,
+            start_time=start_time,
+            end_time=end_time,
+            status=status,
+            extra_attrs=extra_attrs,
+            agent_did=agent_did,
+            session_id=session_id,
+        )
+
+    def _record_span(
+        self,
+        name: str,
+        saga_id: str,
+        step_id: str,
+        step_action: str,
+        start_time: float,
+        end_time: float,
+        status: str,
+        extra_attrs: dict[str, Any] | None = None,
+        agent_did: str | None = None,
+        session_id: str | None = None,
+    ) -> None:
+        """Create a span record, buffer it, and forward to sink if attached."""
+        attrs: dict[str, Any] = {
+            "agent.saga.id": saga_id,
+            "agent.saga.step_id": step_id,
+            "agent.saga.step_action": step_action,
+            "agent.saga.state": status,
+        }
+        if agent_did:
+            attrs["agent.did"] = agent_did
+        if session_id:
+            attrs["session.id"] = session_id
+        if extra_attrs:
+            # Include select payload fields as span attributes
+            for key in ("error", "reason", "result"):
+                if key in extra_attrs:
+                    attrs[f"agent.saga.{key}"] = str(extra_attrs[key])
+
+        record = SagaSpanRecord(
+            name=name,
+            saga_id=saga_id,
+            step_id=step_id,
+            step_action=step_action,
+            start_time=start_time,
+            end_time=end_time,
+            status=status,
+            attributes=attrs,
+        )
+        self._completed_spans.append(record)
+
+        # Forward to sink if attached
+        if self._sink is not None:
+            self._sink.record_span(
+                name=record.name,
+                start_time=record.start_time,
+                end_time=record.end_time,
+                attributes=record.attributes,
+                status=record.status,
+            )

hypervisor/providers.py

@@ -0,0 +1,121 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Provider Discovery System for Agent Hypervisor
+
+Enables plug-and-play upgrades from Public Preview to Advanced implementations.
+"""
+
+from __future__ import annotations
+
+import logging
+from importlib.metadata import entry_points
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+PROVIDER_GROUPS = {
+    "ring_engine": "hypervisor.providers.ring_engine",
+    "liability": "hypervisor.providers.liability",
+    "saga_engine": "hypervisor.providers.saga_engine",
+    "breach_detector": "hypervisor.providers.breach_detector",
+    "session_manager": "hypervisor.providers.session_manager",
+    "audit_engine": "hypervisor.providers.audit_engine",
+}
+
+_provider_cache: dict[str, Any] = {}
+
+
+def _discover_provider(group: str) -> type | None:
+    """Discover an advanced provider via entry_points."""
+    if group in _provider_cache:
+        return _provider_cache[group]
+
+    try:
+        eps = entry_points(group=group)
+        if eps:
+            ep = next(iter(eps))
+            provider_cls = ep.load()
+            if not isinstance(provider_cls, type):
+                logger.warning(
+                    "Provider %s is not a class, skipping", ep.name
+                )
+            else:
+                _provider_cache[group] = provider_cls
+                logger.info("Advanced provider loaded: %s from %s", ep.name, ep.value)
+                return provider_cls
+    except Exception:
+        logger.debug("Provider discovery failed for %s", group, exc_info=True)
+
+    _provider_cache[group] = None
+    return None
+
+
+def get_ring_engine(**kwargs: Any):
+    """Get the best available execution ring engine.
+
+    Advanced: 4-ring privilege escalation with breach detection.
+    Community: Basic ring assignment with classifier.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["ring_engine"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from hypervisor.rings.enforcer import RingEnforcer
+    return RingEnforcer(**kwargs)
+
+
+def get_liability_engine(**kwargs: Any):
+    """Get the best available liability engine.
+
+    Advanced: Shapley-value fault attribution with vouch cascades.
+    Community: Basic vouching with linear slashing.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["liability"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from hypervisor.liability.engine import LiabilityEngine
+    return LiabilityEngine(**kwargs)
+
+
+def get_saga_engine(**kwargs: Any):
+    """Get the best available saga orchestration engine.
+
+    Advanced: Multi-pattern saga with parallel fan-out and escalation.
+    Community: Sequential saga with basic compensation.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["saga_engine"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from hypervisor.saga.engine import SagaOrchestrator
+    return SagaOrchestrator(**kwargs)
+
+
+def get_breach_detector(**kwargs: Any):
+    """Get the best available breach detector.
+
+    Advanced: Multi-signal breach detection with severity scoring.
+    Community: Basic threshold-based detection with safe defaults.
+    """
+    provider = _discover_provider(PROVIDER_GROUPS["breach_detector"])
+    if provider is not None:
+        return provider(**kwargs)
+
+    from hypervisor.rings.breach_detector import RingBreachDetector
+    return RingBreachDetector(**kwargs)
+
+
+def list_providers() -> dict[str, str]:
+    """List all provider slots and their current implementations."""
+    result = {}
+    for name, group in PROVIDER_GROUPS.items():
+        provider = _discover_provider(group)
+        result[name] = "advanced" if provider is not None else "community"
+    return result
+
+
+def clear_cache() -> None:
+    """Clear the provider cache."""
+    _provider_cache.clear()

hypervisor/reversibility/__init__.py

@@ -0,0 +1,3 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Reversibility subpackage."""

hypervisor/reversibility/registry.py

@@ -0,0 +1,108 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Reversibility Registry
+
+Maps every declared action to its Execute_API and Undo_API,
+populated during the IATP handshake.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from hypervisor.models import ActionDescriptor, ReversibilityLevel
+
+
+@dataclass
+class ReversibilityEntry:
+    """An entry in the reversibility registry."""
+
+    action_id: str
+    execute_api: str
+    undo_api: str | None
+    reversibility: ReversibilityLevel
+    undo_window_seconds: int
+    compensation_method: str | None
+    risk_weight: float
+    undo_api_healthy: bool = True
+    last_health_check: str | None = None
+
+
+class ReversibilityRegistry:
+    """
+    Session-scoped registry of action reversibility mappings.
+
+    Auto-populated from IATP Capability Manifests during handshake.
+    Provides lookup for the Saga orchestrator during rollback.
+    """
+
+    def __init__(self, session_id: str) -> None:
+        self.session_id = session_id
+        self._entries: dict[str, ReversibilityEntry] = {}
+
+    def register(self, action: ActionDescriptor) -> ReversibilityEntry:
+        """Register an action from a capability manifest."""
+        entry = ReversibilityEntry(
+            action_id=action.action_id,
+            execute_api=action.execute_api,
+            undo_api=action.undo_api,
+            reversibility=action.reversibility,
+            undo_window_seconds=action.undo_window_seconds,
+            compensation_method=action.compensation_method,
+            risk_weight=action.risk_weight,
+        )
+        self._entries[action.action_id] = entry
+        return entry
+
+    def register_from_manifest(self, actions: list[ActionDescriptor]) -> int:
+        """Register all actions from a manifest. Returns count registered."""
+        for action in actions:
+            self.register(action)
+        return len(actions)
+
+    def get(self, action_id: str) -> ReversibilityEntry | None:
+        """Look up an action's reversibility entry."""
+        return self._entries.get(action_id)
+
+    def get_undo_api(self, action_id: str) -> str | None:
+        """Get the Undo_API for an action, if any."""
+        entry = self._entries.get(action_id)
+        return entry.undo_api if entry else None
+
+    def is_reversible(self, action_id: str) -> bool:
+        """Check if an action has any reversibility."""
+        entry = self._entries.get(action_id)
+        if not entry:
+            return False
+        return entry.reversibility != ReversibilityLevel.NONE
+
+    def get_risk_weight(self, action_id: str) -> float:
+        """Get the risk weight ω for an action."""
+        entry = self._entries.get(action_id)
+        return entry.risk_weight if entry else ReversibilityLevel.NONE.default_risk_weight
+
+    def has_non_reversible_actions(self) -> bool:
+        """Check if any registered action is non-reversible."""
+        return any(
+            e.reversibility == ReversibilityLevel.NONE
+            for e in self._entries.values()
+        )
+
+    def mark_undo_unhealthy(self, action_id: str) -> None:
+        """Mark an Undo_API as unhealthy (failed health check)."""
+        entry = self._entries.get(action_id)
+        if entry:
+            entry.undo_api_healthy = False
+
+    @property
+    def entries(self) -> list[ReversibilityEntry]:
+        return list(self._entries.values())
+
+    @property
+    def non_reversible_actions(self) -> list[str]:
+        return [
+            e.action_id
+            for e in self._entries.values()
+            if e.reversibility == ReversibilityLevel.NONE
+        ]

hypervisor/rings/__init__.py

@@ -0,0 +1,21 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Execution rings subpackage — enforcement, classification, elevation, breach detection."""
+
+from hypervisor.rings.breach_detector import BreachEvent, BreachSeverity, RingBreachDetector
+from hypervisor.rings.elevation import (
+    ElevationDenialReason,
+    RingElevation,
+    RingElevationError,
+    RingElevationManager,
+)
+
+__all__ = [
+    "RingElevationManager",
+    "RingElevation",
+    "RingElevationError",
+    "ElevationDenialReason",
+    "RingBreachDetector",
+    "BreachEvent",
+    "BreachSeverity",
+]