agent-wait 0.4.1__tar.gz → 0.6.0__tar.gz

{agent_wait-0.4.1 → agent_wait-0.6.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.5
 Name: agent-wait
-Version: 0.4.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.
+Version: 0.6.0
+Summary: Human-in-the-loop for LangGraph and Pydantic AI 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,pydantic-ai,serverless,sns,sqs,webhook
 Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
@@ -20,6 +20,16 @@ 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'
+Requires-Dist: pydantic-ai-slim<3,>=2.43; extra == 'all'
+Provides-Extra: aws
+Requires-Dist: boto3>=1.35; extra == 'aws'
+Provides-Extra: langgraph
+Requires-Dist: langgraph<2,>=1.2; extra == 'langgraph'
+Provides-Extra: pydantic-ai
+Requires-Dist: pydantic-ai-slim<3,>=2.43; extra == 'pydantic-ai'
 Description-Content-Type: text/markdown
 
 # agent-wait
@@ -29,32 +39,42 @@ Description-Content-Type: text/markdown
 [![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; Pydantic AI has `ApprovalRequired`. In both, the
+run pauses and the question is handed to whatever called it — and that is where the
+framework 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[pydantic-ai]"      # the same two names for Pydantic AI
+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 agent_wait.langgraph import wait
 from langchain_core.tools import tool
-from langgraph_wait import hitl
 
 FINANCE = WaitPolicy(
     timeout="P3D",
@@ -65,7 +85,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"
@@ -85,23 +105,24 @@ none is enforced — the consumer acts on them:
 | `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 — `@hitl(FINANCE, decision="verdict")` looks for `verdict`.
+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)])
@@ -129,14 +150,58 @@ 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.
 
+## The same two names on Pydantic AI
+
+```python
+from agent_wait.pydantic_ai import publish_interrupts, wait
+from pydantic_ai import Agent, DeferredToolRequests, DeferredToolResults, RunContext, ToolApproved, ToolDenied
+
+agent = Agent("openai:gpt-5.4", output_type=[str, DeferredToolRequests])
+
+
+@agent.tool
+@wait(FINANCE)
+def issue_refund(ctx: RunContext[None], order_id: str, amount: int) -> str:
+    payments.refund(order_id, amount)
+    return "refunded"
+
+
+result = agent.run_sync("refund order 4471", message_history=history)
+publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
+store(thread_id, result.all_messages())  # Pydantic AI has no checkpointer; the history is yours
+```
+
+The run ends with `DeferredToolRequests` in `result.output`; `question_id` is the
+`tool_call_id`. The answer goes back through the framework's own resume, with the answer
+itself riding in `metadata` so the `@wait` rules apply unchanged:
+
+```python
+approved = answer.get("action") == "approve"
+result = agent.run_sync(
+    None,
+    message_history=load(thread_id),
+    deferred_tool_results=DeferredToolResults(
+        approvals={question_id: ToolApproved() if approved else ToolDenied(str(answer))},
+        metadata={question_id: answer},
+    ),
+)
+store(thread_id, result.all_messages())  # before acknowledging the answer message
+```
+
+Two rules the framework leaves to you: name the `RunContext` parameter `ctx`, and store
+the post-run history *before* you acknowledge an answer — a duplicate answer is refused
+only if the history you pass already holds the tool's return. `requires_approval=True`
+tools and `CallDeferred` calls (a job handed to an external system) are published too,
+with the default policy.
+
 ## Async mode — the thread does not park
 
 ```python
-from agent_wait_aws import DynamoDbAnnounce, SnsAnnounce
+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: ...
 ```
 
@@ -165,7 +230,7 @@ question; the `DynamoDbAnnounce` row (or whatever you keep) is the only record.
 ```
 
 `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/).
@@ -191,8 +256,8 @@ class RedisAnnounce(BaseAnnounce):
 
 A raise inside `deliver()` becomes a log line; the run completes.
 
-Shipped: `WebhookAnnounce` (signed JSON POST, stdlib), `LogAnnounce`, `InMemoryAnnounce`,
-and in `agent-wait-aws`: `SnsAnnounce`, `SqsAnnounce`, `EventBridgeAnnounce`,
+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/).
@@ -208,7 +273,7 @@ Your own: [Writing an announcer](https://skamalj.github.io/agent-wait/writing-an
 ## 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
@@ -219,12 +284,22 @@ 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, written for 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.pydantic_ai  [pydantic-ai]  the same two names bound to Pydantic AI's deferred tools.
+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` and `agent_wait.pydantic_ai` are implementors of it,
+about fifty lines each. Announcers are the same split: `BaseAnnounce` is the interface,
+each provider subpackage the implementors. 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.1 → agent_wait-0.6.0}/README.md

@@ -5,32 +5,42 @@
 [![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; Pydantic AI has `ApprovalRequired`. In both, the
+run pauses and the question is handed to whatever called it — and that is where the
+framework 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[pydantic-ai]"      # the same two names for Pydantic AI
+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 agent_wait.langgraph import wait
 from langchain_core.tools import tool
-from langgraph_wait import hitl
 
 FINANCE = WaitPolicy(
     timeout="P3D",
@@ -41,7 +51,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"
@@ -61,23 +71,24 @@ none is enforced — the consumer acts on them:
 | `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 — `@hitl(FINANCE, decision="verdict")` looks for `verdict`.
+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)])
@@ -105,14 +116,58 @@ 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.
 
+## The same two names on Pydantic AI
+
+```python
+from agent_wait.pydantic_ai import publish_interrupts, wait
+from pydantic_ai import Agent, DeferredToolRequests, DeferredToolResults, RunContext, ToolApproved, ToolDenied
+
+agent = Agent("openai:gpt-5.4", output_type=[str, DeferredToolRequests])
+
+
+@agent.tool
+@wait(FINANCE)
+def issue_refund(ctx: RunContext[None], order_id: str, amount: int) -> str:
+    payments.refund(order_id, amount)
+    return "refunded"
+
+
+result = agent.run_sync("refund order 4471", message_history=history)
+publish_interrupts(result, thread_id, announce=[SnsAnnounce(topic_arn)])
+store(thread_id, result.all_messages())  # Pydantic AI has no checkpointer; the history is yours
+```
+
+The run ends with `DeferredToolRequests` in `result.output`; `question_id` is the
+`tool_call_id`. The answer goes back through the framework's own resume, with the answer
+itself riding in `metadata` so the `@wait` rules apply unchanged:
+
+```python
+approved = answer.get("action") == "approve"
+result = agent.run_sync(
+    None,
+    message_history=load(thread_id),
+    deferred_tool_results=DeferredToolResults(
+        approvals={question_id: ToolApproved() if approved else ToolDenied(str(answer))},
+        metadata={question_id: answer},
+    ),
+)
+store(thread_id, result.all_messages())  # before acknowledging the answer message
+```
+
+Two rules the framework leaves to you: name the `RunContext` parameter `ctx`, and store
+the post-run history *before* you acknowledge an answer — a duplicate answer is refused
+only if the history you pass already holds the tool's return. `requires_approval=True`
+tools and `CallDeferred` calls (a job handed to an external system) are published too,
+with the default policy.
+
 ## Async mode — the thread does not park
 
 ```python
-from agent_wait_aws import DynamoDbAnnounce, SnsAnnounce
+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: ...
 ```
 
@@ -141,7 +196,7 @@ question; the `DynamoDbAnnounce` row (or whatever you keep) is the only record.
 ```
 
 `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/).
@@ -167,8 +222,8 @@ class RedisAnnounce(BaseAnnounce):
 
 A raise inside `deliver()` becomes a log line; the run completes.
 
-Shipped: `WebhookAnnounce` (signed JSON POST, stdlib), `LogAnnounce`, `InMemoryAnnounce`,
-and in `agent-wait-aws`: `SnsAnnounce`, `SqsAnnounce`, `EventBridgeAnnounce`,
+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/).
@@ -184,7 +239,7 @@ Your own: [Writing an announcer](https://skamalj.github.io/agent-wait/writing-an
 ## 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
@@ -195,12 +250,22 @@ 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, written for 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.pydantic_ai  [pydantic-ai]  the same two names bound to Pydantic AI's deferred tools.
+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` and `agent_wait.pydantic_ai` are implementors of it,
+about fifty lines each. Announcers are the same split: `BaseAnnounce` is the interface,
+each provider subpackage the implementors. 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.6.0/pyproject.toml

@@ -0,0 +1,111 @@
+[project]
+name = "agent-wait"
+version = "0.6.0"
+description = "Human-in-the-loop for LangGraph and Pydantic AI 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",
+    "pydantic-ai",
+    "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"]
+pydantic-ai = ["pydantic-ai-slim>=2.43,<3"]
+aws = ["boto3>=1.35"]
+all = ["agent-wait[langgraph,pydantic-ai,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.6.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