nullrun 0.16.4__tar.gz → 0.16.6__tar.gz

{nullrun-0.16.4 → nullrun-0.16.6}/CHANGELOG.md

@@ -1,3 +1,81 @@
+## [0.16.6] - 2026-09-08
+
+Patch release — closes the SDK↔backend drift introduced by backend `DEF-SDKK-022-EXEC-BYPASS` (2026-09-04, RUN_ID=20260904T1500). After that backend fix, `/api/v1/execute` runs an `execution:{id}` ownership-binding existence check and returns 404 EXECUTION_NOT_FOUND for any execution_id that was not minted by a prior `/api/v1/gate`. The SDK's `runtime.execute()` had been minting a fresh `uuid7_str()` regardless of prior `/gate`, so every `@protect @sensitive` call returned 404 ("Gateway returned 404") and the displayed workflow_id was the misleading `__nullrun_unknown__` sentinel. LangGraph's `NullRunCallback.on_llm_start` had the symmetric problem on the LLM span side: it fired `llm_call` cost events with no paired `/gate` reservation, so the runtime's `_route_track` silently dropped them. This release closes all three holes. No wire-format change.
+
+### Fixed
+
+- **DEFS-SDKEXEC-GATE-FIRST** — `runtime.execute()` reuses the server-minted execution_id from `_server_minted_execution_id_var` when a prior `/gate` minted it (`src/nullrun/runtime.py:2820+`). Pre-fix minted `uuid7_str()` unconditionally; post-fix reads the contextvar (set by `check_workflow_budget`'s `_capture_server_minted_execution_id` from the `/gate` response's `reservation_id` field) and only mints fresh when the contextvar is empty (direct callers without a prior `/gate`, which is a wire-contract violation the backend's 404 handles correctly). Comment block at the fix site names both DEFS-SDKEXEC-GATE-FIRST and DEF-SDKK-022-EXEC-BYPASS so future readers see the round-trip contract without searching.
+- **DEFS-SDKEXEC-WORKFLOW-LABEL** — `_enforce_sensitive_tool` displays the API key's bound workflow via `runtime._resolve_workflow_id(get_workflow_id())` instead of the literal `__nullrun_unknown__` sentinel (`src/nullrun/decorators.py`). The wire still carries the same workflow_id (server-side binding); only the displayed label changes. Two sites updated (extract failure path + main path).
+- **DEFS-SDKEXEC-LLM-RESERVATION** — `NullRunCallback.on_llm_start` (`src/nullrun/instrumentation/langgraph.py`) fires `runtime.check_workflow_budget()` (fail-OPEN) so the matching `on_llm_end` `llm_call` cost event has a server-minted reservation_id and routes via `/track_single` instead of being dropped by `runtime._route_track` (the WARNING log "dropping llm_call event — no server-minted reservation_id in scope"). The call is wrapped in `except BaseException` so a backend outage or `WorkflowKilledInterrupt` / `WorkflowPausedException` never breaks the LangChain callback contract.
+- **`Transport.execute` docstring** (`src/nullrun/transport.py`) — rewrites the misleading pre-2026-09-04 claim ("/execute MUST be called rather than /gate") to reflect the post-DEF-SDKK-022-EXEC-BYPASS contract ("/execute MUST be preceded by /gate for the same execution_id"). Names both fix tags so the contract is grep-able.
+
+### Added
+
+- **`tests/test_2026_09_08_gate_first_execute.py`** (9 tests). Source-pin regression for all three fixes:
+    - `runtime.execute()` reads `get_server_minted_execution_id()` and reuses it when present (forbids re-introducing an unconditional `uuid7_str()` mint outside the fallback arm).
+    - `_enforce_sensitive_tool` displays via `runtime._resolve_workflow_id(...)` (forbids the pre-fix contextvar-only fallback).
+    - `Transport.execute` docstring references the post-fix contract (forbids the legacy misleading claim).
+    - `NullRunCallback.on_llm_start` calls `check_workflow_budget()` with a never-raise guard.
+    - Contextvar round-trip sanity (`set_server_minted_execution_id` / `get_server_minted_execution_id`).
+
+### Compatibility
+
+Pure reliability fixes — no wire-format change. `/gate`, `/execute`, `/track`, `/cancel` payloads are byte-identical to 0.16.5. The drift existed only on the SDK side; this release brings the SDK in line with the backend's 2026-09-04 contract without rolling back any backend-side hardening.
+
+### Why this is needed
+
+**Gate-first** — the user-facing symptom was that `langgraph_openai_approval_demo.py` (and any `@protect @sensitive` decorator that was actually wired through `runtime.execute()`) returned `Workflow __nullrun_unknown__ blocked: Gateway returned 404` for every call, with `action=block, status_code=None`. The approval rule never had a chance to fire because the 404 was raised on the existence-of-binding check before the policy engine ran. The 0.12.0 SDK had been silently broken against post-2026-09-04 backends for the entire /execute path; this release closes the four-day window of broken `/execute` behaviour.
+
+**Workflow label** — `__nullrun_unknown__` was misleading because the SDK did know the workflow (the API key's binding) but only read the contextvar (which was unset on bare `@protect` calls). The displayed label was wrong; the wire was right. Operators reading traces had no signal that the gate had, in fact, scoped the call to a real workflow.
+
+**LLM reservation** — LangGraph's `NullRunCallback` emits LLM cost events from the LangChain callback hooks. These have no `@protect` scope and therefore no paired `/gate`. The runtime's `_route_track` (which since v0.16.0 / 2026-08-20 backend v3.66.2 alignment refuses to fall back to `/track/batch` for `llm_call` events without a reservation) dropped them with a WARNING log. Cost attribution for agentic LLM loops was silently incomplete. The fix fires `/gate` once per LLM span (fail-OPEN; same wire-call shape as `@protect`), so cost attribution completes via the v3 `/track_single` path.
+
+## [0.16.5] - 2026-09-05
+
+Patch release — two independent reliability fixes: (1) `@protect` cancel-on-exception orphan leak (Redis reservation leak on tool exceptions), (2) P0-26+P0-27 `operation_id` hoist (single-source mint, server-vs-SDK divergence detection). No wire-format change on either fix.
+
+### Fixed
+
+- **`@protect` cancel-on-exception orphan leak** (`src/nullrun/decorators.py`). Both `async_wrapper` and `sync_wrapper` now wrap the with-block in a try/except; on failure, `_safe_cancel_active_execution(reason="tool_exception")` closes the in-flight `/gate` reservation so the budget envelope is released immediately rather than waiting on TTL expiry. Three invariant pins:
+    - **Asymmetry on exception scope.** `async_wrapper` catches `Exception`, NOT `BaseException` — `asyncio.CancelledError`, `KeyboardInterrupt`, and `SystemExit` propagate without doing a synchronous blocking HTTP call inside a cancellation handler. That call has a 5s timeout; inside a cancellation handler it would (a) delay task cancellation by up to 5s on network errors, (b) make `Task was destroyed but it is pending` warnings more frequent and harder to diagnose, and (c) in some shutdown paths get cancelled itself, leaving cleanup incomplete (the server's `/cancel` is idempotent so this is acceptable — orphan via TTL/reconciliation instead). `sync_wrapper` catches `BaseException` to match existing `_protect_body` unify_block semantics; sync code has no event loop to delay and a Ctrl+C during a long sync agent gets a few seconds of cancel I/O before exit.
+    - **`fn_completed` sentinel.** After `fn(...)` returns, `fn_completed = True`. If `track_tool(...)` then fails (rare `/track` batch-sender network error), the wrapper's `except` runs but `fn_completed` is True so cancel does NOT fire — side effects already happened and the right move is to retry `track_tool`, not cancel (which would tell the server "no side effects" — a lie that produces a phantom budget refund and breaks audit).
+    - **Helper is fail-OPEN.** `_safe_cancel_active_execution` swallows everything (`NullRunTransportError`, `NullRunBackendError`, `get_runtime()` failures) so a cancel I/O failure never masks the original exception. An orphan from cancel failure is preferred over masking a `ValueError` from `fn()`.
+- **P0-26 — `operation_id` server-vs-SDK divergence detection** (`src/nullrun/runtime.py`, `src/nullrun/context.py`). `_capture_server_minted_execution_id` previously read `response.get('operation_id')` directly; if a proxy or a backend bug echoed back a different `operation_id` than the SDK minted, the SDK had no signal — audit row stored one id, downstream `/track` used another. Now reads via `_get_op_id_for_capture()` (the SDK-minted contextvar value) and asserts `server_op_id != sdk_op_id` with ERROR log on disagreement. `idempotency_key` is derived from the SDK-minted value, not the server echo, so a divergent server response cannot break idempotency.
+- **P0-27 — `operation_id` hoisted to contextvar; triple-mint collapsed to one** (`src/nullrun/context.py`, `src/nullrun/runtime.py`). New `_operation_id_var` contextvar (name `operation_id`) in `context.py`. `check_workflow_budget` mints ONCE via `_get_op_id_for_check()` / `_set_op_id_for_check()`; `execute` reads via `_get_op_id_for_execute()` with a single fallback mint+stash branch (only runs if `/check` did not run — pre-execution paths that bypass `/check`). The previous code minted at three sites independently, which meant a divergence between `/check` mint and `/execute` mint produced an audit-row-vs-/execute id mismatch.
+
+### Added
+
+- **`tests/test_protect_cancel_on_exception.py`** (7 tests). Pins both halves of the asymmetry and the helper's behavior:
+    - `test_1_async_cancelled_error_does_not_trigger_cancel` — the regression guard. If a future refactor reverts `except Exception` to `except BaseException` in `async_wrapper`, this test fails. `set_server_minted_execution_id(...)` is set so the helper WOULD have run if the except had caught BaseException; `cancel_calls` must be empty.
+    - `test_2_track_tool_failure_after_fn_completion_does_not_trigger_cancel` — the second regression guard. If someone removes the `fn_completed` sentinel, this test fails (cancel would run on a successfully-completed tool, producing a phantom refund).
+    - `test_3_async_fn_raises_value_error_triggers_cancel` — happy-path cancel. `cancel_calls == [("exec-test-123", "tool_exception")]`.
+    - `test_4_async_no_execution_id_skips_cancel` — control_plane reject happens pre-`/gate`, ContextVar stays None, no cancel.
+    - `test_5_sync_fn_raises_value_error_triggers_cancel` — sync ValueError path mirrors async.
+    - `test_6_sync_baseexception_also_triggers_cancel` — sync `KeyboardInterrupt` cancels (sync has no event loop to delay).
+    - `test_happy_path_no_cancel_called` — sanity: success path produces no cancel and gate order stays `control_plane, budget, track_tool`.
+- **`tests/test_audit_p0_27_operation_id_hoist.py`** (8 tests). Pins the single-source-mint + server-vs-SDK divergence detection:
+    - contextvar name `operation_id` (forbids any other name; would silently disable mint if renamed without a corresponding accessor change).
+    - mint-site shapes in `check_workflow_budget` and `execute` (forbids pre-fix `str(uuid.uuid4())` mints outside the fallback branch).
+    - parity assertion in `_capture_server_minted_execution_id` (server_op_id vs sdk_op_id equality required for the no-warn path).
+    - fallback mint+stash in `execute` only fires when `/check` did not mint (idempotency: one operation_id per call site, never two).
+
+### Compatibility
+
+Pure reliability fixes — no wire-format change on either fix. Cancel-on-exception: existing exception paths unchanged; the cancel I/O is purely additive cleanup. Operation-id hoist: wire field `operation_id` is unchanged; the SDK now uses a single mint source and adds a server-divergence warning, both invisible to the wire contract.
+
+### Verification
+
+- Targeted suite: `tests/test_protect_cancel_on_exception.py` — 7/7 pass.
+- Targeted suite: `tests/test_audit_p0_27_operation_id_hoist.py` — 8/8 pass.
+- Broader regression suite: `pytest -q` clean (prior 1613 + 7 + 8 = 1628); `ruff check src tests` clean on the WIP files (decorators.py + test_protect_cancel_on_exception.py); `mypy src/nullrun` no issues reported in 37 source files.
+- Wire-format: zero changes on both fixes. Same `/gate`, `/track`, `/execute`, `/cancel` payloads. The `/cancel` endpoint was already used by `runtime.cancel_execution(...)` from control-plane kill paths, just now also from the exception-cleanup helper. `operation_id` field on the wire was already a single string; this release only changes where the SDK mints/reads it locally.
+
+### Why this is needed
+
+**Cancel-on-exception** — at anti-DoS scale, every orphaned reservation is a permanent slot in `reserved_total` until TTL expiry. A noisy control-plane kill switch OR a single bad batch of tool exceptions could leak thousands of reservations per hour, gradually starving legitimate traffic out of the budget envelope. The fix collapses the leak window from "TTL expiry" (~minutes) to "synchronous cancel I/O on exception" (~ms), with the fail-OPEN helper guaranteeing we never trade an orphan for a swallowed exception.
+
+**Operation-id hoist** — pre-fix, three independent mints meant a race between `/check` and `/execute` could produce two different ids for the same logical call. The audit row stored one, `/execute` sent another, downstream `/track` chained off yet another. Server-vs-SDK divergence had no detection. P0-27 collapses to a single SDK-minted value; P0-26 adds the parity assertion so a divergent server echo is logged at ERROR before it propagates into audit/retry logic.
+
 ## [0.16.4] - 2026-08-31
 
 Patch release — ADR-037 Slice B. The wire protocol bumps from 3 → 4 additively: `/gate` response now echoes the SDK-supplied `action_digest` and a `policy_hash` slot (always `None` today; Slice D wires per-request computation). `min_protocol_version` stays at 2 so v3 SDKs are unaffected. Wire-format additive only — no new hashing/computation introduced on either side (both fields echo already-computed values).

{nullrun-0.16.4 → nullrun-0.16.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: nullrun
-Version: 0.16.4
+Version: 0.16.6
 Summary: NullRun Python SDK — runtime decision layer for tool-using AI agents.
 Project-URL: Homepage, https://nullrun.io
 Project-URL: Documentation, https://docs.nullrun.io

{nullrun-0.16.4 → nullrun-0.16.6}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "hatchling.build"
 name = "nullrun"
 # Full release history lives in CHANGELOG.md; only the current version
 # is pinned here.
-version = "0.16.4"
+version = "0.16.6"
 # Kept under the 200-char preview threshold so the full line is visible
 # without an "expand" click. The headline is the canonical §1 statement
 # from positioning.md — "runtime decision layer for tool-using AI agents"

{nullrun-0.16.4 → nullrun-0.16.6}/src/nullrun/__version__.py

@@ -5,5 +5,5 @@ this module is the single source of truth for the runtime version
 string and the SDK_MIN_VERSION constant.
 """
 
-__version__ = "0.16.4"
+__version__ = "0.16.6"
 __platform_version__ = "1.0.0"

{nullrun-0.16.4 → nullrun-0.16.6}/src/nullrun/_handle.py

@@ -18,10 +18,13 @@ message on failure" case, this module provides three one-liners:
 
 All three translate any:class:`nullrun.NullRunError` into a single
 ``print(format_user_message(exc), file=sys.stderr)`` followed by
-``sys.exit(1)``.:class:`nullrun.WorkflowKilledInterrupt` is a
-``BaseException`` subclass and therefore propagates through all three
-— the kill signal is never silently swallowed. Non-NullRun exceptions
-also propagate unchanged.
+``sys.exit(1)``.:class:`nullrun.WorkflowKilledInterrupt` now inherits
+from :class:`nullrun.NullRunError` (the 2026-09-08 migration; see the
+class docstring), so a bare ``except NullRunError`` would otherwise
+swallow the kill signal. ``handle``/``guarded`` explicitly re-raise it
+— the kill is a control-plane action, not an SDK failure, and must
+reach the top of the agent loop. Non-NullRun exceptions also propagate
+unchanged.
 
 ``init_or_die`` exists because:func:`nullrun.init` is typically
 called at module top-level — before any ``with handle: `` block or
@@ -56,7 +59,7 @@ from collections.abc import Callable
 from contextlib import contextmanager
 from typing import TypeVar
 
-from nullrun.breaker.exceptions import NullRunError
+from nullrun.breaker.exceptions import NullRunError, WorkflowKilledInterrupt
 from nullrun.messages import format_user_message
 
 T = TypeVar("T")
@@ -75,11 +78,16 @@ def handle(*, exit_code: int = 1):
 
     Exceptions that propagate unchanged:
 
-    *:class:`nullrun.WorkflowKilledInterrupt` (``BaseException``) — kill
-      signals must reach the top of the agent loop, not be swallowed
-      into a graceful exit.
+    *:class:`nullrun.WorkflowKilledInterrupt` — kill signals must reach
+      the top of the agent loop, not be swallowed into a graceful exit.
+      Re-raised explicitly inside the ``except NullRunError`` branch
+      because the 2026-09-08 migration moved ``WorkflowKilledInterrupt``
+      onto the ``NullRunError`` MRO (Sentry/OTel ``except Exception``
+      handlers should now record kill events; this ``handle`` /
+      ``guarded`` wrapper opts OUT of that recording on purpose).
     *:class:`KeyboardInterrupt` /:class:`SystemExit` (``BaseException``) —
-      same reason as the kill signal.
+      same reason as the kill signal — never reach the
+      ``except NullRunError`` branch anyway.
     * Any non-NullRun exception — the user's own bugs are not handled
       here; let them propagate for an honest traceback.
 
@@ -101,6 +109,15 @@ def handle(*, exit_code: int = 1):
     try:
         yield
     except NullRunError as exc:
+        # 2026-09-08 migration: WorkflowKilledInterrupt moved onto
+        # the NullRunError MRO so Sentry/OTel `except Exception`
+        # handlers record kill events. ``handle``/``guarded`` are the
+        # friendly-exit pattern, NOT the user-callback pattern — kill
+        # is a control-plane action and must propagate so the agent
+        # loop / dashboard resume path can see it. Re-raise explicitly
+        # before the catalog print + sys.exit.
+        if isinstance(exc, WorkflowKilledInterrupt):
+            raise
         print(format_user_message(exc), file=sys.stderr)
         sys.exit(exit_code)
 
@@ -111,7 +128,8 @@ def guarded(fn: Callable[..., T]) -> Callable[..., T]:
     Wrap a function so any:class:`nullrun.NullRunError` raised inside
     it is caught, rendered as a user-facing message, and the process
     exits with code ``1``. ``WorkflowKilledInterrupt`` and other
-    ``BaseException`` subclasses propagate.
+    ``BaseException`` subclasses propagate (``handle`` re-raises kill
+    explicitly, see the 2026-09-08 migration note).
 
     Pair with:func:`nullrun.protect` for the standard agent loop::
 

{nullrun-0.16.4 → nullrun-0.16.6}/src/nullrun/actions.py

@@ -22,6 +22,7 @@ except ImportError:
 
 from nullrun.breaker.exceptions import (
     NullRunBlockedException,
+    NullRunWorkflowKilledError,
     WorkflowKilledInterrupt,
     WorkflowPausedException,
 )
@@ -69,7 +70,7 @@ class ActionHandler:
     Handler for NullRun circuit breaker actions.
 
     This executes protective actions when triggered:
-    - KILL: Immediately stops the workflow (raises WorkflowKilledInterrupt)
+    - KILL: Immediately stops the workflow (raises NullRunWorkflowKilledError, NR-W002)
     - PAUSE: Temporarily halts the workflow (raises WorkflowPausedException)
     - ALERT: Sends notification (can be customized)
     - SNAPSHOT: Captures workflow state for debugging
@@ -179,7 +180,10 @@ class ActionHandler:
             **details: Additional details about the action
 
         Raises:
-            WorkflowKilledInterrupt: If action is "kill"
+            NullRunWorkflowKilledError: If action is "kill"
+                (2026-09-08 typed signal, NR-W002; subclass of
+                WorkflowKilledInterrupt which remains as the
+                back-compat name.)
             WorkflowPausedException: If action is "pause"
             NullRunBlockedException: If action is "block"
         """
@@ -230,12 +234,11 @@ class ActionHandler:
         except BaseException as e:
             # Don't let handler exceptions propagate. We catch
             # `BaseException` (not just `Exception`) because
-            # `WorkflowKilledInterrupt` is intentionally a
-            # `BaseException` subclass — it's a non-recoverable
-            # control signal, but inside the ActionHandler dispatch
-            # loop we want the kill to be recorded in history
-            # (already done above) and swallowed, NOT re-raised into
-            # the caller's frame.
+            # kill signals (NullRunWorkflowKilledError, the
+            # 2026-09-08-migrated Exception subclass) and any
+            # third-party kill-shaped signals must be recorded
+            # in history (already done above) and swallowed,
+            # NOT re-raised into the caller's frame.
             logger.error(f"Action handler error: {e}")
 
     def _default_kill(
@@ -244,9 +247,21 @@ class ActionHandler:
         reason: str,
         **details: Any,
     ) -> None:
-        """Default kill handler - raises WorkflowKilledInterrupt."""
+        """Default kill handler - raises NullRunWorkflowKilledError.
+
+        2026-09-08: typed kill signal (NR-W002). Cookbook code
+        can `except NullRunWorkflowKilledError` to react to
+        operator-initiated kills with structured error_code +
+        user_action. Legacy `except WorkflowKilledInterrupt`
+        still matches because NullRunWorkflowKilledError is a
+        subclass.
+        """
         logger.warning(f"KILL action for workflow {workflow_id}: {reason}")
-        raise WorkflowKilledInterrupt(workflow_id=workflow_id, reason=reason)
+        raise NullRunWorkflowKilledError(
+            workflow_id=workflow_id,
+            reason=reason,
+            kill_source="action_handler",
+        )
 
     def _default_pause(
         self,