@extrovert.dev/sdk 0.1.0-pre.3

package/dist/index.d.cts

@@ -0,0 +1,3782 @@
+/**
+ * fetch-based transport for the Extrovert API.
+ *
+ * Runtime-agnostic: uses the global `fetch` (Node 18+, Cloudflare Workers, Vercel Edge, Deno,
+ * browsers). No Node-only APIs, no dependencies. Retries idempotent requests with jittered backoff
+ * on 429/5xx, honors `Retry-After`, and surfaces every failure as a typed {@link ApiError}.
+ */
+/** The library version, surfaced in the User-Agent. Kept in sync with package.json by build. */
+declare const SDK_VERSION = "0.1.0-pre.3";
+interface RetryOptions {
+    /** Max retry attempts for idempotent requests on 429/5xx/network errors. Default 2. */
+    maxRetries: number;
+    /** Base backoff in ms (grows exponentially with jitter). Default 250. */
+    baseDelayMs: number;
+    /** Cap on a single backoff delay. Default 8000. */
+    maxDelayMs: number;
+}
+
+/**
+ * `?include=` relation expansion typing (redesign §5.5 / §6.2).
+ *
+ * Reads may expand a per-resource allowlist of relations (depth ≤ 2); the server
+ * re-applies the same ceiling/ownership filter to every expanded child. The SDK
+ * types the allowed relations per resource so a caller cannot ask for a relation the
+ * server would reject with 400 `bad_request`, and serializes the list as the
+ * comma-separated `?include=` value.
+ */
+/** Relations the `inbox` resource may expand (`?include=agent,domain`). */
+type InboxInclude = "agent" | "domain";
+/** Relations the `review` resource may expand (`?include=category,turns`). */
+type ReviewInclude = "category" | "turns";
+/** Serialize an include list into the comma-separated `?include=` query value. */
+declare function serializeInclude(include?: readonly string[]): string | undefined;
+
+/**
+ * Extrovert API — typed request/response models.
+ *
+ * These mirror the Extrovert V1 REST contract (`/v1`, §8 of the build spec). The Go API does not
+ * exist yet; field shapes here are the source of truth the client codes against and are validated
+ * against fixture data in `src/fixtures.ts`.
+ *
+ * Conventions:
+ * - All identifiers (ids, addresses, domains, keys) are `string` and rendered in mono everywhere.
+ * - Timestamps are RFC 3339 / ISO-8601 strings (`created_at`, `expires_at`, ...).
+ * - The wire format is snake_case to match the Go/OpenAPI surface; this file documents it verbatim.
+ */
+
+/** RFC 3339 / ISO-8601 timestamp, e.g. `2026-06-12T18:04:11Z`. */
+type IsoTimestamp = string;
+/**
+ * A capability scope. The server is the source of truth (counter + revocation); a token carries
+ * its caveats but cannot exceed them (§5).
+ *
+ * The `mailbox:*` scope strings are the live wire contract (stored in issued keys'
+ * caveats) and are NOT renamed despite the public "inbox" product naming — renaming
+ * them would invalidate every key already minted. `domain:manage` gates the domains
+ * plane; `domain:purchase` is additionally required (and is opt-in, default-off) to
+ * buy a new domain (`POST /v1/domains` with `mode: "purchased"`). `review:act` gates
+ * the BYO reviewer decision plane.
+ */
+type Scope = "mailbox:create" | "mailbox:read" | "mailbox:send" | "mailbox:quota" | "mailbox:delete" | "webhook:write" | "domain:manage" | "domain:purchase" | "review:act";
+/** How a Extrovert domain was onboarded (§7). */
+type OnboardingMode = "shared" | "purchased" | "ns_delegated" | "manual";
+/** Lifecycle status of an agent principal. */
+type AgentStatus = "active" | "disabled";
+/** Lifecycle status of an inbox. */
+type InboxStatus = "provisioning" | "live" | "disabled" | "deleted";
+/** Direction of a message relative to the inbox that owns it. */
+type MessageDirection = "inbound" | "outbound";
+/**
+ * Request body for `POST /v1/enroll`. An agent redeems a `pk_enroll_...` token to mint a scoped
+ * agent key. Idempotent on `agent_handle` (à la AgentMail's `client_id`).
+ */
+interface EnrollRequest {
+    /**
+     * The raw enrollment token, format `pk_enroll_<id>_<secret>`. Shown once at issue
+     * time. REQUIRED — this is the wire field the server reads (`json:"token"`); the
+     * request is serialized verbatim, so the field name must match the contract.
+     */
+    token: string;
+    /**
+     * Stable client-chosen handle for this agent. Redeeming twice with the same handle returns the
+     * same agent rather than minting a new one.
+     */
+    agent_handle: string;
+    /** Optional human-readable label for the minted agent. */
+    agent_name?: string;
+    /**
+     * Optional idempotency key (sent as the `Idempotency-Key` header). A retry with
+     * the same key replays the original enrollment response instead of re-minting.
+     */
+    client_id?: string;
+}
+/**
+ * Response from `POST /v1/enroll`. The `agent_key` is the short-lived, per-agent scoped key the
+ * agent uses for all subsequent calls — never an org-wide key (§5, §14).
+ */
+interface EnrollResponse {
+    /** The minted agent principal id, e.g. `agt_7Hq2...`. */
+    agent_id: string;
+    /**
+     * The scoped agent key, format `pk_agent_<id>_<secret>`. Returned once. Treat as a secret and
+     * pass as the `Authorization: Bearer` credential on subsequent requests.
+     */
+    agent_key: string;
+    /** Scopes granted to this key (a subset of the enrollment token's scopes). */
+    scopes: Scope[];
+    /**
+     * The fixed org the minted key is bound to (the token's resolved org). The agent
+     * cannot change it; it is the canonical org for every subsequent call.
+     */
+    org_id?: string;
+    /**
+     * The fixed project the minted key is bound to (the token's resolved project). The
+     * agent cannot change it — there is no mutable project selector for a scoped key.
+     */
+    project_id?: string;
+}
+/** A Extrovert agent principal (read shape). */
+interface Agent {
+    id: string;
+    name: string | null;
+    status: AgentStatus;
+    scopes: Scope[];
+    created_at: IsoTimestamp;
+    metadata: Record<string, string>;
+}
+/**
+ * One arbitrary metadata value stored on an inbox. The wire allows string, number,
+ * or boolean (nested objects and arrays are rejected). In a PATCH (update) body a
+ * value of `null` for a key DELETES that key (the merge/null-delete semantics —
+ * see {@link UpdateInboxRequest.metadata}); a read shape ({@link Inbox.metadata})
+ * never contains `null`.
+ */
+type InboxMetadataValue = string | number | boolean;
+/**
+ * The arbitrary key-value metadata object an agent attaches to an inbox (AgentMail
+ * parity). Caps: ≤256 keys, ≤256 chars per key, ≤256 chars per string value. The
+ * read shape is always an object (`{}` when empty, never null); the PATCH shape
+ * additionally allows per-key `null` to delete a key.
+ */
+type InboxMetadata = Record<string, InboxMetadataValue>;
+/**
+ * The metadata patch shape (create/update bodies): each value may be a
+ * string/number/boolean to set it, or `null` to delete that key on a PATCH.
+ */
+type InboxMetadataPatch = Record<string, InboxMetadataValue | null>;
+/**
+ * Request body for `POST /v1/inboxes`. All fields optional: the default path mints an address on a
+ * pre-warmed, pre-ACS-verified shared subdomain of `smtp.extrovert.dev`, so creation is instant.
+ */
+interface CreateInboxRequest {
+    /**
+     * Desired local part (before the `@`). If omitted, the server generates a random handle.
+     * Example: `agent7` -> `agent7@smtp.extrovert.dev`.
+     */
+    username?: string;
+    /**
+     * Domain to mint on. Must be an org domain the calling key is scoped to. If omitted, the default
+     * shared subdomain is used (zero-config path).
+     */
+    domain?: string;
+    /** Human-readable display name used in the `From:` header on sends. */
+    display_name?: string;
+    /**
+     * Idempotency handle. Re-creating with the same `client_id` returns the existing inbox rather
+     * than minting a duplicate.
+     */
+    client_id?: string;
+    /**
+     * Optional inbound webhook to register at create time (HMAC-signed
+     * `message.received`). This is the wire field the server reads (`json:"webhook_url"`);
+     * the create body is serialized verbatim, so the name must match the contract.
+     */
+    webhook_url?: string;
+    /**
+     * Optional arbitrary key-value metadata to store on the inbox (AgentMail parity).
+     * Values may be a string, number, or boolean; nested objects/arrays are rejected.
+     * Caps: ≤256 keys, ≤256 chars per key, ≤256 chars per string value. Echoed back on
+     * the create response (and replayed verbatim on an idempotent `client_id` retry).
+     */
+    metadata?: InboxMetadata;
+    /**
+     * Optional assertion that must match the key's bound project — NEVER a selector.
+     * A mismatch is a 403. The inbox is always created in the key's stored project;
+     * the assertion only lets a caller defend against a misrouted key.
+     */
+    project_id?: string;
+    /**
+     * Whether to return the inbox credentials (IMAP/SMTP password) in the response. Defaults to
+     * false; credentials are sealed at rest and only surfaced on explicit request.
+     */
+    return_credentials?: boolean;
+}
+/**
+ * Request body for `PATCH /v1/inboxes/{addr}`. Cheap, in-place inbox settings an
+ * owning agent may change without delete+recreate. Every field is optional; an
+ * omitted field leaves the stored value untouched (PATCH semantics).
+ */
+interface UpdateInboxRequest {
+    /**
+     * New sender display / `From` name, propagated to the inbox and the authenticated sender.
+     * An empty string falls back to the address local-part at the mail layers.
+     */
+    display_name?: string;
+    /** Replace the inbox's inbound webhook target. An empty string clears it. */
+    webhook_url?: string;
+    /**
+     * Set this inbox's effective rolling-24-hour recipient cap. Must be an integer
+     * from 1 through 10,000. Updating this field requires the opt-in
+     * `mailbox:quota` scope; the other mutable fields do not.
+     */
+    daily_send_limit?: number;
+    /**
+     * Patch the inbox's arbitrary metadata (AgentMail parity). Shallow merge:
+     * - omitting `metadata` entirely leaves the stored metadata unchanged;
+     * - an object MERGES into the existing metadata (set/overwrite the given keys);
+     * - a key whose value is `null` DELETES that key;
+     * - the top-level value `null` CLEARS all metadata (the response then carries `{}`).
+     *
+     * Values may be a string, number, or boolean; nested objects/arrays are rejected;
+     * the same ≤256 key/length caps as create apply.
+     */
+    metadata?: InboxMetadataPatch | null;
+    /**
+     * Optional assertion that must match the key's bound project — NEVER a selector.
+     * A mismatch is a 403.
+     */
+    project_id?: string;
+}
+/**
+ * IMAP/SMTP connection config + login for an inbox, only present when
+ * `return_credentials` was requested. (The IMAP/SMTP host/port/password are mail
+ * protocol internals — the "credentials" of the underlying mailbox.)
+ */
+interface InboxCredentials {
+    imap_host: string;
+    imap_port: number;
+    smtp_host: string;
+    smtp_port: number;
+    username: string;
+    /** Plaintext password — shown once, never re-retrievable. Treat as a secret. */
+    password: string;
+}
+/** A provisioned inbox (read shape). */
+interface Inbox {
+    /**
+     * Resource type discriminator. Always `"inbox"` on the redesigned surface (RFC D9:
+     * every resource carries `object` + `org_id` + `project_id` + timestamps). Optional
+     * for back-compat with legacy/mock shapes that omit it.
+     */
+    object?: "inbox";
+    /**
+     * The canonical OPAQUE inbox id and path key (`/v1/inboxes/{inbox_id}` /
+     * `/v1/projects/{project_id}/inboxes/{inbox_id}`). Treat it as opaque — do not parse
+     * the `pmbx_` prefix.
+     */
+    id: string;
+    /**
+     * The fixed org this inbox belongs to (RFC D9). Optional for legacy/mock shapes.
+     */
+    org_id?: string;
+    /**
+     * The project this inbox belongs to (RFC D9) — the partition key. Optional for
+     * legacy/mock shapes.
+     */
+    project_id?: string;
+    /** Full address, e.g. `agent7@smtp.extrovert.dev`. A within-project email alias for {@link Inbox.id}. */
+    address: string;
+    username: string;
+    domain: string;
+    display_name: string | null;
+    status: InboxStatus;
+    /** Onboarding mode of the domain this inbox lives on. */
+    onboarding_mode: OnboardingMode;
+    /** Agent that owns this inbox, if minted by an agent key. */
+    agent_id: string | null;
+    /** Effective enforced rolling-24-hour recipient cap for this inbox. */
+    daily_send_limit: number;
+    /**
+     * Inbound webhook registered for this inbox, if any. The wire field is
+     * `webhook_url` (the server returns `webhook_url`, never `inbound_webhook_url`);
+     * absent/omitted when no webhook is set.
+     */
+    webhook_url?: string | null;
+    /**
+     * Arbitrary key-value metadata stored on the inbox (AgentMail parity). Always an
+     * object — `{}` when none is set, never null. Values are string, number, or
+     * boolean. Project-scoped: an agent key only reads/mutates metadata for inboxes in
+     * its bound project.
+     */
+    metadata: InboxMetadata;
+    created_at: IsoTimestamp;
+    /**
+     * The RESOLVED {@link ReviewPolicy} for THIS inbox: the per-inbox override,
+     * else the account default, else the `require_review` floor.
+     *
+     * Present on the SINGLE-inbox read only; the list response omits it, because
+     * populating it per row would be one settings read per row for a value that is
+     * identical across every inbox in the org.
+     */
+    effective_review_policy?: ReviewPolicy;
+    /** Present only on the create response when `return_credentials` was requested. */
+    credentials?: InboxCredentials;
+}
+/** Query params for `GET /v1/inboxes`. */
+interface ListInboxesParams {
+    /** Filter to a single domain. */
+    domain?: string;
+    status?: InboxStatus;
+    /** Max items to return (server caps this). */
+    limit?: number;
+    /** Opaque cursor from a previous page's `next_cursor`. */
+    cursor?: string;
+}
+/**
+ * Query params for the canonical project-prefixed inbox list
+ * (`GET /v1/projects/{project_id}/inboxes`, the `x.projects.inboxes.list` chain).
+ * Returns the {@link List} envelope with opaque cursors. `include` expands the
+ * per-resource relation allowlist (`agent`, `domain`; depth ≤ 2).
+ */
+interface ProjectInboxListParams {
+    /** Page size (server clamps to 1–100; default 50). */
+    limit?: number;
+    /** Opaque cursor from a prior page's `next_cursor`. */
+    cursor?: string;
+    /** Relation expansions (`["agent","domain"]`) serialized to `?include=agent,domain`. */
+    include?: InboxInclude[];
+}
+/** Query params for the project-prefixed single-inbox read (`include=` expansion). */
+interface GetInboxParams {
+    /** Relation expansions (`["agent","domain"]`). */
+    include?: InboxInclude[];
+}
+/**
+ * A page of results. This is the canonical envelope shared by Go + MCP + SDK:
+ * `items` holds the page, `total` the full match count, and `next_cursor` the
+ * opaque cursor (an offset) to fetch the next page (absent on the last page).
+ */
+interface Page<T> {
+    items: T[];
+    /** Total count when the server can compute it cheaply. */
+    total: number;
+    /** Cursor to pass as `cursor` to fetch the next page; absent when exhausted. */
+    next_cursor?: string;
+}
+/** An email address with an optional display name. */
+interface EmailAddress {
+    email: string;
+    name?: string | null;
+}
+/**
+ * A message attachment (metadata; bytes fetched separately by id). Mirrors the
+ * canonical Go wire shape (`attachmentResponse`): `id` is the opaque attachment
+ * id addressing one MIME part of the message; `size` is the decoded byte length.
+ */
+interface Attachment {
+    id: string;
+    filename: string;
+    content_type: string;
+    /** Decoded byte length of the attachment. */
+    size: number;
+}
+/**
+ * An outbound attachment on send / reply. `content_base64` is the standard
+ * base64 encoding of the file bytes. Mirrors the Go `attachmentRequest`.
+ */
+interface AttachmentInput {
+    filename: string;
+    content_type: string;
+    /** Standard base64 of the raw file bytes. */
+    content_base64: string;
+}
+/**
+ * A stored message in an inbox (read shape). Mirrors the canonical Go wire shape
+ * (`messageResponse`): `id` is the opaque, inbox-resolvable id; `inbox` is the
+ * owning address; `seen` is the native IMAP \Seen read state (Extrovert has no
+ * Gmail-style labels — read/unread is the \Seen flag); `folder` is the IMAP
+ * mailbox; `date` is the raw `Date` header.
+ */
+interface Message {
+    id: string;
+    thread_id: string;
+    /** Owning inbox address. */
+    inbox: string;
+    direction: MessageDirection;
+    from: EmailAddress;
+    to: EmailAddress[];
+    cc?: EmailAddress[];
+    subject: string;
+    /** Decoded text/plain MIME alternative; null when absent and never derived from HTML. */
+    text: string | null;
+    /** Decoded text/html MIME alternative; null when absent and never synthesized from text. */
+    html?: string | null;
+    /** Best-effort derivative of text; null when unavailable and never authoritative. */
+    extracted_text?: string | null;
+    /** Best-effort derivative of html; null when unavailable and never authoritative. */
+    extracted_html?: string | null;
+    /** RFC 5322 `Message-ID` header value. */
+    message_id: string;
+    /** IMAP folder the message lives in (e.g. `INBOX`, `Junk`). */
+    folder?: string;
+    /** Whether the message has been read (native IMAP \Seen flag). */
+    seen: boolean;
+    /** Raw `Date` header / received timestamp. */
+    date: string;
+}
+/**
+ * Query params for `GET /v1/inboxes/{addr}/messages`. The server applies
+ * exact-field substring filters (from/to/subject) and an `unread` filter
+ * (native \Seen), and pages with limit + offset (cursor is an offset).
+ */
+interface ListMessagesParams {
+    /** Substring match on subject. */
+    subject?: string;
+    /** Substring match on sender address. */
+    from?: string;
+    /** Substring match on a recipient address. */
+    to?: string;
+    /** Only return unread messages (\Seen flag clear). */
+    unread?: boolean;
+    limit?: number;
+    /** Number of messages to skip (paging). */
+    offset?: number;
+    /** Opaque cursor from a previous page's `next_cursor` (an offset). */
+    cursor?: string;
+}
+/** Query params for `GET /v1/inboxes/{addr}/messages/search`. */
+interface SearchMessagesParams {
+    /** Full-text query (matched against from/subject/body via IMAP SEARCH). */
+    q: string;
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+}
+/** Request body for `PATCH /v1/inboxes/{addr}/messages/{id}` — read-state toggle. */
+interface MarkReadRequest {
+    /** true to set the \Seen flag (read), false to clear it (unread). */
+    read: boolean;
+}
+/** A folder a batch update may move messages to. */
+type MailFolder = "INBOX" | "Sent" | "Trash" | "Junk" | "Archive";
+/**
+ * Request body for `PATCH /v1/inboxes/{addr}/messages/batch`: apply a read-state
+ * toggle and/or a folder move to a list of message ids that all belong to the
+ * inbox. At least one of `read` / `folder` must be set.
+ */
+interface BatchUpdateMessagesRequest {
+    /** Opaque message ids (msg_…), all owned by the inbox. Max 200. */
+    ids: string[];
+    /** When set, set (true) or clear (false) the \Seen flag on each id. */
+    read?: boolean;
+    /** When set, move each message to this folder. */
+    folder?: MailFolder;
+}
+/** Per-id outcome of a batch update: `updated` succeeded, `failed` were skipped. */
+interface BatchUpdateResult {
+    updated: string[];
+    failed: string[];
+}
+/**
+ * Outcome of a message or thread delete. `expunged` is true when removed
+ * permanently, false when moved to Trash; `count` is the number of messages
+ * affected (1 for a message, the thread size for a thread).
+ */
+interface DeleteResult {
+    id: string;
+    deleted: true;
+    expunged: boolean;
+    count: number;
+}
+/** Request body for `POST /v1/inboxes/{addr}/send`. */
+interface SendRequest {
+    /** A single address or a list; the SDK normalizes it to an array on the wire. */
+    to: string | string[];
+    subject: string;
+    /**
+     * The plain-text body. This is the CANONICAL wire name (matching
+     * {@link ReplyRequest.text}, {@link ForwardRequest.text} and
+     * {@link Message.text}); the server also accepts a deprecated `body` alias for
+     * already-deployed callers, which the SDK never emits. At least one of `text` /
+     * `html` is required.
+     */
+    text?: string;
+    html?: string;
+    /** A single address or a list; normalized to an array on the wire. */
+    cc?: string | string[];
+    /** A single address or a list; normalized to an array on the wire. */
+    bcc?: string | string[];
+    /** Override the `Reply-To` header. */
+    reply_to?: string;
+    /**
+     * Idempotency key — a replay with the same key returns the first response
+     * instead of sending a second message.
+     *
+     * Sent as the `Idempotency-Key` HEADER and STRIPPED from the JSON body: the
+     * server hashes the raw body to detect a key reused with different content, so
+     * a key that rode along inside the body would be part of its own replay hash.
+     */
+    idempotency_key?: string;
+    /** Custom headers to attach (e.g. `List-Unsubscribe`). */
+    headers?: Record<string, string>;
+    /** Files to attach (base64). Emitted as a multipart/mixed message. */
+    attachments?: AttachmentInput[];
+    /**
+     * Review Loop (HITL): `review` (default per policy) routes the message into the
+     * human-review queue; `direct` requests an immediate send. The account/inbox
+     * review policy may downgrade `direct` to `review`. Setting any of
+     * mode/intent/category_id opts the send into the Review Loop.
+     */
+    mode?: ReviewMode;
+    /** Intent for the human reviewer. Required when the resolved mode is review (D3). */
+    intent?: ReviewIntent;
+    /** Opaque category id (cat_…) matched from the registry; never a name. */
+    category_id?: string;
+    /**
+     * Agent-supplied confidence (0..1) in the category match. Feeds the submit-time
+     * min_confidence auto-send gate ONLY; the server never scores ($0 LLM). Below the
+     * effective threshold (or omitted when a threshold is set) the would-be auto-send
+     * routes to needs_review with gate_outcome `held:low_confidence`.
+     */
+    category_confidence?: number;
+}
+/**
+ * Request body for the canonical thread-aware reply,
+ * `POST /v1/inboxes/{addr}/reply`. Exactly one of `thread_id` / `message_id`
+ * selects the parent; the server derives `to` (original participants), the
+ * `Re:`-prefixed subject, and the `In-Reply-To` / `References` headers — you do
+ * NOT pass `to`. Set `reply_all` to reply to every thread recipient.
+ */
+interface ReplyRequest {
+    /** Reply to the latest message in this thread. One of thread_id / message_id. */
+    thread_id?: string;
+    /** Reply to this specific message. One of thread_id / message_id. */
+    message_id?: string;
+    /** At least one of `text` / `html` is required. */
+    text?: string;
+    html?: string;
+    cc?: string | string[];
+    bcc?: string | string[];
+    /** Override the `Reply-To` header. */
+    reply_to?: string;
+    /** Reply to all thread recipients, not just the original sender. */
+    reply_all?: boolean;
+    /** See {@link SendRequest.idempotency_key} — sent as a header, never in the body. */
+    idempotency_key?: string;
+    headers?: Record<string, string>;
+    /** Files to attach (base64). Emitted as a multipart/mixed message. */
+    attachments?: AttachmentInput[];
+    /** Review Loop assertion (see {@link SendRequest.mode}). */
+    mode?: ReviewMode;
+    /** Intent for the human reviewer. Required when the resolved mode is review (D3). */
+    intent?: ReviewIntent;
+    /** Opaque category id (cat_…) matched from the registry. */
+    category_id?: string;
+    /** Agent-supplied confidence (0..1); see {@link SendRequest.category_confidence}. */
+    category_confidence?: number;
+}
+/**
+ * Request body for `POST /v1/inboxes/{addr}/messages/{id}/forward`. Re-sends the
+ * referenced message to new recipients, preserving the original content.
+ *
+ * A forward is governed by the SAME review policy as a send, and for a stronger
+ * reason: it is an outbound message to arbitrary NEW recipients that quotes an
+ * entire inbound thread. Leaving it outside the policy would have made forward
+ * the documented bypass — and a worse one than a bare send, because it
+ * exfiltrates a received conversation.
+ */
+interface ForwardRequest {
+    /** A single address or a list; normalized to an array on the wire. */
+    to: string | string[];
+    /** Additional recipients on the forward, screened by the same pre-flight as `to`. */
+    cc?: string | string[];
+    /** Blind recipients on the forward. Never rendered as a header. */
+    bcc?: string | string[];
+    /** Optional note prepended to the forwarded content. */
+    text?: string;
+    /**
+     * Accepted and IGNORED by the server. The forwarded content is a plain-text
+     * quote of the parent; emitting an HTML alternative would show HTML-capable
+     * clients the note WITHOUT the forwarded thread.
+     */
+    html?: string;
+    /** Review Loop assertion (see {@link SendRequest.mode}). */
+    mode?: ReviewMode;
+    /** Intent for the human reviewer. Required when the resolved mode is review (D3). */
+    intent?: ReviewIntent;
+    /** Opaque category id (cat_…) matched from the registry. */
+    category_id?: string;
+    /** Agent-supplied confidence (0..1); see {@link SendRequest.category_confidence}. */
+    category_confidence?: number;
+    /** See {@link SendRequest.idempotency_key} — sent as a header, never in the body. */
+    idempotency_key?: string;
+}
+/**
+ * The LEGACY immediate-send 202 body, returned when a caller mentioned nothing
+ * about the review loop and the resolved policy permitted a direct send.
+ *
+ * Its shape differs per verb, which is why almost every field is optional and
+ * this type is NOT the whole story (see {@link SendOutcome}):
+ *
+ *  - `send`          → `{status:"sent", message_id, review_id}` — **no `thread_id`**.
+ *  - `reply`/`forward` → `{message_id, thread_id, review_id}` — no `status`.
+ *
+ * `thread_id` was declared REQUIRED here for a long time while the send path
+ * never returned one, so `res.thread_id` typechecked and was `undefined` at
+ * runtime. It is optional now because that is the truth.
+ */
+interface SendResult {
+    /**
+     * Discriminant hole. This legacy body carries NO `kind` field, unlike the two
+     * review-loop bodies it shares a union with; declaring it as absent is what
+     * lets `if (res.kind === "queued_for_review")` narrow a {@link SendOutcome}.
+     */
+    kind?: undefined;
+    /** Extrovert message id of the sent outbound message. */
+    message_id: string;
+    /** Thread id — present on reply/forward; ABSENT on the direct-send response. */
+    thread_id?: string;
+    /**
+     * Opaque review id (rr_…) of the review row that governed this send. Every
+     * agent-plane send now creates one, so an agent that crashed after issuing the
+     * request can still call `reviews.get(id)` and read `closed` / `sent_message_id`
+     * instead of guessing whether the message went out.
+     */
+    review_id?: string;
+    /** RFC 5322 `Message-ID` header assigned by the sender, when known. */
+    message_id_header?: string;
+    status?: "queued" | "sent";
+    created_at?: IsoTimestamp;
+}
+/**
+ * Every shape `inbox.send()` / `.reply()` / `.forward()` / `.submitForReview()`
+ * can return, discriminated by `kind`.
+ *
+ * There are three, because the resolved review policy — not the caller — decides
+ * what happens to an outbound message:
+ *
+ *  - {@link QueuedForReviewResult} (`kind:"queued_for_review"`, 202) — parked for
+ *    a human. **Nothing has been delivered yet.** Monitor
+ *    `reviewEvents.wait({review_id})` until a `sent` or `send_failed` event
+ *    arrives.
+ *  - {@link SentResult} (`kind:"sent"`, 200) — delivered immediately, returned to
+ *    callers that opted into the review loop by passing mode/intent/category_id.
+ *  - {@link SendResult} (no `kind`, 202) — the legacy immediate-send body for a
+ *    caller that mentioned none of those fields.
+ *
+ * Under the default `require_review` policy a send WITHOUT an `intent` does not
+ * return any of these: it raises `IntentRequiredError` (422) and nothing is sent
+ * or queued. Use {@link isQueuedForReview} / {@link sentMessageIdOf} from
+ * `send-result.js` rather than reaching for a field that may not be there.
+ */
+type SendOutcome = SendResult | SentResult | QueuedForReviewResult;
+/** Per-send agent assertion (D3/D6). The resolved policy may downgrade `direct`. */
+type ReviewMode = "review" | "direct";
+/**
+ * The account/inbox review policy — the AUTHORITY on what happens to an outbound
+ * message. There is no way for a caller to opt out of it.
+ *
+ *  - `require_review` — the default for every account. A send WITHOUT an `intent`
+ *    is rejected 422 `intent_required` (nothing sent, nothing queued); a send
+ *    WITH one is queued for a human (202 `queued_for_review`).
+ *  - `allow_direct` — a bare send (no mode/intent/category_id) is delivered
+ *    immediately. Supplying an intent, or `mode: "review"`, still queues it.
+ *  - `auto_send_graduated` — a categorized message that clears the graduation
+ *    gates auto-sends; everything else is queued.
+ *
+ * Read {@link Inbox.effective_review_policy} once before your first send rather
+ * than learning the policy by being refused.
+ */
+type ReviewPolicy = "require_review" | "allow_direct" | "auto_send_graduated";
+/** Review-request state machine (spec §3.1). */
+type ReviewState = "needs_review" | "in_review" | "chatting" | "stale" | "approved" | "sent" | "auto_sent" | "rejected" | "stalled" | "cancelled" | "failed";
+/** The agent's "for the human reviewer" intent (spec §11). */
+interface ReviewIntent {
+    summary: string;
+    meta?: {
+        goal?: string;
+        recipient?: string;
+        prior_touches?: number;
+        urgency?: string;
+    };
+}
+/** A review request (rr_…) — the pre-send record under the Review Loop. */
+interface Review {
+    id: string;
+    state: ReviewState;
+    mode: ReviewMode;
+    effective_mode: ReviewMode;
+    kind: "send" | "reply" | "forward";
+    from_address: string;
+    agent_id: string;
+    category_id?: string;
+    intent_summary: string;
+    intent_meta?: Record<string, unknown>;
+    revision: number;
+    version: number;
+    proposed_subject: string;
+    proposed_body_text: string;
+    proposed_body_html?: string;
+    proposed_to: string[];
+    proposed_cc?: string[];
+    proposed_bcc?: string[];
+    sent_subject?: string;
+    sent_body_text?: string;
+    diff_unified?: string;
+    sent_message_id?: string;
+    gate_outcome?: string;
+    stale_reason?: string;
+    decision_feedback?: string;
+    /**
+     * The DEFINITIVE per-review "am I done?" answer, and the poll-side companion to
+     * the terminal review events. True for `sent`, `auto_sent`, `cancelled` **and
+     * `failed`**.
+     *
+     * `failed` is included deliberately even though it is not in the formal
+     * terminal set: nothing in the product can move a failed review — the console
+     * cannot re-approve it — so a flag that said `false` there would invite an
+     * agent to wait forever on a row nobody will ever touch.
+     *
+     * An agent that lost its event cursor (a crash, a fresh process) reads this
+     * instead of guessing from the state string.
+     */
+    closed?: boolean;
+    /**
+     * The vendor-scrubbed delivery failure, present on a failed review. Until this
+     * field existed an agent could learn THAT its message failed and never WHY.
+     */
+    send_error?: string;
+    /**
+     * How the message was released, once sent: `human_reviewed`,
+     * `reviewer_approved`, `graduated_auto` or `agent_direct` — without a turns
+     * fetch.
+     */
+    send_path?: string;
+    created_at: IsoTimestamp;
+    updated_at: IsoTimestamp;
+    decided_at?: IsoTimestamp;
+    sent_at?: IsoTimestamp;
+}
+/** One immutable turn in a review's append-only thread (turn_…). */
+interface ReviewTurn {
+    id: string;
+    seq: number;
+    turn_type: string;
+    actor_kind: "agent" | "human" | "review_agent" | "system";
+    actor_id?: string;
+    body?: string;
+    revision?: number;
+    diff_json?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    created_at: IsoTimestamp;
+}
+/** Filters for listing review requests (spec §5.2). */
+interface ListReviewsParams {
+    state?: ReviewState | ReviewState[];
+    category_id?: string;
+    inbox?: string;
+    limit?: number;
+    page?: string;
+}
+/** One human/agent comment in the assembled review feedback (spec §11). */
+interface ReviewFeedbackComment {
+    turn_id: string;
+    actor_kind: "agent" | "human" | "review_agent" | "system";
+    actor_id?: string;
+    body: string;
+    created_at: IsoTimestamp;
+}
+/**
+ * The human's assembled feedback for a review (spec §11), returned by
+ * `reviews.feedback(id)`: the unified + structured diff of the human edit, the human
+ * comments / rejection feedback, the decision, and the rules born from this review
+ * (rule_ ids whose source_review_id is this review). $0 LLM — pure assembly.
+ */
+interface ReviewFeedback {
+    review_id: string;
+    decision: string;
+    diff_unified?: string;
+    diff_json?: Record<string, unknown>;
+    comments: ReviewFeedbackComment[];
+    new_rules: string[];
+}
+/** Body for posting a chat turn on a review's thread (spec §5.2; M5). */
+interface PostReviewChatRequest {
+    /** The agent's question/comment for the human reviewer. */
+    text: string;
+}
+/**
+ * Body for posting a new agent draft under a parent_revision CAS (spec §5.2; M5,
+ * D17). parent_revision is the PRIMARY CAS — it must equal the draft's current
+ * revision, else 409 STALE with NO mutation. version is OPTIONAL belt-and-suspenders.
+ */
+interface SubmitRevisionRequest {
+    parent_revision: number;
+    version?: number;
+    subject?: string;
+    /**
+     * The redrafted plain-text body. Canonical, matching `text` on send / reply /
+     * forward — the same concept should not have two names in the one flow an
+     * agent runs most.
+     */
+    text?: string;
+    /**
+     * @deprecated Permanent alias for {@link SubmitRevisionRequest.text}. Kept
+     * forever so existing callers never break. Sending both with DIFFERENT values
+     * is rejected 400 `conflicting_alias`; the server decides, so both are
+     * forwarded verbatim rather than resolved client-side.
+     */
+    body?: string;
+    html?: string;
+    built_at?: IsoTimestamp;
+    rules_version_seen?: number;
+    /**
+     * REPLACES the draft's attachments. Omit the field to leave them untouched;
+     * send an empty array to clear them.
+     *
+     * Without this a redraft could never restore an attachment, so an agent that
+     * redrafted after reviewer feedback would ship a message the human reviewed
+     * WITH a file and the recipient received without one.
+     */
+    attachments?: AttachmentInput[];
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    idempotency_key?: string;
+}
+/**
+ * The reason a durable review nudge was enqueued (spec §4.5). The agent branches
+ * on it to decide what to do (redraft, learn, re-check a category, …).
+ */
+type ReviewEventReason = 
+/** Redraft via `submit_revision` (a reviewer rejected, escalated, or swept it). */
+"redraft_requested"
+/** A HUMAN added chat/feedback. Answer it, or redraft. (An agent's own question emits none.) */
+ | "feedback_added"
+/** Re-check the draft's category assignment. */
+ | "recheck_category"
+/** A rule changed. Re-read the rules, then redraft or `restamp_review`. */
+ | "rule_changed"
+/** A newly general rule now applies to your drafts. */
+ | "propagate_general_rule"
+/** A human rejected the draft. Learn from the feedback; redraft or stop. */
+ | "rejected"
+/** Delivered. `payload` carries `message_id`, `send_path`, `sent_at`. */
+ | "sent"
+/**
+ * Delivery failed. `payload.error` is the scrubbed reason and
+ * `payload.agent_retryable` is `false`: the only edge out of `failed` is
+ * cancel, so compose and submit a NEW message rather than retrying this one.
+ */
+ | "send_failed"
+/** Withdrawn — by you, by a human, or as the close-out of a failed send. */
+ | "cancelled"
+/**
+ * You were front-run: the review reached a terminal state while you were
+ * trying to act on it, so your `submit_revision` / `post_review_chat` /
+ * `cancel_review` answered 409 `terminal`. STOP retrying that review.
+ */
+ | "front_run_next"
+/** RESERVED — never emitted. Terminal success is `sent`. */
+ | "approved"
+/** RESERVED — no production producer (the D13 staleness detector is unbuilt). */
+ | "staleness";
+/**
+ * One durable review nudge (ndg_…) drained from the AUTHORITATIVE liveness queue
+ * (spec §11). `seq` is the per-review monotonic ordinal the ack cursor advances
+ * against (0 for a broadcast nudge). Opaque typed ids only (D10).
+ */
+interface ReviewEvent {
+    seq: number;
+    id: string;
+    reason: ReviewEventReason;
+    review_id?: string;
+    category_id?: string;
+    payload?: Record<string, unknown>;
+    created_at: IsoTimestamp;
+}
+/** The agent's per-(agent, review) ack frontier — its strict-FIFO position. */
+interface ReviewEventCursor {
+    review_id: string;
+    last_acked_seq: number;
+}
+/** Drain result for list/wait — un-acked events in FIFO seq order + cursors. */
+interface ReviewEventsResult {
+    events: ReviewEvent[];
+    cursors?: ReviewEventCursor[];
+}
+/** Filters for draining review events (spec §5.9 list_review_events). */
+interface ListReviewEventsParams {
+    /** Restrict the drain to one review's events (rr_…). */
+    review_id?: string;
+    /** Max events to return in one drain. */
+    limit?: number;
+}
+/**
+ * A category (cat_…) in the Review Loop registry (D9/D10). `name` + `description`
+ * are skill-style metadata the agent fuzzy-matches against; nothing keys on the
+ * name (renames never break a reference). Categories are CUSTOMER-scoped and
+ * agent-attributed — the deliberate cross-agent-404 exception. Opaque ids only.
+ */
+interface Category {
+    id: string;
+    name: string;
+    description: string;
+    scope: "org_shared" | "agent_private";
+    state: "supervised" | "auto_notify" | "auto_silent";
+    /** Survivor id when this category was merged / soft-deleted (cat_…). */
+    merged_into?: string;
+    created_by_agent_id?: string;
+    author_kind: "agent" | "human";
+    rule_high_water: number;
+    rules_version: number;
+    created_at: IsoTimestamp;
+    updated_at: IsoTimestamp;
+}
+/** Browse filter for the category registry (spec §5.5). */
+interface ListCategoriesParams {
+    /** Pure lexical substring filter over name+description (every token must match; NO LLM). */
+    match?: string;
+}
+/** Propose a new category (spec §5.5; D9). */
+interface ProposeCategoryRequest {
+    name: string;
+    description?: string;
+    /** Defaults to org_shared server-side. */
+    scope?: "org_shared" | "agent_private";
+}
+/** Rename / re-describe a category — metadata only (spec §5.5; D10). */
+interface UpdateCategoryRequest {
+    name?: string;
+    description?: string;
+}
+/**
+ * The account-wide default risk dial (Review Loop, D4/D12) — the values a per-
+ * category null override inherits. The single user-configurable brand-risk lever.
+ */
+interface AccountRiskDial {
+    min_confidence: number;
+    first_contact_gate: boolean;
+    drift_demote_after: number;
+    canary_rate: number;
+    graduate_min_approvals: number;
+    graduate_min_age_hours: number;
+    auto_send_cap_per_day: number;
+}
+/** The RESOLVED risk dial for a category: account default with per-category override applied (D12). */
+interface EffectiveRiskDial {
+    min_confidence: number;
+    first_contact_gate: boolean;
+    drift_demote_after: number;
+    canary_rate: number;
+    graduate_min_approvals: number;
+    graduate_min_age_hours: number;
+    auto_send_cap_per_day: number;
+}
+/**
+ * One category's risk-dial OVERRIDE columns (null = inherit the account default;
+ * D12) alongside the resolved effective dial.
+ */
+interface CategoryRiskDial {
+    category_id: string;
+    min_confidence: number | null;
+    first_contact_gate: boolean | null;
+    drift_demote_after: number | null;
+    canary_rate: number | null;
+    graduate_min_approvals: number | null;
+    graduate_min_age_hours: number | null;
+    effective: EffectiveRiskDial;
+}
+/**
+ * The effective risk dial (Review Loop, agent plane; D4/D12): the account default
+ * plus every category's overrides. Read-only for agents — flipping the dial is a
+ * console (human) action (D16).
+ */
+interface RiskDial {
+    account: AccountRiskDial;
+    categories: CategoryRiskDial[];
+}
+/**
+ * The graduation gate status toward the NEXT rung (Review Loop, D16): clean approvals
+ * (N / needed), category age, the maturity gate (auto_silent precondition), drift vs
+ * K, and whether a human graduate would succeed right now. Read-only.
+ */
+interface GraduationStatus {
+    category_id: string;
+    state: "supervised" | "auto_notify" | "auto_silent";
+    /** The rung a graduate would move to (empty if none). */
+    next_state: string;
+    never_graduate: boolean;
+    clean_approval_count: number;
+    graduate_min_approvals: number;
+    approvals_met: boolean;
+    age_hours: number;
+    graduate_min_age_hours: number;
+    age_met: boolean;
+    maturity_gate_met: boolean;
+    drift_count: number;
+    drift_demote_after: number;
+    can_graduate: boolean;
+}
+/** Record a graduation request (spec §5.6; D16/D6). evidence is opaque agent context. */
+interface ProposeGraduationRequest {
+    evidence?: Record<string, unknown>;
+}
+/**
+ * The D19/§8 re-stamp-without-redraft escape valve ($0). The agent asserts it reviewed
+ * the draft against rules `against_version` and no change is needed; the server
+ * advances the draft's composed_* rules-versions WITHOUT a new draft. against_version
+ * must not exceed the category's current rules-version.
+ */
+interface RestampReviewRequest {
+    /** The category rules-version the agent reviewed against (≤ the current version). */
+    against_version: number;
+    /** Optional: re-stamp the house-style axis to this version (≤ the current version). */
+    house_style_version?: number;
+    /** Stable retry key, sent as Idempotency-Key and never in the JSON body. */
+    idempotency_key?: string;
+}
+/** The reviewer's decision verb (BYO review-agent plane; D5/§9). */
+type ReviewerAction = "approve" | "edit" | "reject" | "escalate";
+/**
+ * The REVIEWER's read-only decision surface for a review (BYO review-agent plane;
+ * D5/§9), returned by `reviews.decisionContext(id)`: the intent + current draft + the
+ * append-only thread + the two-circuit-breaker budget. `force_to_human` is true when
+ * EITHER breaker has tripped — the reviewer's next reject would be FORCED to the human
+ * regardless of intent (the human is the only terminal authority, D17).
+ */
+interface ReviewDecisionContext {
+    review: Review;
+    turns: ReviewTurn[];
+    /** Circuit breaker (a): reviewer hand-backs so far. */
+    hop_count: number;
+    /** Circuit breaker (a): the ceiling; at hop_count ≥ max_hops the next action is forced to the human. */
+    max_hops: number;
+    /** Circuit breaker (b): the hard per-review wall-clock deadline (created_at + review_deadline_s). */
+    review_deadline: IsoTimestamp;
+    /** Breaker (b) tripped. */
+    deadline_passed: boolean;
+    /** Breaker (a) tripped. */
+    hops_exhausted: boolean;
+    /** Either breaker tripped: a reject is overridden to a human escalation. */
+    force_to_human: boolean;
+    /** The tripped breaker (max_hops_reached | review_deadline_passed). */
+    force_reason?: string;
+}
+/**
+ * Body for a reviewer decision (`reviews.decide(id, req)`; reviewer_decide, D5/§9).
+ * `action` is approve|edit|reject|escalate. `revision`/`version` are the optimistic CAS
+ * — a mismatch is a 409 STALE with NO mutation (the human always wins, D17). subject/
+ * body carry the edited content for the edit action; feedback is the reviewer's note.
+ */
+interface ReviewerDecisionRequest {
+    action: ReviewerAction;
+    /** The revision you decided against (PRIMARY CAS; 409 STALE on mismatch). */
+    revision: number;
+    /** Optional row-version CAS (defense in depth). */
+    version?: number;
+    /** Edited subject (edit action). */
+    subject?: string;
+    /** Edited body text (edit action). */
+    body?: string;
+    /** Reviewer note (reject: the rule-birth signal; escalate: the human-facing reason). */
+    feedback?: string;
+}
+/**
+ * The outcome of a reviewer decision (D5/§9). `kind=sent` when the platform ACS-sent
+ * with the COMPOSER's creds (approve/edit — the reviewer NEVER holds mailbox:send);
+ * `kind=sent_to_human` when the draft returned to the human queue (reject/escalate, or
+ * a reject FORCED to the human by a circuit breaker, with `forced_by_breaker` naming it).
+ */
+interface ReviewerDecisionResult {
+    kind: "sent" | "sent_to_human";
+    review: Review;
+    sent: boolean;
+    message_id?: string;
+    thread_id?: string;
+    sent_to_human: boolean;
+    forced_by_breaker?: string;
+}
+/**
+ * The D19/§8 backlog-reconciliation snapshot for a category (agent-readable, $0-LLM).
+ * Counts the QUEUED drafts that are stale vs current-enough against the current
+ * category rules-version + house-style version (a pure integer compare). Read-only —
+ * the agent READS the picture; the human / hooks TRIGGER the actual sweep.
+ */
+interface ScanBacklogStatus {
+    category_id: string;
+    state: "supervised" | "auto_notify" | "auto_silent" | "probation";
+    /** Drafts in the human queue (needs_review|in_review|chatting). */
+    queued: number;
+    /** Of the queued, how many are within tolerance of the current rules-version. */
+    current_enough: number;
+    /** Of the queued, how many were composed under older rules and need a redraft. */
+    stale: number;
+    current_category_rules_version: number;
+    current_house_style_version: number;
+    /** How many versions behind current a draft may be and still count current-enough. */
+    staleness_tolerance: number;
+}
+/** One queued draft's pacing classification relative to the cursor + window (§8). */
+interface PacingItem {
+    review_id: string;
+    state: "behind_cursor" | "in_window_fresh" | "in_window_redrafting" | "ahead";
+}
+/**
+ * The demand-driven pacing snapshot for a category (agent-readable, $0-LLM — M7 Slice
+ * B/§8): the human review cursor, the effective window/ceiling/interval, the queued
+ * count, and each queued draft's in-window/redrafting/behind-cursor classification.
+ * Read-only; the cursor advances from the human's console approve/reject/edit actions.
+ */
+interface CategoryPacingState {
+    category_id: string;
+    /** The last queued draft the human acted on (the cursor); omitted when nothing reviewed yet. */
+    cursor_review_id?: string;
+    /** Monotonic count of cursor advances. */
+    cursor_advanced_count: number;
+    /** Effective freshness window (default org_settings.lookahead_window=3). */
+    lookahead_window: number;
+    /** HARD per-nudge fan-out ceiling (default 10) — one nudge can never fan to 500. */
+    rework_batch_max: number;
+    /** Per-agent token-bucket interval that coalesces feedback storms (default 5000). */
+    nudge_min_interval_ms: number;
+    /** Drafts in the human queue (needs_review|in_review|chatting). */
+    queued: number;
+    /** Of the queued, how many sit in the freshness-guaranteed window. */
+    in_window: number;
+    /** Of the in-window, how many are stale and being redrafted (the console shimmer set). */
+    redrafting: number;
+    items: PacingItem[];
+}
+/** Long-poll params: like {@link ListReviewEventsParams} plus a wait budget. */
+interface WaitForReviewEventParams extends ListReviewEventsParams {
+    /** Long-poll budget in seconds (default ~30, capped ~55). */
+    wait_seconds?: number;
+}
+/**
+ * The ownership layer of a writing rule (org/project model). `org` = house-style
+ * inherited by every project in the org; `project` = layered on top of the org rules
+ * (the agent-plane default). Project/per-agent rules outrank broader org rules in the
+ * ordered get_rules precedence ladder.
+ */
+type RuleLayer = "org" | "project";
+/**
+ * A learned writing rule (rule_…) in the Review Loop (D2/D11). House-style/general
+ * (scope='general', applies across all categories) or category-scoped. Append-only
+ * by supersession: an edit is a new rev (same lineage_id) with the prior superseded.
+ * Read by the agent at compose/redraft time via the ORDERED get_rules ladder; we
+ * never apply it (NO LLM on our side). Opaque ids only (D10).
+ *
+ * Layering (org/project): `rule_layer` says whether the rule is an org-wide
+ * house-style rule (`org`) or a project-layer rule (`project`). `org_id` is always
+ * set; `project_id` is set for a project-layer rule and empty for an org-layer rule.
+ */
+interface Rule {
+    id: string;
+    lineage_id: string;
+    rev: number;
+    /**
+     * Ownership layer (org/project). `org` = house-style inherited by every project;
+     * `project` = layered on top (the agent-plane default). Optional/additive so older
+     * servers that don't set it still parse.
+     */
+    rule_layer?: RuleLayer;
+    /** The org this rule belongs to. */
+    org_id?: string;
+    /** The project this rule belongs to; empty for an org-layer rule. */
+    project_id?: string;
+    scope: "general" | "category";
+    /** Set iff scope=category (cat_…). */
+    category_id?: string;
+    /** Set for a per-agent override; empty = all org agents. */
+    scope_agent_id?: string;
+    rule_text: string;
+    kind: "soft" | "hard";
+    priority: number;
+    status: "proposed" | "active" | "superseded" | "retired";
+    supersedes_id?: string;
+    author_kind: "agent" | "human";
+    created_at: IsoTimestamp;
+    updated_at: IsoTimestamp;
+}
+/** Filter for the ordered get_rules read (spec §5.4; §7). */
+interface GetRulesParams {
+    /** Category id (cat_…). Empty returns ONLY the house-style/general layer. */
+    category_id?: string;
+    /** Narrow to one layer (general | category). Default returns both. */
+    scope?: "general" | "category";
+}
+/**
+ * Save / edit a writing rule (append-only by supersession; spec §5.4; D11).
+ *
+ * Layering (org/project): an agent-plane save is ALWAYS project-layer — the saved
+ * rule's `rule_layer` is `project`, bound to the calling key's project. There is no
+ * settable `rule_layer` here: an agent cannot create org-layer / house-style
+ * (`rule_layer="org"`) rules in v1; authoring org rules is a console/admin action.
+ * (`scope: "general"` still means a house-style rule WITHIN the project layer —
+ * `scope` is the category axis, `rule_layer` is the ownership axis.)
+ */
+interface SaveRuleRequest {
+    /** Defaults from category_id (general iff empty). */
+    scope?: "general" | "category";
+    /** Category id (cat_…); empty = house-style/general (D2). */
+    category_id?: string;
+    rule_text: string;
+    /** Defaults soft. hard = non-overridable. */
+    kind?: "soft" | "hard";
+    priority?: number;
+    source_review_id?: string;
+    source_turn_id?: string;
+    /** Set to EDIT the prior version (rule_…). */
+    supersedes_id?: string;
+    /** Set for a per-agent override; empty = all org agents. */
+    scope_agent_id?: string;
+    /**
+     * D8 retro-propagation HUMAN OPT-IN (default false). When true, a NEW category rule
+     * that could apply to pending siblings enqueues ONE propagate_general_rule nudge
+     * (siblings + suggested_batch) so the agent redrafts a FEW at a time — never the
+     * whole queue. Set only after the human said "apply to N pending?".
+     */
+    propagate_to_pending?: boolean;
+    /** Override the propagate batch (0 = base 3, bounded by rework_batch_max). */
+    suggested_batch?: number;
+}
+/** One append-only rule/category change & undo audit row (udo_…). */
+interface RuleAuditEntry {
+    id: string;
+    entity_kind: "rule" | "category";
+    entity_id: string;
+    action: "create" | "supersede" | "retire" | "rename" | "redescribe" | "merge" | "restore";
+    actor_kind: "agent" | "human" | "system";
+    actor_id?: string;
+    before_json?: string;
+    after_json?: string;
+    undone: boolean;
+    created_at: IsoTimestamp;
+}
+/** Filter for the rule/category change audit read (spec §5.4; D11). */
+interface GetRuleAuditParams {
+    entity_kind?: "rule" | "category";
+    entity_id?: string;
+}
+/** One per-(agent, review) cursor advance for ack_review_event. */
+interface AckReviewEventEntry {
+    review_id: string;
+    through_seq: number;
+}
+/** Ack request: advance per-review cursor(s) and/or mark broadcast nudges done. */
+interface AckReviewEventRequest {
+    acks?: AckReviewEventEntry[];
+    broadcast_ids?: string[];
+}
+/** Ack result: the resulting per-review cursors. */
+interface AckReviewEventResult {
+    cursors?: ReviewEventCursor[];
+}
+/** A Review Loop submit parked for human review (202). */
+interface QueuedForReviewResult {
+    kind: "queued_for_review";
+    review: {
+        id: string;
+        state: ReviewState;
+        effective_mode?: ReviewMode;
+    };
+}
+/** A Review Loop submit sent immediately (200). */
+interface SentResult {
+    kind: "sent";
+    message: {
+        id: string;
+        thread_id?: string;
+    };
+    /**
+     * The review row that governed this send (ADDITIVE). Present on every send the
+     * service routed, i.e. all of them — it is the handle that makes a post-crash
+     * `reviews.get(id)` possible on the direct path too.
+     */
+    review?: {
+        id: string;
+        state: ReviewState;
+    };
+}
+/** The discriminated outcome of a review-mode submit (queued OR sent). */
+type SubmitForReviewResult = QueuedForReviewResult | SentResult;
+/**
+ * A conversation thread (read shape). Grouped server-side by RFC 5322
+ * References / In-Reply-To chaining (subject fallback); `id` is stable across
+ * calls. `participants` are display address strings (`Name <email>` or bare).
+ */
+interface Thread {
+    id: string;
+    /** Owning inbox address. */
+    inbox_id: string;
+    subject: string;
+    /** Distinct participant address strings across the thread. */
+    participants: string[];
+    message_count: number;
+    last_message_at: IsoTimestamp;
+    /** Most-recent-message preview snippet. */
+    snippet: string;
+}
+/** A thread plus its messages (oldest-first) — `GET /v1/inboxes/{addr}/threads/{id}`. */
+interface ThreadDetail extends Thread {
+    messages: Message[];
+}
+/** Query params for `GET /v1/inboxes/{addr}/threads`. */
+interface ListThreadsParams {
+    limit?: number;
+    offset?: number;
+    cursor?: string;
+}
+/**
+ * Request for `POST /v1/inboxes/{addr}/wait`. Polls server-side until a matching message arrives
+ * or the timeout elapses, then returns it with an extracted OTP / verification link.
+ */
+interface WaitForEmailRequest {
+    /** Only match messages from this sender address or domain. */
+    from?: string;
+    /** Only match messages whose subject contains this substring (case-insensitive). */
+    subject?: string;
+    /** Case-sensitive Go RE2 expression over subject/readable body. Prefix `(?i)` for case-insensitive matching. */
+    match?: string;
+    /** Prefer an extracted link containing this substring; this does not filter message matches. */
+    link_hint?: string;
+    /** Max seconds to block before returning a timeout. Server caps this (default 300, cap 600). */
+    timeout_seconds?: number;
+    /**
+     * If true (default), only consider messages that arrive after the request is made, ignoring the
+     * existing inbox contents. Set false to also match an already-delivered message.
+     */
+    since_now?: boolean;
+}
+/** Structured extraction returned alongside the matched message. */
+interface ExtractedCredentials {
+    /** The first OTP-looking code found in the body (e.g. `492013`), or null. */
+    otp: string | null;
+    /** The first verification/magic link found in the body, or null. */
+    link: string | null;
+}
+/** Result of `wait_for_email`. `timed_out` distinguishes "no match in time" from a real match. */
+interface WaitForEmailResult {
+    /** True when the timeout elapsed before a match; in that case `message` is null. */
+    timed_out: boolean;
+    /** The matched message, or null on timeout. */
+    message: Message | null;
+    /** Structured OTP/link extraction from the matched message body. */
+    extracted: ExtractedCredentials;
+}
+/** Webhook event types Extrovert emits. */
+type WebhookEvent = "message.received";
+/** Request body for `POST /v1/webhooks`. Registers an HMAC-signed, timestamped endpoint. */
+interface RegisterWebhookRequest {
+    url: string;
+    /** Events to subscribe to. Defaults to `["message.received"]`. */
+    events?: WebhookEvent[];
+    /** Scope the webhook to a single inbox address; omit for all inboxes the key can read. */
+    inbox?: string;
+    /**
+     * Optional idempotency key (sent as the `Idempotency-Key` header). A retry with
+     * the same key replays the original webhook registration instead of duplicating.
+     */
+    client_id?: string;
+}
+/**
+ * PATCH body for `PATCH /v1/webhooks/{id}`. Every field is optional; an omitted
+ * field leaves the stored value unchanged (PATCH semantics). The signing secret
+ * and id are immutable.
+ */
+interface UpdateWebhookRequest {
+    /** Replace the HTTPS delivery endpoint. */
+    url?: string;
+    /** Replace the subscribed event set. */
+    events?: WebhookEvent[];
+    /** Replace the inbox filter; an empty string clears it (covers all owned inboxes). */
+    inbox?: string;
+    /** Enable or disable delivery without deleting the webhook. */
+    active?: boolean;
+}
+/** A registered webhook (read shape). The `secret` is returned once at registration. */
+interface Webhook {
+    id: string;
+    url: string;
+    events: WebhookEvent[];
+    inbox: string | null;
+    /** Agent that owns this webhook. */
+    agent_id?: string;
+    /**
+     * HMAC signing secret, returned once at registration. Used to verify the `X-Extrovert-Signature`
+     * header on inbound deliveries (see {@link verifyWebhookSignature}). Absent on list/get reads.
+     */
+    secret?: string;
+    /** Display prefix of the secret (safe to store), e.g. `whsec_a1b2`. */
+    secret_prefix: string;
+    /** Whether the webhook is active (deliveries are sent). */
+    active: boolean;
+    created_at: IsoTimestamp;
+}
+/** Whether a contact-list entry permits (allow) or rejects (block) a match. */
+type ContactListKind = "allow" | "block";
+/** Traffic direction a contact-list entry governs. Only `send` is enforced today. */
+type ContactListDirection = "send" | "receive";
+/**
+ * Request body for `POST /v1/inboxes/{addr}/lists`. Adds one allow/block entry.
+ * `pattern` is a bare email address (matched in full) or a bare domain (matches
+ * any address in that domain).
+ */
+interface AddContactListRequest {
+    kind: ContactListKind;
+    /** Defaults to `send` server-side (the only enforced direction today). */
+    direction?: ContactListDirection;
+    pattern: string;
+}
+/**
+ * A contact allow/block-list entry (read shape). `inbox` is null when the entry
+ * is account-wide (covers every inbox the agent owns).
+ */
+interface ContactListEntry {
+    id: string;
+    inbox: string | null;
+    kind: ContactListKind;
+    direction: ContactListDirection;
+    pattern: string;
+    created_at: IsoTimestamp;
+}
+/**
+ * The scope a suppression row applies at. The agent plane only ever sees `org`
+ * rows (the caller's OWN org): the reads never surface a platform-`global` or
+ * shared-domain opt-out (non-leakage). The wider values are part of the shape for
+ * forward-compatibility with the admin/operator plane.
+ */
+type SuppressionScope = "org" | "shared_domain" | "global";
+/** How a suppression came to exist (which signal created the opt-out row). */
+type SuppressionSource = "one_click" | "page" | "mailto" | "reply_stop" | "manual" | "complaint" | "escalation";
+/**
+ * One recipient opt-out row (mirrors the Go `suppressionResponse`). A recipient
+ * with an active (non-`revoked`) row for the sender's org is blocked from receiving
+ * mail; a send to them is rejected with `recipient_suppressed`
+ * ({@link RecipientSuppressedError}). Revoke a row (with a reason) to re-enable
+ * sending to that recipient.
+ */
+interface SuppressionEntry {
+    id: string;
+    /** The canonicalized (lower-cased, normalized) recipient the row suppresses. */
+    recipient: string;
+    /** The recipient exactly as it was originally addressed, when it differs. */
+    recipient_raw?: string;
+    scope: SuppressionScope;
+    source: SuppressionSource;
+    /** Set when the row is narrowed to one agent (recipient-chosen narrow row). */
+    narrow_agent_id?: string;
+    /** Set when the row is narrowed to one mailbox (recipient-chosen narrow row). */
+    narrow_mailbox?: string;
+    /** The mailbox the opt-out originated from, when known. */
+    origin_mailbox?: string;
+    /** The agent whose send produced the opt-out, when known. */
+    origin_agent_id?: string;
+    /** The message that carried the unsubscribe link/header, when known. */
+    origin_message_id?: string;
+    /** How many times this recipient re-suppressed after a revoke (abuse signal). */
+    reactivation_count: number;
+    created_at: IsoTimestamp;
+    /** Present once the row is revoked. */
+    revoked_at?: IsoTimestamp;
+    /** Who revoked the row (e.g. `agent:<id>`), when revoked. */
+    revoked_by?: string;
+    /** The required, audit-logged reason the row was revoked. */
+    revoke_reason?: string;
+    /** True when the row has been revoked (no longer enforced). */
+    revoked: boolean;
+}
+/**
+ * The result of a pre-check (`GET /v1/suppressions?recipient=…`): whether the
+ * caller's OWN org suppresses the recipient, plus the matching org rows. Reflects
+ * only the caller's org state — never a global/shared/cross-tenant opt-out.
+ */
+interface SuppressionPrecheck {
+    recipient: string;
+    /** True when the caller's org has an active (non-revoked) row for the recipient. */
+    suppressed: boolean;
+    rows: SuppressionEntry[];
+}
+/** Filters + paging for `GET /v1/suppressions` (the caller's own org rows). */
+interface ListSuppressionsParams {
+    /** Narrow to one scope; the agent plane only ever returns `org` rows. */
+    scope?: SuppressionScope;
+    /** Include revoked rows too (default: active rows only). */
+    include_revoked?: boolean;
+    /** Max rows to return. */
+    limit?: number;
+    /** Opaque cursor from a previous page's `next_cursor`. */
+    cursor?: string;
+}
+/** One DNS record the customer must set (manual mode) or that we serve (ns_delegated). */
+interface DomainRecord {
+    name: string;
+    type: string;
+    value: string;
+    /** MX priority, when applicable. */
+    priority?: number | null;
+    ttl: number;
+}
+/** Domain visibility for an onboarded domain (org/project model). */
+type DomainScope = "org" | "project";
+/**
+ * Request body for `POST /v1/domains`. Onboards/adds a domain for the customer.
+ *
+ * Permissions: every mode needs the `domain:manage` scope (the route gate); `mode:
+ * "purchased"` spends money at the registrar and therefore ADDITIONALLY requires the
+ * explicit, default-off `domain:purchase` scope (and is capped by the org/project
+ * purchased-domain plan limit, enforced before any registrar spend). `manual` and
+ * `ns_delegated` need `domain:manage` only.
+ */
+interface OnboardDomainRequest {
+    domain: string;
+    /**
+     * Onboarding path. Defaults to `ns_delegated` server-side when omitted. `purchased`
+     * additionally requires the `domain:purchase` scope.
+     */
+    mode?: OnboardingMode;
+    /** A-record IP served at a delegated zone's apex (ns_delegated only). */
+    mail_host_ip?: string;
+    /**
+     * Domain visibility. Defaults to `org` (org-shared, usable by every project in the
+     * org). `project` binds the domain to the key's OWN bound project (never
+     * client-selected) so it is only visible/mintable from that project. A
+     * legacy/unscoped key (no bound project) falls back to `org`.
+     */
+    scope?: DomainScope;
+    /**
+     * Optional assertion that must match the key's bound project — NEVER a selector.
+     * A mismatch is a 403. The binding is always derived from the key.
+     */
+    project_id?: string;
+}
+/**
+ * The agent-facing view of one onboarded domain (mirrors the Go `domainResponse`).
+ * `records` (and `delegation_ns` for ns_delegated) are present on get / onboard /
+ * verify and empty on list reads and for shared/purchased modes.
+ */
+interface Domain {
+    id: string;
+    domain: string;
+    mode: OnboardingMode;
+    verification_status: string;
+    dkim_status: string;
+    shared: boolean;
+    provisioning_phase?: string;
+    provisioning_error?: string;
+    created_at: IsoTimestamp;
+    records?: DomainRecord[];
+    delegation_ns?: DomainRecord[];
+    /** Human-facing copy for what the customer must do next. */
+    instruction?: string;
+}
+/**
+ * Result of an ACCEPTED domain offboard (`DELETE /v1/domains/{domain}` → HTTP 202).
+ * Teardown — reaping the outbound provider senders + routing rows, then scrubbing
+ * the DNS zone/records and the domain row — runs as an async job. Poll `status_url`
+ * (`GET /v1/jobs/{job_id}`, via {@link Job} / `client.getJob(job_id)`) until
+ * `status` is terminal (succeeded/failed/cancelled); the domain is ACCEPTED for
+ * offboard, not yet fully torn down when this returns.
+ */
+interface DomainOffboard {
+    domain: string;
+    job_id: string;
+    status: string;
+    status_url: string;
+}
+/**
+ * Poll-loop status for one async job (currently only the domain-offboard
+ * teardown started by `domains.offboard`). Mirrors `GET /v1/jobs/{job_id}`.
+ * `status` is terminal on succeeded/failed/cancelled; keep polling otherwise.
+ */
+interface Job {
+    object: "job";
+    id: string;
+    type: string;
+    status: string;
+    created_at: IsoTimestamp;
+    updated_at: IsoTimestamp;
+    finished_at?: IsoTimestamp;
+}
+/**
+ * One event from the SSE stream (`GET /v1/inboxes/{addr}/stream` or `GET
+ * /v1/events`). It is the SAME envelope a webhook delivers, so a stream consumer
+ * and a webhook consumer see identical data. `seq` is the monotonic resume token
+ * (the SSE frame's `id:` field): pass the last `seq` you saw as `lastEventId` on
+ * reconnect to replay only events after it. The envelope is intentionally generic
+ * so it can also carry future event types (e.g. HITL).
+ */
+interface StreamEvent {
+    /** Event type, e.g. `message.received`. Mirrors the SSE `event:` field. */
+    event: string;
+    /** Monotonic resume token (the SSE `id:` field). Pass back as `lastEventId`. */
+    seq: number;
+    /** Opaque event id (`evt_...`). */
+    id: string;
+    created_at: IsoTimestamp;
+    /** The inbox this event concerns. */
+    inbox: string;
+    /** The message the event is about (present for message.* events). */
+    message?: Message;
+}
+/** Options for the SSE stream / subscribe helpers. */
+interface StreamOptions {
+    /**
+     * Resume token from a prior run: the `seq` of the last event you processed. The
+     * server replays every event after it (Last-Event-ID semantics), so a reconnect
+     * never misses or double-delivers. Omit to start from now.
+     */
+    lastEventId?: number;
+    /** Abort the stream (close the connection) when this signal fires. */
+    signal?: AbortSignal;
+}
+/** Request body for the unauthenticated `POST /v1/agent/sign-up`. */
+interface SignUpRequest {
+    /** Human email that receives the one-time verification code. */
+    human_email: string;
+    /** Desired local-part for the first inbox (optional; auto-generated when omitted). */
+    username?: string;
+}
+/**
+ * Response from `POST /v1/agent/sign-up`. The `agent_key` is a LIMITED-scope key
+ * (read-only) until the emailed code is confirmed via `POST /v1/agent/verify`.
+ * The OTP itself is never returned — it is emailed to `human_email`.
+ */
+interface SignUpResponse {
+    customer_id: string;
+    agent_id: string;
+    /** Limited-scope agent key, shown once. Re-calling signup rotates it. */
+    agent_key: string;
+    key_prefix: string;
+    scopes: Scope[];
+    /** The first inbox minted for the agent. */
+    address: string;
+    verified: boolean;
+    /** Where the verification code was sent. */
+    otp_sent_to: string;
+    otp_expires_at: IsoTimestamp;
+    message: string;
+}
+/** Request body for `POST /v1/agent/verify`. */
+interface VerifyRequest {
+    /** The one-time code delivered to the signup human email. */
+    otp: string;
+}
+/**
+ * Response from `POST /v1/agent/verify`. On success a NEW full-scope `agent_key`
+ * is returned (shown once); switch to it for subsequent calls.
+ */
+interface VerifyResponse {
+    agent_id: string;
+    agent_key: string;
+    key_prefix: string;
+    scopes: Scope[];
+    verified: boolean;
+    message: string;
+}
+/**
+ * Response from `GET /v1/auth/me` — the verified principal behind the key.
+ *
+ * `org_id`/`project_id` are the FIXED org/project the key is bound to (resolved from
+ * the stored key, never client input). There is NO mutable project selector for a
+ * scoped key — `whoami` is the canonical project-visibility surface; project
+ * selection happens when the human/admin issues the enrollment token or agent key.
+ */
+interface WhoAmI {
+    customer_id: string;
+    /**
+     * The fixed org the key is bound to. Optional to match the OpenAPI contract: a
+     * legacy/unscoped server (or any deploy predating org/project binding) may omit it.
+     */
+    org_id?: string;
+    /**
+     * The fixed project the key is bound to. Optional to match the OpenAPI contract: a
+     * legacy/unscoped server (or any deploy predating org/project binding) may omit it.
+     */
+    project_id?: string;
+    agent_id: string;
+    key_id: string;
+    scopes: Scope[];
+}
+
+/**
+ * The ONE list envelope + opaque-cursor iteration (redesign §5.2 / §6.2).
+ *
+ * Every redesign collection endpoint (the canonical `x.projects.inboxes.*` chain
+ * and beyond) returns {@link List}: `{ object: "list", data, has_more, next_cursor }`.
+ * `next_cursor` is OPAQUE — treat it as a token and pass it back verbatim as
+ * `?cursor` to fetch the next page. {@link ListPage} wraps a raw {@link List} with
+ * ergonomic iteration (`for await … of`) and a `nextPage()` cursor walker so callers
+ * never thread cursors by hand.
+ */
+/** The opaque pagination cursor. Pass it back verbatim as `?cursor`; never parse it. */
+type Cursor = string;
+/** The one collection envelope for every redesign list response. */
+interface List<T> {
+    /** Always the literal `"list"`. */
+    object: "list";
+    /** The rows on this page. */
+    data: T[];
+    /** True when another page exists (i.e. `next_cursor` is non-null). */
+    has_more: boolean;
+    /** Opaque cursor for the next page, or `null` on the last page. */
+    next_cursor: Cursor | null;
+}
+/** Query params shared by every cursor-paginated list. */
+interface ListParams {
+    /** Page size (server clamps to 1–100; default 50). */
+    limit?: number;
+    /** Opaque cursor from a prior page's `next_cursor`. */
+    cursor?: Cursor;
+}
+/** A function that fetches one page given an opaque cursor (or undefined for page 1). */
+type PageFetcher<T> = (cursor: Cursor | undefined, signal?: AbortSignal) => Promise<List<T>>;
+/**
+ * An ergonomic wrapper over a single {@link List} page that also knows how to fetch
+ * the next page and auto-iterate across ALL pages.
+ *
+ * ```ts
+ * const page = await x.projects.inboxes.list("proj_9k");
+ * for await (const inbox of page) console.log(inbox.id);   // walks every page
+ * // …or page-at-a-time:
+ * if (page.hasMore) { const next = await page.nextPage(); }
+ * ```
+ */
+declare class ListPage<T> implements AsyncIterable<T> {
+    private readonly fetcher;
+    /** The rows on THIS page. */
+    readonly data: T[];
+    /** True when another page exists. */
+    readonly hasMore: boolean;
+    /** Opaque cursor for the next page (null on the last page). */
+    readonly nextCursor: Cursor | null;
+    /** Always `"list"`. */
+    readonly object: "list";
+    constructor(raw: List<T>, fetcher: PageFetcher<T>);
+    /**
+     * Fetch the next page. Throws if there is none — guard with {@link hasMore}.
+     */
+    nextPage(signal?: AbortSignal): Promise<ListPage<T>>;
+    /**
+     * Auto-paginate: yield every row across every page, fetching subsequent pages
+     * lazily as the iterator is consumed. The default iteration of a `ListPage`.
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T>;
+    /** Collect EVERY row across EVERY page into a single array (eager). */
+    collect(signal?: AbortSignal): Promise<T[]>;
+}
+/** Build a {@link ListPage} from the first raw {@link List} and a page fetcher. */
+declare function listPage<T>(raw: List<T>, fetcher: PageFetcher<T>): ListPage<T>;
+
+/**
+ * Transport abstraction.
+ *
+ * The resource methods speak a small, typed RPC surface; a transport decides whether each call hits
+ * the live Extrovert API over HTTP or the offline {@link MockBackend}. This is the single mock seam:
+ * flip `transport: "mock"` (or `EXTROVERT_API_BASE_URL=mock`) and the whole SDK runs without a network.
+ *
+ * `HttpTransport` is used for the live API; the mock stays for examples, docs, and tests.
+ */
+
+/** Raw bytes of one attachment plus the metadata needed to save/serve it. */
+interface AttachmentDownload {
+    filename: string;
+    content_type: string;
+    /** Standard base64 of the attachment bytes. */
+    content_base64: string;
+}
+/** The RPC surface every transport implements. One method per spec §8 endpoint. */
+interface Transport {
+    enroll(req: EnrollRequest, signal?: AbortSignal): Promise<EnrollResponse>;
+    signUp(req: SignUpRequest, signal?: AbortSignal): Promise<SignUpResponse>;
+    verify(req: VerifyRequest, signal?: AbortSignal): Promise<VerifyResponse>;
+    whoami(signal?: AbortSignal): Promise<WhoAmI>;
+    createInbox(req: CreateInboxRequest, idempotencyKey?: string, signal?: AbortSignal): Promise<Inbox>;
+    listInboxes(params: ListInboxesParams, signal?: AbortSignal): Promise<Page<Inbox>>;
+    getInbox(address: string, signal?: AbortSignal): Promise<Inbox>;
+    updateInbox(address: string, req: UpdateInboxRequest, signal?: AbortSignal): Promise<Inbox>;
+    deleteInbox(address: string, signal?: AbortSignal): Promise<void>;
+    createInboxInProject(projectId: string, req: CreateInboxRequest, idempotencyKey?: string, signal?: AbortSignal): Promise<Inbox>;
+    listInboxesInProject(projectId: string, params: ProjectInboxListParams, signal?: AbortSignal): Promise<List<Inbox>>;
+    getInboxInProject(projectId: string, inboxId: string, params: GetInboxParams, signal?: AbortSignal): Promise<Inbox>;
+    updateInboxInProject(projectId: string, inboxId: string, req: UpdateInboxRequest, signal?: AbortSignal): Promise<Inbox>;
+    deleteInboxInProject(projectId: string, inboxId: string, signal?: AbortSignal): Promise<void>;
+    getInboxCredentialsInProject(projectId: string, inboxId: string, signal?: AbortSignal): Promise<InboxCredentials>;
+    send(address: string, req: SendRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    reply(address: string, req: ReplyRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    forward(address: string, messageId: string, req: ForwardRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    listMessages(address: string, params: ListMessagesParams, signal?: AbortSignal): Promise<Page<Message>>;
+    getMessage(messageId: string, signal?: AbortSignal): Promise<Message>;
+    getMessageRaw(address: string, messageId: string, signal?: AbortSignal): Promise<string>;
+    listAttachments(address: string, messageId: string, signal?: AbortSignal): Promise<Page<Attachment>>;
+    getAttachment(address: string, messageId: string, attachmentId: string, signal?: AbortSignal): Promise<AttachmentDownload>;
+    markRead(address: string, messageId: string, req: MarkReadRequest, signal?: AbortSignal): Promise<Message>;
+    deleteMessage(address: string, messageId: string, expunge?: boolean, signal?: AbortSignal): Promise<DeleteResult>;
+    batchUpdateMessages(address: string, req: BatchUpdateMessagesRequest, signal?: AbortSignal): Promise<BatchUpdateResult>;
+    searchMessages(address: string, params: SearchMessagesParams, signal?: AbortSignal): Promise<Page<Message>>;
+    listThreads(address: string, params: ListThreadsParams, signal?: AbortSignal): Promise<Page<Thread>>;
+    searchThreads(address: string, params: SearchMessagesParams, signal?: AbortSignal): Promise<Page<Thread>>;
+    getThread(address: string, threadId: string, signal?: AbortSignal): Promise<ThreadDetail>;
+    deleteThread(address: string, threadId: string, expunge?: boolean, signal?: AbortSignal): Promise<DeleteResult>;
+    waitForEmail(address: string, req: WaitForEmailRequest, timeoutMs: number, signal?: AbortSignal): Promise<WaitForEmailResult>;
+    registerWebhook(req: RegisterWebhookRequest, signal?: AbortSignal): Promise<Webhook>;
+    listWebhooks(signal?: AbortSignal): Promise<Page<Webhook>>;
+    getWebhook(webhookId: string, signal?: AbortSignal): Promise<Webhook>;
+    updateWebhook(webhookId: string, req: UpdateWebhookRequest, signal?: AbortSignal): Promise<Webhook>;
+    deleteWebhook(webhookId: string, signal?: AbortSignal): Promise<void>;
+    addContactListEntry(address: string, req: AddContactListRequest, signal?: AbortSignal): Promise<ContactListEntry>;
+    listContactLists(address: string, signal?: AbortSignal): Promise<Page<ContactListEntry>>;
+    deleteContactListEntry(address: string, entryId: string, signal?: AbortSignal): Promise<void>;
+    precheckSuppression(recipient: string, signal?: AbortSignal): Promise<SuppressionPrecheck>;
+    listSuppressions(params: ListSuppressionsParams, signal?: AbortSignal): Promise<Page<SuppressionEntry>>;
+    revokeSuppression(id: string, reason: string, signal?: AbortSignal): Promise<SuppressionEntry>;
+    listDomains(signal?: AbortSignal): Promise<Page<Domain>>;
+    getDomain(domain: string, signal?: AbortSignal): Promise<Domain>;
+    onboardDomain(req: OnboardDomainRequest, signal?: AbortSignal): Promise<Domain>;
+    verifyDomain(domain: string, signal?: AbortSignal): Promise<Domain>;
+    offboardDomain(domain: string, signal?: AbortSignal): Promise<DomainOffboard>;
+    getJob(jobId: string, signal?: AbortSignal): Promise<Job>;
+    submitForReview(address: string, req: SendRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    submitReplyForReview(address: string, req: ReplyRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    listReviews(params: ListReviewsParams, signal?: AbortSignal): Promise<Page<Review>>;
+    getReview(reviewId: string, signal?: AbortSignal): Promise<Review>;
+    getReviewTurns(reviewId: string, signal?: AbortSignal): Promise<Page<ReviewTurn>>;
+    getReviewFeedback(reviewId: string, signal?: AbortSignal): Promise<ReviewFeedback>;
+    postReviewChat(reviewId: string, req: PostReviewChatRequest, idempotencyKey?: string, signal?: AbortSignal): Promise<Review>;
+    submitRevision(reviewId: string, req: SubmitRevisionRequest, signal?: AbortSignal): Promise<Review>;
+    cancelReview(reviewId: string, idempotencyKey?: string, signal?: AbortSignal): Promise<Review>;
+    restampReview(reviewId: string, req: RestampReviewRequest, signal?: AbortSignal): Promise<Review>;
+    getReviewDecisionContext(reviewId: string, signal?: AbortSignal): Promise<ReviewDecisionContext>;
+    reviewerDecide(reviewId: string, req: ReviewerDecisionRequest, signal?: AbortSignal): Promise<ReviewerDecisionResult>;
+    listReviewEvents(params: ListReviewEventsParams, signal?: AbortSignal): Promise<ReviewEventsResult>;
+    waitForReviewEvent(params: WaitForReviewEventParams, signal?: AbortSignal): Promise<ReviewEventsResult>;
+    ackReviewEvent(req: AckReviewEventRequest, signal?: AbortSignal): Promise<AckReviewEventResult>;
+    listCategories(params: ListCategoriesParams, signal?: AbortSignal): Promise<Page<Category>>;
+    getCategory(categoryId: string, signal?: AbortSignal): Promise<Category>;
+    proposeCategory(req: ProposeCategoryRequest, signal?: AbortSignal): Promise<Category>;
+    updateCategory(categoryId: string, req: UpdateCategoryRequest, signal?: AbortSignal): Promise<Category>;
+    getRiskDial(signal?: AbortSignal): Promise<RiskDial>;
+    getGraduationStatus(categoryId: string, signal?: AbortSignal): Promise<GraduationStatus>;
+    proposeGraduation(categoryId: string, req: ProposeGraduationRequest, signal?: AbortSignal): Promise<GraduationStatus>;
+    getScanBacklogStatus(categoryId: string, signal?: AbortSignal): Promise<ScanBacklogStatus>;
+    getCategoryPacingState(categoryId: string, signal?: AbortSignal): Promise<CategoryPacingState>;
+    getRules(params: GetRulesParams, signal?: AbortSignal): Promise<Page<Rule>>;
+    saveRule(req: SaveRuleRequest, signal?: AbortSignal): Promise<Rule>;
+    promoteRule(ruleId: string, toScope: "general" | "category", signal?: AbortSignal): Promise<Rule>;
+    retireRule(ruleId: string, signal?: AbortSignal): Promise<Rule>;
+    getRuleAudit(params: GetRuleAuditParams, signal?: AbortSignal): Promise<Page<RuleAuditEntry>>;
+    undoRuleChange(udoId: string, signal?: AbortSignal): Promise<Rule>;
+    /**
+     * Open a live event stream. `address` scopes to one inbox (`GET
+     * /v1/inboxes/{addr}/stream`); pass `null` for every owned inbox (`GET
+     * /v1/events`). `lastEventId`, when set, resumes after that event seq. The
+     * generator ends when the server closes the stream or `signal` aborts.
+     */
+    stream(address: string | null, lastEventId?: number, signal?: AbortSignal): AsyncGenerator<StreamEvent, void, unknown>;
+}
+
+/**
+ * Offline fixtures for the Extrovert SDK.
+ *
+ * The SDK can run against this in-memory, deterministic mock so examples, the MCP server, and the
+ * console are fully navigable offline without contacting the live `/v1` API. Construct a client with
+ * `transport: "mock"` (or set `EXTROVERT_API_BASE_URL=mock`) to route requests here instead of fetch.
+ *
+ * The mock honors the same request/response models as the real API and reproduces the few behaviors
+ * the SDK ergonomics depend on (enrollment cap, idempotency on `client_id`, wait_for_email returning
+ * an OTP). It is intentionally simple — not a full server — and never reaches the network.
+ */
+
+/**
+ * A self-contained, deterministic-enough in-memory backend implementing the subset of behavior the
+ * SDK exposes. One instance per mock client so tests/examples don't bleed into each other.
+ */
+declare class MockBackend {
+    private state;
+    reset(): void;
+    enroll(req: EnrollRequest): EnrollResponse;
+    /**
+     * Self-signup (Slice E). Returns a LIMITED-scope key and a first inbox; the OTP
+     * is held in-memory (mock only) so `verify` can elevate to full scope. Idempotent
+     * on human_email: a re-call reuses the tenant/agent and rotates the OTP.
+     */
+    signUp(req: SignUpRequest): SignUpResponse;
+    /** Confirm a signup OTP and return a full-scope key (mock). */
+    verify(req: VerifyRequest): VerifyResponse;
+    /** Introspect the mock principal (GET /v1/auth/me). */
+    whoami(): WhoAmI;
+    createInbox(req: CreateInboxRequest): Inbox;
+    listInboxes(params?: ListInboxesParams): Page<Inbox>;
+    getInbox(address: string): Inbox | undefined;
+    /**
+     * Normalize an inbox ref (opaque id OR address alias) to the canonical address the
+     * mock keys its message/thread/contact maps on. The SDK now routes inbox ops by the
+     * canonical opaque `id` when it holds a full record (matching the contract's
+     * canonical-key semantics), so the mock must resolve an id back to its address —
+     * both key `state.inboxes` (same object), `state.messages` keys by address only.
+     * Unknown refs pass through unchanged so the existing not-found paths still fire.
+     */
+    private addrOf;
+    updateInbox(address: string, req: UpdateInboxRequest): Inbox | undefined;
+    deleteInbox(address: string): void;
+    /** Resolve the project path segment against the mock's bound project (fail-closed). */
+    private resolveProjectSegment;
+    createInboxInProject(projectId: string, req: CreateInboxRequest): Inbox;
+    listInboxesInProject(projectId: string, params?: ProjectInboxListParams): List<Inbox>;
+    getInboxInProject(projectId: string, inboxId: string): Inbox | undefined;
+    updateInboxInProject(projectId: string, inboxId: string, req: UpdateInboxRequest): Inbox | undefined;
+    deleteInboxInProject(projectId: string, inboxId: string): boolean;
+    getInboxCredentialsInProject(projectId: string, inboxId: string): InboxCredentials | undefined;
+    /** The RESOLVED review policy for an inbox: per-inbox override, else the account default. */
+    reviewPolicyFor(address: string): ReviewPolicy;
+    /**
+     * Mock-only: set the ACCOUNT-level review policy (the console/admin plane sets
+     * this on the real server; there is no agent-plane write for it). Use it to
+     * exercise an org that has been configured for direct sending.
+     */
+    setReviewPolicy(policy: ReviewPolicy): void;
+    /** Mock-only: set (or clear) the per-inbox override, which beats the account default. */
+    setInboxReviewPolicy(address: string, policy: ReviewPolicy | undefined): void;
+    send(address: string, req: SendRequest): SendOutcome;
+    reply(address: string, req: ReplyRequest): SendOutcome;
+    forward(address: string, messageId: string, req: ForwardRequest): SendOutcome;
+    /**
+     * Submit a new message for review (mock). Rides the SAME endpoint as `send` on
+     * the real server, so it is literally the same call here: the resolved policy —
+     * not which SDK method you picked — decides whether the message is queued
+     * (`kind:"queued_for_review"`) or delivered.
+     */
+    submitForReview(address: string, req: SendRequest): SendOutcome;
+    /** Submit an in-thread reply for review (mock). Same endpoint, same routing, as `reply`. */
+    submitReplyForReview(address: string, req: ReplyRequest): SendOutcome;
+    /**
+     * The single enforcement point. Everything above funnels here; nothing else in
+     * the mock may reach `deliver*` on the agent plane.
+     */
+    private submitOutbound;
+    /**
+     * Move a review to `state` and keep `closed` in lockstep.
+     *
+     * `closed` is DERIVED, never independently assigned, because the two drifting
+     * apart is worse than either being wrong: an agent that polls `closed` on a row
+     * whose state says otherwise has no way to tell which one to believe.
+     */
+    private setReviewState;
+    /** Mark a review delivered on an auto-send path and emit its terminal `sent` nudge. */
+    private markReviewAutoSent;
+    /** Raw delivery for a send — no policy, only reachable from submitOutbound. */
+    private deliverSend;
+    /** Raw delivery for a reply — no policy, only reachable from submitOutbound. */
+    private deliverReply;
+    /** Append the outbound message and shape the legacy send result. */
+    private deliverRaw;
+    /**
+     * Derive a reply's recipients / `Re:` subject / thread from the parent, the way
+     * the server does before it writes the review row.
+     */
+    private deriveReplyEnvelope;
+    /** List review requests (mock), newest-first, with optional filters. */
+    listReviews(params?: ListReviewsParams): Page<Review>;
+    /** Get one review request (mock), or undefined when not found. */
+    getReview(reviewId: string): Review | undefined;
+    /** Get a review's append-only thread turns (mock), or undefined when not found. */
+    getReviewTurns(reviewId: string): Page<ReviewTurn> | undefined;
+    /**
+     * Get the human's assembled feedback (mock; M5): the diff + the human comments /
+     * rejection turns + the decision (derived from state). new_rules is empty in the
+     * mock (rule provenance lives server-side). Undefined when not found.
+     */
+    getReviewFeedback(reviewId: string): ReviewFeedback | undefined;
+    /**
+     * Post a chat turn on a review's thread (mock; M5). Idempotent on the optional key
+     * (parity v21): a replay with the same key returns the same review without doubling
+     * the turn. Flips in_review -> chatting on the first turn. Undefined when not found.
+     */
+    postReviewChat(reviewId: string, req: PostReviewChatRequest, idempotencyKey?: string): Review | undefined;
+    /**
+     * Post a new agent draft under a parent_revision CAS (mock; M5; D17). A mismatch is
+     * a 409 STALE with NO mutation; a clean CAS re-renders the draft in place
+     * (revision++), returns to needs_review. Undefined when not found.
+     */
+    submitRevision(reviewId: string, req: SubmitRevisionRequest): Review | undefined;
+    /** Withdraw a pending review (mock; M5) to the terminal cancelled state. */
+    cancelReview(reviewId: string): Review | undefined;
+    /**
+     * Re-stamp a draft's rules-version WITHOUT redrafting (mock; D19/§8 $0 escape valve).
+     * Advances the version the draft is current against; no revision bump, no body change.
+     * A terminal/sent draft 409s; against_version above the category's current
+     * rules-version is 400. The mock has no per-category rules_version on the Review, so it
+     * just bumps the row version and returns it (the body is untouched).
+     */
+    restampReview(reviewId: string, req: RestampReviewRequest): Review | undefined;
+    /**
+     * Test helper: create a draft already ASSIGNED to a reviewer (in_review), mirroring
+     * how the real server routes a parked draft to a linked review-agent. Returns the
+     * review id so a test can drive the reviewer decision plane offline. `createdAtMs`
+     * (optional) backdates created_at so a test can trip the hard review_deadline breaker.
+     */
+    seedReviewerHeldReview(opts?: {
+        fromAddress: string;
+        createdAtMs?: number;
+    }): string;
+    /** Get the reviewer's decision context for a review (mock; §9). */
+    getReviewDecisionContext(reviewId: string): ReviewDecisionContext | undefined;
+    /**
+     * Submit a reviewer decision (mock; §9). approve/edit → the platform "sends" with the
+     * composer's creds (kind=sent, send_path=reviewer_approved); reject → back to the
+     * composer (needs_review, hop_count++) UNLESS a breaker forces the human; escalate →
+     * the human queue. revision/version are the CAS (409 STALE on mismatch, NO mutation).
+     */
+    reviewerDecide(reviewId: string, req: ReviewerDecisionRequest): ReviewerDecisionResult | undefined;
+    /**
+     * Browse the registry (mock), newest-first, excluding merged/soft-deleted. `match`
+     * is a pure lexical filter (every token must appear in name+description) — NO LLM,
+     * mirroring the server.
+     */
+    listCategories(params?: ListCategoriesParams): Page<Category>;
+    /** Get one category (mock), or undefined when not found. */
+    getCategory(categoryId: string): Category | undefined;
+    /** Propose a category (mock): stands immediately, author_kind=agent (D9). */
+    proposeCategory(req: ProposeCategoryRequest): Category;
+    /** Rename / re-describe a category (mock) — metadata only (D10). */
+    updateCategory(categoryId: string, req: UpdateCategoryRequest): Category | undefined;
+    /** The mock account-default risk dial (mirrors the server defaults). */
+    private accountDial;
+    /**
+     * Read the effective risk dial (mock): the account default + every category with an
+     * inherited (null override) effective dial. The mock category carries no overrides,
+     * so every category inherits — effective == account.
+     */
+    getRiskDial(): RiskDial;
+    private nextGraduationState;
+    /**
+     * Read a category's graduation gate status (mock). The mock category has no
+     * counters, so it reports zero clean approvals / zero drift against the account
+     * defaults; can_graduate is true for supervised→auto_notify (no maturity gate).
+     */
+    getGraduationStatus(categoryId: string): GraduationStatus | undefined;
+    /**
+     * Propose graduating a category (mock): returns the current gate status without
+     * changing the category state (D16 — an agent can never flip the bit).
+     */
+    proposeGraduation(categoryId: string, _req: ProposeGraduationRequest): GraduationStatus | undefined;
+    /**
+     * Read the D19/§8 backlog-reconciliation status (mock): counts the QUEUED drafts in a
+     * category that are stale vs current-enough against the current rules-version. The
+     * mock has no per-draft composed_* stamps on its Review fixtures, so every queued
+     * draft reads as current-enough (composed 0 vs current 0) — the contract shape is
+     * exercised; the integer-compare logic is covered by the Go tests.
+     */
+    getScanBacklogStatus(categoryId: string): ScanBacklogStatus | undefined;
+    /**
+     * Read the demand-driven pacing state (mock — M7 Slice B/§8): the cursor + effective
+     * window/ceiling/interval + each queued draft's classification. The mock has no cursor
+     * (nothing reviewed) and no composed_* stamps, so every queued draft reads in-window-
+     * fresh until the window fills, then ahead; the contract shape is exercised (the
+     * cursor/staleness mechanics are covered by the Go tests).
+     */
+    getCategoryPacingState(categoryId: string): CategoryPacingState | undefined;
+    /** rank a rule for the §7 ladder (mock mirror of the server's deterministic order). */
+    private ruleRank;
+    /** Get the ORDERED active rule set (mock) — §7 ladder + category-before-general. */
+    getRules(params?: GetRulesParams): Page<Rule>;
+    /** Save / edit a rule (mock) — append-only by supersession (D11). */
+    saveRule(req: SaveRuleRequest): Rule;
+    /** Promote a rule between layers (mock, via supersession), or undefined when unknown. */
+    promoteRule(ruleId: string, toScope: "general" | "category"): Rule | undefined;
+    /** Retire a rule (mock) — soft delete, or undefined when unknown. */
+    retireRule(ruleId: string): Rule | undefined;
+    /** Read the rule/category change audit log (mock). */
+    getRuleAudit(params?: GetRuleAuditParams): Page<RuleAuditEntry>;
+    /** Undo a rule change (mock) — restore the prior version; idempotent (re-undo 409). */
+    undoRuleChange(udoId: string): Rule;
+    /** recordRuleAudit appends one change/undo audit row (mock). */
+    private recordRuleAudit;
+    /**
+     * enqueueReviewEvent appends a durable nudge for a review with the next per-review
+     * monotonic seq (mock mirror of the server's enqueue-on-transition).
+     */
+    private enqueueReviewEvent;
+    /**
+     * Emit the terminal-class nudge for the review's current state. `sent` and
+     * `cancelled` close the row. `failed` emits `send_failed`, and a later explicit
+     * cancel emits `cancelled`; this helper deliberately does not claim the first is
+     * the last event the review can produce.
+     */
+    private enqueueTerminalNudge;
+    /**
+     * Enqueue `front_run_next` — the signal that the review reached a terminal state
+     * while the agent was still trying to act on it.
+     *
+     * Deduped on (review, terminal state, parent revision) so a retry loop hitting
+     * the same 409 collapses to ONE row rather than one per attempt. Best-effort by
+     * design: it must never turn a 409 into a failure.
+     */
+    private enqueueFrontRunNudge;
+    /**
+     * Mock-only: mirror a console/human approve that delivers the draft. The live
+     * server does this on the console plane (never an SDK call); the hook exists so a
+     * drain loop can be driven to its terminal `sent` event offline.
+     */
+    simulateReviewApproved(reviewId: string, opts?: {
+        edited?: boolean;
+    }): Review | undefined;
+    /**
+     * Mock-only: mirror an approved draft whose delivery then FAILED at the provider.
+     * This is the case the composing agent was previously never told about — the
+     * console showed the error and the agent's queue stayed silent — so the loop test
+     * that matters most drives this path.
+     */
+    simulateSendFailed(reviewId: string, error?: string): Review | undefined;
+    /**
+     * simulateReviewRejected is a mock-only test hook that mirrors a console reject:
+     * it enqueues a `rejected` durable nudge to the composer so the realtime
+     * drain/ack surface has a deterministic event to exercise offline. The live
+     * server enqueues this on the reject TRANSITION (console-only, never an SDK call).
+     */
+    simulateReviewRejected(reviewId: string, comment?: string): ReviewEvent;
+    /**
+     * simulateReviewOpened is a mock-only test hook that mirrors a reviewer opening a
+     * draft (needs_review -> in_review). There is no agent-plane "open for review"
+     * call (a reviewer/human opens it), so tests of the M5 chat surface use this to get
+     * a chattable draft offline.
+     */
+    simulateReviewOpened(reviewId: string): Review | undefined;
+    /**
+     * simulateHumanComment is a mock-only test hook that mirrors the console chat side-
+     * panel: it appends a human_comment turn so get_review_feedback has a comment to
+     * assemble. The live server writes this on the console plane (never an SDK call).
+     */
+    simulateHumanComment(reviewId: string, body: string): ReviewTurn | undefined;
+    /** Drain the next un-acked review events (mock), FIFO per review + cursors. */
+    listReviewEvents(params?: ListReviewEventsParams): ReviewEventsResult;
+    /**
+     * Long-poll for a review event (mock). Offline there is nothing to wait FOR, so it
+     * returns the immediate drain (empty when caught up) — the server's "empty on
+     * timeout" contract.
+     */
+    waitForReviewEvent(params?: WaitForReviewEventParams): ReviewEventsResult;
+    /** Ack review events (mock): advance per-review cursors monotonically. */
+    ackReviewEvent(req: AckReviewEventRequest): AckReviewEventResult;
+    /** Mint a needs_review record + its intent (agent_note) and initial-draft turns. */
+    private createReviewRecord;
+    /** Append a message to an inbox's store and return it (mock helper). */
+    private appendMessage;
+    /** List a message's attachment metadata (mirrors the list endpoint). */
+    listAttachments(messageId: string): Page<Attachment>;
+    /** Fetch one attachment's bytes + metadata (mirrors the download endpoint). */
+    getAttachment(messageId: string, attachmentId: string): AttachmentDownload;
+    listMessages(address: string, params?: ListMessagesParams): Page<Message>;
+    /** Fetch a single message by id across all inboxes. */
+    getMessage(messageId: string): Message;
+    /** Toggle the \Seen flag for a message by id. */
+    markRead(messageId: string, read: boolean): Message;
+    /** Render a minimal RFC822 .eml for a message by id (mirrors the raw endpoint). */
+    getMessageRaw(messageId: string): string;
+    /** Full-text search scoped to one inbox. */
+    searchMessages(address: string, params: SearchMessagesParams): Page<Message>;
+    listThreads(address: string): Page<Thread>;
+    /** Thread-level search (subject / snippet / participant substring). */
+    searchThreads(address: string, params: SearchMessagesParams): Page<Thread>;
+    /** Fetch one thread (with messages, oldest-first) by id under an inbox. */
+    getThread(address: string, threadId: string): ThreadDetail;
+    /**
+     * Delete a message by id: move it to Trash (soft) or remove it (expunge / it
+     * already lives in Trash). Returns undefined when the inbox/message is unknown
+     * so the transport can surface a 404.
+     */
+    deleteMessage(address: string, messageId: string, expunge: boolean): DeleteResult | undefined;
+    /** Delete every message in a thread by id (move to Trash or expunge). */
+    deleteThread(address: string, threadId: string, expunge: boolean): DeleteResult | undefined;
+    /**
+     * Batch mark read/unread and/or move folder for a list of ids under one inbox.
+     * Unknown ids go in `failed`. Returns undefined when the inbox is unknown.
+     */
+    batchUpdateMessages(address: string, ids: string[], read: boolean | undefined, folder: string | undefined): BatchUpdateResult | undefined;
+    /** Build all threads for an inbox, newest-active first. */
+    private threadsFor;
+    private buildThread;
+    /**
+     * Mock wait_for_email: synthesizes a plausible OTP email after a short delay so the OTP example
+     * runs end-to-end offline. The live implementation waits through the platform receive path.
+     */
+    waitForEmail(address: string, req: WaitForEmailRequest): Promise<WaitForEmailResult>;
+    /**
+     * Append one event to the in-memory journal that backs the SSE stream. Mirrors
+     * the server: a monotonic seq is the resume token and the payload is the same
+     * envelope a webhook delivers.
+     */
+    private emitEvent;
+    /**
+     * Replay journal events after `lastEventId`, scoped to one inbox (or all when
+     * `address` is null). The offline mock yields the backlog and returns; the live
+     * transport tails an open connection. Both honor the same resume contract.
+     */
+    streamEvents(address: string | null, lastEventId?: number): AsyncGenerator<StreamEvent, void, unknown>;
+    registerWebhook(req: RegisterWebhookRequest): Webhook;
+    /** List registered webhooks (secret redacted, mirroring the server). */
+    listWebhooks(): Page<Webhook>;
+    /** Get one webhook by id (secret redacted), or undefined when missing. */
+    getWebhook(webhookId: string): Webhook | undefined;
+    /**
+     * Update a webhook in place (secret redacted), or undefined when missing.
+     * Every field is optional; an unset field leaves the stored value untouched
+     * (PATCH semantics). An empty-string `inbox` clears the filter.
+     */
+    updateWebhook(webhookId: string, req: UpdateWebhookRequest): Webhook | undefined;
+    /** Delete a webhook by id; returns false when it was not found. */
+    deleteWebhook(webhookId: string): boolean;
+    /** Add one allow/block entry scoped to an inbox, or undefined when the inbox is unknown. */
+    addContactListEntry(address: string, req: AddContactListRequest): ContactListEntry | undefined;
+    /** List the entries governing an inbox (inbox-specific + account-wide), or undefined when unknown. */
+    listContactLists(address: string): Page<ContactListEntry> | undefined;
+    /** Delete a contact-list entry by id; returns false when it was not found. */
+    deleteContactListEntry(_address: string, entryId: string): boolean;
+    /** Onboard a domain, mirroring the server's per-mode record set + status. Idempotent on the name. */
+    onboardDomain(req: OnboardDomainRequest): Domain;
+    /** List onboarded domains (records omitted on the summary, mirroring the server). */
+    listDomains(): Page<Domain>;
+    /** Get one domain's detail + the records to set, inline; undefined when absent. */
+    getDomain(domain: string): Domain | undefined;
+    /** Trigger/refresh verification; returns the (re-read) detail, or undefined when absent. */
+    verifyDomain(domain: string): Domain | undefined;
+    /**
+     * Offboard (remove) a domain; returns false when it was not found. Also
+     * records a synthetic succeeded teardown job under `job-offboard-<domain>`
+     * (there is no job runner in the mock) so a subsequent {@link getJob} poll
+     * resolves the same way the live transport's async contract would.
+     */
+    offboardDomain(domain: string): boolean;
+    /** Get one async job's poll status; undefined when the id is unknown. */
+    getJob(jobId: string): Job | undefined;
+    /**
+     * Pre-check whether the caller's org suppresses a recipient (mirrors
+     * `GET /v1/suppressions?recipient=…`). Returns `{recipient, suppressed, rows}`
+     * over the active (non-revoked) org rows for that canonicalized recipient.
+     */
+    precheckSuppression(recipient: string): SuppressionPrecheck;
+    /** List the caller's own org suppression rows (mirrors the paged `GET /v1/suppressions`). */
+    listSuppressions(params: ListSuppressionsParams): Page<SuppressionEntry>;
+    /**
+     * Revoke one org-scope suppression row (mirrors `POST /v1/suppressions/{id}/revoke`).
+     * A reason is required (the caller validates too). Returns the updated row, or
+     * undefined when the id is unknown / not the caller's own org row.
+     */
+    revokeSuppression(id: string, reason: string): SuppressionEntry | undefined;
+    /**
+     * Reject the WHOLE send if ANY recipient has an active org-scope suppression,
+     * naming exactly the suppressed addresses (never the scope/origin) so the caller
+     * can drop them and retry — mirroring the live `recipient_suppressed` (422) path.
+     */
+    private enforceSuppression;
+    /**
+     * Enforce the send-direction contact lists for an inbox: reject a block-listed
+     * recipient, or any recipient outside the allowlist when allowlist mode is on.
+     * Throws a {@link PermissionError} (403) to mirror the real API.
+     */
+    private enforceSendPolicy;
+}
+
+/**
+ * Key-tier awareness (redesign §3.1).
+ *
+ * An agent key encodes its CEILING tier in its raw prefix. The SDK never trusts
+ * client input for scope — the tier is derived from the key the caller already
+ * holds, purely as a client-side hint so an app can branch (e.g. an org-tier key
+ * MUST pick a project breadth on a list; a project/inbox key may use the bare
+ * sugar). The server remains the source of truth; this is advisory only.
+ *
+ * Prefix scheme (the secret tail is unchanged across tiers):
+ *   - `pk_agent_org_…`   → {@link KeyTier.Org}      (admin/console mint only)
+ *   - `pk_agent_proj_…`  → {@link KeyTier.Project}  (enrollment redeem + console)
+ *   - `pk_agent_inbox_…` → {@link KeyTier.Inbox}    (admin/console mint only)
+ *   - legacy `pk_agent_…` (no tier segment) → {@link KeyTier.Project}
+ */
+/** The ceiling tier encoded in an agent key's prefix. */
+type KeyTier = "org" | "project" | "inbox" | "unknown";
+/**
+ * Derive the {@link KeyTier} from a raw agent key by peeking the segment after the
+ * `pk_agent_` head. A legacy bare `pk_agent_…` key (no tier segment) maps to
+ * `"project"` — exactly today's behavior. A non-agent credential (enrollment
+ * token, Clerk session, empty) returns `"unknown"`.
+ */
+declare function parseKeyTier(apiKey: string | undefined): KeyTier;
+/**
+ * Whether a key of this tier can address the org-wide wildcard (`/v1/projects/-/…`).
+ * Only an org-tier key may; a project/inbox key on the wildcard is a 403. Use this
+ * to fail fast client-side before a round-trip.
+ */
+declare function tierAllowsOrgWildcard(tier: KeyTier): boolean;
+/**
+ * Whether a bare (project-less) list is unambiguous for this tier. An org-tier key
+ * MUST pick a breadth (a concrete project or the `-` wildcard), so a bare list is a
+ * 400 `breadth_required`; project/inbox keys default to their bound project.
+ */
+declare function tierNeedsExplicitBreadth(tier: KeyTier): boolean;
+
+/**
+ * InboxHandle — an ergonomic, bound handle to a single inbox.
+ *
+ * Returned by `extrovert.inboxes.create(...)` and `extrovert.inbox(address)`, it scopes every operation
+ * to one address so agent code reads naturally: `inbox.send(...)`, `inbox.waitForEmail(...)`. This
+ * is the "one agent = one inbox" shape the spec's identity model encourages (§5).
+ */
+
+interface InboxHandleOptions {
+    /** Default per-call timeout for blocking calls; resolved from the client config. */
+    defaultWaitTimeoutMs: number;
+}
+declare class InboxHandle {
+    private readonly transport;
+    private readonly options;
+    /** The canonical address, e.g. `agent7@smtp.extrovert.dev`. */
+    readonly address: string;
+    /** The full inbox record this handle was created from (absent when constructed by address). */
+    readonly record: Inbox | undefined;
+    constructor(transport: Transport, address: string, options: InboxHandleOptions, record?: Inbox);
+    /** The inbox id, when known. */
+    get id(): string | undefined;
+    /**
+     * The canonical key every transport op routes on. The contract canonicalizes the
+     * OPAQUE inbox id (`pmbx_…`) and accepts the address only as a within-project alias
+     * (both are valid in the `{inbox_id}` path slot). When this handle was built from a
+     * full record we route by the canonical `id` (matching the "an inbox's canonical key
+     * is its opaque id" docs); when built bare from an address (`client.inbox(addr)`),
+     * the address alias is the only key we have, so we route on it.
+     */
+    private get ref();
+    /**
+     * Arbitrary key-value metadata on this inbox, when known (from the record this
+     * handle was created from). Call {@link refresh} to re-read it after an update.
+     */
+    get metadata(): Inbox["metadata"] | undefined;
+    /** Effective rolling-24-hour recipient cap, when known. */
+    get dailySendLimit(): number | undefined;
+    /** Provisioning status, when known. */
+    get status(): InboxStatus | undefined;
+    /** Onboarding mode of the host domain, when known. */
+    get onboardingMode(): OnboardingMode | undefined;
+    /** Credentials, present only when the inbox was created with `returnCredentials: true`. */
+    get credentials(): InboxCredentials | undefined;
+    /** Re-fetch the live inbox record. */
+    refresh(signal?: AbortSignal): Promise<Inbox>;
+    /**
+     * Update this inbox's settings in place without delete+recreate: rename the sender
+     * `display_name`, change the `webhook_url`, patch arbitrary `metadata` (shallow
+     * merge; a key set to `null` deletes it, top-level `metadata: null` clears all),
+     * or set `daily_send_limit` to 1–10,000 recipients per rolling 24h. The limit
+     * field requires the opt-in `mailbox:quota` scope.
+     * Returns the updated inbox record.
+     */
+    update(req: UpdateInboxRequest, signal?: AbortSignal): Promise<Inbox>;
+    /**
+     * Send an email from this authenticated inbox. Starts a new thread.
+     *
+     * Returns a three-way {@link SendOutcome}: `kind:"queued_for_review"` means a
+     * human has to approve it and NOTHING has been delivered yet; anything else was
+     * delivered. Under the default `require_review` policy a call WITHOUT an
+     * `intent` raises `IntentRequiredError` (422) instead — nothing sent, nothing
+     * queued — so pass one, or read `inbox.record.effective_review_policy` first.
+     */
+    send(req: SendRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    /**
+     * Reply within an existing thread. Select the parent with `thread_id` (reply to
+     * the latest message) or `message_id` (reply to that message); the server
+     * derives To / Subject / In-Reply-To / References. Set `reply_all` to reply to
+     * every thread recipient. Returns the same three-way {@link SendOutcome} as
+     * {@link send} — a reply is governed by the review policy too.
+     */
+    reply(req: ReplyRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    /**
+     * Forward a message in this inbox to new recipients, preserving the original.
+     *
+     * A forward is an outbound message to arbitrary NEW recipients that quotes an
+     * inbound thread, so it is governed by the review policy exactly like a send —
+     * same {@link SendOutcome} union, same `intent` requirement.
+     */
+    forward(messageId: string, req: ForwardRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    /**
+     * Submit a new message from this inbox for human review (Review Loop, HITL).
+     * Pass `intent` (required when the resolved mode is review) and optionally
+     * `mode`/`category_id`. The account/inbox review policy decides whether the
+     * message is queued for review (`kind:"queued_for_review"`) or sent on a
+     * policy-permitted direct path (`kind:"sent"`). Monitor it via
+     * `extrovert.reviews`.
+     */
+    submitForReview(req: SendRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    /**
+     * Submit an in-thread reply from this inbox for human review (Review Loop).
+     * Same routing/return contract as {@link submitForReview}.
+     */
+    submitReplyForReview(req: ReplyRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    /**
+     * List messages in this inbox, newest first. Narrow with exact-field filters
+     * (from/to/subject substring) or `unread: true` (native \Seen); page with
+     * limit + offset.
+     */
+    messages(params?: ListMessagesParams, signal?: AbortSignal): Promise<Page<Message>>;
+    /** Full-text search this inbox (IMAP SEARCH over from/subject/body). */
+    search(params: SearchMessagesParams, signal?: AbortSignal): Promise<Page<Message>>;
+    /** Download the raw RFC822 `.eml` bytes for a message in this inbox. */
+    messageRaw(messageId: string, signal?: AbortSignal): Promise<string>;
+    /** Mark a message in this inbox read/unread via the native \Seen flag. */
+    markRead(messageId: string, req: MarkReadRequest, signal?: AbortSignal): Promise<Message>;
+    /**
+     * Delete a message in this inbox: move it to Trash (default, recoverable) or
+     * permanently remove it when `expunge` is true.
+     */
+    deleteMessage(messageId: string, expunge?: boolean, signal?: AbortSignal): Promise<DeleteResult>;
+    /**
+     * Batch mark read/unread and/or move folder for a list of message ids in this
+     * inbox. At least one of `read` / `folder` must be set; returns the per-id
+     * `{updated, failed}` split.
+     */
+    batchUpdateMessages(req: BatchUpdateMessagesRequest, signal?: AbortSignal): Promise<BatchUpdateResult>;
+    /** List a message's attachment metadata ({id, filename, content_type, size}). */
+    attachments(messageId: string, signal?: AbortSignal): Promise<Page<Attachment>>;
+    /** Download one attachment's bytes (base64) plus filename and content type. */
+    attachment(messageId: string, attachmentId: string, signal?: AbortSignal): Promise<AttachmentDownload>;
+    /** List conversation threads in this inbox, newest-active first. */
+    threads(params?: ListThreadsParams, signal?: AbortSignal): Promise<Page<Thread>>;
+    /** Thread-level search in this inbox (subject / snippet / participants). */
+    searchThreads(params: SearchMessagesParams, signal?: AbortSignal): Promise<Page<Thread>>;
+    /** Fetch one thread (with its messages) in this inbox by stable id. */
+    thread(threadId: string, signal?: AbortSignal): Promise<ThreadDetail>;
+    /**
+     * Delete an entire thread in this inbox (every message): move to Trash
+     * (default) or permanently remove when `expunge` is true.
+     */
+    deleteThread(threadId: string, expunge?: boolean, signal?: AbortSignal): Promise<DeleteResult>;
+    /**
+     * Poll server-side until a matching message arrives and return it with an extracted
+     * OTP / verification link. The HTTP read timeout is set a hair above the server-side
+     * `timeoutSeconds` so the request doesn't abort before the server returns its own timeout result.
+     */
+    waitForEmail(req?: WaitForEmailRequest, signal?: AbortSignal): Promise<WaitForEmailResult>;
+    /** Register an HMAC-signed inbound webhook scoped to this inbox. */
+    registerWebhook(req: Omit<RegisterWebhookRequest, "inbox">, signal?: AbortSignal): Promise<Webhook>;
+    /**
+     * Add an allow/block contact-list entry to this inbox. A `block` entry rejects a
+     * send to a matching recipient; once any `allow` entry exists, sends from this
+     * inbox are restricted to recipients that match one (allowlist mode).
+     */
+    addContactListEntry(req: AddContactListRequest, signal?: AbortSignal): Promise<ContactListEntry>;
+    /** List the allow/block contact-list entries governing this inbox. */
+    listContactLists(signal?: AbortSignal): Promise<Page<ContactListEntry>>;
+    /** Delete a contact-list entry on this inbox by id. */
+    deleteContactListEntry(entryId: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Watch this inbox live (Server-Sent Events). Returns an async iterator of
+     * {@link StreamEvent}; each `message.received` event arrives as it lands instead
+     * of polling {@link waitForEmail}. Pass `lastEventId` (the `seq` of the last
+     * event you saw) to resume without gaps after a reconnect, and a `signal` to
+     * close the stream.
+     *
+     * ```ts
+     * for await (const ev of inbox.stream()) {
+     *   if (ev.event === "message.received") console.log("new mail:", ev.message?.subject);
+     * }
+     * ```
+     */
+    stream(options?: StreamOptions): AsyncGenerator<StreamEvent, void, unknown>;
+    /**
+     * Convenience wrapper over {@link stream}: invoke `onEvent` for every event until
+     * the stream closes (or `signal` aborts). Returns when the stream ends.
+     */
+    subscribe(onEvent: (event: StreamEvent) => void | Promise<void>, options?: StreamOptions): Promise<void>;
+    /**
+     * Permanently tear down this inbox and its messages/sender identity. Requires
+     * `mailbox:delete`; this operation cannot be undone.
+     */
+    delete(signal?: AbortSignal): Promise<void>;
+}
+
+/**
+ * `extrovert.projects` — the CANONICAL project-scoped resource chain (redesign §4).
+ *
+ * Scope lives in the KEY; a broad (org-tier) key narrows to one project by PATH.
+ * The headline chain is `x.projects.inboxes.*`, mirroring
+ * `/v1/projects/{project_id}/inboxes[/{inbox_id}]`:
+ *
+ * ```ts
+ * const inbox = await x.projects.inboxes.create("proj_9k", { username: "ada" });
+ * const page  = await x.projects.inboxes.list("proj_9k");        // List envelope
+ * for await (const i of page) console.log(i.id);                 // auto-paginates
+ * await x.projects.inboxes.send("proj_9k", inbox.id, { to, subject, text });
+ * ```
+ *
+ * Operations are keyed by the OPAQUE `inbox_id` (the inbox's email address is also
+ * accepted as a within-project alias). `projectId` may be `"-"` for the org-wide
+ * wildcard — only an org-tier key may use it (others get 403 `forbidden_scope`).
+ *
+ * The bare `x.inboxes.*` / `x.inbox(address)` surface is curl-style sugar that
+ * resolves to the key's default project; this chain is the contract-canonical one.
+ */
+
+/** Options forwarded into the chain (per-call wait timeout, resolved from the client). */
+interface ProjectsContext {
+    transport: Transport;
+    handleOptions: InboxHandleOptions;
+}
+/**
+ * `x.projects.inboxes` — create / list / get / update / delete inboxes, plus the
+ * send / reply / message / thread / wait operations, all scoped to one project (or
+ * the `-` org wildcard for an org-tier key). List returns a {@link ListPage} that
+ * auto-paginates over the opaque-cursor {@link import("../pagination.js").List} envelope.
+ */
+declare class ProjectInboxes {
+    private readonly ctx;
+    constructor(ctx: ProjectsContext);
+    /** Create an inbox in `projectId`. `idempotencyKey` (or `req.client_id`) makes it exactly-once. */
+    create(projectId: string, req?: CreateInboxRequest, idempotencyKey?: string, signal?: AbortSignal): Promise<Inbox>;
+    /**
+     * List inboxes in `projectId` (or the org subtree with `projectId="-"`). Returns a
+     * {@link ListPage} that yields the {@link import("../pagination.js").List} envelope's
+     * rows and auto-paginates across pages via the opaque cursor.
+     */
+    list(projectId: string, params?: ProjectInboxListParams, signal?: AbortSignal): Promise<ListPage<Inbox>>;
+    /** Get an inbox by opaque `inboxId` (or address alias) in `projectId`. */
+    get(projectId: string, inboxId: string, params?: GetInboxParams, signal?: AbortSignal): Promise<Inbox>;
+    /**
+     * Update an inbox in place (display name / webhook / metadata / daily send
+     * limit). `daily_send_limit` requires the opt-in `mailbox:quota` scope.
+     */
+    update(projectId: string, inboxId: string, req: UpdateInboxRequest, signal?: AbortSignal): Promise<Inbox>;
+    /**
+     * Permanently delete an inbox by opaque id (or address alias). Requires
+     * `mailbox:delete`; the inbox and its messages cannot be recovered.
+     */
+    delete(projectId: string, inboxId: string, signal?: AbortSignal): Promise<void>;
+    /** Fetch IMAP/SMTP connection settings + login for an inbox. */
+    credentials(projectId: string, inboxId: string, signal?: AbortSignal): Promise<InboxCredentials>;
+    /**
+     * Send an email from an inbox in `projectId`.
+     *
+     * Returns a three-way {@link SendOutcome}: `kind:"queued_for_review"` means a
+     * human has to approve it and NOTHING has been delivered yet; anything else was
+     * delivered. Under the default `require_review` policy a call WITHOUT an
+     * `intent` raises `IntentRequiredError` (422) instead — nothing sent, nothing
+     * queued — so pass one, or read `inbox.record.effective_review_policy` first.
+     */
+    send(projectId: string, inboxId: string, req: SendRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    /** Reply within a thread from an inbox in `projectId`. See {@link send} on the return union. */
+    reply(projectId: string, inboxId: string, req: ReplyRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    /** Forward a message from an inbox in `projectId`. See {@link send} on the return union. */
+    forward(projectId: string, inboxId: string, messageId: string, req: ForwardRequest, signal?: AbortSignal): Promise<SendOutcome>;
+    /** List messages in an inbox in `projectId`. */
+    messages(projectId: string, inboxId: string, params?: ListMessagesParams, signal?: AbortSignal): Promise<Page<Message>>;
+    /** Search messages in an inbox in `projectId`. */
+    searchMessages(projectId: string, inboxId: string, params: SearchMessagesParams, signal?: AbortSignal): Promise<Page<Message>>;
+    /** Mark a message read/unread in an inbox in `projectId`. */
+    markRead(projectId: string, inboxId: string, messageId: string, req: MarkReadRequest, signal?: AbortSignal): Promise<Message>;
+    /** Delete a message in an inbox in `projectId`. */
+    deleteMessage(projectId: string, inboxId: string, messageId: string, expunge?: boolean, signal?: AbortSignal): Promise<DeleteResult>;
+    /** Batch mark/move messages in an inbox in `projectId`. */
+    batchUpdateMessages(projectId: string, inboxId: string, req: BatchUpdateMessagesRequest, signal?: AbortSignal): Promise<BatchUpdateResult>;
+    /** List a message's attachment metadata. */
+    attachments(projectId: string, inboxId: string, messageId: string, signal?: AbortSignal): Promise<Page<Attachment>>;
+    /** Download one attachment's bytes + filename + content type. */
+    attachment(projectId: string, inboxId: string, messageId: string, attachmentId: string, signal?: AbortSignal): Promise<AttachmentDownload>;
+    /** List conversation threads in an inbox in `projectId`. */
+    threads(projectId: string, inboxId: string, params?: ListThreadsParams, signal?: AbortSignal): Promise<Page<Thread>>;
+    /** Fetch one thread (+ its messages) in an inbox in `projectId`. */
+    thread(projectId: string, inboxId: string, threadId: string, signal?: AbortSignal): Promise<ThreadDetail>;
+    /**
+     * Block until a matching message arrives in an inbox in `projectId` and return it
+     * with an extracted OTP / verification link.
+     */
+    waitForEmail(projectId: string, inboxId: string, req?: WaitForEmailRequest, signal?: AbortSignal): Promise<WaitForEmailResult>;
+    /**
+     * The inbox reference the message/send/thread transport methods key on.
+     *
+     * The frozen contract project-prefixes ONLY the inbox collection/item/credentials
+     * routes (`/v1/projects/{project_id}/inboxes[/{inbox_id}][/credentials]`); the
+     * send/reply/forward/message/thread/wait sub-ops have NO project-prefixed path —
+     * they address the inbox by its opaque id directly (`/v1/inboxes/{inbox_id}/…`),
+     * where the project is implicit in (and enforced by) the inbox id server-side.
+     *
+     * So for these sub-ops `projectId` cannot be carried on the URL and is NOT a URL
+     * selector. The adversarial review flagged that silently discarding it makes the
+     * signature misleading. CHOICE: keep the arg (dropping it would break the chain's
+     * symmetry with create/list/get/update/delete — the more disruptive option) but
+     * VALIDATE it rather than ignore it. We reject the two client mistakes we can catch
+     * without a round-trip:
+     *   - a blank / whitespace-only `projectId` (a required selector everywhere else in
+     *     the chain), and
+     *   - the org wildcard `-`, which is meaningless for a single-inbox op (there is no
+     *     breadth to pick).
+     * The inbox-id ↔ project binding itself is enforced server-side by the opaque id.
+     */
+    private ref;
+}
+/**
+ * `extrovert.projects` — the canonical project-scoped resource namespace. Today it
+ * exposes the `inboxes` chain (`x.projects.inboxes.*`); future project-scoped
+ * resources (domains, agents) hang off the same namespace.
+ */
+declare class Projects {
+    /** `x.projects.inboxes.*` — the canonical inbox chain. */
+    readonly inboxes: ProjectInboxes;
+    constructor(ctx: ProjectsContext);
+}
+
+/**
+ * Resource namespaces: `extrovert.inboxes`, `extrovert.messages`, `extrovert.threads`,
+ * `extrovert.webhooks`, `extrovert.contactLists`, `extrovert.domains`. Each is a thin,
+ * typed facade over the {@link Transport}.
+ */
+
+interface ResourceContext {
+    transport: Transport;
+    handleOptions: InboxHandleOptions;
+    /**
+     * The CEILING tier derived from the configured key prefix. Advisory client-side
+     * hint ONLY (the server stays authoritative); lets the bare sugar surface fail
+     * fast for an org-tier key that must pick a breadth, matching the MCP surface.
+     */
+    keyTier: KeyTier;
+}
+/** `extrovert.inboxes` — create, list, get, update, delete inboxes. */
+declare class Inboxes {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /**
+     * Create an inbox. The default path mints an address on a pre-verified shared subdomain of
+     * `smtp.extrovert.dev`, so it returns a live, send-and-receive-capable inbox in one call.
+     *
+     * Pass `metadata` to attach arbitrary key-value data, and `client_id` for idempotent creation
+     * (re-calling with the same id returns the same inbox, with its metadata replayed verbatim).
+     */
+    create(req?: CreateInboxRequest, signal?: AbortSignal): Promise<InboxHandle>;
+    /**
+     * List inboxes visible to the calling key (the bare curl-sugar surface — resolves
+     * to the key's default project). An org-tier key has no single default project, so
+     * the bare list is ambiguous: fail fast client-side with a BreadthRequiredError that
+     * names the next call, matching the MCP surface, instead of round-tripping to a 400.
+     * Use `extrovert.projects.inboxes.list("<project_id>")` or `"-"` (org subtree) for
+     * an org key. The check is advisory — the server stays authoritative.
+     */
+    list(params?: ListInboxesParams, signal?: AbortSignal): Promise<Page<Inbox>>;
+    /** Fetch a single inbox and return an ergonomic handle bound to it. */
+    get(address: string, signal?: AbortSignal): Promise<InboxHandle>;
+    /**
+     * Update an inbox's settings in place without delete+recreate: rename the sender
+     * `display_name`, change the `webhook_url`, patch arbitrary `metadata` (shallow
+     * merge; a key set to `null` deletes it, top-level `metadata: null` clears all),
+     * or set the effective `daily_send_limit` (1–10,000 recipients per rolling 24h).
+     * Updating the daily limit requires the opt-in `mailbox:quota` scope.
+     * Returns a handle bound to the updated record.
+     */
+    update(address: string, req: UpdateInboxRequest, signal?: AbortSignal): Promise<InboxHandle>;
+    /**
+     * Permanently delete an inbox by address. Requires `mailbox:delete`; the inbox,
+     * messages, and sender identity cannot be recovered.
+     */
+    delete(address: string, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * `extrovert.messages` — read a message, fetch its raw bytes, mark it read.
+ *
+ * Reply and forward are inbox-scoped (the server resolves the parent and derives
+ * recipients), so they live on the {@link InboxHandle} (`inbox.reply(...)`,
+ * `inbox.forward(...)`), not here.
+ */
+declare class Messages {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /** Fetch a single message by its opaque id; the owning inbox is resolved from the id. */
+    get(messageId: string, signal?: AbortSignal): Promise<Message>;
+    /**
+     * Download the raw RFC822 `.eml` bytes for a message. `inbox` is the owning
+     * address (needed to open the inbox); the id identifies the message.
+     */
+    raw(inbox: string, messageId: string, signal?: AbortSignal): Promise<string>;
+    /**
+     * Mark a message read/unread via the native IMAP \Seen flag (Extrovert's
+     * label-free read state). `inbox` is the owning address.
+     */
+    markRead(inbox: string, messageId: string, req: MarkReadRequest, signal?: AbortSignal): Promise<Message>;
+    /**
+     * Delete a message: move it to Trash (default, recoverable) or permanently
+     * remove it when `expunge` is true. `inbox` is the owning address.
+     */
+    delete(inbox: string, messageId: string, expunge?: boolean, signal?: AbortSignal): Promise<DeleteResult>;
+    /**
+     * Batch mark read/unread and/or move folder for a list of message ids in one
+     * inbox. At least one of `read` / `folder` must be set; returns the per-id
+     * `{updated, failed}` split.
+     */
+    batchUpdate(inbox: string, req: BatchUpdateMessagesRequest, signal?: AbortSignal): Promise<BatchUpdateResult>;
+    /**
+     * List a message's attachment metadata ({id, filename, content_type, size}).
+     * `inbox` is the owning address; the message id identifies the message.
+     */
+    listAttachments(inbox: string, messageId: string, signal?: AbortSignal): Promise<Page<Attachment>>;
+    /**
+     * Download one attachment's bytes (base64) plus its filename and content type.
+     * The "easy attachment fetch": `inbox` is the owning address, `messageId` the
+     * message, and `attachmentId` the opaque id from {@link listAttachments}.
+     */
+    getAttachment(inbox: string, messageId: string, attachmentId: string, signal?: AbortSignal): Promise<AttachmentDownload>;
+}
+/**
+ * `extrovert.threads` — fetch a conversation thread (with its messages) by id,
+ * scoped to its owning inbox.
+ */
+declare class Threads {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /** Fetch one thread (+ its messages, oldest-first) by id under its owning inbox address. */
+    get(inbox: string, threadId: string, signal?: AbortSignal): Promise<ThreadDetail>;
+    /**
+     * Delete an entire thread (every message): move to Trash (default) or
+     * permanently remove when `expunge` is true. `inbox` is the owning address.
+     */
+    delete(inbox: string, threadId: string, expunge?: boolean, signal?: AbortSignal): Promise<DeleteResult>;
+}
+/** `extrovert.webhooks` — register / list / get / update / delete HMAC-signed inbound webhooks. */
+declare class Webhooks {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /** Register an HMAC-signed, timestamped webhook. The signing `secret` is returned once. */
+    register(req: RegisterWebhookRequest, signal?: AbortSignal): Promise<Webhook>;
+    /** List registered webhooks (the one-time signing `secret` is omitted). */
+    list(signal?: AbortSignal): Promise<Page<Webhook>>;
+    /** Fetch one webhook by id (the signing `secret` is omitted). */
+    get(webhookId: string, signal?: AbortSignal): Promise<Webhook>;
+    /**
+     * Update a webhook in place: change the delivery `url`, the subscribed
+     * `events`, the `inbox` filter (empty string clears it), or `active` to
+     * enable/disable delivery. Omitted fields are left unchanged (PATCH
+     * semantics). The signing `secret` is immutable and stays redacted.
+     */
+    update(webhookId: string, req: UpdateWebhookRequest, signal?: AbortSignal): Promise<Webhook>;
+    /** Delete a webhook by id. */
+    delete(webhookId: string, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * `extrovert.contactLists` — per-inbox allow/block lists of addresses/domains.
+ * A `block` entry rejects a send to a matching recipient; once an `allow` entry
+ * exists for an inbox, sends from it are restricted to matching recipients
+ * (allowlist mode). Entries are addressable by their opaque id (`lst_…`).
+ */
+declare class ContactLists {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /** Add an allow/block entry to an inbox. */
+    add(inbox: string, req: AddContactListRequest, signal?: AbortSignal): Promise<ContactListEntry>;
+    /** List the entries governing an inbox (inbox-specific + account-wide). */
+    list(inbox: string, signal?: AbortSignal): Promise<Page<ContactListEntry>>;
+    /** Delete an entry on an inbox by id. */
+    delete(inbox: string, entryId: string, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * `extrovert.suppressions` — recipient opt-outs (list-unsubscribe). A recipient
+ * that has unsubscribed cannot be mailed by this org: a send to them is rejected
+ * with `recipient_suppressed` ({@link RecipientSuppressedError}). Use `precheck`
+ * before composing to skip a would-be-rejected recipient, `list` to browse the
+ * org's opt-outs, and `revoke` (reason required, audit-logged) to re-enable a
+ * recipient. All reads/writes are scoped to the caller's OWN org — a
+ * platform-global or shared-domain opt-out is never surfaced here.
+ */
+declare class Suppressions {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /**
+     * Pre-check whether the caller's org already suppresses a recipient, BEFORE
+     * composing. `suppressed: true` means a send to them would be rejected — skip
+     * that recipient. Returns the matching org rows too (never a global/shared row).
+     */
+    precheck(recipient: string, signal?: AbortSignal): Promise<SuppressionPrecheck>;
+    /** List the org's suppression rows (active by default; `include_revoked` for all). */
+    list(params?: ListSuppressionsParams, signal?: AbortSignal): Promise<Page<SuppressionEntry>>;
+    /**
+     * Revoke one org-scope suppression row (re-enable sending to that recipient). A
+     * `reason` is REQUIRED (empty/whitespace is a 400) and is audit-logged. A
+     * foreign/global/shared id is an indistinguishable 404.
+     */
+    revoke(id: string, reason: string, signal?: AbortSignal): Promise<SuppressionEntry>;
+}
+/**
+ * `extrovert.domains` — the customer's domains (privileged; the agent key must
+ * carry the `domain:manage` scope). Onboard (shared | ns_delegated | manual |
+ * purchased), read status + the DNS records to set inline, trigger/refresh
+ * verification, and offboard. `mode: "purchased"` spends money at the registrar and
+ * ADDITIONALLY requires the explicit, default-off `domain:purchase` scope (and is
+ * capped by the org/project purchased-domain plan limit). Set `scope: "project"` to
+ * bind the domain to the key's project; it defaults to `org` (org-shared).
+ */
+declare class Domains {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /** List the customer's onboarded domains and their status. */
+    list(signal?: AbortSignal): Promise<Page<Domain>>;
+    /** Get one domain's detail + verification status + the DNS records to set, inline. */
+    get(domain: string, signal?: AbortSignal): Promise<Domain>;
+    /**
+     * Onboard (add) a domain. `mode` defaults to ns_delegated. `mode: "purchased"`
+     * requires the `domain:purchase` scope (in addition to `domain:manage`). Returns
+     * the record set / NS instruction.
+     */
+    onboard(req: OnboardDomainRequest, signal?: AbortSignal): Promise<Domain>;
+    /** Trigger or refresh verification for a domain; returns its (possibly advanced) status. */
+    verify(domain: string, signal?: AbortSignal): Promise<Domain>;
+    /**
+     * Offboard (remove) a domain from the customer. Async: the API accepts the
+     * request (HTTP 202) and tears the domain down as a job. Returns the accepted
+     * job's id + poll URL (`status_url`); poll it with `extrovert.getJob(job_id)`
+     * until the status is terminal (succeeded/failed/cancelled).
+     */
+    offboard(domain: string, signal?: AbortSignal): Promise<DomainOffboard>;
+}
+/**
+ * `extrovert.reviews` — the Review Loop (HITL) agent-plane reads. A sending agent
+ * monitors its submissions in the human-review queue: list/get a review request and
+ * read its append-only thread of turns (intent, drafts, human comments/edits/
+ * decisions, captured diffs). Submitting FOR review rides `inbox.send` /
+ * `inbox.reply` with `mode`/`intent`/`category_id`. Human-authority actions
+ * (approve/reject/edit-send) are console-only (D17) and never exposed here.
+ */
+declare class Reviews {
+    private readonly ctx;
+    /**
+     * `extrovert.reviews.events` — the Review Loop (HITL) realtime plane: drain,
+     * long-poll, and ack the durable nudge queue (the AUTHORITATIVE liveness source;
+     * SSE/webhook are best-effort fast paths on top of it).
+     */
+    readonly events: ReviewEvents;
+    constructor(ctx: ResourceContext);
+    /** List review requests (customer-scoped). Filter by state / category / inbox. */
+    list(params?: ListReviewsParams, signal?: AbortSignal): Promise<Page<Review>>;
+    /** Get one review request by id (rr_…): current draft + intent + state. */
+    get(reviewId: string, signal?: AbortSignal): Promise<Review>;
+    /** Get a review's append-only thread turns by id (rr_…). */
+    turns(reviewId: string, signal?: AbortSignal): Promise<Page<ReviewTurn>>;
+    /**
+     * Get the human's assembled feedback (M5): the diff + comments + decision + the
+     * rules born from this review. Read it after a rejected/edited nudge to learn what
+     * the human wanted. $0 LLM — pure assembly on our side.
+     */
+    feedback(reviewId: string, signal?: AbortSignal): Promise<ReviewFeedback>;
+    /**
+     * Post a chat turn on a review's thread (M5): an agent question to the human
+     * reviewer; flips in_review -> chatting on the first turn. Idempotent on the
+     * optional `idempotencyKey` (the `Idempotency-Key` header). $0 LLM — you compose it.
+     */
+    chat(reviewId: string, req: PostReviewChatRequest, idempotencyKey?: string, signal?: AbortSignal): Promise<Review>;
+    /**
+     * Post a new agent draft under a parent_revision CAS (M5; D17). parent_revision
+     * must equal the draft's current revision, else a 409 STALE with NO mutation (the
+     * human always wins — re-read, re-apply, retry). On success the draft is re-rendered
+     * in place (revision++) and returns to needs_review. $0 LLM — you compose the redraft.
+     */
+    revise(reviewId: string, req: SubmitRevisionRequest, signal?: AbortSignal): Promise<Review>;
+    /**
+     * Withdraw your own pending review (M5) to the terminal cancelled state. Only the
+     * composing agent may cancel; a terminal (already sent) review 409s.
+     */
+    cancel(reviewId: string, idempotencyKeyOrSignal?: string | AbortSignal, signal?: AbortSignal): Promise<Review>;
+    /**
+     * Re-stamp a draft's rules-version WITHOUT redrafting (M7; D19/§8 $0 escape valve):
+     * assert "I reviewed this against rules vX and no change is needed", advancing the
+     * draft's composed_* versions with no new draft, no revision bump, no nudge. A
+     * born-stale draft re-stamped to the current version becomes current-enough and
+     * releasable on the next reconciliation sweep — the cheap counterpart to revise().
+     * against_version above the category's current rules-version is 400; a terminal draft
+     * 409s. $0 LLM — you judged.
+     */
+    restamp(reviewId: string, req: RestampReviewRequest, signal?: AbortSignal): Promise<Review>;
+    /**
+     * Get the REVIEWER's decision context for a review (M8 Slice B; D5/§9). The reviewer
+     * is an AGENT granted review:act, authorized for THIS review ONLY via a matching
+     * ACTIVE review-link (per-inbox beats account-wide). The context is the intent +
+     * current draft + thread + the two-circuit-breaker budget (hop_count vs max_hops, the
+     * hard review_deadline). `force_to_human` is true when a reject would be FORCED to the
+     * human regardless of intent (the human is the only terminal authority, D17). A
+     * cross-tenant id is 404; a non-reviewer is 403. Read-only, $0 LLM.
+     */
+    decisionContext(reviewId: string, signal?: AbortSignal): Promise<ReviewDecisionContext>;
+    /**
+     * Submit a reviewer decision (M8 Slice B; reviewer_decide, D5/§9). approve/edit → the
+     * PLATFORM ACS-sends with the COMPOSER's credentials (the reviewer NEVER holds
+     * mailbox:send on an inbox it doesn't own — the credential boundary); reject → back to
+     * the composer (needs_review, hop_count++); escalate → the human queue. revision/
+     * version are the CAS (409 STALE on mismatch, NO mutation — the human always wins,
+     * D17). The two circuit breakers (hop_count ≥ max_hops, or the hard review_deadline)
+     * FORCE a reject to the human regardless of intent — `forced_by_breaker` names it. $0
+     * LLM — you judged; we route, send, and enforce the breakers.
+     */
+    decide(reviewId: string, req: ReviewerDecisionRequest, signal?: AbortSignal): Promise<ReviewerDecisionResult>;
+}
+/**
+ * `extrovert.reviews.events` — drain / long-poll / ack the durable review nudge
+ * queue (spec §5.9). `list` is a non-blocking, side-effect-free drain of the next
+ * un-acked nudges in FIFO seq order (strict per review); `wait` long-polls
+ * (~25–55s) for the next one; `ack` advances the per-(agent, review) cursor
+ * monotonically (idempotent — re-acking an older seq is a no-op).
+ */
+declare class ReviewEvents {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /** Drain the next un-acked review events (non-blocking). */
+    list(params?: ListReviewEventsParams, signal?: AbortSignal): Promise<ReviewEventsResult>;
+    /** Long-poll for the next review event (empty on timeout). */
+    wait(params?: WaitForReviewEventParams, signal?: AbortSignal): Promise<ReviewEventsResult>;
+    /** Advance the per-review cursor(s) and/or mark broadcast nudges done. */
+    ack(req: AckReviewEventRequest, signal?: AbortSignal): Promise<AckReviewEventResult>;
+}
+/**
+ * `extrovert.categories` — the Review Loop category registry (D9/D10). Browse and
+ * MATCH an existing category before composing (like a skills registry), or propose
+ * a new one. Categories are CUSTOMER-scoped and agent-attributed (the deliberate
+ * cross-agent-404 exception); identity is opaque cat_ ids — nothing keys on the
+ * name, so renames never break a reference. `match` is a pure lexical filter (NO
+ * LLM on our side); the agent does the semantic matching. Merging / deleting a
+ * category is a human (console) action, not exposed here (D17).
+ */
+declare class Categories {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /** Browse the registry. `match` lexically filters name+description (NO LLM). */
+    list(params?: ListCategoriesParams, signal?: AbortSignal): Promise<Page<Category>>;
+    /** Get one category by id (cat_…): name + description + scope + state. */
+    get(categoryId: string, signal?: AbortSignal): Promise<Category>;
+    /** Propose a new category; it stands immediately and writes a create audit row. */
+    propose(req: ProposeCategoryRequest, signal?: AbortSignal): Promise<Category>;
+    /** Rename / re-describe a category — metadata only (D10). */
+    update(categoryId: string, req: UpdateCategoryRequest, signal?: AbortSignal): Promise<Category>;
+    /**
+     * Read the effective risk dial (D4/D12): the account default + every category's
+     * overrides (each with its resolved effective value; null override = inherit).
+     * Read-only — agents read but NEVER flip the dial; setting it is a human (console)
+     * action (D16).
+     */
+    riskDial(signal?: AbortSignal): Promise<RiskDial>;
+    /**
+     * Read a category's graduation gate status (D16): the gates passed / still needed
+     * toward the next rung (approvals N/needed, age, maturity gate, drift vs K,
+     * can_graduate). Read-only.
+     */
+    graduationStatus(categoryId: string, signal?: AbortSignal): Promise<GraduationStatus>;
+    /**
+     * Propose graduating a category (D16/D6): RECORDS the request (durable evidence) and
+     * returns the current gate status. It does NOT change the category state — flipping
+     * the bit is a human (console) action; an agent only proposes.
+     */
+    proposeGraduation(categoryId: string, req?: ProposeGraduationRequest, signal?: AbortSignal): Promise<GraduationStatus>;
+    /**
+     * Read the D19/§8 backlog-reconciliation status: how many of the category's QUEUED
+     * drafts are stale vs current-enough against the current rules-version (a pure
+     * integer compare, $0 LLM). Read-only — you READ the picture; the human (console
+     * scan-backlog) or the graduate/rule-change hooks TRIGGER the actual reconciliation
+     * sweep that releases current-enough drafts and nudges stale ones to redraft.
+     */
+    backlogStatus(categoryId: string, signal?: AbortSignal): Promise<ScanBacklogStatus>;
+    /**
+     * Read the demand-driven pacing state (M7 Slice B/§8): the human review cursor, the
+     * effective lookahead window (freshness is guaranteed only for the next few drafts
+     * after the cursor), the HARD per-nudge fan-out ceiling (rework_batch_max), the
+     * per-agent nudge interval, and each queued draft's classification (behind_cursor |
+     * in_window_fresh | in_window_redrafting | ahead). Read-only; the cursor advances
+     * from the human's console approve/reject/edit actions.
+     */
+    pacingState(categoryId: string, signal?: AbortSignal): Promise<CategoryPacingState>;
+}
+/**
+ * `extrovert.rules` — the Review Loop writing-rule store + house-style + the §7
+ * precedence ladder + audit/undo (D2/D11). ANY agent in the customer may write,
+ * edit, promote, retire, and undo rules (the deliberate cross-agent exception — the
+ * shared house-style is the whole pitch). `get()` returns the ORDERED active rule
+ * set with the precedence ladder applied SERVER-SIDE (NO LLM on our side); the agent
+ * reconciles the list semantically. Rules are append-only by supersession; undo
+ * restores the prior version as a forward 'restore' supersession. Identity is opaque
+ * rule_/rln_/udo_ ids — nothing keys on a name.
+ */
+declare class Rules {
+    private readonly ctx;
+    constructor(ctx: ResourceContext);
+    /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
+    get(params?: GetRulesParams, signal?: AbortSignal): Promise<Page<Rule>>;
+    /**
+     * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
+     * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
+     * key's project. Agents cannot author org-layer / house-style (`rule_layer:"org"`)
+     * rules in v1 — that is a console/admin action.
+     */
+    save(req: SaveRuleRequest, signal?: AbortSignal): Promise<Rule>;
+    /** Promote a rule between the category and general/house-style layers. */
+    promote(ruleId: string, toScope: "general" | "category", signal?: AbortSignal): Promise<Rule>;
+    /** Retire a rule — soft delete; the history survives as training data. */
+    retire(ruleId: string, signal?: AbortSignal): Promise<Rule>;
+    /** Read the rule/category change audit log (the safety net, D11). */
+    audit(params?: GetRuleAuditParams, signal?: AbortSignal): Promise<Page<RuleAuditEntry>>;
+    /** Undo a rule change by its audit-row id (udo_…) — restore the prior version. */
+    undo(udoId: string, signal?: AbortSignal): Promise<Rule>;
+}
+
+/**
+ * ExtrovertClient — the entry point.
+ *
+ * ```ts
+ * import { Extrovert } from "@extrovert.dev/sdk";
+ * const extrovert = new Extrovert({ apiKey: process.env.EXTROVERT_API_KEY! });
+ * const inbox = await extrovert.inboxes.create();        // a real inbox, in one call
+ * const outcome = await inbox.send({
+ *   to: "ops@acme.test",
+ *   subject: "hi",
+ *   text: "from an agent",
+ *   intent: { summary: "send the requested status update" },
+ * });
+ * if (outcome.kind === "queued_for_review") console.log(outcome.review.id);
+ * ```
+ */
+
+/** Default production API base URL. Overridable via `baseUrl` or `EXTROVERT_API_BASE_URL`. */
+declare const DEFAULT_BASE_URL = "https://api.extrovert.dev";
+/** The sentinel that routes the client to the offline mock instead of the network. */
+declare const MOCK_BASE_URL = "mock";
+interface ExtrovertClientOptions {
+    /**
+     * Scoped agent key (`pk_agent_...`) or, for `enroll`, any bearer credential the server accepts.
+     * Falls back to `EXTROVERT_API_KEY` when omitted.
+     */
+    apiKey?: string;
+    /**
+     * API base URL. Falls back to `EXTROVERT_API_BASE_URL`, then {@link DEFAULT_BASE_URL}. Set to
+     * `"mock"` (or `transport: "mock"`) to run fully offline against the built-in fixtures.
+     */
+    baseUrl?: string;
+    /** Force a transport. `"mock"` ignores `baseUrl` and never touches the network. */
+    transport?: "http" | "mock";
+    /** Default request timeout in ms. Default 30000. (wait_for_email manages its own, longer timeout.) */
+    timeoutMs?: number;
+    /** Retry policy for idempotent requests on 429/5xx/network errors. */
+    retry?: Partial<RetryOptions>;
+    /** Custom fetch implementation (tests, proxies, instrumentation). Defaults to global `fetch`. */
+    fetch?: typeof fetch;
+    /** Extra headers merged into every request. */
+    defaultHeaders?: Record<string, string>;
+    /**
+     * Dated API version to pin (sent as the `Extrovert-Version` header on every
+     * request; redesign §5.4). Defaults to {@link CURRENT_API_VERSION}. Pin an older
+     * dated version to opt into the server's transform shim for that version.
+     */
+    apiVersion?: string;
+    /** Inject a pre-built mock backend (shares state across clients in tests). */
+    mockBackend?: MockBackend;
+}
+declare class ExtrovertClient {
+    /** `extrovert.inboxes` — create / list / get / update / delete inboxes. */
+    readonly inboxes: Inboxes;
+    /** `extrovert.messages` — read a message, reply to it (threaded). */
+    readonly messages: Messages;
+    /** `extrovert.threads` — fetch a conversation thread. */
+    readonly threads: Threads;
+    /** `extrovert.webhooks` — register HMAC-signed inbound webhooks. */
+    readonly webhooks: Webhooks;
+    /** `extrovert.contactLists` — per-inbox allow/block lists of addresses/domains. */
+    readonly contactLists: ContactLists;
+    /** `extrovert.suppressions` — recipient opt-outs (list-unsubscribe); precheck/list/revoke. */
+    readonly suppressions: Suppressions;
+    /** `extrovert.domains` — the customer's domains (privileged; domain:manage scope). */
+    readonly domains: Domains;
+    /** `extrovert.reviews` — the Review Loop (HITL) agent-plane reads. */
+    readonly reviews: Reviews;
+    /** `extrovert.categories` — the Review Loop category registry (browse/propose/curate). */
+    readonly categories: Categories;
+    /** `extrovert.rules` — the Review Loop writing-rule store + house-style + audit/undo. */
+    readonly rules: Rules;
+    /**
+     * `extrovert.projects` — the CANONICAL project-scoped chain. The headline is
+     * `extrovert.projects.inboxes.*` (create/list/get/update/delete/send/...), keyed by
+     * the opaque `inbox_id` and scoped to a `{project_id}` path (or `-` for the org
+     * wildcard on an org-tier key). The bare `extrovert.inboxes` surface is curl sugar
+     * that resolves to the key's default project.
+     */
+    readonly projects: Projects;
+    /** The resolved API base URL (or `"mock"`). */
+    readonly baseUrl: string;
+    /**
+     * The dated API version pinned on every request (`Extrovert-Version`). Defaults to
+     * {@link CURRENT_API_VERSION}.
+     */
+    readonly apiVersion: string;
+    /**
+     * The CEILING tier derived from the configured agent key prefix (`org` | `project`
+     * | `inbox` | `unknown`). Advisory client-side hint only — the server is the source
+     * of truth. Lets an app branch (e.g. require a project pick for an org-tier key).
+     */
+    readonly keyTier: KeyTier;
+    private readonly transport;
+    private readonly handleOptions;
+    constructor(options?: ExtrovertClientOptions);
+    /**
+     * Redeem an enrollment token (`pk_enroll_...`) and mint a scoped agent key.
+     *
+     * Idempotent on `agent_handle`: redeeming twice with the same handle returns the same agent.
+     * Returns the raw `EnrollResponse` — to immediately use the minted key, prefer
+     * {@link ExtrovertClient.enrolled}.
+     */
+    enroll(req: EnrollRequest, signal?: AbortSignal): Promise<EnrollResponse>;
+    /**
+     * Grab a free account in one unauthenticated call (Slice E). Provisions a tenant
+     * + a first inbox and returns a LIMITED-scope (read-only) agent key; a one-time
+     * code is emailed to `human_email`. Call {@link verify} with the code to unlock
+     * full scopes. Idempotent on `human_email`: re-calling rotates the key + resends.
+     */
+    signUp(req: SignUpRequest, signal?: AbortSignal): Promise<SignUpResponse>;
+    /**
+     * Confirm the emailed signup code and receive a NEW full-scope agent key (shown
+     * once). Must be called with the limited key from {@link signUp} as the bearer.
+     */
+    verify(req: VerifyRequest, signal?: AbortSignal): Promise<VerifyResponse>;
+    /** Introspect the principal behind the current key (`GET /v1/auth/me`). */
+    whoami(signal?: AbortSignal): Promise<WhoAmI>;
+    /**
+     * Poll the status of an async job (`GET /v1/jobs/{job_id}`) — currently only
+     * the domain-offboard teardown started by {@link Domains.offboard} enqueues
+     * one. `status` is terminal on succeeded/failed/cancelled; keep polling
+     * otherwise. An unknown or foreign job id is a {@link NotFoundError}.
+     */
+    getJob(jobId: string, signal?: AbortSignal): Promise<Job>;
+    /**
+     * Redeem an enrollment token and return a *new* client already authenticated with the minted
+     * agent key — the natural "redeem then act" flow for an agent.
+     *
+     * ```ts
+     * const bootstrap = new Extrovert({ apiKey: enrollmentToken });
+     * const { client, enrollment } = await bootstrap.enrolled({
+     *   token: enrollmentToken,
+     *   agent_handle: "support-bot",
+     * });
+     * const inbox = await client.inboxes.create();
+     * ```
+     */
+    enrolled(req: EnrollRequest, options?: Pick<ExtrovertClientOptions, "timeoutMs" | "retry" | "fetch" | "defaultHeaders">, signal?: AbortSignal): Promise<{
+        client: ExtrovertClient;
+        enrollment: EnrollResponse;
+    }>;
+    /**
+     * Get an ergonomic handle to an existing inbox by address — without an extra round-trip. Use this
+     * when you already know the address (e.g. from a previous create) and want to send/wait/reply.
+     * Call {@link InboxHandle.refresh} to load the full record.
+     */
+    inbox(address: string): InboxHandle;
+    /**
+     * The headline shortcut: provision a real inbox in one call and get a handle bound to it.
+     * Equivalent to `extrovert.inboxes.create(req)`, named to match the docs/marketing promise.
+     */
+    createInbox(req?: CreateInboxRequest, signal?: AbortSignal): Promise<InboxHandle>;
+    /**
+     * Watch events across EVERY inbox the agent owns (Server-Sent Events, `GET
+     * /v1/events`). Returns an async iterator of {@link StreamEvent}; pass
+     * `lastEventId` (the `seq` of the last event you saw) to resume after a reconnect
+     * and a `signal` to close the stream. To watch a single inbox, use
+     * {@link InboxHandle.stream} instead.
+     *
+     * ```ts
+     * for await (const ev of extrovert.stream()) {
+     *   if (ev.event === "message.received") console.log(ev.inbox, ev.message?.subject);
+     * }
+     * ```
+     */
+    stream(options?: StreamOptions): AsyncGenerator<StreamEvent, void, unknown>;
+    /**
+     * Convenience wrapper over {@link stream}: invoke `onEvent` for every event
+     * across all owned inboxes until the stream closes (or `signal` aborts).
+     */
+    subscribe(onEvent: (event: StreamEvent) => void | Promise<void>, options?: StreamOptions): Promise<void>;
+}
+
+/**
+ * RFC-9457 problem+json errors (redesign §5.1 / §6.2).
+ *
+ * The redesigned surface returns `application/problem+json` with a CLOSED machine
+ * `code` enum clients switch on. The SDK parses it into {@link Problem} and raises a
+ * {@link ProblemError} whose `code` is the typed {@link ProblemCode} union, so callers
+ * branch exhaustively without inspecting raw bodies. The legacy `{ error, message }`
+ * envelope is still parsed by the transport (back-compat); when present it is mapped
+ * onto the closest {@link ProblemCode}.
+ */
+/**
+ * The CLOSED problem code enum (mirrors `components.schemas.Problem.code` in the
+ * frozen OpenAPI). Adding a member is a contract change — keep it in lockstep with
+ * the Go `ProblemCode` enum.
+ */
+type ProblemCode = "bad_request" | "unauthorized" | "forbidden_scope" | "not_found" | "conflict" | "idempotency_conflict" | "breadth_required" | "quota_exceeded" | "rate_limited" | "domain_not_allowed" | "recipient_blocked" | "recipient_suppressed" | "not_configured" | "domain_unavailable" | "internal" | "intent_required" | "wrong_state" | "terminal" | "stale" | "born_stale" | "send_needs_reconciliation" | "graduation_locked" | "maturity_gate_unmet" | "scope_taken" | "unavailable";
+/** The full set of {@link ProblemCode} values (for runtime validation / exhaustive UIs). */
+declare const PROBLEM_CODES: readonly ProblemCode[];
+/**
+ * Which review-loop problem codes are worth retrying, and which are a dead end.
+ *
+ * This table is the whole point of splitting the 409: only a failed
+ * compare-and-set (`stale`) and a redraft built against an older rule high-water
+ * (`born_stale`) describe a situation a retry can fix, and each only a bounded
+ * number of times (re-read, re-apply on top of the other party's change,
+ * resubmit). `wrong_state` means the verb is wrong, not the timing — read the
+ * `allowed_action` hints and pick another one. `terminal` means the review is
+ * finished forever; a `front_run_next` nudge is already waiting on the queue
+ * with the outcome. `send_needs_reconciliation` means a delivery attempt is
+ * unconfirmed — resending is precisely how a message goes out twice.
+ *
+ * `intent_required` is listed false because retrying the SAME bytes fails
+ * identically: the fix is to ADD an `intent` and send a different request. The
+ * server states in its `detail` that nothing was sent and nothing was queued, so
+ * that amended retry is safe.
+ */
+declare const REVIEW_PROBLEM_RETRYABLE: Readonly<Record<string, boolean>>;
+/** One per-field validation detail in a {@link Problem}. */
+interface ProblemField {
+    field?: string;
+    code?: string;
+    detail?: string;
+}
+/** The RFC-9457 problem+json body. */
+interface Problem {
+    /** Dereferenceable URI under `https://extrovert.dev/problems/{code}`. */
+    type: string;
+    /** Short, human-readable summary of the problem type. */
+    title: string;
+    /** HTTP status code, duplicated in the body. */
+    status: number;
+    /** Human-readable, instance-specific detail. */
+    detail?: string;
+    /** The closed machine code clients switch on. */
+    code: ProblemCode;
+    /** Per-request id for support correlation. */
+    request_id?: string;
+    /** Optional machine hints (e.g. `breadth_required` may name the next calls). */
+    errors?: ProblemField[];
+}
+/** True when `value` is a member of the closed {@link ProblemCode} enum. */
+declare function isProblemCode(value: unknown): value is ProblemCode;
+/**
+ * Parse an unknown JSON body into a {@link Problem} when it carries the required
+ * problem+json shape (`code` in the closed enum), else `undefined`. Unknown codes
+ * are coerced to `"internal"` so the typed union holds while the raw value is still
+ * available via {@link ProblemError.rawCode}.
+ */
+declare function parseProblem(body: unknown): {
+    problem: Problem;
+    rawCode: string;
+} | undefined;
+
+/**
+ * Extrovert error types. Every non-2xx response is surfaced as an {@link ApiError} (or a subclass),
+ * so callers can branch on `status` / `code` without inspecting raw responses.
+ *
+ * The redesigned surface returns RFC-9457 `application/problem+json` with a CLOSED
+ * machine {@link ProblemCode} enum. When that body is present, the thrown error
+ * carries the parsed {@link Problem} on `.problem` and a typed `.problemCode`; the
+ * legacy `{ error, message }` envelope is still parsed for back-compat.
+ */
+
+/** The machine-readable error envelope the Extrovert API returns on failures. */
+interface ApiErrorBody {
+    error: {
+        /** Stable, machine-readable code, e.g. `enrollment_token_exhausted`, `not_found`. */
+        code: string;
+        /** Human-readable message safe to surface to developers. */
+        message: string;
+        /** Optional per-field validation detail. */
+        details?: Record<string, unknown>;
+    };
+    /** Request id for support correlation, echoed from the `X-Request-Id` header. */
+    request_id?: string;
+}
+/**
+ * Base error for any failed Extrovert API call. Carries the HTTP `status`, the stable `code`, the
+ * `request_id` for support, and the raw `body` for forward-compatible inspection.
+ */
+declare class ApiError extends Error {
+    /** HTTP status code (e.g. 401, 404, 409, 429). 0 when the request never reached the server. */
+    readonly status: number;
+    /** Stable machine-readable error code from the body, or a synthesized one for transport errors. */
+    readonly code: string;
+    /** Request id for support correlation, when present. */
+    readonly requestId: string | undefined;
+    /** The parsed error body, when the server returned one. */
+    readonly body: ApiErrorBody | undefined;
+    /**
+     * The parsed RFC-9457 problem+json body, when the server returned one. Present on
+     * the redesigned surface; `undefined` for the legacy `{ error }` envelope.
+     */
+    readonly problem: Problem | undefined;
+    /**
+     * The typed closed-enum problem code, when the server returned problem+json. An
+     * unknown/legacy code is coerced to `"internal"`; the raw string is always on
+     * {@link ApiError.code}.
+     */
+    readonly problemCode: ProblemCode | undefined;
+    constructor(args: {
+        status: number;
+        code: string;
+        message: string;
+        requestId?: string | undefined;
+        body?: ApiErrorBody | undefined;
+        problem?: Problem | undefined;
+        cause?: unknown;
+    });
+    /** True for 4xx responses (client errors that retrying won't fix). */
+    get isClientError(): boolean;
+    /** True for 5xx responses (server errors that may succeed on retry). */
+    get isServerError(): boolean;
+}
+/** 401 — the agent key / enrollment token was missing, malformed, expired, or revoked. */
+declare class AuthenticationError extends ApiError {
+}
+/** 403 — authenticated, but the key's scopes don't permit this action (capability denied). */
+declare class PermissionError extends ApiError {
+}
+/**
+ * 403 `forbidden_scope` — the call is outside the key's CEILING (e.g. a non-org key
+ * on the org-wide wildcard, or a mint that would escalate). A redesign-specific
+ * subclass of {@link PermissionError} so existing `instanceof PermissionError`
+ * branches keep working.
+ */
+declare class ForbiddenScopeError extends PermissionError {
+}
+/**
+ * 400 `breadth_required` — an org-tier key/operator issued a bare list that needs a
+ * breadth pick; the problem `errors`/`detail` name the next call
+ * (`/v1/projects/{id}/inboxes` or `/v1/projects/-/inboxes`).
+ */
+declare class BreadthRequiredError extends ApiError {
+}
+/** 404 — the inbox, message, thread, or webhook does not exist (or isn't visible to this tenant). */
+declare class NotFoundError extends ApiError {
+}
+/** 409 — a conflicting state, e.g. an enrollment token that already minted its max of N inboxes. */
+declare class ConflictError extends ApiError {
+}
+/** 422 — the request body failed validation; see `body.error.details`. */
+declare class ValidationError extends ApiError {
+}
+/**
+ * 422 `recipient_suppressed` — a send/reply/forward was rejected because one or
+ * more recipients have opted out (list-unsubscribe / suppression). The whole send
+ * is rejected (never a silent partial drop). {@link suppressedRecipients} lists the
+ * exact addresses to drop; retry the send without them. The scope/origin of the
+ * opt-out is deliberately NOT surfaced. A subclass of {@link ValidationError} so
+ * existing `instanceof ValidationError` branches keep working.
+ */
+declare class RecipientSuppressedError extends ValidationError {
+    /** The recipient addresses that are suppressed — drop these and retry. */
+    readonly suppressedRecipients: string[];
+    constructor(args: ConstructorParameters<typeof ApiError>[0]);
+}
+/**
+ * 422 `intent_required` — the inbox's resolved review policy requires a human to
+ * see this message before it goes out, and the request carried no `intent`.
+ *
+ * **Nothing was sent and nothing was queued.** The server checks this before it
+ * writes any row, which is what makes the amended retry safe: add an `intent`
+ * and re-POST the SAME request. {@link retryWith} is the literal JSON fragment to
+ * splice in, and the human-readable remediation (the full recipe, including how
+ * to monitor the resulting review) is on `.message` / `.problem.detail`.
+ *
+ * Under `require_review` — the default for every account — this is the FIRST
+ * thing most agents hit. Read `effective_review_policy` on
+ * `GET /v1/inboxes/{id}` once at start-up and compose an intent up front instead
+ * of learning the policy by being refused. A subclass of {@link ValidationError}
+ * so existing `instanceof ValidationError` branches keep working.
+ */
+declare class IntentRequiredError extends ValidationError {
+    /** The resolved review policy, e.g. `require_review`. */
+    readonly policy: string | undefined;
+    /** Where the policy came from — a per-inbox override or the account default. */
+    readonly policySource: string | undefined;
+    /** Literal JSON to merge into the original request body, then retry once. */
+    readonly retryWith: string | undefined;
+    constructor(args: ConstructorParameters<typeof ApiError>[0]);
+}
+/**
+ * Base for the review-loop 409s. Carries the live state and CAS keys the server
+ * attached so a retry (where one is legal at all) needs no extra `get_review`,
+ * and the `allowed_action` verbs that ARE legal from the current state so an
+ * agent is told what to do instead of guessing.
+ *
+ * Extends {@link ConflictError}: every one of these used to be a bare 409, and
+ * nothing that catches `ConflictError` should have to change.
+ */
+declare class ReviewConflictError extends ConflictError {
+    /** The review's CURRENT state (`needs_review`, `approved`, `sent`, …). */
+    readonly currentState: string | undefined;
+    /** The current revision — pass it as `parent_revision` on a legal retry. */
+    readonly currentRevision: number | undefined;
+    /** The current row version (the optional belt-and-braces CAS). */
+    readonly currentVersion: number | undefined;
+    /** The verbs that ARE legal from {@link currentState}, e.g. `submit_revision`. */
+    readonly allowedActions: string[];
+    constructor(args: ConstructorParameters<typeof ApiError>[0]);
+    /**
+     * Whether retrying the same call could ever succeed. False for every subclass
+     * except {@link StaleError} and {@link BornStaleError} — and true there only
+     * after re-reading and re-applying on top of the other party's change.
+     */
+    get isRetryable(): boolean;
+}
+/**
+ * 409 `stale` — the `(revision[, version])` you named is no longer current
+ * because a human or reviewer moved the draft. **Nothing was mutated.**
+ *
+ * The one genuinely retryable conflict, and bounded (≤3): re-read the draft and
+ * the feedback, re-apply your edit on top of theirs, resubmit with
+ * {@link ReviewConflictError.currentRevision} as the new `parent_revision`. The
+ * current state/revision/version ride along on the error, so the retry costs no
+ * extra round trip.
+ */
+declare class StaleError extends ReviewConflictError {
+    get isRetryable(): boolean;
+}
+/**
+ * 409 `wrong_state` — this VERB is illegal from the review's current state, but
+ * the draft is still live.
+ *
+ * **Never retry the same verb**; the timing is not the problem, the choice of
+ * call is. Read {@link ReviewConflictError.allowedActions} and pick one of those.
+ */
+declare class WrongStateError extends ReviewConflictError {
+}
+/**
+ * 409 `terminal` — the review has already finished (sent / auto_sent /
+ * cancelled). Nothing will EVER succeed on it.
+ *
+ * **Stop.** A `front_run_next` review event is waiting on the durable queue with
+ * the outcome; drain it, ack it, and compose a NEW message if one is still
+ * wanted. {@link sentMessageId} is the message that actually went out, when the
+ * review reached a delivery.
+ */
+declare class TerminalError extends ReviewConflictError {
+    /** The message that was actually delivered, when this review sent one. */
+    readonly sentMessageId: string | undefined;
+    constructor(args: ConstructorParameters<typeof ApiError>[0]);
+}
+/**
+ * 409 `born_stale` — the redraft was composed against an OLDER writing-rule
+ * high-water than the one now in force. **Nothing was mutated** and the composer
+ * has been re-nudged.
+ *
+ * Retryable at most once per rule high-water: re-read the rules, re-apply them,
+ * resubmit — or `restamp_review` when re-reading shows nothing genuinely needed
+ * to change. Restamping when the body DID need to change makes the draft lie to
+ * the born-stale accounting, so do it only for a true no-op.
+ */
+declare class BornStaleError extends ReviewConflictError {
+    get isRetryable(): boolean;
+}
+/**
+ * 409 `send_needs_reconciliation` — a delivery attempt reached (or may have
+ * reached) the mail provider and the process died before recording the outcome,
+ * so the review is parked for recover-by-Message-ID.
+ *
+ * **Do not resend.** That is exactly how one message goes out twice. Poll the
+ * review (`closed` / `sent_message_id`) until an operator or the recovery path
+ * resolves it.
+ */
+declare class SendNeedsReconciliationError extends ReviewConflictError {
+}
+/**
+ * 409 `idempotency_conflict` — the same `Idempotency-Key` was replayed with a
+ * DIFFERENT request body within the same scope. The replay key is a hash of the
+ * raw bytes, so "same message, different spelling" counts as different.
+ *
+ * A caller bug, not a race: do not retry under that key. Either send the byte-
+ * identical body, or mint a new key for the genuinely new message.
+ */
+declare class IdempotencyConflictError extends ConflictError {
+}
+/**
+ * 503 `unavailable` — a dependency could not be read, so the request was failed
+ * CLOSED rather than served on a guess. On the send path this specifically means
+ * the account's review policy was unreadable: relaying unsupervised mail for a
+ * customer whose stated policy we could not see is the failure that would be
+ * worse than the outage.
+ *
+ * Retryable after {@link retryAfter} seconds. Distinct from `not_configured`,
+ * which means the deployment does not have the capability at all.
+ */
+declare class UnavailableError extends ApiError {
+    /** Seconds to wait before retrying, from the `Retry-After` header. */
+    readonly retryAfter: number | undefined;
+    constructor(args: ConstructorParameters<typeof ApiError>[0] & {
+        retryAfter?: number;
+    });
+}
+/** 402 — payment required (x402 test-mode). `paymentRequired` holds the raw challenge header. */
+declare class PaymentRequiredError extends ApiError {
+    /** The raw `PAYMENT-REQUIRED` header challenge to sign + retry (EIP-3009, Base Sepolia). */
+    readonly paymentRequired: string | undefined;
+    constructor(args: ConstructorParameters<typeof ApiError>[0] & {
+        paymentRequired?: string;
+    });
+}
+/** 429 — rate limited. `retryAfter` is the server's hint in seconds, when provided. */
+declare class RateLimitError extends ApiError {
+    /** Seconds to wait before retrying, parsed from the `Retry-After` header. */
+    readonly retryAfter: number | undefined;
+    constructor(args: ConstructorParameters<typeof ApiError>[0] & {
+        retryAfter?: number;
+    });
+}
+/** The request failed before a response was received (network down, DNS, abort, timeout). */
+declare class ConnectionError extends ApiError {
+    constructor(message: string, cause?: unknown);
+}
+/** The request was aborted by the caller's `AbortSignal` or the client `timeout`. */
+declare class TimeoutError extends ApiError {
+    constructor(message?: string, cause?: unknown);
+}
+
+/**
+ * Narrowing helpers for {@link SendOutcome} — the three shapes a send can answer.
+ *
+ * `inbox.send()` used to be typed as one struct with a REQUIRED `thread_id`, which
+ * the direct-send response has never carried. The type checked; the value was
+ * `undefined`. Now the return type is an honest union, and these helpers exist so
+ * that reading it does not turn into a `"kind" in res` puzzle at every call site.
+ *
+ * The one rule worth internalizing: a `queued_for_review` outcome means **nothing
+ * has been delivered**. A human has to approve it first, and the delivery outcome
+ * arrives later as a `sent` / `send_failed` review event. Code that treats every
+ * 2xx from `send()` as "the mail went out" is wrong under the default
+ * `require_review` policy — which is every account that has not changed it.
+ */
+
+/**
+ * True when the message was PARKED for a human and nothing has been delivered.
+ * Narrow with this before reading `res.review.id`, then monitor the review via
+ * `extrovert.reviewEvents.wait({ review_id })`.
+ */
+declare function isQueuedForReview(res: SendOutcome): res is QueuedForReviewResult;
+/**
+ * True when the message was delivered immediately — either the review-loop
+ * `{kind:"sent"}` body or the legacy body a bare send gets under `allow_direct`.
+ */
+declare function isSentImmediately(res: SendOutcome): res is SendResult | SentResult;
+/**
+ * The delivered message id, or `undefined` when the message was queued instead.
+ *
+ * `undefined` here is NOT an error — it is the normal answer under
+ * `require_review`. Pair it with {@link reviewIdOf} to follow the message to its
+ * outcome.
+ */
+declare function sentMessageIdOf(res: SendOutcome): string | undefined;
+/**
+ * The thread id when one is known.
+ *
+ * Absent on a direct `send` (the server assigns the thread at delivery and the
+ * legacy body does not echo it) and on a queued outcome (there is no message
+ * yet). Reply and forward do return it.
+ */
+declare function threadIdOf(res: SendOutcome): string | undefined;
+/**
+ * The opaque review id (rr_…) that governed this send, on EVERY branch.
+ *
+ * This is the crash-recovery handle: an agent that issued a send and then died
+ * can call `reviews.get(id)` and read `closed` / `send_error` / `sent_message_id`
+ * rather than guessing whether the message went out. It is `undefined` only
+ * against a server old enough to predate the field.
+ */
+declare function reviewIdOf(res: SendOutcome): string | undefined;
+
+/**
+ * Dated API version pin (redesign §5.4).
+ *
+ * The Extrovert API is versioned by a dated `Extrovert-Version` request header. A
+ * request that omits the header is served the latest version; a pinned older
+ * version is transformed to the current shape by a server-side shim. The SDK pins
+ * {@link CURRENT_API_VERSION} on every request by default so an app's behavior is
+ * stable across server deploys; override it per client via
+ * `new Extrovert({ apiVersion: "YYYY-MM-DD" })`.
+ */
+/** The dated API version this SDK was built against. Sent as `Extrovert-Version`. */
+declare const CURRENT_API_VERSION = "2026-06-23";
+/** The HTTP header carrying the dated API version (request + echoed on the response). */
+declare const API_VERSION_HEADER = "Extrovert-Version";
+
+/**
+ * OTP / verification-link extraction.
+ *
+ * Find the most likely one-time code and preferred verification link in a message body. Pure and
+ * dependency-free so it runs in Node, the edge, and the browser.
+ */
+
+/** Extract the most likely OTP code from a body of text, or null. */
+declare function extractOtp(body: string): string | null;
+/** Extract the most likely verification link from a body, or null. */
+declare function extractLink(body: string): string | null;
+/**
+ * Extract OTP + verification link from a message. Prefers the plain-text body; falls back to a
+ * tag-stripped HTML body so codes/links rendered only in HTML are still found.
+ */
+declare function extractCredentials(message: Message): ExtractedCredentials;
+
+/**
+ * Inbound webhook verification.
+ *
+ * Extrovert signs every inbound delivery with an HMAC-SHA256 over `${timestamp}.${rawBody}` and sends
+ * `X-Extrovert-Signature: t=<unix>,v1=<hex>` (§6, §14). Verify with the per-webhook `secret` returned
+ * once at registration. Uses Web Crypto (`crypto.subtle`), so it works in Node 18+, Cloudflare
+ * Workers, Vercel Edge, Deno, and the browser without any dependency.
+ */
+
+/** The decoded body of a `message.received` (and similar) webhook delivery. */
+interface WebhookPayload {
+    event: WebhookEvent;
+    /** Delivery id, unique per attempt. */
+    id: string;
+    created_at: string;
+    /** The message that triggered the event (present for message.* events). */
+    message?: Message;
+    /** The inbox address the event concerns. */
+    inbox?: string;
+}
+interface VerifyWebhookOptions {
+    /** Raw request body, exactly as received (do not re-serialize JSON before verifying). */
+    payload: string;
+    /** The `X-Extrovert-Signature` header value. */
+    signature: string;
+    /** The webhook signing secret (`whsec_...`). */
+    secret: string;
+    /** Reject deliveries whose timestamp is older than this many seconds. Default 300 (5 min). */
+    toleranceSeconds?: number;
+    /** Override the clock (unix seconds) for deterministic testing. */
+    nowSeconds?: number;
+}
+/**
+ * Verify an inbound webhook signature. Returns true when the signature is valid and within the
+ * timestamp tolerance. Throws only if the runtime lacks Web Crypto.
+ *
+ * @example
+ * ```ts
+ * const ok = await verifyWebhookSignature({
+ *   payload: rawBody,
+ *   signature: req.headers["x-extrovert-signature"],
+ *   secret: process.env.EXTROVERT_WEBHOOK_SECRET!,
+ * });
+ * if (!ok) return new Response("bad signature", { status: 400 });
+ * ```
+ */
+declare function verifyWebhookSignature(options: VerifyWebhookOptions): Promise<boolean>;
+/**
+ * Verify a webhook and parse its JSON body in one step. Returns the typed payload on success, or
+ * null when the signature is invalid (so callers can branch without a try/catch on the common path).
+ */
+declare function parseWebhook(options: VerifyWebhookOptions): Promise<WebhookPayload | null>;
+/**
+ * Produce the canonical `X-Extrovert-Signature` header value for a body — the exact format the Go
+ * delivery engine emits: `t=<unix>,v1=<hex hmac-sha256("<t>.<rawbody>")>`. Mainly useful for tests
+ * and self-hosted senders; the platform signs deliveries server-side. The Go `SignWebhook` and this
+ * helper are pinned to the same fixed conformance vector across languages.
+ */
+declare function signWebhook(secret: string, body: string, timestampSeconds: number): Promise<string>;
+
+/**
+ * The Extrovert Review-Loop **open contract** (HITL D14, spec §11).
+ *
+ * This module is the single, documented, *versioned* publication of the stable
+ * agent-facing JSON shapes that the Review Loop exposes — the shapes agents and
+ * third-party harnesses code against. It does **not** redesign any types: it
+ * re-exports the canonical models built across M1–M8 (see `./models`) under one
+ * named contract surface, stamps a {@link CONTRACT_VERSION}, and publishes a
+ * machine-readable {@link CONTRACT_MANIFEST} so a harness can pin the exact set of
+ * shapes + the version it built against.
+ *
+ * ## This is a contract, NOT a protocol (D14)
+ *
+ * Per resolved decision **D14**, the open surface is published **now** as an open,
+ * documented **skill + SDK contract** — explicitly **not** a wire protocol and
+ * **not** a standalone `/v1/contract` endpoint. The contract is exactly: these SDK
+ * types + the agent skills (`extrovert-send-email`, `extrovert-writing-rules`) + the
+ * docs, **versioned with the SDK** (this package). Formal protocol
+ * standardization is deferred (spec §12).
+ *
+ * ## Provisional, pre-1.0 (0.x)
+ *
+ * {@link CONTRACT_VERSION} is **`0.1.0-pre.3`** — a deliberately **provisional**, pre-1.0
+ * contract. It is open and documented, but it MAY still evolve before 1.0: there
+ * are no external users yet, and the **D20 shared-pool auto-send governor** is a
+ * hard prerequisite before onboarding external users. Pin the version; expect
+ * additive 0.x changes. See {@link CONTRACT_MANIFEST}.`stability`.
+ *
+ * ## Identity (D10)
+ *
+ * Every shape keys on **opaque, typed ids** (`rr_`, `turn_`, `cat_`, `rule_`,
+ * `rln_`, `ndg_`, …) and never on names. Names/descriptions are mutable display
+ * metadata; renaming never breaks a reference. $0-LLM on our side — the contract
+ * is pure deterministic JSON; all judgment lives in the agent skills.
+ *
+ * The canonical example payloads for the §11 core shapes (Intent, ReviewFeedback,
+ * DiffJson, Rule, Nudge) are the conformance golden fixtures — see
+ * `golang/internal/extrovertapi/testdata/contract/` and the SDK
+ * `contract.test.ts` (both assert these examples parse/validate without loss).
+ *
+ * @packageDocumentation
+ */
+/** §11 "Intent (submit time)". The agent's for-the-reviewer summary (D3). */
+
+/**
+ * One structured hunk of a `diff_json` (spec §11 "Diff (`diff_json`)"). A single
+ * deterministic field change computed server-side in Go ($0 LLM). `op` is the
+ * change verb; `before`/`after` carry the literal text.
+ */
+interface DiffHunk {
+    /** The Review field this hunk changed (e.g. `subject`, `body_text`). */
+    field: string;
+    /** The change verb (e.g. `replace`, `insert`, `delete`). */
+    op: string;
+    /** The text before the change. */
+    before?: string;
+    /** The text after the change. */
+    after?: string;
+}
+/**
+ * §11 "Diff (`diff_json`)". The structured proposed-vs-sent diff, computed
+ * deterministically in Go ($0 LLM). `fields_changed` names the changed Review
+ * fields; `hunks` carry the per-field before/after.
+ *
+ * This is the named publication of the `diff_json` object that already appears
+ * (as `diff_json`) on `ReviewFeedback` and `ReviewTurn`; those fields keep their
+ * permissive `Record<string, unknown>` wire type for back-compat, and a harness
+ * MAY narrow them to this shape.
+ */
+interface DiffJson {
+    /** The Review fields that changed (e.g. `["subject","body_text"]`). */
+    fields_changed: string[];
+    /** Per-field structured before/after hunks. */
+    hunks: DiffHunk[];
+}
+
+/**
+ * The published version of the Extrovert Review-Loop open contract (D14).
+ *
+ * **`0.1.0-pre.3` — PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
+ * `package.json` version) and aligned to the openapi `info.version`. Open and
+ * documented, but MAY still evolve before 1.0 (no external users yet; the D20
+ * shared-pool governor is required before external users). Pin it.
+ */
+declare const CONTRACT_VERSION: "0.1.0-pre.3";
+/** The stability posture of a published contract version. */
+type ContractStability = "provisional" | "stable";
+/**
+ * The machine-readable manifest of the open contract (D14) — what a harness pins.
+ *
+ * It enumerates the canonical §11 **core** shapes and the **full** M1–M8 surface
+ * by name, stamps {@link CONTRACT_VERSION}, and marks the {@link ContractStability}
+ * posture so a consumer can reason about evolution risk. It carries no runtime
+ * behavior (M9 adds none — types + a version + a test + docs) and no LLM.
+ */
+interface ContractManifest {
+    /** Stable contract name (NOT a protocol name — D14). */
+    readonly name: "extrovert.review-loop";
+    /** The published contract version (== {@link CONTRACT_VERSION}). */
+    readonly version: string;
+    /**
+     * `provisional` (0.x) until the D20 shared-pool governor lands + external users
+     * exist. Provisional ⇒ additive evolution before 1.0 is expected.
+     */
+    readonly stability: ContractStability;
+    /**
+     * D14: this is an SDK + skill contract, versioned WITH the SDK — never a wire
+     * protocol or a standalone protocol endpoint.
+     */
+    readonly kind: "sdk+skill-contract";
+    /** Cross-reference to the spec section that froze these shapes. */
+    readonly spec_ref: "hitl-spec.md#11";
+    /** The five canonical §11 shapes, named verbatim from the spec. */
+    readonly core_shapes: readonly string[];
+    /** The full published M1–M8 agent-facing contract surface (one 0.x contract; no tiering). */
+    readonly shapes: readonly string[];
+    /** The agent skills that are part of the contract (D14 — "skill + SDK"). */
+    readonly skills: readonly string[];
+}
+/**
+ * The published manifest instance. Frozen so a harness can compare it
+ * structurally. The `core_shapes` are the five §11 canonical shapes; `shapes` is
+ * the full provisional-0.x surface. Keep this list in sync with the re-exports
+ * above — the `contract.test.ts` drift test asserts every named shape resolves.
+ */
+declare const CONTRACT_MANIFEST: ContractManifest;
+
+export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainRecord, type DomainScope, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type List, type ListCategoriesParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };