openbox-temporal-sdk-python 1.2.0__py3-none-any.whl → 1.3.0__py3-none-any.whl

openbox/__init__.py

@@ -6,45 +6,43 @@
 # it crashes the workflow sandbox as a circular import, lazily it recurses
 # unboundedly from build_auth_headers on every evaluate. Keep in sync with
 # pyproject.toml on release.
-__version__ = "1.2.0"
-
-from .worker import create_openbox_worker
-
-from .config import (
-    initialize,
-    get_global_config,
-    GovernanceConfig,
-)
+__version__ = "1.3.0"
 
+from .config import GovernanceConfig, get_global_config, initialize
 from .errors import (
-    OpenBoxError,
-    OpenBoxConfigError,
-    OpenBoxAuthError,
-    OpenBoxNetworkError,
-    OpenBoxInsecureURLError,
-    OpenBoxSigningError,
-    GovernanceBlockedError,
-    GovernanceHaltError,
-    GovernanceAPIError,
-    GuardrailsValidationError,
     ApprovalExpiredError,
     ApprovalRejectedError,
     ApprovalTimeoutError,
+    GovernanceAPIError,
+    GovernanceBlockedError,
+    GovernanceHaltError,
+    GuardrailsValidationError,
+    OpenBoxAuthError,
+    OpenBoxConfigError,
+    OpenBoxError,
+    OpenBoxInsecureURLError,
+    OpenBoxNetworkError,
+    OpenBoxSigningError,
     extract_governance_error,
     map_signing_error,
 )
 
-from .types import (
-    Verdict,
-    WorkflowEventType,
-    GovernanceVerdictResponse,
-    GuardrailsCheckResult,
-)
-
 # Multi-agent primitives (sandbox-safe — only imports temporalio.workflow eagerly;
 # signing/HTTP routed lazily through the governance activity).
 from .multi_agent import emit_handoff
 
+# Retryable-BLOCK restart envelope (sandbox-safe: pure stdlib + base contracts).
+from .retryable_block import (
+    GOVERNANCE_RETRYABLE_BLOCK_SCHEMA_VERSION,
+    RetryableBlockRequest,
+)
+from .types import (
+    GovernanceVerdictResponse,
+    GuardrailsCheckResult,
+    Verdict,
+    WorkflowEventType,
+)
+from .worker import create_openbox_worker
 from .workflow_interceptor import GovernanceInterceptor
 
 try:
@@ -54,11 +52,9 @@ try:
 except ImportError:
     pass  # temporalio < 1.23.0, plugin not available
 
-from .verdict_handler import enforce_verdict, VerdictEnforcementResult
-
-from .hitl import handle_approval_response, raise_approval_pending, should_skip_hitl
-
 from .client import GovernanceClient
+from .hitl import handle_approval_response, raise_approval_pending, should_skip_hitl
+from .verdict_handler import VerdictEnforcementResult, enforce_verdict
 
 # NOTE: ActivityGovernanceInterceptor is NOT imported here because it imports
 # OpenTelemetry which uses importlib_metadata -> os.stat, causing sandbox issues.
@@ -114,6 +110,8 @@ __all__ = [
     "WorkflowEventType",
     "GovernanceVerdictResponse",
     "GuardrailsCheckResult",
+    "RetryableBlockRequest",
+    "GOVERNANCE_RETRYABLE_BLOCK_SCHEMA_VERSION",
     "emit_handoff",
     "GovernanceInterceptor",
     "enforce_verdict",

openbox/activities.py

@@ -21,18 +21,16 @@ executes. This ensures timestamps are generated in activity context (non-determi
 code allowed) rather than workflow context (must be deterministic).
 """
 
-import httpx
 import logging
 from datetime import datetime, timezone
-from typing import Dict, Any, Optional
-
-
-from .types import rfc3339_now as _rfc3339_now
+from typing import Any, Dict, Optional
 
+import httpx
 from temporalio import activity
 from temporalio.exceptions import ApplicationError
 
-from .types import Verdict
+from .types import GovernanceVerdictResponse, Verdict
+from .types import rfc3339_now as _rfc3339_now
 
 logger = logging.getLogger(__name__)
 
@@ -201,12 +199,26 @@ class GovernanceActivities:
                     )
 
                 data = response.json()
-                verdict = Verdict.from_string(
-                    data.get("verdict") or data.get("action", "continue")
-                )
-                reason = data.get("reason")
-                policy_id = data.get("policy_id")
-                risk_score = data.get("risk_score", 0.0)
+                parsed = GovernanceVerdictResponse.from_dict(data)
+                verdict = parsed.verdict
+                reason = parsed.reason
+                policy_id = parsed.policy_id
+                risk_score = parsed.risk_score
+
+                # A BLOCK carrying a valid retry plan restarts the workflow run
+                # instead of merely failing this activity — check for it before
+                # the plain BLOCK/HALT stop handling below ever sees the verdict.
+                from .errors import GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE
+                from .retryable_block import retryable_block_request
+
+                retry_req = retryable_block_request(parsed, event_type=event_type)
+                if retry_req is not None:
+                    raise ApplicationError(
+                        "Governance requested workflow restart",
+                        retry_req.to_dict(),
+                        type=GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE,
+                        non_retryable=True,
+                    )
 
                 if verdict.should_stop():
                     result = await _handle_stop_verdict(

openbox/activity_interceptor.py

@@ -11,12 +11,11 @@ IMPORTANT: Activities CAN use datetime/time and make HTTP calls directly.
 This is different from workflow interceptors which must maintain determinism.
 """
 
-from typing import Optional, Any, List
 import dataclasses
-from dataclasses import asdict, is_dataclass, fields
-import time
 import json
-
+import time
+from dataclasses import asdict, fields, is_dataclass
+from typing import Any, List, NoReturn, Optional
 
 from .types import rfc3339_now as _rfc3339_now
 
@@ -63,27 +62,44 @@ def _update_list_items(current_list: list, new_list: list, _logger=None) -> None
             current_list[i] = new_item
 
 
+from opentelemetry import trace
 from temporalio import activity
 from temporalio.worker import (
-    Interceptor,
     ActivityInboundInterceptor,
     ExecuteActivityInput,
+    Interceptor,
 )
-from opentelemetry import trace
 
+from .activities import _terminate_workflow_for_halt
+from .client import GovernanceClient
 from .config import GovernanceConfig
 from .core_adapter import core_activity_scope, get_core_context_store
-from .governance_state import TemporalGovernanceState
-from .types import (
-    WorkflowEventType,
-    GovernanceVerdictResponse,
-    Verdict,
+from .errors import (
+    GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE,
+    GovernanceBlockedError,
+    GovernanceHaltError,
+    GuardrailsValidationError,
 )
+from .governance_state import TemporalGovernanceState
 from .multi_agent import read_session_from_header
-from .activities import _terminate_workflow_for_halt
+from .retryable_block import RetryableBlockRequest, retryable_block_request
+from .types import GovernanceVerdictResponse, Verdict, WorkflowEventType
 from .verdict_handler import enforce_verdict
-from .errors import GovernanceBlockedError, GovernanceHaltError, GuardrailsValidationError
-from .client import GovernanceClient
+
+
+def _raise_retryable_block(req: RetryableBlockRequest) -> NoReturn:
+    """Raise the stable, versioned ``GovernanceRetryableBlock`` ApplicationError
+    for a valid retryable-BLOCK directive. Non-retryable — the workflow
+    interceptor catches this stable type and Continue-As-News with the
+    replacement input."""
+    from temporalio.exceptions import ApplicationError
+
+    raise ApplicationError(
+        "Governance requested workflow restart",
+        req.to_dict(),
+        type=GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE,
+        non_retryable=True,
+    )
 
 
 def _serialize_value(value: Any) -> Any:
@@ -94,6 +110,12 @@ def _serialize_value(value: Any) -> Any:
         return value
     if isinstance(value, bytes):
         return _serialize_bytes(value)
+    model_dump = getattr(value, "model_dump", None)
+    if callable(model_dump):
+        try:
+            return model_dump(mode="json")
+        except Exception:
+            pass
     if is_dataclass(value) and not isinstance(value, type):
         return asdict(value)
     if isinstance(value, (list, tuple)):
@@ -111,6 +133,7 @@ def _serialize_bytes(value: bytes) -> str:
         return value.decode("utf-8")
     except Exception:
         import base64
+
         return base64.b64encode(value).decode("ascii")
 
 
@@ -238,35 +261,56 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             )
         except Exception:
             # The activity (or a hook) raised, so _handle_completion is skipped. A
-            # completed-hook HALT recorded during user code is a kill-switch and
-            # must STILL reach the terminate path — failing the activity does not
-            # halt the workflow. Consume the completed-stop here too (also clears
-            # it, so it can never strand/leak on the exception path).
+            # completed-hook stop recorded during user code must still be enforced:
+            # HALT reaches the terminate path and raises GovernanceHalt, and a
+            # retryable request raises GovernanceRetryableBlock — either REPLACES
+            # the original exception (completed-hook priority HALT > retryable >
+            # original exception). A plain completed BLOCK is a no-op, so the
+            # `raise` below re-propagates the original exception unchanged. Consume
+            # the completed-stop either way (also clears it, so it can never
+            # strand/leak on the exception path).
             await self._consume_completed_halt(info)
             raise
 
         result = await self._handle_completion(
-            info, status, error, start_time, end_time,
-            activity_input, activity_output, result,
+            info,
+            status,
+            error,
+            start_time,
+            end_time,
+            activity_input,
+            activity_output,
+            result,
             session_id,
         )
 
         return result
 
     async def _consume_completed_halt(self, info) -> None:
-        """Exception-path safety net: a completed-hook HALT recorded during user
-        code must terminate the workflow even when the activity itself raised.
-        Clears the completed-stop and the base abort flag so nothing strands."""
+        """Exception-path safety net: a completed-hook stop recorded during user
+        code must still be enforced even though the activity itself raised, so
+        _handle_completion (the success path) never runs. Priority: HALT raises
+        GovernanceHalt (terminating the workflow and REPLACING the original
+        exception); a retryable request raises GovernanceRetryableBlock (also
+        replacing the original exception with the restart request); a plain
+        completed BLOCK is a no-op here, so the caller's re-raise propagates the
+        original exception unchanged. Clears the completed-stop and the base abort
+        flag so nothing strands."""
         stop = self._state.take_completed_stop(
             info.workflow_id, info.workflow_run_id, info.activity_id
         )
         get_core_context_store().clear_activity_aborted(
             info.workflow_id, info.activity_id
         )
-        if stop is not None and stop[0] is Verdict.HALT:
+        if stop is None:
+            return
+        if stop.verdict is Verdict.HALT:
             await _terminate_workflow_for_halt(
-                info.workflow_id, stop[1] or "Governance halt"
+                info.workflow_id, stop.reason or "Governance halt"
             )
+            return
+        if stop.request is not None:
+            _raise_retryable_block(stop.request)
 
     async def _check_pending_verdicts(self, info) -> None:
         """Enforce a SignalReceived BLOCK/HALT recorded for this run by the
@@ -292,6 +336,7 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             await _terminate_workflow_for_halt(workflow_id, reason)
         else:
             from temporalio.exceptions import ApplicationError
+
             raise ApplicationError(
                 f"Governance blocked: {reason}",
                 type="GovernanceBlock",
@@ -329,9 +374,7 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             info.activity_id,
         )
         if approved:
-            activity.logger.info(
-                f"Approval granted for workflow_id={info.workflow_id}"
-            )
+            activity.logger.info(f"Approval granted for workflow_id={info.workflow_id}")
             self._state.clear_pending_approval(
                 info.workflow_id, info.workflow_run_id, info.activity_id
             )
@@ -362,7 +405,21 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
         self, verdict_response: GovernanceVerdictResponse, info, context: str
     ) -> None:
         """Enforce a governance verdict (HITL, BLOCK, HALT, guardrails)."""
-        from .hitl import should_skip_hitl, raise_approval_pending
+        from .hitl import raise_approval_pending, should_skip_hitl
+
+        # An exact BLOCK with a valid retry plan requests a workflow restart and
+        # takes priority over the generic BLOCK/HALT/guardrails mapping below —
+        # checked before enforce_verdict() so it is never first converted to a
+        # plain GovernanceBlockedError. These are REAL activity-lifecycle events
+        # (not hooks), so hook_trigger stays the default False.
+        event_type = (
+            WorkflowEventType.ACTIVITY_STARTED.value
+            if context == "activity_start"
+            else WorkflowEventType.ACTIVITY_COMPLETED.value
+        )
+        req = retryable_block_request(verdict_response, event_type=event_type)
+        if req is not None:
+            _raise_retryable_block(req)
 
         try:
             verdict_result = enforce_verdict(verdict_response, context)
@@ -384,6 +441,7 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             await _terminate_workflow_for_halt(info.workflow_id, str(e))
         except GovernanceBlockedError as e:
             from temporalio.exceptions import ApplicationError
+
             raise ApplicationError(
                 f"Governance blocked: {e.reason}",
                 type="GovernanceBlock",
@@ -391,6 +449,7 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
             )
         except GuardrailsValidationError as e:
             from temporalio.exceptions import ApplicationError
+
             activity.logger.info(f"Guardrails validation failed: {e}")
             raise ApplicationError(
                 f"Guardrails validation failed: {e}",
@@ -510,8 +569,16 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
         return result, status, error, activity_output, end_time
 
     async def _handle_completion(
-        self, info, status, error, start_time, end_time,
-        activity_input, activity_output, result, multi_agent_session_id=None,
+        self,
+        info,
+        status,
+        error,
+        start_time,
+        end_time,
+        activity_input,
+        activity_output,
+        result,
+        multi_agent_session_id=None,
     ) -> Any:
         """Send ActivityCompleted, enforce verdict, apply output redaction."""
         store = get_core_context_store()
@@ -525,10 +592,16 @@ class _ActivityInterceptor(ActivityInboundInterceptor):
         base_aborted = store.is_activity_aborted(info.workflow_id, info.activity_id)
         store.clear_activity_aborted(info.workflow_id, info.activity_id)
 
-        if completed_stop is not None and completed_stop[0] is Verdict.HALT:
-            await _terminate_workflow_for_halt(
-                info.workflow_id, completed_stop[1] or "Governance halt"
-            )
+        if completed_stop is not None:
+            if completed_stop.verdict is Verdict.HALT:
+                await _terminate_workflow_for_halt(
+                    info.workflow_id, completed_stop.reason or "Governance halt"
+                )
+            elif completed_stop.request is not None:
+                # A retryable request outranks the plain skip-completed-event
+                # behavior below — raise the restart request now that user code
+                # has already returned.
+                _raise_retryable_block(completed_stop.request)
 
         was_aborted = base_aborted or completed_stop is not None
 

openbox/config.py

@@ -10,17 +10,16 @@ linecache -> os.stat which triggers Temporal sandbox restrictions.
 
 import re
 from dataclasses import dataclass, field
-from typing import Set, Optional
+from typing import Optional, Set
 
 from openbox_core.errors import OpenBoxConfigError as CoreOpenBoxConfigError
-from openbox_core.identity import (
-    AGENT_DID_PREFIX as CORE_AGENT_DID_PREFIX,
-    load_ed25519_seed as load_core_ed25519_seed,
-    validate_agent_did as validate_core_agent_did,
-)
 
-# NOTE: urllib and logging imports are lazy to avoid Temporal sandbox restrictions.
-# Both use os.stat internally which triggers sandbox errors.
+# NOTE: urllib, logging, and openbox_core.identity imports are lazy to avoid
+# Temporal sandbox restrictions. urllib/logging use os.stat internally; identity
+# pulls cryptography. None may load on a workflow-sandbox import path
+# (openbox/__init__ → worker → config), so identity is imported inside the
+# functions that need it and via module __getattr__ for AGENT_DID_PREFIX.
+# Guarded by tests/test_workflow_sandbox_import_safety.py.
 
 
 def _get_logger():
@@ -33,15 +32,24 @@ def _get_logger():
 # API key format pattern (obx_live_... or obx_test_...)
 API_KEY_PATTERN = re.compile(r"^obx_(live|test)_\w+$")
 
-# Backward-compatible public constant, owned by the base SDK.
-AGENT_DID_PREFIX = CORE_AGENT_DID_PREFIX
+
+# Backward-compatible public constant, owned by the base SDK. Resolved lazily via
+# module __getattr__ (PEP 562) so a workflow-sandbox import of openbox.config never
+# eagerly loads openbox_core.identity (and its cryptography dependency).
+def __getattr__(name: str):
+    if name == "AGENT_DID_PREFIX":
+        from openbox_core.identity import AGENT_DID_PREFIX as _prefix
+
+        return _prefix
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
 
 # Re-export from errors.py for backward compatibility
 from .errors import (  # noqa: F401
-    OpenBoxConfigError,
     OpenBoxAuthError,
-    OpenBoxNetworkError,
+    OpenBoxConfigError,
     OpenBoxInsecureURLError,
+    OpenBoxNetworkError,
 )
 
 # GovernanceConfig - Configuration for interceptors
@@ -117,6 +125,22 @@ class GovernanceConfig:
     # Temporal currently uses its native retry backoff for HITL polling.
     hitl_poll_interval_ms: int = 5000
 
+    # Maximum Continue-As-New restarts a retryable BLOCK may trigger across the
+    # whole workflow chain (bounded input-remediation loop). Applies uniformly to
+    # every event origin; must be >= 1.
+    max_retryable_block_restarts: int = 3
+
+    def __post_init__(self) -> None:
+        # GovernanceConfig is public and can be handed directly to an interceptor,
+        # bypassing the factory/plugin — so validation lives on the dataclass (the
+        # single source of truth), not only at the call sites. Pure + sandbox-safe:
+        # raises the already-imported OpenBoxConfigError, no logging/IO.
+        if self.max_retryable_block_restarts < 1:
+            raise OpenBoxConfigError(
+                "max_retryable_block_restarts must be >= 1 "
+                f"(got {self.max_retryable_block_restarts})"
+            )
+
 
 # Global Configuration Singleton
 
@@ -128,6 +152,8 @@ def _validate_api_key_format(api_key: str) -> bool:
 
 def _validate_did(agent_did: str) -> None:
     """Validate agent DID format through the shared base SDK."""
+    from openbox_core.identity import validate_agent_did as validate_core_agent_did
+
     try:
         validate_core_agent_did(agent_did)
     except CoreOpenBoxConfigError as exc:
@@ -150,6 +176,8 @@ def resolve_signing_defaults(agent_did, signer):
 
 def _load_ed25519_seed(agent_private_key: str):
     """Decode and load an Ed25519 signer through the shared base SDK."""
+    from openbox_core.identity import load_ed25519_seed as load_core_ed25519_seed
+
     try:
         return load_core_ed25519_seed(agent_private_key)
     except CoreOpenBoxConfigError as exc:
@@ -218,8 +246,8 @@ def _validate_api_key_with_server(
     urllib.request uses os.stat internally which triggers sandbox errors.
     """
     # Lazy imports to avoid sandbox restrictions
-    from urllib.request import Request, urlopen
     from urllib.error import HTTPError, URLError
+    from urllib.request import Request, urlopen
 
     # Build signed (or plain) headers via the single source of truth.
     from .request_signing import prepare_signed_request

openbox/core_adapter.py

@@ -9,7 +9,10 @@ effects and never builds hook payloads or evaluates hook events itself:
   ``ApprovalPending`` (Temporal's native HITL retry loop) + a pending marker in
   ``TemporalGovernanceState``; completed-hook BLOCK/HALT -> recorded in
   ``TemporalGovernanceState`` (run-scoped) for the activity interceptor to
-  surface after user code returns.
+  surface after user code returns. An exact BLOCK carrying a valid retry plan
+  is checked FIRST at every one of these seams and raises the stable, versioned
+  ``GovernanceRetryableBlock`` instead — HALT still wins because the base
+  normalizer never surfaces a directive for it.
 - ``core_activity_scope`` binds the shared ``ActivityContext`` around activity
   execution with a GUARANTEED try/finally reset.
 
@@ -31,8 +34,10 @@ from openbox_core.contracts.results import EvaluationResult, Verdict
 from .errors import (
     GOVERNANCE_BLOCK_ERROR_TYPE,
     GOVERNANCE_HALT_ERROR_TYPE,
+    GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE,
 )
 from .governance_state import TemporalGovernanceState
+from .retryable_block import RetryableBlockRequest, retryable_block_request
 
 logger = logging.getLogger(__name__)
 
@@ -78,7 +83,9 @@ class TemporalFrameworkAdapter:
         self._state = state
         self._hitl_enabled = hitl_enabled
         self._skip_hitl_activity_types = skip_hitl_activity_types or set()
-        self._store = context_store if context_store is not None else _core_context_store
+        self._store = (
+            context_store if context_store is not None else _core_context_store
+        )
 
     async def handle_approval(self, result: EvaluationResult) -> None:
         """Async hook REQUIRE_APPROVAL -> Temporal's retry-based HITL loop.
@@ -125,9 +132,25 @@ class TemporalFrameworkAdapter:
         raise_approval_pending(result.reason or "Approval required")
 
     def raise_lifecycle_blocked(self, result: EvaluationResult) -> NoReturn:
+        # An exact BLOCK with a valid retry plan requests a workflow restart and
+        # is checked before the generic BLOCK/HALT mapping; HALT still wins
+        # because retryable_block_request never surfaces a directive for it.
+        req = retryable_block_request(result, event_type="ActivityStarted")
+        if req is not None:
+            self._raise_retryable_block(req)
         self._raise_application_error(result)
 
     def raise_hook_blocked(self, result: EvaluationResult) -> NoReturn:
+        # Started hooks are wire-represented as ActivityStarted + hook_trigger=
+        # True (the stage rides in hook_stage) — same retryable-first ordering.
+        req = retryable_block_request(
+            result,
+            event_type="ActivityStarted",
+            hook_trigger=True,
+            hook_stage="started",
+        )
+        if req is not None:
+            self._raise_retryable_block(req)
         self._raise_application_error(result)
 
     def on_completed_hook_result(
@@ -135,17 +158,31 @@ class TemporalFrameworkAdapter:
     ) -> None:
         """Completed verdicts affect FUTURE execution only (the operation already
         ran). Record a BLOCK/HALT run-scoped so the activity interceptor can skip
-        a duplicate completed event (BLOCK) or reach the terminate path (HALT)
-        after user code returns. Without a resolved context there is no run to key
-        on — the base ContextStore still carries the within-activity abort flag."""
+        a duplicate completed event (plain BLOCK), reach the terminate path
+        (HALT), or raise a retryable-BLOCK restart request (BLOCK with a valid
+        retry plan) after user code returns. Without a resolved context there is
+        no run to key on — the base ContextStore still carries the
+        within-activity abort flag.
+
+        Every hook is wire-represented as ``event_type="ActivityStarted"`` with
+        ``hook_trigger=True`` — the completed stage rides ONLY in ``hook_stage``,
+        never by flipping ``event_type`` to ``ActivityCompleted``.
+        """
         if not result.verdict.should_stop() or context is None:
             return
+        request = retryable_block_request(
+            result,
+            event_type="ActivityStarted",
+            hook_trigger=True,
+            hook_stage="completed",
+        )
         self._state.record_completed_stop(
             context.workflow_id or "",
             context.run_id or "",
             context.activity_id or "",
             result.verdict,
             result.reason,
+            request,
         )
 
     @staticmethod
@@ -165,6 +202,19 @@ class TemporalFrameworkAdapter:
             non_retryable=True,
         )
 
+    @staticmethod
+    def _raise_retryable_block(req: RetryableBlockRequest) -> NoReturn:
+        """Raise the stable, versioned ``GovernanceRetryableBlock`` the workflow
+        interceptor catches to Continue-As-New with the replacement input."""
+        from temporalio.exceptions import ApplicationError
+
+        raise ApplicationError(
+            "Governance requested workflow restart",
+            req.to_dict(),
+            type=GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE,
+            non_retryable=True,
+        )
+
 
 def build_core_activity_context(
     info: Any,

openbox/errors.py

@@ -36,6 +36,15 @@ GOVERNANCE_API_ERROR_TYPE: Final[str] = "GovernanceAPIError"
 # Legacy alias; kept for histories predating the rename.
 GOVERNANCE_STOP_ERROR_TYPE: Final[str] = "GovernanceStop"
 
+# Retryable-BLOCK restart transport. A governance BLOCK carrying a valid retry
+# plan crosses the activity/workflow boundary as a non-retryable ApplicationError
+# of this stable type; the workflow interceptor catches it and Continue-As-News.
+GOVERNANCE_RETRYABLE_BLOCK_ERROR_TYPE: Final[str] = "GovernanceRetryableBlock"
+# Raised when the bounded restart chain would exceed max_retryable_block_restarts.
+GOVERNANCE_RETRY_LIMIT_EXCEEDED_ERROR_TYPE: Final[str] = "GovernanceRetryLimitExceeded"
+# Raised when replacement input cannot be converted for Continue-As-New.
+GOVERNANCE_RETRY_INPUT_INVALID_ERROR_TYPE: Final[str] = "GovernanceRetryInputInvalid"
+
 
 class OpenBoxError(Exception):
     """Base class for all OpenBox SDK errors."""
@@ -105,7 +114,9 @@ _SIGNING_REASON_MESSAGES: dict[str, str] = {
 }
 
 
-def map_signing_error(reason_code: str | None, fallback: str = "") -> OpenBoxSigningError:
+def map_signing_error(
+    reason_code: str | None, fallback: str = ""
+) -> OpenBoxSigningError:
     """Map a Core signing reason code to an actionable OpenBoxSigningError.
 
     Unknown/empty codes fall back to a generic message (optionally augmented with