agent-wait 0.2.0__py3-none-any.whl

agent_wait/__init__.py

@@ -0,0 +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/announce/__init__.py

@@ -0,0 +1,16 @@
+from .base import AnnounceAdapter, BaseAnnounce
+from .composite import CompositeAnnounce
+from .log import LogAnnounce
+from .memory import FailingAnnounce, InMemoryAnnounce
+from .webhook import WebhookAnnounce, verify_signature
+
+__all__ = [
+    "AnnounceAdapter",
+    "BaseAnnounce",
+    "CompositeAnnounce",
+    "FailingAnnounce",
+    "InMemoryAnnounce",
+    "LogAnnounce",
+    "WebhookAnnounce",
+    "verify_signature",
+]

agent_wait/announce/base.py

@@ -0,0 +1,98 @@
+"""The announce port: a `Protocol` to satisfy, and a base class that satisfies it for you.
+
+An announce adapter puts the envelope somewhere. That is all it does. It makes no
+decisions, it is never consulted, and its return value is discarded. The contract is one
+line long:
+
+    **`announce()` must not raise into the caller.**
+
+If Slack is down, the graph still parked and the run still completes.
+
+## Writing one
+
+Subclass `BaseAnnounce` and implement `deliver()`:
+
+    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())
+
+That is a complete, contract-conforming adapter. The base class wraps `deliver()` so an
+exception becomes a log line rather than a failed run, and gives you `only=` so a caller
+can restrict the adapter to `("created",)` without you writing the filter.
+
+You do not *have* to subclass. `AnnounceAdapter` is a `Protocol`: any object with `name`,
+`supports()` and `announce()` is accepted, and `CompositeAnnounce` contains its failures
+either way. The base class exists so that the common case is the correct case by default.
+
+## Anything can be an announcer
+
+Nothing reads state back through this library, so "announce" does not mean "publish an
+event". It means *put the question where whoever answers it will find it*.
+That can be a topic, a queue, a bus -- or a DynamoDB table, a Redis key, a Postgres row,
+a database your UI already queries, a file on disk. `DynamoDbAnnounce` in
+`agent-wait-aws` is there to make the point.
+
+`supports()` lets an adapter opt out cheaply: a UI that only wants to draw new questions
+takes `only=("created",)`. Most adapters want both -- `created` is "draw the button",
+`resumed` is "retract it".
+"""
+
+from __future__ import annotations
+
+import logging
+from abc import ABC, abstractmethod
+from typing import Protocol, runtime_checkable
+
+from ..model import Transition, WaitEnvelope
+
+
+@runtime_checkable
+class AnnounceAdapter(Protocol):
+    """What `WaitPublisher` accepts. Structural: subclassing is not required."""
+
+    name: str
+
+    def announce(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        """Fire-and-forget. Log failures; never raise."""
+        ...
+
+    def supports(self, transition: Transition) -> bool:
+        """Which transitions this adapter wants. Called before every announce."""
+        ...
+
+
+class BaseAnnounce(ABC):
+    """Implements the contract once. Subclasses implement `deliver()` and nothing else.
+
+    `name` is used in log lines and should be set as a class attribute.
+    """
+
+    name: str = "base"
+
+    def __init__(self, *, only: tuple[Transition, ...] | None = None) -> None:
+        self._only = only
+        self._log = logging.getLogger(f"agent_wait.announce.{self.name}")
+
+    def supports(self, transition: Transition) -> bool:
+        return self._only is None or transition in self._only
+
+    def announce(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        """The contract, enforced. Do not override this; override `deliver()`."""
+        try:
+            self.deliver(envelope, transition)
+        except Exception:
+            # A backend being unreachable must not fail a run that has already parked.
+            self._log.exception(
+                "%s failed for interrupt %s (%s)", type(self).__name__, envelope.interrupt_id, transition
+            )
+
+    @abstractmethod
+    def deliver(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        """Put the envelope where it goes. Raise freely; the base class contains it."""
+        ...

agent_wait/announce/composite.py

@@ -0,0 +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,
+                )

agent_wait/announce/log.py

@@ -0,0 +1,47 @@
+"""`LogAnnounce` -- a structured log line per transition. The default in tests.
+
+Deliberately careful about what it prints. The question may hold anything the agent was
+working on -- a customer's address, the body of a claim -- so it does not go to INFO
+(CLAUDE.md). At DEBUG it is included, because by then someone has opted in.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+
+from ..model import Transition, WaitEnvelope
+from .base import BaseAnnounce
+
+
+class LogAnnounce(BaseAnnounce):
+    name = "log"
+
+    def __init__(
+        self,
+        logger: logging.Logger | None = None,
+        *,
+        level: int = logging.INFO,
+        only: tuple[Transition, ...] | None = None,
+    ) -> None:
+        super().__init__(only=only)
+        self._out = logger or logging.getLogger("agent_wait.announce")
+        self._level = level
+
+    def deliver(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        record = {
+            "event": envelope.type,
+            "event_id": envelope.event_id,
+            "thread_id": envelope.thread_id,
+            "interrupt_id": envelope.interrupt_id,
+            "allowed_actions": list(envelope.allowed_actions),
+            "expires_at": envelope.expires_at,
+            "tags": dict(envelope.tags),
+        }
+        self._out.log(self._level, "agent-wait %s", json.dumps(record, default=str))
+        if self._out.isEnabledFor(logging.DEBUG):
+            self._out.debug(
+                "agent-wait question for %s: %s",
+                envelope.interrupt_id,
+                json.dumps(envelope.question, default=str),
+            )

agent_wait/announce/memory.py

@@ -0,0 +1,51 @@
+"""`InMemoryAnnounce` -- collects envelopes so tests can assert on what the world saw.
+
+`FailingAnnounce` raises on demand, so the suite can check the run is unharmed and the
+other adapters still got their envelope.
+"""
+
+from __future__ import annotations
+
+from ..model import Transition, WaitEnvelope
+from .base import BaseAnnounce
+
+
+class InMemoryAnnounce(BaseAnnounce):
+    name = "memory"
+
+    def __init__(self, *, only: tuple[Transition, ...] | None = None) -> None:
+        super().__init__(only=only)
+        self.events: list[tuple[Transition, WaitEnvelope]] = []
+
+    def deliver(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        self.events.append((transition, envelope))
+
+    # -- test helpers --------------------------------------------------------
+    def of(self, transition: Transition) -> list[WaitEnvelope]:
+        return [e for t, e in self.events if t == transition]
+
+    def transitions(self) -> list[Transition]:
+        return [t for t, _ in self.events]
+
+    def last(self) -> WaitEnvelope | None:
+        return self.events[-1][1] if self.events else None
+
+    def clear(self) -> None:
+        self.events.clear()
+
+
+class FailingAnnounce:
+    """Raises on every announce. Used to prove the isolation in `CompositeAnnounce`."""
+
+    name = "failing"
+
+    def __init__(self, message: str = "announce backend is down") -> None:
+        self.calls = 0
+        self._message = message
+
+    def supports(self, transition: Transition) -> bool:
+        return True
+
+    def announce(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        self.calls += 1
+        raise RuntimeError(self._message)

agent_wait/announce/webhook.py

@@ -0,0 +1,99 @@
+"""`WebhookAnnounce` -- POST the envelope to a URL.
+
+    announce=[WebhookAnnounce("https://approvals.internal/hooks/agent-wait",
+                              secret=b"shared-with-the-receiver")]
+
+Stdlib only, so it lives in the core package with no new dependency. One POST per
+transition, JSON body, three headers a receiver can route or verify on:
+
+    Content-Type:              application/json
+    X-Agent-Wait-Event:        wait.created | wait.resumed
+    X-Agent-Wait-Dedupe-Key:   wait.created:<interrupt_id>
+    X-Agent-Wait-Signature:    sha256=<hex>          (only when `secret` is given)
+
+## Signing
+
+The signature is `HMAC-SHA256(secret, raw body)`, hex-encoded, in the same shape GitHub
+and Stripe use. It answers one question for the receiver -- *did this come from the
+agent?* -- and nothing else. It is not a credential for answering; the library has no
+inbound path and nothing here creates one. `verify_signature()` is the
+receiver's half, and is a pure function so it can be copied into a service that does not
+install this package.
+
+## Failure
+
+A non-2xx response raises, and `BaseAnnounce` turns that into a log line: the graph that
+just parked stays parked. There is no retry -- `republish()` is the retry, same as every
+other adapter -- so a receiver that was down gets the question again the next time the
+thread is re-invoked, with the same dedupe key.
+
+The timeout is deliberately short. This runs inside the agent's own invocation, after the
+graph has already done its work; a slow receiver must not turn a two-second run into a
+thirty-second one.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+
+from ..model import Transition, WaitEnvelope
+from .base import BaseAnnounce
+
+SIGNATURE_HEADER = "X-Agent-Wait-Signature"
+EVENT_HEADER = "X-Agent-Wait-Event"
+DEDUPE_HEADER = "X-Agent-Wait-Dedupe-Key"
+
+
+def sign(secret: bytes, body: bytes) -> str:
+    return "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()
+
+
+def verify_signature(secret: bytes, body: bytes, header: str | None) -> bool:
+    """The receiver's half. Constant-time; a missing or malformed header is False."""
+    if not header:
+        return False
+    return hmac.compare_digest(sign(secret, body), header)
+
+
+class WebhookAnnounce(BaseAnnounce):
+    name = "webhook"
+
+    def __init__(
+        self,
+        url: str,
+        *,
+        secret: bytes | None = None,
+        headers: Mapping[str, str] | None = None,
+        timeout: float = 5.0,
+        only: tuple[Transition, ...] | None = None,
+    ) -> None:
+        super().__init__(only=only)
+        self.url = url
+        self._secret = secret
+        self._headers = dict(headers or {})
+        self._timeout = timeout
+
+    def deliver(self, envelope: WaitEnvelope, transition: Transition) -> None:
+        body = envelope.to_json().encode("utf-8")
+        headers = {
+            **self._headers,
+            "Content-Type": "application/json",
+            EVENT_HEADER: envelope.type,
+            DEDUPE_HEADER: envelope.dedupe_key,
+        }
+        if self._secret is not None:
+            headers[SIGNATURE_HEADER] = sign(self._secret, body)
+
+        request = urllib.request.Request(self.url, data=body, headers=headers, method="POST")
+        try:
+            with urllib.request.urlopen(request, timeout=self._timeout) as response:
+                status = response.status
+        except urllib.error.HTTPError as err:
+            # A 4xx/5xx is an HTTPError in urllib; make the log line say the status.
+            raise RuntimeError(f"webhook {self.url} returned {err.code}") from err
+        if not 200 <= status < 300:  # pragma: no cover - urllib raises for these
+            raise RuntimeError(f"webhook {self.url} returned {status}")

agent_wait/errors.py

@@ -0,0 +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.
+    """

agent_wait/model.py

@@ -0,0 +1,179 @@
+"""The data that crosses the boundary: what comes out of a run, and what goes out to
+the world.
+
+`WaitEnvelope` is the contract. Everything else in this repository is an implementation
+detail; that one is not. It is specified in `docs/message-formats.md`, and a team that
+has read only that file should be able to write a working consumer.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any, Literal, Protocol
+
+from .errors import QuestionTooLarge
+from .policy import WaitPolicy
+
+Transition = Literal["created", "resumed"]
+"""The two things that can be said about a wait.
+
+`created` -- the graph is parked on this question; here is everything needed to answer
+it. `resumed` -- the graph has moved past it; close the ticket, retract the button.
+
+There is no `answered`, `expired` or `cancelled`. Those would describe the library's
+opinion about an answer, and no answer ever reaches the library. Only the graph's own
+state is reported, and the graph knows exactly two things: parked, or not.
+"""
+
+# 256 KB is the smallest of the caps on the way out (SNS, SQS and EventBridge all sit
+# there). Leave headroom for the rest of the envelope.
+MAX_QUESTION_BYTES = 200 * 1024
+
+_CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+
+
+class Clock(Protocol):
+    def now(self) -> float: ...
+
+
+class SystemClock:
+    def now(self) -> float:
+        return time.time()
+
+
+class FakeClock:
+    """A clock tests can drive. Nothing in the library reads the wall clock directly."""
+
+    def __init__(self, start: float = 1_760_000_000.0) -> None:
+        self._now = start
+
+    def now(self) -> float:
+        return self._now
+
+    def advance(self, seconds: float) -> None:
+        self._now += seconds
+
+
+def new_ulid(clock: Clock | None = None) -> str:
+    """A ULID: 48 bits of millisecond timestamp then 80 bits of randomness, Crockford
+    base32. Lexicographically sortable, which is what makes it useful as a key."""
+    ms = int((clock.now() if clock else time.time()) * 1000)
+    value = (ms << 80) | int.from_bytes(secrets.token_bytes(10), "big")
+    out = [""] * 26
+    for i in range(25, -1, -1):
+        out[i] = _CROCKFORD[value & 0x1F]
+        value >>= 5
+    return "".join(out)
+
+
+def canonical_json(obj: Any) -> str:
+    """One byte-exact rendering of a value, so a size check or a hash of it means
+    something."""
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"), default=str, ensure_ascii=False)
+
+
+def check_question_size(question: Any) -> None:
+    size = len(canonical_json(question).encode("utf-8"))
+    if size > MAX_QUESTION_BYTES:
+        raise QuestionTooLarge(
+            f"question is {size} bytes; the limit is {MAX_QUESTION_BYTES}. "
+            "Publish a reference (an id, an S3 key) and let the consumer fetch the rest."
+        )
+
+
+def iso(ts: float | None) -> str | None:
+    if ts is None:
+        return None
+    return time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime(ts))
+
+
+def _no_str_map() -> dict[str, str]:
+    """A typed factory: a bare `dict` leaves the field's value type unknown."""
+    return {}
+
+
+@dataclass(frozen=True)
+class EntryPoint:
+    """Where the agent listens, if you want consumers told.
+
+    Optional. agent-wait builds no return leg, so it never needs this itself; it is
+    published as `reply_to` purely as a hint, so that a consumer you write does not have
+    to hardcode an address that differs between environments."""
+
+    kind: Literal["sqs", "lambda", "http"]
+    address: str
+
+    def to_dict(self) -> dict[str, str]:
+        key = {"sqs": "url", "lambda": "arn", "http": "url"}[self.kind]
+        return {"kind": self.kind, key: self.address}
+
+
+@dataclass(frozen=True)
+class PendingInterrupt:
+    """One question a thread is parked on. What a `FrameworkAdapter` hands back."""
+
+    interrupt_id: str
+    question: Any
+    policy: WaitPolicy
+    asked_at: float | None = None
+    """When the framework checkpointed this interrupt, if it can say.
+
+    This is what `expires_at` is measured from. It has to come from the checkpoint
+    rather than from the clock at publish time, because the same question is republished
+    whenever a start message is redelivered -- and a deadline recomputed as `now +
+    timeout` on each republish would walk forward forever, which is precisely the
+    failure a timeout exists to prevent.
+    """
+
+
+@dataclass(frozen=True)
+class WaitEnvelope:
+    """The outbound contract. One per interrupt, per transition."""
+
+    type: str
+    event_id: str
+    thread_id: str
+    interrupt_id: str
+    question: Any
+    allowed_actions: tuple[str, ...]
+    expires_at: str | None
+    reply_with: Mapping[str, Any]
+    reply_to: Mapping[str, str] | None = None
+    default: Any = None
+    correlation: Mapping[str, str] | None = None
+    tags: Mapping[str, str] = field(default_factory=_no_str_map)
+
+    @property
+    def dedupe_key(self) -> str:
+        """What a consumer -- or an adapter with a natural key -- should dedupe on.
+
+        Not `event_id`: that is fresh per publish, so a redelivered start message
+        republishing the same question would look like a second question. LangGraph
+        guarantees `interrupt_id` is stable across re-entry and resume-from-checkpoint
+        (verified in `test_spike_langgraph.py`), which makes this key stable for exactly
+        as long as the question is.
+        """
+        return f"{self.type}:{self.interrupt_id}"
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "type": self.type,
+            "event_id": self.event_id,
+            "thread_id": self.thread_id,
+            "interrupt_id": self.interrupt_id,
+            "question": self.question,
+            "allowed_actions": list(self.allowed_actions),
+            "expires_at": self.expires_at,
+            "default": self.default,
+            "reply_to": dict(self.reply_to) if self.reply_to else None,
+            "reply_with": dict(self.reply_with),
+            "correlation": dict(self.correlation) if self.correlation else None,
+            "tags": dict(self.tags),
+        }
+
+    def to_json(self) -> str:
+        return json.dumps(self.to_dict(), default=str, ensure_ascii=False)

agent_wait/policy.py

@@ -0,0 +1,122 @@
+"""`WaitPolicy` -- what the author of an interrupt declares about the wait.
+
+Every field here is **advisory**. agent-wait publishes the policy and does nothing else
+with it: it does not enforce the timeout, apply the default, or reject a disallowed
+action. It cannot -- the library never sees the answer.
+
+What these fields buy you is that the *world* is told the rules in a machine-readable
+way, on the same envelope as the question, so whatever does the enforcing has what it
+needs:
+
+* `timeout` becomes `expires_at` -- an absolute instant, so a scheduler, a cron sweep or
+  a UI countdown can act on it without re-parsing a duration;
+* `allowed_actions` tells a UI which buttons to draw;
+* `default` tells whoever enforces the timeout what to send when it fires;
+* `tags` become SNS message attributes, so filter policies can route on them.
+
+The policy rides inside the interrupt value under the `__wait__` key, because that is the
+only channel a framework interrupt gives us, so it must round-trip through JSON.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from .errors import PolicyError
+
+# ISO-8601 durations, restricted to the parts that make sense for a wait. Years and
+# months are refused on purpose: they are not fixed-length, so "P1M" cannot be turned
+# into the definite instant that `expires_at` promises to be.
+_ISO_DURATION = re.compile(
+    r"^P(?!$)(?:(?P<weeks>\d+(?:\.\d+)?)W)?(?:(?P<days>\d+(?:\.\d+)?)D)?"
+    r"(?:T(?!$)(?:(?P<hours>\d+(?:\.\d+)?)H)?(?:(?P<minutes>\d+(?:\.\d+)?)M)?"
+    r"(?:(?P<seconds>\d+(?:\.\d+)?)S)?)?$"
+)
+
+_UNIT_SECONDS = {
+    "weeks": 604800.0,
+    "days": 86400.0,
+    "hours": 3600.0,
+    "minutes": 60.0,
+    "seconds": 1.0,
+}
+
+
+def _no_tags() -> dict[str, str]:
+    """A typed factory: a bare `dict` leaves the field's value type unknown."""
+    return {}
+
+
+def parse_duration(value: str | int | float | None) -> float | None:
+    """Return seconds for an ISO-8601 duration string, a number, or None.
+
+    >>> parse_duration("P3D")
+    259200.0
+    >>> parse_duration("PT2H30M")
+    9000.0
+    """
+    if value is None:
+        return None
+    if isinstance(value, bool):  # bool is an int subclass; almost certainly a mistake
+        raise PolicyError(f"timeout must be a duration, got {value!r}")
+    if isinstance(value, int | float):
+        if value <= 0:
+            raise PolicyError(f"timeout must be positive, got {value!r}")
+        return float(value)
+    match = _ISO_DURATION.match(value.strip().upper())
+    if match is None:
+        raise PolicyError(
+            f"unparseable timeout {value!r}: expected seconds or an ISO-8601 duration "
+            "such as 'P3D' or 'PT2H30M' (years and months are not accepted)"
+        )
+    total = sum(_UNIT_SECONDS[k] * float(v) for k, v in match.groupdict().items() if v is not None)
+    if total <= 0:
+        raise PolicyError(f"timeout must be positive, got {value!r}")
+    return total
+
+
+@dataclass(frozen=True)
+class WaitPolicy:
+    """Declared at the interrupt site, by whoever asked the question. All advisory."""
+
+    timeout: str | int | None = None
+    default: Any = None
+    allowed_actions: tuple[str, ...] = ("resume",)
+    tags: Mapping[str, str] = field(default_factory=_no_tags)
+    correlation: Mapping[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        # Fail here, in the graph, at the line that got it wrong -- not three days later
+        # in whatever consumer tried to read `expires_at`.
+        parse_duration(self.timeout)
+        if not self.allowed_actions:
+            raise PolicyError("allowed_actions must not be empty")
+
+    @property
+    def timeout_seconds(self) -> float | None:
+        return parse_duration(self.timeout)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "timeout": self.timeout,
+            "default": self.default,
+            "allowed_actions": list(self.allowed_actions),
+            "tags": dict(self.tags),
+            "correlation": dict(self.correlation) if self.correlation is not None else None,
+        }
+
+    @classmethod
+    def from_dict(cls, data: Mapping[str, Any] | None) -> WaitPolicy:
+        if not data:
+            return cls()
+        correlation = data.get("correlation")
+        return cls(
+            timeout=data.get("timeout"),
+            default=data.get("default"),
+            allowed_actions=tuple(data.get("allowed_actions") or ("resume",)),
+            tags=dict(data.get("tags") or {}),
+            correlation=dict(correlation) if correlation else None,
+        )

agent_wait/publisher.py

@@ -0,0 +1,204 @@
+"""`WaitPublisher` -- run the graph, and tell the world about anything it parked on.
+
+That is the entire library. There is one call:
+
+    agent.invoke(payload, thread_id="order-4471")
+
+It runs the graph, works out which questions opened and which closed, and publishes an
+envelope for each. Nothing else happens: no store, no tokens, no timers, no inbound
+message handling. Whoever receives the envelope decides what to do with it, and calls
+`invoke()` again with the answer.
+
+## How "opened" and "closed" are worked out
+
+By diffing the framework's own state, not by tracking anything ourselves:
+
+    before = {what the thread was parked on}
+    result = graph.invoke(...)
+    after  = {what the thread is parked on now}
+
+    created = after - before      # new questions
+    resumed = before - after      # questions the graph has moved past
+
+Two `get_state()` reads per invoke, and the framework stays the only source of truth.
+
+## Recovering a lost announce
+
+If the process dies between the invoke and the announce, the graph is parked and nobody
+was told. `republish()` is the repair: it publishes `created` for whatever the thread is
+parked on right now, with the same interrupt ids and therefore the same `dedupe_key`, so
+a consumer that already saw the question discards it.
+
+The caller has to know when to use it, and the rule is short enough to inline:
+
+    if agent.pending(thread_id):   # a redelivered start for a thread already parked
+        agent.republish(thread_id)
+    else:
+        agent.invoke(message["input"], thread_id)
+
+**Do not re-invoke a parked thread with its original input.** LangGraph will treat it as
+a fresh turn, ask the question a second time, and give it a new interrupt id -- so the
+consumer sees two questions and the deduplication that repairs everything else cannot
+help. This is the one rule the caller has to remember, and it is why `pending()` is part
+of the public surface.
+
+## What happens if the graph raises
+
+The exception propagates and nothing is published, because nothing is known: a run that
+raised has not necessarily parked or unparked anything. There is no bookkeeping left
+half-done, which is the advantage of keeping none.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from typing import Any, Protocol, runtime_checkable
+
+from .announce.base import AnnounceAdapter
+from .announce.composite import CompositeAnnounce
+from .model import (
+    Clock,
+    EntryPoint,
+    PendingInterrupt,
+    SystemClock,
+    Transition,
+    WaitEnvelope,
+    iso,
+    new_ulid,
+)
+
+_log = logging.getLogger("agent_wait.publisher")
+
+
+@runtime_checkable
+class FrameworkAdapter(Protocol):
+    """Everything framework-specific, in three methods.
+
+    `langgraph_wait.LangGraphAdapter` is the one implementation; the protocol exists so
+    the core can be tested without LangGraph and so a second framework is a day's work
+    rather than a fork.
+    """
+
+    name: str
+
+    def config_for(self, thread_id: str) -> dict[str, Any]:
+        """The framework's handle for one conversation."""
+        ...
+
+    def invoke(self, value: Any, config: Any) -> Any:
+        """Run the graph. `value` is whatever the caller passed -- fresh input on a
+        start, a resume command on an answer. The adapter does not inspect it."""
+        ...
+
+    def pending(self, thread_id: str) -> list[PendingInterrupt]:
+        """What this thread is parked on *right now*, read from the checkpoint.
+
+        Must return `[]` for a thread that has never run. Must not over-report: an
+        interrupt the graph has already moved past does not belong here, however the
+        framework's own API chooses to report it.
+        """
+        ...
+
+
+class WaitPublisher:
+    """Wraps a graph. Runs it, and publishes what it parks on."""
+
+    def __init__(
+        self,
+        adapter: FrameworkAdapter,
+        *,
+        announce: Sequence[AnnounceAdapter],
+        reply_to: EntryPoint | None = None,
+        clock: Clock | None = None,
+    ) -> None:
+        """`reply_to` is a hint for consumers, and nothing more.
+
+        This library builds no return leg. It does not listen anywhere, does not receive
+        answers and does not verify them -- so it has no need to know where the agent
+        lives. If you *do* build a return leg and want the envelope to tell consumers
+        where it is, pass an `EntryPoint` and it is published verbatim. Leave it out and
+        `reply_to` is `null`, which is fine for any consumer that already knows.
+        """
+        self.adapter = adapter
+        self.announce = CompositeAnnounce(announce)
+        self.reply_to = reply_to
+        self.clock: Clock = clock or SystemClock()
+
+    # ------------------------------------------------------------------ the one call
+    def invoke(self, value: Any, thread_id: str, *, config: Any = None) -> Any:
+        """Run the graph for `thread_id` and publish whatever changed.
+
+        Returns the framework's own result, unchanged -- the wrapper is not a filter.
+        """
+        resolved = config if config is not None else self.adapter.config_for(thread_id)
+
+        before = {p.interrupt_id: p for p in self.adapter.pending(thread_id)}
+        result = self.adapter.invoke(value, resolved)
+        after = {p.interrupt_id: p for p in self.adapter.pending(thread_id)}
+
+        for interrupt_id, opened in after.items():
+            if interrupt_id not in before:
+                self._publish(thread_id, opened, "created")
+        for interrupt_id, closed in before.items():
+            if interrupt_id not in after:
+                self._publish(thread_id, closed, "resumed")
+
+        return result
+
+    def republish(self, thread_id: str) -> list[PendingInterrupt]:
+        """Announce `created` again for everything this thread is parked on.
+
+        The repair for an announce that was lost -- a crash before it went out, a broker
+        that was down, an adapter added after the question was asked. Safe to call at any
+        time and as often as you like: the interrupt ids are stable, so every republish
+        carries the same `dedupe_key` and a consumer that already has the question
+        discards it.
+
+        Runs the graph not at all.
+        """
+        parked = self.adapter.pending(thread_id)
+        for interrupt in parked:
+            self._publish(thread_id, interrupt, "created")
+        return parked
+
+    # ------------------------------------------------------------------ reading back
+    def pending(self, thread_id: str) -> list[PendingInterrupt]:
+        """What this thread is parked on. Read-only; publishes nothing.
+
+        This is the answer to "is this answer I just received still live, or did
+        somebody beat me to it?" -- which is the caller's question, and this is the tool
+        for it.
+        """
+        return self.adapter.pending(thread_id)
+
+    # ------------------------------------------------------------------ the envelope
+    def envelope_for(
+        self, thread_id: str, interrupt: PendingInterrupt, transition: Transition
+    ) -> WaitEnvelope:
+        policy = interrupt.policy
+        timeout = policy.timeout_seconds
+        # Anchored to the checkpoint, not to now -- see `PendingInterrupt.asked_at`.
+        asked_at = interrupt.asked_at if interrupt.asked_at is not None else self.clock.now()
+        return WaitEnvelope(
+            type=f"wait.{transition}",
+            event_id=new_ulid(self.clock),
+            thread_id=thread_id,
+            interrupt_id=interrupt.interrupt_id,
+            question=interrupt.question,
+            allowed_actions=policy.allowed_actions,
+            expires_at=iso(asked_at + timeout) if timeout else None,
+            reply_to=self.reply_to.to_dict() if self.reply_to is not None else None,
+            # A filled-in stub, not a description of one. The consumer replaces `answer`
+            # and posts this back to `reply_to`; the presence of `interrupt_id` is what
+            # makes it a resume rather than a start.
+            reply_with={"thread_id": thread_id, "interrupt_id": interrupt.interrupt_id, "answer": None},
+            default=policy.default,
+            correlation=policy.correlation,
+            tags=policy.tags,
+        )
+
+    def _publish(self, thread_id: str, interrupt: PendingInterrupt, transition: Transition) -> None:
+        envelope = self.envelope_for(thread_id, interrupt, transition)
+        _log.debug("publishing %s for %s", envelope.type, envelope.interrupt_id)
+        self.announce.announce(envelope, transition)

agent_wait-0.2.0.dist-info/METADATA

@@ -0,0 +1,224 @@
+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.
+Project-URL: Homepage, https://skamalj.github.io/agent-wait/
+Project-URL: Documentation, https://skamalj.github.io/agent-wait/
+Project-URL: Source, https://github.com/skamalj/agent-wait
+Project-URL: Issues, https://github.com/skamalj/agent-wait/issues
+Project-URL: Changelog, https://github.com/skamalj/agent-wait/blob/main/CHANGELOG.md
+Author-email: Kamaljeet Singh <skamalj@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,approval,durable,human-in-the-loop,interrupt,langgraph,serverless
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# agent-wait
+
+[![PyPI](https://img.shields.io/pypi/v/agent-wait.svg)](https://pypi.org/project/agent-wait/)
+[![CI](https://github.com/skamalj/agent-wait/actions/workflows/ci.yml/badge.svg)](https://github.com/skamalj/agent-wait/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/skamalj/agent-wait/blob/main/LICENSE)
+
+**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-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+agent_wait/__init__.py,sha256=scwphyvw1JsdLN4hO7KLIy2Fx7A4-0KBqKQf6OaneAc,2083
+agent_wait/errors.py,sha256=WmVd41xAjEw_2DuAUWNzkCwqlS9lT2cBgCTlomuZy-Q,981
+agent_wait/model.py,sha256=AWYJcJFRvjg098_maM1Syd1BvhpInl6ldZLH8eHEPdo,6419
+agent_wait/policy.py,sha256=CH9hZMl4-Q8f_FXvCDh5Wohl22kBG9W02CZfIL1NZ2U,4736
+agent_wait/publisher.py,sha256=SD1Kmnn06LbjN94kh3fDKO57XwlLQOSvxEltYhR6cu0,8726
+agent_wait/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+agent_wait/announce/__init__.py,sha256=t_4Cl9KkswbYqnEZ9vD1Qsu6d9W23TRpnUBqPqeY1t8,439
+agent_wait/announce/base.py,sha256=tqPaWOqn0rNPLqNqSiTuP87-8pVmy9phCY5MeCjBDps,3833
+agent_wait/announce/composite.py,sha256=KdCTMkYG62ZwBqTMHDDSqSKIkVCEXp26A77enIIhfxo,1792
+agent_wait/announce/log.py,sha256=GRqVd3R0AIa_xvqKmpMhdRQq8KLaW__doSiF-_YauFg,1663
+agent_wait/announce/memory.py,sha256=0rqc4zmGSV3oTYQ-mtUcGs29vJf96cdFZNFcSbAAexE,1703
+agent_wait/announce/webhook.py,sha256=GCgRh1WCKSvL3Dna3R5Yn1f1k_Irqhv-pidNp3vdQx8,3910
+agent_wait-0.2.0.dist-info/METADATA,sha256=RwA8-i5gADmuwfcAiueEbqGz-DcuRHNDjBb7dkhDU84,9594
+agent_wait-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+agent_wait-0.2.0.dist-info/licenses/LICENSE,sha256=TQBglRUWN92LKHbaB4t4LAIMXrGtBPV24oXNLMIIVlg,1072
+agent_wait-0.2.0.dist-info/RECORD,,

agent_wait-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

agent_wait-0.2.0.dist-info/licenses/LICENSE

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