openbox-temporal-sdk-python 1.1.1__py3-none-any.whl → 1.2.0__py3-none-any.whl

openbox/__init__.py

@@ -1,38 +1,28 @@
 """OpenBox SDK - Workflow-Boundary Governance with OpenTelemetry"""
 
-from importlib.metadata import version, PackageNotFoundError
-
-try:
-    __version__ = version("openbox-temporal-sdk-python")
-except PackageNotFoundError:
-    __version__ = "0.0.0"  # Fallback for editable installs without metadata
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# Simple Factories (recommended)
-# ═══════════════════════════════════════════════════════════════════════════════
+# STATIC on purpose — never read via importlib.metadata. A metadata lookup
+# OPENS A FILE; with file instrumentation active (traced_open patches
+# builtins.open + io.open) that read re-enters governance: eagerly at import
+# it crashes the workflow sandbox as a circular import, lazily it recurses
+# unboundedly from build_auth_headers on every evaluate. Keep in sync with
+# pyproject.toml on release.
+__version__ = "1.2.0"
 
 from .worker import create_openbox_worker
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Core Configuration
-# ═══════════════════════════════════════════════════════════════════════════════
-
 from .config import (
     initialize,
     get_global_config,
     GovernanceConfig,
 )
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Errors (unified hierarchy in errors.py)
-# ═══════════════════════════════════════════════════════════════════════════════
-
 from .errors import (
     OpenBoxError,
     OpenBoxConfigError,
     OpenBoxAuthError,
     OpenBoxNetworkError,
     OpenBoxInsecureURLError,
+    OpenBoxSigningError,
     GovernanceBlockedError,
     GovernanceHaltError,
     GovernanceAPIError,
@@ -41,68 +31,40 @@ from .errors import (
     ApprovalRejectedError,
     ApprovalTimeoutError,
     extract_governance_error,
+    map_signing_error,
 )
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Types (sandbox-safe - can be imported in workflow code)
-# ═══════════════════════════════════════════════════════════════════════════════
-
 from .types import (
     Verdict,
     WorkflowEventType,
-    WorkflowSpanBuffer,
     GovernanceVerdictResponse,
     GuardrailsCheckResult,
 )
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Span Processor
-# ═══════════════════════════════════════════════════════════════════════════════
-
-from .span_processor import WorkflowSpanProcessor
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# Interceptors
-# ═══════════════════════════════════════════════════════════════════════════════
+# Multi-agent primitives (sandbox-safe — only imports temporalio.workflow eagerly;
+# signing/HTTP routed lazily through the governance activity).
+from .multi_agent import emit_handoff
 
 from .workflow_interceptor import GovernanceInterceptor
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Plugin (requires temporalio >= 1.24.0)
-# ═══════════════════════════════════════════════════════════════════════════════
-
 try:
     from temporalio.plugin import SimplePlugin  # noqa: F401 — probe only
 
     from .plugin import OpenBoxPlugin
 except ImportError:
-    pass  # temporalio < 1.24.0, plugin not available
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# Verdict Handler
-# ═══════════════════════════════════════════════════════════════════════════════
+    pass  # temporalio < 1.23.0, plugin not available
 
 from .verdict_handler import enforce_verdict, VerdictEnforcementResult
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# HITL — Human-in-the-Loop approval helpers
-# ═══════════════════════════════════════════════════════════════════════════════
-
 from .hitl import handle_approval_response, raise_approval_pending, should_skip_hitl
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Governance HTTP Client (sandbox-safe — httpx imported lazily inside methods)
-# ═══════════════════════════════════════════════════════════════════════════════
-
 from .client import GovernanceClient
 
 # NOTE: ActivityGovernanceInterceptor is NOT imported here because it imports
 # OpenTelemetry which uses importlib_metadata -> os.stat, causing sandbox issues.
 # Users must import directly: from openbox.activity_interceptor import ActivityGovernanceInterceptor
 
-# ═══════════════════════════════════════════════════════════════════════════════
 # Activities - DO NOT import here!
-# ═══════════════════════════════════════════════════════════════════════════════
 #
 # IMPORTANT: Do NOT import activities from openbox/__init__.py!
 # activities.py imports httpx which uses os.stat internally. If we re-export them
@@ -111,25 +73,16 @@ from .client import GovernanceClient
 # Users must import directly:
 #   from openbox.activities import send_governance_event
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# OTel Setup - NOT imported here to avoid sandbox issues!
-# ═══════════════════════════════════════════════════════════════════════════════
+# Instrumentation — owned by the openbox_core base runtime
 #
-# IMPORTANT: Do NOT import otel_setup here!
-# otel_setup imports OpenTelemetry which uses importlib_metadata -> os.stat
-# This triggers Temporal sandbox restrictions.
+# HTTP/DB/file/function hook instrumentation is installed by the base runtime
+# (create_openbox_worker / OpenBoxPlugin call runtime.install_instrumentation()).
+# There is no Temporal-local OpenTelemetry setup to import.
 #
-# Users must import directly: from openbox.otel_setup import setup_opentelemetry_for_governance
-
-# ═══════════════════════════════════════════════════════════════════════════════
 # Tracing Decorators - NOT imported here to avoid sandbox issues!
-# ═══════════════════════════════════════════════════════════════════════════════
-#
-# Use the @traced decorator to capture internal function calls as spans.
-# Import directly: from openbox.tracing import traced, create_span
 #
-# Example:
-#     from openbox.tracing import traced
+# @traced wraps the base SDK's governed() decorator. Import directly:
+#     from openbox.tracing import traced, create_span
 #
 #     @traced
 #     def my_function(data):
@@ -137,20 +90,17 @@ from .client import GovernanceClient
 
 
 __all__ = [
-    # Simple Worker Factory (recommended)
     "create_openbox_worker",
-    # Plugin (recommended for temporalio >= 1.24.0)
     "OpenBoxPlugin",
-    # Configuration
     "initialize",
     "get_global_config",
     "GovernanceConfig",
-    # Errors (unified hierarchy)
     "OpenBoxError",
     "OpenBoxConfigError",
     "OpenBoxAuthError",
     "OpenBoxNetworkError",
     "OpenBoxInsecureURLError",
+    "OpenBoxSigningError",
     "GovernanceBlockedError",
     "GovernanceHaltError",
     "GovernanceAPIError",
@@ -159,23 +109,17 @@ __all__ = [
     "ApprovalRejectedError",
     "ApprovalTimeoutError",
     "extract_governance_error",
-    # Types
+    "map_signing_error",
     "Verdict",
     "WorkflowEventType",
-    "WorkflowSpanBuffer",
     "GovernanceVerdictResponse",
     "GuardrailsCheckResult",
-    # Span Processor
-    "WorkflowSpanProcessor",
-    # Interceptors
+    "emit_handoff",
     "GovernanceInterceptor",
-    # Verdict handler
     "enforce_verdict",
     "VerdictEnforcementResult",
-    # HITL helpers
     "handle_approval_response",
     "raise_approval_pending",
     "should_skip_hitl",
-    # Governance HTTP client
     "GovernanceClient",
 ]

openbox/activities.py

@@ -1,11 +1,9 @@
-# openbox/activities.py
-#
-# IMPORTANT: This module imports httpx which uses os.stat internally.
-# Do NOT import this module from workflow code (workflow_interceptor.py)!
-# The workflow interceptor references this activity by string name "send_governance_event".
 """
 Governance event activity for workflow-level HTTP calls.
 
+NOT sandbox-safe: this module imports httpx. Workflow code references the
+activity by string name instead of importing it.
+
 CRITICAL: Temporal workflows must be deterministic. HTTP calls are NOT allowed directly
 in workflow code (including interceptors). WorkflowInboundInterceptor sends events via
 workflow.execute_activity() using this activity.
@@ -29,13 +27,12 @@ from datetime import datetime, timezone
 from typing import Dict, Any, Optional
 
 
-from .types import rfc3339_now as _rfc3339_now  # shared utility
+from .types import rfc3339_now as _rfc3339_now
 
 from temporalio import activity
 from temporalio.exceptions import ApplicationError
 
 from .types import Verdict
-from .hook_governance import build_auth_headers
 
 logger = logging.getLogger(__name__)
 
@@ -50,7 +47,6 @@ def set_temporal_client(client) -> None:
     _temporal_client = client
 
 
-# Re-export from errors.py for backward compatibility
 from .errors import GovernanceAPIError  # noqa: F401
 
 
@@ -142,60 +138,141 @@ def _handle_api_error(event_type: str, error_msg: str, on_api_error: str) -> dic
     return {"success": False, "error": error_msg}
 
 
-@activity.defn(name="send_governance_event")
-async def send_governance_event(input: Dict[str, Any]) -> Optional[Dict[str, Any]]:
-    """
-    Activity that sends governance events to OpenBox Core.
+class GovernanceActivities:
+    """Container for Temporal activities that need OpenBox credentials.
 
-    Called from WorkflowInboundInterceptor via workflow.execute_activity()
-    to maintain workflow determinism.
+    Credentials live on the instance (never in activity inputs → never in
+    workflow history → not visible to anyone with namespace read access).
+    The worker registers bound methods of a single instance, created at
+    worker-init time by the plugin / create_openbox_worker factory.
     """
-    api_url = input.get("api_url", "")
-    api_key = input.get("api_key", "")
-    event_payload = input.get("payload", {})
-    timeout = input.get("timeout", 30.0)
-    on_api_error = input.get("on_api_error", "fail_open")
-
-    # Add timestamp in activity context (non-deterministic code allowed)
-    payload = {**event_payload, "timestamp": _rfc3339_now()}
-    event_type = event_payload.get("event_type", "unknown")
-
-    try:
-        async with httpx.AsyncClient(timeout=timeout) as client:
-            response = await client.post(
-                f"{api_url}/api/v1/governance/evaluate",
-                json=payload,
-                headers=build_auth_headers(api_key),
-            )
-
-            if response.status_code != 200:
-                return _handle_api_error(
-                    event_type,
-                    f"HTTP {response.status_code}: {response.text}",
-                    on_api_error,
+
+    def __init__(self, api_url: str, api_key: str, *, agent_did=None, signer=None):
+        self._api_url = api_url.rstrip("/")
+        self._api_key = api_key
+        # AIP signing material — held on the instance so it never flows through
+        # activity inputs / workflow history.
+        self._agent_did = agent_did
+        self._signer = signer
+
+    @activity.defn(name="send_governance_event")
+    async def send_governance_event(
+        self, input: Dict[str, Any]
+    ) -> Optional[Dict[str, Any]]:
+        """Send a governance event to OpenBox Core.
+
+        Called from WorkflowInboundInterceptor via workflow.execute_activity()
+        to maintain workflow determinism. The `input` dict carries only the
+        event payload and per-call policy — never credentials.
+        """
+        event_payload = input.get("payload", {})
+        timeout = input.get("timeout", 30.0)
+        on_api_error = input.get("on_api_error", "fail_open")
+
+        # Add timestamp in activity context (non-deterministic code allowed)
+        payload = {**event_payload, "timestamp": _rfc3339_now()}
+        event_type = event_payload.get("event_type", "unknown")
+
+        # Sign once over the exact bytes we transmit (timestamp included).
+        from .request_signing import prepare_signed_request
+
+        headers, body = prepare_signed_request(
+            "POST",
+            "/api/v1/governance/evaluate",
+            payload,
+            api_key=self._api_key,
+            agent_did=self._agent_did,
+            signer=self._signer,
+        )
+
+        try:
+            async with httpx.AsyncClient(timeout=timeout) as client:
+                response = await client.post(
+                    f"{self._api_url}/api/v1/governance/evaluate",
+                    content=body,
+                    headers=headers,
                 )
 
-            data = response.json()
-            verdict = Verdict.from_string(
-                data.get("verdict") or data.get("action", "continue")
-            )
-            reason = data.get("reason")
-            policy_id = data.get("policy_id")
-            risk_score = data.get("risk_score", 0.0)
-
-            if verdict.should_stop():
-                result = await _handle_stop_verdict(
-                    verdict, reason, policy_id, risk_score, event_type, event_payload
+                if response.status_code != 200:
+                    return _handle_api_error(
+                        event_type,
+                        f"HTTP {response.status_code}: {response.text}",
+                        on_api_error,
+                    )
+
+                data = response.json()
+                verdict = Verdict.from_string(
+                    data.get("verdict") or data.get("action", "continue")
                 )
-                if result:
-                    return result
-
-            return _build_verdict_result(verdict, reason, policy_id, risk_score)
-
-    except (GovernanceAPIError, ApplicationError):
-        raise
-    except Exception as e:
-        logger.warning(f"Failed to send {event_type} event: {e}")
-        if on_api_error == "fail_closed":
-            raise GovernanceAPIError(str(e))
-        return {"success": False, "error": str(e)}
+                reason = data.get("reason")
+                policy_id = data.get("policy_id")
+                risk_score = data.get("risk_score", 0.0)
+
+                if verdict.should_stop():
+                    result = await _handle_stop_verdict(
+                        verdict,
+                        reason,
+                        policy_id,
+                        risk_score,
+                        event_type,
+                        event_payload,
+                    )
+                    if result:
+                        return result
+
+                return _build_verdict_result(verdict, reason, policy_id, risk_score)
+
+        except (GovernanceAPIError, ApplicationError):
+            raise
+        except Exception as e:
+            logger.warning(f"Failed to send {event_type} event: {e}")
+            if on_api_error == "fail_closed":
+                raise GovernanceAPIError(str(e))
+            return {"success": False, "error": str(e)}
+
+
+def build_governance_activities(
+    api_url: str,
+    api_key: str,
+    *,
+    agent_did=None,
+    signer=None,
+) -> GovernanceActivities:
+    """Factory used by plugin.py and worker.py to build the activities instance.
+
+    agent_did + signer enable AIP signed requests; both stay on the instance
+    (never in inputs).
+    """
+    # Fall back to the globally-configured signer/DID when omitted (manual setups),
+    # so workflow/signal events routed through this activity are signed too.
+    from .config import resolve_signing_defaults
+
+    agent_did, signer = resolve_signing_defaults(agent_did, signer)
+    return GovernanceActivities(
+        api_url=api_url,
+        api_key=api_key,
+        agent_did=agent_did,
+        signer=signer,
+    )
+
+
+# Backward-compat module-level helper.
+#
+# Not decorated with @activity.defn — worker/plugin register the class-based
+# version above so credentials never flow through activity inputs. This shim
+# exists for direct callers (tests, scripts) who already hold credentials and
+# want to invoke the HTTP logic without constructing the class themselves.
+async def send_governance_event(input: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    """Backward-compat wrapper — delegates to GovernanceActivities.
+
+    Tests and direct callers can keep passing api_url/api_key in the input
+    dict. The class-based activity registered with the worker does NOT see
+    these fields (it reads credentials from self), so nothing written to
+    workflow history ever carries the API key.
+    """
+    instance = GovernanceActivities(
+        api_url=input.get("api_url", ""),
+        api_key=input.get("api_key", ""),
+    )
+    forwarded = {k: v for k, v in input.items() if k not in ("api_url", "api_key")}
+    return await instance.send_governance_event(forwarded)