openbox-langgraph-sdk-python 0.1.0__py3-none-any.whl

openbox_langgraph/errors.py

@@ -0,0 +1,114 @@
+"""OpenBox LangGraph SDK — Custom exception classes."""
+
+from __future__ import annotations
+
+
+class OpenBoxError(Exception):
+    """Base class for all OpenBox SDK errors."""
+
+
+class OpenBoxAuthError(OpenBoxError):
+    """Raised when the API key is invalid or unauthorized."""
+
+
+class OpenBoxNetworkError(OpenBoxError):
+    """Raised when the OpenBox Core API is unreachable or returns an error."""
+
+
+class OpenBoxInsecureURLError(OpenBoxError):
+    """Raised when an insecure HTTP URL is used for a non-localhost endpoint."""
+
+
+class GovernanceBlockedError(OpenBoxError):
+    """Raised when governance returns a BLOCK or HALT verdict.
+
+    Supports two calling conventions:
+
+    Hook-level (3 positional args):
+        GovernanceBlockedError(verdict_str, reason, identifier)
+        e.g. GovernanceBlockedError("block", "Blocked by policy", "https://api.example.com")
+
+    SDK-level (keyword args):
+        GovernanceBlockedError(reason, policy_id=..., risk_score=...)
+    """
+
+    def __init__(
+        self,
+        verdict_or_reason: str,
+        reason_or_policy_id: str | None = None,
+        identifier_or_risk_score: str | float | None = None,
+        policy_id: str | None = None,
+        risk_score: float | None = None,
+    ) -> None:
+        from openbox_langgraph.types import Verdict  # lazy to avoid circular
+
+        _HOOK_VERDICTS = ("block", "halt", "require_approval", "stop")
+        is_hook_call = verdict_or_reason in _HOOK_VERDICTS
+
+        if is_hook_call:
+            # GovernanceBlockedError(verdict, reason, identifier)
+            self.verdict = Verdict.from_string(verdict_or_reason).value
+            reason = reason_or_policy_id or verdict_or_reason
+            self.identifier = (
+                str(identifier_or_risk_score) if isinstance(identifier_or_risk_score, str) else ""
+            )
+            self.policy_id = policy_id
+            self.risk_score = risk_score
+            super().__init__(reason)
+        else:
+            # GovernanceBlockedError(reason, policy_id?, risk_score?)
+            self.verdict = "block"
+            self.identifier = ""
+            self.policy_id = (
+                reason_or_policy_id if isinstance(reason_or_policy_id, str) else policy_id
+            )
+            self.risk_score = (
+                identifier_or_risk_score
+                if isinstance(identifier_or_risk_score, (int, float))
+                else risk_score
+            )
+            super().__init__(verdict_or_reason)
+
+
+class GovernanceHaltError(OpenBoxError):
+    """Raised when governance returns a HALT verdict (workflow-level stop)."""
+
+    verdict = "halt"
+
+    def __init__(
+        self,
+        reason: str,
+        *,
+        identifier: str = "",
+        policy_id: str | None = None,
+        risk_score: float | None = None,
+    ) -> None:
+        super().__init__(reason)
+        self.identifier = identifier
+        self.policy_id = policy_id
+        self.risk_score = risk_score
+
+
+class GuardrailsValidationError(OpenBoxError):
+    """Raised when guardrails validation fails."""
+
+    def __init__(self, reasons: list[str]) -> None:
+        msg = f"Guardrails validation failed: {'; '.join(reasons)}"
+        super().__init__(msg)
+        self.reasons = reasons
+
+
+class ApprovalExpiredError(OpenBoxError):
+    """Raised when the HITL approval window has expired."""
+
+
+class ApprovalRejectedError(OpenBoxError):
+    """Raised when the HITL approval is explicitly rejected."""
+
+
+class ApprovalTimeoutError(OpenBoxError):
+    """Raised when HITL polling exceeds max_wait_ms."""
+
+    def __init__(self, max_wait_ms: int | float) -> None:
+        super().__init__(f"HITL approval timed out after {max_wait_ms}ms")
+        self.max_wait_ms = max_wait_ms

openbox_langgraph/file_governance_hooks.py

@@ -0,0 +1,413 @@
+# openbox/file_governance_hooks.py
+"""File I/O governance hooks — instruments builtins.open() and os.fdopen().
+
+Wraps file objects with TracedFile to create OTel spans and send
+hook-level governance evaluations for every file operation (open,
+read, write, readline, readlines, writelines, close).
+
+- "started" evaluations can block file access before it happens
+- "completed" evaluations report what happened (informational)
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time as _time
+
+from . import hook_governance as _hook_gov
+
+logger = logging.getLogger(__name__)
+
+
+def _build_file_span_data(
+    span,
+    file_path: str,
+    file_mode: str,
+    operation: str,
+    stage: str,
+    error: str | None = None,
+    duration_ms: float | None = None,
+    data: str | None = None,
+    bytes_read: int | None = None,
+    bytes_written: int | None = None,
+    lines_count: int | None = None,
+    operations: list | None = None,
+) -> dict:
+    """Build span data dict for a file operation (used by governance hooks).
+
+    attributes: OTel-original only. All custom data at root level.
+    """
+
+    span_id_hex, trace_id_hex, parent_span_id = _hook_gov.extract_span_context(span)
+    raw_attrs = getattr(span, 'attributes', None)
+    attrs = dict(raw_attrs) if raw_attrs else {}
+
+    span_name = getattr(span, 'name', None) or f"file.{operation}"
+    now_ns = _time.time_ns()
+    duration_ns = int(duration_ms * 1_000_000) if duration_ms else None
+    end_time = now_ns if stage == "completed" else None
+    start_time = (now_ns - duration_ns) if duration_ns else now_ns
+
+    result = {
+        "span_id": span_id_hex,
+        "trace_id": trace_id_hex,
+        "parent_span_id": parent_span_id,
+        "name": span_name,
+        "kind": "INTERNAL",
+        "stage": stage,
+        "start_time": start_time,
+        "end_time": end_time,
+        "duration_ns": duration_ns,
+        "attributes": attrs,
+        "status": {"code": "ERROR" if error else "UNSET", "description": error},
+        "events": [],
+        # Hook type identification
+        "hook_type": "file_operation",
+        # File-specific root fields
+        "file_path": file_path,
+        "file_mode": file_mode,
+        "file_operation": operation,
+        "error": error,
+    }
+
+    # Only include optional fields if they have values
+    if data is not None:
+        result["data"] = data
+    if bytes_read is not None:
+        result["bytes_read"] = bytes_read
+    if bytes_written is not None:
+        result["bytes_written"] = bytes_written
+    if lines_count is not None:
+        result["lines_count"] = lines_count
+    if operations is not None:
+        result["operations"] = operations
+
+    return result
+
+
+def setup_file_io_instrumentation() -> bool:
+    """Setup file I/O instrumentation by patching built-in open().
+
+    File operations will be captured as spans with:
+    - file.path: File path
+    - file.mode: Open mode (r, w, a, etc.)
+    - file.operation: read, write, etc.
+    - file.bytes: Number of bytes read/written
+
+    Returns:
+        True if instrumentation was successful
+    """
+    import builtins
+
+    from opentelemetry import trace
+
+    # Check if already instrumented
+    if hasattr(builtins, '_openbox_original_open'):
+        logger.debug("File I/O already instrumented")
+        return True
+
+    _original_open = builtins.open
+    builtins._openbox_original_open = _original_open  # Store for uninstrumentation
+    _tracer = trace.get_tracer("openbox.file_io")
+
+    # Paths to skip (noisy system files)
+    _skip_patterns = ('/dev/', '/proc/', '/sys/', '__pycache__', '.pyc', '.pyo', '.so', '.dylib')
+
+    class TracedFile:
+        """Wrapper around file object to trace read/write operations.
+
+        Also sends hook-level governance evaluations:
+        - "started" on open (can block file access)
+        - "completed" on close (reports summary of operations performed)
+        """
+
+        def __init__(self, file_obj, file_path: str, mode: str, parent_span):
+            self._file = file_obj
+            self._file_path = file_path
+            self._mode = mode
+            self._parent_span = parent_span
+            self._bytes_read = 0
+            self._bytes_written = 0
+            self._operations: list = []  # Track operations for governance payload
+
+        def _evaluate_governance(self, operation: str, stage: str, span=None, **extra):
+            """Send governance evaluation for a file operation stage.
+
+            Args:
+                operation: File operation name (read, write, close, etc.)
+                stage: Governance stage (started, completed)
+                span: OTel span for this operation. Falls back to parent span.
+                **extra: Additional trigger fields (data, bytes_read, etc.)
+            """
+            if not _hook_gov.is_configured():
+                return
+            from openbox_langgraph.errors import GovernanceBlockedError
+            active_span = span or self._parent_span
+            try:
+                span_data = _build_file_span_data(
+                    active_span, self._file_path, self._mode, operation, stage,
+                    **extra,
+                )
+                _hook_gov.evaluate_sync(
+                    active_span,
+                    identifier=self._file_path,
+                    span_data=span_data,
+                )
+            except GovernanceBlockedError:
+                raise
+            except Exception:
+                pass  # fail_open handled inside evaluate_sync
+
+        def read(self, size=-1):
+            with _tracer.start_as_current_span("file.read") as span:
+                span.set_attribute("file.path", self._file_path)
+                span.set_attribute("file.operation", "read")
+                self._evaluate_governance("read", "started", span=span)
+
+                data = self._file.read(size)
+                bytes_count = len(data) if isinstance(data, (str, bytes)) else 0
+                self._bytes_read += bytes_count
+                self._operations.append("read")
+                span.set_attribute("file.bytes", bytes_count)
+
+                self._evaluate_governance(
+                    "read", "completed", span=span, data=data, bytes_read=bytes_count
+                )
+                return data
+
+        def readline(self):
+            with _tracer.start_as_current_span("file.readline") as span:
+                span.set_attribute("file.path", self._file_path)
+                span.set_attribute("file.operation", "readline")
+                self._evaluate_governance("readline", "started", span=span)
+
+                data = self._file.readline()
+                bytes_count = len(data) if isinstance(data, (str, bytes)) else 0
+                self._bytes_read += bytes_count
+                self._operations.append("readline")
+                span.set_attribute("file.bytes", bytes_count)
+
+                self._evaluate_governance(
+                    "readline", "completed", span=span, data=data, bytes_read=bytes_count
+                )
+                return data
+
+        def readlines(self):
+            with _tracer.start_as_current_span("file.readlines") as span:
+                span.set_attribute("file.path", self._file_path)
+                span.set_attribute("file.operation", "readlines")
+                self._evaluate_governance("readlines", "started", span=span)
+
+                data = self._file.readlines()
+                bytes_count = sum(len(line) for line in data) if data else 0
+                self._bytes_read += bytes_count
+                self._operations.append("readlines")
+                span.set_attribute("file.bytes", bytes_count)
+                span.set_attribute("file.lines", len(data) if data else 0)
+
+                self._evaluate_governance(
+                    "readlines", "completed", span=span,
+                    data=data, bytes_read=bytes_count,
+                    lines_count=len(data) if data else 0,
+                )
+                return data
+
+        def write(self, data):
+            with _tracer.start_as_current_span("file.write") as span:
+                span.set_attribute("file.path", self._file_path)
+                span.set_attribute("file.operation", "write")
+                self._evaluate_governance("write", "started", span=span)
+
+                bytes_count = len(data) if isinstance(data, (str, bytes)) else 0
+                span.set_attribute("file.bytes", bytes_count)
+                self._bytes_written += bytes_count
+                self._operations.append("write")
+                result = self._file.write(data)
+
+                self._evaluate_governance(
+                    "write", "completed", span=span, data=data, bytes_written=bytes_count
+                )
+                return result
+
+        def writelines(self, lines):
+            with _tracer.start_as_current_span("file.writelines") as span:
+                span.set_attribute("file.path", self._file_path)
+                span.set_attribute("file.operation", "writelines")
+                self._evaluate_governance("writelines", "started", span=span)
+
+                bytes_count = sum(len(line) for line in lines) if lines else 0
+                span.set_attribute("file.bytes", bytes_count)
+                span.set_attribute("file.lines", len(lines) if lines else 0)
+                self._bytes_written += bytes_count
+                self._operations.append("writelines")
+                result = self._file.writelines(lines)
+
+                self._evaluate_governance(
+                    "writelines", "completed", span=span,
+                    data=lines, bytes_written=bytes_count,
+                    lines_count=len(lines) if lines else 0,
+                )
+                return result
+
+        def close(self):
+            # Governance "completed" — reports what happened during file lifecycle
+            # Use try/finally to ensure file handle and span are always cleaned up
+            from openbox_langgraph.errors import GovernanceBlockedError
+            gov_error = None
+            try:
+                self._evaluate_governance(
+                    "close", "completed", span=self._parent_span,
+                    bytes_read=self._bytes_read,
+                    bytes_written=self._bytes_written,
+                    operations=self._operations,
+                )
+            except GovernanceBlockedError as e:
+                gov_error = e
+            finally:
+                if self._parent_span:
+                    self._parent_span.set_attribute("file.total_bytes_read", self._bytes_read)
+                    self._parent_span.set_attribute("file.total_bytes_written", self._bytes_written)
+                    self._parent_span.end()
+                self._file.close()
+            if gov_error:
+                raise gov_error
+
+        def __enter__(self):
+            return self
+
+        def __exit__(self, exc_type, exc_val, exc_tb):
+            # Don't mask the original exception if close() also raises
+            try:
+                self.close()
+            except Exception:
+                if exc_type is None:
+                    raise
+            return False
+
+        def __iter__(self):
+            return iter(self._file)
+
+        def __next__(self):
+            return next(self._file)
+
+        def __getattr__(self, name):
+            return getattr(self._file, name)
+
+    def traced_open(file, mode='r', *args, **kwargs):
+        file_str = str(file)
+
+        # Skip system/noisy paths
+        if any(p in file_str for p in _skip_patterns):
+            return _original_open(file, mode, *args, **kwargs)
+
+        span = _tracer.start_span("file.open")
+        span.set_attribute("file.path", file_str)
+        span.set_attribute("file.mode", mode)
+
+        # Governance "started" — can block file access before it happens
+        if _hook_gov.is_configured():
+            from openbox_langgraph.errors import GovernanceBlockedError
+            try:
+                open_span_data = _build_file_span_data(
+                    span, file_str, mode, "open", "started",
+                )
+                _hook_gov.evaluate_sync(
+                    span,
+                    identifier=file_str,
+                    span_data=open_span_data,
+                )
+            except GovernanceBlockedError:
+                span.set_attribute("error", True)
+                span.set_attribute("governance.blocked", True)
+                span.end()
+                raise
+            except Exception:
+                pass  # Non-governance errors are swallowed (fail_open handled inside evaluate_sync)
+
+        try:
+            file_obj = _original_open(file, mode, *args, **kwargs)
+            return TracedFile(file_obj, file_str, mode, span)
+        except Exception as e:
+            span.set_attribute("error", True)
+            span.set_attribute("error.type", type(e).__name__)
+            span.set_attribute("error.message", str(e))
+            span.end()
+            raise
+
+    builtins.open = traced_open
+
+    # Also patch os.fdopen — some frameworks (e.g. DeepAgents) use
+    # os.open() + os.fdopen() for symlink-safe I/O with O_NOFOLLOW,
+    # bypassing builtins.open entirely.
+    _original_fdopen = os.fdopen
+    os._openbox_original_fdopen = _original_fdopen  # Store for uninstrumentation
+
+    def traced_fdopen(fd, mode='r', *args, **kwargs):
+        # Resolve path from fd when possible
+        try:
+            file_str = os.readlink(f"/proc/self/fd/{fd}")
+        except (OSError, ValueError):
+            try:
+                # macOS: use fcntl F_GETPATH
+                import fcntl
+                buf = b'\x00' * 1024
+                file_str = fcntl.fcntl(fd, fcntl.F_GETPATH, buf).split(b'\x00', 1)[0].decode()
+            except Exception:
+                file_str = f"<fd:{fd}>"
+
+        if any(p in file_str for p in _skip_patterns):
+            return _original_fdopen(fd, mode, *args, **kwargs)
+
+        span = _tracer.start_span("file.open")
+        span.set_attribute("file.path", file_str)
+        span.set_attribute("file.mode", mode)
+
+        if _hook_gov.is_configured():
+            from openbox_langgraph.errors import GovernanceBlockedError
+            try:
+                open_span_data = _build_file_span_data(
+                    span, file_str, mode, "open", "started",
+                )
+                _hook_gov.evaluate_sync(
+                    span,
+                    identifier=file_str,
+                    span_data=open_span_data,
+                )
+            except GovernanceBlockedError:
+                span.set_attribute("error", True)
+                span.set_attribute("governance.blocked", True)
+                span.end()
+                raise
+            except Exception:
+                pass
+
+        try:
+            file_obj = _original_fdopen(fd, mode, *args, **kwargs)
+            return TracedFile(file_obj, file_str, mode, span)
+        except Exception as e:
+            span.set_attribute("error", True)
+            span.set_attribute("error.type", type(e).__name__)
+            span.set_attribute("error.message", str(e))
+            span.end()
+            raise
+
+    os.fdopen = traced_fdopen
+    logger.info("Instrumented: file I/O (builtins.open + os.fdopen)")
+    return True
+
+
+def uninstrument_file_io() -> None:
+    """Restore original open() and os.fdopen() functions."""
+    import builtins
+    restored = []
+    if hasattr(builtins, '_openbox_original_open'):
+        builtins.open = builtins._openbox_original_open
+        delattr(builtins, '_openbox_original_open')
+        restored.append("builtins.open")
+    if hasattr(os, '_openbox_original_fdopen'):
+        os.fdopen = os._openbox_original_fdopen
+        delattr(os, '_openbox_original_fdopen')
+        restored.append("os.fdopen")
+    if restored:
+        logger.info("Uninstrumented: file I/O (%s)", ", ".join(restored))

openbox_langgraph/hitl.py

@@ -0,0 +1,88 @@
+"""OpenBox LangGraph SDK — Human-in-the-Loop (HITL) approval polling."""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+
+from openbox_langgraph.client import ApprovalPollParams, GovernanceClient
+from openbox_langgraph.errors import (
+    ApprovalExpiredError,
+    ApprovalRejectedError,
+    GovernanceBlockedError,
+)
+from openbox_langgraph.types import HITLConfig, Verdict, verdict_should_stop
+
+
+@dataclass
+class HITLPollParams:
+    """Parameters for the HITL polling loop."""
+
+    workflow_id: str
+    run_id: str
+    activity_id: str
+    activity_type: str
+
+
+async def poll_until_decision(
+    client: GovernanceClient,
+    params: HITLPollParams,
+    config: HITLConfig,
+) -> None:
+    """Block until governance approves or rejects.
+
+    Polls OpenBox Core indefinitely until a terminal verdict is received.
+    The server controls approval expiration — the SDK does not impose a deadline.
+
+    Resolves (returns None) when approval is granted (ALLOW verdict).
+    Raises on rejection, expiry, or HALT/BLOCK verdict.
+
+    Args:
+        client: The governance HTTP client.
+        params: Identifiers for the pending approval.
+        config: HITL polling configuration (poll_interval_ms).
+
+    Raises:
+        ApprovalExpiredError: When the approval window has expired (server-side).
+        ApprovalRejectedError: When approval is explicitly rejected.
+        GovernanceBlockedError: When verdict is BLOCK.
+    """
+    while True:
+        await asyncio.sleep(config.poll_interval_ms / 1000.0)
+
+        response = await client.poll_approval(
+            ApprovalPollParams(
+                workflow_id=params.workflow_id,
+                run_id=params.run_id,
+                activity_id=params.activity_id,
+            )
+        )
+
+        if response is None:
+            # API unreachable — keep polling (fail-open for HITL)
+            continue
+
+        if response.expired:
+            msg = (
+                f"Approval expired for {params.activity_type} "
+                f"(activity_id={params.activity_id})"
+            )
+            raise ApprovalExpiredError(msg)
+
+        verdict = response.verdict
+        reason = response.reason
+
+        if verdict == Verdict.ALLOW:
+            return
+
+        # HALT or any stop verdict → rejected
+        if verdict_should_stop(verdict):
+            msg = reason or f"Approval rejected for {params.activity_type}"
+            raise ApprovalRejectedError(msg)
+
+        # BLOCK specifically
+        if verdict == Verdict.BLOCK:
+            msg = reason or f"Approval rejected for {params.activity_type}"
+            raise GovernanceBlockedError("block", msg, params.activity_id)
+
+        # Still pending (REQUIRE_APPROVAL / CONSTRAIN) — keep polling