agent_hypervisor 3.5.0__tar.gz → 3.7.0__tar.gz

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/.gitignore

@@ -69,6 +69,7 @@ bld/
 
 # Build results on 'Bin' directories
 **/[Bb]in/*
+!agent-governance-copilot-cli/bin/agt-copilot.mjs
 # Uncomment if you have tasks that rely on *.refresh files to move binaries
 # (https://github.com/github/gitignore/pull/3736)
 #!**/[Bb]in/*.refresh
@@ -465,3 +466,4 @@ _site/
 
 # Code Security Assessment artifacts
 .security-assessment/
+*.tgz

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent_hypervisor
-Version: 3.5.0
+Version: 3.7.0
 Summary: Public Preview — Agent Hypervisor: Runtime supervisor for multi-agent Shared Sessions with Execution Rings, Joint Liability, Saga Orchestration, and hash-chained audit trails
 Project-URL: Homepage, https://github.com/microsoft/agent-governance-toolkit
 Project-URL: Repository, https://github.com/microsoft/agent-governance-toolkit
@@ -35,7 +35,7 @@ Requires-Dist: web3<8.0,>=6.0.0; extra == 'blockchain'
 Provides-Extra: dev
 Requires-Dist: hypothesis<7.0,>=6.0.0; extra == 'dev'
 Requires-Dist: jsonschema<5.0,>=4.0.0; extra == 'dev'
-Requires-Dist: mypy<2.0,>=1.8.0; extra == 'dev'
+Requires-Dist: mypy<3.0,>=1.8.0; extra == 'dev'
 Requires-Dist: pytest-asyncio<2.0,>=0.23.0; extra == 'dev'
 Requires-Dist: pytest-cov<8.0,>=4.0.0; extra == 'dev'
 Requires-Dist: pytest<10.0,>=8.0.0; extra == 'dev'

agent_hypervisor-3.7.0/examples/requirements.txt

@@ -0,0 +1 @@
+agent-hypervisor>=3.6.0

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/notebooks/README.md

@@ -11,7 +11,8 @@ Interactive Jupyter notebooks for exploring the **agent-hypervisor** runtime.
 ## Quick Start
 
 ```bash
-# From the repository root
+# From the agent-hypervisor package root
+cd agent-governance-python/agent-hypervisor
 pip install -e ".[dev]" plotly nest-asyncio
 jupyter notebook notebooks/
 ```

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent_hypervisor"
-version = "3.5.0"
+version = "3.7.0"
 description = "Public Preview — Agent Hypervisor: Runtime supervisor for multi-agent Shared Sessions with Execution Rings, Joint Liability, Saga Orchestration, and hash-chained audit trails"
 readme = "README.md"
 license = {text = "MIT"}
@@ -58,7 +58,7 @@ dev = [
     "pytest-cov>=4.0.0,<8.0",
     "hypothesis>=6.0.0,<7.0",
     "ruff>=0.4.0,<1.0",
-    "mypy>=1.8.0,<2.0",
+    "mypy>=1.8.0,<3.0",
     "jsonschema>=4.0.0,<5.0",
 ]
 blockchain = [

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/src/hypervisor/api/server.py

@@ -180,19 +180,16 @@ async def get_stats() -> StatsResponse:
     """Get overall hypervisor statistics."""
     hv = _hv()
     bus = _bus()
-    total_participants = sum(
-        m.sso.participant_count for m in hv._sessions.values()
-    )
-    active_sagas = sum(
-        len(m.saga.active_sagas) for m in hv._sessions.values()
-    )
+    sessions = hv.sessions
+    total_participants = sum(m.sso.participant_count for m in sessions)
+    active_sagas = sum(len(m.saga.active_sagas) for m in sessions)
     return StatsResponse(
         version=__version__,
-        total_sessions=len(hv._sessions),
+        total_sessions=hv.session_count,
         active_sessions=len(hv.active_sessions),
         total_participants=total_participants,
         active_sagas=active_sagas,
-        total_vouches=len(hv.vouching._vouches),
+        total_vouches=hv.vouching.vouch_count,
         event_count=bus.event_count,
     )
 

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/src/hypervisor/core.py

@@ -306,6 +306,23 @@ class Hypervisor:
         return [self._sessions[sid] for sid in self._active_ids
                 if sid in self._sessions]
 
+    @property
+    def sessions(self) -> list[ManagedSession]:
+        """All managed sessions, including archived/terminating ones.
+
+        ``active_sessions`` filters via ``_active_ids``; this property
+        exposes the full registry for callers (admin APIs, monitoring,
+        stats) that need a count or iterator over every session the
+        Hypervisor is still tracking. Returns a snapshot list so callers
+        can iterate without holding any internal reference.
+        """
+        return list(self._sessions.values())
+
+    @property
+    def session_count(self) -> int:
+        """Total number of managed sessions, including archived/terminating."""
+        return len(self._sessions)
+
     def _get_session(self, session_id: str) -> ManagedSession:
         managed = self._sessions.get(session_id)
         if not managed:

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/src/hypervisor/liability/vouching.py

@@ -57,6 +57,11 @@ class VouchingEngine:
         self._vouches: dict[str, VouchRecord] = {}
         self.max_exposure = max_exposure or self.DEFAULT_MAX_EXPOSURE
 
+    @property
+    def vouch_count(self) -> int:
+        """Total number of sponsorship records (active + released)."""
+        return len(self._vouches)
+
     def vouch(
         self,
         voucher_did: str,

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/src/hypervisor/observability/event_bus.py

@@ -10,13 +10,21 @@ full replay debugging, post-mortem analysis, and real-time monitoring.
 
 from __future__ import annotations
 
+import threading
 import uuid
+from collections import deque
 from collections.abc import Callable
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from enum import Enum
 from typing import Any
 
+# Default cap for the in-memory event store. Hypervisor deployments run for
+# weeks; an unbounded list eventually OOMs. The cap is configurable via the
+# ``HypervisorEventBus(max_events=...)`` constructor; ``None`` opts back into
+# unbounded growth for tests or analysis tooling that needs full history.
+DEFAULT_MAX_EVENTS = 100_000
+
 
 class EventType(str, Enum):
     """Categorised hypervisor event types."""
@@ -119,34 +127,61 @@ class HypervisorEventBus:
     - Event count and statistics
     """
 
-    def __init__(self) -> None:
-        self._events: list[HypervisorEvent] = []
+    def __init__(self, max_events: int | None = DEFAULT_MAX_EVENTS) -> None:
+        """Create an event bus.
+
+        ``max_events`` caps the in-memory store. Each per-key index list
+        (by-type, by-session, by-agent) is independently capped to the
+        same value, so a single chatty session cannot starve the
+        history of other sessions. Pass ``None`` to disable the cap
+        (testing or full-replay tooling).
+        """
+        self._max_events = max_events
+        # `deque` with `maxlen` evicts the oldest entry on overflow in
+        # O(1), avoiding the OOM cliff of an unbounded `list`.
+        self._events: deque[HypervisorEvent] = deque(maxlen=max_events)
         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]] = {}
+        self._by_type: dict[EventType, deque[HypervisorEvent]] = {}
+        self._by_session: dict[str, deque[HypervisorEvent]] = {}
+        self._by_agent: dict[str, deque[HypervisorEvent]] = {}
+        # Use an RLock so a subscriber that re-enters the bus (e.g.
+        # emits an event in response to another event) doesn't deadlock.
+        self._lock = threading.RLock()
+
+    def _new_index_deque(self) -> deque[HypervisorEvent]:
+        return deque(maxlen=self._max_events)
 
     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, []):
+        with self._lock:
+            self._events.append(event)
+
+            self._by_type.setdefault(
+                event.event_type, self._new_index_deque()
+            ).append(event)
+
+            if event.session_id:
+                self._by_session.setdefault(
+                    event.session_id, self._new_index_deque()
+                ).append(event)
+
+            if event.agent_did:
+                self._by_agent.setdefault(
+                    event.agent_did, self._new_index_deque()
+                ).append(event)
+
+            # Snapshot subscriber lists while holding the lock so a
+            # subscriber that mutates the registry mid-notify doesn't
+            # invalidate iteration.
+            type_subs = list(self._subscribers.get(event.event_type, ()))
+            wildcard_subs = list(self._subscribers.get(None, ()))
+
+        # Invoke handlers outside the lock so a slow subscriber can't
+        # serialize the entire bus or, worse, deadlock with a caller
+        # that also holds an external lock.
+        for handler in type_subs:
             handler(event)
-
-        # Notify wildcard subscribers
-        for handler in self._subscribers.get(None, []):
+        for handler in wildcard_subs:
             handler(event)
 
     def subscribe(
@@ -155,20 +190,25 @@ class HypervisorEventBus:
         handler: EventHandler | None = None,
     ) -> None:
         """Subscribe to events. Use event_type=None for all events."""
-        if handler:
+        if not handler:
+            return
+        with self._lock:
             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, []))
+        with self._lock:
+            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, []))
+        with self._lock:
+            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, []))
+        with self._lock:
+            return list(self._by_agent.get(agent_did, ()))
 
     def query_by_time_range(
         self,
@@ -178,7 +218,8 @@ class HypervisorEventBus:
         """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]
+        with self._lock:
+            return [e for e in self._events if start <= e.timestamp <= end]
 
     def query(
         self,
@@ -188,7 +229,8 @@ class HypervisorEventBus:
         limit: int | None = None,
     ) -> list[HypervisorEvent]:
         """Flexible query with multiple filters."""
-        results = self._events
+        with self._lock:
+            results: list[HypervisorEvent] = list(self._events)
 
         if event_type is not None:
             results = [e for e in results if e.event_type == event_type]
@@ -204,19 +246,35 @@ class HypervisorEventBus:
 
     @property
     def event_count(self) -> int:
-        return len(self._events)
+        with self._lock:
+            return len(self._events)
 
     @property
     def all_events(self) -> list[HypervisorEvent]:
-        return list(self._events)
+        with self._lock:
+            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()
+        with self._lock:
+            return {t.value: len(evts) for t, evts in self._by_type.items()}
+
+    def _clear(self) -> None:
+        """Clear all events. **Test-only — do not call in production.**
+
+        The event bus is wired into the hypervisor as a long-lived,
+        process-singleton-shaped collaborator (see
+        ``hypervisor.api.server._event_bus``): production calls would
+        wipe the audit trail of every running session at once.
+
+        The leading underscore makes the test-only contract visible at
+        every call site. The method is kept on the class (rather than
+        moved to a test helper) because some tests construct a fresh
+        bus and then exercise the clear path itself; it just shouldn't
+        be reached from non-test code.
+        """
+        with self._lock:
+            self._events.clear()
+            self._by_type.clear()
+            self._by_session.clear()
+            self._by_agent.clear()

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/src/hypervisor/providers.py

@@ -69,27 +69,34 @@ 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.
+    Community: ``LiabilityMatrix`` from ``hypervisor.liability``.
     """
     provider = _discover_provider(PROVIDER_GROUPS["liability"])
     if provider is not None:
         return provider(**kwargs)
 
-    from hypervisor.liability.engine import LiabilityEngine
-    return LiabilityEngine(**kwargs)
+    # Community fallback. The previous import targeted
+    # ``hypervisor.liability.engine.LiabilityEngine`` which does not
+    # exist in this tree; ``LiabilityMatrix`` is the real public-
+    # edition entry point.
+    from hypervisor.liability import LiabilityMatrix
+    return LiabilityMatrix(**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.
+    Community: ``SagaOrchestrator`` from ``hypervisor.saga.orchestrator``.
     """
     provider = _discover_provider(PROVIDER_GROUPS["saga_engine"])
     if provider is not None:
         return provider(**kwargs)
 
-    from hypervisor.saga.engine import SagaOrchestrator
+    # Community fallback. The previous import targeted
+    # ``hypervisor.saga.engine.SagaOrchestrator`` which does not exist
+    # in this tree; the real module is ``hypervisor.saga.orchestrator``.
+    from hypervisor.saga.orchestrator import SagaOrchestrator
     return SagaOrchestrator(**kwargs)
 
 

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/src/hypervisor/rings/__init__.py

@@ -4,18 +4,34 @@
 
 from hypervisor.rings.breach_detector import BreachEvent, BreachSeverity, RingBreachDetector
 from hypervisor.rings.elevation import (
+    ChildRegistration,
     ElevationDenialReason,
+    ELEVATION_TRUST_THRESHOLDS,
     RingElevation,
     RingElevationError,
     RingElevationManager,
 )
+from hypervisor.rings.enforcer import (
+    ResourceConstraints,
+    ResourceType,
+    RING_CONSTRAINTS,
+    RingCheckResult,
+    RingEnforcer,
+)
 
 __all__ = [
-    "RingElevationManager",
-    "RingElevation",
-    "RingElevationError",
+    "ChildRegistration",
     "ElevationDenialReason",
+    "ELEVATION_TRUST_THRESHOLDS",
+    "ResourceConstraints",
+    "ResourceType",
+    "RING_CONSTRAINTS",
     "RingBreachDetector",
+    "RingCheckResult",
+    "RingElevation",
+    "RingElevationError",
+    "RingElevationManager",
+    "RingEnforcer",
     "BreachEvent",
     "BreachSeverity",
 ]

{agent_hypervisor-3.5.0 → agent_hypervisor-3.7.0}/src/hypervisor/rings/breach_detector.py

@@ -127,8 +127,24 @@ class RingBreachDetector:
             window.popleft()
 
         # --- 3. Compute actual rate (calls / second) ---
+        # Dividing by the full ``window_seconds`` underestimates the rate
+        # when the window has just begun — 10 calls in the first 2s of a
+        # 60s window would read as 0.16/s instead of 5/s, missing real
+        # bursts. Use the shorter of (window, time_since_first_event)
+        # as the denominator so early bursts surface accurately. A single
+        # call has no rate to measure (need ≥2 samples for an interval),
+        # so fall back to the conservative full-window divisor.
         call_count = len(window)
-        actual_rate = call_count / self.window_seconds if self.window_seconds > 0 else 0.0
+        if self.window_seconds <= 0 or call_count == 0:
+            actual_rate = 0.0
+        elif call_count < 2:
+            actual_rate = call_count / self.window_seconds
+        else:
+            time_since_first = max(now - window[0], 0.0)
+            # Floor at 1ms: prevents divide-by-zero for ultra-tight
+            # bursts while still surfacing them with a high rate.
+            denominator = max(min(self.window_seconds, time_since_first), 1e-3)
+            actual_rate = call_count / denominator
 
         # --- 4. Ring-distance amplifier ---
         #   Upward calls (low value = higher privilege) are escalations.