agenthandler 0.92.0__py3-none-any.whl

agenthandler/__init__.py

@@ -0,0 +1,163 @@
+"""AgentHandler — supervision for AI agent tool execution.
+
+Timeouts, budgets, circuit breakers, and audit for tool calls.
+Works with any agent framework — just wrap your tool calls.
+
+Usage:
+    from agenthandler import Supervisor, Policy
+
+    policy = Policy(max_iterations=3, tool_timeout=15, token_budget=10000)
+    supervisor = Supervisor(policy)
+
+    # Supervise a tool call
+    result = await supervisor.call("web_search", my_tool_fn, query="python async")
+    if result.succeeded:
+        print(result.output)
+    else:
+        print(result.error)
+"""
+
+__version__ = "0.92.0"
+
+from .approval import ApprovalQueue, ApprovalRequest, ApprovalStatus
+from .audit import AuditEntry, AuditLog, AuditOutcome, AuditPhase, AuditSink, JsonlAuditSink
+from .budget import BudgetSnapshot, BudgetTracker
+from .builder import SkillBuilder
+from .circuit_breaker import CircuitBreaker, CircuitState
+from .connectors import MongoConnector, SqlConnector
+from .context import AnchoredState, CompressedContext, CompressedHistory, ContextWindow, Turn
+from .errors import AgentHandlerError
+from .guardrails import (
+    ActiveHours,
+    AnomalyScorer,
+    CategoryRateLimit,
+    EnsembleDecision,
+    ExplanationRequired,
+    GoalVerifier,
+    GuardrailResult,
+    IdempotencyGuard,
+    IntentDriftDetector,
+    OutputLengthLimit,
+    PromptInjectionDetector,
+    RecursionDetector,
+    ResourceQuota,
+    SafetyClassifier,
+    SchemaValidator,
+    SemanticPiiRedactor,
+    UrlGuard,
+)
+from .observe import ModelPricing, Observer, PricingTable, ToolCallRecord, ToolMetrics
+from .openclaw import OpenClawBridge, to_openclaw_manifest, to_openclaw_tool_schema
+from .pipeline import Pipeline, PipelineResult
+from .pipeline_poml import PipelineBuilder, parse_pipeline_poml
+from .policy import Action, OnFailure, Policy, ScopeRule, ToolScope
+from .redact import Redactor
+from .reflection import ReflectionCycle, ReflectionLoop, ReflectionResult
+from .replay import ReplayFrame, ReplaySummary, SessionReplay
+from .session import SessionManager
+from .skill import Skill, SkillStore, ToolDefinition, ToolParameter
+from .store import (
+    Checkpoint,
+    MemoryStore,
+    SessionStatus,
+    SqliteStore,
+    StateStore,
+    validate_payload,
+)
+from .streams import (
+    KafkaStreamConnector,
+    KinesisStreamConnector,
+    RedisStreamConnector,
+    StreamConnector,
+)
+from .supervisor import SupervisedResult, Supervisor
+from .triggers import DbWatchEntry, Scheduler, WebhookTrigger
+
+__all__ = [
+    "Policy",
+    "OnFailure",
+    "Action",
+    "ScopeRule",
+    "ToolScope",
+    "Supervisor",
+    "SupervisedResult",
+    "BudgetTracker",
+    "BudgetSnapshot",
+    "CircuitBreaker",
+    "CircuitState",
+    "AuditLog",
+    "AuditEntry",
+    "AuditPhase",
+    "AuditOutcome",
+    "AuditSink",
+    "JsonlAuditSink",
+    "AgentHandlerError",
+    "Skill",
+    "SkillStore",
+    "ToolDefinition",
+    "ToolParameter",
+    "SkillBuilder",
+    "ContextWindow",
+    "CompressedContext",
+    "CompressedHistory",
+    "AnchoredState",
+    "Turn",
+    "OpenClawBridge",
+    "to_openclaw_tool_schema",
+    "to_openclaw_manifest",
+    "StateStore",
+    "MemoryStore",
+    "SqliteStore",
+    "Checkpoint",
+    "SessionStatus",
+    "SessionManager",
+    "validate_payload",
+    "ApprovalQueue",
+    "ApprovalRequest",
+    "ApprovalStatus",
+    "Redactor",
+    "Observer",
+    "ToolCallRecord",
+    "ToolMetrics",
+    "PricingTable",
+    "ModelPricing",
+    "Pipeline",
+    "PipelineResult",
+    "PipelineBuilder",
+    "parse_pipeline_poml",
+    "SqlConnector",
+    "MongoConnector",
+    "Scheduler",
+    "WebhookTrigger",
+    "DbWatchEntry",
+    "StreamConnector",
+    "KafkaStreamConnector",
+    "KinesisStreamConnector",
+    "RedisStreamConnector",
+    # Guardrails — deterministic
+    "GuardrailResult",
+    "SchemaValidator",
+    "CategoryRateLimit",
+    "RecursionDetector",
+    "IdempotencyGuard",
+    "ResourceQuota",
+    "OutputLengthLimit",
+    "UrlGuard",
+    "ActiveHours",
+    # Guardrails — LLM-based
+    "PromptInjectionDetector",
+    "SafetyClassifier",
+    "IntentDriftDetector",
+    "SemanticPiiRedactor",
+    "AnomalyScorer",
+    "GoalVerifier",
+    "ExplanationRequired",
+    "EnsembleDecision",
+    # Long-duration features
+    "ReflectionLoop",
+    "ReflectionCycle",
+    "ReflectionResult",
+    "SessionReplay",
+    "ReplayFrame",
+    "ReplaySummary",
+]

agenthandler/approval.py

@@ -0,0 +1,135 @@
+"""Approval queue — human-in-the-loop confirmation for dangerous tool calls.
+
+When a tool is in the policy's require_confirm list, the Supervisor queues
+the call here instead of blocking it outright. The call stays pending until
+a human approves or denies it via the REST API, dashboard, or any client
+listening on the WebSocket events stream.
+
+Usage (internal — SessionManager wires this up automatically):
+
+    queue = ApprovalQueue()
+    approval_id = queue.submit("delete_file", {"path": "/tmp/data"}, session_id)
+    # ... user reviews and approves via REST ...
+    queue.approve(approval_id)
+    # ... or denies ...
+    queue.deny(approval_id, reason="Too risky")
+"""
+
+import secrets
+import threading
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any, Dict, List, Optional
+
+
+class ApprovalStatus(Enum):
+    PENDING = "pending"
+    APPROVED = "approved"
+    DENIED = "denied"
+    EXPIRED = "expired"
+
+
+@dataclass
+class ApprovalRequest:
+    """A pending tool call awaiting human approval."""
+
+    approval_id: str
+    session_id: str
+    tool_name: str
+    tool_args: Dict[str, Any]
+    status: ApprovalStatus = ApprovalStatus.PENDING
+    created_at: str = ""
+    resolved_at: str = ""
+    resolved_by: str = ""  # who approved/denied (for audit)
+    deny_reason: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.created_at:
+            self.created_at = datetime.now(timezone.utc).isoformat()
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "approval_id": self.approval_id,
+            "session_id": self.session_id,
+            "tool_name": self.tool_name,
+            "tool_args": {k: str(v)[:200] for k, v in self.tool_args.items()},
+            "status": self.status.value,
+            "created_at": self.created_at,
+            "resolved_at": self.resolved_at,
+            "resolved_by": self.resolved_by,
+            "deny_reason": self.deny_reason,
+        }
+
+
+class ApprovalQueue:
+    """Thread-safe queue of pending tool call approvals.
+
+    One queue per SessionManager — holds approvals for all sessions.
+    """
+
+    def __init__(self) -> None:
+        self._requests: Dict[str, ApprovalRequest] = {}
+        self._lock = threading.Lock()
+
+    def submit(
+        self,
+        tool_name: str,
+        tool_args: Dict[str, Any],
+        session_id: str,
+    ) -> ApprovalRequest:
+        """Queue a tool call for approval. Returns the ApprovalRequest."""
+        req = ApprovalRequest(
+            approval_id=secrets.token_hex(8),
+            session_id=session_id,
+            tool_name=tool_name,
+            tool_args=tool_args,
+        )
+        with self._lock:
+            self._requests[req.approval_id] = req
+        return req
+
+    def get(self, approval_id: str) -> Optional[ApprovalRequest]:
+        with self._lock:
+            return self._requests.get(approval_id)
+
+    def approve(self, approval_id: str, approved_by: str = "") -> Optional[ApprovalRequest]:
+        """Approve a pending request. Returns the request, or None if not found."""
+        with self._lock:
+            req = self._requests.get(approval_id)
+            if req is None or req.status != ApprovalStatus.PENDING:
+                return None
+            req.status = ApprovalStatus.APPROVED
+            req.resolved_at = datetime.now(timezone.utc).isoformat()
+            req.resolved_by = approved_by
+            return req
+
+    def deny(
+        self, approval_id: str, reason: str = "", denied_by: str = ""
+    ) -> Optional[ApprovalRequest]:
+        """Deny a pending request. Returns the request, or None if not found."""
+        with self._lock:
+            req = self._requests.get(approval_id)
+            if req is None or req.status != ApprovalStatus.PENDING:
+                return None
+            req.status = ApprovalStatus.DENIED
+            req.deny_reason = reason
+            req.resolved_at = datetime.now(timezone.utc).isoformat()
+            req.resolved_by = denied_by
+            return req
+
+    def list_pending(self, session_id: Optional[str] = None) -> List[ApprovalRequest]:
+        """List pending approvals, optionally filtered by session."""
+        with self._lock:
+            reqs = list(self._requests.values())
+        if session_id is not None:
+            reqs = [r for r in reqs if r.session_id == session_id]
+        return [r for r in reqs if r.status == ApprovalStatus.PENDING]
+
+    def list_all(self, session_id: Optional[str] = None) -> List[ApprovalRequest]:
+        """List all approvals (any status), optionally filtered by session."""
+        with self._lock:
+            reqs = list(self._requests.values())
+        if session_id is not None:
+            reqs = [r for r in reqs if r.session_id == session_id]
+        return reqs

agenthandler/audit.py

@@ -0,0 +1,144 @@
+"""Audit logging — every supervised action gets recorded."""
+
+import json
+import sys
+import threading
+from abc import ABC, abstractmethod
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from enum import Enum
+from pathlib import Path
+from typing import IO, Any, Dict, List, Optional
+
+
+class AuditPhase(Enum):
+    TOOL_CALL = "tool_call"
+    BUDGET_CHECK = "budget_check"
+    CIRCUIT_BREAKER = "circuit_breaker"
+    ITERATION_CHECK = "iteration_check"
+    DEAD_MAN_SWITCH = "dead_man_switch"
+    POLICY_CHECK = "policy_check"
+    SCOPE_CHECK = "scope_check"
+    REQUEST_START = "request_start"
+    REQUEST_END = "request_end"
+
+
+class AuditOutcome(Enum):
+    ALLOWED = "allowed"
+    DENIED = "denied"
+    TIMED_OUT = "timed_out"
+    FAILED = "failed"
+    BUDGET_EXCEEDED = "budget_exceeded"
+    RETRIED = "retried"
+    INFO = "info"
+
+
+@dataclass
+class AuditEntry:
+    """A single audit log entry."""
+
+    timestamp: str
+    request_id: str
+    phase: str
+    outcome: str
+    target: Optional[str] = None
+    detail: Optional[str] = None
+    metadata: Optional[Dict[str, Any]] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        d = asdict(self)
+        return {k: v for k, v in d.items() if v is not None}
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), default=str)
+
+
+class AuditSink(ABC):
+    """Interface for audit log destinations."""
+
+    @abstractmethod
+    def write(self, entry: AuditEntry) -> None: ...
+
+
+class JsonlAuditSink(AuditSink):
+    """Writes audit entries as JSONL to a file or stream."""
+
+    def __init__(self, writer: IO[str]):
+        self._writer = writer
+        self._lock = threading.Lock()
+
+    @classmethod
+    def stdout(cls) -> "JsonlAuditSink":
+        return cls(sys.stdout)
+
+    @classmethod
+    def file(cls, path: str) -> "JsonlAuditSink":
+        p = Path(path)
+        p.parent.mkdir(parents=True, exist_ok=True)
+        return cls(open(p, "a"))
+
+    def write(self, entry: AuditEntry) -> None:
+        with self._lock:
+            self._writer.write(entry.to_json() + "\n")
+            self._writer.flush()
+
+
+class MemoryAuditSink(AuditSink):
+    """In-memory audit sink for testing."""
+
+    def __init__(self) -> None:
+        self._entries: List[AuditEntry] = []
+        self._lock = threading.Lock()
+
+    def write(self, entry: AuditEntry) -> None:
+        with self._lock:
+            self._entries.append(entry)
+
+    @property
+    def entries(self) -> List[AuditEntry]:
+        with self._lock:
+            return list(self._entries)
+
+    def __len__(self) -> int:
+        with self._lock:
+            return len(self._entries)
+
+
+class AuditLog:
+    """Records audit entries for a single request."""
+
+    def __init__(self, request_id: str, sinks: Optional[List[AuditSink]] = None):
+        self._request_id = request_id
+        self._sinks = sinks or []
+
+    @classmethod
+    def noop(cls) -> "AuditLog":
+        """Audit log that discards all entries."""
+        return cls("noop", [])
+
+    @property
+    def request_id(self) -> str:
+        return self._request_id
+
+    def record(
+        self,
+        phase: AuditPhase,
+        outcome: AuditOutcome,
+        target: Optional[str] = None,
+        detail: Optional[str] = None,
+        metadata: Optional[Dict[str, Any]] = None,
+    ) -> None:
+        entry = AuditEntry(
+            timestamp=datetime.now(timezone.utc).isoformat(),
+            request_id=self._request_id,
+            phase=phase.value,
+            outcome=outcome.value,
+            target=target,
+            detail=detail,
+            metadata=metadata,
+        )
+        for sink in self._sinks:
+            try:
+                sink.write(entry)
+            except Exception:
+                pass  # audit must never crash the request

agenthandler/auth.py

@@ -0,0 +1,188 @@
+"""Authentication providers for the REST control plane.
+
+Supports:
+- API key (Bearer token) — simple, self-issued
+- OAuth2 (GitHub, Google) — for production deployments
+
+Usage:
+    # API key only
+    app = create_app(api_key="my-secret")
+
+    # OAuth2 via env vars:
+    #   AGENTHANDLER_OAUTH_PROVIDER=github
+    #   AGENTHANDLER_OAUTH_CLIENT_ID=...
+    #   AGENTHANDLER_OAUTH_CLIENT_SECRET=...
+    app = create_app()
+"""
+
+from __future__ import annotations
+
+import secrets
+import time
+from typing import Any, Dict, Optional
+
+try:
+    from fastapi import Depends, FastAPI, HTTPException, Request
+    from fastapi.security import (
+        HTTPAuthorizationCredentials,
+        HTTPBearer,
+    )
+except ImportError:
+    pass
+
+
+_bearer_scheme = HTTPBearer(auto_error=False)
+
+# In-memory token store for OAuth sessions (maps token -> user info + expiry)
+_oauth_tokens: Dict[str, Dict[str, Any]] = {}
+
+
+def make_auth_dependency(
+    api_key: Optional[str] = None,
+    oauth_enabled: bool = False,
+) -> Any:
+    """Build a FastAPI dependency that enforces auth.
+
+    Checks in order:
+    1. Bearer token matches api_key (if set)
+    2. Bearer token is a valid OAuth session token (if oauth enabled)
+    3. Reject
+
+    If api_key is None and oauth is disabled, all requests pass.
+    """
+
+    async def _check_auth(
+        credentials: Optional[HTTPAuthorizationCredentials] = Depends(_bearer_scheme),
+    ) -> Optional[Dict[str, Any]]:
+        # No auth configured — open access
+        if api_key is None and not oauth_enabled:
+            return None
+
+        if credentials is None:
+            raise HTTPException(status_code=401, detail="Missing authentication")
+
+        token = credentials.credentials
+
+        # Check API key
+        if api_key is not None and secrets.compare_digest(token, api_key):
+            return {"auth_type": "api_key"}
+
+        # Check OAuth session token
+        if oauth_enabled and token in _oauth_tokens:
+            session = _oauth_tokens[token]
+            if session.get("expires_at", 0) > time.time():
+                return session
+            else:
+                del _oauth_tokens[token]  # expired
+
+        raise HTTPException(status_code=401, detail="Invalid or missing API key")
+
+    return _check_auth
+
+
+def register_oauth_routes(
+    app: "FastAPI", provider: str, client_id: str, client_secret: str
+) -> None:
+    """Add OAuth2 login/callback routes to the FastAPI app.
+
+    Supports: "github", "google"
+    """
+    providers = {
+        "github": {
+            "authorize_url": "https://github.com/login/oauth/authorize",
+            "token_url": "https://github.com/login/oauth/access_token",
+            "user_url": "https://api.github.com/user",
+            "scope": "read:user",
+        },
+        "google": {
+            "authorize_url": "https://accounts.google.com/o/oauth2/v2/auth",
+            "token_url": "https://oauth2.googleapis.com/token",
+            "user_url": "https://www.googleapis.com/oauth2/v2/userinfo",
+            "scope": "openid email profile",
+        },
+    }
+
+    if provider not in providers:
+        raise ValueError(f"Unsupported OAuth provider: {provider}. Use: {list(providers.keys())}")
+
+    config = providers[provider]
+
+    @app.get("/auth/login")
+    def oauth_login(request: Request) -> Dict[str, Any]:
+        """Redirect URL for OAuth2 login."""
+        callback_url = str(request.base_url) + "auth/callback"
+        state = secrets.token_hex(16)
+        url = (
+            f"{config['authorize_url']}?"
+            f"client_id={client_id}&"
+            f"redirect_uri={callback_url}&"
+            f"scope={config['scope']}&"
+            f"state={state}"
+        )
+        return {"login_url": url, "state": state}
+
+    @app.get("/auth/callback")
+    async def oauth_callback(code: str, state: str = "") -> Dict[str, Any]:
+        """OAuth2 callback — exchange code for token, create session."""
+        try:
+            import httpx
+        except ImportError:
+            raise HTTPException(
+                status_code=500,
+                detail="httpx required for OAuth. pip install httpx",
+            )
+
+        # Exchange code for access token
+        async with httpx.AsyncClient() as client:
+            token_resp = await client.post(
+                config["token_url"],
+                data={
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "code": code,
+                },
+                headers={"Accept": "application/json"},
+            )
+            if token_resp.status_code != 200:
+                raise HTTPException(status_code=401, detail="OAuth token exchange failed")
+            token_data = token_resp.json()
+            access_token = token_data.get("access_token")
+            if not access_token:
+                raise HTTPException(status_code=401, detail="No access token in response")
+
+            # Get user info
+            user_resp = await client.get(
+                config["user_url"],
+                headers={"Authorization": f"Bearer {access_token}"},
+            )
+            if user_resp.status_code != 200:
+                raise HTTPException(status_code=401, detail="Failed to fetch user info")
+            user_info = user_resp.json()
+
+        # Create a session token
+        session_token = secrets.token_hex(32)
+        _oauth_tokens[session_token] = {
+            "auth_type": "oauth",
+            "provider": provider,
+            "user": user_info.get("login") or user_info.get("email", "unknown"),
+            "user_info": user_info,
+            "expires_at": time.time() + 86400,  # 24 hours
+        }
+
+        return {
+            "token": session_token,
+            "user": _oauth_tokens[session_token]["user"],
+            "expires_in": 86400,
+        }
+
+    @app.get("/auth/me")
+    async def auth_me(
+        credentials: Optional[HTTPAuthorizationCredentials] = Depends(_bearer_scheme),
+    ) -> Dict[str, Any]:
+        """Get info about the current authenticated user."""
+        if credentials is None:
+            raise HTTPException(status_code=401, detail="Not authenticated")
+        session = _oauth_tokens.get(credentials.credentials)
+        if session and session.get("expires_at", 0) > time.time():
+            return {"user": session["user"], "provider": session.get("provider")}
+        raise HTTPException(status_code=401, detail="Invalid or expired token")