openbox-sdk-python 1.0.1__tar.gz → 1.1.0__tar.gz

openbox_sdk_python-1.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.1.0] - 2026-07-21
+
+### Added
+- `RetryPlan` and `RetryDirective` dataclasses in `openbox_core.contracts.results`.
+- Optional `retry_plan` directive parsing on both `EvaluationResult` and `ApprovalResult`.
+  A `_MISSING` sentinel keeps a present `new_input: null` distinct from an absent field; falsy
+  values (`null`, `""`, `0`, `[]`, `{}`) are preserved; a boolean `new_input` is rejected; and every
+  number (recursively) must be finite and, if integral, a JS-safe integer (`|n| <= 2^53 - 1`).
+- `handle_retryable_block(result)` — an opt-in, pure inspector that returns a `RetryDirective` only
+  for a `BLOCK` verdict carrying a valid plan. Returns `None` for a plain BLOCK, every non-BLOCK
+  verdict (including HALT), a pending verdict, and an expired `ApprovalResult`.
+
+### Notes
+- Default enforcement is unchanged: a `BLOCK` verdict still raises `GovernanceBlockedError`. The new
+  helper is opt-in and never triggers an automatic retry; malformed or ineligible plans are treated
+  as absent (never fail open).

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openbox-sdk-python
-Version: 1.0.1
+Version: 1.1.0
 Summary: OpenBox base SDK - governance contracts, strict gate, identity/signing, evaluate client, context runtime, OTel span wire serialization, and generic instrumentation shared by every OpenBox framework SDK
 Author-email: OpenBox Team <tino@openbox.ai>
 License-Expression: MIT

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/openbox_core/__init__.py

@@ -37,7 +37,7 @@ from .errors import (
 # governance; eagerly it can deadlock package init as a circular import, and
 # lazily it can recurse unboundedly when a per-request header builder resolves
 # the version. Keep in sync with pyproject.toml on release.
-__version__ = "1.0.1"
+__version__ = "1.1.0"
 
 __all__ = [
     "__version__",

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/openbox_core/adapters/base.py

@@ -8,7 +8,8 @@ core error types directly.
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Protocol, runtime_checkable
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any, Protocol, runtime_checkable
 
 from ..contracts.results import EvaluationResult
 from ..errors import (
@@ -24,7 +25,7 @@ if TYPE_CHECKING:
     from ..approvals import ApprovalPoller
     from ..contracts.context import ActivityContext
 
-__all__ = ["FrameworkAdapter", "CoreAdapter"]
+__all__ = ["FrameworkAdapter", "CoreAdapter", "adapter_accepts_context"]
 
 
 @runtime_checkable
@@ -33,16 +34,27 @@ class FrameworkAdapter(Protocol):
 
     name: str
 
-    async def handle_approval(self, result: EvaluationResult) -> None:
+    async def handle_approval(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
         """Drive the framework's approval flow for REQUIRE_APPROVAL.
 
         Return normally when approved; raise the framework's native rejection/
         expiry error otherwise. Called BEFORE the real operation runs.
 
-        Adapters may ALSO define a plain-sync ``handle_approval_sync(result)``
-        (not part of the required protocol): when present, sync hook paths
-        delegate to it instead of driving the core inline poller. Frameworks
-        with retry-based HITL can raise their native pending error there.
+        ``context`` carries the workflow/run/activity IDs the approval poll
+        needs: Core's evaluate response does NOT echo them, so they cannot be
+        recovered from ``result.raw``. The runtime passes the originating
+        ``ActivityContext`` (lifecycle events build one from the event).
+        Optional — an adapter defined as ``handle_approval(self, result)`` still
+        conforms; the runtime passes ``context`` only when the signature accepts
+        it (see :func:`adapter_accepts_context`).
+
+        Adapters may ALSO define a plain-sync ``handle_approval_sync(result,
+        context)`` (not part of the required protocol): when present, sync hook
+        paths delegate to it instead of driving the core inline poller.
+        Frameworks with retry-based HITL can raise their native pending error
+        there.
         """
         ...
 
@@ -82,17 +94,16 @@ class CoreAdapter:
     def __init__(self, approval_poller: ApprovalPoller | None = None):
         self._poller = approval_poller
 
-    async def handle_approval(self, result: EvaluationResult) -> None:
+    async def handle_approval(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
         if self._poller is None or not result.approval_id:
             raise ApprovalRejectedError(
                 "REQUIRE_APPROVAL verdict but no approval flow is configured — "
                 "failing safe (operation not run)"
             )
-        approval = await self._poller.await_decision(
-            result.raw.get("workflow_id", ""),
-            result.raw.get("run_id", ""),
-            result.raw.get("activity_id", ""),
-        )
+        workflow_id, run_id, activity_id = _approval_poll_ids(result, context)
+        approval = await self._poller.await_decision(workflow_id, run_id, activity_id)
         if approval.allow_shaped:
             return
         if approval.expired:
@@ -121,3 +132,50 @@ class CoreAdapter:
         raise GovernanceBlockedError(
             result.verdict, result.reason or "Blocked by governance policy"
         )
+
+
+def _approval_poll_ids(
+    result: EvaluationResult, context: ActivityContext | None
+) -> tuple[str, str, str]:
+    """Resolve the (workflow_id, run_id, activity_id) the approval poll sends.
+
+    Core's evaluate response does not echo them, so the originating
+    ``ActivityContext`` is authoritative; ``result.raw`` is only a fallback for
+    a caller that predates the ``context`` argument (it is empty in real Core
+    traffic).
+    """
+    raw = result.raw
+    if context is None:
+        return (
+            raw.get("workflow_id", ""),
+            raw.get("run_id", ""),
+            raw.get("activity_id", ""),
+        )
+    return (
+        context.workflow_id or raw.get("workflow_id", ""),
+        context.run_id or raw.get("run_id", ""),
+        context.activity_id or raw.get("activity_id", ""),
+    )
+
+
+def adapter_accepts_context(callback: Callable[..., Any] | None) -> bool:
+    """True when an adapter callback accepts a ``context`` argument (an explicit
+    parameter or ``**kwargs``).
+
+    Checked by signature so a genuine ``TypeError`` raised inside the callback
+    body is never mistaken for an arity mismatch and silently dropped. Lets the
+    runtime stay backward-compatible with adapters written against the older
+    ``handle_approval(self, result)`` / ``on_completed_hook_result(self,
+    result)`` signatures.
+    """
+    import inspect
+
+    if callback is None:
+        return False
+    try:
+        params = inspect.signature(callback).parameters
+    except (TypeError, ValueError):
+        return False
+    return "context" in params or any(
+        p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()
+    )

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/openbox_core/conformance/hook_preflight.py

@@ -39,10 +39,14 @@ class RecordingHookAdapter:
         self.completed_results: list[EvaluationResult] = []
         self.completed_contexts: list[ActivityContext | None] = []
         self.approvals: list[EvaluationResult] = []
+        self.approval_contexts: list[ActivityContext | None] = []
         self.approve_next = True
 
-    async def handle_approval(self, result: EvaluationResult) -> None:
+    async def handle_approval(
+        self, result: EvaluationResult, context: ActivityContext | None = None
+    ) -> None:
         self.approvals.append(result)
+        self.approval_contexts.append(context)
         if not self.approve_next:
             raise ApprovalRejectedError("rejected by conformance adapter")
 

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/openbox_core/contracts/results.py

@@ -10,6 +10,7 @@ tolerant of unknown keys (field-shape drift from Core must not crash SDKs).
 
 from __future__ import annotations
 
+import math
 from dataclasses import dataclass, field
 from enum import Enum
 from typing import Any
@@ -19,6 +20,9 @@ __all__ = [
     "GuardrailsResult",
     "EvaluationResult",
     "ApprovalResult",
+    "RetryPlan",
+    "RetryDirective",
+    "handle_retryable_block",
 ]
 
 
@@ -102,6 +106,87 @@ class GuardrailsResult:
         return [r.get("reason", "") for r in self.reasons if r.get("reason")]
 
 
+# Sentinel distinguishing an absent ``retry_plan`` field from a present JSON ``null``.
+# ``dict.get("retry_plan")`` would collapse both to None; membership via this sentinel does not.
+_MISSING = object()
+
+# JS Number.MAX_SAFE_INTEGER. Integral numbers must fit within +/- this bound so ``new_input`` can
+# never silently change across FE, backend, Core, and Python (json.loads yields arbitrary-precision
+# ``int`` and ``float('inf')``, both broader than JS).
+_MAX_SAFE_INTEGER = 2**53 - 1
+
+
+def _numbers_are_safe(value: Any) -> bool:
+    """Every number (recursively) must be finite and, if integral, within the JS-safe range.
+
+    ``bool`` is a subclass of ``int`` but is not a number here; a nested bool is a plain leaf
+    (top-level ``new_input`` booleans are rejected separately by :func:`_parse_retry_plan`).
+    """
+    if isinstance(value, bool):
+        return True
+    if isinstance(value, int):
+        return abs(value) <= _MAX_SAFE_INTEGER
+    if isinstance(value, float):
+        if math.isinf(value) or math.isnan(value):
+            return False
+        if value.is_integer():
+            return abs(value) <= _MAX_SAFE_INTEGER
+        return True
+    if isinstance(value, dict):
+        return all(_numbers_are_safe(v) for v in value.values())
+    if isinstance(value, (list, tuple)):
+        return all(_numbers_are_safe(v) for v in value)
+    return True
+
+
+@dataclass
+class RetryPlan:
+    """Optional remediation hint carried on a BLOCK verdict (policy-produced or admin-retry).
+
+    ``new_input`` may be null | str | number | list | dict (boolean rejected). A present
+    ``new_input`` of ``None`` is a valid plan (retry with the original input) and is distinct
+    from an absent ``retry_plan`` field.
+    """
+
+    new_input: Any = None
+
+
+@dataclass
+class RetryDirective:
+    """Caller-facing view of a retryable BLOCK, surfaced only via :func:`handle_retryable_block`.
+
+    It is a remediation hint, not proof that a retry was evaluated or executed.
+    """
+
+    new_input: Any = None
+    governance_event_id: str | None = None
+    reason: str | None = None
+
+
+def _parse_retry_plan(container: dict[str, Any]) -> RetryPlan | None:
+    """Parse an optional ``retry_plan`` from a result dict against the frozen wire contract.
+
+    Returns a plan only when ``retry_plan`` is present, is a dict whose ONLY key is ``new_input``,
+    and ``new_input`` is null/str/number/list/dict (boolean rejected) with every number finite and,
+    if integral, within the JS-safe integer range. An absent field, a JSON ``null`` field, or any
+    contract violation yields ``None`` (treated as absent — never an error). A present
+    ``new_input`` of ``None`` is preserved as a valid plan.
+    """
+    plan = container.get("retry_plan", _MISSING)
+    if plan is _MISSING or not isinstance(plan, dict):
+        return None
+    # Exactly the single key new_input (also guarantees new_input is present, not merely null).
+    if set(plan.keys()) != {"new_input"}:
+        return None
+    new_input = plan["new_input"]
+    # bool is a subclass of int — reject a boolean new_input BEFORE the number check.
+    if isinstance(new_input, bool):
+        return None
+    if not _numbers_are_safe(new_input):
+        return None
+    return RetryPlan(new_input=new_input)
+
+
 @dataclass
 class EvaluationResult:
     """Response from a governance evaluation.
@@ -130,6 +215,7 @@ class EvaluationResult:
     fallback_used: bool = False  # True when fail-open produced this result
     diagnostics: list[Any] = field(default_factory=list)
     raw: dict[str, Any] = field(default_factory=dict)
+    retry_plan: RetryPlan | None = None  # Optional BLOCK remediation hint; None = absent
 
     @property
     def guardrails_result(self) -> GuardrailsResult | None:
@@ -180,6 +266,7 @@ class EvaluationResult:
             fallback_used=bool(data.get("fallback_used", False)),
             diagnostics=data.get("diagnostics") or [],
             raw=dict(data),
+            retry_plan=_parse_retry_plan(data),
         )
 
     @classmethod
@@ -212,6 +299,7 @@ class ApprovalResult:
     approval_expiration_time: str | None = None
     expired: bool = False
     raw: dict[str, Any] = field(default_factory=dict)
+    retry_plan: RetryPlan | None = None  # Present only on an admin-retry BLOCK
 
     # Known decision vocabulary for approvals (current values + accepted aliases).
     # Anything OUTSIDE this set parses to None (pending) — the evaluate-path
@@ -257,6 +345,7 @@ class ApprovalResult:
             approval_expiration_time=data.get("approval_expiration_time"),
             expired=bool(data.get("expired", False)),
             raw=dict(data),
+            retry_plan=_parse_retry_plan(data),
         )
 
     @property
@@ -285,3 +374,44 @@ class ApprovalResult:
         if self.verdict is None:
             return True
         return self.verdict in (Verdict.REQUIRE_APPROVAL, Verdict.CONSTRAIN)
+
+
+def handle_retryable_block(
+    result: EvaluationResult | ApprovalResult,
+) -> RetryDirective | None:
+    """Opt-in, pure inspector: surface a retry directive from a retryable BLOCK.
+
+    Returns a :class:`RetryDirective` ONLY for ``verdict == Verdict.BLOCK`` with a present, valid
+    ``retry_plan``. Returns ``None`` for plain BLOCK, every non-BLOCK verdict (including HALT),
+    a pending/``None`` verdict, and an expired :class:`ApprovalResult`.
+
+    This does NOT change enforcement: importing or exposing it never auto-retries. A caller must
+    invoke it explicitly, and it makes no claim that a replacement was evaluated or executed.
+
+    The gate is deliberately ``verdict == Verdict.BLOCK`` — NOT ``is_blocking()`` /
+    ``verdict.should_stop()``, which also match HALT (and, for approvals, expired results) and would
+    violate the wire-contract invariant that HALT always strips the plan.
+    """
+    # A stale/expired poll result must not surface a directive, even if verdict == BLOCK.
+    if isinstance(result, ApprovalResult) and result.expired:
+        return None
+    # ApprovalResult.verdict may be None (pending); the != BLOCK comparison handles that. Using
+    # getattr keeps this safe if a caller passes an unexpected object.
+    if getattr(result, "verdict", None) != Verdict.BLOCK:
+        return None
+
+    plan = result.retry_plan
+    if plan is None:
+        return None
+
+    # governance_event_id is typed on EvaluationResult; ApprovalResult carries it only in raw.
+    if isinstance(result, EvaluationResult):
+        governance_event_id = result.governance_event_id
+    else:
+        governance_event_id = result.raw.get("governance_event_id") or result.raw.get("id")
+
+    return RetryDirective(
+        new_input=plan.new_input,
+        governance_event_id=governance_event_id,
+        reason=result.reason,
+    )

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/openbox_core/hooks/preflight.py

@@ -18,6 +18,7 @@ import logging
 from collections.abc import Mapping
 from typing import Any, NoReturn
 
+from ..adapters.base import adapter_accepts_context
 from ..approvals import ApprovalPoller
 from ..contracts.events import EventEnvelope
 from ..contracts.otel_spans import HookType, Stage
@@ -39,10 +40,13 @@ class HookRuntime:
         self._store = runtime.context_store
         self._gate = runtime.gate
         self._adapter = runtime.adapter
-        # Decide ONCE whether the adapter's completed callback takes ``context``,
-        # by inspecting its signature — so a genuine TypeError raised inside the
+        # Decide ONCE whether the adapter's callbacks take ``context``, by
+        # inspecting their signatures — so a genuine TypeError raised inside a
         # callback body is never mistaken for an arity mismatch and swallowed.
-        self._completed_accepts_context = self._adapter_accepts_context()
+        self._completed_accepts_context = adapter_accepts_context(
+            self._adapter.on_completed_hook_result
+        )
+        self._approval_accepts_context = adapter_accepts_context(self._adapter.handle_approval)
         hitl = runtime.config.hitl
         self._sync_poller: ApprovalPoller | None = None
         if hitl.enabled:
@@ -163,7 +167,14 @@ class HookRuntime:
             )
         if verdict.requires_approval():
             # Adapter drives its native approval flow; returning ⇒ approved.
-            await self._adapter.handle_approval(result)
+            # Core omits the workflow/run/activity IDs from the evaluate
+            # response, so hand the span-resolved context for the poll.
+            if self._approval_accepts_context:
+                await self._adapter.handle_approval(
+                    result, context=resolve_context(self._store, span)
+                )
+            else:
+                await self._adapter.handle_approval(result)
             return True
         return True
 
@@ -259,24 +270,6 @@ class HookRuntime:
             return
         self._after_completed(result, span)
 
-    def _adapter_accepts_context(self) -> bool:
-        """True when the adapter's ``on_completed_hook_result`` accepts a
-        ``context`` argument (checked once, by signature — not by catching a
-        TypeError from the call, which would mask real errors)."""
-        import inspect
-
-        callback = getattr(self._adapter, "on_completed_hook_result", None)
-        if callback is None:
-            return False
-        try:
-            params = inspect.signature(callback).parameters
-        except (TypeError, ValueError):
-            return False
-        # Accepts context via an explicit param or **kwargs.
-        return "context" in params or any(
-            p.kind is inspect.Parameter.VAR_KEYWORD for p in params.values()
-        )
-
     def _after_completed(self, result: EvaluationResult, span: Any) -> None:
         if result.verdict.should_stop():
             self._mark_stopped(result, span)  # future execution only

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/openbox_core/runtime.py

@@ -17,10 +17,11 @@ from __future__ import annotations
 
 from typing import Any
 
-from .adapters.base import CoreAdapter, FrameworkAdapter
+from .adapters.base import CoreAdapter, FrameworkAdapter, adapter_accepts_context
 from .client import EvaluationClient
 from .config import OpenBoxConfig
 from .context import ContextStore, default_context_store
+from .contracts.context import ActivityContext
 from .contracts.events import EventEnvelope
 from .contracts.results import EvaluationResult, Verdict
 from .errors import GuardrailsValidationError
@@ -51,6 +52,9 @@ class OpenBoxRuntime:
     ):
         self.config = config
         self.adapter: FrameworkAdapter = adapter if adapter is not None else CoreAdapter()
+        # Decide ONCE whether the adapter's handle_approval accepts ``context``
+        # (older adapters take only ``result``) — see adapter_accepts_context.
+        self._approval_accepts_context = adapter_accepts_context(self.adapter.handle_approval)
         self.context_store = context_store if context_store is not None else default_context_store()
         self.client = client if client is not None else EvaluationClient(
             config.api_url,
@@ -104,7 +108,14 @@ class OpenBoxRuntime:
         result = await self.gate.aevaluate(event)
         if result.verdict.requires_approval():
             self._check_guardrails(result)
-            await self.adapter.handle_approval(result)
+            # Core omits workflow/run/activity IDs from the evaluate response, so
+            # build the approval context from the originating event for the poll.
+            if self._approval_accepts_context:
+                await self.adapter.handle_approval(
+                    result, context=_approval_context_from_event(event)
+                )
+            else:
+                await self.adapter.handle_approval(result)
             return result
         return self._enforce_lifecycle(result, drive_approval=False)
 
@@ -136,3 +147,25 @@ class OpenBoxRuntime:
         self.uninstall_instrumentation()
         self.context_store.clear()
         await self.client.aclose()
+
+
+def _approval_context_from_event(event: EventEnvelope) -> ActivityContext:
+    """Build the approval context for a lifecycle event.
+
+    ``workflow_id`` / ``run_id`` live in the flat wire ``payload``;
+    ``activity_id`` is a first-class envelope field (a workflow-level approval
+    legitimately has none). Core's evaluate response omits all three, so the
+    poll must be built from the originating event — see
+    ``CoreAdapter.handle_approval``.
+    """
+    payload = event.payload
+
+    def _s(value: Any) -> str | None:
+        return value if isinstance(value, str) else None
+
+    activity_id = event.activity_id if event.activity_id is not None else _s(payload.get("activity_id"))
+    return ActivityContext(
+        workflow_id=_s(payload.get("workflow_id")),
+        run_id=_s(payload.get("run_id")),
+        activity_id=activity_id,
+    )

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "openbox-sdk-python"
-version = "1.0.1"
+version = "1.1.0"
 description = "OpenBox base SDK - governance contracts, strict gate, identity/signing, evaluate client, context runtime, OTel span wire serialization, and generic instrumentation shared by every OpenBox framework SDK"
 authors = [
     { name = "OpenBox Team", email = "tino@openbox.ai" },

openbox_sdk_python-1.1.0/tests/contracts/test_retry_plan.py

@@ -0,0 +1,207 @@
+"""retry_plan parsing + handle_retryable_block tests (frozen wire contract).
+
+Covers: present-null vs absent, falsy-value preservation, boolean rejection, the finite/
+safe-integer numeric rule (incl. nested), action="block" approvals, HALT/expired -> None,
+the EvaluationResult path not raising AttributeError, and default BLOCK enforcement unchanged.
+"""
+
+import pytest
+
+from openbox_core.contracts.results import (
+    ApprovalResult,
+    EvaluationResult,
+    RetryDirective,
+    RetryPlan,
+    Verdict,
+    handle_retryable_block,
+)
+from openbox_core.errors import GovernanceBlockedError
+from openbox_core.gate import raise_for_verdict
+
+SAFE_MAX = 2**53 - 1
+
+
+def _block(**extra):
+    return {"verdict": "block", **extra}
+
+
+class TestRetryPlanParsing:
+    def test_valid_plan_parses_on_evaluation(self):
+        r = EvaluationResult.from_dict(_block(retry_plan={"new_input": "x"}))
+        assert isinstance(r.retry_plan, RetryPlan)
+        assert r.retry_plan.new_input == "x"
+
+    def test_valid_plan_parses_on_approval_block_action(self):
+        r = ApprovalResult.from_dict(
+            {"action": "block", "retry_plan": {"new_input": [1, 2]}}
+        )
+        assert r.verdict is Verdict.BLOCK
+        assert isinstance(r.retry_plan, RetryPlan)
+        assert r.retry_plan.new_input == [1, 2]
+
+    def test_present_null_is_distinct_from_absent(self):
+        present = EvaluationResult.from_dict(_block(retry_plan={"new_input": None}))
+        assert present.retry_plan is not None
+        assert present.retry_plan.new_input is None
+
+        absent = EvaluationResult.from_dict(_block())
+        assert absent.retry_plan is None
+
+    def test_json_null_field_is_treated_as_absent(self):
+        assert EvaluationResult.from_dict(_block(retry_plan=None)).retry_plan is None
+
+    def test_falsy_values_preserved(self):
+        for val in (None, "", 0, [], {}):
+            r = EvaluationResult.from_dict(_block(retry_plan={"new_input": val}))
+            assert r.retry_plan is not None, val
+            assert r.retry_plan.new_input == val
+
+    def test_boolean_new_input_rejected(self):
+        for val in (True, False):
+            r = EvaluationResult.from_dict(_block(retry_plan={"new_input": val}))
+            assert r.retry_plan is None
+
+    def test_extra_key_rejected(self):
+        r = EvaluationResult.from_dict(
+            _block(retry_plan={"new_input": None, "x": 1})
+        )
+        assert r.retry_plan is None
+
+    def test_missing_new_input_rejected(self):
+        r = EvaluationResult.from_dict(_block(retry_plan={"other": 1}))
+        assert r.retry_plan is None
+
+    def test_non_dict_plan_rejected(self):
+        for bad in ("str", 5, [1], True):
+            r = EvaluationResult.from_dict(_block(retry_plan=bad))
+            assert r.retry_plan is None
+
+    def test_numeric_safe_boundary(self):
+        assert (
+            EvaluationResult.from_dict(
+                _block(retry_plan={"new_input": SAFE_MAX})
+            ).retry_plan
+            is not None
+        )
+        assert (
+            EvaluationResult.from_dict(
+                _block(retry_plan={"new_input": SAFE_MAX + 1})
+            ).retry_plan
+            is None
+        )
+
+    def test_non_finite_and_nested_unsafe_rejected(self):
+        assert (
+            EvaluationResult.from_dict(
+                _block(retry_plan={"new_input": float("inf")})
+            ).retry_plan
+            is None
+        )
+        assert (
+            EvaluationResult.from_dict(
+                _block(retry_plan={"new_input": float("nan")})
+            ).retry_plan
+            is None
+        )
+        assert (
+            EvaluationResult.from_dict(
+                _block(retry_plan={"new_input": {"a": [SAFE_MAX + 1]}})
+            ).retry_plan
+            is None
+        )
+        assert (
+            EvaluationResult.from_dict(
+                _block(retry_plan={"new_input": {"a": [SAFE_MAX]}})
+            ).retry_plan
+            is not None
+        )
+
+    def test_raw_preserved(self):
+        data = _block(retry_plan={"new_input": "x"}, extra="keep")
+        r = EvaluationResult.from_dict(data)
+        assert r.raw["extra"] == "keep"
+        assert r.raw["retry_plan"] == {"new_input": "x"}
+
+
+class TestHandleRetryableBlock:
+    def test_directive_from_evaluation_block(self):
+        r = EvaluationResult.from_dict(
+            _block(
+                retry_plan={"new_input": "x"},
+                governance_event_id="ev-1",
+                reason="blocked",
+            )
+        )
+        d = handle_retryable_block(r)
+        assert isinstance(d, RetryDirective)
+        assert d.new_input == "x"
+        assert d.governance_event_id == "ev-1"
+        assert d.reason == "blocked"
+
+    def test_directive_from_approval_reads_event_id_from_raw(self):
+        r = ApprovalResult.from_dict(
+            {
+                "action": "block",
+                "retry_plan": {"new_input": None},
+                "governance_event_id": "ev-2",
+                "reason": "retry",
+            }
+        )
+        d = handle_retryable_block(r)
+        assert d is not None
+        assert d.new_input is None
+        assert d.governance_event_id == "ev-2"
+
+    def test_approval_event_id_falls_back_to_id(self):
+        r = ApprovalResult.from_dict(
+            {"action": "block", "retry_plan": {"new_input": 1}, "id": "ev-3"}
+        )
+        d = handle_retryable_block(r)
+        assert d is not None
+        assert d.governance_event_id == "ev-3"
+
+    def test_plain_block_returns_none(self):
+        assert handle_retryable_block(EvaluationResult.from_dict(_block())) is None
+
+    def test_non_block_verdicts_return_none(self):
+        for verdict in ("allow", "constrain", "require_approval", "halt"):
+            r = EvaluationResult.from_dict(
+                {"verdict": verdict, "retry_plan": {"new_input": "x"}}
+            )
+            assert handle_retryable_block(r) is None, verdict
+
+    def test_halt_approval_returns_none_even_with_plan(self):
+        r = ApprovalResult.from_dict(
+            {"action": "halt", "retry_plan": {"new_input": "x"}}
+        )
+        assert handle_retryable_block(r) is None
+
+    def test_expired_approval_returns_none_even_if_block(self):
+        r = ApprovalResult.from_dict(
+            {"action": "block", "retry_plan": {"new_input": "x"}, "expired": True}
+        )
+        assert r.verdict is Verdict.BLOCK
+        assert handle_retryable_block(r) is None
+
+    def test_pending_approval_returns_none(self):
+        r = ApprovalResult.from_dict({"retry_plan": {"new_input": "x"}})
+        assert r.verdict is None
+        assert handle_retryable_block(r) is None
+
+    def test_evaluation_result_never_raises_attributeerror(self):
+        # EvaluationResult has no is_blocking()/expired; the gate must not touch them.
+        r = EvaluationResult.from_dict(_block(retry_plan={"new_input": "x"}))
+        assert handle_retryable_block(r) is not None
+
+    def test_block_without_plan_returns_none(self):
+        assert handle_retryable_block(EvaluationResult.from_dict(_block())) is None
+
+
+class TestEnforcementUnchanged:
+    def test_block_still_raises_even_with_retry_plan(self):
+        # Adding retry_plan support must NOT suppress the default block; the helper is opt-in only.
+        r = EvaluationResult.from_dict(
+            _block(retry_plan={"new_input": "x"}, reason="nope")
+        )
+        with pytest.raises(GovernanceBlockedError):
+            raise_for_verdict(r)

{openbox_sdk_python-1.0.1 → openbox_sdk_python-1.1.0}/tests/runtime/test_runtime_delegation.py

@@ -4,10 +4,12 @@ import httpx
 import pytest
 
 from openbox_core.adapters.base import CoreAdapter, FrameworkAdapter
+from openbox_core.approvals import ApprovalPoller
 from openbox_core.client import EvaluationClient
 from openbox_core.config import OpenBoxConfig
+from openbox_core.contracts.context import ActivityContext
 from openbox_core.contracts.events import workflow_started
-from openbox_core.contracts.results import EvaluationResult, Verdict
+from openbox_core.contracts.results import ApprovalResult, EvaluationResult, Verdict
 from openbox_core.errors import (
     ApprovalRejectedError,
     GovernanceBlockedError,
@@ -45,6 +47,30 @@ class RecordingAdapter:
         self.completed.append(result)
 
 
+class _IdRecordingClient:
+    """Fake client recording the (workflow_id, run_id, activity_id) each async
+    poll is called with, then returning an allow-shaped decision."""
+
+    def __init__(self, seen: list[tuple[str, str, str]]):
+        self._seen = seen
+
+    async def apoll_approval(self, workflow_id, run_id, activity_id):
+        self._seen.append((workflow_id, run_id, activity_id))
+        return ApprovalResult.from_dict({"action": "allow"})
+
+
+class _ContextRecordingAdapter(RecordingAdapter):
+    """RecordingAdapter whose handle_approval ACCEPTS and records ``context``."""
+
+    def __init__(self):
+        super().__init__()
+        self.approval_contexts: list[ActivityContext | None] = []
+
+    async def handle_approval(self, result, context=None):
+        self.approvals.append(result)
+        self.approval_contexts.append(context)
+
+
 def make_runtime(response_json, adapter=None):
     transport = httpx.MockTransport(lambda r: httpx.Response(200, json=response_json))
     client = EvaluationClient(
@@ -91,6 +117,17 @@ class TestLifecycleDelegation:
         assert result.verdict is Verdict.REQUIRE_APPROVAL
         assert len(adapter.approvals) == 1
 
+    async def test_require_approval_threads_event_context(self):
+        # A context-accepting adapter receives the event's workflow/run IDs —
+        # Core's evaluate response never echoes them, so the runtime must supply
+        # them from the originating event.
+        adapter = _ContextRecordingAdapter()
+        runtime = make_runtime({"verdict": "require_approval", "approval_id": "app-1"}, adapter)
+        await runtime.aevaluate_lifecycle(workflow_started(**WF))
+        ctx = adapter.approval_contexts[0]
+        assert ctx is not None
+        assert (ctx.workflow_id, ctx.run_id) == ("wf-1", "r-1")
+
     def test_sync_require_approval_returned_to_caller(self):
         adapter = RecordingAdapter()
         runtime = make_runtime({"verdict": "require_approval"}, adapter)
@@ -117,6 +154,29 @@ class TestCoreAdapterDefaults:
                 EvaluationResult(verdict=Verdict.REQUIRE_APPROVAL, approval_id="a")
             )
 
+    async def test_core_adapter_polls_with_context_ids_not_raw(self):
+        # raw is EMPTY, exactly as a real Core evaluate response is — the poll
+        # IDs must come from the context the runtime threads in.
+        seen: list[tuple[str, str, str]] = []
+        poller = ApprovalPoller(_IdRecordingClient(seen), poll_interval_seconds=0.001)
+        adapter = CoreAdapter(approval_poller=poller)
+        result = EvaluationResult(verdict=Verdict.REQUIRE_APPROVAL, approval_id="a")
+        ctx = ActivityContext(workflow_id="wf-9", run_id="run-9", activity_id="act-9")
+        await adapter.handle_approval(result, context=ctx)
+        assert seen == [("wf-9", "run-9", "act-9")]
+
+    async def test_core_adapter_approval_falls_back_to_raw_without_context(self):
+        seen: list[tuple[str, str, str]] = []
+        poller = ApprovalPoller(_IdRecordingClient(seen), poll_interval_seconds=0.001)
+        adapter = CoreAdapter(approval_poller=poller)
+        result = EvaluationResult(
+            verdict=Verdict.REQUIRE_APPROVAL,
+            approval_id="a",
+            raw={"workflow_id": "wf-raw", "run_id": "run-raw", "activity_id": "act-raw"},
+        )
+        await adapter.handle_approval(result)
+        assert seen == [("wf-raw", "run-raw", "act-raw")]
+
     def test_protocol_conformance(self):
         assert isinstance(CoreAdapter(), FrameworkAdapter)
         assert isinstance(RecordingAdapter(), FrameworkAdapter)