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

{agent_wait-0.4.0 → agent_wait-0.5.0}/PKG-INFO

@@ -1,7 +1,7 @@
 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.
+Version: 0.5.0
+Summary: Human-in-the-loop for LangGraph agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get 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
@@ -10,7 +10,7 @@ Project-URL: Changelog, https://github.com/skamalj/agent-wait/blob/main/CHANGELO
 Author-email: Kamaljeet Singh <skamalj@gmail.com>
 License-Expression: MIT
 License-File: LICENSE
-Keywords: agents,approval,durable,human-in-the-loop,interrupt,langgraph,serverless
+Keywords: agents,approval,callback,durable,dynamodb,eventbridge,hitl,human-in-the-loop,interrupt,lambda,langchain,langgraph,serverless,sns,sqs,webhook
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -20,6 +20,13 @@ Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Typing :: Typed
 Requires-Python: >=3.12
+Provides-Extra: all
+Requires-Dist: boto3>=1.35; extra == 'all'
+Requires-Dist: langgraph<2,>=1.2; extra == 'all'
+Provides-Extra: aws
+Requires-Dist: boto3>=1.35; extra == 'aws'
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2,>=1.2; extra == 'langgraph'
 Description-Content-Type: text/markdown
 
 # agent-wait
@@ -27,32 +34,42 @@ Description-Content-Type: text/markdown
 [![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)
+[![Docs](https://img.shields.io/badge/docs-skamalj.github.io%2Fagent--wait-black.svg)](https://skamalj.github.io/agent-wait/)
 
-**Get a LangGraph interrupt out of the process, and the answer back in.**
+**Make an agent wait for something outside the process — and get 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.
+Human-in-the-loop is the common case: a refund over the limit, a contract clause, a
+deploy. But the same shape covers a vendor callback, a payment processor, a KYC check, or
+another agent — anything the run cannot continue without, and nothing inside the process
+can supply.
 
-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`.
+LangGraph has `interrupt()` for this. When a node calls it 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 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 (or systems)
+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
+pip install "agent-wait[langgraph]"        # @wait + publish_interrupts for LangGraph
+pip install "agent-wait[langgraph,aws]"    # + SNS / SQS / EventBridge / DynamoDB announcers
 ```
 
+The bare `agent-wait` is the framework-free core (policy, envelope, webhook and in-memory
+announcers) and depends on nothing. Each extra pulls in exactly one framework or provider.
+
 ## 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
+from agent_wait.langgraph import wait
+from langchain_core.tools import tool
 
 FINANCE = WaitPolicy(
     timeout="P3D",
@@ -63,7 +80,7 @@ FINANCE = WaitPolicy(
 
 
 @tool
-@hitl(FINANCE)
+@wait(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"
@@ -73,19 +90,34 @@ Calling `issue_refund(...)` inside a run parks the graph on `{"function": "issue
 "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:
+The policy is what the asker declares about the question. Every field is published and
+none is enforced — the consumer acts on them:
+
+| field | meaning |
+|---|---|
+| `timeout` | ISO 8601 duration. Published as an absolute `expires_at`. |
+| `default` | What to send as the answer if nobody answers by then. |
+| `answer_ttl` | How long an answer stays usable after it is given. |
+| `allowed_actions` | Which answers are meaningful — the buttons to draw. |
+| `tags` | Routing hints; become SNS message attributes. |
+| `correlation` | Your reference for the thing being waited on — a vendor job id, a ticket. |
+
+A node that needs the answer itself declares a `decision` parameter and always runs,
+approve or not, with the answer in it:
 
 ```python
-@hitl(FINANCE)
+@wait(FINANCE)
 def review(state, decision=None):
     return {"decision": decision}  # verbatim: {"action": "approve", "note": "ok"}
 ```
 
+The parameter name is yours — `@wait(FINANCE, decision="verdict")` looks for `verdict`.
+
 **After the run** — one call:
 
 ```python
-from agent_wait_aws import SnsAnnounce
-from langgraph_wait import publish_interrupts
+from agent_wait.aws import SnsAnnounce
+from agent_wait.langgraph import publish_interrupts
 
 result = graph.invoke(value, {"configurable": {"thread_id": thread_id}})
 publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
@@ -116,16 +148,21 @@ resume for a question the thread has moved past — so there is nothing to check
 ## Async mode — the thread does not park
 
 ```python
+from agent_wait.aws import DynamoDbAnnounce, SnsAnnounce
+
+
 @tool
-@hitl(FINANCE, mode="async", announce=[SnsAnnounce(topic_arn), DynamoDbAnnounce(table)])
+@wait(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.
+`{"status": "pending_approval", "question_id": "...", "function": "issue_refund"}`
+without running the body. 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 — and since nothing is parked, LangGraph remembers nothing about the
+question; the `DynamoDbAnnounce` row (or whatever you keep) is the only record.
 
 ## What goes out
 
@@ -144,7 +181,7 @@ WhatsApp, where the approver is not the person on the thread.
 ```
 
 `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.
+`answer` is what the `@wait` function receives — verbatim.
 
 Full schema, the recommended answer shape, and how to deduplicate:
 [Message formats](https://skamalj.github.io/agent-wait/message-formats/).
@@ -168,19 +205,13 @@ class RedisAnnounce(BaseAnnounce):
         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. |
+A raise inside `deliver()` becomes a log line; the run completes.
 
-[Writing an announcer](https://skamalj.github.io/agent-wait/writing-an-announcer/).
+Shipped in the core: `WebhookAnnounce` (signed JSON POST, stdlib), `LogAnnounce`,
+`InMemoryAnnounce`. With `[aws]`: `SnsAnnounce`, `SqsAnnounce`, `EventBridgeAnnounce`,
+`DynamoDbAnnounce` (the question as a row an approvals UI can query). Each one, its
+constructor and where the question lands: [Announcers](https://skamalj.github.io/agent-wait/announcers/).
+Your own: [Writing an announcer](https://skamalj.github.io/agent-wait/writing-an-announcer/).
 
 ## What the library does *not* do
 
@@ -193,7 +224,7 @@ A raise inside `deliver()` becomes a log line; the run completes. Shipped:
 ## 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
+tool is called, in its own shape; `@wait` 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
@@ -204,12 +235,21 @@ interrupting tool its own node. Pinned by a test that fails if LangGraph changes
 
 ## Layout
 
+One distribution, one import root. Frameworks and providers are subpackages behind extras:
+
 ```
-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.
+agent_wait              core: WaitPolicy, Question, the envelope, publish(), BaseAnnounce,
+                        Webhook/Log/InMemory announcers, and the Framework interface. No deps.
+agent_wait.langgraph    [langgraph]  @wait and publish_interrupts() bound to LangGraph.
+agent_wait.aws          [aws]        SnsAnnounce, SqsAnnounce, EventBridgeAnnounce, DynamoDbAnnounce.
+examples/refund_agent   a graph, a host written for Lambda behind SQS, and its CDK stack.
+docs/                   message contract, architecture, announcer guide, consumer guide.
 ```
 
+`@wait` and `publish_interrupts` are written once against a three-method `Framework`
+interface; `agent_wait.langgraph` is one implementor of it. Announcers are the same
+split: `BaseAnnounce` is the interface, each provider subpackage the implementors. A
+`strands` extra follows the same pattern — see
+[Architecture](https://skamalj.github.io/agent-wait/architecture/).
+
 MIT. Issues and PRs at [github.com/skamalj/agent-wait](https://github.com/skamalj/agent-wait).

{agent_wait-0.4.0 → agent_wait-0.5.0}/README.md

@@ -3,32 +3,42 @@
 [![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)
+[![Docs](https://img.shields.io/badge/docs-skamalj.github.io%2Fagent--wait-black.svg)](https://skamalj.github.io/agent-wait/)
 
-**Get a LangGraph interrupt out of the process, and the answer back in.**
+**Make an agent wait for something outside the process — and get 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.
+Human-in-the-loop is the common case: a refund over the limit, a contract clause, a
+deploy. But the same shape covers a vendor callback, a payment processor, a KYC check, or
+another agent — anything the run cannot continue without, and nothing inside the process
+can supply.
 
-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`.
+LangGraph has `interrupt()` for this. When a node calls it 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 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 (or systems)
+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
+pip install "agent-wait[langgraph]"        # @wait + publish_interrupts for LangGraph
+pip install "agent-wait[langgraph,aws]"    # + SNS / SQS / EventBridge / DynamoDB announcers
 ```
 
+The bare `agent-wait` is the framework-free core (policy, envelope, webhook and in-memory
+announcers) and depends on nothing. Each extra pulls in exactly one framework or provider.
+
 ## 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
+from agent_wait.langgraph import wait
+from langchain_core.tools import tool
 
 FINANCE = WaitPolicy(
     timeout="P3D",
@@ -39,7 +49,7 @@ FINANCE = WaitPolicy(
 
 
 @tool
-@hitl(FINANCE)
+@wait(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"
@@ -49,19 +59,34 @@ Calling `issue_refund(...)` inside a run parks the graph on `{"function": "issue
 "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:
+The policy is what the asker declares about the question. Every field is published and
+none is enforced — the consumer acts on them:
+
+| field | meaning |
+|---|---|
+| `timeout` | ISO 8601 duration. Published as an absolute `expires_at`. |
+| `default` | What to send as the answer if nobody answers by then. |
+| `answer_ttl` | How long an answer stays usable after it is given. |
+| `allowed_actions` | Which answers are meaningful — the buttons to draw. |
+| `tags` | Routing hints; become SNS message attributes. |
+| `correlation` | Your reference for the thing being waited on — a vendor job id, a ticket. |
+
+A node that needs the answer itself declares a `decision` parameter and always runs,
+approve or not, with the answer in it:
 
 ```python
-@hitl(FINANCE)
+@wait(FINANCE)
 def review(state, decision=None):
     return {"decision": decision}  # verbatim: {"action": "approve", "note": "ok"}
 ```
 
+The parameter name is yours — `@wait(FINANCE, decision="verdict")` looks for `verdict`.
+
 **After the run** — one call:
 
 ```python
-from agent_wait_aws import SnsAnnounce
-from langgraph_wait import publish_interrupts
+from agent_wait.aws import SnsAnnounce
+from agent_wait.langgraph import publish_interrupts
 
 result = graph.invoke(value, {"configurable": {"thread_id": thread_id}})
 publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
@@ -92,16 +117,21 @@ resume for a question the thread has moved past — so there is nothing to check
 ## Async mode — the thread does not park
 
 ```python
+from agent_wait.aws import DynamoDbAnnounce, SnsAnnounce
+
+
 @tool
-@hitl(FINANCE, mode="async", announce=[SnsAnnounce(topic_arn), DynamoDbAnnounce(table)])
+@wait(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.
+`{"status": "pending_approval", "question_id": "...", "function": "issue_refund"}`
+without running the body. 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 — and since nothing is parked, LangGraph remembers nothing about the
+question; the `DynamoDbAnnounce` row (or whatever you keep) is the only record.
 
 ## What goes out
 
@@ -120,7 +150,7 @@ WhatsApp, where the approver is not the person on the thread.
 ```
 
 `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.
+`answer` is what the `@wait` function receives — verbatim.
 
 Full schema, the recommended answer shape, and how to deduplicate:
 [Message formats](https://skamalj.github.io/agent-wait/message-formats/).
@@ -144,19 +174,13 @@ class RedisAnnounce(BaseAnnounce):
         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. |
+A raise inside `deliver()` becomes a log line; the run completes.
 
-[Writing an announcer](https://skamalj.github.io/agent-wait/writing-an-announcer/).
+Shipped in the core: `WebhookAnnounce` (signed JSON POST, stdlib), `LogAnnounce`,
+`InMemoryAnnounce`. With `[aws]`: `SnsAnnounce`, `SqsAnnounce`, `EventBridgeAnnounce`,
+`DynamoDbAnnounce` (the question as a row an approvals UI can query). Each one, its
+constructor and where the question lands: [Announcers](https://skamalj.github.io/agent-wait/announcers/).
+Your own: [Writing an announcer](https://skamalj.github.io/agent-wait/writing-an-announcer/).
 
 ## What the library does *not* do
 
@@ -169,7 +193,7 @@ A raise inside `deliver()` becomes a log line; the run completes. Shipped:
 ## 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
+tool is called, in its own shape; `@wait` 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
@@ -180,12 +204,21 @@ interrupting tool its own node. Pinned by a test that fails if LangGraph changes
 
 ## Layout
 
+One distribution, one import root. Frameworks and providers are subpackages behind extras:
+
 ```
-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.
+agent_wait              core: WaitPolicy, Question, the envelope, publish(), BaseAnnounce,
+                        Webhook/Log/InMemory announcers, and the Framework interface. No deps.
+agent_wait.langgraph    [langgraph]  @wait and publish_interrupts() bound to LangGraph.
+agent_wait.aws          [aws]        SnsAnnounce, SqsAnnounce, EventBridgeAnnounce, DynamoDbAnnounce.
+examples/refund_agent   a graph, a host written for Lambda behind SQS, and its CDK stack.
+docs/                   message contract, architecture, announcer guide, consumer guide.
 ```
 
+`@wait` and `publish_interrupts` are written once against a three-method `Framework`
+interface; `agent_wait.langgraph` is one implementor of it. Announcers are the same
+split: `BaseAnnounce` is the interface, each provider subpackage the implementors. A
+`strands` extra follows the same pattern — see
+[Architecture](https://skamalj.github.io/agent-wait/architecture/).
+
 MIT. Issues and PRs at [github.com/skamalj/agent-wait](https://github.com/skamalj/agent-wait).

agent_wait-0.5.0/pyproject.toml

@@ -0,0 +1,109 @@
+[project]
+name = "agent-wait"
+version = "0.5.0"
+description = "Human-in-the-loop for LangGraph agents -- and anything else a run has to wait for. Get the interrupt out of the process (SNS, SQS, EventBridge, DynamoDB, webhook) with everything needed to answer it; get the answer back in."
+readme = "README.md"
+requires-python = ">=3.12"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Kamaljeet Singh", email = "skamalj@gmail.com" }]
+keywords = [
+    "human-in-the-loop",
+    "hitl",
+    "approval",
+    "langgraph",
+    "langchain",
+    "agents",
+    "interrupt",
+    "durable",
+    "serverless",
+    "lambda",
+    "sqs",
+    "sns",
+    "eventbridge",
+    "dynamodb",
+    "webhook",
+    "callback",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries",
+    "Typing :: Typed",
+]
+dependencies = []
+
+[project.optional-dependencies]
+langgraph = ["langgraph>=1.2,<2"]
+aws = ["boto3>=1.35"]
+all = ["agent-wait[langgraph,aws]"]
+
+[project.urls]
+Homepage = "https://skamalj.github.io/agent-wait/"
+Documentation = "https://skamalj.github.io/agent-wait/"
+Source = "https://github.com/skamalj/agent-wait"
+Issues = "https://github.com/skamalj/agent-wait/issues"
+Changelog = "https://github.com/skamalj/agent-wait/blob/main/CHANGELOG.md"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_wait"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/agent_wait", "README.md", "LICENSE"]
+
+[dependency-groups]
+dev = [
+    "agent-wait[all]",
+    "pytest>=8.3",
+    "pytest-cov>=5.0",
+    "ruff>=0.6",
+    "pyright>=1.1.380",
+    "moto[dynamodb,sqs,sns,events]>=5.0",
+    "boto3-stubs[dynamodb,sqs,sns,events]>=1.35",
+    "langgraph-checkpoint-sqlite>=2.0",
+    "aws-cdk-lib>=2.160",
+    "constructs>=10.3",
+]
+
+[tool.uv.sources]
+agent-wait = { workspace = true }
+
+[tool.uv.workspace]
+members = ["."]
+
+[tool.pytest.ini_options]
+testpaths = ["tests", "examples"]
+addopts = "-q --strict-markers"
+norecursedirs = ["cdk.out", "build", ".venv", "reference"]
+markers = [
+    "e2e: requires real AWS; opt in with AGENT_WAIT_E2E=1",
+    "spike: empirical probes of LangGraph behaviour",
+]
+filterwarnings = ["ignore::DeprecationWarning"]
+
+[tool.ruff]
+line-length = 110
+target-version = "py312"
+extend-exclude = ["reference", "cdk.out"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
+ignore = ["B008", "RUF012"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["E501"]
+
+[tool.pyright]
+include = ["src"]
+exclude = ["reference", "**/node_modules", "**/__pycache__"]
+pythonVersion = "3.12"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false

agent_wait-0.5.0/reference/wait-sim/README.md

@@ -0,0 +1,31 @@
+# agent-wait · end-to-end simulation (LangGraph agent on Lambda)
+
+Runs a real LangGraph graph (1.2.x) through the durable-wait design, with in-memory stand-ins
+for the AWS services. Every stand-in mimics the one property the design relies on:
+
+| Stand-in            | Real service          | Property relied on                                   |
+|---------------------|-----------------------|------------------------------------------------------|
+| `DynamoWaitStore`   | DynamoDB              | conditional writes (status CAS), unique idempotency key |
+| `SqsFifo`           | SQS FIFO              | one in-flight message per MessageGroupId, visibility timeout, redelivery |
+| `EventBridgeScheduler` | EventBridge Scheduler | one-time schedule named by wait_id, deleted on cancel |
+| `EventBridgeBus`    | EventBridge           | fan-out to subscribers (SNS/Slack/webhooks)          |
+| `run_handler` etc.  | Lambda                | stateless invocations that can die mid-way           |
+
+```
+pip install langgraph
+python simulate.py
+```
+
+Files:
+- `agent_wait/core.py`            — the framework-agnostic core: Wait model, 5 ports, HMAC tokens, Waiter, sweeper
+- `agent_wait/langgraph_adapter.py` — `ask()` + the LangGraph adapter (extract interrupts, build resume, still_pending)
+- `agent_wait/aws_sim.py`         — the AWS stand-ins
+- `app/graph.py`                  — the customer's refund graph (knows nothing about AWS)
+- `app/lambdas.py`                — three Lambda handlers: run (SQS), answer (API Gateway), on_timer (Scheduler)
+- `simulate.py`                   — four scenarios; `RUN_OUTPUT.txt` is a captured run
+
+Scenarios:
+- A  crash after checkpoint but before register → redelivery → idempotent; double-click; stale reject; tampered token; resume on another Lambda; refund issued once
+- B  no answer for 3 days → Scheduler fires → default reject → late click gets 409
+- C  crash after resume applied but before SQS ack → redelivery → still_pending() guard → no second refund
+- D  crash after DynamoDB create but before timer/notify → sweeper completes setup