openbox-langgraph-sdk-python 1.0.0__py3-none-any.whl → 1.1.0__py3-none-any.whl

openbox_langgraph/__init__.py

@@ -17,7 +17,7 @@ Example:
     ... )
 """
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 
 from openbox_langgraph.client import GovernanceClient, build_auth_headers
 from openbox_langgraph.config import (
@@ -38,6 +38,7 @@ from openbox_langgraph.errors import (
     OpenBoxError,
     OpenBoxInsecureURLError,
     OpenBoxNetworkError,
+    OpenBoxSigningError,
 )
 from openbox_langgraph.hitl import poll_until_decision
 from openbox_langgraph.identity import (
@@ -112,6 +113,7 @@ __all__ = [
     "OpenBoxLangGraphHandler",
     "OpenBoxLangGraphHandlerOptions",
     "OpenBoxNetworkError",
+    "OpenBoxSigningError",
     "Verdict",
     "VerdictContext",
     "WorkflowEventType",

openbox_langgraph/client.py

@@ -13,14 +13,20 @@ from openbox_core.contracts.results import EvaluationResult
 from openbox_core.contracts.results import Verdict as _CoreVerdict
 from openbox_core.errors import ContractError as _CoreContractError
 from openbox_core.errors import GovernanceAPIError as _CoreGovernanceAPIError
-from openbox_core.errors import OpenBoxNetworkError as _CoreOpenBoxNetworkError
+from openbox_core.errors import OpenBoxConfigError as _CoreOpenBoxConfigError
 
 from openbox_langgraph.core_events import to_envelope
-from openbox_langgraph.errors import OpenBoxConfigError, OpenBoxNetworkError
+from openbox_langgraph.errors import (
+    OpenBoxConfigError,
+    OpenBoxError,
+    OpenBoxNetworkError,
+    _raise_core_error,
+)
 from openbox_langgraph.identity import (
     AgentIdentityConfig,
     create_agent_identity_headers,
     parse_optional_agent_identity_config,
+    parse_optional_workload_private_key,
 )
 from openbox_langgraph.types import (
     ApprovalResponse,
@@ -32,9 +38,10 @@ from openbox_langgraph.types import (
 )
 
 if TYPE_CHECKING:
+    from openbox_core.client import EvaluationClient
     from openbox_core.gate import GovernanceGate
 
-_SDK_PACKAGE_VERSION = "1.0.0"
+_SDK_PACKAGE_VERSION = "1.1.0"
 _SDK_IDENTIFIER = f"openbox-langgraph-python-v{_SDK_PACKAGE_VERSION}"
 
 
@@ -114,9 +121,11 @@ async def _gate_evaluate(
       independent of `on_api_error`. Enforcing fail_closed here would let an
       SDK-side mapping defect block a user's graph for a reason their OWN policy
       never produced — strictly worse than dropping one governance event.
-    - `GovernanceAPIError` / `OpenBoxNetworkError` (network-shaped failure) ->
-      this SDK's `OpenBoxNetworkError`, same public exception the legacy path
-      raises under fail_closed.
+    - Base authentication, signing, and configuration errors always propagate
+      through this SDK's public errors, including under fail_open.
+    - `GovernanceAPIError` / `OpenBoxNetworkError` -> this SDK's
+      `OpenBoxNetworkError`. Bootstrap/token-exchange failures must propagate;
+      the base client applies fail_open only to ordinary governance transport errors.
     - Any OTHER exception (e.g. a malformed Core 200 body the base parser
       cannot decode) is a transport-shaped fault, NOT a governance verdict:
       routed through `_network_fallback_result` so fail_open returns `None`
@@ -127,8 +136,8 @@ async def _gate_evaluate(
         result = await gate.aevaluate(to_envelope(event))
     except _CoreContractError:
         return None
-    except (_CoreGovernanceAPIError, _CoreOpenBoxNetworkError) as e:
-        raise OpenBoxNetworkError(str(e)) from e
+    except (_CoreGovernanceAPIError, _CoreOpenBoxConfigError) as e:
+        _raise_core_error(e)
     except Exception as e:
         return _network_fallback_result(on_api_error, f"Governance gate error: {e}")
     return _collapse_client_synthesized_fallback(result)
@@ -144,7 +153,8 @@ def build_auth_headers(
 ) -> dict[str, str]:
     """Build standard auth headers for governance API calls.
 
-    Single source of truth for the SDK's outbound governance requests.
+    Compatibility helper for API-key/DID requests. Workload headers are composed
+    by the base SDK after bootstrap and token exchange.
     """
     headers = {
         "Authorization": f"Bearer {api_key}",
@@ -194,6 +204,8 @@ class GovernanceClient:
         agent_did: str | None = None,
         agent_private_key: str | None = None,
         gate: GovernanceGate | None = None,
+        workload_private_key: str | None = None,
+        core_client: EvaluationClient | None = None,
     ) -> None:
         self._api_url = api_url.rstrip("/")
         self._api_key = api_key
@@ -205,13 +217,37 @@ class GovernanceClient:
             did=agent_did,
             private_key=agent_private_key,
         )
+        workload_private_key = parse_optional_workload_private_key(workload_private_key)
+        self._core_client = core_client
+        self._owns_core_client = core_client is None and workload_private_key is not None
+        if self._owns_core_client:
+            from openbox_core.client import EvaluationClient
+            from openbox_core.identity import AgentIdentity
+
+            self._core_client = EvaluationClient(
+                self._api_url,
+                self._api_key,
+                timeout_seconds=timeout,
+                on_api_error=on_api_error,
+                identity=(
+                    AgentIdentity.from_private_key(
+                        self._agent_identity.did, self._agent_identity.private_key
+                    )
+                    if self._agent_identity
+                    else None
+                ),
+                workload_private_key=workload_private_key,
+                sdk_version=_SDK_PACKAGE_VERSION,
+                sdk_engine="langgraph",
+            )
         # Optional base-SDK gate. When wired (by the handler, from a core
         # runtime built off the SAME api_url/api_key/timeout/on_api_error),
         # `evaluate_event`'s ASYNC path routes lifecycle events through it
         # instead of this client's own httpx transport — see `evaluate_event`.
         # `None` (the default) preserves the exact legacy transport/serialization
         # for every existing caller that constructs a bare `GovernanceClient()`.
-        # `evaluate_event_sync` (sync middleware hooks) is unaffected either way.
+        # The handler also lends its runtime client for sync/raw calls and
+        # approval polling, so every path shares the same workload token cache.
         self._gate = gate
         # Deduplication: prevent sending the same (activity_id, event_type) twice
         # within the same workflow run. Keyed by (workflow_id, run_id) so it resets
@@ -234,7 +270,9 @@ class GovernanceClient:
         return self._sync_client
 
     async def close(self) -> None:
-        """Close the underlying HTTP clients."""
+        """Close owned HTTP clients; a borrowed runtime client belongs to its runtime."""
+        if self._owns_core_client and self._core_client is not None:
+            await self._core_client.aclose()
         if self._client and not self._client.is_closed:
             await self._client.aclose()
         self._client = None
@@ -255,6 +293,13 @@ class GovernanceClient:
         """
         from openbox_langgraph.errors import OpenBoxAuthError
 
+        if self._core_client is not None:
+            try:
+                await self._core_client.avalidate_api_key()
+            except _CoreOpenBoxConfigError as exc:
+                _raise_core_error(exc)
+            return
+
         try:
             client = self._get_client()
             response = await client.get(
@@ -341,13 +386,25 @@ class GovernanceClient:
             )
 
         if self._gate is not None:
-            return await _gate_evaluate(self._gate, event, self._on_api_error)
+            try:
+                return await _gate_evaluate(self._gate, event, self._on_api_error)
+            except OpenBoxError:
+                self._forget_failed_event(event, server_event_type)
+                raise
 
         payload = event.to_dict()
         payload["event_type"] = server_event_type
         payload["task_queue"] = event.task_queue or "langgraph"
         payload["source"] = "workflow-telemetry"
 
+        if self._core_client is not None:
+            try:
+                result = await self._core_client.aevaluate(payload)
+            except (_CoreOpenBoxConfigError, _CoreGovernanceAPIError) as exc:
+                self._forget_failed_event(event, server_event_type)
+                _raise_core_error(exc)
+            return _collapse_client_synthesized_fallback(result)
+
         try:
             client = self._get_client()
             body = _json_body(payload)
@@ -372,9 +429,7 @@ class GovernanceClient:
         except OpenBoxNetworkError:
             raise
         except Exception as e:
-            return _network_fallback_result(
-                self._on_api_error, f"Governance API unreachable: {e}"
-            )
+            return _network_fallback_result(self._on_api_error, f"Governance API unreachable: {e}")
 
     def evaluate_event_sync(
         self, event: LangChainGovernanceEvent
@@ -395,6 +450,14 @@ class GovernanceClient:
         payload["task_queue"] = event.task_queue or "langgraph"
         payload["source"] = "workflow-telemetry"
 
+        if self._core_client is not None:
+            try:
+                result = self._core_client.evaluate(payload)
+            except (_CoreOpenBoxConfigError, _CoreGovernanceAPIError) as exc:
+                self._forget_failed_event(event, server_event_type)
+                _raise_core_error(exc)
+            return _collapse_client_synthesized_fallback(result)
+
         if os.environ.get("OPENBOX_DEBUG") == "1":
             import json
 
@@ -427,18 +490,26 @@ class GovernanceClient:
         except OpenBoxNetworkError:
             raise
         except Exception as e:
-            return _network_fallback_result(
-                self._on_api_error, f"Governance API unreachable: {e}"
-            )
+            return _network_fallback_result(self._on_api_error, f"Governance API unreachable: {e}")
 
     async def poll_approval(self, params: ApprovalPollParams) -> ApprovalResponse | None:
         """Poll for HITL approval status.
 
-        Returns `None` on network failure so the caller can retry.
+        Returns `None` on ordinary polling transport failure so the caller can retry.
+        Workload authentication and bootstrap failures always raise.
 
         Args:
             params: Identifiers for the pending approval.
         """
+        if self._core_client is not None:
+            try:
+                result = await self._core_client.apoll_approval(
+                    params.workflow_id, params.run_id, params.activity_id
+                )
+            except _CoreOpenBoxConfigError as exc:
+                _raise_core_error(exc)
+            return ApprovalResponse.from_result(result) if result is not None else None
+
         try:
             client = self._get_client()
             body = _json_body(
@@ -482,8 +553,17 @@ class GovernanceClient:
         by the caller (no event_type translation needed).
 
         Args:
-            payload: The raw dict to POST to `/api/v1/governance/evaluate`.
+            payload: The raw dict to POST to the identity-appropriate evaluate route.
         """
+        if self._core_client is not None:
+            try:
+                result = await self._core_client.aevaluate(payload)
+            except (_CoreOpenBoxConfigError, _CoreGovernanceAPIError) as exc:
+                _raise_core_error(exc)
+            if _collapse_client_synthesized_fallback(result) is None:
+                return None
+            return dict(result.raw)
+
         if os.environ.get("OPENBOX_DEBUG") == "1":
             import json
 
@@ -535,6 +615,11 @@ class GovernanceClient:
     # Private helpers
     # ─────────────────────────────────────────────────────────────
 
+    def _forget_failed_event(self, event: LangChainGovernanceEvent, event_type: str) -> None:
+        """A caller retrying a rejected event must authenticate again, never dedup to ALLOW."""
+        if event.activity_id and self._dedup_run == (event.workflow_id, event.run_id):
+            self._dedup_sent.discard((event.activity_id, event_type))
+
     def _headers(self, *, method: str, pathname: str, body: bytes | str | None) -> dict[str, str]:
         return build_auth_headers(
             self._api_key,

openbox_langgraph/config.py

@@ -14,10 +14,12 @@ from openbox_langgraph.errors import (
     OpenBoxConfigError,
     OpenBoxInsecureURLError,
     OpenBoxNetworkError,
+    _raise_core_error,
 )
 from openbox_langgraph.identity import (
     AgentIdentityConfig,
     parse_optional_agent_identity_config,
+    parse_optional_workload_private_key,
 )
 from openbox_langgraph.types import DEFAULT_HITL_CONFIG, HITLConfig
 
@@ -193,6 +195,7 @@ class _GlobalConfigState:
     governance_timeout: float = 30.0  # seconds
     agent_did: str | None = None
     agent_private_key: str | None = None
+    workload_private_key: str | None = field(default=None, repr=False)
 
     def configure(
         self,
@@ -200,12 +203,14 @@ class _GlobalConfigState:
         api_key: str,
         governance_timeout: float = 30.0,
         agent_identity: AgentIdentityConfig | None = None,
+        workload_private_key: str | None = None,
     ) -> None:
         self.api_url = api_url.rstrip("/")
         self.api_key = api_key
         self.governance_timeout = governance_timeout
         self.agent_did = agent_identity.did if agent_identity else None
         self.agent_private_key = agent_identity.private_key if agent_identity else None
+        self.workload_private_key = workload_private_key
 
     def __repr__(self) -> str:
         if self.api_key and len(self.api_key) > 8:
@@ -293,6 +298,41 @@ def _validate_api_key_with_server(
 # ═══════════════════════════════════════════════════════════════════
 
 
+def _validate_workload_identity_with_server(
+    api_url: str,
+    api_key: str,
+    timeout: float,
+    workload_private_key: str,
+    agent_identity: AgentIdentityConfig | None,
+) -> None:
+    """Let the base SDK bootstrap, exchange a token, and validate the active identity."""
+    from openbox_core.client import EvaluationClient
+    from openbox_core.errors import OpenBoxConfigError as CoreOpenBoxConfigError
+    from openbox_core.identity import AgentIdentity
+
+    from openbox_langgraph.client import _SDK_PACKAGE_VERSION
+
+    client = EvaluationClient(
+        api_url,
+        api_key,
+        timeout_seconds=timeout,
+        workload_private_key=workload_private_key,
+        identity=(
+            AgentIdentity.from_private_key(agent_identity.did, agent_identity.private_key)
+            if agent_identity
+            else None
+        ),
+        sdk_version=_SDK_PACKAGE_VERSION,
+        sdk_engine="langgraph",
+    )
+    try:
+        client.validate_api_key()
+    except CoreOpenBoxConfigError as exc:
+        _raise_core_error(exc)
+    finally:
+        client.close()
+
+
 def initialize(
     api_url: str,
     api_key: str,
@@ -300,6 +340,7 @@ def initialize(
     validate: bool = True,
     agent_did: str | None = None,
     agent_private_key: str | None = None,
+    workload_private_key: str | None = None,
 ) -> None:
     """Initialize the OpenBox LangGraph SDK with credentials.
 
@@ -314,6 +355,8 @@ def initialize(
         agent_did: Optional OpenBox agent DID. Falls back to `OPENBOX_AGENT_DID`.
         agent_private_key: Optional raw Ed25519 private key seed. Falls back to
             `OPENBOX_AGENT_PRIVATE_KEY`.
+        workload_private_key: PKCS8 PEM RSA key for IAM v3. Falls back to
+            `OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY`, then `OPENBOX_WORKLOAD_PRIVATE_KEY`.
     """
     import os
 
@@ -337,7 +380,17 @@ def initialize(
     except OpenBoxConfigError:
         raise
 
-    if validate:
+    if workload_private_key is None:
+        workload_private_key = os.environ.get(
+            "OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY", os.environ.get("OPENBOX_WORKLOAD_PRIVATE_KEY")
+        )
+    workload_private_key = parse_optional_workload_private_key(workload_private_key)
+
+    if validate and workload_private_key is not None:
+        _validate_workload_identity_with_server(
+            api_url.rstrip("/"), api_key, governance_timeout, workload_private_key, agent_identity
+        )
+    elif validate:
         _validate_api_key_with_server(
             api_url.rstrip("/"),
             api_key,
@@ -350,6 +403,7 @@ def initialize(
         api_key,
         governance_timeout,
         agent_identity,
+        workload_private_key,
     )
 
     _get_logger().info(f"OpenBox LangGraph SDK initialized with API URL: {api_url}")

openbox_langgraph/core_adapter.py

@@ -92,7 +92,9 @@ class LangGraphFrameworkAdapter:
 
     # ── Approval (RAISE-ONLY — never an inline blocking wait) ──────────────
 
-    async def handle_approval(self, result: EvaluationResult) -> None:
+    async def handle_approval(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
         """Async started-hook REQUIRE_APPROVAL -> raise, never await inline.
 
         The base ``HookRuntime._adecide_started`` treats a normal RETURN as
@@ -100,7 +102,8 @@ class LangGraphFrameworkAdapter:
         signal for a ``requires_approval()`` verdict, so the handler's outer
         catch/poll/retry loop drives the approval flow.
         """
-        self._raise_pending_approval(result, self._store.current_activity_context())
+        ctx = context if context is not None else self._store.current_activity_context()
+        self._raise_pending_approval(result, ctx)
 
     def handle_approval_sync(
         self, result: EvaluationResult, *, context: ActivityContext | None = None
@@ -138,7 +141,9 @@ class LangGraphFrameworkAdapter:
 
     # ── Completed-hook telemetry (never undoes the operation) ──────────────
 
-    def on_completed_hook_result(self, result: EvaluationResult) -> None:
+    def on_completed_hook_result(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
         """Completed verdicts affect FUTURE execution only — the operation
         already ran. ``HookRuntime._after_completed`` has already marked the
         abort/halt flags on the base ``ContextStore`` for a stop-shaped

openbox_langgraph/core_runtime.py

@@ -42,6 +42,7 @@ from openbox_core.runtime import OpenBoxRuntime
 
 from openbox_langgraph.config import GovernanceConfig
 from openbox_langgraph.errors import OpenBoxConfigError
+from openbox_langgraph.identity import parse_optional_workload_private_key
 from openbox_langgraph.trace_context_registry import (
     TraceContextRegistry,
     get_context_store,
@@ -53,7 +54,7 @@ from openbox_langgraph.trace_context_registry import (
 CORE_ENV_PREFIX = "OPENBOX_LANGGRAPH"
 SDK_ENGINE = "langgraph"
 SDK_LANGUAGE = "python"
-SDK_PACKAGE_VERSION = "1.0.0"
+SDK_PACKAGE_VERSION = "1.1.0"
 
 __all__ = [
     "CORE_ENV_PREFIX",
@@ -72,6 +73,7 @@ def create_core_runtime(
     governance_timeout: float | None = None,
     agent_did: str | None = None,
     agent_private_key: str | None = None,
+    workload_private_key: str | None = None,
     extra_ignored_urls: set[str] | None = None,
 ) -> OpenBoxRuntime:
     """Resolve base-SDK config and build an isolated ``OpenBoxRuntime``.
@@ -124,11 +126,15 @@ def create_core_runtime(
         agent_name=config.agent_name,
         agent_did=agent_did,
         agent_private_key=agent_private_key,
+        workload_private_key=workload_private_key,
         sdk_version=SDK_PACKAGE_VERSION,
         sdk_engine=SDK_ENGINE,
         sdk_language=SDK_LANGUAGE,
         validate=True,
     )
+    core_config.workload_private_key = parse_optional_workload_private_key(
+        core_config.workload_private_key
+    )
 
     from openbox_core.context import ContextStore
     from openbox_core.instrumentation.manager import InstrumentationManager

openbox_langgraph/errors.py

@@ -2,13 +2,23 @@
 
 from __future__ import annotations
 
+from typing import NoReturn
+
 
 class OpenBoxError(Exception):
     """Base class for all OpenBox SDK errors."""
 
 
 class OpenBoxAuthError(OpenBoxError):
-    """Raised when the API key is invalid or unauthorized."""
+    """Raised when the API key or workload identity is invalid or unauthorized."""
+
+
+class OpenBoxSigningError(OpenBoxAuthError):
+    """Identity proof rejected by Core, with its machine-readable reason code."""
+
+    def __init__(self, message: str, reason_code: str | None = None) -> None:
+        self.reason_code = reason_code
+        super().__init__(message)
 
 
 class OpenBoxConfigError(OpenBoxError):
@@ -23,6 +33,25 @@ class OpenBoxInsecureURLError(OpenBoxError):
     """Raised when an insecure HTTP URL is used for a non-localhost endpoint."""
 
 
+def _raise_core_error(exc: Exception) -> NoReturn:
+    """Keep base-SDK auth/configuration failures in this SDK's public hierarchy."""
+    from openbox_core.errors import GovernanceAPIError as CoreGovernanceAPIError
+    from openbox_core.errors import OpenBoxAuthError as CoreOpenBoxAuthError
+    from openbox_core.errors import OpenBoxConfigError as CoreOpenBoxConfigError
+    from openbox_core.errors import OpenBoxNetworkError as CoreOpenBoxNetworkError
+    from openbox_core.errors import OpenBoxSigningError as CoreOpenBoxSigningError
+
+    if isinstance(exc, CoreOpenBoxSigningError):
+        raise OpenBoxSigningError(str(exc), exc.reason_code) from exc
+    if isinstance(exc, CoreOpenBoxAuthError):
+        raise OpenBoxAuthError(str(exc)) from exc
+    if isinstance(exc, (CoreOpenBoxNetworkError, CoreGovernanceAPIError)):
+        raise OpenBoxNetworkError(str(exc)) from exc
+    if isinstance(exc, CoreOpenBoxConfigError):
+        raise OpenBoxConfigError(str(exc)) from exc
+    raise exc
+
+
 class GovernanceBlockedError(OpenBoxError):
     """Raised when governance returns a BLOCK or HALT verdict.
 

openbox_langgraph/identity.py

@@ -46,6 +46,20 @@ class AgentIdentityConfig:
 AgentIdentityHeaders = dict[str, str]
 
 
+def parse_optional_workload_private_key(private_key: str | None) -> str | None:
+    """Validate a workload key locally, including when startup validation is off."""
+    if private_key is None:
+        return None
+    from openbox_core.identity_okta import load_rsa_pkcs8_private_key
+
+    normalized = private_key.strip()
+    try:
+        load_rsa_pkcs8_private_key(normalized, key_label="workload_private_key")
+    except CoreOpenBoxConfigError as exc:
+        raise OpenBoxConfigError(str(exc)) from exc
+    return normalized
+
+
 def build_agent_identity_canonical_request(
     *,
     body_sha256: str,

openbox_langgraph/langgraph_handler.py

@@ -19,6 +19,7 @@ from collections.abc import AsyncGenerator, AsyncIterator, Callable
 from dataclasses import dataclass, field
 from typing import Any, cast
 
+from openbox_core.errors import OpenBoxConfigError as _CoreOpenBoxConfigError
 from openbox_langchain import (
     ActivityBridge,
     OpenBoxLangChainCoreAsyncCallbackHandler,
@@ -45,6 +46,7 @@ from openbox_langgraph.errors import (
     GovernanceBlockedError,
     GovernanceHaltError,
     GuardrailsValidationError,
+    _raise_core_error,
 )
 from openbox_langgraph.hitl import HITLPollParams, poll_until_decision
 from openbox_langgraph.tool_activity_binding import bind_tools_activity_scope, turn_metadata
@@ -388,6 +390,7 @@ class OpenBoxLangGraphHandler:
                 governance_timeout=gc.governance_timeout,
                 agent_did=gc.agent_did,
                 agent_private_key=gc.agent_private_key,
+                workload_private_key=gc.workload_private_key,
                 extra_ignored_urls={gc.api_url} if gc.api_url else None,
             )
             self._client = GovernanceClient(
@@ -398,6 +401,7 @@ class OpenBoxLangGraphHandler:
                 agent_did=gc.agent_did,
                 agent_private_key=gc.agent_private_key,
                 gate=self._core_runtime.gate,
+                core_client=self._core_runtime.client,
             )
             # C1 — install condition == prepare condition: the pure-LangChain-Core
             # callback (installed per-turn in `_governed_config`) is only ever
@@ -921,6 +925,8 @@ class OpenBoxLangGraphHandler:
             _logger.info("[OpenBox] Approval granted, retrying ainvoke")
             self._reset_after_approval(workflow_id)
             final_output = await self._graph.ainvoke(input, config=cfg, **kwargs)
+        except _CoreOpenBoxConfigError as exc:
+            _raise_core_error(exc)
         except Exception as exc:
             hook_err = _extract_governance_blocked(exc)
             if hook_err is None or hook_err.verdict != "require_approval":
@@ -1006,6 +1012,8 @@ class OpenBoxLangGraphHandler:
                     pre_screen_claim=pre_screen_claim,
                 )
                 yield event
+        except _CoreOpenBoxConfigError as exc:
+            _raise_core_error(exc)
         finally:
             # Outermost `finally` on an async generator fires on normal
             # exhaustion, an exception raised through the loop, OR the
@@ -1094,6 +1102,8 @@ class OpenBoxLangGraphHandler:
                     workflow_started_sent=workflow_started_sent,
                 )
                 yield event
+        except _CoreOpenBoxConfigError as exc:
+            _raise_core_error(exc)
         finally:
             # See astream_governed's identical finally for why this covers
             # normal exhaustion, mid-stream exceptions, AND an abandoned
@@ -1981,6 +1991,7 @@ def create_openbox_graph_handler(
     sqlalchemy_engine: Any = None,
     agent_did: str | None = None,
     agent_private_key: str | None = None,
+    workload_private_key: str | None = None,
     **handler_kwargs: Any,
 ) -> OpenBoxLangGraphHandler:
     """Create a fully configured `OpenBoxLangGraphHandler` wrapping a compiled LangGraph graph.
@@ -2000,6 +2011,8 @@ def create_openbox_graph_handler(
         agent_did: Optional OpenBox agent DID. Falls back to `OPENBOX_AGENT_DID`.
         agent_private_key: Optional raw Ed25519 private key seed. Falls back to
             `OPENBOX_AGENT_PRIVATE_KEY`.
+        workload_private_key: PKCS8 PEM RSA key for IAM v3. Falls back to
+            `OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY`, then `OPENBOX_WORKLOAD_PRIVATE_KEY`.
         **handler_kwargs: Additional keyword arguments forwarded to
             `OpenBoxLangGraphHandlerOptions`.
 
@@ -2023,6 +2036,7 @@ def create_openbox_graph_handler(
         validate=validate,
         agent_did=agent_did,
         agent_private_key=agent_private_key,
+        workload_private_key=workload_private_key,
     )
 
     options = OpenBoxLangGraphHandlerOptions(

openbox_langgraph/langgraph_hook_runtime.py

@@ -35,10 +35,13 @@ from typing import Any
 from openbox_core.context import activity_scope
 from openbox_core.contracts.context import ActivityContext
 from openbox_core.contracts.otel_spans import HookType
+from openbox_core.errors import OpenBoxConfigError as _CoreOpenBoxConfigError
 from openbox_core.hooks.events import resolve_context
 from openbox_core.hooks.preflight import HookRuntime
 from openbox_core.otel.trace_context import raw_trace_id
 
+from openbox_langgraph.errors import _raise_core_error
+
 __all__ = ["LangGraphHookRuntime"]
 
 # Bound on in-flight pins. A pin is normally cleared at completed (or when
@@ -139,6 +142,9 @@ class LangGraphHookRuntime(HookRuntime):
             proceed = super().preflight(
                 span, hook_type=hook_type, identifier=identifier, fields=fields
             )
+        except _CoreOpenBoxConfigError as exc:
+            self._unpin(key)
+            _raise_core_error(exc)
         except BaseException:
             # Blocked / halted / approval-rejected: no completed callback will
             # follow, so drop the pin rather than leak it.
@@ -161,6 +167,9 @@ class LangGraphHookRuntime(HookRuntime):
             proceed = await super().apreflight(
                 span, hook_type=hook_type, identifier=identifier, fields=fields
             )
+        except _CoreOpenBoxConfigError as exc:
+            self._unpin(key)
+            _raise_core_error(exc)
         except BaseException:
             self._unpin(key)
             raise

{openbox_langgraph_sdk_python-1.0.0.dist-info → openbox_langgraph_sdk_python-1.1.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openbox-langgraph-sdk-python
-Version: 1.0.0
+Version: 1.1.0
 Summary: OpenBox governance and observability SDK for LangGraph
 License: MIT
 License-File: LICENSE
@@ -10,7 +10,7 @@ Requires-Dist: langchain-core>=1.3.3
 Requires-Dist: langgraph>=0.2.0
 Requires-Dist: langsmith>=0.8.18
 Requires-Dist: openbox-langchain-sdk-python>=1.0.0
-Requires-Dist: openbox-sdk-python>=1.0.1
+Requires-Dist: openbox-sdk-python>=1.4.0
 Requires-Dist: opentelemetry-api>=1.20.0
 Requires-Dist: opentelemetry-instrumentation-asyncpg>=0.41b0
 Requires-Dist: opentelemetry-instrumentation-httpx>=0.41b0
@@ -136,17 +136,14 @@ uv add openbox-langgraph-sdk-python
 
 ### 1. Get your agent credentials
 
-Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy the agent API key plus its DID credentials.
-
-New OpenBox agents have DID signing enabled by default. Keep the private key secret and load it from your environment.
+Sign in to [dashboard.openbox.ai](https://dashboard.openbox.ai), create an agent called `"MyAgent"`, and copy its API key. For an IAM v3 workload-enabled agent, also load the PKCS8 PEM RSA private key registered for its active Keycloak service account. Keep the key secret.
 
 ### 2. Set environment variables
 
 ```bash
 export OPENBOX_URL="https://core.openbox.ai"
 export OPENBOX_API_KEY="obx_live_..."
-export OPENBOX_AGENT_DID="did:aip:..."
-export OPENBOX_AGENT_PRIVATE_KEY="..."
+export OPENBOX_WORKLOAD_PRIVATE_KEY="$(cat /path/to/workload-private-key.pem)"
 ```
 
 ### 3. Wrap your graph
@@ -181,6 +178,50 @@ asyncio.run(main())
 
 That's it. Your agent now sends governance events to OpenBox on every tool call, LLM prompt, HTTP request, and database query.
 
+### IAM v3 workload identity
+
+IAM v3 is provided by `openbox-sdk-python>=1.4.0`. The existing
+`openbox-langchain-sdk-python` dependency remains at `>=1.0.0`; its callbacks
+use the same base runtime as the LangGraph handler and operation hooks.
+
+You can pass the workload key explicitly instead of setting an environment variable:
+
+```python
+governed = create_openbox_graph_handler(
+    graph=agent,
+    api_url=os.environ["OPENBOX_URL"],
+    api_key=os.environ["OPENBOX_API_KEY"],
+    workload_private_key=os.environ["OPENBOX_WORKLOAD_PRIVATE_KEY"],
+)
+```
+
+Key resolution is explicit argument, then `OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY`,
+then `OPENBOX_WORKLOAD_PRIVATE_KEY`. The value is the PEM contents, not a file path.
+The Python base SDK selects workload authentication from this key; no
+`OPENBOX_AGENT_IDENTITY_METHOD` setting is needed for IAM v3.
+
+The base SDK fetches `/api/v3/auth/bootstrap`, exchanges a signed `private_key_jwt`
+for a short-lived Keycloak token, and sends the API key plus
+`X-OpenBox-Workload-Token` on v3 validation, evaluation, and approval requests.
+It owns token caching and refresh for OpenBox-, Okta-, and Entra-managed identities.
+Lifecycle callbacks, hooks, synchronous/raw evaluations, and approval polling share
+the handler's runtime client. A standalone `GovernanceClient` also accepts
+`workload_private_key`; call `await client.close()` when finished with it.
+
+Authentication and signing failures raise `OpenBoxAuthError` or its subclass
+`OpenBoxSigningError` even with `on_api_error="fail_open"`. The signing error retains
+Core's `reason_code`. Invalid bootstrap metadata raises `OpenBoxConfigError`, and
+bootstrap/token service outages raise `OpenBoxNetworkError`; these do not become
+implicit ALLOW or pending approval results. `validate=False` skips the startup
+network check only: the key is still validated locally, and runtime requests
+still authenticate.
+
+The base SDK preserves rolling-upgrade compatibility: bootstrap HTTP 404, or
+HTTP 409 with `workload_identity_unavailable`, retains the configured legacy route.
+Other bootstrap failures do not downgrade. Existing DID signing remains available
+through `agent_did`/`agent_private_key` or `OPENBOX_AGENT_DID`/`OPENBOX_AGENT_PRIVATE_KEY`.
+Without identity credentials, the existing API-key-only behavior is preserved.
+
 ### Try it locally (included test agent)
 
 The repository includes a runnable LangGraph test agent under `test-agent/`.
@@ -207,6 +248,7 @@ See `test-agent/README.md` for setup and run instructions.
 | `api_key` | `str` | **required** | API key (`obx_live_*` or `obx_test_*`) |
 | `agent_did` | `str` | `OPENBOX_AGENT_DID` | Agent DID used to sign governance requests |
 | `agent_private_key` | `str` | `OPENBOX_AGENT_PRIVATE_KEY` | Base64 raw Ed25519 private key seed for the agent DID |
+| `workload_private_key` | `str` | `OPENBOX_LANGGRAPH_WORKLOAD_PRIVATE_KEY`, then `OPENBOX_WORKLOAD_PRIVATE_KEY` | PKCS8 PEM RSA key for IAM v3 workload authentication |
 | `agent_name` | `str` | `None` | Agent name as configured in the dashboard |
 | `validate` | `bool` | `True` | Validate API key against server on startup |
 | `on_api_error` | `str` | `"fail_open"` | `"fail_open"` (allow on error) or `"fail_closed"` (block on error) |

openbox_langgraph_sdk_python-1.1.0.dist-info/RECORD

@@ -0,0 +1,23 @@
+openbox_langgraph/__init__.py,sha256=J-3oOgnRjF5ixC8r90vthDAVdotGI-fyg84byXvl4xQ,4142
+openbox_langgraph/activity_context_binding.py,sha256=kI_Qu7R0mjM2js50sN3H-9CNWjzF8tI7Xg9afvnQeHo,4789
+openbox_langgraph/client.py,sha256=Asq9iw6BcazzIgRpyqP4KJOFris2ferOoz0u63EAtNo,26835
+openbox_langgraph/config.py,sha256=XSbd5RMEsf1VWFQkCx7hJceTu_EcSs_uTMYL_LIybRE,17183
+openbox_langgraph/core_adapter.py,sha256=xv--ptTjoeAD7bo7IvJOhP_RRnKTkoAr06VY945yYBE,11418
+openbox_langgraph/core_events.py,sha256=UXS9iWFPBLcClbfMa9MjaJDp4ZjMrm49x_oqX3TAZQg,6237
+openbox_langgraph/core_runtime.py,sha256=NRcjbbYnE-1sOaFM_rcmNpcAkufqTpRbn1L2WB0GXWk,8600
+openbox_langgraph/errors.py,sha256=Xry_Ir6U2wmKerluIJ18eHPzuE5YCq0Ib1uY58raXro,5137
+openbox_langgraph/hitl.py,sha256=p8Xyxp9vvIBciumghM2RGJ53deIIwbufLRmw-PPLteU,2751
+openbox_langgraph/identity.py,sha256=t4jGkUNGz4OwcGXrWMgy5jVriEYJwCE_509Yi-MKaHY,5965
+openbox_langgraph/langgraph_handler.py,sha256=Ibp4wcBznlAh4qtH2nNiWGzCUX4YFZhrJF7pTSpLZaA,106043
+openbox_langgraph/langgraph_hook_runtime.py,sha256=FVoTvay5ZJAI8iNxRCdPNEeldi7l50AMRGP_vmWU6G4,8757
+openbox_langgraph/otel_setup.py,sha256=Qk8GiXZ1f4WlSjT1_Id48dRfoZGkP_A0VCQFVX2wysU,1584
+openbox_langgraph/span_processor.py,sha256=MfsHG4La0P-G1mo2GCgFqU-al5iljExTAA1bSrCRtJA,14045
+openbox_langgraph/tool_activity_binding.py,sha256=MBql-XoqRkooy6vwBhi8kmnWnmJIIuIXRyWqj1lUqmo,14918
+openbox_langgraph/trace_context_registry.py,sha256=fcU-WXt-8VLsyd8irJ1feQQCeLiGFSK8oNN-zfbCcPM,9583
+openbox_langgraph/tracing.py,sha256=24CIs5hgnK2nRH0vF7g96L3fuxyP66w24Oe0sJbBCc8,7299
+openbox_langgraph/types.py,sha256=zUrk44-1PBWirW7bPPrsLcMNzJSVYCdpzPuu4iBwIXs,26368
+openbox_langgraph/verdict_handler.py,sha256=YmZjBxzOa2RBbkF13xDCPUAGzz7m1hwdMErwOVDl2WM,8323
+openbox_langgraph_sdk_python-1.1.0.dist-info/METADATA,sha256=sl6QbrHNXa8u8J0SRYzXb-3JReuTwVyl1BlD9hk8rHA,24140
+openbox_langgraph_sdk_python-1.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+openbox_langgraph_sdk_python-1.1.0.dist-info/licenses/LICENSE,sha256=bPyy7QFDMnA5r6asaR3iD9rQvpjz5cUFk1ouHCuBYIY,1071
+openbox_langgraph_sdk_python-1.1.0.dist-info/RECORD,,

{openbox_langgraph_sdk_python-1.0.0.dist-info → openbox_langgraph_sdk_python-1.1.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.30.1
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any

openbox_langgraph_sdk_python-1.0.0.dist-info/RECORD

@@ -1,23 +0,0 @@
-openbox_langgraph/__init__.py,sha256=A2qUhwWwxsySPtYQ-oRp8G06nCfjXKODBmz7ZP8dkQw,4090
-openbox_langgraph/activity_context_binding.py,sha256=kI_Qu7R0mjM2js50sN3H-9CNWjzF8tI7Xg9afvnQeHo,4789
-openbox_langgraph/client.py,sha256=awaj-q-ImFCfdJQAxMkSWUGeI_dN6TMe6pe1J3Nhojw,22834
-openbox_langgraph/config.py,sha256=-eZuX59ydO9XkWMKSOkZGfuYkXnUswFdefoNpJOt3SI,15120
-openbox_langgraph/core_adapter.py,sha256=y6oVTuq6AZvAv6EREC6HublU8Pi2si8FSAyK-ky6knc,11256
-openbox_langgraph/core_events.py,sha256=UXS9iWFPBLcClbfMa9MjaJDp4ZjMrm49x_oqX3TAZQg,6237
-openbox_langgraph/core_runtime.py,sha256=bVsm_9o7rI6boAL5YnQ5kpjpHWj8lrZDML__dmv3fi4,8306
-openbox_langgraph/errors.py,sha256=2FLK2_h-ObNZ-r3jPZJQR0fU5WMBoEE_0FPOxL5BLlA,3806
-openbox_langgraph/hitl.py,sha256=p8Xyxp9vvIBciumghM2RGJ53deIIwbufLRmw-PPLteU,2751
-openbox_langgraph/identity.py,sha256=kFP2AwUyCrmp26kE7J-_Cajksef2x4YVFf_WSCpJUTE,5436
-openbox_langgraph/langgraph_handler.py,sha256=kMHs1j9Pn-EFIT66706cmO_E_172Ve-9iXX3YHtyQE4,105318
-openbox_langgraph/langgraph_hook_runtime.py,sha256=m3UXOKmsAz0qCiYyAsZvJEs1EecIrbxblPivJtlTt14,8401
-openbox_langgraph/otel_setup.py,sha256=Qk8GiXZ1f4WlSjT1_Id48dRfoZGkP_A0VCQFVX2wysU,1584
-openbox_langgraph/span_processor.py,sha256=MfsHG4La0P-G1mo2GCgFqU-al5iljExTAA1bSrCRtJA,14045
-openbox_langgraph/tool_activity_binding.py,sha256=MBql-XoqRkooy6vwBhi8kmnWnmJIIuIXRyWqj1lUqmo,14918
-openbox_langgraph/trace_context_registry.py,sha256=fcU-WXt-8VLsyd8irJ1feQQCeLiGFSK8oNN-zfbCcPM,9583
-openbox_langgraph/tracing.py,sha256=24CIs5hgnK2nRH0vF7g96L3fuxyP66w24Oe0sJbBCc8,7299
-openbox_langgraph/types.py,sha256=zUrk44-1PBWirW7bPPrsLcMNzJSVYCdpzPuu4iBwIXs,26368
-openbox_langgraph/verdict_handler.py,sha256=YmZjBxzOa2RBbkF13xDCPUAGzz7m1hwdMErwOVDl2WM,8323
-openbox_langgraph_sdk_python-1.0.0.dist-info/METADATA,sha256=6cO6xSCgLUcoltXiOruip3gVuKRCakgB_1DabcbZTEM,21647
-openbox_langgraph_sdk_python-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
-openbox_langgraph_sdk_python-1.0.0.dist-info/licenses/LICENSE,sha256=bPyy7QFDMnA5r6asaR3iD9rQvpjz5cUFk1ouHCuBYIY,1071
-openbox_langgraph_sdk_python-1.0.0.dist-info/RECORD,,