agentconnect-cli 0.1.0a1__py3-none-any.whl

agentconnect/daemon/__init__.py

@@ -0,0 +1,41 @@
+"""``agentconnectd``: the separate-daemon host of the runtime (ADR-005).
+
+It reads the configuration, registers the adapters the configuration names
+(:func:`agentconnect.adapters.build_adapters`), runs one
+:class:`~agentconnect.runtime.Runtime` until SIGINT or SIGTERM, and stops
+it. Everything else, every check included, is the runtime's.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import signal
+
+from agentconnect.adapters import build_adapters
+from agentconnect.runtime import Config, Runtime, SystemClock
+
+SIGNALS = (signal.SIGINT, signal.SIGTERM)
+
+
+async def serve(config: Config, ready: asyncio.Event | None = None) -> None:
+    """Run the daemon until a signal (or cancellation); ``ready`` is set
+    once the runtime and its local API are up. Logging is the caller's
+    (``agentconnect.log.configure``)."""
+    clock = SystemClock()
+    runtime = Runtime(config, adapters=build_adapters(config, clock), clock=clock)
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    await runtime.start()
+    try:
+        for sig in SIGNALS:
+            with contextlib.suppress(NotImplementedError):
+                loop.add_signal_handler(sig, stop.set)
+        if ready is not None:
+            ready.set()
+        await stop.wait()
+    finally:
+        for sig in SIGNALS:
+            with contextlib.suppress(NotImplementedError):
+                loop.remove_signal_handler(sig)
+        await runtime.stop()

agentconnect/deliveries.py

@@ -0,0 +1,295 @@
+"""The delivery queue: messages kept until an agent tool takes them.
+
+The MCP host (``agentconnect mcp``, ADR-005) registers it as the ``mcp``
+adapter. An MCP client pulls: the model calls a tool that waits for
+messages. So the adapter doesn't push anything. It keeps each delivery in
+the runtime's encrypted database until a tool call has returned it, and
+answers the runtime ``ACK`` at once, so the relay can drop its copy.
+
+* **Durable.** A queued message survives a restart; one that no tool call
+  returned before the session ended is returned by the next one. The queue
+  keeps the newest 10 000.
+* **At least once, deduplicated.** A delivery the runtime hands over again
+  after a crash has the same key (``["msg", group, sender, msg_id]``, the
+  embedded SDK's key): it isn't queued twice, and once a tool call returned
+  it, the key is in the runtime's handled ids (:attr:`Runtime.handled`'s
+  table), so a later repeat is dropped.
+* **Leases.** :meth:`DeliveryQueue.take` leases what it returns for
+  :data:`LEASE_SECS` under a lease token; :meth:`DeliveryQueue.ack` with
+  that token takes it off the queue, and no other token can. Another waiter
+  (a second session attached through the local API) doesn't see a leased
+  message. A lease that runs out without an ack (the caller went away) puts
+  the message back; its holder may still ack it until another take leases it.
+* **Addressed first.** Each row records whether it addresses this agent, so
+  a take with ``addressed_only`` finds the oldest such row directly, however
+  many others are queued before it.
+* **Content only.** Text and task messages are queued. Agent Cards and
+  ``control.*`` messages carry no text for the model: they are acknowledged
+  and not queued (the runtime keeps the card). Events are not queued
+  either: they are in the agent's event log (``GET /v0/events``).
+
+Every queued message keeps its SPEC 10.1 framing (``untrusted``,
+``notice``, ``scope``, ``addressed_to_me``) in the payload shape of the
+webhook adapter (:mod:`agentconnect.payloads`).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import secrets
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+from typing import Any, Protocol
+
+from agentconnect.adapter import (
+    Capabilities,
+    Delivery,
+    DeliveryResult,
+    Event,
+    GroupView,
+    OutboundSend,
+    Sender,
+)
+from agentconnect.clock import Clock
+from agentconnect.payloads import message_payload
+
+ADAPTER_NAME = "mcp"
+CONTENT_KINDS = frozenset(
+    {"a2a.message", "a2a.task_status", "a2a.task_artifact", "a2a.task_cancel"}
+)
+QUEUE_KEEP = 10_000  # queued messages kept per runtime, the newest
+MAX_BATCH = 50  # messages one take returns at most
+LEASE_SECS = 120.0  # how long a taken, unacknowledged message stays hidden
+MAX_WAIT_SECS = 300.0  # the longest one take waits
+HOLDER_KEEP_SECS = 3600.0  # how long a lease's holder may still ack after it ran out
+
+
+class QueueStore(Protocol):
+    """The part of the runtime's store the queue uses."""
+
+    def adapter_event_add(
+        self,
+        adapter: str,
+        event_id: str,
+        payload: dict[str, Any],
+        keep: int = ...,
+        *,
+        addressed: bool = ...,
+    ) -> bool: ...
+    def queue_rows(  # noqa: PLR0913
+        self,
+        adapter: str,
+        *,
+        group_id: str | None,
+        skip: Sequence[int],
+        limit: int,
+        addressed: bool = ...,
+        before: int | None = ...,
+    ) -> list[tuple[int, dict[str, Any]]]: ...
+    def adapter_event_finish(self, adapter: str, seq: int) -> bool: ...
+    def handled_has(self, key: str) -> bool: ...
+
+
+def delivery_key(payload: dict[str, Any]) -> str:
+    """``["msg", group, sender, msg_id]``: each sender picks its own
+    ``msg_id`` (SPEC 8.3), so the key names the sender too, and a peer can't
+    pick an id that hides another sender's message."""
+    group, sender = payload.get("group"), payload.get("sender")
+    group_id = group.get("id") if isinstance(group, dict) else None
+    identity = sender.get("identity") if isinstance(sender, dict) else None
+    return json.dumps(["msg", group_id, identity, payload.get("msg_id")], separators=(",", ":"))
+
+
+@dataclass(frozen=True)
+class _Holder:
+    token: str
+    ends: float  # Unix seconds on the runtime's clock
+
+
+@dataclass(frozen=True)
+class Batch:
+    """What one take leased: ``lease`` acknowledges or releases it."""
+
+    lease: str
+    items: list[Taken]
+    more: bool
+
+
+@dataclass(frozen=True)
+class Taken:
+    """One leased message: ``delivery_id`` acknowledges it."""
+
+    delivery_id: int
+    payload: dict[str, Any]
+
+
+class DeliveryQueue:
+    """Implements :class:`agentconnect.adapter.Adapter`; the agent pulls with
+    :meth:`take` and confirms with :meth:`ack`."""
+
+    def __init__(self, clock: Clock, *, name: str = ADAPTER_NAME) -> None:
+        self.name = name
+        self._clock = clock
+        self._store: QueueStore | None = None
+        self._holders: dict[int, _Holder] = {}  # delivery_id -> its lease
+        self._changed = asyncio.Event()
+        self._closed = False
+        self.waiting = 0  # takes waiting now (status and tests)
+
+    def capabilities(self) -> Capabilities:
+        # The agent sends through the runtime's AgentApi, not on_outbound.
+        return Capabilities(accepts=["text", "data"], originates=False)
+
+    def bind_store(self, store: QueueStore) -> None:
+        """Called by the runtime at start with its store."""
+        self._store = store
+        self._closed = False
+
+    async def on_outbound(self, send: OutboundSend) -> None:
+        return None
+
+    def _queue(self) -> QueueStore:
+        if self._store is None:
+            msg = "the delivery queue has no store yet"
+            raise RuntimeError(msg)
+        return self._store
+
+    async def deliver(
+        self, group: GroupView, sender: Sender, to: list[str], inner: Delivery
+    ) -> DeliveryResult:
+        if inner.kind not in CONTENT_KINDS:
+            return DeliveryResult.ACK
+        store = self._queue()  # raises without a store: the runtime retries
+        payload = message_payload(group, inner)
+        key = delivery_key(payload)
+        if not store.handled_has(key) and store.adapter_event_add(
+            self.name, key, payload, QUEUE_KEEP, addressed=inner.addressed_to_me
+        ):
+            self._changed.set()
+        return DeliveryResult.ACK
+
+    async def on_event(self, group: GroupView | None, event: Event) -> None:
+        """Events are read from the agent's event log, not queued here."""
+        return None
+
+    async def close(self) -> None:
+        """Called by the runtime when it stops: waiting takes return."""
+        self._closed = True
+        self._changed.set()
+
+    def _now(self) -> float:
+        return self._clock.now().timestamp()
+
+    def _leased(self) -> list[int]:
+        """The seqs under a lease that hasn't run out. A record outlives its
+        lease (it names the last holder, who may still ack) until another
+        take leases the message again; old ones are pruned."""
+        now = self._now()
+        self._holders = {d: h for d, h in self._holders.items() if h.ends > now - HOLDER_KEEP_SECS}
+        return [d for d, h in self._holders.items() if h.ends > now]
+
+    def _pick(
+        self, group: str | None, limit: int, addressed_only: bool
+    ) -> tuple[list[tuple[int, dict[str, Any]]], bool] | None:
+        """What a take returns now (the rows and whether more are queued),
+        or ``None`` when it has to wait.
+
+        Without ``addressed_only``: the oldest ``limit`` unleased rows.
+        With it, the oldest unleased row that addresses this agent is found
+        directly, however many others are queued before it: the batch is the
+        oldest ``limit`` rows if it is among them, else that row and the
+        ``limit - 1`` rows right before it."""
+        store, skip = self._queue(), self._leased()
+        head = store.queue_rows(self.name, group_id=group, skip=skip, limit=limit + 1)
+        if not head:
+            return None
+        if not addressed_only:
+            return head[:limit], len(head) > limit
+        first = store.queue_rows(self.name, group_id=group, skip=skip, limit=1, addressed=True)
+        if not first:
+            return None
+        if any(seq == first[0][0] for seq, _ in head[:limit]):
+            return head[:limit], len(head) > limit
+        before = store.queue_rows(
+            self.name, group_id=group, skip=skip, limit=limit - 1, before=first[0][0]
+        )
+        return [*before, first[0]], True
+
+    async def take(
+        self,
+        group: str | None = None,
+        *,
+        addressed_only: bool = False,
+        wait_secs: float = 0.0,
+        limit: int = MAX_BATCH,
+        stop: asyncio.Event | None = None,
+    ) -> Batch:
+        """Wait (on the runtime's clock, at most ``wait_secs`` seconds, capped
+        at :data:`MAX_WAIT_SECS`) until a message of ``group`` (any group:
+        ``None``) is queued, or with ``addressed_only`` one that addresses
+        this agent; then lease what :meth:`_pick` chose under a new lease
+        token and return it. Nothing is leased if the caller is cancelled,
+        the runtime stops or ``stop`` is set: the batch is then empty."""
+        limit = max(1, min(limit, MAX_BATCH))
+        deadline = self._now() + max(0.0, min(wait_secs, MAX_WAIT_SECS))
+        while True:
+            self._changed.clear()  # before checking: no change is missed
+            if self._closed:
+                return Batch("", [], more=False)
+            picked = self._pick(group, limit, addressed_only)
+            if picked is not None:
+                rows, more = picked
+                holder = _Holder(secrets.token_urlsafe(16), self._now() + LEASE_SECS)
+                for seq, _ in rows:
+                    self._holders[seq] = holder
+                return Batch(holder.token, [Taken(d, p) for d, p in rows], more=more)
+            now = self._now()
+            if now >= deadline or (stop is not None and stop.is_set()):
+                return Batch("", [], more=False)
+            ends = [h.ends for h in self._holders.values() if h.ends > now]
+            await self._nap(min([deadline, *ends]), stop)
+
+    async def _nap(self, until: float, stop: asyncio.Event | None) -> None:
+        """Until something changes, ``until`` (Unix seconds on the runtime's
+        clock: the deadline or the end of a lease) or ``stop``."""
+        waits = [
+            asyncio.ensure_future(self._changed.wait()),
+            asyncio.ensure_future(self._clock.sleep_until(until, deadline=True)),
+        ]
+        if stop is not None:
+            waits.append(asyncio.ensure_future(stop.wait()))
+        self.waiting += 1
+        try:
+            await asyncio.wait(waits, return_when=asyncio.FIRST_COMPLETED)
+        finally:
+            self.waiting -= 1
+            for w in waits:
+                w.cancel()
+
+    def _held(self, lease: str, delivery_ids: Iterable[int]) -> list[int]:
+        return [
+            d
+            for d in delivery_ids
+            if lease and (h := self._holders.get(d)) is not None and h.token == lease
+        ]
+
+    def ack(self, lease: str, delivery_ids: Iterable[int]) -> list[int]:
+        """Take messages off the queue (a tool call returned them) and
+        remember their keys as handled. Only the ids ``lease`` holds, or
+        held last if nobody leased them since: an id never leased, or leased
+        again by another caller, is refused. The ids acknowledged."""
+        store = self._queue()
+        done = []
+        for delivery_id in self._held(lease, delivery_ids):
+            del self._holders[delivery_id]
+            if store.adapter_event_finish(self.name, delivery_id):
+                done.append(delivery_id)
+        return done
+
+    def release(self, lease: str, delivery_ids: Iterable[int]) -> None:
+        """End ``lease``'s hold early: the messages are queued again for any
+        waiter. Ids it doesn't hold are left alone."""
+        for delivery_id in self._held(lease, delivery_ids):
+            del self._holders[delivery_id]
+        self._changed.set()

agentconnect/directory_client.py

@@ -0,0 +1,255 @@
+"""Requests to a pinned directory (SPEC 13.2, docs/discovery.md).
+
+A :class:`DirectoryClient` talks only to the ``url`` of one configured
+``[[directory]]``, never to a URL a listing names. It follows no redirects,
+sends no compressed bodies home, caps every answer while it streams, and
+for an ``https`` directory dials only a public address its host resolved
+to, once (the guard of :mod:`agentconnect.ownerfile`). A loopback
+``http://`` directory (tests) is dialled directly.
+
+Every answer is data from a party this daemon doesn't trust: the caller
+verifies listings through the core and treats the directory's own fields
+(such as ``owner_state``) as information only.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import re
+import unicodedata
+from collections.abc import Callable
+from typing import Any
+from urllib.parse import urlsplit
+
+import httpx
+
+import agentconnect_core as ac
+from agentconnect.config import DirectoryConfig
+from agentconnect.ownerfile import (
+    REQUEST_HEADERS,
+    Resolver,
+    head_problem,
+    pinned_transport,
+    public_addresses,
+    read_capped,
+    system_resolver,
+)
+
+REQUEST_TIMEOUT_SECS = 10.0
+MAX_ANSWER_BYTES = 64 << 10  # publish and withdraw answers, and error bodies
+SUCCESS = 200
+MULTIPLE_CHOICES = 300
+TOO_MANY_REQUESTS = 429
+SERVER_ERROR = 500
+NOT_FOUND = 404
+GONE = 410
+MAX_DETAIL_CHARS = 200
+#: The codes a directory answers with (directory/README.md). Any other code,
+#: or anything that isn't a short code, becomes ``directory``: what a
+#: directory says is untrusted, and only known codes reach events, logs and
+#: the terminal.
+DIRECTORY_CODES = frozenset(
+    {
+        "bad_door",
+        "bad_listing",
+        "bad_request",
+        "bad_signature",
+        "bad_token",
+        "conflict",
+        "internal",
+        "name_held",
+        "not_found",
+        "not_vouched",
+        "owner_revoked",
+        "rate_limited",
+        "stale_seq",
+        "stale_ts",
+        "token_revoked",
+        "too_large",
+        "unavailable",
+        "unknown_key",
+        "withdrawn",
+        "wrong_directory",
+        "wrong_identity",
+        "wrong_relay",
+    }
+)
+#: The owner states of SPEC 13.2.4; any other value a directory reports is
+#: ``unknown``.
+OWNER_STATES = frozenset(
+    {"verified", "unclaimed", "stale", "failed", "revoked", "checking", "unchecked"}
+)
+_CODE = re.compile(r"^[a-z_]{1,32}$")
+# Answers that say "not now" rather than "no", and ours for no usable answer.
+TRANSIENT_CODES = frozenset(
+    {"conflict", "rate_limited", "unreachable", "timeout", "blocked", "unreadable", "redirect"}
+)
+
+
+def clean_detail(text: str) -> str:
+    """A directory's ``detail`` made safe to show: no control or format
+    characters, at most 200 characters."""
+    out = "".join("?" if unicodedata.category(c)[0] == "C" else c for c in text)
+    return out[:MAX_DETAIL_CHARS]
+
+
+def owner_state(answer: dict[str, Any]) -> str | None:
+    """The owner state a publish answer reports (information only): a known
+    state, ``unknown`` for anything else, None when there is none."""
+    value = answer.get("owner_state")
+    if value is None:
+        return None
+    return value if isinstance(value, str) and value in OWNER_STATES else "unknown"
+
+
+class DirectoryError(Exception):
+    """A refused or failed directory request: the directory's ``code`` (one of
+    :data:`DIRECTORY_CODES`, else ``directory``) or ours (``unreachable``,
+    ``timeout``, ``blocked``, ``redirect``, ``unreadable``), its HTTP
+    ``status`` (0 when there was no answer), and its cleaned ``detail`` and
+    ``kind`` when it gave them."""
+
+    def __init__(self, code: str, status: int = 0, detail: str = "", kind: str | None = None):
+        super().__init__(f"{code}: {detail}" if detail else code)
+        self.code, self.status, self.detail, self.kind = code, status, detail, kind
+
+    @property
+    def transient(self) -> bool:
+        """Whether the same request may succeed later (5xx, 429, a conflict,
+        no answer, or one that couldn't be read)."""
+        return (
+            self.status == 0
+            or self.status >= SERVER_ERROR
+            or self.status == TOO_MANY_REQUESTS
+            or self.code in TRANSIENT_CODES
+        )
+
+    @property
+    def maybe_accepted(self) -> bool:
+        """A 2xx whose body couldn't be read: the directory may have taken
+        the request, so the outcome is unknown, never a refusal."""
+        return self.code == "unreadable" and SUCCESS <= self.status < MULTIPLE_CHOICES
+
+
+class DirectoryClient:
+    """One pinned directory. ``transport`` (tests) replaces the network,
+    resolution included; ``resolver`` and ``transport_for`` replace the
+    lookup and the pinned dial."""
+
+    def __init__(
+        self,
+        entry: DirectoryConfig,
+        *,
+        transport: httpx.AsyncBaseTransport | None = None,
+        resolver: Resolver = system_resolver,
+        transport_for: Callable[[str], httpx.AsyncBaseTransport] = pinned_transport,
+    ) -> None:
+        self.entry = entry
+        self._transport = transport
+        self._resolver = resolver
+        self._transport_for = transport_for
+
+    async def publish(self, listing: bytes) -> dict[str, Any]:
+        """``POST /v0/listings``. Re-posting the same bytes is idempotent."""
+        return await self._write("/v0/listings", listing)
+
+    async def withdraw(self, withdrawal: bytes) -> dict[str, Any]:
+        """``POST /v0/withdrawals``."""
+        return await self._write("/v0/withdrawals", withdrawal)
+
+    async def fetch_listing(self, name: str) -> bytes:
+        """The exact signed bytes at ``/a/<name>.json``: ``not_found`` (404),
+        ``listing_withdrawn`` (410), else what the directory said."""
+        if not ac.is_listing_name(name):
+            raise DirectoryError("bad_request", 0, "not a listing name")
+        status, headers, body = await self._send("GET", f"/a/{name}.json", None)
+        if status == NOT_FOUND:
+            raise DirectoryError("not_found", status)
+        if status == GONE:
+            raise DirectoryError("listing_withdrawn", status)
+        if status != httpx.codes.OK:
+            raise _refusal(status, body)
+        if headers.get("content-type", "").split(";", 1)[0].strip().lower() != "application/json":
+            raise DirectoryError("unreadable", status, "not application/json")
+        return body
+
+    async def _write(self, path: str, body: bytes) -> dict[str, Any]:
+        status, _headers, answer = await self._send("POST", path, body)
+        if status not in (httpx.codes.OK, httpx.codes.CREATED):
+            raise _refusal(status, answer)
+        data = _json_object(answer)
+        if data is None:
+            raise DirectoryError("unreadable", status, "not a JSON object")
+        return data
+
+    async def _send(
+        self, method: str, path: str, body: bytes | None
+    ) -> tuple[int, httpx.Headers, bytes]:
+        cap = ac.MAX_LISTING_BYTES if method == "GET" else MAX_ANSWER_BYTES
+        try:
+            async with asyncio.timeout(REQUEST_TIMEOUT_SECS):
+                transport = await self._transport_for_request()
+                headers = dict(REQUEST_HEADERS)
+                if body is not None:
+                    headers["content-type"] = "application/json"
+                async with (
+                    httpx.AsyncClient(
+                        transport=transport,
+                        follow_redirects=False,
+                        trust_env=False,
+                        timeout=REQUEST_TIMEOUT_SECS,
+                    ) as http,
+                    http.stream(
+                        method, self.entry.url + path, content=body, headers=headers
+                    ) as resp,
+                ):
+                    problem = head_problem(resp, cap)
+                    if problem == "redirect":
+                        raise DirectoryError("redirect", resp.status_code)
+                    if problem in ("encoding", "too_large"):
+                        raise DirectoryError("unreadable", resp.status_code, problem)
+                    data = await read_capped(resp, cap)
+                    if data is None:
+                        raise DirectoryError("unreadable", resp.status_code, "too_large")
+                    return resp.status_code, resp.headers, data
+        except TimeoutError:
+            raise DirectoryError("timeout") from None
+        except (httpx.HTTPError, OSError) as e:
+            raise DirectoryError("unreachable", 0, type(e).__name__) from None
+
+    async def _transport_for_request(self) -> httpx.AsyncBaseTransport:
+        if self._transport is not None:
+            return self._transport
+        parts = urlsplit(self.entry.url)
+        host = parts.hostname or ""
+        if parts.scheme == "http":  # a loopback directory (config.py allows no other)
+            return httpx.AsyncHTTPTransport(trust_env=False)
+        addresses = await public_addresses(host, parts.port or 443, self._resolver)
+        if not addresses:
+            raise DirectoryError("blocked", 0, "the directory host has no public address")
+        return self._transport_for(addresses[0])
+
+
+def _json_object(body: bytes) -> dict[str, Any] | None:
+    try:
+        data = json.loads(body)
+    except ValueError:
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def _refusal(status: int, body: bytes) -> DirectoryError:
+    """The directory's ``{"code", "detail", "kind"?}`` as an error. A body
+    without a code is ``unreadable`` (retried); a code this daemon doesn't
+    know is ``directory``."""
+    data = _json_object(body)
+    if data is None or not isinstance(data.get("code"), str):
+        return DirectoryError("unreadable", status, "no error code")
+    code, detail, kind = data["code"], data.get("detail"), data.get("kind")
+    return DirectoryError(
+        code if _CODE.match(code) and code in DIRECTORY_CODES else "directory",
+        status,
+        clean_detail(detail) if isinstance(detail, str) else "",
+        kind if isinstance(kind, str) and _CODE.match(kind) else None,
+    )

agentconnect/failpoints.py

@@ -0,0 +1,99 @@
+"""Test-only fault injection at the daemon's step boundaries (ADR-004).
+
+Each :class:`~agentconnect.runtime.engine.Engine` has a :class:`Failpoints` set. It
+is empty unless a test arms a point, and an empty set is one falsy check per
+point, so the points are inert in production. An armed point either
+
+* **raises** :class:`FailpointError`, a transient failure the daemon
+  retries (the frame is neither recorded nor acked), or
+* **crashes**: raises :class:`SimulatedCrash`, a ``BaseException`` that no
+  handler in the daemon catches, so the worker dies on the spot as if the
+  process had been killed there; the test then restarts the daemon.
+
+The core has its own points (``Client._arm_failpoint_for_testing``). The
+names are listed in :data:`POINTS` and in TESTING.md.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+Action = Literal["raise", "crash"]
+
+#: Every daemon failpoint. ``<path>.before_core`` and ``<path>.after_core``
+#: surround the core call; ``in_tx`` is inside the daemon transaction that
+#: records the result, ``after_tx`` right after it commits, and
+#: ``after_consume`` after the core journal entry is consumed (before the
+#: relay ack). ``event.after_record`` and ``event.after_notify`` surround
+#: telling the adapter about a recorded event; ``delivery.after_adapter`` is
+#: after the adapter accepted a message, before the inbox records that.
+#: Publishing a listing (docs/discovery.md): ``door.after_register`` (the
+#: relay has the door, the daemon doesn't record it yet), ``listing.after_sign``
+#: (signed and stored, not posted) and ``listing.after_post`` (the directory
+#: accepted it, not recorded yet); ``withdraw.after_close`` is after closing
+#: the doors, before the withdrawal is sent.
+#: Knocks: ``knock.in_tx`` and ``knock.after_tx`` around the owner's record
+#: of a received knock (ledger, approval, inbox); ``knock_welcome.*`` are
+#: the knocker's join steps (as ``welcome.*``); ``knock_send.after_core``
+#: is after the core built the knock, before it is recorded and queued;
+#: ``knock_approve.after_group`` after the core created the approval's
+#: group, before it is recorded; ``knock_add.after_welcome`` after the
+#: approved knock's Welcome went out, before the approval is recorded done.
+#: Joins: ``join_request.in_tx`` and ``join_request.after_tx`` around the
+#: inviter's record of a verified JoinRequest (replay ledger, approval, inbox).
+#: Leaves: ``leave_timeout.in_tx`` and ``leave_timeout.after_tx`` around a
+#: timed-out leave's deletion of the group and its ``left`` event.
+#: A message that fails alone: ``poison.in_tx`` and ``poison.after_tx``
+#: around recording it as failed (inbox, audit row, ``message_failed``).
+PATHS = ("receive", "confirm", "welcome", "knock_welcome")
+STEPS = ("before_core", "after_core", "in_tx", "after_tx", "after_consume")
+POINTS = frozenset(
+    {f"{path}.{step}" for path in PATHS for step in STEPS}
+    | {"invite.after_register", "event.after_record", "event.after_notify"}
+    | {"held_timer.expire", "delivery.after_adapter"}
+    | {"door.after_register", "listing.after_sign", "listing.after_post"}
+    | {"withdraw.after_close"}
+    | {"knock.in_tx", "knock.after_tx", "knock_send.after_core"}
+    | {"knock_approve.after_group", "knock_add.after_welcome"}
+    | {"join_request.in_tx", "join_request.after_tx"}
+    | {"leave_timeout.in_tx", "leave_timeout.after_tx"}
+    | {"poison.in_tx", "poison.after_tx"}
+)
+
+
+class FailpointError(Exception):
+    """An injected transient failure."""
+
+
+class SimulatedCrash(BaseException):
+    """An injected crash: nothing in the daemon catches it."""
+
+
+class Failpoints:
+    """A daemon's armed failpoints."""
+
+    def __init__(self) -> None:
+        self._armed: dict[str, tuple[Action, int]] = {}
+        self.fired: list[str] = []
+
+    def arm(self, name: str, action: Action = "raise", times: int = 1) -> None:
+        if name not in POINTS:
+            msg = f"unknown failpoint {name}"
+            raise ValueError(msg)
+        self._armed[name] = (action, times)
+
+    def clear(self) -> None:
+        self._armed.clear()
+
+    def hit(self, name: str) -> None:
+        if not self._armed or name not in self._armed:
+            return
+        action, left = self._armed[name]
+        if left <= 1:
+            del self._armed[name]
+        else:
+            self._armed[name] = (action, left - 1)
+        self.fired.append(name)
+        if action == "crash":
+            raise SimulatedCrash(name)
+        raise FailpointError(name)