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

{agent_wait-0.2.0 → agent_wait-0.2.1}/.gitignore

@@ -10,10 +10,10 @@ __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/
+
+# generated by the docs workflow from README.md / CHANGELOG.md
+docs/index.md
+docs/changelog.md
+# build output
+dist/
+site/

{agent_wait-0.2.0 → agent_wait-0.2.1}/LICENSE

@@ -1,21 +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.
+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.

{agent_wait-0.2.0 → agent_wait-0.2.1}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: agent-wait
-Version: 0.2.0
-Summary: Publish a LangGraph agent's interrupts to the outside world so a human can answer them -- from a queue, a Lambda, anywhere the process does not stick around.
+Version: 0.2.1
+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
@@ -28,15 +28,20 @@ Description-Content-Type: text/markdown
 [![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)
 
-**Publish a LangGraph agent's interrupts to the outside world, so a human can answer them.**
+**Get a LangGraph interrupt out of the process, and the answer back in.**
 
-A LangGraph node calls `interrupt()` and the graph stops. If the agent runs in a Lambda,
-a container, or anything else that doesn't stick around, the process exits and nobody
-knows a question was asked or where to send the answer. agent-wait takes that pause 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.
+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.
 
-It does not receive the answer. That part is yours, and it is about a dozen lines.
+agent-wait is that code. It takes the pause 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 reduces "is this message a new request or an answer?" to a one-line check.
+
+It does not receive the answer for you. That part is yours, and it is about a dozen lines.
 
 ```bash
 pip install agent-wait langgraph-wait          # core + LangGraph
@@ -170,7 +175,10 @@ Because nothing reads state back through this library, "announce" doesn't have t
 | `EventBridgeAnnounce` | `agent-wait-aws` | A bus, with the transition as detail-type. Notices partial failures behind a 200. |
 | `DynamoDbAnnounce` | `agent-wait-aws` | **A row.** `open` on `created`, `closed` on `resumed`. A GSI on `status` gives an approvals UI its query with no broker anywhere. |
 
-Pass as many as you like; failures are contained per adapter.
+Pass as many as you like; failures are contained per adapter. The full guide — what
+`deliver()` receives, why `dedupe_key` is the one field to get right, patterns from the
+shipped adapters, and how to test yours:
+[Writing an announcer](https://skamalj.github.io/agent-wait/writing-an-announcer/).
 
 ## What the library does *not* do
 
@@ -212,7 +220,7 @@ packages/agent-wait        core. No LangGraph, no AWS, no dependencies. pyright
 packages/langgraph-wait    ask(), the adapter, resume_command(). The only LangGraph import.
 packages/agent-wait-aws    four announce adapters, and a CDK stack.
 examples/refund_agent      a graph, a router, and four scenarios against real AWS.
-docs/                      message contract, architecture, consumer guide.
+docs/                      message contract, architecture, announcer guide, consumer guide.
 ```
 
 ```bash

{agent_wait-0.2.0 → agent_wait-0.2.1}/README.md

@@ -1,200 +1,208 @@
-# 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)
-
-**Publish a LangGraph agent's interrupts to the outside world, so a human can answer them.**
-
-A LangGraph node calls `interrupt()` and the graph stops. If the agent runs in a Lambda,
-a container, or anything else that doesn't stick around, the process exits and nobody
-knows a question was asked or where to send the answer. agent-wait takes that pause 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.
-
-It does not receive the answer. That part is yours, and it is about a dozen lines.
-
-```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 line, where the decision belongs:
-
-```python
-from agent_wait import WaitPolicy
-from langgraph_wait import ask
-
-
-def review(state):
-    if state["amount"] <= 5_000:
-        return {"decision": {"action": "approve", "by": "policy:auto"}}
-
-    decision = ask(
-        {"kind": "refund_approval", "order_id": state["order_id"], "amount": state["amount"]},
-        policy=WaitPolicy(
-            timeout="P3D",
-            default={"action": "reject", "reason": "no response in 3 days"},
-            allowed_actions=("approve", "reject"),
-            tags={"approver_group": "finance"},
-        ),
-    )
-    return {"decision": decision}
-```
-
-`ask()` is a thin wrapper over `interrupt()`. The node pauses exactly as LangGraph pauses;
-what `ask()` adds is the policy, which rides along and comes back out in the envelope. A
-plain `interrupt(value)` works too, with default policy — a graph that already interrupts
-gets published with no edit at all.
-
-**In the host** — wire it once:
-
-```python
-from agent_wait import WaitPublisher
-from agent_wait_aws import SnsAnnounce
-from langgraph_wait import LangGraphAdapter
-
-agent = WaitPublisher(LangGraphAdapter(graph), announce=[SnsAnnounce(topic_arn)])
-```
-
-**Then route each message.** Starts and answers arrive at the same place; `interrupt_id`
-tells them apart:
-
-```python
-from langgraph_wait import is_answer, resume_command
-
-
-def route(message):
-    thread_id = message["thread_id"]
-    if is_answer(message):
-        if not is_still_open(thread_id, message["interrupt_id"]):
-            return  # somebody already answered
-        return agent.invoke(resume_command(message), thread_id)
-    if agent.pending(thread_id):
-        return agent.republish(thread_id)  # a redelivery; don't re-ask
-    return agent.invoke(message["input"], thread_id)
-
-
-def is_still_open(thread_id, interrupt_id):
-    return any(p.interrupt_id == interrupt_id for p in agent.pending(thread_id))
-```
-
-That is the complete integration. [`examples/refund_agent/`](https://github.com/skamalj/agent-wait/tree/main/examples/refund_agent)
-is it, deployed to Lambda behind SQS.
-
-## What goes out
-
-```json
-{
-  "type": "wait.created",
-  "thread_id": "order-4471",
-  "interrupt_id": "a1b2c3d4e5f60718",
-  "question": { "kind": "refund_approval", "amount": 41000 },
-  "allowed_actions": ["approve", "reject"],
-  "expires_at": "2026-09-12T09:00:00Z",
-  "default": { "action": "reject", "reason": "no response in 3 days" },
-  "reply_with": { "thread_id": "order-4471", "interrupt_id": "a1b2c3d4e5f60718", "answer": null }
-}
-```
-
-`reply_with` is a filled-in stub: the consumer copies it, sets `answer`, and posts it to
-wherever your agent listens. Whatever goes in `answer` is what the `ask()` call returns —
-verbatim, with nothing merged into it.
-
-A second envelope, `wait.resumed`, goes out when the graph moves past the question, so a
-UI knows to retract the button.
-
-Full schema, including how to deduplicate:
-[Message formats](https://skamalj.github.io/agent-wait/message-formats/).
-
-## Announcers
-
-An announcer is the only thing you are expected to implement. Subclass `BaseAnnounce`
-and 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())
-```
-
-The contract — **an announcer must never raise into the run** — is enforced by the base
-class: an exception from `deliver()` becomes a log line, and the graph that just parked
-stays parked.
-
-Because nothing reads state back through this library, "announce" doesn't have to mean
-"publish an event". It means *put the question where whoever answers it will find it*:
-
-| Adapter | Package | Where the question lands |
-|---|---|---|
-| `WebhookAnnounce` | `agent-wait` | A URL. JSON POST, optional HMAC-SHA256 signature in the GitHub/Stripe shape. 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; policy `tags` become message attributes for subscription filters. |
-| `SqsAnnounce` | `agent-wait-aws` | A queue; on FIFO, grouped by thread and deduplicated on the stable key. |
-| `EventBridgeAnnounce` | `agent-wait-aws` | A bus, with the transition as detail-type. Notices partial failures behind a 200. |
-| `DynamoDbAnnounce` | `agent-wait-aws` | **A row.** `open` on `created`, `closed` on `resumed`. A GSI on `status` gives an approvals UI its query with no broker anywhere. |
-
-Pass as many as you like; failures are contained per adapter.
-
-## What the library does *not* do
-
-Deliberately — each of these is where teams' own opinions live:
-
-- **Receive answers.** No inbound endpoint, no validation, no tokens. The router above is yours.
-- **Enforce the timeout.** `expires_at` and `default` are published; a sweep of yours
-  sends the default when the deadline passes. There is a
-  [working one](https://github.com/skamalj/agent-wait/blob/main/examples/refund_agent/demo_scenarios.py)
-  in the example.
-- **Decide a race.** `pending()` rejects an answer the graph has already moved past.
-  Two *different* answers in the same instant are your transport's problem — SQS FIFO
-  keyed by thread solves it; an HTTP endpoint with concurrent handlers needs a
-  conditional write.
-- **Authenticate.** Whoever can write to your entry point can answer.
-- **Store anything.** LangGraph's checkpoint is the only state.
-
-## Two LangGraph 1.2.x behaviours you should know about
-
-Both verified against 1.2.11, both pinned by tests that fail if LangGraph changes them.
-
-**`get_state().tasks[*].interrupts` over-reports** ([#4796](https://github.com/langchain-ai/langgraph/issues/4796),
-[#6792](https://github.com/langchain-ai/langgraph/issues/6792)). Resume one of two parallel
-interrupts and the finished task still lists its id. `pending()` filters on `task.result`,
-which is `None` only while genuinely parked.
-
-**Two interrupting tools in one `ToolNode` get the same id** ([#6626](https://github.com/langchain-ai/langgraph/issues/6626),
-[#6624](https://github.com/langchain-ai/langgraph/issues/6624)). A different question under
-an identical id defeats deduplication, and there is no filter for it. The rule is **one
-`interrupt()` per node** — give each approval-requiring tool its own node, which is also
-the fix for a node re-running its side effects on resume.
-
-Details: [Architecture](https://skamalj.github.io/agent-wait/architecture/).
-
-## Layout
-
-```
-packages/agent-wait        core. No LangGraph, no AWS, no dependencies. pyright strict.
-packages/langgraph-wait    ask(), the adapter, resume_command(). The only LangGraph import.
-packages/agent-wait-aws    four announce adapters, and a CDK stack.
-examples/refund_agent      a graph, a router, and four scenarios against real AWS.
-docs/                      message contract, architecture, consumer guide.
-```
-
-```bash
-uv sync
-uv run pytest
-uv run ruff check . && uv run pyright
-```
-
-MIT. Issues and PRs at [github.com/skamalj/agent-wait](https://github.com/skamalj/agent-wait).
+# 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 pause 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 reduces "is this message a new request or an answer?" to a one-line check.
+
+It does not receive the answer for you. That part is yours, and it is about a dozen lines.
+
+```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 line, where the decision belongs:
+
+```python
+from agent_wait import WaitPolicy
+from langgraph_wait import ask
+
+
+def review(state):
+    if state["amount"] <= 5_000:
+        return {"decision": {"action": "approve", "by": "policy:auto"}}
+
+    decision = ask(
+        {"kind": "refund_approval", "order_id": state["order_id"], "amount": state["amount"]},
+        policy=WaitPolicy(
+            timeout="P3D",
+            default={"action": "reject", "reason": "no response in 3 days"},
+            allowed_actions=("approve", "reject"),
+            tags={"approver_group": "finance"},
+        ),
+    )
+    return {"decision": decision}
+```
+
+`ask()` is a thin wrapper over `interrupt()`. The node pauses exactly as LangGraph pauses;
+what `ask()` adds is the policy, which rides along and comes back out in the envelope. A
+plain `interrupt(value)` works too, with default policy — a graph that already interrupts
+gets published with no edit at all.
+
+**In the host** — wire it once:
+
+```python
+from agent_wait import WaitPublisher
+from agent_wait_aws import SnsAnnounce
+from langgraph_wait import LangGraphAdapter
+
+agent = WaitPublisher(LangGraphAdapter(graph), announce=[SnsAnnounce(topic_arn)])
+```
+
+**Then route each message.** Starts and answers arrive at the same place; `interrupt_id`
+tells them apart:
+
+```python
+from langgraph_wait import is_answer, resume_command
+
+
+def route(message):
+    thread_id = message["thread_id"]
+    if is_answer(message):
+        if not is_still_open(thread_id, message["interrupt_id"]):
+            return  # somebody already answered
+        return agent.invoke(resume_command(message), thread_id)
+    if agent.pending(thread_id):
+        return agent.republish(thread_id)  # a redelivery; don't re-ask
+    return agent.invoke(message["input"], thread_id)
+
+
+def is_still_open(thread_id, interrupt_id):
+    return any(p.interrupt_id == interrupt_id for p in agent.pending(thread_id))
+```
+
+That is the complete integration. [`examples/refund_agent/`](https://github.com/skamalj/agent-wait/tree/main/examples/refund_agent)
+is it, deployed to Lambda behind SQS.
+
+## What goes out
+
+```json
+{
+  "type": "wait.created",
+  "thread_id": "order-4471",
+  "interrupt_id": "a1b2c3d4e5f60718",
+  "question": { "kind": "refund_approval", "amount": 41000 },
+  "allowed_actions": ["approve", "reject"],
+  "expires_at": "2026-09-12T09:00:00Z",
+  "default": { "action": "reject", "reason": "no response in 3 days" },
+  "reply_with": { "thread_id": "order-4471", "interrupt_id": "a1b2c3d4e5f60718", "answer": null }
+}
+```
+
+`reply_with` is a filled-in stub: the consumer copies it, sets `answer`, and posts it to
+wherever your agent listens. Whatever goes in `answer` is what the `ask()` call returns —
+verbatim, with nothing merged into it.
+
+A second envelope, `wait.resumed`, goes out when the graph moves past the question, so a
+UI knows to retract the button.
+
+Full schema, including how to deduplicate:
+[Message formats](https://skamalj.github.io/agent-wait/message-formats/).
+
+## Announcers
+
+An announcer is the only thing you are expected to implement. Subclass `BaseAnnounce`
+and 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())
+```
+
+The contract — **an announcer must never raise into the run** — is enforced by the base
+class: an exception from `deliver()` becomes a log line, and the graph that just parked
+stays parked.
+
+Because nothing reads state back through this library, "announce" doesn't have to mean
+"publish an event". It means *put the question where whoever answers it will find it*:
+
+| Adapter | Package | Where the question lands |
+|---|---|---|
+| `WebhookAnnounce` | `agent-wait` | A URL. JSON POST, optional HMAC-SHA256 signature in the GitHub/Stripe shape. 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; policy `tags` become message attributes for subscription filters. |
+| `SqsAnnounce` | `agent-wait-aws` | A queue; on FIFO, grouped by thread and deduplicated on the stable key. |
+| `EventBridgeAnnounce` | `agent-wait-aws` | A bus, with the transition as detail-type. Notices partial failures behind a 200. |
+| `DynamoDbAnnounce` | `agent-wait-aws` | **A row.** `open` on `created`, `closed` on `resumed`. A GSI on `status` gives an approvals UI its query with no broker anywhere. |
+
+Pass as many as you like; failures are contained per adapter. The full guide — what
+`deliver()` receives, why `dedupe_key` is the one field to get right, patterns from the
+shipped adapters, and how to test yours:
+[Writing an announcer](https://skamalj.github.io/agent-wait/writing-an-announcer/).
+
+## What the library does *not* do
+
+Deliberately — each of these is where teams' own opinions live:
+
+- **Receive answers.** No inbound endpoint, no validation, no tokens. The router above is yours.
+- **Enforce the timeout.** `expires_at` and `default` are published; a sweep of yours
+  sends the default when the deadline passes. There is a
+  [working one](https://github.com/skamalj/agent-wait/blob/main/examples/refund_agent/demo_scenarios.py)
+  in the example.
+- **Decide a race.** `pending()` rejects an answer the graph has already moved past.
+  Two *different* answers in the same instant are your transport's problem — SQS FIFO
+  keyed by thread solves it; an HTTP endpoint with concurrent handlers needs a
+  conditional write.
+- **Authenticate.** Whoever can write to your entry point can answer.
+- **Store anything.** LangGraph's checkpoint is the only state.
+
+## Two LangGraph 1.2.x behaviours you should know about
+
+Both verified against 1.2.11, both pinned by tests that fail if LangGraph changes them.
+
+**`get_state().tasks[*].interrupts` over-reports** ([#4796](https://github.com/langchain-ai/langgraph/issues/4796),
+[#6792](https://github.com/langchain-ai/langgraph/issues/6792)). Resume one of two parallel
+interrupts and the finished task still lists its id. `pending()` filters on `task.result`,
+which is `None` only while genuinely parked.
+
+**Two interrupting tools in one `ToolNode` get the same id** ([#6626](https://github.com/langchain-ai/langgraph/issues/6626),
+[#6624](https://github.com/langchain-ai/langgraph/issues/6624)). A different question under
+an identical id defeats deduplication, and there is no filter for it. The rule is **one
+`interrupt()` per node** — give each approval-requiring tool its own node, which is also
+the fix for a node re-running its side effects on resume.
+
+Details: [Architecture](https://skamalj.github.io/agent-wait/architecture/).
+
+## Layout
+
+```
+packages/agent-wait        core. No LangGraph, no AWS, no dependencies. pyright strict.
+packages/langgraph-wait    ask(), the adapter, resume_command(). The only LangGraph import.
+packages/agent-wait-aws    four announce adapters, and a CDK stack.
+examples/refund_agent      a graph, a router, and four scenarios against real AWS.
+docs/                      message contract, architecture, announcer guide, consumer guide.
+```
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check . && uv run pyright
+```
+
+MIT. Issues and PRs at [github.com/skamalj/agent-wait](https://github.com/skamalj/agent-wait).

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

@@ -1,7 +1,7 @@
 [project]
 name = "agent-wait"
-version = "0.2.0"
-description = "Publish a LangGraph agent's interrupts to the outside world so a human can answer them -- from a queue, a Lambda, anywhere the process does not stick around."
+version = "0.2.1"
+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"
 license = "MIT"

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

@@ -1,81 +1,81 @@
-"""agent-wait: publish an agent's interrupts to the outside world.
-
-A graph node asks a question and pauses:
-
-    from langgraph_wait import ask
-
-    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:
-
-    agent = WaitPublisher(LangGraphAdapter(graph), 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.
-"""
-
-from .announce import (
-    AnnounceAdapter,
-    BaseAnnounce,
-    CompositeAnnounce,
-    FailingAnnounce,
-    InMemoryAnnounce,
-    LogAnnounce,
-    WebhookAnnounce,
-    verify_signature,
-)
-from .errors import PolicyError, QuestionTooLarge, WaitError
-from .model import (
-    MAX_QUESTION_BYTES,
-    Clock,
-    EntryPoint,
-    FakeClock,
-    PendingInterrupt,
-    SystemClock,
-    Transition,
-    WaitEnvelope,
-    canonical_json,
-    check_question_size,
-    iso,
-    new_ulid,
-)
-from .policy import WaitPolicy, parse_duration
-from .publisher import FrameworkAdapter, WaitPublisher
-
-__version__ = "0.2.0"
-
-__all__ = [
-    "MAX_QUESTION_BYTES",
-    "AnnounceAdapter",
-    "BaseAnnounce",
-    "Clock",
-    "CompositeAnnounce",
-    "EntryPoint",
-    "FailingAnnounce",
-    "FakeClock",
-    "FrameworkAdapter",
-    "InMemoryAnnounce",
-    "LogAnnounce",
-    "PendingInterrupt",
-    "PolicyError",
-    "QuestionTooLarge",
-    "SystemClock",
-    "Transition",
-    "WaitEnvelope",
-    "WaitError",
-    "WaitPolicy",
-    "WaitPublisher",
-    "WebhookAnnounce",
-    "__version__",
-    "canonical_json",
-    "check_question_size",
-    "iso",
-    "new_ulid",
-    "parse_duration",
-    "verify_signature",
-]
+"""agent-wait: publish an agent's interrupts to the outside world.
+
+A graph node asks a question and pauses:
+
+    from langgraph_wait import ask
+
+    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:
+
+    agent = WaitPublisher(LangGraphAdapter(graph), 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.
+"""
+
+from .announce import (
+    AnnounceAdapter,
+    BaseAnnounce,
+    CompositeAnnounce,
+    FailingAnnounce,
+    InMemoryAnnounce,
+    LogAnnounce,
+    WebhookAnnounce,
+    verify_signature,
+)
+from .errors import PolicyError, QuestionTooLarge, WaitError
+from .model import (
+    MAX_QUESTION_BYTES,
+    Clock,
+    EntryPoint,
+    FakeClock,
+    PendingInterrupt,
+    SystemClock,
+    Transition,
+    WaitEnvelope,
+    canonical_json,
+    check_question_size,
+    iso,
+    new_ulid,
+)
+from .policy import WaitPolicy, parse_duration
+from .publisher import FrameworkAdapter, WaitPublisher
+
+__version__ = "0.2.1"
+
+__all__ = [
+    "MAX_QUESTION_BYTES",
+    "AnnounceAdapter",
+    "BaseAnnounce",
+    "Clock",
+    "CompositeAnnounce",
+    "EntryPoint",
+    "FailingAnnounce",
+    "FakeClock",
+    "FrameworkAdapter",
+    "InMemoryAnnounce",
+    "LogAnnounce",
+    "PendingInterrupt",
+    "PolicyError",
+    "QuestionTooLarge",
+    "SystemClock",
+    "Transition",
+    "WaitEnvelope",
+    "WaitError",
+    "WaitPolicy",
+    "WaitPublisher",
+    "WebhookAnnounce",
+    "__version__",
+    "canonical_json",
+    "check_question_size",
+    "iso",
+    "new_ulid",
+    "parse_duration",
+    "verify_signature",
+]

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

@@ -1,47 +1,47 @@
-"""`CompositeAnnounce` -- fan out to several adapters, isolate their failures.
-
-This is where "must not raise" is actually enforced rather than merely requested of
-adapter authors. A third-party adapter that breaks its side of the contract is contained
-here, and the publisher never learns about it.
-
-There is no retry and no reporting of what got through. A failed announce is recovered
-the same way everything else is: re-invoke the thread, get the same interrupt ids back,
-republish. The consumer discards the duplicate on `dedupe_key`.
-"""
-
-from __future__ import annotations
-
-import logging
-from collections.abc import Sequence
-
-from ..model import Transition, WaitEnvelope
-from .base import AnnounceAdapter
-
-_log = logging.getLogger("agent_wait.announce")
-
-
-class CompositeAnnounce:
-    name = "composite"
-
-    def __init__(self, adapters: Sequence[AnnounceAdapter]) -> None:
-        self.adapters = list(adapters)
-
-    def supports(self, transition: Transition) -> bool:
-        return any(a.supports(transition) for a in self.adapters)
-
-    def announce(self, envelope: WaitEnvelope, transition: Transition) -> None:
-        for adapter in self.adapters:
-            name = getattr(adapter, "name", "?")
-            try:
-                if not adapter.supports(transition):
-                    continue
-                adapter.announce(envelope, transition)
-            except Exception:
-                # A contract violation by the adapter. Contained here, on purpose: if
-                # Slack is down, the graph still parked, and the run still completes.
-                _log.exception(
-                    "announce adapter %s raised on %s for interrupt %s",
-                    name,
-                    transition,
-                    envelope.interrupt_id,
-                )
+"""`CompositeAnnounce` -- fan out to several adapters, isolate their failures.
+
+This is where "must not raise" is actually enforced rather than merely requested of
+adapter authors. A third-party adapter that breaks its side of the contract is contained
+here, and the publisher never learns about it.
+
+There is no retry and no reporting of what got through. A failed announce is recovered
+the same way everything else is: re-invoke the thread, get the same interrupt ids back,
+republish. The consumer discards the duplicate on `dedupe_key`.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+
+from ..model import Transition, WaitEnvelope
+from .base import AnnounceAdapter
+
+_log = logging.getLogger("agent_wait.announce")
+
+
+class CompositeAnnounce:
+    name = "composite"
+
+    def __init__(self, adapters: Sequence[AnnounceAdapter]) -> None:
+        self.adapters = list(adapters)
+
+    def supports(self, transition: Transition) -> bool:
+        return any(a.supports(transition) for a in self.adapters)
+
+    def announce(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        for adapter in self.adapters:
+            name = getattr(adapter, "name", "?")
+            try:
+                if not adapter.supports(transition):
+                    continue
+                adapter.announce(envelope, transition)
+            except Exception:
+                # A contract violation by the adapter. Contained here, on purpose: if
+                # Slack is down, the graph still parked, and the run still completes.
+                _log.exception(
+                    "announce adapter %s raised on %s for interrupt %s",
+                    name,
+                    transition,
+                    envelope.interrupt_id,
+                )

{agent_wait-0.2.0 → agent_wait-0.2.1}/src/agent_wait/errors.py

@@ -1,26 +1,26 @@
-"""The two exceptions agent-wait raises, both at the interrupt site.
-
-There are no runtime errors to speak of. Announce adapters are forbidden from raising
-(see `announce/base.py`) and nothing else in the library makes a decision that can fail.
-"""
-
-from __future__ import annotations
-
-
-class WaitError(Exception):
-    """Base class, so `except WaitError` catches everything this library raises."""
-
-
-class PolicyError(WaitError):
-    """A `WaitPolicy` that cannot mean anything -- an unparseable timeout, an empty
-    `allowed_actions`. Raised at construction, in the graph, where the mistake is."""
-
-
-class QuestionTooLarge(WaitError):
-    """The question would not survive the trip.
-
-    An envelope has to fit through whatever the announce adapter is: SNS caps a message
-    at 256 KB, EventBridge at 256 KB, SQS at 256 KB. Finding out at publish time means a
-    parked interrupt nobody ever hears about, so the size is checked when the question is
-    asked instead.
-    """
+"""The two exceptions agent-wait raises, both at the interrupt site.
+
+There are no runtime errors to speak of. Announce adapters are forbidden from raising
+(see `announce/base.py`) and nothing else in the library makes a decision that can fail.
+"""
+
+from __future__ import annotations
+
+
+class WaitError(Exception):
+    """Base class, so `except WaitError` catches everything this library raises."""
+
+
+class PolicyError(WaitError):
+    """A `WaitPolicy` that cannot mean anything -- an unparseable timeout, an empty
+    `allowed_actions`. Raised at construction, in the graph, where the mistake is."""
+
+
+class QuestionTooLarge(WaitError):
+    """The question would not survive the trip.
+
+    An envelope has to fit through whatever the announce adapter is: SNS caps a message
+    at 256 KB, EventBridge at 256 KB, SQS at 256 KB. Finding out at publish time means a
+    parked interrupt nobody ever hears about, so the size is checked when the question is
+    asked instead.
+    """