agentconnect-cli 0.1.0a1__py3-none-any.whl

agentconnect/provision.py

@@ -0,0 +1,239 @@
+"""Provisioning a replica: the identity key from one data directory into a
+fresh one, with a fresh instance (SPEC 9.4, ADR-005 Decision 5).
+
+``agentconnect identity export`` and ``identity import`` are the only way
+in. Both are human-only and CLI-only: no local API route, SDK call or MCP
+tool reaches this module, because whoever holds the identity key can add
+instances that every member accepts (SPEC 12).
+
+- **Export** wraps ``IK``'s secret under a fresh random 32-byte key in the
+  core (ChaCha20-Poly1305, AAD ``agentconnect/v0/identity-export``) and
+  writes the file 0600, never over an existing one. The key is the export
+  code: the CLI shows it once, and the human carries it apart from the file.
+- **Import** opens the file with the code into a data directory that holds
+  no identity, instance, database key or MLS store, and creates a fresh
+  instance there: its own signing key and ``instance_id``, never the
+  exporting instance's. A copied data directory has those, so it is refused:
+  a copy is not a replica (two runtimes on one leaf break the group).
+
+Both take the data directory's lock first, so they refuse to run while a
+runtime (a daemon, an embedded agent, an MCP server) holds it, and nothing
+starts on the directory meanwhile. An import cut between its two keystore
+writes (the identity, then the instance) leaves a directory that holds that
+identity and nothing else; importing the same export again finishes it.
+File errors are :class:`ProvisionError` too, naming the path, so the CLI
+reports them like any other refusal.
+
+Nothing here logs. The secret is zeroized inside the core; in Python it
+passes once as ``bytes`` into the keystore, and the code is a ``str``,
+neither of which can be zeroized (the residual exposure noted in
+:mod:`agentconnect.identity`).
+"""
+
+from __future__ import annotations
+
+import contextlib
+import os
+from collections.abc import Generator
+from pathlib import Path
+from typing import Any
+
+import agentconnect_core as ac
+from agentconnect.config import Config
+from agentconnect.keystore import DataDirLock, DataDirLockedError, Keystore, open_keystore
+
+# What makes a data directory an instance already: its keys and databases.
+STATE_KEYS = ("identity", "instance", "db_key")
+STATE_FILES = ("mls.sqlite3", "daemon.sqlite3")
+ISOLATION_HINT = (
+    "in separate-OS-user mode, run `identity export` and `identity import` as the "
+    "daemon's OS user (docs/isolation.md)"
+)
+
+EXPORT_WARNING = (
+    "Whoever has both this file and the code holds the identity: every host you "
+    "import it on can speak as this agent in every group. Carry the code apart "
+    "from the file (not in the same message or folder), import it once, then "
+    "delete the file."
+)
+
+
+class ProvisionError(Exception):
+    """A refused export or import: a machine-readable code and a message."""
+
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code, self.message = code, message
+
+
+@contextlib.contextmanager
+def _os_errors(code: str, what: str) -> Generator[None]:
+    """An ``OSError`` inside as ``ProvisionError(code)``, naming ``what``."""
+    try:
+        yield
+    except OSError as e:
+        msg = f"{what}: {e.strerror or e}"
+        if isinstance(e, PermissionError):
+            msg = f"{msg}; {ISOLATION_HINT}"
+        raise ProvisionError(code, msg) from None
+
+
+@contextlib.contextmanager
+def _locked(data_dir: Path) -> Generator[None]:
+    try:
+        with _os_errors("data_dir_access", f"can't open the data directory {data_dir}"):
+            lock = DataDirLock(data_dir, note=False)
+    except DataDirLockedError as e:
+        msg = f"{e}; provisioning works only on a stopped runtime's data directory"
+        raise ProvisionError("runtime_running", msg) from None
+    try:
+        yield
+    finally:
+        lock.release()
+
+
+def _write_new(path: Path, data: bytes) -> None:
+    """Write ``data`` to a new file created 0600; never replace or follow a
+    link to an existing one."""
+    flags = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | os.O_CLOEXEC
+    try:
+        fd = os.open(path, flags, 0o600)
+    except FileExistsError:
+        msg = f"{path} exists: an export never replaces a file, choose another path"
+        raise ProvisionError("exists", msg) from None
+    except OSError as e:
+        raise ProvisionError("cannot_write", f"can't write {path}: {e.strerror}") from None
+    try:
+        try:
+            os.fchmod(fd, 0o600)
+            view = memoryview(data)
+            while view:
+                view = view[os.write(fd, view) :]
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+    except BaseException as e:
+        path.unlink(missing_ok=True)
+        if isinstance(e, OSError):
+            raise ProvisionError("cannot_write", f"can't write {path}: {e.strerror}") from None
+        raise
+
+
+def export_identity(config: Config, out: Path, keystore: Keystore | None = None) -> dict[str, Any]:
+    """Wrap this data directory's identity into ``out``: the file's path,
+    the identity, its fingerprint and the code (to show once)."""
+    with _locked(config.data_dir):
+        with _os_errors("data_dir_access", f"can't read the keys in {config.data_dir}"):
+            store = keystore or open_keystore(config.keystore, config.data_dir)
+            secret = store.get("identity")
+        if secret is None:
+            msg = f"{config.data_dir} has no identity to export"
+            raise ProvisionError("no_identity", msg)
+        identity = ac.Identity.from_secret_bytes(secret)
+        file, code = ac.wrap_identity_export(identity)
+        _write_new(out, file)
+    return {
+        "file": str(out),
+        "identity": identity.id,
+        "fingerprint": identity.fingerprint,
+        "code": code,
+        "warning": EXPORT_WARNING,
+    }
+
+
+def read_export(path: Path) -> bytes:
+    """An export file's bytes (at most the core's limit)."""
+    try:
+        with path.open("rb") as f:
+            data = f.read(ac.MAX_IDENTITY_EXPORT_LEN + 1)
+    except OSError as e:
+        msg = f"can't read {path}: {e.strerror}"
+        raise ProvisionError("bad_export", msg) from None
+    if len(data) > ac.MAX_IDENTITY_EXPORT_LEN:
+        raise ProvisionError("bad_export", f"{path} is not an identity export (too large)")
+    return data
+
+
+def export_identity_id(data: bytes) -> str:
+    """The identity an export file names, read without its code."""
+    try:
+        return ac.identity_export_identity(data)
+    except ac.AgentConnectError as e:
+        raise _open_error(e) from None
+
+
+def _open_error(e: ac.AgentConnectError) -> ProvisionError:
+    kind = getattr(e, "kind", None)
+    if kind == "authentication":
+        msg = "the code does not open this file: check the code, or export again"
+        return ProvisionError("bad_code", msg)
+    if kind == "unsupported_version":
+        msg = (
+            "the file is from another identity export format version: export it "
+            "again with this version of agentconnect"
+        )
+        return ProvisionError("unsupported_version", msg)
+    if "export code" in str(e):
+        msg = "the code is not an export code: give the 43 characters export printed"
+        return ProvisionError("bad_code", msg)
+    msg = "the file is not an identity export, or it is damaged (cut short?)"
+    return ProvisionError("bad_export", msg)
+
+
+def _not_empty(config: Config, found: list[str]) -> ProvisionError:
+    msg = (
+        f"{config.data_dir} already holds an instance ({', '.join(found)}): import "
+        "only into a new, empty data directory (a copied one is not a replica)"
+    )
+    return ProvisionError("not_empty", msg)
+
+
+def _check_fresh(config: Config, store: Keystore) -> bytes | None:
+    """Refuse a data directory that is an instance already, or a copy of one.
+    One that holds an identity and nothing else is what an import cut
+    between its writes leaves: its secret is returned, for the caller to
+    resume only an import of that same identity."""
+    found = [name for name in STATE_KEYS if store.get(name) is not None]
+    found += [name for name in STATE_FILES if (config.data_dir / name).exists()]
+    keys = config.data_dir / "keys"
+    # A dot file is a temporary of a write that was cut (keystore.write_private).
+    other_keys = keys.is_dir() and any(
+        p.name != "identity" and not p.name.startswith(".") for p in keys.iterdir()
+    )
+    if other_keys and found in ([], ["identity"]):
+        found.append("keys/")
+    if found == ["identity"]:
+        return store.get("identity")
+    if found:
+        raise _not_empty(config, found)
+    return None
+
+
+def import_identity(
+    config: Config, data: bytes, code: str, keystore: Keystore | None = None
+) -> dict[str, Any]:
+    """Open an export into this fresh data directory and create a new
+    instance for it: the identity, its fingerprint and the new
+    ``instance_id``. A directory that holds the same identity and nothing
+    else (an import cut before its second write) is finished."""
+    with _locked(config.data_dir):
+        with _os_errors("data_dir_access", f"can't read the keys in {config.data_dir}"):
+            store = keystore or open_keystore(config.keystore, config.data_dir)
+            resumed = _check_fresh(config, store)
+        try:
+            identity = ac.unwrap_identity_export(data, code)
+        except ac.AgentConnectError as e:
+            raise _open_error(e) from None
+        if resumed is not None and resumed != identity.secret_bytes():
+            raise _not_empty(config, ["identity"])
+        instance = identity.create_instance()
+        with _os_errors("cannot_write", f"can't write the keys in {config.data_dir}"):
+            if resumed is None:
+                store.put("identity", identity.secret_bytes())
+            store.put("instance", instance.to_secret_bytes())
+    return {
+        "identity": identity.id,
+        "fingerprint": identity.fingerprint,
+        "instance_id": instance.instance_id_hex,
+        "data_dir": str(config.data_dir),
+    }

agentconnect/relay.py

@@ -0,0 +1,405 @@
+"""The relay link: a persistent WebSocket (SPEC §8.2) and signed REST (§8.1.1).
+
+The WebSocket authenticates with the instance key, reconnects with
+exponential backoff and jitter (timed by the injectable clock), and hands
+every server frame to the daemon. Replies (``accepted``/``error``) are
+matched to requests by ``msg_id``. Nothing polls: the relay pushes queued
+``deliver`` frames on (re)connect and as they arrive.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import base64
+import json
+import time
+from collections.abc import Awaitable, Callable, Coroutine
+from typing import Any
+
+import httpx
+import websockets
+from websockets.asyncio.client import ClientConnection, connect
+
+import agentconnect_core as ac
+from agentconnect import log
+from agentconnect.backoff import Backoff
+from agentconnect.clock import Clock, unix_seconds
+from agentconnect.limits import MAX_PAYLOAD_DEPTH, loads
+
+LOG = log.get("agentconnect.relay")
+
+# The relay's frame limit is 2 MiB of JSON; leave headroom.
+MAX_FRAME = 4 << 20
+REQUEST_TIMEOUT = 30.0
+NONCE_LEN = 32  # SPEC 8.2
+# How far a signed request's ts may run ahead of the clock (many requests
+# in one second, or the last run's); the relay allows 300 s either way.
+REST_TS_LEAD_SECS = 60
+# A relay that just restarted refuses signed requests for at most 300 s and
+# says for how long (SPEC 8.1.1): the longest such wait a signed request sits
+# out before it is signed again.
+RESTART_RETRY_MAX_SECS = 310
+DRAIN_KEY = "_drain"  # set on every frame handed to the daemon
+# Ours, never the relay's: handed to the daemon after the relay's ``drained``,
+# behind every frame of the reconnect drain, with the connection's number.
+CAUGHT_UP = "_caught_up"
+
+
+def b64(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def unb64(text: str) -> bytes:
+    return base64.urlsafe_b64decode(text + "=" * (-len(text) % 4))
+
+
+class NotConnectedError(ConnectionError):
+    """The relay link is down; the request will be retried after reconnect."""
+
+
+class RelayError(Exception):
+    """An ``error`` frame or REST error from the relay (SPEC §8.4)."""
+
+    def __init__(self, code: str, detail: str = "", current_epoch: int | None = None) -> None:
+        super().__init__(f"{code}: {detail}" if detail else code)
+        self.code = code
+        self.detail = detail
+        self.current_epoch = current_epoch
+        # Seconds until a retry, when the relay says (REST `retry_after`).
+        self.retry_after: int | None = None
+
+
+FrameHandler = Callable[[dict[str, Any]], Awaitable[None]]
+
+
+class RelayLink:
+    """One authenticated WebSocket to the relay, kept up until :meth:`stop`."""
+
+    def __init__(  # noqa: PLR0913
+        self,
+        url: str,
+        relay_host: str,
+        instance: ac.Instance,
+        clock: Clock,
+        on_frame: FrameHandler,
+        *,
+        backoff: Backoff | None = None,
+        on_connected: Callable[[], Coroutine[Any, Any, None]] | None = None,
+        on_state: Callable[[], None] | None = None,
+    ) -> None:
+        self._url = url
+        self._host = relay_host
+        self._instance = instance
+        self._clock = clock
+        self._on_frame = on_frame
+        self._on_connected = on_connected
+        self._on_state = on_state or (lambda: None)
+        self.backoff = backoff or Backoff()
+        self._ws: ClientConnection | None = None
+        self._pending: dict[str, asyncio.Future[dict[str, Any]]] = {}
+        self._connected = asyncio.Event()
+        self._stop = asyncio.Event()
+        self.connections = 0
+        self.draining = False
+
+    @property
+    def connected(self) -> bool:
+        return self._connected.is_set()
+
+    async def wait_connected(self) -> None:
+        await self._connected.wait()
+
+    async def run(self) -> None:
+        """Connect, serve, and reconnect forever (until :meth:`stop`)."""
+        while not self._stop.is_set():
+            try:
+                async with connect(
+                    self._url, max_size=MAX_FRAME, open_timeout=10, compression=None
+                ) as ws:
+                    await self._authenticate(ws)
+                    self._ws = ws
+                    # Until the relay's ``drained`` frame: the reconnect drain.
+                    self.draining = True
+                    self.connections += 1
+                    self.backoff.reset()
+                    self._connected.set()
+                    LOG.info("relay_connected", connections=self.connections)
+                    if self._on_connected is not None:
+                        asyncio.get_running_loop().create_task(self._on_connected())
+                    async for raw in ws:
+                        await self._dispatch(raw)
+            except (OSError, websockets.WebSocketException, TimeoutError, ValueError) as e:
+                LOG.info("relay_disconnected", reason=type(e).__name__)
+            except Exception as e:
+                # Anything else a relay frame can provoke (a bug included) must
+                # not end the link for good: log the type only and reconnect.
+                LOG.warning("relay_link_error", reason=type(e).__name__)
+            finally:
+                self._down()
+            if self._stop.is_set():
+                break
+            delay = self.backoff.next()
+            LOG.info("relay_reconnect_scheduled", delay=round(delay, 3))
+            sleeping = asyncio.ensure_future(self._clock.sleep(delay))
+            await asyncio.sleep(0)  # let the sleep register before announcing it
+            self._on_state()
+            await sleeping
+
+    def _down(self) -> None:
+        self._ws = None
+        self._connected.clear()
+        for fut in self._pending.values():
+            if not fut.done():
+                fut.set_exception(NotConnectedError("relay connection lost"))
+        self._pending.clear()
+        self._on_state()
+
+    async def _authenticate(self, ws: ClientConnection) -> None:
+        """SPEC 8.2. Every malformed frame raises ``ValueError`` (reconnect)."""
+        challenge = loads(await asyncio.wait_for(ws.recv(), REQUEST_TIMEOUT), MAX_PAYLOAD_DEPTH)
+        if not isinstance(challenge, dict) or challenge.get("t") != "challenge":
+            msg = "expected a challenge"
+            raise ValueError(msg)
+        nonce_text = challenge.get("nonce")
+        if not isinstance(nonce_text, str):
+            msg = "challenge without a nonce"
+            raise ValueError(msg)
+        try:
+            nonce = unb64(nonce_text)
+        except (ValueError, TypeError):
+            msg = "challenge nonce is not base64url"
+            raise ValueError(msg) from None
+        if len(nonce) != NONCE_LEN:
+            msg = "challenge nonce is not 32 bytes"
+            raise ValueError(msg)
+        sig = self._instance.sign_relay_challenge(nonce, self._host)
+        await ws.send(
+            json.dumps({"t": "auth", "sig_key": b64(self._instance.public_key), "sig": b64(sig)})
+        )
+        ready = loads(await asyncio.wait_for(ws.recv(), REQUEST_TIMEOUT), MAX_PAYLOAD_DEPTH)
+        if (
+            not isinstance(ready, dict)
+            or ready.get("t") != "ready"
+            or ready.get("mailbox_id") != self._instance.mailbox_id
+        ):
+            msg = "relay authentication failed"
+            raise ValueError(msg)
+
+    async def _dispatch(self, raw: str | bytes) -> None:
+        try:
+            frame = loads(raw, MAX_PAYLOAD_DEPTH)
+        except (ValueError, RecursionError):  # not UTF-8 JSON, or nested too deep
+            LOG.warning("relay_frame_unparsable")
+            return
+        if not isinstance(frame, dict):
+            return
+        t = frame.get("t")
+        if t == "drained":
+            self.draining = False
+            # In order after the drain's frames: once the daemon has handled
+            # it, it has seen everything the relay held for this mailbox.
+            await self._on_frame({"t": CAUGHT_UP, "connection": self.connections})
+            return
+        if t == CAUGHT_UP:
+            return  # never from the relay
+        # Ours, never the relay's: was this frame queued before we connected?
+        frame[DRAIN_KEY] = self.draining
+        if t in ("accepted", "error"):
+            fut = self._pending.pop(str(frame.get("msg_id")), None)
+            if fut is not None and not fut.done():
+                fut.set_result(frame)
+                return
+        await self._on_frame(frame)
+
+    async def send(self, frame: dict[str, Any]) -> None:
+        """Send without waiting for a reply (acks)."""
+        ws = self._ws
+        if ws is None:
+            raise NotConnectedError("relay link is down")
+        try:
+            await ws.send(json.dumps(frame, separators=(",", ":")))
+        except websockets.WebSocketException as e:
+            # The socket is gone, but run() may not have noticed yet. Mark
+            # the link down now: a caller that retries after
+            # NotConnectedError then waits in wait_connected() instead of
+            # failing again without yielding, which would starve the loop
+            # (run() included) for good.
+            if self._ws is ws:
+                self._down()
+            raise NotConnectedError(str(e)) from None
+
+    async def request(
+        self,
+        frame: dict[str, Any],
+        msg_id: str,
+        *,
+        on_sent: Callable[[], None] | None = None,
+    ) -> dict[str, Any]:
+        """Send a frame and wait for the ``accepted``/``error`` with ``msg_id``.
+        ``on_sent`` runs once the frame was written to the socket (from then
+        on the relay may have it, whatever happens to the answer).
+
+        Raises :class:`NotConnectedError` if the link drops first (the caller
+        resends the same frame after reconnecting) and :class:`RelayError`
+        for an ``error`` reply.
+        """
+        if self._ws is None:
+            raise NotConnectedError("relay link is down")
+        fut: asyncio.Future[dict[str, Any]] = asyncio.get_running_loop().create_future()
+        self._pending[msg_id] = fut
+        try:
+            await self.send(frame)
+            if on_sent is not None:
+                on_sent()
+            reply = await asyncio.wait_for(fut, REQUEST_TIMEOUT)
+        except TimeoutError:
+            raise NotConnectedError("no reply from relay") from None
+        finally:
+            self._pending.pop(msg_id, None)
+        if reply.get("t") == "error":
+            raise RelayError(
+                str(reply.get("code")), str(reply.get("detail", "")), reply.get("current_epoch")
+            )
+        return reply
+
+    async def kick(self) -> None:
+        """Drop the current connection (it reconnects); used on shutdown."""
+        ws = self._ws
+        if ws is not None:
+            await ws.close()
+
+    async def stop(self) -> None:
+        """Go down at once (pending requests fail, nothing new is sent),
+        then close the socket."""
+        self._stop.set()
+        ws = self._ws
+        if ws is not None:
+            self._down()
+            await ws.close()
+
+
+class RelayRest:
+    """Signed REST calls (SPEC §8.1.1): a fresh ``ts`` for every request."""
+
+    def __init__(  # noqa: PLR0913
+        self,
+        base_url: str,
+        relay_host: str,
+        instance: ac.Instance,
+        clock: Clock,
+        transport: httpx.AsyncBaseTransport | None = None,
+        *,
+        last_ts: int = 0,
+        on_ts: Callable[[int], None] | None = None,
+    ) -> None:
+        self._base = base_url.rstrip("/")
+        self._host = relay_host
+        self._instance = instance
+        self._clock = clock
+        self._transport = transport
+        self._last_ts = last_ts
+        self._on_ts = on_ts
+
+    def _ts(self) -> int:
+        # Strictly increasing, so two requests never share a signature (each
+        # signed request is single use at the relay, and Ed25519 signs the
+        # same input the same way). `on_ts` stores it before the request
+        # goes out, and the next run starts above it (`last_ts`), so this
+        # holds across a restart in the same second too. A value far ahead of
+        # the clock (it was wrong once, then put right) is dropped: the relay
+        # refuses a ts more than 300 s off, and a repeat matters only within
+        # that window.
+        now = unix_seconds(self._clock)
+        following = self._last_ts + 1
+        if following > now + REST_TS_LEAD_SECS:
+            LOG.warning("relay_rest_ts_reset", reason="clock_behind_last_request")
+            following = now
+        ts = max(now, following)
+        self._last_ts = ts
+        if self._on_ts is not None:
+            self._on_ts(ts)
+        return ts
+
+    def authorization(self, method: str, path: str, body: bytes) -> str:
+        ts = self._ts()
+        sig = self._instance.sign_relay_request(method, path, ts, body, self._host)
+        return f"AgentConnect-Ed25519 {b64(self._instance.public_key)}.{ts}.{b64(sig)}"
+
+    async def _call(self, method: str, path: str, body: bytes = b"", signed: bool = True) -> Any:
+        try:
+            return await self._call_once(method, path, body, signed)
+        except RelayError as e:
+            # A relay that just restarted refuses signed requests for a
+            # moment and says for how long (SPEC 8.1.1): sign again, once,
+            # when it ends, rather than fail the human's request.
+            wait = e.retry_after
+            if not signed or e.code != "rate_limited" or wait is None:
+                raise
+            if wait > RESTART_RETRY_MAX_SECS:
+                raise
+            LOG.info("relay_restarting_retry", wait=wait)
+            await self._clock.sleep(wait)
+            return await self._call_once(method, path, body, signed)
+
+    async def _call_once(self, method: str, path: str, body: bytes, signed: bool) -> Any:
+        headers = {"content-type": "application/json"}
+        if signed:
+            headers["authorization"] = self.authorization(method, path, body)
+        started = time.monotonic()
+        try:
+            async with httpx.AsyncClient(
+                transport=self._transport, timeout=REQUEST_TIMEOUT
+            ) as http:
+                resp = await http.request(method, self._base + path, content=body, headers=headers)
+        except httpx.HTTPError as e:
+            # Connection refused, DNS, timeouts: all "relay unreachable".
+            raise RelayError("relay_unreachable", type(e).__name__) from None
+        LOG.debug(
+            "relay_rest",
+            method=method,
+            status=resp.status_code,
+            ms=round((time.monotonic() - started) * 1000),
+        )
+        try:
+            data = resp.json() if resp.content else {}
+        except ValueError:
+            data = None
+        if not isinstance(data, dict):
+            # A proxy's HTML error page, or a non-object body.
+            code = "internal" if resp.status_code >= 400 else "bad_response"  # noqa: PLR2004
+            raise RelayError(code, f"HTTP {resp.status_code} without a JSON object")
+        if resp.status_code >= 400:  # noqa: PLR2004
+            err = RelayError(str(data.get("code", "internal")), str(data.get("detail", "")))
+            retry_after = data.get("retry_after")
+            if isinstance(retry_after, int) and not isinstance(retry_after, bool):
+                err.retry_after = max(1, retry_after)
+            raise err
+        return data
+
+    async def create_invite(self, meta: dict[str, Any]) -> dict[str, Any]:
+        body = json.dumps(
+            {**meta, "inviter_mailbox": self._instance.mailbox_id}, separators=(",", ":")
+        ).encode()
+        return await self._call("POST", "/v0/invites", body)
+
+    async def revoke_invite(self, invite_id: str) -> None:
+        await self._call("DELETE", f"/v0/invites/{invite_id}")
+
+    async def invite_meta(self, invite_id: str) -> dict[str, Any]:
+        return await self._call("GET", f"/v0/invites/{invite_id}", signed=False)
+
+    async def create_door(self, door_id: str, expires_at: int) -> dict[str, Any]:
+        """Register a door for this instance's mailbox (SPEC 6.6.1, 8.1)."""
+        body = json.dumps(
+            {
+                "door_id": door_id,
+                "expires_at": expires_at,
+                "owner_mailbox": self._instance.mailbox_id,
+            },
+            separators=(",", ":"),
+        ).encode()
+        return await self._call("POST", "/v0/doors", body)
+
+    async def close_door(self, door_id: str) -> None:
+        """Close a door at once: from then on every knock gets ``door_not_open``."""
+        await self._call("DELETE", f"/v0/doors/{door_id}")

agentconnect/runtime/__init__.py

@@ -0,0 +1,46 @@
+"""The AgentConnect runtime: everything one identity and instance needs.
+
+Embeddable: no terminal, no signals, no stdout. Hosts (``agentconnectd`` in
+:mod:`agentconnect.daemon`, the embedded SDK in ``agentconnect_sdk``, the
+MCP server in :mod:`agentconnect.mcp`) build on :class:`Runtime` and import
+from this package only, never from its submodules (ADR-005, Decision 1;
+ruff's ``TID251`` enforces it).
+"""
+
+from agentconnect.adapter import Adapter
+from agentconnect.callback import CallbackAdapter, PayloadCallback
+from agentconnect.clock import Clock, SystemClock
+from agentconnect.config import Config, ConfigError, load_config
+from agentconnect.deliveries import MAX_WAIT_SECS, DeliveryQueue, Taken
+from agentconnect.isolation import IsolationError
+from agentconnect.keystore import DataDirLockedError, Keystore
+from agentconnect.runtime.agent import AgentApi
+from agentconnect.runtime.engine import Options
+from agentconnect.runtime.errors import ApiError, error_reply
+from agentconnect.runtime.registry import AdapterRegistry
+from agentconnect.runtime.runtime import STOP_FLUSH_SECS, HandledIds, Runtime
+
+__all__ = [
+    "MAX_WAIT_SECS",
+    "STOP_FLUSH_SECS",
+    "Adapter",
+    "AdapterRegistry",
+    "AgentApi",
+    "ApiError",
+    "CallbackAdapter",
+    "Clock",
+    "Config",
+    "ConfigError",
+    "DataDirLockedError",
+    "DeliveryQueue",
+    "HandledIds",
+    "IsolationError",
+    "Keystore",
+    "Options",
+    "PayloadCallback",
+    "Runtime",
+    "SystemClock",
+    "Taken",
+    "error_reply",
+    "load_config",
+]