langgraph-wait 0.3.0__tar.gz → 0.4.0__tar.gz

{langgraph_wait-0.3.0 → langgraph_wait-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: langgraph-wait
-Version: 0.3.0
+Version: 0.4.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/
@@ -19,7 +19,7 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
-Requires-Dist: agent-wait<0.4,>=0.3
+Requires-Dist: agent-wait<0.5,>=0.4
 Requires-Dist: langgraph<2,>=1.2
 Description-Content-Type: text/markdown
 
@@ -33,19 +33,19 @@ pip install langgraph-wait          # pulls in agent-wait
 ```
 
 ```python
-from langgraph_wait import ask, hitl, publish_interrupts
+from langgraph_wait import hitl, publish_interrupts
 ```
 
-* **`ask(question, policy)`** — a thin wrapper over `interrupt()`; the policy rides along
-  inside the interrupt value. A plain `interrupt(value)` also works, with the default policy.
-* **`@hitl(policy)`** — on a tool function, under `@tool`. Calls `ask()` with `{tool, args}`
-  before the tool runs. `mode="async"` makes the decorator the publisher: it announces and
-  returns pending without parking the thread.
+* **`@hitl(policy)`** — on any function, under `@tool` if it is a tool. Calling it inside a
+  run parks the graph on `{"function", "args"}`. `{"action": "approve"}` runs the body;
+  anything else is returned in its place. A function with a `decision` parameter always
+  runs and receives the answer. `mode="async"` makes the decorator the publisher: it
+  announces and returns pending without parking.
 * **`publish_interrupts(result, thread_id, announce)`** — after `graph.invoke()`. Reads
   `result["__interrupt__"]` and hands one envelope per question to the announcers.
-  Understands `ask()`, bare `interrupt()`, and `HumanInTheLoopMiddleware` batches.
 
-Requires `langgraph >= 1.2`. One `interrupt()` per node — two interrupting tools in one
-`ToolNode` share an id on 1.2.x (langgraph #6626); use the middleware, which batches.
+Requires `langgraph >= 1.2`. Not compatible with LangChain's `HumanInTheLoopMiddleware`
+on the same tool (two interrupts for one approval). One `interrupt()` per node on 1.2.x
+(langgraph #6626).
 
 Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

langgraph_wait-0.4.0/README.md

@@ -0,0 +1,26 @@
+# langgraph-wait
+
+The LangGraph side of [agent-wait](https://pypi.org/project/agent-wait/) — get a LangGraph
+interrupt out of the process, and the answer back in.
+
+```bash
+pip install langgraph-wait          # pulls in agent-wait
+```
+
+```python
+from langgraph_wait import hitl, publish_interrupts
+```
+
+* **`@hitl(policy)`** — on any function, under `@tool` if it is a tool. Calling it inside a
+  run parks the graph on `{"function", "args"}`. `{"action": "approve"}` runs the body;
+  anything else is returned in its place. A function with a `decision` parameter always
+  runs and receives the answer. `mode="async"` makes the decorator the publisher: it
+  announces and returns pending without parking.
+* **`publish_interrupts(result, thread_id, announce)`** — after `graph.invoke()`. Reads
+  `result["__interrupt__"]` and hands one envelope per question to the announcers.
+
+Requires `langgraph >= 1.2`. Not compatible with LangChain's `HumanInTheLoopMiddleware`
+on the same tool (two interrupts for one approval). One `interrupt()` per node on 1.2.x
+(langgraph #6626).
+
+Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

{langgraph_wait-0.3.0 → langgraph_wait-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "langgraph-wait"
-version = "0.3.0"
+version = "0.4.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"
@@ -18,7 +18,7 @@ classifiers = [
     "Topic :: Software Development :: Libraries",
     "Typing :: Typed",
 ]
-dependencies = ["agent-wait>=0.3,<0.4", "langgraph>=1.2,<2"]
+dependencies = ["agent-wait>=0.4,<0.5", "langgraph>=1.2,<2"]
 
 [project.urls]
 Homepage = "https://skamalj.github.io/agent-wait/"

langgraph_wait-0.4.0/src/langgraph_wait/__init__.py

@@ -0,0 +1,6 @@
+"""langgraph-wait: `@hitl` in the graph, `publish_interrupts()` after the run."""
+
+from .hitl import hitl
+from .publish import publish_interrupts, questions_in
+
+__all__ = ["hitl", "publish_interrupts", "questions_in"]

langgraph_wait-0.4.0/src/langgraph_wait/_interrupt.py

@@ -0,0 +1,43 @@
+"""The interrupt value `@hitl` raises, and how `publish_interrupts` reads it back.
+
+Private. An `Interrupt` has one payload and LangGraph offers no side channel, so the
+policy and the source ride inside the value next to the question:
+
+    {"question": {...}, "__wait__": {policy}, "__source__": {...}}
+
+`unwrap()` reverses it. A value without `__wait__` -- a bare `interrupt(x)` from a graph
+that has never heard of this library -- is read as a question with the default policy.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from agent_wait import WaitPolicy, check_question_size
+from langgraph.types import interrupt
+
+WAIT_KEY = "__wait__"
+SOURCE_KEY = "__source__"
+QUESTION_KEY = "question"
+
+
+def raise_question(question: Any, policy: WaitPolicy, source: Mapping[str, Any] | None) -> Any:
+    """Park the graph on `question`; return the answer, verbatim, on resume."""
+    check_question_size(question)
+    value: dict[str, Any] = {QUESTION_KEY: question, WAIT_KEY: policy.to_dict()}
+    if source:
+        value[SOURCE_KEY] = dict(source)
+    return interrupt(value)
+
+
+def unwrap(value: Any) -> tuple[Any, WaitPolicy, Mapping[str, Any] | None]:
+    """`(question, policy, source)` from an interrupt value of either shape."""
+    if isinstance(value, Mapping) and WAIT_KEY in value:
+        source = value.get(SOURCE_KEY)
+        return (
+            value.get(QUESTION_KEY),
+            WaitPolicy.from_dict(value.get(WAIT_KEY)),
+            dict(source) if isinstance(source, Mapping) else None,  # pyright: ignore[reportUnknownArgumentType]
+        )
+    return value, WaitPolicy(), None

langgraph_wait-0.4.0/src/langgraph_wait/hitl.py

@@ -0,0 +1,132 @@
+"""`@hitl` -- make a function interruptible.
+
+    @tool
+    @hitl(WaitPolicy(timeout="P1D", default={"action": "reject"}, tags={"approver_group": "finance"}))
+    def issue_refund(order_id: str, amount: int) -> str:
+        ...
+
+That is the whole declaration. Calling the decorated function inside a run raises a
+LangGraph interrupt with `{"function": "issue_refund", "args": {...}}` as the question;
+`publish_interrupts()` after the run announces it; the answer comes back as
+`Command(resume={question_id: answer})`, and:
+
+    {"action": "approve"}                    -> the body runs with its original args
+    {"action": "approve", "args": {...}}     -> the body runs with these args instead
+    anything else                            -> the body does NOT run; the answer is
+                                                returned in its place, so a model sees why
+
+## Getting the answer itself: the `decision` parameter
+
+A tool usually only needs to know whether to run. A node usually needs the answer. If
+the decorated function has a parameter named `decision` (rename it with `decision=`),
+it **always** runs and receives the answer there, approve or not:
+
+    @hitl(FINANCE)
+    def review(state, decision=None):
+        return {"decision": decision}        # verbatim: {"action": "approve", "note": "ok"}
+
+## `mode="async"` -- the thread does not park
+
+    @tool
+    @hitl(FINANCE, mode="async", announce=[SnsAnnounce(topic), DynamoDbAnnounce(table)])
+    def issue_refund(order_id: str, amount: int) -> str: ...
+
+The decorator *is* the publisher. The call announces the question through the announcers
+given here and returns `{"status": "pending_approval", "question_id": ...}` without
+running the body. Nothing is parked; nothing is called after the run; the graph carries
+on. The decision arrives later as a **new message** and the graph acts on it however you
+designed it. This is the mode for a single-thread channel like WhatsApp, where the
+approver is not the person on the thread. LangGraph remembers nothing about the
+question; whatever record you keep (a `DynamoDbAnnounce` row is one) is the only one.
+
+`question_id` is `sha256(thread | function | args)`, so the same call on the same thread
+is the same question and a consumer sees one, not two.
+
+## Not compatible with `HumanInTheLoopMiddleware`
+
+LangChain's `create_agent` middleware interrupts *before* a tool is called, in its own
+shape, with its own resume format. Putting `@hitl` on a tool the middleware also
+intercepts interrupts twice -- once by the middleware, then again inside the tool when it
+finally runs. Use one or the other. This library is the other.
+
+## One `interrupt()` per node
+
+Two `@hitl` functions dispatched by the same `ToolNode` share an interrupt id on
+langgraph 1.2.x (#6626); only one surfaces per run (#6624). Give each interrupting tool
+its own node.
+"""
+
+from __future__ import annotations
+
+import functools
+import hashlib
+import inspect
+from collections.abc import Callable, Mapping, Sequence
+from typing import Any, Literal
+
+from agent_wait import AnnounceAdapter, Question, WaitPolicy, canonical_json, publish
+
+from ._interrupt import raise_question
+
+Mode = Literal["interrupt", "async"]
+
+
+def question_id_for(thread_id: str, function: str, args: Mapping[str, Any]) -> str:
+    """Deterministic: the same call on the same thread is the same question."""
+    return hashlib.sha256(f"{thread_id}|{function}|{canonical_json(dict(args))}".encode()).hexdigest()[:32]
+
+
+def _thread_id() -> str:
+    from langgraph.config import get_config
+
+    thread_id = get_config().get("configurable", {}).get("thread_id")
+    if not thread_id:
+        raise RuntimeError("@hitl(mode='async') needs a thread_id in the run config")
+    return str(thread_id)
+
+
+def hitl(
+    policy: WaitPolicy | None = None,
+    *,
+    mode: Mode = "interrupt",
+    announce: Sequence[AnnounceAdapter] | None = None,
+    decision: str = "decision",
+) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Make a function interruptible. See the module docstring."""
+    resolved = policy or WaitPolicy(allowed_actions=("approve", "reject"))
+    if mode == "async" and not announce:
+        raise ValueError("@hitl(mode='async') publishes from inside the function, so it needs announce=[...]")
+    announcers: Sequence[AnnounceAdapter] = list(announce or ())
+
+    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
+        name = fn.__name__
+        signature = inspect.signature(fn)
+        wants_decision = decision in signature.parameters
+        source = {"function": name}
+
+        @functools.wraps(fn)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            bound = signature.bind_partial(*args, **kwargs)
+            bound.apply_defaults()
+            call_args: dict[str, Any] = {k: v for k, v in bound.arguments.items() if k != decision}
+            question = {"function": name, "args": call_args}
+
+            if mode == "async":
+                thread_id = _thread_id()
+                qid = question_id_for(thread_id, name, call_args)
+                publish([Question(qid, question, resolved, source=source)], thread_id, announcers)
+                return {"status": "pending_approval", "question_id": qid, "function": name}
+
+            answer = raise_question(question, resolved, source)
+            if wants_decision:
+                return fn(**call_args, **{decision: answer})
+            if isinstance(answer, Mapping) and answer.get("action") == "approve":
+                edited = answer.get("args")
+                merged = {**call_args, **dict(edited)} if isinstance(edited, Mapping) else call_args  # pyright: ignore[reportUnknownArgumentType]
+                return fn(**merged)
+            return answer
+
+        wrapper.__hitl__ = {"mode": mode, "policy": resolved}  # type: ignore[attr-defined]
+        return wrapper
+
+    return decorate

langgraph_wait-0.4.0/src/langgraph_wait/publish.py

@@ -0,0 +1,57 @@
+"""`publish_interrupts()` -- announce what `graph.invoke()` just parked on.
+
+    result = graph.invoke(value, config)
+    publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
+
+When a `@hitl` function is called (or any node calls `interrupt()`), LangGraph returns
+the run's output with an `__interrupt__` entry: a sequence of `Interrupt` objects, each
+with `.id` and `.value` and nothing else (`ns`, `when`, `resumable` were removed in
+langgraph 0.6). This reads that entry and hands one envelope per question to the
+announcers. No `__interrupt__`, nothing happens. `stream()` yields the same shape as a
+chunk, so it works on a chunk.
+
+A bare `interrupt(value)` from a node that never heard of this library is published too,
+with `value` as the question and the default policy.
+
+Nothing here runs the graph, reads its state, or resumes anything.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, Sequence
+from typing import Any
+
+from agent_wait import AnnounceAdapter, Clock, EntryPoint, Question, WaitEnvelope, publish
+
+from ._interrupt import unwrap
+
+INTERRUPT_KEY = "__interrupt__"
+
+
+def questions_in(result: Any) -> list[Question]:
+    """The questions a run returned, from its `__interrupt__`. `[]` if it did not park."""
+    if not isinstance(result, Mapping):
+        return []
+    raw = result.get(INTERRUPT_KEY)  # pyright: ignore[reportUnknownMemberType]
+    if not raw:
+        return []
+    out: list[Question] = []
+    for item in raw:  # pyright: ignore[reportUnknownVariableType]
+        question, policy, source = unwrap(getattr(item, "value", None))
+        out.append(Question(str(getattr(item, "id", "")), question, policy, source=source))
+    return out
+
+
+def publish_interrupts(
+    result: Any,
+    thread_id: str,
+    announce: Sequence[AnnounceAdapter],
+    *,
+    reply_to: EntryPoint | None = None,
+    clock: Clock | None = None,
+) -> list[WaitEnvelope]:
+    """Announce every question in `result`. Returns the envelopes sent; `[]` if none."""
+    questions = questions_in(result)
+    if not questions:
+        return []
+    return publish(questions, thread_id, announce, reply_to=reply_to, clock=clock)

langgraph_wait-0.3.0/README.md

@@ -1,26 +0,0 @@
-# langgraph-wait
-
-The LangGraph side of [agent-wait](https://pypi.org/project/agent-wait/) — get a LangGraph
-interrupt out of the process, and the answer back in.
-
-```bash
-pip install langgraph-wait          # pulls in agent-wait
-```
-
-```python
-from langgraph_wait import ask, hitl, publish_interrupts
-```
-
-* **`ask(question, policy)`** — a thin wrapper over `interrupt()`; the policy rides along
-  inside the interrupt value. A plain `interrupt(value)` also works, with the default policy.
-* **`@hitl(policy)`** — on a tool function, under `@tool`. Calls `ask()` with `{tool, args}`
-  before the tool runs. `mode="async"` makes the decorator the publisher: it announces and
-  returns pending without parking the thread.
-* **`publish_interrupts(result, thread_id, announce)`** — after `graph.invoke()`. Reads
-  `result["__interrupt__"]` and hands one envelope per question to the announcers.
-  Understands `ask()`, bare `interrupt()`, and `HumanInTheLoopMiddleware` batches.
-
-Requires `langgraph >= 1.2`. One `interrupt()` per node — two interrupting tools in one
-`ToolNode` share an id on 1.2.x (langgraph #6626); use the middleware, which batches.
-
-Full documentation: [skamalj.github.io/agent-wait](https://skamalj.github.io/agent-wait/).

langgraph_wait-0.3.0/src/langgraph_wait/__init__.py

@@ -1,16 +0,0 @@
-"""langgraph-wait: `ask()` or `@hitl` in the graph, `publish_interrupts()` after the run."""
-
-from .ask import WAIT_KEY, ask, unwrap
-from .hitl import hitl, policy_for, question_id_for
-from .publish import publish_interrupts, questions_in
-
-__all__ = [
-    "WAIT_KEY",
-    "ask",
-    "hitl",
-    "policy_for",
-    "publish_interrupts",
-    "question_id_for",
-    "questions_in",
-    "unwrap",
-]

langgraph_wait-0.3.0/src/langgraph_wait/ask.py

@@ -1,57 +0,0 @@
-"""`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 collections.abc import Mapping
-from typing import Any
-
-from agent_wait import WaitPolicy, check_question_size
-from langgraph.types import interrupt
-
-WAIT_KEY = "__wait__"
-SOURCE_KEY = "__source__"
-QUESTION_KEY = "question"
-
-
-def ask(question: Any, policy: WaitPolicy | None = None, *, source: Mapping[str, Any] | 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()
-    value: dict[str, Any] = {QUESTION_KEY: question, WAIT_KEY: resolved.to_dict()}
-    if source:
-        value[SOURCE_KEY] = dict(source)
-    return interrupt(value)
-
-
-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.3.0/src/langgraph_wait/hitl.py

@@ -1,146 +0,0 @@
-"""`@hitl` -- mark a tool as needing a human, in one of two ways.
-
-    @tool
-    @hitl(WaitPolicy(timeout="P1D", default={"action": "reject"}, tags={"approver_group": "finance"}))
-    def issue_refund(order_id: str, amount: int) -> str:
-        ...
-
-Apply it *under* `@tool`, on the function. It registers the policy against the tool's
-name (so `publish_interrupts` can find it for middleware-batched interrupts too) and
-wraps the call in one of two behaviours.
-
-## `mode="interrupt"` (default) -- the thread parks
-
-The wrapper calls `ask()` with `{"tool": name, "args": {...}}` before running the tool.
-The graph stops; `publish_interrupts()` after the run announces it; the answer comes back
-as `Command(resume={question_id: decision})` and the tool runs, or does not:
-
-    {"action": "approve"}                      -> the tool runs with its original args
-    {"action": "approve", "args": {...}}       -> the tool runs with these args instead
-    anything else                              -> the tool does NOT run; the decision is
-                                                  returned as the tool's result, so the
-                                                  model sees why
-
-One `interrupt()` per node still applies (langgraph #6626): two `@hitl` tools dispatched
-by the same `ToolNode` share an interrupt id. Use `HumanInTheLoopMiddleware`, which
-batches them into one interrupt, or give each its own node.
-
-## `mode="async"` -- the thread does not park
-
-    @tool
-    @hitl(FINANCE, mode="async", announce=[SnsAnnounce(topic), DynamoDbAnnounce(table)])
-    def issue_refund(order_id: str, amount: int) -> str: ...
-
-The decorator *is* the publisher. When the tool is called it announces the question
-through the announcers given here and returns `{"status": "pending_approval",
-"question_id": ...}` without running the tool body. The graph carries on; the model sees
-that the action is pending; there is no `__interrupt__` and nothing to call after the run.
-The decision arrives later as a **new message** to the agent, carrying the `question_id`
--- how, and what the graph does with it, is yours.
-
-Nothing is parked, so nothing in LangGraph remembers the question. Whatever record you
-keep (a `DynamoDbAnnounce` table is one) is the only one. This is the right mode when the
-person answering is not the person on the thread -- a customer chatting on WhatsApp while
-finance approves in a dashboard -- and it should be a visible choice, not a default.
-
-`question_id` is derived from the thread, the tool and its arguments, so the same call
-on the same thread produces the same id: a consumer sees one question, not two. Pass
-`question_id=` to override. The thread id comes from the run config, where LangGraph
-keeps it.
-"""
-
-from __future__ import annotations
-
-import functools
-import hashlib
-import inspect
-import json
-from collections.abc import Callable, Mapping, Sequence
-from typing import Any, Literal
-
-from agent_wait import AnnounceAdapter, Question, WaitPolicy, canonical_json, publish
-
-from .ask import ask
-
-Mode = Literal["interrupt", "async"]
-
-_REGISTRY: dict[str, WaitPolicy] = {}
-
-
-def policy_for(tool_name: str) -> WaitPolicy | None:
-    """The policy `@hitl` registered for a tool, or None."""
-    return _REGISTRY.get(tool_name)
-
-
-def question_id_for(thread_id: str, tool: str, args: Mapping[str, Any]) -> str:
-    """Deterministic: the same call on the same thread is the same question."""
-    return hashlib.sha256(f"{thread_id}|{tool}|{canonical_json(dict(args))}".encode()).hexdigest()[:32]
-
-
-def _thread_id() -> str:
-    from langgraph.config import get_config
-
-    configurable = get_config().get("configurable", {})
-    thread_id = configurable.get("thread_id")
-    if not thread_id:
-        raise RuntimeError("@hitl(mode='async') needs a thread_id in the run config")
-    return str(thread_id)
-
-
-def hitl(
-    policy: WaitPolicy | None = None,
-    *,
-    mode: Mode = "interrupt",
-    announce: Sequence[AnnounceAdapter] | None = None,
-    question_id: Callable[[str, str, Mapping[str, Any]], str] | None = None,
-) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
-    resolved = policy or WaitPolicy(allowed_actions=("approve", "reject"))
-    if mode == "async" and not announce:
-        raise ValueError("@hitl(mode='async') publishes from inside the tool, so it needs announce=[...]")
-    announcers: Sequence[AnnounceAdapter] = list(announce or ())
-
-    def decorate(fn: Callable[..., Any]) -> Callable[..., Any]:
-        name = fn.__name__
-        _REGISTRY[name] = resolved
-        signature = inspect.signature(fn)
-
-        @functools.wraps(fn)
-        def wrapper(*args: Any, **kwargs: Any) -> Any:
-            bound = signature.bind_partial(*args, **kwargs)
-            bound.apply_defaults()
-            call_args: dict[str, Any] = dict(bound.arguments)
-            question = {"tool": name, "args": call_args}
-
-            if mode == "interrupt":
-                decision = ask(question, resolved, source={"tool": name})
-                return _apply(decision, fn, call_args)
-
-            thread_id = _thread_id()
-            qid = (question_id or question_id_for)(thread_id, name, call_args)
-            publish(
-                [Question(question_id=qid, question=question, policy=resolved, source={"tool": name})],
-                thread_id,
-                announcers,
-            )
-            return {"status": "pending_approval", "question_id": qid, "tool": name}
-
-        wrapper.__hitl__ = {"mode": mode, "policy": resolved}  # type: ignore[attr-defined]
-        return wrapper
-
-    return decorate
-
-
-def _apply(decision: Any, fn: Callable[..., Any], call_args: Mapping[str, Any]) -> Any:
-    """Run the tool if the decision says so; otherwise hand the decision back as the result."""
-    if isinstance(decision, Mapping) and decision.get("action") == "approve":
-        edited = decision.get("args")
-        merged = {**call_args, **dict(edited)} if isinstance(edited, Mapping) else dict(call_args)  # pyright: ignore[reportUnknownArgumentType]
-        return fn(**merged)
-    if isinstance(decision, Mapping):
-        return {"status": "not_executed", **dict(decision)}  # pyright: ignore[reportUnknownArgumentType]
-    return {
-        "status": "not_executed",
-        "decision": decision
-        if isinstance(decision, str | int | float | bool | type(None))
-        else json.loads(json.dumps(decision, default=str)),
-    }

langgraph_wait-0.3.0/src/langgraph_wait/publish.py

@@ -1,91 +0,0 @@
-"""`publish_interrupts()` -- announce what `graph.invoke()` just parked on.
-
-    result = graph.invoke(value, config)
-    publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
-
-When a node calls `interrupt()`, LangGraph returns the run's output with an
-`__interrupt__` entry: a sequence of `Interrupt` objects, each with `.id` and `.value`
-(nothing else -- `ns`, `when`, `resumable` were removed in langgraph 0.6). This reads
-that entry and hands one envelope per question to the announcers. No `__interrupt__`,
-nothing happens. `stream()` yields the same shape as a chunk, so it works on a chunk.
-
-## Three interrupt shapes are understood
-
-1. **`ask()`** -- `.value` is `{"question": ..., "__wait__": policy}`. One question.
-2. **A bare `interrupt(value)`** -- one question, `value` verbatim, default policy.
-3. **`HumanInTheLoopMiddleware`** (`langchain.agents`) -- `.value` is an `HITLRequest`:
-   `{"action_requests": [{name, args, description}], "review_configs": [...]}`. The
-   middleware batches every tool call needing review into ONE interrupt, so this is one
-   question whose payload is the whole batch, and whose answer is the middleware's
-   `HITLResponse`: `{"decisions": [{type: approve|reject|edit|respond, ...}, ...]}` in
-   batch order. The policy comes from `@hitl` on the first tool in the batch, if any.
-
-Nothing here runs the graph, reads its state, or resumes anything. The answer's shape
-and its return path are yours; the envelope's `reply_with` stub carries `question_id`,
-and `Command(resume={question_id: answer})` is how LangGraph takes it.
-"""
-
-from __future__ import annotations
-
-from collections.abc import Mapping, Sequence
-from typing import Any
-
-from agent_wait import AnnounceAdapter, Clock, EntryPoint, Question, WaitEnvelope, WaitPolicy, publish
-
-from .ask import unwrap
-from .hitl import policy_for
-
-INTERRUPT_KEY = "__interrupt__"
-
-
-def _is_hitl_request(value: Any) -> bool:
-    return isinstance(value, Mapping) and "action_requests" in value and "review_configs" in value
-
-
-def _from_hitl_request(interrupt_id: str, value: Mapping[str, Any]) -> Question:
-    actions: list[Mapping[str, Any]] = list(value.get("action_requests") or [])
-    names = [str(a.get("name", "")) for a in actions]
-    policy = policy_for(names[0]) if names else None
-    return Question(
-        question_id=interrupt_id,
-        question={"actions": actions, "review": list(value.get("review_configs") or [])},
-        policy=policy or WaitPolicy(allowed_actions=("approve", "reject", "edit", "respond")),
-        source={"tools": names, "via": "HumanInTheLoopMiddleware"},
-    )
-
-
-def questions_in(result: Any) -> list[Question]:
-    """The questions a run returned, from its `__interrupt__`. `[]` if it did not park."""
-    if not isinstance(result, Mapping):
-        return []
-    raw = result.get(INTERRUPT_KEY)  # pyright: ignore[reportUnknownMemberType]
-    if not raw:
-        return []
-    out: list[Question] = []
-    for item in raw:  # pyright: ignore[reportUnknownVariableType]
-        interrupt_id = str(getattr(item, "id", ""))
-        value = getattr(item, "value", None)
-        if _is_hitl_request(value):
-            out.append(_from_hitl_request(interrupt_id, value))
-            continue
-        question, policy = unwrap(value)
-        source = None
-        if isinstance(value, Mapping) and isinstance(value.get("__source__"), Mapping):
-            source = dict(value["__source__"])  # pyright: ignore[reportUnknownArgumentType]
-        out.append(Question(question_id=interrupt_id, question=question, policy=policy, source=source))
-    return out
-
-
-def publish_interrupts(
-    result: Any,
-    thread_id: str,
-    announce: Sequence[AnnounceAdapter],
-    *,
-    reply_to: EntryPoint | None = None,
-    clock: Clock | None = None,
-) -> list[WaitEnvelope]:
-    """Announce every question in `result`. Returns the envelopes sent; `[]` if none."""
-    questions = questions_in(result)
-    if not questions:
-        return []
-    return publish(questions, thread_id, announce, reply_to=reply_to, clock=clock)