agent_os_kernel 3.1.0__py3-none-any.whl

agent_os/escalation.py

@@ -0,0 +1,276 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Human-in-the-loop escalation workflows for AI agent governance.
+
+Provides approval gates, timeout escalation, and configurable escalation
+policies so agents can't take high-risk actions without human sign-off.
+
+This directly addresses the criticism that AGT has "no human escalation
+primitives baked in." Now it does.
+
+Usage:
+    from agent_os.escalation import EscalationManager, EscalationPolicy
+
+    policy = EscalationPolicy(
+        actions_requiring_approval=["delete_file", "deploy", "send_email"],
+        timeout_seconds=300,
+        default_on_timeout="deny",
+    )
+    manager = EscalationManager(policy)
+
+    decision = await manager.request_approval(
+        agent_id="agent-1",
+        action="deploy",
+        context={"target": "production", "version": "2.1.0"},
+    )
+    if decision.approved:
+        # proceed
+        ...
+"""
+
+from __future__ import annotations
+
+import asyncio
+import uuid
+from datetime import datetime, timedelta, timezone
+from enum import Enum
+from typing import Any, Callable, Awaitable
+
+from pydantic import BaseModel, Field
+
+
+class EscalationOutcome(str, Enum):
+    """Outcome of an escalation request."""
+    APPROVED = "approved"
+    DENIED = "denied"
+    TIMED_OUT = "timed_out"
+    PENDING = "pending"
+    AUTO_APPROVED = "auto_approved"
+
+
+class EscalationRequest(BaseModel):
+    """A pending human approval request."""
+    request_id: str = Field(default_factory=lambda: uuid.uuid4().hex[:12])
+    agent_id: str
+    action: str
+    context: dict[str, Any] = Field(default_factory=dict)
+    reason: str = ""
+    urgency: str = Field(default="normal", description="low, normal, high, critical")
+    requested_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    expires_at: datetime | None = None
+    outcome: EscalationOutcome = EscalationOutcome.PENDING
+    decided_by: str | None = None
+    decided_at: datetime | None = None
+
+
+class EscalationDecision(BaseModel):
+    """Result of an escalation request."""
+    request_id: str
+    approved: bool
+    outcome: EscalationOutcome
+    decided_by: str
+    decided_at: datetime = Field(default_factory=lambda: datetime.now(timezone.utc))
+    reason: str = ""
+
+
+class EscalationPolicy(BaseModel):
+    """Policy governing when and how actions are escalated to humans."""
+
+    actions_requiring_approval: list[str] = Field(
+        default_factory=list,
+        description="Actions that always require human approval",
+    )
+    action_patterns_requiring_approval: list[str] = Field(
+        default_factory=list,
+        description="Regex patterns for actions requiring approval",
+    )
+    classifications_requiring_approval: list[str] = Field(
+        default_factory=list,
+        description="Data classifications that trigger escalation (e.g., RESTRICTED, TOP_SECRET)",
+    )
+    timeout_seconds: int = Field(
+        default=300,
+        description="Seconds to wait for human response before timeout action",
+    )
+    default_on_timeout: str = Field(
+        default="deny",
+        description="Action when timeout: 'deny' (safe default) or 'approve'",
+    )
+    max_auto_approvals_per_hour: int = Field(
+        default=0,
+        description="Max actions auto-approved per hour (0 = never auto-approve)",
+    )
+    escalation_chain: list[str] = Field(
+        default_factory=list,
+        description="Ordered list of approvers. If first doesn't respond, escalate to next.",
+    )
+    notify_on_timeout: bool = Field(
+        default=True,
+        description="Send notification when escalation times out",
+    )
+
+
+class EscalationManager:
+    """Manages human-in-the-loop approval workflows.
+
+    When an agent requests a high-risk action, the manager:
+    1. Checks if the action requires approval (per policy)
+    2. Creates an EscalationRequest
+    3. Notifies the approval handler (webhook, UI, Slack, etc.)
+    4. Waits for human response or timeout
+    5. Returns the decision
+
+    The approval handler is pluggable — implement your own notification
+    system (Slack bot, email, Teams, dashboard, etc.)
+    """
+
+    def __init__(
+        self,
+        policy: EscalationPolicy,
+        approval_handler: Callable[[EscalationRequest], Awaitable[None]] | None = None,
+        timeout_handler: Callable[[EscalationRequest], Awaitable[None]] | None = None,
+    ) -> None:
+        self.policy = policy
+        self._pending: dict[str, EscalationRequest] = {}
+        self._approval_handler = approval_handler
+        self._timeout_handler = timeout_handler
+        self._events: list[dict[str, Any]] = []
+
+    def requires_approval(self, action: str, **context: Any) -> bool:
+        """Check if an action requires human approval per policy."""
+        import re
+
+        if action in self.policy.actions_requiring_approval:
+            return True
+
+        for pattern in self.policy.action_patterns_requiring_approval:
+            if re.search(pattern, action):
+                return True
+
+        classification = context.get("classification", "")
+        if classification in self.policy.classifications_requiring_approval:
+            return True
+
+        return False
+
+    async def request_approval(
+        self,
+        agent_id: str,
+        action: str,
+        context: dict[str, Any] | None = None,
+        reason: str = "",
+        urgency: str = "normal",
+    ) -> EscalationDecision:
+        """Request human approval for an action.
+
+        If the action doesn't require approval, returns auto-approved.
+        Otherwise, creates an escalation request and waits for response.
+        """
+        if not self.requires_approval(action, **(context or {})):
+            decision = EscalationDecision(
+                request_id="auto",
+                approved=True,
+                outcome=EscalationOutcome.AUTO_APPROVED,
+                decided_by="policy",
+                reason="Action does not require approval",
+            )
+            self._record_event("auto_approved", agent_id, action, decision)
+            return decision
+
+        now = datetime.now(timezone.utc)
+        request = EscalationRequest(
+            agent_id=agent_id,
+            action=action,
+            context=context or {},
+            reason=reason,
+            urgency=urgency,
+            expires_at=now + timedelta(seconds=self.policy.timeout_seconds),
+        )
+        self._pending[request.request_id] = request
+
+        # Notify approval handler
+        if self._approval_handler:
+            await self._approval_handler(request)
+
+        self._record_event("escalated", agent_id, action, request)
+
+        # Wait for response or timeout
+        deadline = request.expires_at
+        while datetime.now(timezone.utc) < deadline:
+            if request.outcome != EscalationOutcome.PENDING:
+                break
+            await asyncio.sleep(0.1)
+
+        # Handle timeout
+        if request.outcome == EscalationOutcome.PENDING:
+            if self.policy.default_on_timeout == "approve":
+                request.outcome = EscalationOutcome.TIMED_OUT
+                approved = True
+            else:
+                request.outcome = EscalationOutcome.TIMED_OUT
+                approved = False
+
+            request.decided_by = "timeout"
+            request.decided_at = datetime.now(timezone.utc)
+
+            if self._timeout_handler and self.policy.notify_on_timeout:
+                await self._timeout_handler(request)
+
+            decision = EscalationDecision(
+                request_id=request.request_id,
+                approved=approved,
+                outcome=EscalationOutcome.TIMED_OUT,
+                decided_by="timeout",
+                reason=f"Timed out after {self.policy.timeout_seconds}s — default: {self.policy.default_on_timeout}",
+            )
+        else:
+            decision = EscalationDecision(
+                request_id=request.request_id,
+                approved=request.outcome == EscalationOutcome.APPROVED,
+                outcome=request.outcome,
+                decided_by=request.decided_by or "unknown",
+                decided_at=request.decided_at or datetime.now(timezone.utc),
+            )
+
+        del self._pending[request.request_id]
+        self._record_event("decided", agent_id, action, decision)
+        return decision
+
+    def approve(self, request_id: str, decided_by: str = "human", reason: str = "") -> bool:
+        """Approve a pending escalation request (called by human/UI)."""
+        request = self._pending.get(request_id)
+        if not request or request.outcome != EscalationOutcome.PENDING:
+            return False
+        request.outcome = EscalationOutcome.APPROVED
+        request.decided_by = decided_by
+        request.decided_at = datetime.now(timezone.utc)
+        return True
+
+    def deny(self, request_id: str, decided_by: str = "human", reason: str = "") -> bool:
+        """Deny a pending escalation request (called by human/UI)."""
+        request = self._pending.get(request_id)
+        if not request or request.outcome != EscalationOutcome.PENDING:
+            return False
+        request.outcome = EscalationOutcome.DENIED
+        request.decided_by = decided_by
+        request.decided_at = datetime.now(timezone.utc)
+        return True
+
+    @property
+    def pending_requests(self) -> list[EscalationRequest]:
+        """Get all pending escalation requests."""
+        return [r for r in self._pending.values() if r.outcome == EscalationOutcome.PENDING]
+
+    @property
+    def audit_trail(self) -> list[dict[str, Any]]:
+        """Get the escalation audit trail."""
+        return list(self._events)
+
+    def _record_event(self, event_type: str, agent_id: str, action: str, data: Any) -> None:
+        self._events.append({
+            "event_type": event_type,
+            "agent_id": agent_id,
+            "action": action,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "data": data.model_dump(mode="json") if hasattr(data, "model_dump") else str(data),
+        })

agent_os/event_bus.py

@@ -0,0 +1,124 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""Cross-gate event bus for governance layer composition.
+
+Enables governance gates (PolicyEvaluator, TrustGate, CircuitBreaker,
+ConversationGuardian) to communicate via events without tight coupling.
+
+Example::
+
+    bus = GovernanceEventBus()
+    bus.subscribe("policy.violation", on_violation)
+    bus.publish("policy.violation", agent_id="a1", action="delete_db")
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import defaultdict
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from typing import Any, Callable
+
+logger = logging.getLogger(__name__)
+
+EventHandler = Callable[["GovernanceEvent"], None]
+
+
+@dataclass
+class GovernanceEvent:
+    """A governance event emitted by any gate."""
+
+    event_type: str
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+    source: str = ""
+    agent_id: str = ""
+    data: dict[str, Any] = field(default_factory=dict)
+
+
+# Standard event types
+POLICY_VIOLATION = "policy.violation"
+POLICY_ALLOW = "policy.allow"
+TRUST_PENALTY = "trust.penalty"
+TRUST_BOOST = "trust.boost"
+CIRCUIT_OPEN = "circuit.open"
+CIRCUIT_CLOSE = "circuit.close"
+ESCALATION = "governance.escalation"
+BUDGET_EXCEEDED = "budget.exceeded"
+
+
+class GovernanceEventBus:
+    """Publish/subscribe event bus for governance gate composition.
+
+    Example::
+
+        bus = GovernanceEventBus()
+
+        # Trust gate penalizes on policy violations
+        def on_violation(event):
+            trust_engine.penalize(event.agent_id, severity=0.3)
+        bus.subscribe("policy.violation", on_violation)
+
+        # Circuit breaker trips on trust penalties
+        def on_trust_penalty(event):
+            if event.data.get("new_score", 1.0) < 0.3:
+                circuit_breaker.trip(event.agent_id)
+        bus.subscribe("trust.penalty", on_trust_penalty)
+
+        # Policy engine publishes violation
+        bus.publish("policy.violation", agent_id="agent-1", action="drop_table")
+    """
+
+    def __init__(self) -> None:
+        self._handlers: dict[str, list[EventHandler]] = defaultdict(list)
+        self._history: list[GovernanceEvent] = []
+        self._max_history: int = 1000
+
+    def subscribe(self, event_type: str, handler: EventHandler) -> None:
+        """Subscribe a handler to an event type."""
+        self._handlers[event_type].append(handler)
+
+    def unsubscribe(self, event_type: str, handler: EventHandler) -> None:
+        """Remove a handler from an event type."""
+        if event_type in self._handlers:
+            self._handlers[event_type] = [
+                h for h in self._handlers[event_type] if h is not handler
+            ]
+
+    def publish(self, event_type: str, source: str = "", agent_id: str = "", **data: Any) -> GovernanceEvent:
+        """Publish an event to all subscribers."""
+        event = GovernanceEvent(
+            event_type=event_type,
+            source=source,
+            agent_id=agent_id,
+            data=data,
+        )
+        self._history.append(event)
+        if len(self._history) > self._max_history:
+            self._history = self._history[-self._max_history:]
+
+        for handler in self._handlers.get(event_type, []):
+            try:
+                handler(event)
+            except Exception:
+                logger.exception("Event handler failed for %s", event_type)
+
+        # Wildcard subscribers
+        for handler in self._handlers.get("*", []):
+            try:
+                handler(event)
+            except Exception:
+                logger.exception("Wildcard handler failed for %s", event_type)
+
+        return event
+
+    def get_history(self, event_type: str | None = None, limit: int = 100) -> list[GovernanceEvent]:
+        """Get recent events, optionally filtered by type."""
+        events = self._history
+        if event_type:
+            events = [e for e in events if e.event_type == event_type]
+        return events[-limit:]
+
+    def clear_history(self) -> None:
+        """Clear event history."""
+        self._history.clear()

agent_os/exceptions.py

@@ -0,0 +1,180 @@
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+"""
+Agent OS Exception Hierarchy
+
+Standardized exceptions with error codes for all Agent OS components.
+Each exception carries an error_code, optional details dict, and timestamp
+for structured error handling and logging.
+"""
+
+from datetime import datetime, timezone
+
+
+class AgentOSError(Exception):
+    """Base exception for all Agent OS errors."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message)
+        self.error_code = error_code or "AGENT_OS_ERROR"
+        self.details = details or {}
+        self.timestamp = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self):
+        return {
+            "error": self.error_code,
+            "message": str(self),
+            "details": self.details,
+            "timestamp": self.timestamp,
+        }
+
+
+# --- Policy errors ---
+
+class PolicyError(AgentOSError):
+    """Base exception for policy-related errors."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "POLICY_ERROR", details)
+
+
+class PolicyViolationError(PolicyError):
+    """Raised when a governance policy check fails."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "POLICY_VIOLATION", details)
+
+
+class PolicyDeniedError(PolicyError):
+    """Raised when a policy explicitly denies an action."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "POLICY_DENIED", details)
+
+
+class PolicyTimeoutError(PolicyError):
+    """Raised when a policy evaluation times out."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "POLICY_TIMEOUT", details)
+
+
+# --- Budget errors ---
+
+class BudgetError(AgentOSError):
+    """Base exception for budget-related errors."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "BUDGET_ERROR", details)
+
+
+class BudgetExceededError(BudgetError):
+    """Raised when a budget limit is exceeded."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "BUDGET_EXCEEDED", details)
+
+
+class BudgetWarningError(BudgetError):
+    """Raised when approaching a budget limit."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "BUDGET_WARNING", details)
+
+
+# --- Identity errors ---
+
+class IdentityError(AgentOSError):
+    """Base exception for identity-related errors."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "IDENTITY_ERROR", details)
+
+
+class IdentityVerificationError(IdentityError):
+    """Raised when identity verification fails."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "IDENTITY_VERIFICATION_FAILED", details)
+
+
+class CredentialExpiredError(IdentityError):
+    """Raised when credentials have expired."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "CREDENTIAL_EXPIRED", details)
+
+
+# --- Integration errors ---
+
+class IntegrationError(AgentOSError):
+    """Base exception for integration-related errors."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "INTEGRATION_ERROR", details)
+
+
+class AdapterNotFoundError(IntegrationError):
+    """Raised when a requested adapter is not found."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "ADAPTER_NOT_FOUND", details)
+
+
+class AdapterTimeoutError(IntegrationError):
+    """Raised when an adapter operation times out."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "ADAPTER_TIMEOUT", details)
+
+
+# --- Configuration errors ---
+
+class ConfigurationError(AgentOSError):
+    """Base exception for configuration-related errors."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "CONFIGURATION_ERROR", details)
+
+
+class InvalidPolicyError(ConfigurationError):
+    """Raised when a policy definition is invalid."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "INVALID_POLICY", details)
+
+
+class MissingConfigError(ConfigurationError):
+    """Raised when required configuration is missing."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "MISSING_CONFIG", details)
+
+
+# --- Rate limit errors ---
+
+class RateLimitError(AgentOSError):
+    """Raised when a rate limit is hit."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "RATE_LIMIT_EXCEEDED", details)
+
+
+# --- Security errors ---
+
+
+class SecurityError(AgentOSError):
+    """Raised when a sandbox security violation is detected."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "SECURITY_VIOLATION", details)
+
+
+# --- Serialization errors ---
+
+
+class SerializationError(AgentOSError):
+    """Raised when state serialization or deserialization fails."""
+
+    def __init__(self, message, error_code=None, details=None):
+        super().__init__(message, error_code or "SERIALIZATION_ERROR", details)