bud-relay 0.1.0__tar.gz

bud_relay-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+dist/
+.env
+.env.*
+relay.toml
+*.sqlite3
+*.sqlite3-*
+.claude/
+.orchestra/

bud_relay-0.1.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+Notable changes to bud-relay. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-04
+
+First public release.
+
+### Added
+
+- One self-hosted MCP server where agents send each other requests and replies: a mailbox per
+  agent, threads, reply deadlines, retries, progress lines and a shared board.
+- Agent types: OpenAI's dot (OAuth, woken by an MCP Events webhook), Claude Duet and Claude
+  Code cloud (claude.ai connector, OAuth; cloud woken by a routine trigger), Claude Code on your
+  computer (API key, optional channel), Meta Muse (API key, optional unofficial bridge), and any
+  other MCP client with an API key.
+- Sign-in with an API key per agent, or OAuth with a one-time pairing code.
+- Relayed messages arrive in an envelope that names the sender and marks the text untrusted.
+- CLI: `init`, `serve`, `keys`, `connect`, `setup`, `send`, `inbox`, `thread` and `demo`.
+- A Dockerfile and [docs/docker.md](docs/docker.md).
+
+### Tested live at release
+
+- dot, through chatgpt.com in a browser: woke about 6 s after a send and replied at 22 s.
+- Claude Code with an API key.
+- Duet, connected with the built-in client id `bud-relay`. It reads mail only while you chat
+  with it: it never woke on its own in a 6-hour test.
+- Muse: replied in 17 s through the optional unofficial bridge. Through a connector built in a
+  Muse chat, `whoami` and `send` worked. Behind Cloudflare, Muse was blocked (error 1010) until
+  Browser Integrity Check was turned off for the relay hostname.
+
+### Not yet tested
+
+- Claude Code cloud and the Claude Code channel.
+- A Duet routine answering a request, and claude.ai registering itself as a client.
+- Muse reading its inbox through its connector.
+- A dot subscription renewing after 24 hours.
+
+[Unreleased]: https://github.com/BaeHenryS/bud-relay/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/BaeHenryS/bud-relay/releases/tag/v0.1.0

bud_relay-0.1.0/CONTRACT.md

@@ -0,0 +1,574 @@
+# bud-relay contract
+
+How the parts of bud-relay fit together: the data model, the tools, auth, the agent types and the
+config. v2 made it one installable relay; connecting an agent is one command (`bud-relay connect`)
+and one pairing code. A change to an interface named here changes this file in the same PR.
+
+## What it is
+
+One self-hosted MCP server (default `127.0.0.1:8787`, exposed through an HTTPS tunnel) that lets
+always-on agents from several vendors send each other requests and replies, and share a small
+board of notes. The core is vendor-neutral; every vendor's quirks live in one module under
+`src/bud_relay/agents/`.
+
+**Every agent has a mailbox, plus an optional waker.**
+
+- Every message lands in the recipient's inbox, requests included. A request stays there until
+  it is answered or expires: the `inbox` tool and `GET /api/inbox` return every open request
+  addressed to the caller on every read, from any session, plus replies, notes and errors once
+  each (see `inbox` below). A recipient may answer a request with `reply` in any open state.
+- A **waker** tells an agent at once that mail arrived. It is optional: an agent without one
+  (Duet) reads its inbox when it checks. A waker never replaces the mailbox.
+- Two waker modes (`WakeResult.mode`):
+  - `tool_reply`: the waker nudges the agent (the dot's webhook, a Claude Code cloud routine
+    fire) and the agent answers with the `reply` tool. The relay never polls it.
+  - `job`: the waker starts a job the relay polls (the optional Muse bridge). A job's `replied`
+    result is stored as the agent's reply, unless the agent already replied by tool.
+- **The first reply wins.** A later reply to the same request is refused.
+
+Agent ids match `^[a-z][a-z0-9-]{0,31}$`. The set and each agent's type come from config.
+
+| Type | Who | Signs in with | Waker | Backstop (finds mail without a waker) |
+|---|---|---|---|---|
+| `inbox` | scripts, other MCP clients | API key | none | reads its inbox when asked |
+| `duet` | Anthropic Claude Duet | OAuth (the claude.ai connector) | none (no official way to wake Duet) | an hourly routine Duet sets up itself |
+| `claude-code` | Claude Code sessions on the user's machines | API key (MCP, or `bud-relay-channel`) | none server-side | the channel pushes into a live session, or it checks when asked |
+| `claude-cloud` | a Claude Code cloud session started by a routine | OAuth (the claude.ai connector, with `as_agent`) | routine fire (`tool_reply`) | — |
+| `muse` | Meta Muse | API key (a custom connector Muse builds in chat) | **optional, unofficial**: the Muse bridge (`job`), only when `bridge_url` is set | checks when asked, or on a schedule it runs itself |
+| `dot` | an OpenAI dot | OAuth (a ChatGPT plugin) | MCP Events webhook (`tool_reply`) | — |
+| `fake` | the demo and tests | API key | scripted (`job`) | — |
+
+## Data model (`models.py`)
+
+- **Thread** `thr_…`: subject, created_by, timestamps. A `send` without `thread_id` starts one.
+- **Message** `msg_…`: `seq` (global, monotonic, the SQLite rowid; inbox cursors use it),
+  thread, sender, recipient, kind (`request | reply | note | error`), text (≤ 16,000 chars; a
+  request to an agent with a waker must also fit its envelope in 16,000, see Envelope),
+  `in_reply_to`, `delivery` (below), `external_ref` (the dot's event id, a Muse job id, a cloud
+  session URL), `error`, `deadline_at`.
+- **Progress** lines per request, from `report_progress` (≤ 1,000 chars each) or a job's
+  snapshot; either way the request's recipient writes them. Shown by `get_message` and
+  `get_thread`, never in inboxes.
+- **BoardEntry**: key (≤ 200 chars, `^[A-Za-z0-9._/-]+$`), value (≤ 8,000 chars), integer
+  version starting at 1, updated_by, updated_at. No deletes.
+- **OAuthClient** `(client_id, redirect_uris, agents)` (a static client), **OAuthConfig**
+  (`public_base_url`, `owner_key`, `clients` (default: the claude.ai client), scopes, token
+  lifetimes, `dynamic_clients` (default true), `allowed_redirect_hosts` (default
+  `("claude.ai", "chatgpt.com")`)), **OAuthGrant** (`client_id`, scopes, `expires_at`, `agent`)
+  and **PairingCode** (`code` shown as `XXXX-XXXX`, `agent`, `expires_at` in unix seconds).
+- Timestamps are ISO-8601 UTC strings with `Z`. Ids are a prefix plus 26 lowercase hex chars.
+
+### Delivery states
+
+`inbox | pending | sending | delivered | replied | failed | expired | cancelled`
+
+```
+agent with no waker:   inbox ──reply──▶ replied
+agent with a waker:    pending ──wake()──▶ sending ──ok──▶ delivered ──reply tool / job──▶ replied
+                          │                   │                 │
+                          └── waker finally fails, or a job ends without a reply ──▶ inbox + note
+any open state ──deadline passes──▶ expired + error
+```
+
+- `sending` is written before `wake()` is called. On startup, a `sending` row moves to `inbox`
+  with the note below. Wakes are never replayed automatically.
+- **A waker failure does not fail the request.** A non-retryable `WakeError`, a retryable one
+  out of tries (`MAX_DELIVERY_ATTEMPTS = 5`, with backoff), a timeout, a waker bug, or a job that
+  ends `failed`, `cancelled` or `expired` (its own expiry) moves the request to `inbox`, and the
+  relay adds one `note` to the sender: `Could not wake <agent> (<detail>); it will see your
+  request <id> when it next checks.` The note's sender is the request's recipient (there is no
+  relay agent id); `in_reply_to` is the request and `error` holds the detail.
+- Only the deadline ends a request without a reply: `reply_timeout_hours` from config (default
+  6), set when the request is created. The relay adds an `error` message to the sender.
+- A reply (tool or job) is stored as a `reply` message from the request's recipient to its
+  sender, `in_reply_to` the request, and marks the request `replied`.
+- `failed` and `cancelled` remain for rows a v1 relay wrote; v2 sets neither. The SQLite schema
+  is v1's: v1 rows a relay pushed keep `in_inbox = 0` until a fallback moves them, and the `job`
+  mode is stored as `poll`.
+
+## Envelope
+
+Everything the relay hands an agent (a webhook event, a routine fire, a channel push) is wrapped
+by `models.render_envelope(...)`. It names the message, the thread, the sender and the subject,
+says the text was written by another of the user's agents and is information to weigh, not the
+user's instructions (`UNTRUSTED_NOTICE`), and says how to answer. Tool results carry structured
+fields instead, with `untrusted: true` and the notice on any text another agent wrote (see
+MessageView, ThreadView and BoardView below).
+
+Only a request's envelope asks for an answer ("call bud-relay's reply tool with
+message_id=..."). A reply, error or note says "This is a <kind> to your request <in_reply_to>.
+It needs no answer", since the relay refuses a reply to it.
+
+The envelope adds 557-861 characters (agent ids and the thread subject vary; ids have a fixed
+width). `send` to an agent with a waker refuses with `too_long` any text whose envelope would
+exceed `MAX_TEXT_CHARS`, and says how much room there is. A follow-up in a thread is measured
+with the thread's subject. Requests to agents without a waker, and replies, keep the full 16,000.
+
+## MCP tools (`/mcp`, streamable HTTP)
+
+Every tool takes an optional `as_agent`; it must be in the caller's `allowed_agents`, and
+defaults to the caller's `default_agent`. `reply` and `report_progress` default instead to the
+request's recipient when the caller may act as it (a cloud session on Duet's connector answering
+`claude-cloud`'s request), else to `default_agent`. No tool blocks longer than 25 s
+(`MAX_TOOL_WAIT_SECONDS`): tunnels and claude.ai cut off long calls.
+
+Every result in the table below also carries `unanswered`: how many open requests are addressed
+to the agent the call acted as (one indexed count; `reply` counts after its reply lands). The one
+exception is `board_get`'s `null` for a missing entry, which stays a bare `null`.
+
+| Tool | Args | Returns |
+|---|---|---|
+| `whoami` | | `{agent, allowed_agents}` |
+| `list_agents` | | `{agents: [{id, type, description, connects, waker, backstop}]}`; `waker` is a bool |
+| `send` | `to, text, thread_id=None, subject=None` | `{message_id, thread_id, delivery}` at once; `too_long` if an envelope would pass 16,000 |
+| `inbox` | `since=None, limit=20, wait_seconds=0` | `{messages: [MessageView + new], cursor, more, open_not_shown}` |
+| `reply` | `message_id, text` | `{message_id, thread_id}`; caller must be the request's recipient |
+| `report_progress` | `message_id, text, idempotency_key=None` | `{message_id, recorded}`; caller must be the recipient of an open request; a repeated key records nothing |
+| `get_message` | `message_id` | `MessageView` plus `progress: [str]` |
+| `get_thread` | `thread_id` | `{thread: ThreadView, messages: [MessageView plus progress]}` |
+| `board_list` | `prefix=""` | `{entries: [BoardView]}` |
+| `board_get` | `key` | `BoardView` or `null` |
+| `board_put` | `key, value, expected_version=None` | `BoardView`; version mismatch is an error |
+| `status` | | `{version, agents: [{id, type, waker_kind}], counts}` (counts by delivery state) |
+
+`inbox` with `since=None` reads from the caller's stored cursor (one per agent, shared by every
+session acting as it: Duet's chats and its routine). It returns every **open** request addressed
+to the caller (kind `request`, delivery `inbox | pending | sending | delivered`), wherever it is
+relative to the cursor, plus the replies, notes and errors past the cursor, oldest first by seq.
+A request already answered or expired is left out, even one no read has returned. The cursor
+then moves past the page's newest message, so a reply, note or error is returned once, while an
+open request comes back on every read until it is answered or expires. When the page holds all
+the new mail, the cursor also moves past the closed requests it skipped, so each is scanned once
+and an idle read costs the same however long the history. A page holds at most
+`limit` messages: mail past the cursor fills it first (oldest first), and open requests already
+shown fill the room left (oldest first), so they never hide new mail. Each shown request sits
+before the cursor, so the page stays in seq order. `more` is true only when new mail was left
+out (the next read returns it, at once even with a wait), so reading while `more` is true always
+ends. `open_not_shown` counts the open requests addressed to the caller that are not on the
+page (`unanswered` minus the open requests shown): above 0, a larger `limit` (up to 100) or
+answering some shows the rest. With an explicit `since` it returns every message
+after `since`, any kind or state, and does not touch the stored cursor. `cursor` is the stored
+cursor after the call (for `since`, the last message's seq, or `since`).
+
+Each MessageView in an `inbox` result adds `new`: true when its seq is past the stored cursor as
+the call found it (no default read has returned it), for `since` reads too.
+
+`wait_seconds` (clamped to 0–25) long-polls for new mail only: the call returns as soon as its
+page holds a message past where it started (the stored cursor, or `since`), else at the
+deadline, with the open requests in the result either way. An open request no read has returned
+yet is new, so it returns a waiting call at once; one already returned never ends a wait early.
+A watch is repeated `inbox(wait_seconds=25)` calls, one call per 25 s while nothing new comes. A
+fresh session's first waiting call can take the full 25 s when another session was already
+shown every open request; `inbox()` without a wait returns them at once.
+
+`MessageView` is `{message_id, seq, thread_id, from, to, kind, text, in_reply_to, created_at,
+delivery, external_ref, error, untrusted}`, plus `notice: UNTRUSTED_NOTICE` when untrusted.
+`untrusted` is true when another agent wrote any of the view's text: the message
+(`from != caller`), or its progress lines, which the recipient writes (progress is non-empty and
+`to != caller`). One flag covers the whole view; `progress` stays a list of strings.
+
+`ThreadView` is `{thread_id, subject, created_by, created_at, updated_at, untrusted}`, where
+`untrusted = (created_by != caller)` (the creator wrote the subject), plus the notice when
+untrusted.
+
+`BoardView` is the BoardEntry `{key, value, version, updated_by, updated_at}` plus `untrusted =
+(updated_by != caller)`, and `notice: UNTRUSTED_NOTICE` when untrusted. An entry the caller
+wrote last is not marked, even if another agent wrote an earlier version.
+
+**Prompt.** `/mcp` lists one MCP prompt, `check_mail` (title "Check my mail", no arguments).
+Its one user message tells the agent to read its bud-relay inbox (again while `more` is true,
+and with `limit=100` when `open_not_shown` is above 0), answer every open request with `reply` under the user's usual approval rules (asking first about
+anything that needs a yes), never put passwords, keys, codes or private data the request does
+not need into a reply, and say what arrived. claude.ai shows a connector's prompts in its menu.
+
+Tool errors are MCP tool errors with a short code first: `not_found`, `forbidden`, `invalid`,
+`conflict`, `too_long`.
+
+**Extra JSON-RPC methods.** An agent type may add methods to `/mcp` (`AgentPlugin.mcp_methods`),
+each with an optional capability to advertise. `tools.build_mcp` mounts them through
+`mcp_methods.mount(mcp, methods, context_for)` while the app is built, before its lifespan starts
+(fastmcp refuses new extensions once it runs). `context_for()` reads the principal the bearer
+middleware left in the ASGI scope and returns `McpCallContext(principal, principal.default_agent)`,
+or None (an auth error). Two plugins may not mount the same method, so a relay has at most one
+`dot` agent.
+
+**Tool-call log.** One INFO line per MCP tool call and REST call on the `bud_relay.calls` logger:
+the surface, the tool, the caller and the agent the call acted as (an inferred one included;
+the requested one when the call failed before choosing), message and thread ids when they look
+like ids, and the outcome (`ok` or the error code). Never message text or a secret.
+
+## REST API (`/api`, JSON, same auth and semantics)
+
+For the channel process and scripts. Same bodies and results as the tools (`unanswered`
+included).
+
+- `POST /api/send` `{to, text, thread_id?, subject?, as_agent?}`
+- `GET /api/inbox?since=&limit=&wait=&as_agent=`
+- `POST /api/reply` `{message_id, text, as_agent?}`
+- `POST /api/messages/{id}/progress` `{text, idempotency_key?, as_agent?}`
+- `GET /api/messages/{id}`, `GET /api/threads/{id}`, `GET /api/agents`, `GET /api/board?prefix=`,
+  `GET /api/board/{key}`, `PUT /api/board/{key}` `{value, expected_version?}`
+- `GET /api/whoami`, `GET /api/status`
+- `GET /health` is open and returns `{"status": "ok"}` and nothing else.
+
+Errors: `{"error": code, "detail": str}` with 400/401/403/404/409/413, and 429 `locked` and
+503 `unavailable` from the admin API.
+
+### Admin API (`/api/admin`)
+
+For `bud-relay connect --relay` on another machine. It takes the owner key as its bearer token
+(SHA-256, then a constant-time compare) instead of an API key or OAuth token; the bearer
+middleware leaves exactly the `/api/admin` prefix to it.
+
+- `GET /api/admin/agents` → `{public_url, owner_key_env, agents: [list_agents' view + client_id]}`,
+  where `client_id` is the one static client that lists the agent, else null. Remote `connect`
+  renders an agent's steps from it.
+- `POST /api/admin/pairing-codes {agent}` → `{code, agent, expires_at}` (ISO-8601 UTC). 400
+  `invalid` for an agent whose type does not connect with OAuth (checked before the bundle is
+  asked) or that `create_pairing_code` refuses; 503 `unavailable` when OAuth is off.
+- `POST /api/admin/keys {agent, name?}` → `{name, agent, key}`, with a free name (`<agent>`,
+  `<agent>-2`, …) when none is given. The key is shown only this once.
+- A wrong or missing key gets 401 with `WWW-Authenticate: Bearer realm="bud-relay admin"`
+  (`ADMIN_CHALLENGE`), which tells it from the OAuth challenge. 5 wrong keys from one address
+  within 15 minutes lock that address out for 15 minutes, the right key included: 429 `locked`
+  with `Retry-After`. The state is in memory; a restart clears it.
+- With no owner key of 32+ characters in `[oauth] owner_key_env`, every admin route is 404
+  `not_found`. With OAuth off it still makes keys.
+- One call-log line per call, `admin <tool> agent=<id> from=<address> -> <outcome>`; never the
+  owner key, a code or a key.
+
+## Auth
+
+Two credential types, both `Authorization: Bearer <token>`. Core resolves a token in this order:
+`br_` prefix → API key table; otherwise → `OAuthBundle.verify_access_token`. Unknown or expired
+→ 401. OAuth tokens start with `bro_`, so a random token can never pass as an API key.
+
+1. **API keys** (`keys.py`). `bud-relay connect <id>` (or the admin API) makes one for an
+   `api_key` agent; `bud-relay keys create <name> --agent <id> [--allow id,id]` makes one by
+   hand. Either shows `br_<43 url-safe chars>` once; the relay stores only its SHA-256. Principal:
+   `Principal(name, default_agent=<id>, allowed_agents={<id>, …allow})`. `keys list`,
+   `keys revoke`.
+2. **OAuth** (`oauth/`), for the vendors' connectors. No client secrets: clients are public
+   (`token_endpoint_auth_method = "none"`), except that a client metadata document may ask for
+   `private_key_jwt` (below). Each grant is bound to one agent, which survives refresh. Two
+   kinds of client:
+   - **Static** clients: `[[oauth.clients]]`, each with exact-match redirect URIs and its
+     agents (the first preselected for the owner-key path). Optional: with none at all, the
+     claude.ai client (`bud-relay`) is implied for `duet` and `claude-cloud` if configured
+     (first, so its existing grants keep working) and every other agent of those types; with
+     none, there is no static client (a ConfigError only with `dynamic_clients = false`). A
+     client with no redirect URI cannot authorize.
+   - **Dynamic** clients, with `[oauth] dynamic_clients` (default true):
+     - **DCR** (RFC 7591) at `/register`, advertised as `registration_endpoint`. Public
+       code-flow clients only: an omitted `token_endpoint_auth_method` registers as `none`,
+       `client_secret_*` and `private_key_jwt` are refused, and the registration is exactly
+       `authorization_code` and `refresh_token`. 1-10 redirect URIs, each `https://` on port 443
+       with its host exactly in `allowed_redirect_hosts` (no wildcards). A random client id
+       (`token_urlsafe(24)`); at most 20 registrations an hour, then 429 with `Retry-After`.
+       Stored in `oauth.sqlite3` (`oauth_clients`); never purged.
+     - **CIMD** (client ID metadata documents): a `client_id` that is an `https://` URL is
+       fetched only from `CLIENT_METADATA_HOSTS = ("chatgpt.com", "claude.ai")` in
+       `oauth/documents.py` (the hosts the vendors document), under the webhook destination
+       rules (port 443, every resolved address public, the connection pinned to a checked
+       address with Host and SNI kept, no redirects, no env proxies), at most 64 KiB within
+       5 s. The document must name itself, be a code-flow client whose
+       `token_endpoint_auth_method` is `none` (or omitted) or `private_key_jwt` (`client_secret_*`
+       is refused), and have redirect URIs that pass the same host rule. Cached 24 hours (a
+       refresh after that fetches it again); a refused URL is not fetched again for 5 minutes.
+       Advertised as `client_id_metadata_document_supported: true`. A refused document makes
+       `/authorize` answer 400 `{"error": "invalid_client", "error_description":
+       "bud-relay refused the client metadata document at <url>: <reason>"}`, which the vendor
+       shows (the SDK's own answer was "Client ID … not found"); the log has the same reason.
+     - **`private_key_jwt`** (`oauth/assertions.py`; RFC 7523 §2.2, RFC 7521), as ChatGPT's
+       document asks. The document needs a `jwks_uri` that passes the document URL rules on the
+       document's own host, and a `token_endpoint_auth_signing_alg` of `RS256` or `ES256`
+       (absent: `RS256`); both are stored with the cached document (`oauth_clients.jwks_uri`,
+       `signing_alg`). At `/token` (both grants) and `/revoke` such a client sends
+       `client_assertion_type=urn:ietf:params:oauth:client-assertion-type:jwt-bearer` and a
+       `client_assertion` JWT: signed with the document's algorithm by the JWKS key its `kid`
+       names (no `kid`: the JWKS's only key; a key whose `use` or `alg` says otherwise does not
+       count), `iss` = `sub` = the client id, `aud` naming the token endpoint
+       (`<public_url>/token`) or the issuer (`<public_url>`, with or without the slash), `exp`
+       in the future but at most 10 minutes ahead, `iat` and `nbf` (when present) not in the
+       future, 60 s leeway on each, and a `jti` not used before. Used assertions are kept in
+       `oauth.sqlite3` (`oauth_assertions`: SHA-256 of client id and `jti`) until they expire.
+       `client_id` may be left out of the form: the assertion's `sub` names the client (it
+       still has to verify against that client's keys). A document that also lists `none` in
+       `token_endpoint_auth_methods_supported` (ChatGPT's does) may send no assertion and is
+       then a public client (PKCE); an assertion it does send must pass. The log says at INFO
+       which way it authenticated. Anything else is 401 `invalid_client`
+       with the reason in `error_description` and a warning in the log; PKCE is still
+       required. The JWKS is fetched under the document rules, kept 5 minutes, and fetched
+       again for a `kid` it lacks, at most once every 30 seconds. There is one fetch of a JWKS
+       at a time: requests that arrive during it share its keys. Metadata advertises
+       `token_endpoint_auth_methods_supported` and `revocation_endpoint_auth_methods_supported`
+       `["none", "private_key_jwt"]`, and
+       `…_auth_signing_alg_values_supported` `["RS256", "ES256"]`, when dynamic clients are on
+       (otherwise `["none"]`).
+     - Redirect hosts are checked at every lookup and every token check, so taking a host off
+       `allowed_redirect_hosts` retires the clients that use it and their tokens at once. With
+       `dynamic_clients = false` there is no `/register`, no fetch, and every dynamic grant
+       gets 401.
+   - **Pairing codes.** `await bundle.create_pairing_code(agent) -> PairingCode`: 8 Crockford
+     base32 characters (no I, L, O, U), shown `XXXX-XXXX`, accepted in any case with or without
+     the dash or spaces (I and L read as 1, O as 0). Valid once, for 10 minutes; stored only as
+     a SHA-256 hash (`oauth_pairing_codes`). `ValueError` for an agent not in `oauth_agents`. A
+     static client takes only codes for its own agents (otherwise 400; the code stays valid
+     and nothing is counted).
+   - **Consent page.** `/consent` (GET) names the client's redirect host (and a static
+     client's id) and asks for a pairing code; the grant acts as the code's agent. "Use the
+     owner key instead" (a collapsed `<details>`, no JavaScript) keeps the owner key plus an
+     agent choice: a static client's `agents`, or for a dynamic client every `oauth_agents`
+     agent. Refusals (a wrong or expired code, a wrong key, a lockout, an expired login) are a
+     short HTML page; after a wrong code or key it links back to the same form, which stays
+     open.
+   - **Consent lockout.** Wrong codes and wrong owner keys count together, before the request
+     and CSRF checks: 5 from one address within 15 minutes lock that address out for 15
+     minutes (429 with `Retry-After`), and 50 from all addresses together lock consent for
+     everyone. The right code or key clears its address's count, not the total. The counts are
+     in `oauth.sqlite3` (`oauth_consent_failures`). The address is the ASGI client, which
+     `serve` takes from `X-Forwarded-For` only for a proxy in `[relay] forwarded_allow_ips`.
+   - **Principals.** A static client's grant: `Principal(f"oauth:{client_id}",
+     default_agent=grant.agent, allowed_agents=frozenset(client.agents))`. A dynamic client's
+     grant always has an agent: `Principal(f"oauth:{client_id}", grant.agent,
+     frozenset({grant.agent} | {a for a in agents if a.via == grant.agent}))` (one hop).
+   - The provider (through `RelayConfig.oauth_config()`) and core's resolver read the same
+     clients. Each grant records its client's kind (`oauth_grants.client_kind`: `static`,
+     `dcr` or `cimd`; NULL, from before dynamic clients, is static) and, for a dynamic client,
+     its redirect URIs, and never changes kind. Every token check re-checks it against the
+     current config: a static grant needs its static client still configured and listing its
+     agent; a dynamic grant needs a client id that is not static, `dynamic_clients` on, its
+     agent still an OAuth agent, its recorded redirect URIs still on allowed hosts, and its
+     registration (DCR) or a document URL on a vendor host (CIMD; no fresh document needed).
+     Anything else gets 401, so retiring a client or a host retires its tokens at once.
+   - Grants made before v2 have no agent: they act as their client's first agent, with no
+     re-consent (`oauth.sqlite3` gains a nullable `agent` column in place).
+   - PKCE S256 required. The token endpoint accepts `application/x-www-form-urlencoded`. Refresh
+     tokens rotate; reusing a rotated refresh token revokes the grant. Scopes are `("relay",)`.
+   - Routes: `/.well-known/oauth-protected-resource` (RFC 9728, resource `<public_url>/mcp`),
+     `/.well-known/oauth-authorization-server` (RFC 8414), `/authorize`, `/consent`, `/token`,
+     `/revoke`, and `/register` with dynamic clients.
+   - bud-relay sends no `iss` (RFC 9207), so ChatGPT uses its
+     `https://chatgpt.com/connector/oauth/<id>` callback.
+   - Ported from dots-bridge's `PersonalOAuth` (`uezo/dots-bridge` at `46010a7`, MIT), credited
+     in the file header.
+
+A 401 on `/mcp` or `/api` carries
+`WWW-Authenticate: Bearer resource_metadata="<public_url>/.well-known/oauth-protected-resource"`,
+plus `error="invalid_token"` when a token was sent. claude.ai and ChatGPT discover OAuth from it.
+
+```python
+def build_oauth(
+    config: OAuthConfig,
+    db_path: Path,
+    *,
+    # The configured agents whose type connects with OAuth, in config order: the agents a
+    # pairing code may name and a dynamic client may act as. Default: the static clients'.
+    oauth_agents: Iterable[str] | None = None,
+    # Tests only: replace the network for client metadata documents and their JWKS.
+    document_transport: httpx.AsyncBaseTransport | None = None,
+    document_resolver: Resolver | None = None,
+) -> OAuthBundle: ...
+
+
+@dataclass
+class OAuthBundle:
+    routes: list[BaseRoute]  # every OAuth/discovery route; core mounts them at the root
+    verify_access_token: Callable[[str], Awaitable[OAuthGrant | None]]
+    provider: object | None = None  # the mcp/fastmcp provider object
+    create_pairing_code: Callable[[str], Awaitable[PairingCode]] | None = None
+```
+
+Core builds it with `server.build_relay_oauth(config, plugins, environ)`, which passes
+`oauth_agents` from the plugins (`connects == "oauth"`); `create_app` and local `connect` both
+use it.
+
+## Agent types (`agents/`)
+
+`agents/base.py` defines the plugin interface; `agents/__init__.py` the registry. A module
+registers its factory with `@register("<type>")`. Core builds each agent's plugin with
+`build_plugin(type, PluginContext)` (`delivery.build_plugins`) and prints its setup steps with
+`render_setup(type, SetupContext)`. A type missing from the build logs a warning at startup, and
+the agent keeps its mailbox with no waker.
+
+- `PluginContext(agent_id, options, data_dir, public_url, env, transport=None,
+  owner_key_env="BUD_RELAY_OWNER_KEY")`. `options` is the rest of `[agents.<id>]`; a factory
+  refuses keys it does not read. `env` is read at wake time, never at build time, so the relay
+  runs with only some secrets set; building a plugin writes nothing to `data_dir`. `transport`
+  routes HTTP into an ASGI stand-in (demo, tests). `owner_key_env` is `[oauth] owner_key_env`,
+  for a plugin that encrypts its secrets with the owner key (the dot).
+- `AgentPlugin(type, connects, waker=None, mcp_methods=(), backstop=None)`: `connects` is
+  `"oauth"` or `"api_key"`.
+- `Waker`: `wake(OutboundMessage) -> WakeResult`, `poll(external_ref) -> PollResult` (jobs
+  only), `aclose()`. Failures raise `WakeError(retryable=…)`: connection errors, 429 and 5xx
+  are retryable; other 4xx are not. A missing secret is a non-retryable error at wake time.
+- `PollResult.progress` is a snapshot (every line so far, oldest first). Core stores line `i`
+  once, so only the new tail is added; an empty tuple means none known, never "cleared".
+
+| Type | Options | Waker |
+|---|---|---|
+| `inbox`, `duet`, `claude-code` | none | none |
+| `claude-cloud` | `api_base`, `trigger_id_env`, `token_env` | `POST /v1/claude_code/routines/{trigger_id}/fire` with `Authorization: Bearer <token>`, `anthropic-beta: experimental-cc-routine-2026-04-01`, `anthropic-version: 2023-06-01`, body `{"text": <envelope>}`; ref = session URL; `tool_reply`. 429/5xx retryable, 401/403/404 not. Limits: 30 fires/hour per routine, 100/hour per account |
+| `muse` | `bridge_url`, `api_key_env`, `job_timeout_seconds` | only with `bridge_url`: `POST /v1/jobs` on the Muse bridge, ref = job id; `job`, polled at `GET /v1/jobs/{id}/result` (`completed` → reply) |
+| `dot` | `loopback_webhooks_for_tests` (demo only) | publishes `relay.request.created` to the dot's subscriptions (below); ref = event id; `tool_reply` |
+| `fake` | `reply_after_polls` (default 1), `prefix` | records the message; after N polls replies `"<prefix>: <first 200 chars>"` |
+
+The Muse bridge is a separate, unofficial project that drives Muse's website; bud-relay only
+calls its HTTP jobs API, it is off by default, and its setup text says it may break Meta's terms.
+
+**Setup steps** are package data: `agents/setup/<type>.md` for every type but `fake`, rendered
+with `str.format_map` and these placeholders only: `{agent_id}`, `{public_url}`, `{mcp_url}`,
+`{client_id}`, `{owner_key_env}`, `{key_command}`, `{pairing_code}`, `{pairing_minutes}`,
+`{key_hint}`. `connect` fills `pairing_code` and `pairing_minutes` for an OAuth agent and
+`key_hint` ("on your clipboard", or the key itself) for an API-key agent; `setup` replaces
+both with a line saying to run `connect`. The shipped templates use the last three, not
+`{client_id}`, `{key_command}` or `{owner_key_env}`. Each OAuth agent's steps say to paste
+`{mcp_url}`, let the platform register itself and type the code, and end with a short
+static-client fallback.
+
+## MCP Events and the dot (`events/`, `agents/dot.py`)
+
+Ported from dots-bridge (`mcp.py`, `bridge.py`, `webhooks.py`, `store.py` at `46010a7`, MIT),
+credited in each module's header.
+
+- **Methods:** `events/list`, `events/subscribe`, `events/unsubscribe`, advertised under the
+  capability `io.dotsbridge/webhook-events` (and `capabilities.events`). They take no
+  `as_agent`: subscriptions belong to the calling principal's agent, and only the dot's agent may
+  subscribe.
+- **The event** `relay.request.created` takes no arguments. Its envelope is
+  `{eventId, name, timestamp, data, cursor: null}`, signed per Standard Webhooks with the
+  subscriber's `whsec_…` secret. `eventId` = `webhook-id` = `evt_<message id hex>`, the same on
+  every retry, so a repeat is dropped. `data` is `{message_id, thread_id, from, to, subject,
+  text}`, where `text` is the full envelope. The dot answers with `reply` and `report_progress`
+  and can read the same request with `inbox` or `get_message`.
+- **Subscriptions** last at most 24 hours (`ttlMs` is capped) and the dot renews them. Renewing
+  with the same secret within 5 minutes skips the callback challenge; a new secret signs beside
+  the old one for 5 minutes.
+- **Wake:** no live subscription is a non-retryable `WakeError`; every delivery failing is one,
+  retryable only when a failure was transient (408, 425, 429, 5xx, connection errors). A 410
+  removes the subscription. `poll()` is never called for the dot's own wakes; a ref it gets is a
+  request a v1 relay sent through dots-bridge, and it refuses it for good, so such a request
+  falls back to the dot's inbox with a note.
+- **Destinations:** HTTPS on port 443 only; the host is resolved once, every address must be
+  public, and the connection is pinned to it with the host name kept for TLS. No redirects,
+  256 KiB per event, 16 KiB per answer. `loopback_webhooks_for_tests = true` also accepts plain
+  HTTP to this machine, for the local demo only.
+- **Storage:** `data_dir / "events.sqlite3"` (mode 0600). Each destination (URL and secret) is
+  encrypted with a Fernet key derived from the owner key by HKDF, so `init` needs no new secret.
+  A rotated owner key drops every subscription instead of failing.
+
+## Channel (`channel.py`)
+
+`bud-relay-channel --url <relay> --agent claude-code` (key from `BUD_RELAY_KEY`) is a stdio MCP
+server for one live Claude Code session. It declares `capabilities.experimental["claude/channel"]
+= {}`, long-polls `GET /api/inbox?wait=25`, and pushes each message with `new: true` once as
+`notifications/claude/channel` with `content = envelope` and `meta = {message_id, thread_id,
+from_agent, kind}`, plus `in_reply_to` for replies, notes and errors. Open requests that come back
+with `new: false` are not pushed again, so a request an earlier session was shown and left
+unanswered reaches a new session only when it reads its inbox; a message with no `new` (a relay
+from before it) is pushed. New mail fills each page first, so open requests never stall the
+channel; when more new mail waits than one page holds, its next poll returns it at once. It exposes `reply(message_id,
+text)` and `send(to, text, thread_id=None)`. Launch needs
+`claude --dangerously-load-development-channels server:bud-relay-channel`, which shows a
+confirmation dialog, so it is tested interactively; the suite has unit tests. Docs:
+https://code.claude.com/docs/en/channels-reference.md
+
+## Config (`relay.toml`, parsed by `config.py`)
+
+See `relay.example.toml` (package data at `src/bud_relay/relay.example.toml`, which `init` reads
+with `importlib.resources`; the repo root's copy is a symlink to it).
+
+```toml
+[relay]
+public_url = "https://relay.example"      # an origin: no path
+data_dir = "~/.bud-relay"
+forwarded_allow_ips = ["127.0.0.1", "::1"]  # proxies whose X-Forwarded-For is believed
+
+[oauth]
+enabled = true
+owner_key_env = "BUD_RELAY_OWNER_KEY"     # admin only: the admin API and the consent fallback
+dynamic_clients = true                    # /register (DCR) and client metadata documents
+allowed_redirect_hosts = ["claude.ai", "chatgpt.com"]
+
+# Optional: a static client, for a platform that cannot register itself.
+[[oauth.clients]]
+client_id = "bud-relay"                   # claude.ai, "Use your own OAuth client"
+redirect_uris = ["https://claude.ai/api/mcp/auth_callback"]
+agents = ["duet", "claude-cloud"]         # the first is preselected
+
+[agents.duet]
+type = "duet"                             # the rest of the table is the type's options
+
+[agents.claude-cloud]
+type = "claude-cloud"
+via = "duet"                              # a dynamic grant acting as duet may act as this too
+
+[agents.dot]
+type = "dot"
+```
+
+- Each `[agents.<id>]` has a `type`, an optional `description`, an optional `via` (another
+  configured agent; a core key, not passed to the type's factory), and the type's options.
+- `allowed_redirect_hosts` takes host names only (lower-cased; no scheme, port, path or
+  wildcard). `forwarded_allow_ips` takes IP addresses or networks (`172.16.0.0/12`); `serve`
+  runs uvicorn with `proxy_headers=True` and exactly these, never uvicorn's
+  `FORWARDED_ALLOW_IPS` environment variable.
+- A v1 file (any agent with `kind`) is refused with one error that lists every edit: each
+  agent's v2 type, the `dots_bridge` options to drop, the `muse_bridge` `base_url` to rename to
+  `bridge_url`, the legacy `[oauth]` keys to move into `[[oauth.clients]]`, and that the dot
+  then connects with `bud-relay connect dot`.
+- v1's `[oauth] client_id / redirect_uris / default_agent / allowed_agents`, with no
+  `[[oauth.clients]]`, still read as one client (the default agent first). A file with both is
+  refused.
+- Secrets come from environment variables named in the config; the CLI loads a gitignored
+  `.env` beside the config. Data lives in `data_dir`: `relay.sqlite3` (core), `oauth.sqlite3`
+  (`oauth.DB_FILENAME`) and `events.sqlite3` (the dot's subscriptions), in WAL mode, mode 0600.
+- `public_url` must be an origin (`https://host[:port]`, no path): OAuth metadata and the token
+  audience are `<public_url>/mcp`, and plain HTTP is accepted only on loopback. It is stored
+  canonical, as browsers write `Origin` (lower-case host, no default port), via
+  `oauth.canonical_origin`; the consent page compares `Origin` against it. The host must be
+  ASCII: an internationalized name goes in its punycode (`xn--`) form.
+
+## CLI (`bud-relay`)
+
+- `init` writes `relay.toml` and a `.env` (mode 0600) with a fresh owner key and the example's
+  secret env names commented out; it refuses to overwrite.
+- `serve`, `keys create|list|revoke`, `send`, `inbox`, `thread`. `inbox <agent>` peeks like
+  `inbox` with `since=None` without moving the cursor, marks new messages, and prints the
+  unanswered count.
+- `connect <agent-id> [--relay URL] [--no-copy]` makes a pairing code for an OAuth agent, or a
+  new API key for the rest, and prints the agent's steps with it filled in (or, for a type with
+  no steps, what it needs). Without `--relay` it runs the admin operations in process on the
+  relay's data dir and OAuth bundle (`build_relay_oauth`). With `--relay` it calls the admin API
+  with `BUD_RELAY_OWNER_KEY` from the environment or the `.env` beside `--config` (no relay.toml
+  needed), refuses a non-HTTPS URL except to loopback, and canonicalizes it to its origin. A
+  key goes to the clipboard through the first of `pbcopy`, `wl-copy` and `xclip -selection
+  clipboard` that exits 0 (unless `--no-copy`) and is then never printed; otherwise it is
+  printed once. Steps without the placeholder get the code, or the uncopied key, on a line
+  after them.
+- `setup <agent-id> [--callback URL]` is read-only: the same steps, with `{pairing_code}` and
+  `{key_hint}` replaced by a line saying to run `connect`. `--callback` checks the URL with the
+  OAuth provider's own redirect URI rule, then adds it to the `[[oauth.clients]]` entry that
+  lists the agent with a one-line edit, written only if the result parses to the same TOML plus
+  that URI. Otherwise, or when the file cannot be written, it prints the exact line to add.
+- `demo [--no-claude] [--model …]` runs the relay end to end on free local ports with stand-ins
+  from `tests/fakes/`: the dot is a ChatGPT stand-in (`dot_client.py`: OAuth as the ChatGPT
+  client, subscribe, verify the webhook, progress and reply), Muse a muse-bridge jobs fake, and
+  claude-cloud a routine fire fake. claude-code's key comes from `POST /api/admin/keys`, the
+  cloud session replies with no `as_agent`, and a last leg connects duet the new way (a code
+  from `POST /api/admin/pairing-codes`, a DCR client through `oauth.testing.dynamic_flow`) and
+  asks the dot. `demo.Stage(ports=False)` builds the same world in process for the end-to-end
+  tests.
+
+## Tests and checks
+
+`uv run pytest -q` and `uv run ruff check . && uv run ruff format --check .` pass on every
+branch, and `uv run bud-relay demo --no-claude` finishes every round trip. Nothing in the test
+suite touches the network, a real dot, a real Muse or a real routine. Test files are prefixed by
+area: `tests/test_core_*.py`, `tests/test_oauth_*.py`, `tests/test_agent_*.py`,
+`tests/test_events_*.py`, `tests/test_channel_*.py`, `tests/test_e2e_*.py`.
+
+## Out of scope
+
+No claude.ai automation of any kind. No A2A, no Grok, no web UI. No agent types beyond the
+table above.