langgraph-node-deadline 0.1.0__tar.gz

langgraph_node_deadline-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: python -m pip install --upgrade pip && pip install -e ".[dev]"
+      - name: Run tests
+        run: pytest -q
+      - name: Run the demo
+        run: python examples/salvage_demo.py

langgraph_node_deadline-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual envs
+.venv/
+venv/
+env/
+
+# Test / tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

langgraph_node_deadline-0.1.0/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/); this project uses
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — unreleased
+
+Initial release.
+
+### Added
+- `node_deadline_scope` / `node_deadline` — context manager binding a deadline
+  on a `time.monotonic()` basis.
+- `node_deadline_in(seconds)` — relative-budget convenience scope.
+- `clamp_to_node_deadline(budget_secs, *, reserve_secs=0.0)` — the core
+  primitive; clamps any proposed timeout to the binding deadline, fail-open.
+- `cooperative_wait_for(awaitable, budget_secs, *, reserve_secs=0.0)` — a
+  deadline-clamped `asyncio.wait_for`.
+- `get_node_deadline_remaining_secs()` and `node_deadline_exceeded()` readers.
+- Runnable, dependency-free `examples/salvage_demo.py`.
+- Full test suite covering fail-open semantics, the clamp monotonicity
+  invariant, nested-scope restoration, and async context propagation into and
+  out of child tasks.

langgraph_node_deadline-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fred Becker
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

langgraph_node_deadline-0.1.0/PKG-INFO

@@ -0,0 +1,150 @@
+Metadata-Version: 2.4
+Name: langgraph-node-deadline
+Version: 0.1.0
+Summary: One binding deadline for every inner timeout in a LangGraph node — clamp inner budgets to the cooperative deadline so work salvages instead of getting killed by the watchdog.
+Project-URL: Homepage, https://github.com/youknowfred/langgraph-node-deadline
+Project-URL: Issues, https://github.com/youknowfred/langgraph-node-deadline/issues
+Author: Fred Becker
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,asyncio,cancellation,deadline,langchain,langgraph,llm,reliability,timeout
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# langgraph-node-deadline
+
+**One binding deadline for every inner timeout in a LangGraph node.** Clamp inner
+budgets to the node's cooperative deadline so heavy work **salvages a partial
+result** instead of getting hard-killed by the watchdog and discarding everything.
+
+Zero runtime dependencies. ~120 lines. Python 3.9+.
+
+```bash
+pip install langgraph-node-deadline
+```
+
+---
+
+## The problem
+
+A LangGraph node that does real work has *several layers each re-deriving their
+own clock*: an outer `TimeoutPolicy` watchdog, an inner agent/tool budget, a
+retry loop, a sub-planner that "wants" 60 seconds. When those clocks disagree,
+the inner layers happily dispatch work the outer watchdog is **guaranteed to
+kill** — and the kill is uncooperative. It cancels the node and **throws away
+everything**, including the partial answer you could have returned.
+
+You've seen the symptom: a long run times out into *nothing* after burning
+minutes of paid LLM calls, and the user just sees "it failed." The upstream
+issue is real and open: [langchain-ai/langgraph#5672 — *Run Cancellation Causes
+Loss of Streamed State Not Yet Persisted*](https://github.com/langchain-ai/langgraph/issues/5672).
+
+The trap, distilled: if your cooperative cancel and the watchdog are pinned to
+the **same** number, the watchdog clock starts at *node entry — before your code
+runs* — so your cancel loses the race deterministically. Equal timeouts lose.
+
+## The fix
+
+Set **one** deadline at node entry. Make every inner timeout *clamp to it*
+instead of re-deriving its own. Now inner calls yield at the node boundary, with
+a little grace, **before** the watchdog fires — so your `try/except` actually
+runs and you return a complete-but-shorter answer.
+
+```python
+import asyncio
+from langgraph_node_deadline import node_deadline_in, cooperative_wait_for
+
+async def my_node(state):
+    # this node gets ~1.8s of cooperative runtime (a hair under its watchdog)
+    with node_deadline_in(1.8):
+        try:
+            # the planner asks for 5s, but gets clamped to what's actually left
+            result = await cooperative_wait_for(plan_and_write(state), budget_secs=5.0)
+            return {"draft": result}
+        except asyncio.TimeoutError:
+            # runs BEFORE the watchdog can kill us — keep the partial work
+            return {"draft": salvage_partial(state)}
+```
+
+## See it lose vs. salvage (30 seconds, no LangGraph needed)
+
+```bash
+python examples/salvage_demo.py
+```
+
+```
+Outer watchdog (LangGraph TimeoutPolicy): 2.0s  |  inner planner wants ~5s
+
+  NAIVE   (inner ignores the node deadline)
+    -> LOST in 2.00s — outer watchdog cancelled the node, salvage code never ran, ALL work discarded
+
+  CLAMPED (inner clamps to the node deadline)
+    -> SALVAGED in 1.80s — kept 3 steps: ['step 1', 'step 2', 'step 3']
+```
+
+Same work, same watchdog. One import decides whether you keep anything.
+
+## Wiring it into a real LangGraph node
+
+Set the scope to a hair under whatever cap the executor enforces, then clamp
+every inner timed call through it:
+
+```python
+from langgraph_node_deadline import node_deadline_in, clamp_to_node_deadline, cooperative_wait_for
+
+NODE_CAP_SECS = 30.0   # match this to your TimeoutPolicy, minus a small grace
+
+async def research_node(state):
+    with node_deadline_in(NODE_CAP_SECS - 1.0):   # leave 1s of grace under the watchdog
+        # an inner retry loop, sub-agent, or tool call — all clamp to the same deadline
+        per_call = clamp_to_node_deadline(15.0, reserve_secs=2.0)  # reserve finalize headroom
+        chunks = await cooperative_wait_for(retrieve(state), budget_secs=per_call)
+        return {"chunks": chunks}
+```
+
+Because the deadline lives in a `contextvars.ContextVar`, and `asyncio` copies
+the ambient context when it creates a task, the scope you open before you
+`await` is visible to the agent task **and every subagent task it spawns** — no
+threading the deadline through call signatures.
+
+## API
+
+| Symbol | What it does |
+| --- | --- |
+| `node_deadline_in(seconds)` | Context manager. Set the binding deadline to `now + seconds`. Use at node entry. |
+| `node_deadline_scope(deadline_monotonic)` | Context manager. Set the deadline to an absolute `time.monotonic()` timestamp (or `None` to clear). `node_deadline` is an alias. |
+| `clamp_to_node_deadline(budget_secs, *, reserve_secs=0.0)` | **The core primitive.** Returns `min(budget_secs, remaining - reserve_secs)`, floored at 0. Returns `budget_secs` unchanged when no scope is active. |
+| `cooperative_wait_for(awaitable, budget_secs, *, reserve_secs=0.0)` | `asyncio.wait_for` that never outlasts the node deadline. Raises `asyncio.TimeoutError` on the clamped budget. |
+| `get_node_deadline_remaining_secs()` | Seconds left, or `None` if no scope. Never negative. |
+| `node_deadline_exceeded()` | `True` only when a scope is active *and* its deadline has passed. Safe loop guard. |
+
+**Fail-open by design.** With no active scope, every function behaves as if it
+weren't there — so adding it to one node never changes the behavior of the rest
+of your graph, your tests, or direct invocations.
+
+## Why a whole package for ~120 lines
+
+Because the *lesson* is the hard part, not the code. This is the
+[`derive-don't-pin`](https://github.com/langchain-ai/langgraph/issues/5672)
+discipline extracted from a production agent that paid for it: a synthesis pool
+that believed it had 43.5 seconds left *nine seconds before* the watchdog killed
+the node — because four inner layers each trusted their own clock and none knew
+the one the executor was actually enforcing. One binding deadline fixes the
+entire class of bug.
+
+## License
+
+MIT © 2026 Fred Becker. See [LICENSE](LICENSE).

langgraph_node_deadline-0.1.0/README.md

@@ -0,0 +1,124 @@
+# langgraph-node-deadline
+
+**One binding deadline for every inner timeout in a LangGraph node.** Clamp inner
+budgets to the node's cooperative deadline so heavy work **salvages a partial
+result** instead of getting hard-killed by the watchdog and discarding everything.
+
+Zero runtime dependencies. ~120 lines. Python 3.9+.
+
+```bash
+pip install langgraph-node-deadline
+```
+
+---
+
+## The problem
+
+A LangGraph node that does real work has *several layers each re-deriving their
+own clock*: an outer `TimeoutPolicy` watchdog, an inner agent/tool budget, a
+retry loop, a sub-planner that "wants" 60 seconds. When those clocks disagree,
+the inner layers happily dispatch work the outer watchdog is **guaranteed to
+kill** — and the kill is uncooperative. It cancels the node and **throws away
+everything**, including the partial answer you could have returned.
+
+You've seen the symptom: a long run times out into *nothing* after burning
+minutes of paid LLM calls, and the user just sees "it failed." The upstream
+issue is real and open: [langchain-ai/langgraph#5672 — *Run Cancellation Causes
+Loss of Streamed State Not Yet Persisted*](https://github.com/langchain-ai/langgraph/issues/5672).
+
+The trap, distilled: if your cooperative cancel and the watchdog are pinned to
+the **same** number, the watchdog clock starts at *node entry — before your code
+runs* — so your cancel loses the race deterministically. Equal timeouts lose.
+
+## The fix
+
+Set **one** deadline at node entry. Make every inner timeout *clamp to it*
+instead of re-deriving its own. Now inner calls yield at the node boundary, with
+a little grace, **before** the watchdog fires — so your `try/except` actually
+runs and you return a complete-but-shorter answer.
+
+```python
+import asyncio
+from langgraph_node_deadline import node_deadline_in, cooperative_wait_for
+
+async def my_node(state):
+    # this node gets ~1.8s of cooperative runtime (a hair under its watchdog)
+    with node_deadline_in(1.8):
+        try:
+            # the planner asks for 5s, but gets clamped to what's actually left
+            result = await cooperative_wait_for(plan_and_write(state), budget_secs=5.0)
+            return {"draft": result}
+        except asyncio.TimeoutError:
+            # runs BEFORE the watchdog can kill us — keep the partial work
+            return {"draft": salvage_partial(state)}
+```
+
+## See it lose vs. salvage (30 seconds, no LangGraph needed)
+
+```bash
+python examples/salvage_demo.py
+```
+
+```
+Outer watchdog (LangGraph TimeoutPolicy): 2.0s  |  inner planner wants ~5s
+
+  NAIVE   (inner ignores the node deadline)
+    -> LOST in 2.00s — outer watchdog cancelled the node, salvage code never ran, ALL work discarded
+
+  CLAMPED (inner clamps to the node deadline)
+    -> SALVAGED in 1.80s — kept 3 steps: ['step 1', 'step 2', 'step 3']
+```
+
+Same work, same watchdog. One import decides whether you keep anything.
+
+## Wiring it into a real LangGraph node
+
+Set the scope to a hair under whatever cap the executor enforces, then clamp
+every inner timed call through it:
+
+```python
+from langgraph_node_deadline import node_deadline_in, clamp_to_node_deadline, cooperative_wait_for
+
+NODE_CAP_SECS = 30.0   # match this to your TimeoutPolicy, minus a small grace
+
+async def research_node(state):
+    with node_deadline_in(NODE_CAP_SECS - 1.0):   # leave 1s of grace under the watchdog
+        # an inner retry loop, sub-agent, or tool call — all clamp to the same deadline
+        per_call = clamp_to_node_deadline(15.0, reserve_secs=2.0)  # reserve finalize headroom
+        chunks = await cooperative_wait_for(retrieve(state), budget_secs=per_call)
+        return {"chunks": chunks}
+```
+
+Because the deadline lives in a `contextvars.ContextVar`, and `asyncio` copies
+the ambient context when it creates a task, the scope you open before you
+`await` is visible to the agent task **and every subagent task it spawns** — no
+threading the deadline through call signatures.
+
+## API
+
+| Symbol | What it does |
+| --- | --- |
+| `node_deadline_in(seconds)` | Context manager. Set the binding deadline to `now + seconds`. Use at node entry. |
+| `node_deadline_scope(deadline_monotonic)` | Context manager. Set the deadline to an absolute `time.monotonic()` timestamp (or `None` to clear). `node_deadline` is an alias. |
+| `clamp_to_node_deadline(budget_secs, *, reserve_secs=0.0)` | **The core primitive.** Returns `min(budget_secs, remaining - reserve_secs)`, floored at 0. Returns `budget_secs` unchanged when no scope is active. |
+| `cooperative_wait_for(awaitable, budget_secs, *, reserve_secs=0.0)` | `asyncio.wait_for` that never outlasts the node deadline. Raises `asyncio.TimeoutError` on the clamped budget. |
+| `get_node_deadline_remaining_secs()` | Seconds left, or `None` if no scope. Never negative. |
+| `node_deadline_exceeded()` | `True` only when a scope is active *and* its deadline has passed. Safe loop guard. |
+
+**Fail-open by design.** With no active scope, every function behaves as if it
+weren't there — so adding it to one node never changes the behavior of the rest
+of your graph, your tests, or direct invocations.
+
+## Why a whole package for ~120 lines
+
+Because the *lesson* is the hard part, not the code. This is the
+[`derive-don't-pin`](https://github.com/langchain-ai/langgraph/issues/5672)
+discipline extracted from a production agent that paid for it: a synthesis pool
+that believed it had 43.5 seconds left *nine seconds before* the watchdog killed
+the node — because four inner layers each trusted their own clock and none knew
+the one the executor was actually enforcing. One binding deadline fixes the
+entire class of bug.
+
+## License
+
+MIT © 2026 Fred Becker. See [LICENSE](LICENSE).

langgraph_node_deadline-0.1.0/examples/salvage_demo.py

@@ -0,0 +1,82 @@
+"""The README hero, runnable with zero dependencies.
+
+Run it:
+
+    python examples/salvage_demo.py
+
+Two nodes do the SAME work and live under the SAME outer watchdog. The only
+difference is whether the inner planner clamps its budget to the binding node
+deadline. One loses everything; one salvages a partial result.
+
+This simulates a LangGraph node wrapped in a ``TimeoutPolicy`` watchdog. No
+LangGraph install is needed — ``asyncio.wait_for`` plays the role of the
+watchdog so you can see the mechanics directly.
+"""
+
+import asyncio
+import time
+
+from langgraph_node_deadline import node_deadline_in, cooperative_wait_for
+
+OUTER_WATCHDOG = 2.0  # simulates LangGraph TimeoutPolicy on the node (kills uncooperatively)
+NODE_CAP = 1.8        # the cooperative deadline we enforce INSIDE the node (fires first)
+
+
+async def long_planner(progress):
+    """An inner agent/LLM loop that 'wants' ~5s and accretes partial work."""
+    for i in range(10):
+        await asyncio.sleep(0.5)
+        progress.append(f"step {i + 1}")
+
+
+# --- Naive node: the inner call re-derives its OWN 5s budget, blind to the watchdog.
+async def naive_node():
+    progress = []
+    try:
+        await asyncio.wait_for(long_planner(progress), timeout=5.0)
+    except asyncio.TimeoutError:
+        return "salvaged", progress  # never reached — the watchdog kills us first
+    return "complete", progress
+
+
+# --- Clamped node: the inner call clamps to the binding node deadline.
+async def clamped_node():
+    progress = []
+    with node_deadline_in(NODE_CAP):
+        try:
+            await cooperative_wait_for(long_planner(progress), budget_secs=5.0)
+        except asyncio.TimeoutError:
+            return "salvaged", progress  # fires at ~1.8s, BEFORE the 2.0s watchdog
+    return "complete", progress
+
+
+async def run(label, node):
+    start = time.monotonic()
+    try:
+        outcome, progress = await asyncio.wait_for(node(), timeout=OUTER_WATCHDOG)
+        elapsed = time.monotonic() - start
+        print(
+            f"  {label}\n"
+            f"    -> {outcome.upper()} in {elapsed:.2f}s — kept {len(progress)} steps: {progress}\n"
+        )
+    except asyncio.TimeoutError:
+        elapsed = time.monotonic() - start
+        print(
+            f"  {label}\n"
+            f"    -> LOST in {elapsed:.2f}s — outer watchdog cancelled the node, "
+            f"salvage code never ran, ALL work discarded\n"
+        )
+
+
+async def main():
+    print(
+        f"\nOuter watchdog (LangGraph TimeoutPolicy): {OUTER_WATCHDOG}s"
+        f"  |  inner planner wants ~5s\n"
+    )
+    await run("NAIVE   (inner ignores the node deadline)", naive_node)
+    await run("CLAMPED (inner clamps to the node deadline)", clamped_node)
+    print("Same work, same watchdog. One import decides whether you keep anything.\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

langgraph_node_deadline-0.1.0/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "langgraph-node-deadline"
+version = "0.1.0"
+description = "One binding deadline for every inner timeout in a LangGraph node — clamp inner budgets to the cooperative deadline so work salvages instead of getting killed by the watchdog."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Fred Becker" }]
+keywords = [
+    "langgraph",
+    "langchain",
+    "asyncio",
+    "timeout",
+    "deadline",
+    "cancellation",
+    "agents",
+    "llm",
+    "reliability",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+dev = ["pytest>=7", "pytest-asyncio>=0.23"]
+
+[project.urls]
+Homepage = "https://github.com/youknowfred/langgraph-node-deadline"
+Issues = "https://github.com/youknowfred/langgraph-node-deadline/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langgraph_node_deadline"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]

langgraph_node_deadline-0.1.0/src/langgraph_node_deadline/__init__.py

@@ -0,0 +1,176 @@
+"""langgraph-node-deadline — one binding deadline for every inner timeout.
+
+The problem this solves
+-----------------------
+A LangGraph node that does real work usually has *several* layers each
+re-deriving their own clock: an outer ``TimeoutPolicy`` watchdog, an inner
+agent/tool budget, a retry loop, a sub-planner that "wants" 60 seconds. When
+those clocks disagree, the inner layers dispatch work the outer watchdog is
+guaranteed to kill — and the kill is uncooperative: it cancels the node and
+**discards everything**, including any partial result you could have salvaged.
+(See the long-standing upstream report: langchain-ai/langgraph#5672, "Run
+Cancellation Causes Loss of Streamed State Not Yet Persisted as a Checkpoint".)
+
+The fix
+-------
+Establish **one** binding deadline at node entry and make every inner timeout
+*clamp to it* instead of re-deriving its own. Then your inner calls always
+yield at the node boundary — with a few hundred ms of grace — *before* the
+watchdog fires, so a ``try/except`` around the inner call actually runs and you
+return a complete-but-shorter answer instead of nothing.
+
+How it threads through async code
+---------------------------------
+The deadline lives in a :class:`contextvars.ContextVar`. ``asyncio`` tasks copy
+the ambient context at creation, so a scope opened before you ``await`` is
+visible to the agent task *and every subagent task it spawns*. The default is
+``None`` (no scope) and every consumer **fails open** — code that runs outside a
+scope (unit tests, direct invocations) keeps its existing arithmetic unchanged.
+
+Quick start
+-----------
+>>> import asyncio
+>>> from langgraph_node_deadline import node_deadline_in, cooperative_wait_for
+>>> async def node():
+...     # this node is allowed ~1.8s of cooperative runtime
+...     with node_deadline_in(1.8):
+...         try:
+...             # the planner "wants" 5s but will be clamped to what's left
+...             return await cooperative_wait_for(planner(), budget_secs=5.0)
+...         except asyncio.TimeoutError:
+...             return salvage_partial()   # runs BEFORE the outer watchdog kills us
+
+See ``examples/salvage_demo.py`` for a runnable, dependency-free contrast
+between the naive path (work discarded) and the clamped path (work salvaged).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from contextlib import contextmanager
+from contextvars import ContextVar
+from typing import Awaitable, Iterator, Optional, TypeVar
+
+__all__ = [
+    "node_deadline",
+    "node_deadline_scope",
+    "node_deadline_in",
+    "get_node_deadline_remaining_secs",
+    "node_deadline_exceeded",
+    "clamp_to_node_deadline",
+    "cooperative_wait_for",
+]
+
+__version__ = "0.1.0"
+
+_T = TypeVar("_T")
+
+_node_deadline_monotonic: ContextVar[Optional[float]] = ContextVar(
+    "node_deadline_monotonic", default=None
+)
+
+
+@contextmanager
+def node_deadline_scope(deadline_monotonic: Optional[float]) -> Iterator[None]:
+    """Scope the binding cooperative deadline, on a ``time.monotonic()`` basis.
+
+    Args:
+        deadline_monotonic: An absolute ``time.monotonic()`` timestamp by which
+            inner work should have yielded. Pass ``None`` to explicitly clear
+            the scope (fail-open) — used when the outer layer has no hard cap.
+
+    The scope is restored on exit, so nesting is safe: an inner, tighter
+    deadline reverts to the outer one when its ``with`` block ends.
+    """
+    token = _node_deadline_monotonic.set(deadline_monotonic)
+    try:
+        yield
+    finally:
+        _node_deadline_monotonic.reset(token)
+
+
+# Primary public alias — reads naturally at call sites that already hold an
+# absolute monotonic deadline: ``with node_deadline(executor_deadline): ...``
+node_deadline = node_deadline_scope
+
+
+@contextmanager
+def node_deadline_in(seconds: float) -> Iterator[None]:
+    """Convenience scope expressed as a *relative* budget from now.
+
+    ``with node_deadline_in(30): ...`` is exactly
+    ``with node_deadline_scope(time.monotonic() + 30): ...`` — use it at node
+    entry when you think in "this node gets N seconds" rather than in absolute
+    monotonic timestamps.
+    """
+    with node_deadline_scope(time.monotonic() + seconds):
+        yield
+
+
+def get_node_deadline_remaining_secs() -> Optional[float]:
+    """Seconds until the binding deadline, or ``None`` when no scope is active.
+
+    Never negative — a passed deadline reports ``0.0``.
+    """
+    deadline = _node_deadline_monotonic.get()
+    if deadline is None:
+        return None
+    return max(0.0, deadline - time.monotonic())
+
+
+def node_deadline_exceeded() -> bool:
+    """``True`` only when a scope is active *and* its deadline has passed.
+
+    Returns ``False`` when no scope is active (fail-open), so it is safe to use
+    as a cooperative loop guard: ``while not node_deadline_exceeded(): ...``.
+    """
+    remaining = get_node_deadline_remaining_secs()
+    return remaining is not None and remaining <= 0.0
+
+
+def clamp_to_node_deadline(budget_secs: float, *, reserve_secs: float = 0.0) -> float:
+    """Clamp a proposed budget/timeout to the real deadline remaining.
+
+    This is the core primitive: every inner layer that is about to start a
+    timed operation passes its desired budget through here, so it can never
+    exceed the binding node deadline.
+
+    Args:
+        budget_secs: The timeout the inner layer *wants*.
+        reserve_secs: Headroom to carve below the deadline (e.g. a phase
+            transition / finalize buffer) so the clamped work still has time to
+            wrap up before the cooperative cancel.
+
+    Returns:
+        ``budget_secs`` unchanged when no deadline scope is active (fail-open);
+        otherwise ``min(budget_secs, remaining - reserve_secs)``, floored at
+        ``0.0`` so it is always a valid ``asyncio.wait_for`` timeout.
+    """
+    remaining = get_node_deadline_remaining_secs()
+    if remaining is None:
+        return budget_secs
+    return max(0.0, min(budget_secs, remaining - reserve_secs))
+
+
+async def cooperative_wait_for(
+    awaitable: Awaitable[_T],
+    budget_secs: float,
+    *,
+    reserve_secs: float = 0.0,
+) -> _T:
+    """``asyncio.wait_for`` that never outlasts the binding node deadline.
+
+    Equivalent to ``asyncio.wait_for(awaitable, clamp_to_node_deadline(...))``.
+    Because the clamped timeout fires *inside* the node, an
+    ``asyncio.TimeoutError`` you catch here runs your salvage path **before**
+    an outer watchdog can cancel the node and discard the work.
+
+    With no active deadline scope this is a plain ``wait_for(awaitable,
+    budget_secs)`` — fail-open, no behavior change.
+
+    Raises:
+        asyncio.TimeoutError: if the clamped budget elapses first.
+    """
+    timeout = clamp_to_node_deadline(budget_secs, reserve_secs=reserve_secs)
+    return await asyncio.wait_for(awaitable, timeout)

langgraph_node_deadline-0.1.0/tests/test_node_deadline.py

@@ -0,0 +1,153 @@
+"""Behavioral + invariant tests for langgraph-node-deadline.
+
+asyncio_mode = "auto" (set in pyproject) runs ``async def`` tests directly.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+
+import pytest
+
+from langgraph_node_deadline import (
+    clamp_to_node_deadline,
+    cooperative_wait_for,
+    get_node_deadline_remaining_secs,
+    node_deadline_exceeded,
+    node_deadline_in,
+    node_deadline_scope,
+)
+
+
+# --------------------------------------------------------------------------- #
+# Fail-open: no scope active                                                   #
+# --------------------------------------------------------------------------- #
+
+def test_no_scope_is_fail_open():
+    assert get_node_deadline_remaining_secs() is None
+    assert node_deadline_exceeded() is False
+    # clamp returns the requested budget unchanged
+    assert clamp_to_node_deadline(60.0) == 60.0
+    assert clamp_to_node_deadline(60.0, reserve_secs=5.0) == 60.0
+
+
+# --------------------------------------------------------------------------- #
+# Core clamp behavior under an active scope                                    #
+# --------------------------------------------------------------------------- #
+
+def test_clamp_under_scope_caps_to_remaining():
+    with node_deadline_in(10.0):
+        clamped = clamp_to_node_deadline(60.0)
+        # never more than what's left, never more than the request
+        assert 9.0 < clamped <= 10.0
+
+
+def test_clamp_passes_through_when_budget_is_smaller():
+    with node_deadline_in(10.0):
+        # a 2s request well under the 10s deadline is unchanged
+        assert clamp_to_node_deadline(2.0) == pytest.approx(2.0, abs=0.05)
+
+
+def test_reserve_carves_headroom():
+    with node_deadline_in(10.0):
+        clamped = clamp_to_node_deadline(60.0, reserve_secs=2.0)
+        assert 7.0 < clamped <= 8.0
+
+
+def test_remaining_never_negative_and_exceeded_flips():
+    # a deadline one second in the past
+    with node_deadline_scope(time.monotonic() - 1.0):
+        assert get_node_deadline_remaining_secs() == 0.0
+        assert node_deadline_exceeded() is True
+        assert clamp_to_node_deadline(5.0) == 0.0
+
+
+# --------------------------------------------------------------------------- #
+# Nesting: an inner tighter deadline reverts to the outer one                  #
+# --------------------------------------------------------------------------- #
+
+def test_nested_scope_restores_outer():
+    with node_deadline_in(10.0):
+        assert 9.0 < get_node_deadline_remaining_secs() <= 10.0
+        with node_deadline_in(1.0):
+            assert get_node_deadline_remaining_secs() <= 1.0
+        # back to the outer scope
+        assert 8.5 < get_node_deadline_remaining_secs() <= 10.0
+    # back to fail-open
+    assert get_node_deadline_remaining_secs() is None
+
+
+# --------------------------------------------------------------------------- #
+# The invariant the package exists to guarantee                               #
+# --------------------------------------------------------------------------- #
+
+def test_clamp_monotonicity_invariant():
+    """clamp(b) is always <= b AND <= remaining, for every budget."""
+    with node_deadline_in(5.0):
+        remaining = get_node_deadline_remaining_secs()
+        assert remaining is not None
+        for budget in (0.0, 0.5, 1.0, 4.9, 5.0, 50.0, 5000.0):
+            clamped = clamp_to_node_deadline(budget)
+            assert clamped <= budget + 1e-9
+            assert clamped <= remaining + 1e-9
+            assert clamped >= 0.0
+
+
+# --------------------------------------------------------------------------- #
+# Context propagation into child tasks (the whole reason it's a contextvar)    #
+# --------------------------------------------------------------------------- #
+
+async def test_scope_propagates_to_child_task():
+    async def child_reads_deadline():
+        return get_node_deadline_remaining_secs()
+
+    with node_deadline_in(5.0):
+        # a task created inside the scope inherits the deadline
+        remaining = await asyncio.create_task(child_reads_deadline())
+    assert remaining is not None
+    assert 4.0 < remaining <= 5.0
+
+
+async def test_scope_not_visible_to_task_created_outside():
+    async def child_reads_deadline():
+        # yield once so the parent's scope would be active if it leaked
+        await asyncio.sleep(0)
+        return get_node_deadline_remaining_secs()
+
+    # task created BEFORE entering the scope must not see it
+    task = asyncio.create_task(child_reads_deadline())
+    with node_deadline_in(5.0):
+        result = await task
+    assert result is None
+
+
+# --------------------------------------------------------------------------- #
+# cooperative_wait_for                                                         #
+# --------------------------------------------------------------------------- #
+
+async def test_cooperative_wait_for_clamps_to_deadline():
+    start = time.monotonic()
+    with node_deadline_in(0.2):
+        with pytest.raises(asyncio.TimeoutError):
+            # asks for 5s but the node only has ~0.2s left
+            await cooperative_wait_for(asyncio.sleep(5.0), budget_secs=5.0)
+    elapsed = time.monotonic() - start
+    assert elapsed < 1.0  # fired at the node deadline, not the 5s request
+
+
+async def test_cooperative_wait_for_returns_when_work_fits():
+    with node_deadline_in(5.0):
+        result = await cooperative_wait_for(_quick(), budget_secs=5.0)
+    assert result == "done"
+
+
+async def test_cooperative_wait_for_fail_open_without_scope():
+    # no scope: behaves like a plain wait_for(awaitable, budget_secs)
+    result = await cooperative_wait_for(_quick(), budget_secs=5.0)
+    assert result == "done"
+
+
+async def _quick():
+    await asyncio.sleep(0.01)
+    return "done"