agent-wait 0.2.1__tar.gz → 0.4.0__tar.gz

agent_wait-0.4.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.5
+Name: agent-wait
+Version: 0.4.0
+Summary: Get a LangGraph interrupt out of the process -- to a topic, a queue, a webhook, a table -- so anyone can answer it, and the answer back in.
+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
+Project-URL: Changelog, https://github.com/skamalj/agent-wait/blob/main/CHANGELOG.md
+Author-email: Kamaljeet Singh <skamalj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,approval,durable,human-in-the-loop,interrupt,langgraph,serverless
+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
+Description-Content-Type: text/markdown
+
+# agent-wait
+
+[![PyPI](https://img.shields.io/pypi/v/agent-wait.svg)](https://pypi.org/project/agent-wait/)
+[![CI](https://github.com/skamalj/agent-wait/actions/workflows/ci.yml/badge.svg)](https://github.com/skamalj/agent-wait/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/skamalj/agent-wait/blob/main/LICENSE)
+
+**Get a LangGraph interrupt out of the process, and the answer back in.**
+
+When a node calls `interrupt()`, the graph pauses and the interrupt is handed to whatever
+called `invoke()` — and that is where LangGraph stops. There is no built-in way to tell
+anyone *else* that a question was asked, and no built-in way for anyone else to answer
+it. The moment the question has to reach a person on Slack, an approvals dashboard, a
+ticket queue or another service, you are writing that code yourself — whether your agent
+is a server that runs for a year or a Lambda that is gone in seconds.
+
+agent-wait is that code. It takes the interrupt and puts it somewhere people can see it —
+a topic, a queue, a webhook, a database row — with everything needed to answer it in one
+envelope, and documents the shape of the answer so the return leg is one `if`.
+
+```bash
+pip install agent-wait langgraph-wait          # core + LangGraph
+pip install agent-wait-aws                     # SNS / SQS / EventBridge / DynamoDB announcers
+```
+
+## The whole thing
+
+**In the graph** — one decorator, on the function where the decision belongs:
+
+```python
+from agent_wait import WaitPolicy
+from langgraph_wait import hitl
+
+FINANCE = WaitPolicy(
+    timeout="P3D",
+    default={"action": "reject"},
+    allowed_actions=("approve", "reject"),
+    tags={"approver_group": "finance"},
+)
+
+
+@tool
+@hitl(FINANCE)
+def issue_refund(order_id: str, amount: int) -> str:
+    payments.refund(order_id, amount)  # runs only if the answer is {"action": "approve"}
+    return "refunded"
+```
+
+Calling `issue_refund(...)` inside a run parks the graph on `{"function": "issue_refund",
+"args": {...}}`. On resume, `{"action": "approve"}` runs the body — optionally with edited
+`args` — and anything else is returned in its place, so a model sees why it did not run.
+
+A node that needs the answer itself declares a `decision` parameter and always runs:
+
+```python
+@hitl(FINANCE)
+def review(state, decision=None):
+    return {"decision": decision}  # verbatim: {"action": "approve", "note": "ok"}
+```
+
+**After the run** — one call:
+
+```python
+from agent_wait_aws import SnsAnnounce
+from langgraph_wait import publish_interrupts
+
+result = graph.invoke(value, {"configurable": {"thread_id": thread_id}})
+publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
+```
+
+It reads `result["__interrupt__"]` — `Interrupt.id` and `Interrupt.value`, nothing else —
+and hands one envelope per question to the announcers. No graph handle, no `get_state()`,
+no checkpointer. If nothing interrupted, it does nothing. A plain `interrupt(value)` from
+a node that never heard of this library is published too, with the default policy.
+
+**When the answer comes back** — the one `if` you write:
+
+```python
+from langgraph.types import Command
+
+if "question_id" in message:  # an answer
+    value = Command(resume={message["question_id"]: message["answer"]})
+else:  # a start
+    value = message["input"]
+
+result = graph.invoke(value, {"configurable": {"thread_id": message["thread_id"]}})
+publish_interrupts(result, message["thread_id"], announce)
+```
+
+That is the complete integration. A duplicate answer runs nothing — LangGraph ignores a
+resume for a question the thread has moved past — so there is nothing to check.
+
+## Async mode — the thread does not park
+
+```python
+@tool
+@hitl(FINANCE, mode="async", announce=[SnsAnnounce(topic_arn), DynamoDbAnnounce(table)])
+def issue_refund(order_id: str, amount: int) -> str: ...
+```
+
+The decorator *is* the publisher: the call announces the question and returns
+`{"status": "pending_approval", "question_id": ...}` without running. The graph carries
+on; nothing is parked; nothing to call after the run. The decision arrives later as a new
+message and your graph acts on it. This is the mode for a single-thread channel like
+WhatsApp, where the approver is not the person on the thread.
+
+## What goes out
+
+```json
+{
+  "type": "wait.created",
+  "thread_id": "order-4471",
+  "question_id": "a1b2c3d4e5f60718",
+  "question": { "function": "issue_refund", "args": { "order_id": "order-4471", "amount": 41000 } },
+  "allowed_actions": ["approve", "reject"],
+  "expires_at": "2026-09-14T09:00:00Z",
+  "default": { "action": "reject" },
+  "source": { "function": "issue_refund" },
+  "reply_with": { "thread_id": "order-4471", "question_id": "a1b2c3d4e5f60718", "answer": null }
+}
+```
+
+`reply_with` is a filled-in stub: copy it, set `answer`, send it back. Whatever goes in
+`answer` is what the `@hitl` function receives — verbatim.
+
+Full schema, the recommended answer shape, and how to deduplicate:
+[Message formats](https://skamalj.github.io/agent-wait/message-formats/).
+
+## Announcers
+
+Subclass `BaseAnnounce`, write one method:
+
+```python
+from agent_wait import BaseAnnounce
+
+
+class RedisAnnounce(BaseAnnounce):
+    name = "redis"
+
+    def __init__(self, client, **kw):
+        super().__init__(**kw)
+        self.client = client
+
+    def deliver(self, envelope, transition):
+        self.client.set(envelope.dedupe_key, envelope.to_json())
+```
+
+A raise inside `deliver()` becomes a log line; the run completes. Shipped:
+
+| Adapter | Package | Where the question lands |
+|---|---|---|
+| `WebhookAnnounce` | `agent-wait` | A URL. JSON POST, optional HMAC-SHA256 signature. Stdlib only. |
+| `LogAnnounce` | `agent-wait` | A structured log line. The question never reaches INFO. |
+| `InMemoryAnnounce` | `agent-wait` | A list. For tests. |
+| `SnsAnnounce` | `agent-wait-aws` | A topic; `tags` become message attributes for subscription filters. |
+| `SqsAnnounce` | `agent-wait-aws` | A queue; on FIFO, grouped by thread, deduplicated on the stable key. |
+| `EventBridgeAnnounce` | `agent-wait-aws` | A bus. Notices partial failures behind a 200. |
+| `DynamoDbAnnounce` | `agent-wait-aws` | **A row**, `status=open`, with a GSI an approvals UI can query. Write-only. |
+
+[Writing an announcer](https://skamalj.github.io/agent-wait/writing-an-announcer/).
+
+## What the library does *not* do
+
+- **Receive answers.** No endpoint, no validation, no ledger reads. The `if` above is yours.
+- **Enforce anything.** `expires_at`, `default`, `answer_ttl`, `allowed_actions` are
+  published so the consumer has the asker's intent. Acting on them is the consumer's.
+- **Store anything.** LangGraph's checkpoint is the only state in interrupt mode; in
+  async mode there is none unless you keep one.
+
+## Two things to know
+
+**Not compatible with LangChain's `HumanInTheLoopMiddleware`.** It interrupts *before* a
+tool is called, in its own shape; `@hitl` interrupts inside the call. Both on one tool
+means two interrupts for one approval. Use one or the other.
+
+**One `interrupt()` per node** on langgraph 1.2.x. Two interrupting tools dispatched by
+one `ToolNode` get the **same interrupt id**
+([#6626](https://github.com/langchain-ai/langgraph/issues/6626)), and only one surfaces
+per run ([#6624](https://github.com/langchain-ai/langgraph/issues/6624)). Give each
+interrupting tool its own node. Pinned by a test that fails if LangGraph changes it.
+
+## Layout
+
+```
+packages/agent-wait        core: Question, WaitPolicy, the envelope, publish(), announcers. No deps.
+packages/langgraph-wait    @hitl and publish_interrupts(). The only LangGraph import.
+packages/agent-wait-aws    four announce adapters, and a CDK stack for the example.
+examples/refund_agent      a graph and a host, deployed to Lambda behind SQS.
+docs/                      message contract, architecture, announcer guide, consumer guide.
+```
+
+MIT. Issues and PRs at [github.com/skamalj/agent-wait](https://github.com/skamalj/agent-wait).

agent_wait-0.4.0/README.md

@@ -0,0 +1,191 @@
+# agent-wait
+
+[![PyPI](https://img.shields.io/pypi/v/agent-wait.svg)](https://pypi.org/project/agent-wait/)
+[![CI](https://github.com/skamalj/agent-wait/actions/workflows/ci.yml/badge.svg)](https://github.com/skamalj/agent-wait/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/skamalj/agent-wait/blob/main/LICENSE)
+
+**Get a LangGraph interrupt out of the process, and the answer back in.**
+
+When a node calls `interrupt()`, the graph pauses and the interrupt is handed to whatever
+called `invoke()` — and that is where LangGraph stops. There is no built-in way to tell
+anyone *else* that a question was asked, and no built-in way for anyone else to answer
+it. The moment the question has to reach a person on Slack, an approvals dashboard, a
+ticket queue or another service, you are writing that code yourself — whether your agent
+is a server that runs for a year or a Lambda that is gone in seconds.
+
+agent-wait is that code. It takes the interrupt and puts it somewhere people can see it —
+a topic, a queue, a webhook, a database row — with everything needed to answer it in one
+envelope, and documents the shape of the answer so the return leg is one `if`.
+
+```bash
+pip install agent-wait langgraph-wait          # core + LangGraph
+pip install agent-wait-aws                     # SNS / SQS / EventBridge / DynamoDB announcers
+```
+
+## The whole thing
+
+**In the graph** — one decorator, on the function where the decision belongs:
+
+```python
+from agent_wait import WaitPolicy
+from langgraph_wait import hitl
+
+FINANCE = WaitPolicy(
+    timeout="P3D",
+    default={"action": "reject"},
+    allowed_actions=("approve", "reject"),
+    tags={"approver_group": "finance"},
+)
+
+
+@tool
+@hitl(FINANCE)
+def issue_refund(order_id: str, amount: int) -> str:
+    payments.refund(order_id, amount)  # runs only if the answer is {"action": "approve"}
+    return "refunded"
+```
+
+Calling `issue_refund(...)` inside a run parks the graph on `{"function": "issue_refund",
+"args": {...}}`. On resume, `{"action": "approve"}` runs the body — optionally with edited
+`args` — and anything else is returned in its place, so a model sees why it did not run.
+
+A node that needs the answer itself declares a `decision` parameter and always runs:
+
+```python
+@hitl(FINANCE)
+def review(state, decision=None):
+    return {"decision": decision}  # verbatim: {"action": "approve", "note": "ok"}
+```
+
+**After the run** — one call:
+
+```python
+from agent_wait_aws import SnsAnnounce
+from langgraph_wait import publish_interrupts
+
+result = graph.invoke(value, {"configurable": {"thread_id": thread_id}})
+publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
+```
+
+It reads `result["__interrupt__"]` — `Interrupt.id` and `Interrupt.value`, nothing else —
+and hands one envelope per question to the announcers. No graph handle, no `get_state()`,
+no checkpointer. If nothing interrupted, it does nothing. A plain `interrupt(value)` from
+a node that never heard of this library is published too, with the default policy.
+
+**When the answer comes back** — the one `if` you write:
+
+```python
+from langgraph.types import Command
+
+if "question_id" in message:  # an answer
+    value = Command(resume={message["question_id"]: message["answer"]})
+else:  # a start
+    value = message["input"]
+
+result = graph.invoke(value, {"configurable": {"thread_id": message["thread_id"]}})
+publish_interrupts(result, message["thread_id"], announce)
+```
+
+That is the complete integration. A duplicate answer runs nothing — LangGraph ignores a
+resume for a question the thread has moved past — so there is nothing to check.
+
+## Async mode — the thread does not park
+
+```python
+@tool
+@hitl(FINANCE, mode="async", announce=[SnsAnnounce(topic_arn), DynamoDbAnnounce(table)])
+def issue_refund(order_id: str, amount: int) -> str: ...
+```
+
+The decorator *is* the publisher: the call announces the question and returns
+`{"status": "pending_approval", "question_id": ...}` without running. The graph carries
+on; nothing is parked; nothing to call after the run. The decision arrives later as a new
+message and your graph acts on it. This is the mode for a single-thread channel like
+WhatsApp, where the approver is not the person on the thread.
+
+## What goes out
+
+```json
+{
+  "type": "wait.created",
+  "thread_id": "order-4471",
+  "question_id": "a1b2c3d4e5f60718",
+  "question": { "function": "issue_refund", "args": { "order_id": "order-4471", "amount": 41000 } },
+  "allowed_actions": ["approve", "reject"],
+  "expires_at": "2026-09-14T09:00:00Z",
+  "default": { "action": "reject" },
+  "source": { "function": "issue_refund" },
+  "reply_with": { "thread_id": "order-4471", "question_id": "a1b2c3d4e5f60718", "answer": null }
+}
+```
+
+`reply_with` is a filled-in stub: copy it, set `answer`, send it back. Whatever goes in
+`answer` is what the `@hitl` function receives — verbatim.
+
+Full schema, the recommended answer shape, and how to deduplicate:
+[Message formats](https://skamalj.github.io/agent-wait/message-formats/).
+
+## Announcers
+
+Subclass `BaseAnnounce`, write one method:
+
+```python
+from agent_wait import BaseAnnounce
+
+
+class RedisAnnounce(BaseAnnounce):
+    name = "redis"
+
+    def __init__(self, client, **kw):
+        super().__init__(**kw)
+        self.client = client
+
+    def deliver(self, envelope, transition):
+        self.client.set(envelope.dedupe_key, envelope.to_json())
+```
+
+A raise inside `deliver()` becomes a log line; the run completes. Shipped:
+
+| Adapter | Package | Where the question lands |
+|---|---|---|
+| `WebhookAnnounce` | `agent-wait` | A URL. JSON POST, optional HMAC-SHA256 signature. Stdlib only. |
+| `LogAnnounce` | `agent-wait` | A structured log line. The question never reaches INFO. |
+| `InMemoryAnnounce` | `agent-wait` | A list. For tests. |
+| `SnsAnnounce` | `agent-wait-aws` | A topic; `tags` become message attributes for subscription filters. |
+| `SqsAnnounce` | `agent-wait-aws` | A queue; on FIFO, grouped by thread, deduplicated on the stable key. |
+| `EventBridgeAnnounce` | `agent-wait-aws` | A bus. Notices partial failures behind a 200. |
+| `DynamoDbAnnounce` | `agent-wait-aws` | **A row**, `status=open`, with a GSI an approvals UI can query. Write-only. |
+
+[Writing an announcer](https://skamalj.github.io/agent-wait/writing-an-announcer/).
+
+## What the library does *not* do
+
+- **Receive answers.** No endpoint, no validation, no ledger reads. The `if` above is yours.
+- **Enforce anything.** `expires_at`, `default`, `answer_ttl`, `allowed_actions` are
+  published so the consumer has the asker's intent. Acting on them is the consumer's.
+- **Store anything.** LangGraph's checkpoint is the only state in interrupt mode; in
+  async mode there is none unless you keep one.
+
+## Two things to know
+
+**Not compatible with LangChain's `HumanInTheLoopMiddleware`.** It interrupts *before* a
+tool is called, in its own shape; `@hitl` interrupts inside the call. Both on one tool
+means two interrupts for one approval. Use one or the other.
+
+**One `interrupt()` per node** on langgraph 1.2.x. Two interrupting tools dispatched by
+one `ToolNode` get the **same interrupt id**
+([#6626](https://github.com/langchain-ai/langgraph/issues/6626)), and only one surfaces
+per run ([#6624](https://github.com/langchain-ai/langgraph/issues/6624)). Give each
+interrupting tool its own node. Pinned by a test that fails if LangGraph changes it.
+
+## Layout
+
+```
+packages/agent-wait        core: Question, WaitPolicy, the envelope, publish(), announcers. No deps.
+packages/langgraph-wait    @hitl and publish_interrupts(). The only LangGraph import.
+packages/agent-wait-aws    four announce adapters, and a CDK stack for the example.
+examples/refund_agent      a graph and a host, deployed to Lambda behind SQS.
+docs/                      message contract, architecture, announcer guide, consumer guide.
+```
+
+MIT. Issues and PRs at [github.com/skamalj/agent-wait](https://github.com/skamalj/agent-wait).

{agent_wait-0.2.1 → agent_wait-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agent-wait"
-version = "0.2.1"
+version = "0.4.0"
 description = "Get a LangGraph interrupt out of the process -- to a topic, a queue, a webhook, a table -- so anyone can answer it, and the answer back in."
 readme = "README.md"
 requires-python = ">=3.12"

{agent_wait-0.2.1 → agent_wait-0.4.0}/src/agent_wait/__init__.py

@@ -1,4 +1,4 @@
-"""agent-wait: publish an agent's interrupts to the outside world.
+"""agent-wait: announce an agent's interrupts to the outside world.
 
 A graph node asks a question and pauses:
 
@@ -7,16 +7,13 @@ A graph node asks a question and pauses:
     decision = ask({"kind": "refund_approval", "amount": amount},
                    policy=WaitPolicy(timeout="P3D", allowed_actions=("approve", "reject")))
 
-The host runs the graph through a publisher, and whatever the graph parked on goes out
-to wherever people can see it:
+After the run, the host announces whatever it parked on:
 
-    agent = WaitPublisher(LangGraphAdapter(graph), announce=[SnsAnnounce(topic_arn)])
+    result = graph.invoke(value, config)
+    publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
 
-    agent.invoke(payload, thread_id)
-
-That is the whole library. It publishes questions and it reports what a thread is parked
-on. It does not receive answers, hold state, mint credentials or run timers -- see
-`docs/migrating-from-0.1.md` for what that means if you are coming from v0.1.
+That is the whole library. It builds one envelope per interrupt and hands it to the
+announcers. It does not run the graph, receive answers, hold state or run timers.
 """
 
 from .announce import (
@@ -35,7 +32,7 @@ from .model import (
     Clock,
     EntryPoint,
     FakeClock,
-    PendingInterrupt,
+    Question,
     SystemClock,
     Transition,
     WaitEnvelope,
@@ -45,9 +42,9 @@ from .model import (
     new_ulid,
 )
 from .policy import WaitPolicy, parse_duration
-from .publisher import FrameworkAdapter, WaitPublisher
+from .publish import build_envelope, publish
 
-__version__ = "0.2.1"
+__version__ = "0.4.0"
 
 __all__ = [
     "MAX_QUESTION_BYTES",
@@ -58,24 +55,24 @@ __all__ = [
     "EntryPoint",
     "FailingAnnounce",
     "FakeClock",
-    "FrameworkAdapter",
     "InMemoryAnnounce",
     "LogAnnounce",
-    "PendingInterrupt",
     "PolicyError",
+    "Question",
     "QuestionTooLarge",
     "SystemClock",
     "Transition",
     "WaitEnvelope",
     "WaitError",
     "WaitPolicy",
-    "WaitPublisher",
     "WebhookAnnounce",
     "__version__",
+    "build_envelope",
     "canonical_json",
     "check_question_size",
     "iso",
     "new_ulid",
     "parse_duration",
+    "publish",
     "verify_signature",
 ]

{agent_wait-0.2.1 → agent_wait-0.4.0}/src/agent_wait/announce/base.py

@@ -89,7 +89,7 @@ class BaseAnnounce(ABC):
         except Exception:
             # A backend being unreachable must not fail a run that has already parked.
             self._log.exception(
-                "%s failed for interrupt %s (%s)", type(self).__name__, envelope.interrupt_id, transition
+                "%s failed for interrupt %s (%s)", type(self).__name__, envelope.question_id, transition
             )
 
     @abstractmethod

{agent_wait-0.2.1 → agent_wait-0.4.0}/src/agent_wait/announce/composite.py

@@ -43,5 +43,5 @@ class CompositeAnnounce:
                     "announce adapter %s raised on %s for interrupt %s",
                     name,
                     transition,
-                    envelope.interrupt_id,
+                    envelope.question_id,
                 )

{agent_wait-0.2.1 → agent_wait-0.4.0}/src/agent_wait/announce/log.py

@@ -33,7 +33,7 @@ class LogAnnounce(BaseAnnounce):
             "event": envelope.type,
             "event_id": envelope.event_id,
             "thread_id": envelope.thread_id,
-            "interrupt_id": envelope.interrupt_id,
+            "question_id": envelope.question_id,
             "allowed_actions": list(envelope.allowed_actions),
             "expires_at": envelope.expires_at,
             "tags": dict(envelope.tags),
@@ -42,6 +42,6 @@ class LogAnnounce(BaseAnnounce):
         if self._out.isEnabledFor(logging.DEBUG):
             self._out.debug(
                 "agent-wait question for %s: %s",
-                envelope.interrupt_id,
+                envelope.question_id,
                 json.dumps(envelope.question, default=str),
             )

{agent_wait-0.2.1 → agent_wait-0.4.0}/src/agent_wait/announce/webhook.py

@@ -8,7 +8,7 @@ transition, JSON body, three headers a receiver can route or verify on:
 
     Content-Type:              application/json
     X-Agent-Wait-Event:        wait.created | wait.resumed
-    X-Agent-Wait-Dedupe-Key:   wait.created:<interrupt_id>
+    X-Agent-Wait-Dedupe-Key:   wait.created:<question_id>
     X-Agent-Wait-Signature:    sha256=<hex>          (only when `secret` is given)
 
 ## Signing

{agent_wait-0.2.1 → agent_wait-0.4.0}/src/agent_wait/model.py

@@ -18,15 +18,11 @@ from typing import Any, Literal, Protocol
 from .errors import QuestionTooLarge
 from .policy import WaitPolicy
 
-Transition = Literal["created", "resumed"]
-"""The two things that can be said about a wait.
+Transition = Literal["created"]
+"""The one thing said about a wait: the graph is parked on this question.
 
-`created` -- the graph is parked on this question; here is everything needed to answer
-it. `resumed` -- the graph has moved past it; close the ticket, retract the button.
-
-There is no `answered`, `expired` or `cancelled`. Those would describe the library's
-opinion about an answer, and no answer ever reaches the library. Only the graph's own
-state is reported, and the graph knows exactly two things: parked, or not.
+Announce adapters receive it as a second argument so an adapter can be written once for
+any future transition without changing its signature; today only `created` is emitted.
 """
 
 # 256 KB is the smallest of the caps on the way out (SNS, SQS and EventBridge all sit
@@ -113,21 +109,24 @@ class EntryPoint:
 
 
 @dataclass(frozen=True)
-class PendingInterrupt:
-    """One question a thread is parked on. What a `FrameworkAdapter` hands back."""
+class Question:
+    """One question for a human. What `publish()` takes.
+
+    `question_id` is whatever the answer must carry back. In interrupt mode it is
+    LangGraph's `Interrupt.id`; in async mode it is an id you minted -- derive it from the
+    inputs (`sha256(thread | tool | args)`) so the same trigger produces the same question
+    and the consumer sees one, not two.
+    """
 
-    interrupt_id: str
+    question_id: str
     question: Any
     policy: WaitPolicy
     asked_at: float | None = None
-    """When the framework checkpointed this interrupt, if it can say.
-
-    This is what `expires_at` is measured from. It has to come from the checkpoint
-    rather than from the clock at publish time, because the same question is republished
-    whenever a start message is redelivered -- and a deadline recomputed as `now +
-    timeout` on each republish would walk forward forever, which is precisely the
-    failure a timeout exists to prevent.
-    """
+    """POSIX timestamp of when the question was asked, if known. `expires_at` is measured
+    from it when set and from publish time otherwise."""
+    source: Mapping[str, Any] | None = None
+    """Where it came from -- `{"tool": "issue_refund"}`, `{"node": "review"}`. The first
+    thing an approver reads, so worth filling in when you can."""
 
 
 @dataclass(frozen=True)
@@ -137,13 +136,15 @@ class WaitEnvelope:
     type: str
     event_id: str
     thread_id: str
-    interrupt_id: str
+    question_id: str
     question: Any
     allowed_actions: tuple[str, ...]
     expires_at: str | None
     reply_with: Mapping[str, Any]
     reply_to: Mapping[str, str] | None = None
     default: Any = None
+    answer_ttl: str | int | None = None
+    source: Mapping[str, Any] | None = None
     correlation: Mapping[str, str] | None = None
     tags: Mapping[str, str] = field(default_factory=_no_str_map)
 
@@ -153,22 +154,24 @@ class WaitEnvelope:
 
         Not `event_id`: that is fresh per publish, so a redelivered start message
         republishing the same question would look like a second question. LangGraph
-        guarantees `interrupt_id` is stable across re-entry and resume-from-checkpoint
+        guarantees `question_id` is stable across re-entry and resume-from-checkpoint
         (verified in `test_spike_langgraph.py`), which makes this key stable for exactly
         as long as the question is.
         """
-        return f"{self.type}:{self.interrupt_id}"
+        return f"{self.type}:{self.question_id}"
 
     def to_dict(self) -> dict[str, Any]:
         return {
             "type": self.type,
             "event_id": self.event_id,
             "thread_id": self.thread_id,
-            "interrupt_id": self.interrupt_id,
+            "question_id": self.question_id,
             "question": self.question,
             "allowed_actions": list(self.allowed_actions),
             "expires_at": self.expires_at,
             "default": self.default,
+            "answer_ttl": self.answer_ttl,
+            "source": dict(self.source) if self.source else None,
             "reply_to": dict(self.reply_to) if self.reply_to else None,
             "reply_with": dict(self.reply_with),
             "correlation": dict(self.correlation) if self.correlation else None,