openbox-temporal-sdk-python 1.1.2__tar.gz → 1.2.1__tar.gz

{openbox_temporal_sdk_python-1.1.2 → openbox_temporal_sdk_python-1.2.1}/.gitignore

@@ -40,3 +40,4 @@ AGENTS.md
 .claude/
 CLAUDE.md
 plans/
+_notes/

{openbox_temporal_sdk_python-1.1.2 → openbox_temporal_sdk_python-1.2.1}/CHANGELOG.md

@@ -2,6 +2,128 @@
 
 All notable changes to OpenBox SDK for Temporal Workflows.
 
+## [Unreleased]
+
+## [1.2.1] - 2026-07-21
+
+### Changed
+
+- **Resolve `openbox-sdk-python` from PyPI.** The dependency now installs from the
+  published package (floor raised to `>=1.0.1`) instead of a local editable checkout,
+  so `pip install openbox-temporal-sdk-python` works without a sibling source tree.
+
+## [1.2.0] - 2026-07-20
+
+### Changed
+
+- **Depends on `openbox-sdk-python>=0.2.0`** (import package `openbox_core`) — the shared
+  base SDK owning contracts, the always-strict gate, identity/signing, the evaluate
+  client, context runtime, Core `SpanData` wire serialization, generic instrumentation,
+  and the conformance kit. The `0.2.0` floor adds Redis/MongoDB/urllib3/urllib
+  instrumentation in the base runtime so no hook coverage is lost in the flip.
+- **Hook governance is now owned entirely by the base runtime.** The worker/plugin
+  build and own an `openbox_core` runtime and call `install_instrumentation()`;
+  HTTP/DB/file/function hooks, payload shape, evaluation, and enforcement all live in
+  `openbox_core`. LangGraph and Temporal now emit one identical flat hook interface.
+- `request_signing` now shims over `openbox_core.identity`. Signed request bytes are
+  UNCHANGED — gated byte-for-byte by a golden fixture generated from the pre-migration
+  signer (`tests/test_base_sdk_signing_parity.py`).
+- `Verdict`, `GuardrailsCheckResult`, and `WorkflowEventType` re-export the shared
+  contracts; `GovernanceVerdictResponse` subclasses the shared `EvaluationResult`
+  (same public surface, plus `fallback_used`/`diagnostics`/`raw`/`approval_expiration_time`).
+- Workflow lifecycle events route through shared `EventEnvelope` factories
+  (sandbox-safe pure contracts; wire payloads unchanged).
+- Activity execution binds the shared `ActivityContext` with a guaranteed
+  try/finally reset — governance context can no longer leak when an activity raises.
+
+### Behavior changes (regression-gated)
+
+- **Approval decision precedence:** approval poll responses parse via the shared
+  `ApprovalResult`; `action` now outranks `verdict` when both are present
+  (previously verdict-first), and a response with NEITHER field stays PENDING
+  (previously implicit ALLOW). Pinned by `tests/test_approval_action_precedence.py`.
+
+### Known behavior differences in the core runtime
+
+- **Completed-hook semantics:** core completed hooks never raise to the caller —
+  stop verdicts mark FUTURE execution blocked (abort/halt flags). Some legacy
+  completed hooks could raise after the operation ran (HTTP response hook, file
+  close); raising post-hoc cannot undo the operation, so the core model drops it
+  by design.
+- **Fail-closed shaping:** core maps started-hook evaluation failures under
+  `on_api_error="fail_closed"` (and started-hook contract errors, always) to a
+  non-retryable `GovernanceHalt` via the adapter — same terminal effect as
+  legacy's HALT-shaped `GovernanceBlockedError`, different exception chain.
+- **Redaction point for `activity_input`:** the core `ActivityContext` receives
+  the post-redaction input (what actually ran); the legacy buffer stored the
+  pre-redaction value. Core hook payloads therefore never leak redacted fields.
+
+### Added
+
+- `openbox.governance_state.TemporalGovernanceState` — run-scoped state carrying the
+  Temporal effects that must survive past a base hook callback: signal BLOCK/HALT
+  verdicts that fail the next activity, HITL pending-approval retry markers, and the
+  completed-hook stop bridge (completed BLOCK skips the duplicate completed event;
+  completed HALT reaches the terminate path). Consumed on every activity exit path.
+- `openbox.core_adapter` — `TemporalFrameworkAdapter` (maps base-SDK verdicts to
+  native `ApplicationError` types and the retry-based HITL loop; REQUIRE_APPROVAL marks
+  the pending-approval retry marker and degrades to a non-retryable block when HITL is
+  disabled/skipped; completed BLOCK/HALT records run-scoped stop state with the resolved
+  `ActivityContext`), and `create_core_runtime(...)` which builds and owns the base
+  runtime the worker/plugin install. `core_activity_scope` is the sole hook-context
+  bridge (guaranteed try/finally reset + trace registration).
+- Redis, MongoDB, urllib3, and urllib governance now flow through the base runtime.
+- Gates: workflow-sandbox import-safety, base-SDK conformance suite driven by the
+  Temporal adapter, public-API compatibility suite, and a deterministic
+  `llm_completion` hook-parity test (flat interface via the Temporal runtime, no live
+  OpenAI credentials).
+
+### Removed
+
+- `WorkflowSpanProcessor`, `WorkflowSpanBuffer`, and the `setup_opentelemetry_for_governance`
+  entry point (public exports). Governance instrumentation is installed by the base
+  runtime; there is no Temporal-local OpenTelemetry setup to call.
+- Temporal-local hook modules `otel_setup`, `hook_governance`, `http_governance_hooks`,
+  `db_governance_hooks`, `file_governance_hooks`, `span_processor`, and the dead
+  `context_propagation` helper (its ContextVar-to-executor propagation lives in the base
+  runtime). Their payload-shape/instrumentation coverage moved to the base SDK suite.
+- `openbox.tracing.traced` now wraps `openbox_core.instrumentation.function.governed`;
+  `create_span` remains a plain span helper.
+
+### Fixed (legacy file instrumentation — pre-existing upstream)
+
+- **Runtime RecursionError under file instrumentation:** governance evaluation
+  itself opens files (httpx/ssl, package-metadata scans via importlib_metadata/
+  zipp) — governing those opens re-evaluated recursively until RecursionError.
+  traced_open now (1) passes through any open performed on a thread already
+  inside file-governance work (re-entrancy guard) and (2) bypasses
+  interpreter-owned trees (venv, stdlib, site-packages — sys.prefix/base_prefix
+  + sysconfig paths): those reads are Python machinery, not application data
+  access. Application paths (./.env, data files, temp files) remain governed.
+  Same guard mirrored in the base SDK's file instrumentation.
+
+### Fixed (HTTP hook payloads — pre-existing upstream)
+
+- **Mangled method on httpx spans:** OTel's httpx instrumentation passes the
+  method as BYTES; `str(b"POST")` shipped `http_method: "b'POST'"` on every
+  httpx started span. Methods now decode bytes-safely at all client paths.
+- **Credential leak in governance payloads:** raw request/response headers
+  (`authorization`, `cookie`, `set-cookie`, `x-api-key`, …) were sent to Core
+  verbatim — live API keys landed in Core logs. All header dicts are now
+  redacted at the span-data builder choke point. Same redaction added to the
+  base SDK instrumentation. **Rotate any API keys that appeared in payloads.**
+
+### Migration notes
+
+- Base-runtime instrumentation is the sole hook governance path
+  and the legacy in-repo hook stack is removed. Approval-retry, signal BLOCK/HALT, and
+  completed-hook BLOCK/HALT behavior are preserved (run-scoped, cleaned after use).
+- Dropped coverage vs the legacy stack: direct raw-driver DB queries (psycopg2/mysql/
+  pymysql/sqlite3 used WITHOUT SQLAlchemy). The base runtime governs SQLAlchemy (all
+  backends), asyncpg, Redis, and MongoDB; activating raw dbapi driver instrumentors
+  interferes with SQLAlchemy's own dialect queries, so raw-driver-only governance is a
+  base-SDK follow-up.
+
 ## [1.1.2] - 2026-04-22
 
 ### Security

{openbox_temporal_sdk_python-1.1.2 → openbox_temporal_sdk_python-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbox-temporal-sdk-python
-Version: 1.1.2
+Version: 1.2.1
 Summary: OpenBox SDK - Governance and observability for Temporal workflows
 Project-URL: Homepage, https://github.com/OpenBox-AI/temporal-sdk-python
 Project-URL: Documentation, https://github.com/OpenBox-AI/temporal-sdk-python#readme
@@ -24,6 +24,7 @@ Requires-Python: >=3.11
 Requires-Dist: asyncpg>=0.29.0
 Requires-Dist: httpx<1,>=0.28.0
 Requires-Dist: mysql-connector-python>=8.0.0
+Requires-Dist: openbox-sdk-python>=1.0.1
 Requires-Dist: opentelemetry-api<1.40.0,>=1.38.0
 Requires-Dist: opentelemetry-instrumentation-asyncpg<0.61b0,>=0.59b0
 Requires-Dist: opentelemetry-instrumentation-httpx<0.61b0,>=0.59b0
@@ -51,7 +52,8 @@ Description-Content-Type: text/markdown
 OpenBox SDK provides **governance and observability** for Temporal workflows by capturing workflow/activity lifecycle events, HTTP telemetry, database queries, and file operations, then sending them to OpenBox Core for policy evaluation.
 
 **Key Features:**
-- 6 event types (WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted)
+- 7 event types (WorkflowStarted, WorkflowCompleted, WorkflowFailed, SignalReceived, ActivityStarted, ActivityCompleted, Handoff)
+- Multi-agent sessions — propagate a shared `multi_agent_session_id` across workflow + activity events
 - 5-tier verdict system (ALLOW, CONSTRAIN, REQUIRE_APPROVAL, BLOCK, HALT)
 - **Hook-level governance** — per-operation evaluation (HTTP requests, file I/O, database queries, function tracing) with started/completed stages
 - HTTP/Database/File I/O instrumentation via OpenTelemetry
@@ -199,8 +201,6 @@ worker = create_openbox_worker(
 
     # Database instrumentation
     instrument_databases=True,
-    db_libraries={"psycopg2", "sqlalchemy"},  # None = all available
-    sqlalchemy_engine=engine,  # pass pre-existing engine for query capture
 
     # File I/O instrumentation
     instrument_file_io=False,  # disabled by default
@@ -247,6 +247,48 @@ OpenBox Core returns a verdict indicating what action the SDK should take.
 | SignalReceived | Signal received | workflow_id, signal_name, signal_args |
 | ActivityStarted | Activity begins | activity_id, activity_type, activity_input |
 | ActivityCompleted | Activity ends | activity_id, activity_type, activity_input, activity_output, spans, status, duration |
+| Handoff | Agent hands off to another agent | from_agent_did, multi_agent_session_id |
+
+When a workflow runs as part of a multi-agent session (see below), every event
+above also carries `multi_agent_session_id`. The field is omitted when no
+session id is supplied.
+
+---
+
+## Multi-Agent Sessions
+
+Group the work of several agents under one shared `multi_agent_session_id`. The
+SDK only **propagates** the id you supply — it never invents one, and it owns no
+routing, session minting, or agent registry (those stay in your application).
+
+**Supply the id** via the Temporal workflow memo at start time:
+
+```python
+await client.start_workflow(
+    MyWorkflow.run,
+    arg,
+    id="order-123",
+    task_queue="my-queue",
+    memo={"openbox_multi_agent_session_id": session_id},
+)
+```
+
+The SDK then tags every governance event (workflow, activity, and hook events)
+with that id, propagating it from the workflow to its activities automatically.
+
+**Emit an explicit handoff** from inside workflow code:
+
+```python
+from openbox import emit_handoff
+
+await emit_handoff(
+    multi_agent_session_id=session_id,
+    from_agent_did="did:aip:...",   # the sending agent
+)
+```
+
+The receiving agent is derived server-side from the signed identity and is never
+sent. `emit_handoff` validates its arguments locally before any network call.
 
 ---
 
@@ -279,7 +321,7 @@ OpenBox Core can validate and redact sensitive data before/after activity execut
 
 ## Error Handling
 
-Configure error policy via `on_api_error` (constants available as `hook_governance.FAIL_OPEN` / `FAIL_CLOSED`):
+Configure error policy via the `governance_policy` parameter (`"fail_open"` / `"fail_closed"`):
 
 | Policy | Behavior |
 |--------|----------|
@@ -307,15 +349,12 @@ Configure error policy via `on_api_error` (constants available as `hook_governan
 - `redis` — native OTel `request_hook`/`response_hook`
 - `sqlalchemy` — `before/after_cursor_execute` event listeners
 
-**SQLAlchemy Note:** If your SQLAlchemy engine is created before `create_openbox_worker()` runs (e.g., at module import time), you must pass it via the `sqlalchemy_engine` parameter. Without this, `SQLAlchemyInstrumentor` only patches future `create_engine()` calls and won't capture queries on pre-existing engines.
+**SQLAlchemy Note:** Query-level governance works on pre-existing engines automatically — even engines created before `create_openbox_worker()` runs (e.g., at module import time) — because the base runtime governs SQLAlchemy via a global `Engine` event listener. No engine handle needs to be passed in. The `db_libraries` and `sqlalchemy_engine` parameters are still accepted for backward compatibility but are no longer required and have no effect: the base runtime installs every available database instrumentor best-effort.
 
 ```python
-from db.engine import engine
-
 worker = create_openbox_worker(
     ...,
-    db_libraries={"psycopg2", "sqlalchemy"},
-    sqlalchemy_engine=engine,
+    instrument_databases=True,  # default; installs all available DB instrumentors
 )
 ```
 
@@ -411,7 +450,7 @@ Every database operation is evaluated at `started` (pre-query, can block) and `c
 
 ### Function Tracing
 
-Functions decorated with `@traced` are automatically governed when `hook_governance` is configured:
+Functions decorated with `@traced` are automatically governed when a worker (or plugin) has installed the base runtime. `@traced` wraps the base SDK's `governed()` decorator:
 
 | Stage | Trigger | Data Available |
 |-------|---------|----------------|
@@ -420,15 +459,13 @@ Functions decorated with `@traced` are automatically governed when `hook_governa
 
 **How it works (Function Tracing):**
 
-1. `@traced` decorator wrapper starts OTel span
-2. → SDK sends `started` governance evaluation with function name and module
-3. If verdict is BLOCK/HALT → `GovernanceBlockedError` raised, function never executes
+1. `@traced` delegates to the base SDK's `governed()` decorator
+2. → the base runtime sends a `started` FUNCTION_CALL evaluation with function name and module
+3. If verdict is BLOCK/HALT → the call is blocked and the function never executes
 4. Function executes normally
-5. → SDK sends `completed` governance evaluation with result or error info
-6. If verdict is BLOCK/HALT → `GovernanceBlockedError` raised after execution
-7. When `hook_governance` is not configured → zero overhead, no governance calls
-
-**Governed span tracking:** When hook-level governance is active, the SDK marks HTTP spans as "governed" so the OTel `on_end` processor skips buffering them — preventing duplicate spans.
+5. → the base runtime sends a `completed` FUNCTION_CALL evaluation with result or error info
+6. If verdict is BLOCK/HALT → the block is surfaced after execution
+7. When no base runtime is installed → transparent passthrough, zero governance calls
 
 ---
 
@@ -439,116 +476,87 @@ See [System Architecture](./docs/system-architecture.md) for detailed component
 **High-Level Flow:**
 
 ```
-Workflow/Activity → Interceptors → Span Processor → OpenBox Core API
-                                                    ↓
-                                            Returns Verdict
-                                                    ↓
-                                    (ALLOW, BLOCK, HALT, etc.)
-
-Hook-Level (per HTTP request):
-Activity HTTP Call → OTel Hook → hook_governance → API (started) → Allow/Block
-                   → Response  → hook_governance → API (completed) → Allow/Block
-
-Hook-Level (per file operation):
-Activity open()       → hook_governance → API (started)   → Allow/Block
-Activity read/write() → hook_governance → API (started)   → Allow/Block
-                      → hook_governance → API (completed) → Allow/Block
-Activity close()      → hook_governance → API (completed) → Allow/Block
-
-Hook-Level (per DB query):
-Activity DB Call → db_governance_hooks → hook_governance → API (started) → Allow/Block
-                → Query executes     → hook_governance → API (completed)
-
-Hook-Level (per @traced function):
-@traced call    → hook_governance → API (started) → Allow/Block
-                → Function runs  → hook_governance → API (completed)
+Workflow / Activity lifecycle → Temporal SDK interceptors → OpenBox Core API
+                                                            ↓
+                                                    Returns Verdict
+                                                            ↓
+                                            (ALLOW, BLOCK, HALT, REQUIRE_APPROVAL)
+
+Hook-Level (per HTTP request / DB query / file op / @traced fn):
+Operation → base-SDK instrumentation → OpenBox Core API (started)   → Allow/Block
+          → Operation runs           → OpenBox Core API (completed) → Allow/Block
 ```
 
-**Module responsibilities:**
-- `otel_setup.py` — OTel instrumentation, hooks, TracedFile wrapper
-- `hook_governance.py` — Shared governance evaluator (payload building, API calls, verdict handling)
-- `db_governance_hooks.py` — Per-library DB governance wrappers (wrapt, OTel hooks, SQLAlchemy events)
-- `span_processor.py` — Span buffering, activity context tracking
-- `activity_interceptor.py` — Activity lifecycle governance events
+The Temporal worker/plugin builds and owns an `openbox_core` runtime that installs
+all hook instrumentation. Hook payload building, evaluation, and enforcement are
+owned entirely by the base SDK; the Temporal SDK maps the resulting verdicts onto
+Temporal-native effects.
 
----
+**Responsibility split:**
 
-## Advanced Usage
+Base SDK (`openbox_core`):
+- HTTP / DB / file / function hook instrumentation
+- Hook payload shape, evaluation, and enforcement
 
-For manual control, import individual components:
+Temporal SDK (this package):
+- `workflow_interceptor.py` / `activity_interceptor.py` — workflow/activity/signal lifecycle governance events (via workflow-safe activities)
+- `governance_state.py` — `TemporalGovernanceState`: signal-verdict bridging, HITL pending-approval markers, completed-hook stop/halt propagation
+- `core_adapter.py` — builds the base runtime (`create_core_runtime`) and maps base verdicts to Temporal effects (`TemporalFrameworkAdapter`)
 
-```python
-from openbox import (
-    initialize,
-    WorkflowSpanProcessor,
-    GovernanceInterceptor,
-    GovernanceConfig,
-)
-from openbox.otel_setup import setup_opentelemetry_for_governance
-from openbox.activity_interceptor import ActivityGovernanceInterceptor
-from openbox.activities import build_governance_activities
-from openbox.hook_governance import FAIL_OPEN, FAIL_CLOSED  # error policy constants
+---
 
-# 1. Initialize SDK
-initialize(api_url="http://localhost:8086", api_key="obx_test_key_1")
+## Advanced Usage
 
-# 2. Create span processor
-span_processor = WorkflowSpanProcessor(
-    ignored_url_prefixes=["http://localhost:8086"]
-)
+The supported integration is a single call. Both `create_openbox_worker(...)` and
+`OpenBoxPlugin(...)` build and own the base `openbox_core` runtime, install all
+hook instrumentation, register the governance interceptors, and wire the
+`send_governance_event` activity for you — there is no manual OpenTelemetry or
+span-processor setup to perform.
 
-# 3. Setup OTel instrumentation (governance always enabled)
-setup_opentelemetry_for_governance(
-    span_processor,
-    api_url="http://localhost:8086",
-    api_key="obx_test_key_1",
-    sqlalchemy_engine=engine,  # optional: instrument pre-existing engine
-)
+Worker factory:
 
-# 4. Create governance config
-config = GovernanceConfig(
-    on_api_error="fail_closed",
-    api_timeout=30.0,
-)
+```python
+import os
+from openbox import create_openbox_worker
 
-# 5. Create interceptors
-workflow_interceptor = GovernanceInterceptor(
-    api_url="http://localhost:8086",
-    api_key="obx_test_key_1",
-    span_processor=span_processor,
-    config=config,
+worker = create_openbox_worker(
+    client=client,
+    task_queue="my-task-queue",
+    workflows=[MyWorkflow],
+    activities=[my_activity],
+    openbox_url=os.getenv("OPENBOX_URL"),
+    openbox_api_key=os.getenv("OPENBOX_API_KEY"),
+    governance_policy="fail_closed",
+    governance_timeout=30.0,
+    instrument_databases=True,
+    instrument_file_io=True,
 )
 
-activity_interceptor = ActivityGovernanceInterceptor(
-    api_url="http://localhost:8086",
-    api_key="obx_test_key_1",
-    span_processor=span_processor,
-    config=config,
-)
+await worker.run()
+```
 
-# 6. Build the governance activity instance (credentials captured on `self`
-# so they never flow through workflow history).
-governance_activities = build_governance_activities(
-    api_url="http://localhost:8086",
-    api_key="obx_test_key_1",
-)
+Plugin (Temporal >= 1.23.0) — attach to a plain `Worker`:
 
-# 7. Create worker
+```python
 from temporalio.worker import Worker
-from temporalio.contrib.opentelemetry import TracingInterceptor
+from openbox.plugin import OpenBoxPlugin
+
 worker = Worker(
-    client=client,
+    client,
     task_queue="my-task-queue",
     workflows=[MyWorkflow],
-    activities=[my_activity, governance_activities.send_governance_event],
-    interceptors=[
-        workflow_interceptor,
-        activity_interceptor,
-        TracingInterceptor(),  # W3C header propagation for OTel spans
-    ],
+    activities=[my_activity],
+    plugins=[OpenBoxPlugin(
+        openbox_url=os.getenv("OPENBOX_URL"),
+        openbox_api_key=os.getenv("OPENBOX_API_KEY"),
+        governance_policy="fail_closed",
+    )],
 )
 ```
 
+Both entry points accept the same governance, HITL, signing, and instrumentation
+options (see [Configuration](./docs/configuration.md)).
+
 ---
 
 ## Documentation
@@ -563,13 +571,17 @@ worker = Worker(
 
 ## Testing
 
-The SDK includes comprehensive test coverage with 15 test files:
+The SDK includes comprehensive test coverage under `tests/`:
 
 ```bash
 pytest tests/
 ```
 
-Test files: `test_activities.py`, `test_activity_interceptor.py`, `test_config.py`, `test_db_governance_hooks.py`, `test_file_governance_hooks.py`, `test_otel_hook_pause.py`, `test_otel_hook_pause_db.py`, `test_otel_setup.py`, `test_plugin.py`, `test_plugin_integration.py`, `test_span_processor.py`, `test_tracing.py`, `test_types.py`, `test_worker.py`, `test_workflow_interceptor.py`
+Coverage spans the worker factory and plugin, workflow/activity/signal
+interceptors, HITL approval flow, request signing, public-API compatibility, and
+parity with the base SDK's hook governance (`test_temporal_hook_parity.py`,
+`test_core_conformance_suite.py`). Hook instrumentation internals (HTTP/DB/file
+payload shape) are verified in the base SDK's own conformance suite.
 
 ---