openbox-langgraph-sdk-python 1.0.0__tar.gz → 1.2.0__tar.gz

{openbox_langgraph_sdk_python-1.0.0 → openbox_langgraph_sdk_python-1.2.0}/.github/workflows/pr-quality.yml

@@ -165,7 +165,7 @@ jobs:
         id: sonarqube_quality_gate
         if: ${{ env.SONAR_TOKEN != '' && env.SONAR_HOST_URL != '' }}
         continue-on-error: true
-        uses: SonarSource/sonarqube-quality-gate-action@master
+        uses: SonarSource/sonarqube-quality-gate-action@v1.2.0
         with:
           pollingTimeoutSec: 600
         env:

{openbox_langgraph_sdk_python-1.0.0 → openbox_langgraph_sdk_python-1.2.0}/.github/workflows/publish.yml

@@ -342,7 +342,7 @@ jobs:
         id: sonarqube_quality_gate
         if: ${{ env.SONAR_TOKEN != '' && env.SONAR_HOST_URL != '' }}
         continue-on-error: true
-        uses: SonarSource/sonarqube-quality-gate-action@master
+        uses: SonarSource/sonarqube-quality-gate-action@v1.2.0
         with:
           pollingTimeoutSec: 600
         env:

{openbox_langgraph_sdk_python-1.0.0 → openbox_langgraph_sdk_python-1.2.0}/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## 1.2.0
+
+- Resume approved tools and operation hooks in place, preserving their activity IDs
+  and graph state instead of replaying the entire graph from its original input.
+- Handle repeated approval requests through invocation and streaming entry points.
+  Share each decision between sync and async callbacks for the same evaluation.
+- Cancel pending sync-tool waits when their turn ends, preventing a late approval
+  from executing an abandoned tool. Fail closed for sync waits on the event loop.
+
+## 1.1.0
+
+- Upgrade `openbox-sdk-python` to `>=1.4.0` for IAM v3 workload identity. Keep
+  `openbox-langchain-sdk-python` at `>=1.0.0` (locked to 1.0.0).
+- Update locked AnyIO to 4.14.2 and urllib3 to 2.8.0 in the SDK and demo, plus
+  pyasn1 to 0.6.4 in the demo, to address Trivy's critical/high findings.
+- Add `workload_private_key` to initialization, graph creation, runtime creation,
+  and standalone governance clients, with framework/global environment support
+  during initialization and runtime creation.
+- Delegate workload bootstrap, token exchange, caching, and refresh to the base
+  SDK. Reuse the handler's runtime client for validation, sync/raw evaluation,
+  and approval polling alongside callbacks and operation hooks.
+- Preserve authentication, signing, and bootstrap/configuration errors under
+  fail-open policies. Export `OpenBoxSigningError` with Core's `reason_code`.
+- Preserve legacy DID/API-key configuration and the base SDK's explicit
+  no-workload-authority fallback for rolling upgrades.
+
 ## 0.3.0
 
 Migrates the SDK onto the shared `openbox-sdk-python` (`openbox_core`) governance

{openbox_langgraph_sdk_python-1.0.0 → openbox_langgraph_sdk_python-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: openbox-langgraph-sdk-python
-Version: 1.0.0
+Version: 1.2.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) |
@@ -331,7 +373,17 @@ governed = create_openbox_graph_handler(
 )
 ```
 
-The human approves or rejects from the OpenBox dashboard. The SDK resumes or raises `ApprovalRejectedError` accordingly.
+The human approves or rejects from the OpenBox dashboard. Approval resumes the
+pending tool or hook operation with the same activity ID and graph state. Completed
+nodes and earlier tool side effects are not replayed. Later approval requests wait
+independently, including through `astream_governed` and `astream_events`. Rejection
+raises `ApprovalRejectedError`; expiration raises `ApprovalExpiredError`.
+
+Async operations await the decision without blocking the event loop. Synchronous
+tools wait in their executor thread. A synchronous operation called directly on the
+event-loop thread cannot safely suspend its stack, so pending approval raises
+`OpenBoxConfigError`; use an async operation or `asyncio.to_thread()` in that case.
+Cancelling the governed turn also stops pending approval waits.
 
 | Key | Type | Default | Description |
 |---|---|---|---|

{openbox_langgraph_sdk_python-1.0.0 → openbox_langgraph_sdk_python-1.2.0}/README.md

@@ -94,17 +94,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
@@ -139,6 +136,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/`.
@@ -165,6 +206,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) |
@@ -289,7 +331,17 @@ governed = create_openbox_graph_handler(
 )
 ```
 
-The human approves or rejects from the OpenBox dashboard. The SDK resumes or raises `ApprovalRejectedError` accordingly.
+The human approves or rejects from the OpenBox dashboard. Approval resumes the
+pending tool or hook operation with the same activity ID and graph state. Completed
+nodes and earlier tool side effects are not replayed. Later approval requests wait
+independently, including through `astream_governed` and `astream_events`. Rejection
+raises `ApprovalRejectedError`; expiration raises `ApprovalExpiredError`.
+
+Async operations await the decision without blocking the event loop. Synchronous
+tools wait in their executor thread. A synchronous operation called directly on the
+event-loop thread cannot safely suspend its stack, so pending approval raises
+`OpenBoxConfigError`; use an async operation or `asyncio.to_thread()` in that case.
+Cancelling the governed turn also stops pending approval waits.
 
 | Key | Type | Default | Description |
 |---|---|---|---|