openbox-temporal-sdk-python 1.1.2__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,36 +31,22 @@ 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.23.0)
-# ═══════════════════════════════════════════════════════════════════════════════
-
 try:
     from temporalio.plugin import SimplePlugin  # noqa: F401 — probe only
 
@@ -78,31 +54,17 @@ try:
 except ImportError:
     pass  # temporalio < 1.23.0, plugin not available
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Verdict Handler
-# ═══════════════════════════════════════════════════════════════════════════════
-
 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.23.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
 
 
@@ -151,9 +147,13 @@ class GovernanceActivities:
     worker-init time by the plugin / create_openbox_worker factory.
     """
 
-    def __init__(self, api_url: str, api_key: str):
+    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(
@@ -173,12 +173,24 @@ class GovernanceActivities:
         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",
-                    json=payload,
-                    headers=build_auth_headers(self._api_key),
+                    content=body,
+                    headers=headers,
                 )
 
                 if response.status_code != 200:
@@ -220,20 +232,36 @@ class GovernanceActivities:
 
 
 def build_governance_activities(
-    api_url: str, api_key: str
+    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."""
-    return GovernanceActivities(api_url=api_url, api_key=api_key)
+    """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.