langgraph-wait 0.2.0__tar.gz

langgraph_wait-0.2.0/.gitignore

@@ -0,0 +1,19 @@
+*.egg-info/
+*.pyc
+.coverage
+.env
+.pytest_cache/
+.ruff_cache/
+.scratch/
+.venv/
+__pycache__/
+build/
+cdk.out/
+reports/*.log
+
+# generated by the docs workflow from README.md / CHANGELOG.md
+docs/index.md
+docs/changelog.md
+# build output
+dist/
+site/

langgraph_wait-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kamaljeet Singh
+
+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_wait-0.2.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.5
+Name: langgraph-wait
+Version: 0.2.0
+Summary: The LangGraph side of agent-wait: ask() to declare a question at the interrupt site, an adapter that reads what a thread is parked on, and helpers for the host's start/resume routing.
+Project-URL: Homepage, https://skamalj.github.io/agent-wait/
+Project-URL: Documentation, https://skamalj.github.io/agent-wait/
+Project-URL: Source, https://github.com/skamalj/agent-wait
+Project-URL: Issues, https://github.com/skamalj/agent-wait/issues
+Author-email: Kamaljeet Singh <skamalj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,approval,human-in-the-loop,interrupt,langgraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: agent-wait<0.3,>=0.2
+Requires-Dist: langgraph<2,>=1.2
+Description-Content-Type: text/markdown
+
+# langgraph-wait
+
+The LangGraph side of [agent-wait](https://pypi.org/project/agent-wait/) — publish a
+LangGraph agent's interrupts so a human can answer them from anywhere.
+
+```bash
+pip install langgraph-wait          # pulls in agent-wait
+```
+
+```python
+from langgraph_wait import ask, LangGraphAdapter, is_answer, resume_command
+```
+
+* **`ask(question, policy)`** — a thin wrapper over `interrupt()`. The node pauses exactly
+  as LangGraph pauses; the policy rides along inside the interrupt value and comes back
+  out in the published envelope. A plain `interrupt(value)` also works, with the default
+  policy.
+* **`LangGraphAdapter(graph)`** — three methods. `pending()` reads what a thread is parked
+  on and filters LangGraph's `tasks[*].interrupts` over-report on `task.result`.
+* **`is_answer(message)`** / **`resume_command(message)`** — pure functions for the host's
+  router. `interrupt_id` present means resume; the `Command` is keyed by interrupt id so
+  parallel interrupts resume independently.
+
+Requires `langgraph >= 1.2`. One `interrupt()` per node — two interrupting tools in one
+`ToolNode` share an id on 1.2.x (langgraph #6626), and this package documents rather
+than hides that.
+
+Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

langgraph_wait-0.2.0/README.md

@@ -0,0 +1,28 @@
+# langgraph-wait
+
+The LangGraph side of [agent-wait](https://pypi.org/project/agent-wait/) — publish a
+LangGraph agent's interrupts so a human can answer them from anywhere.
+
+```bash
+pip install langgraph-wait          # pulls in agent-wait
+```
+
+```python
+from langgraph_wait import ask, LangGraphAdapter, is_answer, resume_command
+```
+
+* **`ask(question, policy)`** — a thin wrapper over `interrupt()`. The node pauses exactly
+  as LangGraph pauses; the policy rides along inside the interrupt value and comes back
+  out in the published envelope. A plain `interrupt(value)` also works, with the default
+  policy.
+* **`LangGraphAdapter(graph)`** — three methods. `pending()` reads what a thread is parked
+  on and filters LangGraph's `tasks[*].interrupts` over-report on `task.result`.
+* **`is_answer(message)`** / **`resume_command(message)`** — pure functions for the host's
+  router. `interrupt_id` present means resume; the `Command` is keyed by interrupt id so
+  parallel interrupts resume independently.
+
+Requires `langgraph >= 1.2`. One `interrupt()` per node — two interrupting tools in one
+`ToolNode` share an id on 1.2.x (langgraph #6626), and this package documents rather
+than hides that.
+
+Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

langgraph_wait-0.2.0/pyproject.toml

@@ -0,0 +1,40 @@
+[project]
+name = "langgraph-wait"
+version = "0.2.0"
+description = "The LangGraph side of agent-wait: ask() to declare a question at the interrupt site, an adapter that reads what a thread is parked on, and helpers for the host's start/resume routing."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kamaljeet Singh", email = "skamalj@gmail.com" }]
+keywords = ["agents", "langgraph", "human-in-the-loop", "interrupt", "approval"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = ["agent-wait>=0.2,<0.3", "langgraph>=1.2,<2"]
+
+[project.urls]
+Homepage = "https://skamalj.github.io/agent-wait/"
+Documentation = "https://skamalj.github.io/agent-wait/"
+Source = "https://github.com/skamalj/agent-wait"
+Issues = "https://github.com/skamalj/agent-wait/issues"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/langgraph_wait"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/langgraph_wait", "README.md", "LICENSE"]
+
+[tool.uv.sources]
+agent-wait = { workspace = true }

langgraph_wait-0.2.0/src/langgraph_wait/__init__.py

@@ -0,0 +1,14 @@
+"""langgraph-wait: the LangGraph side of agent-wait."""
+
+from .adapter import LangGraphAdapter
+from .ask import WAIT_KEY, ask, unwrap
+from .resume import is_answer, resume_command
+
+__all__ = [
+    "WAIT_KEY",
+    "LangGraphAdapter",
+    "ask",
+    "is_answer",
+    "resume_command",
+    "unwrap",
+]

langgraph_wait-0.2.0/src/langgraph_wait/adapter.py

@@ -0,0 +1,87 @@
+"""`LangGraphAdapter` -- three methods, and the one LangGraph bug that matters.
+
+The core never imports LangGraph. Everything framework-specific lives here, which is also
+where the framework's rough edges get handled.
+
+## `get_state().tasks[*].interrupts` over-reports
+
+This is the finding the whole adapter is shaped around (langgraph #4796 / #6792,
+reproduced against 1.2.11 in `tests/test_spike_langgraph.py`). With two parallel
+interrupts, resume one, and the *finished* task still lists its interrupt id. Anyone
+building "what is this thread waiting on?" from `tasks[*].interrupts` alone gets an
+interrupt the graph has already moved past -- and the failure mode is republishing an
+approval button for a node that already ran, or resuming it a second time.
+
+The discriminator is `task.result`: it holds the finished task's return value and is
+`None` while the task is genuinely parked. `pending()` filters on it, and the spike test
+pins the behaviour so a future LangGraph fix shows up as a failing test rather than as
+silence.
+
+## What else was verified empirically, against langgraph 1.2.11
+
+* **`Interrupt.id` is stable** across `invoke(None, config)` re-entry and across
+  resume-from-checkpoint. This is what makes `dedupe_key` work: a republished envelope
+  carries the same id, so consumers can discard it.
+* **Interrupts raised inside a subgraph** surface on the parent's state against the
+  subgraph node's task, with a stable id. `subgraphs=True` was not needed, and resuming
+  by id works through the parent.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from agent_wait import PendingInterrupt
+
+from .ask import unwrap
+
+
+class LangGraphAdapter:
+    """Wraps a compiled graph. Requires langgraph >= 1.2."""
+
+    name = "langgraph"
+
+    def __init__(self, graph: Any) -> None:
+        self.graph = graph
+
+    def config_for(self, thread_id: str) -> dict[str, Any]:
+        return {"configurable": {"thread_id": thread_id}}
+
+    def invoke(self, value: Any, config: Any) -> Any:
+        """Run the graph. `value` is the caller's -- fresh input, or a `Command`."""
+        return self.graph.invoke(value, config)
+
+    def pending(self, thread_id: str) -> list[PendingInterrupt]:
+        """What this thread is parked on right now. `[]` if it has never run."""
+        state = self.graph.get_state(self.config_for(thread_id))
+        asked_at = _epoch(getattr(state, "created_at", None))
+
+        out: list[PendingInterrupt] = []
+        for task in getattr(state, "tasks", ()) or ():
+            # See the module docstring. A task that has produced a result is finished,
+            # whatever its `interrupts` list still claims.
+            if getattr(task, "result", None) is not None:
+                continue
+            for raw in getattr(task, "interrupts", ()) or ():
+                question, policy = unwrap(getattr(raw, "value", None))
+                out.append(
+                    PendingInterrupt(
+                        interrupt_id=str(raw.id),
+                        question=question,
+                        policy=policy,
+                        asked_at=asked_at,
+                    )
+                )
+        return out
+
+
+def _epoch(created_at: Any) -> float | None:
+    """LangGraph stamps checkpoints with an ISO-8601 string. Anchor `expires_at` to it
+    so a republished question keeps its original deadline."""
+    if not isinstance(created_at, str):
+        return None
+    try:
+        return datetime.fromisoformat(created_at).timestamp()
+    except ValueError:
+        return None

langgraph_wait-0.2.0/src/langgraph_wait/ask.py

@@ -0,0 +1,52 @@
+"""`ask()` -- the one line a graph author writes.
+
+    decision = ask({"kind": "refund_approval", "amount": amount},
+                   policy=WaitPolicy(timeout="P3D", allowed_actions=("approve", "reject")))
+
+It is a thin wrapper over `langgraph.types.interrupt()`, and thin is the point: the node
+still pauses exactly the way LangGraph pauses, the checkpointer still does its job, and
+nothing about the graph changes. What `ask()` adds is the *policy* -- how long this
+question should stand, what to assume if nobody answers, which answers are meaningful --
+carried inside the interrupt value under `__wait__`.
+
+That key is the only channel available. An interrupt has one payload and LangGraph does
+not offer a side channel for metadata, so the policy rides with the question and
+`unwrap()` peels it back off.
+
+A plain `interrupt(value)` with no `ask()` still works. It is read as a question with the
+default policy, so a graph that already interrupts gets published without any edit at all.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from agent_wait import WaitPolicy, check_question_size
+from langgraph.types import interrupt
+
+WAIT_KEY = "__wait__"
+QUESTION_KEY = "question"
+
+
+def ask(question: Any, policy: WaitPolicy | None = None) -> Any:
+    """Park the graph on `question` and return the answer when it arrives.
+
+    On the first pass this raises through `interrupt()` and the node does not return. On
+    resume it returns the answer message's `answer` field, verbatim -- whatever the
+    consumer put there. The library does not wrap it, merge into it or add an action to
+    it; what was sent is what the node sees.
+    """
+    check_question_size(question)
+    resolved = policy or WaitPolicy()
+    return interrupt({QUESTION_KEY: question, WAIT_KEY: resolved.to_dict()})
+
+
+def unwrap(value: Any) -> tuple[Any, WaitPolicy]:
+    """Split an interrupt value back into `(question, policy)`.
+
+    Handles both shapes: one raised by `ask()`, and a bare `interrupt(value)` from a
+    graph that has never heard of this library.
+    """
+    if isinstance(value, dict) and WAIT_KEY in value:
+        return value.get(QUESTION_KEY), WaitPolicy.from_dict(value.get(WAIT_KEY))
+    return value, WaitPolicy()

langgraph_wait-0.2.0/src/langgraph_wait/resume.py

@@ -0,0 +1,39 @@
+"""`resume_command()` -- turn an answer message into the thing you pass to `invoke()`.
+
+A pure function. It makes no decisions, reads nothing and writes nothing; it exists so
+that the one LangGraph-specific detail in the inbound message format -- that a resume is
+keyed by interrupt id, so that parallel interrupts resume independently -- is written
+down once instead of in every consumer.
+
+    def handle(message):
+        if is_answer(message):
+            return agent.invoke(resume_command(message), message["thread_id"])
+        return agent.invoke(message["input"], message["thread_id"])
+
+`Command(resume=value)` -- the un-keyed form -- hands the same value to *every* parked
+interrupt on the thread. With two approvals outstanding that is one click approving both,
+which is why this builds the dict form even when there is only one.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from langgraph.types import Command
+
+
+def is_answer(message: Mapping[str, Any]) -> bool:
+    """`interrupt_id` present means resume; absent means start. That is the whole rule.
+
+    It holds because the publisher ships a filled-in `reply_with` stub in every envelope
+    and the consumer echoes it back, so the key is there by construction rather than by
+    the consumer remembering to add it.
+    """
+    return bool(message.get("interrupt_id"))
+
+
+def resume_command(message: Mapping[str, Any]) -> Command:
+    """Build the resume for one answer message. Raises `KeyError` if it is a start."""
+    interrupt_id = message["interrupt_id"]
+    return Command(resume={str(interrupt_id): message.get("answer")})