agent_hypervisor 3.1.0__py3-none-any.whl

hypervisor/security/rate_limiter.py

@@ -0,0 +1,190 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""Runtime-layer per-agent/per-ring rate limiting.
+
+This module enforces token-bucket limits per agent, session, and execution ring
+inside the hypervisor runtime layer.
+
+See also:
+    - agent_os.integrations.rate_limiter: tool-call policy limits in Agent OS.
+    - agentmesh.services.rate_limiter: service/proxy-level limits in Agent Mesh.
+    - agentmesh.services.rate_limit_middleware: HTTP edge middleware in Agent Mesh.
+    - agent_os.policies.rate_limiting: shared token-bucket primitives.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+
+from hypervisor.constants import (
+    RATE_LIMIT_FALLBACK,
+    RATE_LIMIT_RING_0,
+    RATE_LIMIT_RING_1,
+    RATE_LIMIT_RING_2,
+    RATE_LIMIT_RING_3,
+)
+from hypervisor.models import ExecutionRing
+
+
+class RateLimitExceeded(Exception):
+    """Raised when an agent exceeds their rate limit."""
+
+
+@dataclass
+class TokenBucket:
+    """A token bucket for rate limiting."""
+
+    capacity: float
+    tokens: float
+    refill_rate: float  # tokens per second
+    last_refill: datetime = field(default_factory=lambda: datetime.now(UTC))
+
+    def consume(self, tokens: float = 1.0) -> bool:
+        """Try to consume tokens. Returns True if successful."""
+        self._refill()
+        if self.tokens >= tokens:
+            self.tokens -= tokens
+            return True
+        return False
+
+    def _refill(self) -> None:
+        """Refill tokens based on elapsed time."""
+        now = datetime.now(UTC)
+        elapsed = (now - self.last_refill).total_seconds()
+        self.tokens = min(self.capacity, self.tokens + elapsed * self.refill_rate)
+        self.last_refill = now
+
+    @property
+    def available(self) -> float:
+        self._refill()
+        return self.tokens
+
+
+# Default rate limits per ring (requests per second, burst capacity)
+DEFAULT_RING_LIMITS: dict[ExecutionRing, tuple[float, float]] = {
+    ExecutionRing.RING_0_ROOT: RATE_LIMIT_RING_0,
+    ExecutionRing.RING_1_PRIVILEGED: RATE_LIMIT_RING_1,
+    ExecutionRing.RING_2_STANDARD: RATE_LIMIT_RING_2,
+    ExecutionRing.RING_3_SANDBOX: RATE_LIMIT_RING_3,
+}
+
+
+@dataclass
+class RateLimitStats:
+    """Statistics for an agent's rate limiting."""
+
+    agent_did: str
+    ring: ExecutionRing
+    total_requests: int = 0
+    rejected_requests: int = 0
+    tokens_available: float = 0.0
+    capacity: float = 0.0
+
+
+class AgentRateLimiter:
+    """
+    Rate limiting per agent per ring using token buckets.
+
+    Higher-privilege rings get more generous limits. When an agent
+    is promoted/demoted, their bucket is recreated with new limits.
+    """
+
+    def __init__(
+        self,
+        ring_limits: dict[ExecutionRing, tuple[float, float]] | None = None,
+    ) -> None:
+        self._limits = ring_limits or dict(DEFAULT_RING_LIMITS)
+        # (agent_did, session_id) -> TokenBucket
+        self._buckets: dict[str, TokenBucket] = {}
+        self._stats: dict[str, RateLimitStats] = {}
+
+    def check(
+        self,
+        agent_did: str,
+        session_id: str,
+        ring: ExecutionRing,
+        cost: float = 1.0,
+    ) -> bool:
+        """
+        Check if an agent can make a request.
+
+        Returns True if allowed, raises RateLimitExceeded if not.
+        """
+        key = f"{agent_did}:{session_id}"
+        bucket = self._get_or_create_bucket(key, ring)
+
+        # Track stats
+        stats = self._stats.setdefault(
+            key,
+            RateLimitStats(agent_did=agent_did, ring=ring),
+        )
+        stats.total_requests += 1
+
+        if not bucket.consume(cost):
+            stats.rejected_requests += 1
+            raise RateLimitExceeded(
+                f"Agent {agent_did} exceeded rate limit for ring "
+                f"{ring.value} ({stats.rejected_requests} rejections)"
+            )
+        return True
+
+    def try_check(
+        self,
+        agent_did: str,
+        session_id: str,
+        ring: ExecutionRing,
+        cost: float = 1.0,
+    ) -> bool:
+        """Like check(), but returns False instead of raising."""
+        try:
+            return self.check(agent_did, session_id, ring, cost)
+        except RateLimitExceeded:
+            return False
+
+    def update_ring(
+        self,
+        agent_did: str,
+        session_id: str,
+        new_ring: ExecutionRing,
+    ) -> None:
+        """Update an agent's rate limit when their ring changes."""
+        key = f"{agent_did}:{session_id}"
+        rate, capacity = self._limits.get(
+            new_ring, RATE_LIMIT_FALLBACK
+        )
+        self._buckets[key] = TokenBucket(
+            capacity=capacity,
+            tokens=capacity,  # Start full
+            refill_rate=rate,
+        )
+        if key in self._stats:
+            self._stats[key].ring = new_ring
+
+    def get_stats(self, agent_did: str, session_id: str) -> RateLimitStats | None:
+        """Get rate limit stats for an agent."""
+        key = f"{agent_did}:{session_id}"
+        stats = self._stats.get(key)
+        if stats:
+            bucket = self._buckets.get(key)
+            if bucket:
+                stats.tokens_available = bucket.available
+                stats.capacity = bucket.capacity
+        return stats
+
+    def _get_or_create_bucket(
+        self, key: str, ring: ExecutionRing
+    ) -> TokenBucket:
+        if key not in self._buckets:
+            rate, capacity = self._limits.get(ring, RATE_LIMIT_FALLBACK)
+            self._buckets[key] = TokenBucket(
+                capacity=capacity,
+                tokens=capacity,
+                refill_rate=rate,
+            )
+        return self._buckets[key]
+
+    @property
+    def tracked_agents(self) -> int:
+        return len(self._buckets)

hypervisor/session/__init__.py

@@ -0,0 +1,194 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Shared Session Object — lifecycle manager for multi-agent sessions."""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime, timezone
+from typing import Any, Optional
+
+from hypervisor.models import (
+    ConsistencyMode,
+    ExecutionRing,
+    SessionConfig,
+    SessionParticipant,
+    SessionState,
+)
+from hypervisor.session.sso import SessionVFS
+
+
+class SharedSessionObject:
+    """
+    Encapsulates a multi-agent interaction.
+
+    Every Shared Session has:
+    - SessionID: UUID bound to a DID
+    - ConsistencyMode: Strong (consensus) or Eventual (gossip)
+    - StateSubstrate: A VFS representing the shared world
+    - LiabilityMatrix: Registry of who sponsors for whom
+
+    Lifecycle: created → handshaking → active → terminating → archived
+    """
+
+    def __init__(
+        self,
+        config: SessionConfig,
+        creator_did: str,
+        session_id: str | None = None,
+    ):
+        self.session_id = session_id or f"session:{uuid.uuid4()}"
+        self.creator_did = creator_did
+        self.config = config
+        self.state = SessionState.CREATED
+        self.consistency_mode = config.consistency_mode
+
+        # Participants
+        self._participants: dict[str, SessionParticipant] = {}
+
+        # VFS state substrate (namespace for this session)
+        self.vfs_namespace = f"/sessions/{self.session_id}"
+        self.vfs = SessionVFS(self.session_id, namespace=self.vfs_namespace)
+        self._vfs_snapshots: dict[str, Any] = {}
+
+        # Timestamps
+        self.created_at = datetime.now(UTC)
+        self.terminated_at: datetime | None = None
+
+    @property
+    def participants(self) -> list[SessionParticipant]:
+        """Active participants in this session."""
+        return [p for p in self._participants.values() if p.is_active]
+
+    @property
+    def participant_count(self) -> int:
+        # Avoid building a filtered list just to count
+        return sum(1 for p in self._participants.values() if p.is_active)
+
+    def _assert_state(self, *allowed: SessionState) -> None:
+        if self.state not in allowed:
+            raise SessionLifecycleError(
+                f"Operation not allowed in state {self.state.value}. "
+                f"Allowed: {[s.value for s in allowed]}"
+            )
+
+    def begin_handshake(self) -> None:
+        """Transition to handshaking phase."""
+        self._assert_state(SessionState.CREATED)
+        self.state = SessionState.HANDSHAKING
+
+    def activate(self) -> None:
+        """Transition to active execution phase."""
+        self._assert_state(SessionState.HANDSHAKING)
+        if not self._participants:
+            raise SessionLifecycleError("Cannot activate session with no participants")
+        self.state = SessionState.ACTIVE
+
+    def join(
+        self,
+        agent_did: str,
+        sigma_raw: float = 0.0,
+        eff_score: float = 0.0,
+        ring: ExecutionRing = ExecutionRing.RING_3_SANDBOX,
+    ) -> SessionParticipant:
+        """Add an agent to this session."""
+        self._assert_state(SessionState.HANDSHAKING, SessionState.ACTIVE)
+
+        if agent_did in self._participants:
+            raise SessionParticipantError(f"Agent {agent_did} already in session")
+        if self.participant_count >= self.config.max_participants:
+            raise SessionParticipantError(
+                f"Session at capacity ({self.config.max_participants})"
+            )
+        if eff_score < self.config.min_eff_score and ring != ExecutionRing.RING_3_SANDBOX:
+            raise SessionParticipantError(
+                f"eff_score {eff_score:.2f} below minimum {self.config.min_eff_score:.2f}"
+            )
+
+        participant = SessionParticipant(
+            agent_did=agent_did,
+            ring=ring,
+            sigma_raw=sigma_raw,
+            eff_score=eff_score,
+        )
+        self._participants[agent_did] = participant
+        return participant
+
+    def leave(self, agent_did: str) -> None:
+        """Remove an agent from this session."""
+        if agent_did not in self._participants:
+            raise SessionParticipantError(f"Agent {agent_did} not in session")
+        self._participants[agent_did].is_active = False
+
+    def get_participant(self, agent_did: str) -> SessionParticipant:
+        """Get a participant by DID."""
+        if agent_did not in self._participants:
+            raise SessionParticipantError(f"Agent {agent_did} not in session")
+        return self._participants[agent_did]
+
+    def update_ring(self, agent_did: str, new_ring: ExecutionRing) -> None:
+        """Update an agent's ring level (escalation or demotion)."""
+        participant = self.get_participant(agent_did)
+        participant.ring = new_ring
+
+    def force_consistency_mode(self, mode: ConsistencyMode) -> None:
+        """Force a consistency mode (e.g., when non-reversible actions are detected)."""
+        self.consistency_mode = mode
+
+    def terminate(self) -> None:
+        """Begin session termination."""
+        self._assert_state(SessionState.ACTIVE, SessionState.HANDSHAKING)
+        self.state = SessionState.TERMINATING
+        self.terminated_at = datetime.now(UTC)
+
+    def archive(self) -> None:
+        """Archive the session after audit commitment."""
+        self._assert_state(SessionState.TERMINATING)
+        self.state = SessionState.ARCHIVED
+
+    def create_vfs_snapshot(self, snapshot_id: str | None = None) -> str:
+        """Create a VFS state snapshot for rollback.
+
+        Captures both VFS file state (snapshot) and participant metadata.
+        """
+        self._assert_state(SessionState.ACTIVE)
+        # Snapshot the VFS file state
+        sid = self.vfs.create_snapshot(snapshot_id)
+        # Also snapshot participant metadata for full restore
+        self._vfs_snapshots[sid] = {
+            "created_at": datetime.now(UTC).isoformat(),
+            "participant_states": {
+                did: {"ring": p.ring.value, "eff_score": p.eff_score}
+                for did, p in self._participants.items()
+            },
+        }
+        return sid
+
+    def restore_vfs_snapshot(
+        self, snapshot_id: str, agent_did: str
+    ) -> None:
+        """Restore VFS to a previous snapshot.
+
+        Args:
+            snapshot_id: ID returned by create_vfs_snapshot.
+            agent_did: Agent requesting the restore (recorded in audit log).
+        """
+        self._assert_state(SessionState.ACTIVE)
+        self.vfs.restore_snapshot(snapshot_id, agent_did)
+
+    def __repr__(self) -> str:
+        return (
+            f"SharedSessionObject(id={self.session_id!r}, "
+            f"state={self.state.value}, "
+            f"participants={self.participant_count}, "
+            f"mode={self.consistency_mode.value})"
+        )
+
+
+class SessionLifecycleError(Exception):
+    """Raised when a session lifecycle transition is invalid."""
+
+
+class SessionParticipantError(Exception):
+    """Raised for participant-related errors."""

hypervisor/session/intent_locks.py

@@ -0,0 +1,118 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Resource Locks — stub implementation.
+
+Public Preview: locks are not enforced. All acquire calls succeed.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from enum import Enum
+
+
+class LockIntent(str, Enum):
+    """Types of lock intent."""
+
+    READ = "read"
+    WRITE = "write"
+    EXCLUSIVE = "exclusive"
+
+
+@dataclass
+class IntentLock:
+    """A declared resource lock on a resource."""
+
+    lock_id: str = field(default_factory=lambda: f"lock:{uuid.uuid4().hex[:8]}")
+    agent_did: str = ""
+    session_id: str = ""
+    resource_path: str = ""
+    intent: LockIntent = LockIntent.READ
+    acquired_at: datetime = field(default_factory=lambda: datetime.now(UTC))
+    is_active: bool = True
+    saga_step_id: str | None = None
+
+
+class LockContentionError(Exception):
+    """Raised when lock contention is detected."""
+
+
+class DeadlockError(Exception):
+    """Raised when a deadlock is detected."""
+
+
+class IntentLockManager:
+    """
+    Resource lock stub (Public Preview: all locks succeed, no contention).
+    """
+
+    def __init__(self) -> None:
+        self._locks: dict[str, IntentLock] = {}
+
+    def acquire(
+        self,
+        agent_did: str,
+        session_id: str,
+        resource_path: str,
+        intent: LockIntent,
+        saga_step_id: str | None = None,
+    ) -> IntentLock:
+        """Acquire a lock (Public Preview: always succeeds)."""
+        lock = IntentLock(
+            agent_did=agent_did,
+            session_id=session_id,
+            resource_path=resource_path,
+            intent=intent,
+            saga_step_id=saga_step_id,
+        )
+        self._locks[lock.lock_id] = lock
+        return lock
+
+    def release(self, lock_id: str) -> None:
+        """Release a lock."""
+        lock = self._locks.get(lock_id)
+        if lock:
+            lock.is_active = False
+
+    def release_agent_locks(self, agent_did: str, session_id: str) -> int:
+        count = 0
+        for lock in list(self._locks.values()):
+            if lock.agent_did == agent_did and lock.session_id == session_id and lock.is_active:
+                lock.is_active = False
+                count += 1
+        return count
+
+    def release_session_locks(self, session_id: str) -> int:
+        count = 0
+        for lock in list(self._locks.values()):
+            if lock.session_id == session_id and lock.is_active:
+                lock.is_active = False
+                count += 1
+        return count
+
+    def get_agent_locks(self, agent_did: str, session_id: str) -> list[IntentLock]:
+        return [
+            lock for lock in self._locks.values()
+            if lock.agent_did == agent_did
+            and lock.session_id == session_id
+            and lock.is_active
+        ]
+
+    def get_resource_locks(self, resource_path: str) -> list[IntentLock]:
+        return [
+            lock for lock in self._locks.values()
+            if lock.resource_path == resource_path
+            and lock.is_active
+        ]
+
+    @property
+    def active_lock_count(self) -> int:
+        return sum(1 for lock in self._locks.values() if lock.is_active)
+
+    @property
+    def contention_points(self) -> list[str]:
+        return []

hypervisor/session/isolation.py

@@ -0,0 +1,37 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# Public Preview — basic implementation
+"""
+Session Isolation Levels — stub implementation.
+
+Public Preview: all access is serialized via a single lock.
+Isolation levels are retained for API compatibility but not enforced.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class IsolationLevel(str, Enum):
+    """Session isolation levels (Public Preview: not enforced)."""
+
+    SNAPSHOT = "snapshot"
+    READ_COMMITTED = "read_committed"
+    SERIALIZABLE = "serializable"
+
+    @property
+    def requires_vector_clocks(self) -> bool:
+        return False
+
+    @property
+    def requires_intent_locks(self) -> bool:
+        return False
+
+    @property
+    def allows_concurrent_writes(self) -> bool:
+        return True
+
+    @property
+    def coordination_cost(self) -> str:
+        return "none"