agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/observability/event_bus.py

@@ -0,0 +1,222 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Structured event bus for the Agent Hypervisor.
+
+Every ring transition, liability event, saga step, session write, and
+security action emits a typed event to an append-only store. Enables
+full replay debugging, post-mortem analysis, and real-time monitoring.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+
+class EventType(str, Enum):
+    """Categorised hypervisor event types."""
+
+    # Session lifecycle
+    SESSION_CREATED = "session.created"
+    SESSION_JOINED = "session.joined"
+    SESSION_ACTIVATED = "session.activated"
+    SESSION_TERMINATED = "session.terminated"
+    SESSION_ARCHIVED = "session.archived"
+
+    # Ring transitions
+    RING_ASSIGNED = "ring.assigned"
+    RING_ELEVATED = "ring.elevated"
+    RING_DEMOTED = "ring.demoted"
+    RING_ELEVATION_EXPIRED = "ring.elevation_expired"
+    RING_BREACH_DETECTED = "ring.breach_detected"
+
+    # Liability
+    VOUCH_CREATED = "liability.vouch_created"
+    VOUCH_RELEASED = "liability.vouch_released"
+    SLASH_EXECUTED = "liability.slash_executed"
+    FAULT_ATTRIBUTED = "liability.fault_attributed"
+    QUARANTINE_ENTERED = "liability.quarantine_entered"
+    QUARANTINE_RELEASED = "liability.quarantine_released"
+
+    # Saga
+    SAGA_CREATED = "saga.created"
+    SAGA_STEP_STARTED = "saga.step_started"
+    SAGA_STEP_COMMITTED = "saga.step_committed"
+    SAGA_STEP_FAILED = "saga.step_failed"
+    SAGA_COMPENSATING = "saga.compensating"
+    SAGA_COMPLETED = "saga.completed"
+    SAGA_ESCALATED = "saga.escalated"
+    SAGA_FANOUT_STARTED = "saga.fanout_started"
+    SAGA_FANOUT_RESOLVED = "saga.fanout_resolved"
+    SAGA_CHECKPOINT_SAVED = "saga.checkpoint_saved"
+
+    # VFS / Session writes
+    VFS_WRITE = "vfs.write"
+    VFS_DELETE = "vfs.delete"
+    VFS_SNAPSHOT = "vfs.snapshot"
+    VFS_RESTORE = "vfs.restore"
+    VFS_CONFLICT = "vfs.conflict"
+
+    # Security
+    RATE_LIMITED = "security.rate_limited"
+    AGENT_KILLED = "security.agent_killed"
+    SAGA_HANDOFF = "security.saga_handoff"
+    IDENTITY_VERIFIED = "security.identity_verified"
+
+    # Audit
+    AUDIT_DELTA_CAPTURED = "audit.delta_captured"
+    AUDIT_COMMITTED = "audit.committed"
+    AUDIT_GC_COLLECTED = "audit.gc_collected"
+
+    # Verification
+    BEHAVIOR_DRIFT = "verification.behavior_drift"
+    HISTORY_VERIFIED = "verification.history_verified"
+
+
+@dataclass(frozen=True)
+class HypervisorEvent:
+    """An immutable, structured event emitted by the hypervisor."""
+
+    event_id: str = field(default_factory=lambda: uuid.uuid4().hex[:16])
+    event_type: EventType = EventType.SESSION_CREATED
+    timestamp: datetime = field(default_factory=lambda: datetime.now(UTC))
+    session_id: str | None = None
+    agent_did: str | None = None
+    causal_trace_id: str | None = None
+    parent_event_id: str | None = None
+    payload: dict[str, Any] = field(default_factory=dict)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "event_id": self.event_id,
+            "event_type": self.event_type.value,
+            "timestamp": self.timestamp.isoformat(),
+            "session_id": self.session_id,
+            "agent_did": self.agent_did,
+            "causal_trace_id": self.causal_trace_id,
+            "parent_event_id": self.parent_event_id,
+            "payload": self.payload,
+        }
+
+
+# Type alias for event subscribers
+EventHandler = Callable[[HypervisorEvent], None]
+
+
+class HypervisorEventBus:
+    """
+    Append-only structured event store with pub/sub.
+
+    All hypervisor components emit events here. Supports:
+    - Append-only storage (immutable event log)
+    - Query by type, agent, session, time range
+    - Subscribe to specific event types
+    - Event count and statistics
+    """
+
+    def __init__(self) -> None:
+        self._events: list[HypervisorEvent] = []
+        self._subscribers: dict[EventType | None, list[EventHandler]] = {}
+        self._by_type: dict[EventType, list[HypervisorEvent]] = {}
+        self._by_session: dict[str, list[HypervisorEvent]] = {}
+        self._by_agent: dict[str, list[HypervisorEvent]] = {}
+
+    def emit(self, event: HypervisorEvent) -> None:
+        """Append an event and notify subscribers."""
+        self._events.append(event)
+
+        # Index by type
+        self._by_type.setdefault(event.event_type, []).append(event)
+
+        # Index by session
+        if event.session_id:
+            self._by_session.setdefault(event.session_id, []).append(event)
+
+        # Index by agent
+        if event.agent_did:
+            self._by_agent.setdefault(event.agent_did, []).append(event)
+
+        # Notify type-specific subscribers
+        for handler in self._subscribers.get(event.event_type, []):
+            handler(event)
+
+        # Notify wildcard subscribers
+        for handler in self._subscribers.get(None, []):
+            handler(event)
+
+    def subscribe(
+        self,
+        event_type: EventType | None = None,
+        handler: EventHandler | None = None,
+    ) -> None:
+        """Subscribe to events. Use event_type=None for all events."""
+        if handler:
+            self._subscribers.setdefault(event_type, []).append(handler)
+
+    def query_by_type(self, event_type: EventType) -> list[HypervisorEvent]:
+        """Get all events of a specific type."""
+        return list(self._by_type.get(event_type, []))
+
+    def query_by_session(self, session_id: str) -> list[HypervisorEvent]:
+        """Get all events for a specific session."""
+        return list(self._by_session.get(session_id, []))
+
+    def query_by_agent(self, agent_did: str) -> list[HypervisorEvent]:
+        """Get all events involving a specific agent."""
+        return list(self._by_agent.get(agent_did, []))
+
+    def query_by_time_range(
+        self,
+        start: datetime,
+        end: datetime | None = None,
+    ) -> list[HypervisorEvent]:
+        """Get events within a time range."""
+        if end is None:
+            end = datetime.now(UTC)
+        return [e for e in self._events if start <= e.timestamp <= end]
+
+    def query(
+        self,
+        event_type: EventType | None = None,
+        session_id: str | None = None,
+        agent_did: str | None = None,
+        limit: int | None = None,
+    ) -> list[HypervisorEvent]:
+        """Flexible query with multiple filters."""
+        results = self._events
+
+        if event_type is not None:
+            results = [e for e in results if e.event_type == event_type]
+        if session_id is not None:
+            results = [e for e in results if e.session_id == session_id]
+        if agent_did is not None:
+            results = [e for e in results if e.agent_did == agent_did]
+
+        if limit is not None:
+            results = results[-limit:]
+
+        return results
+
+    @property
+    def event_count(self) -> int:
+        return len(self._events)
+
+    @property
+    def all_events(self) -> list[HypervisorEvent]:
+        return list(self._events)
+
+    def type_counts(self) -> dict[str, int]:
+        """Return count of events per type."""
+        return {t.value: len(evts) for t, evts in self._by_type.items()}
+
+    def clear(self) -> None:
+        """Clear all events (for testing)."""
+        self._events.clear()
+        self._by_type.clear()
+        self._by_session.clear()
+        self._by_agent.clear()

hypervisor/observability/prometheus_collector.py

@@ -0,0 +1,248 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Prometheus metrics collector for Hypervisor ring transitions.
+
+Subscribes to the HypervisorEventBus and maintains in-memory counters
+for ring-related events (transitions, breaches, elevations). Metrics
+follow the ``agent_hypervisor_ring_*`` prefix convention.
+
+No external dependencies — works standalone or exports to the
+``agent-sre`` PrometheusExporter via dependency injection.
+
+Usage::
+
+    from hypervisor.observability import RingMetricsCollector, HypervisorEventBus
+
+    bus = HypervisorEventBus()
+    collector = RingMetricsCollector(bus)
+
+    # ... hypervisor operates, ring events flow through the bus ...
+
+    snapshot = collector.collect()
+    # {"agent_hypervisor_ring_transitions_total": {"ring.assigned": 5, ...}, ...}
+
+    # Optional: export to agent-sre PrometheusExporter
+    from agent_sre.integrations.prometheus import PrometheusExporter
+    prom = PrometheusExporter()
+    collector.export_to_prometheus(prom)
+"""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict
+from typing import Any, Protocol
+
+from hypervisor.observability.event_bus import EventType, HypervisorEvent, HypervisorEventBus
+
+# Ring event types that represent transitions
+_RING_TRANSITION_EVENTS = frozenset({
+    EventType.RING_ASSIGNED,
+    EventType.RING_ELEVATED,
+    EventType.RING_DEMOTED,
+    EventType.RING_ELEVATION_EXPIRED,
+})
+
+_RING_BREACH_EVENTS = frozenset({
+    EventType.RING_BREACH_DETECTED,
+})
+
+_ALL_RING_EVENTS = _RING_TRANSITION_EVENTS | _RING_BREACH_EVENTS
+
+
+class PrometheusExporterProtocol(Protocol):
+    """Protocol for Prometheus exporters — avoids hard dep on agent-sre."""
+
+    def set_gauge(
+        self, name: str, value: float,
+        labels: dict[str, str] | None = None,
+        help_text: str = "",
+    ) -> None: ...
+
+    def inc_counter(
+        self, name: str, value: float = 1.0,
+        labels: dict[str, str] | None = None,
+        help_text: str = "",
+    ) -> None: ...
+
+
+# ---------------------------------------------------------------------------
+# Metric name constants
+# ---------------------------------------------------------------------------
+
+METRIC_RING_TRANSITIONS_TOTAL = "agent_hypervisor_ring_transitions_total"
+METRIC_RING_BREACHES_TOTAL = "agent_hypervisor_ring_breaches_total"
+METRIC_RING_CURRENT = "agent_hypervisor_ring_current"
+METRIC_RING_ELEVATION_DURATION = "agent_hypervisor_ring_elevation_duration_seconds"
+
+
+class RingMetricsCollector:
+    """Collects Prometheus-compatible metrics from hypervisor ring events.
+
+    Subscribes to the ``HypervisorEventBus`` for ring transition and breach
+    events. Maintains in-memory counters and gauges that can be exported
+    to any :class:`PrometheusExporterProtocol`-compatible exporter.
+
+    Attributes:
+        _bus: The event bus this collector is subscribed to.
+        _transition_counts: Counter per ``(event_type, agent_did, session_id)``.
+        _breach_counts: Counter per ``(agent_did, session_id)``.
+        _current_rings: Current ring gauge per ``agent_did``.
+        _elevation_start: Timestamp when an agent entered elevated state.
+        _elevation_durations: Last known elevation duration per ``agent_did``.
+    """
+
+    def __init__(self, bus: HypervisorEventBus) -> None:
+        self._bus = bus
+
+        # Counters: (event_type_value, agent_did, session_id) -> count
+        self._transition_counts: dict[tuple[str, str, str], int] = defaultdict(int)
+
+        # Breach counter: (agent_did, session_id) -> count
+        self._breach_counts: dict[tuple[str, str], int] = defaultdict(int)
+
+        # Current ring per agent: agent_did -> ring_value (int)
+        self._current_rings: dict[str, int] = {}
+
+        # Elevation tracking: agent_did -> start timestamp
+        self._elevation_start: dict[str, float] = {}
+
+        # Last elevation duration: agent_did -> seconds (float)
+        self._elevation_durations: dict[str, float] = {}
+
+        # Total events processed
+        self._events_processed: int = 0
+
+        # Subscribe to all ring events
+        for event_type in _ALL_RING_EVENTS:
+            bus.subscribe(event_type=event_type, handler=self._handle_event)
+
+    def _handle_event(self, event: HypervisorEvent) -> None:
+        """Process a ring-related event from the bus."""
+        agent_did = event.agent_did or "unknown"
+        session_id = event.session_id or "unknown"
+        self._events_processed += 1
+
+        if event.event_type in _RING_TRANSITION_EVENTS:
+            key = (event.event_type.value, agent_did, session_id)
+            self._transition_counts[key] += 1
+
+            # Track current ring from payload
+            to_ring = event.payload.get("to_ring") or event.payload.get("ring")
+            if to_ring is not None:
+                self._current_rings[agent_did] = (
+                    to_ring if isinstance(to_ring, int) else int(to_ring)
+                )
+
+            # Track elevation timing
+            if event.event_type == EventType.RING_ELEVATED:
+                self._elevation_start[agent_did] = event.timestamp.timestamp()
+            elif event.event_type in (
+                EventType.RING_DEMOTED,
+                EventType.RING_ELEVATION_EXPIRED,
+            ):
+                start = self._elevation_start.pop(agent_did, None)
+                if start is not None:
+                    self._elevation_durations[agent_did] = (
+                        event.timestamp.timestamp() - start
+                    )
+
+        elif event.event_type in _RING_BREACH_EVENTS:
+            self._breach_counts[(agent_did, session_id)] += 1
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def collect(self) -> dict[str, Any]:
+        """Return a snapshot of all metrics as a framework-agnostic dict.
+
+        Returns:
+            Dictionary with metric names as keys and nested dicts/values:
+
+            - ``agent_hypervisor_ring_transitions_total``:
+              ``{(event_type, agent, session): count}``
+            - ``agent_hypervisor_ring_breaches_total``:
+              ``{(agent, session): count}``
+            - ``agent_hypervisor_ring_current``:
+              ``{agent: ring_value}``
+            - ``agent_hypervisor_ring_elevation_duration_seconds``:
+              ``{agent: seconds}``
+        """
+        return {
+            METRIC_RING_TRANSITIONS_TOTAL: dict(self._transition_counts),
+            METRIC_RING_BREACHES_TOTAL: dict(self._breach_counts),
+            METRIC_RING_CURRENT: dict(self._current_rings),
+            METRIC_RING_ELEVATION_DURATION: dict(self._elevation_durations),
+            "events_processed": self._events_processed,
+        }
+
+    def export_to_prometheus(self, exporter: PrometheusExporterProtocol) -> None:
+        """Write all current metrics into a Prometheus-compatible exporter.
+
+        Args:
+            exporter: Any object implementing :class:`PrometheusExporterProtocol`
+                (e.g. ``agent_sre.integrations.prometheus.PrometheusExporter``).
+        """
+        # Transition counters
+        for (event_type, agent_did, session_id), count in self._transition_counts.items():
+            exporter.inc_counter(
+                METRIC_RING_TRANSITIONS_TOTAL,
+                float(count),
+                labels={
+                    "event_type": event_type,
+                    "agent_did": agent_did,
+                    "session_id": session_id,
+                },
+                help_text="Total ring transition events by type",
+            )
+
+        # Breach counters
+        for (agent_did, session_id), count in self._breach_counts.items():
+            exporter.inc_counter(
+                METRIC_RING_BREACHES_TOTAL,
+                float(count),
+                labels={
+                    "agent_did": agent_did,
+                    "session_id": session_id,
+                },
+                help_text="Total ring breach events detected",
+            )
+
+        # Current ring gauge
+        for agent_did, ring_value in self._current_rings.items():
+            exporter.set_gauge(
+                METRIC_RING_CURRENT,
+                float(ring_value),
+                labels={"agent_did": agent_did},
+                help_text="Current execution ring for each agent (0=root, 3=sandbox)",
+            )
+
+        # Elevation duration gauge
+        for agent_did, duration in self._elevation_durations.items():
+            exporter.set_gauge(
+                METRIC_RING_ELEVATION_DURATION,
+                duration,
+                labels={"agent_did": agent_did},
+                help_text="Duration of the last ring elevation in seconds",
+            )
+
+        # Also export any currently-active elevations
+        now = time.time()
+        for agent_did, start_ts in self._elevation_start.items():
+            exporter.set_gauge(
+                METRIC_RING_ELEVATION_DURATION,
+                now - start_ts,
+                labels={"agent_did": agent_did},
+                help_text="Duration of the last ring elevation in seconds",
+            )
+
+    def reset(self) -> None:
+        """Reset all counters (for testing)."""
+        self._transition_counts.clear()
+        self._breach_counts.clear()
+        self._current_rings.clear()
+        self._elevation_start.clear()
+        self._elevation_durations.clear()
+        self._events_processed = 0