@extrovert.dev/mcp 0.1.0-pre.3

package/dist/tools.js

@@ -0,0 +1,2752 @@
+/**
+ * Extrovert MCP tool definitions (spec §8).
+ *
+ * Each tool is a plain object describing its name, a model-facing description,
+ * a zod `inputSchema` (raw shape), behavioural annotations, and a handler that
+ * calls the typed `ExtrovertClient`. `registerTools` wires them onto an
+ * `McpServer`. Keeping the definitions data-first (rather than imperative
+ * `server.registerTool(...)` calls scattered around) makes the toolset easy to
+ * audit and reuse across the stdio and HTTP transports.
+ *
+ * Auth model (spec §14): the host supplies a SCOPED agent key via env — never
+ * an org-wide master key. `redeem_enrollment` lets an agent exchange a
+ * single-use enrollment token for that scoped key at runtime.
+ */
+import { z } from "zod";
+import { ExtrovertApiError } from "./client.js";
+import { isTerminalReviewEvent } from "./types.js";
+/**
+ * Bind a tool's `Shape` at definition time so registration is fully typed per
+ * tool (no cross-tool union, which would erase the arg types). The returned
+ * object carries a `register` closure the server calls during setup.
+ */
+function defineTool(spec) {
+    return {
+        name: spec.name,
+        register(server, ctx) {
+            server.registerTool(spec.name, {
+                title: spec.title,
+                description: spec.description,
+                inputSchema: spec.inputSchema,
+                annotations: spec.annotations,
+            }, 
+            // The SDK validates `args` against `inputSchema` before invoking us, so
+            // `args` already has the handler's input shape. Typed as the SDK's own
+            // `ToolCallback<Shape>` so the registration overload resolves cleanly.
+            (async (args) => {
+                try {
+                    return await spec.handler(args, ctx);
+                }
+                catch (err) {
+                    return toErrorResult(err);
+                }
+            }));
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Reusable schema fragments
+// ---------------------------------------------------------------------------
+const inboxRef = z
+    .string()
+    .min(1)
+    .describe("Inbox id — the canonical OPAQUE inbox_id (`pmbx_…`; treat it as opaque), or the inbox's " +
+    "full email address as a within-project alias (agent7@smtp.extrovert.dev).");
+const emailAddress = z.string().email().describe("An email address.");
+/**
+ * Optional assertion that the request's project matches the agent key's FIXED
+ * bound project — NEVER a selector. A mismatch is rejected server-side. Project
+ * binding is read from the key (see whoami); this only lets a caller assert it.
+ */
+const projectAssertion = z
+    .string()
+    .min(1)
+    .optional()
+    .describe("Optional project_id ASSERTION — must match the key's fixed bound project (see whoami). " +
+    "This is NOT a project selector; a mismatch is rejected. Omit unless you want the safety check.");
+/** A single metadata value on a create/update patch (number values stay numbers). */
+const metadataValue = z.union([z.string().max(256), z.number(), z.boolean()]);
+/**
+ * Inbox metadata on create: string/number/boolean values; nested objects/arrays
+ * rejected. A key whose value is `null` is DROPPED on create (mirrors the
+ * CreateInboxInput docstring + the SDK InboxMetadataPatch create shape).
+ */
+const createMetadata = z
+    .record(metadataValue.nullable())
+    .describe("Arbitrary key-value metadata to store on the inbox (string/number/boolean values; ≤256 keys, " +
+    "≤256 chars per key/string value; nested objects/arrays rejected; a key with a null value is " +
+    "dropped). Echoed back on the response and replayed on idempotent retries.");
+/**
+ * Inbox metadata patch on update: merge-null-clear semantics — a value SETS a
+ * key, `null` DELETES that key, and a top-level `null` clears ALL metadata.
+ */
+const updateMetadata = z
+    .record(metadataValue.nullable())
+    .nullable()
+    .describe("Patch the inbox's metadata with a shallow merge: an object merges in (a key whose value is null " +
+    "DELETES that key); a top-level null clears ALL metadata; omit the field to leave it unchanged. " +
+    "Values are string/number/boolean; nested objects/arrays rejected; ≤256 keys, ≤256 chars each.");
+/** The agent's "for the human reviewer" intent (Review Loop, spec §11, D3). */
+const reviewIntent = z
+    .object({
+    summary: z.string().describe("Free-text intent summary (who/what/why). Required when mode is review."),
+    meta: z
+        .object({
+        goal: z.string().optional(),
+        recipient: z.string().optional(),
+        prior_touches: z.number().int().optional(),
+        urgency: z.string().optional(),
+    })
+        .optional()
+        .describe("Optional structured intent payload."),
+})
+    .describe("Intent for the human reviewer. Required when the resolved mode is review.");
+const reviewModeEnum = z
+    .enum(["review", "direct"])
+    .describe("Review Loop assertion: 'review' routes into the human-review queue; 'direct' requests an immediate send. " +
+    "The account/inbox review policy may downgrade 'direct' to 'review'.");
+/** The review-request states (spec §3.1), as a const tuple for zod enums. */
+const REVIEW_STATES = [
+    "needs_review",
+    "in_review",
+    "chatting",
+    "stale",
+    "approved",
+    "sent",
+    "auto_sent",
+    "rejected",
+    "stalled",
+    "cancelled",
+    "failed",
+];
+/** One outbound attachment: filename + MIME type + base64 of the file bytes. */
+const attachmentInput = z
+    .object({
+    filename: z.string().min(1).max(255).describe("File name shown to the recipient, e.g. invoice.pdf."),
+    content_type: z
+        .string()
+        .min(1)
+        .max(127)
+        .describe("MIME type, e.g. application/pdf, image/png, text/csv."),
+    content_base64: z.string().min(1).describe("Standard base64 of the raw file bytes."),
+})
+    .describe("A file to attach (base64).");
+// ---------------------------------------------------------------------------
+// Render helpers — compact, human-skimmable text alongside structuredContent
+// ---------------------------------------------------------------------------
+/** Render a mailbox's credentials as a Himalaya `config.toml` account block. */
+function renderHimalayaConfig(c, accountName) {
+    const name = (accountName ?? c.address.split("@")[0] ?? "extrovert").replace(/[^a-zA-Z0-9_-]/g, "-");
+    const enc = (s) => s === "starttls" ? "start-tls" : "tls";
+    const q = (s) => `"${s.replace(/\\/g, "\\\\").replace(/"/g, '\\"')}"`;
+    return [
+        `# Himalaya account for ${c.address} — write to ~/.config/himalaya/config.toml`,
+        `[accounts.${name}]`,
+        `email = ${q(c.address)}`,
+        `default = true`,
+        ``,
+        `backend.type = "imap"`,
+        `backend.host = ${q(c.imap.host)}`,
+        `backend.port = ${c.imap.port}`,
+        `backend.encryption.type = "${enc(c.imap.security)}"`,
+        `backend.login = ${q(c.username)}`,
+        `backend.auth.type = "password"`,
+        `backend.auth.raw = ${q(c.password)}`,
+        ``,
+        `message.send.backend.type = "smtp"`,
+        `message.send.backend.host = ${q(c.smtp.host)}`,
+        `message.send.backend.port = ${c.smtp.port}`,
+        `message.send.backend.encryption.type = "${enc(c.smtp.security)}"`,
+        `message.send.backend.login = ${q(c.username)}`,
+        `message.send.backend.auth.type = "password"`,
+        `message.send.backend.auth.raw = ${q(c.password)}`,
+        ``,
+    ].join("\n");
+}
+function renderInbox(inbox) {
+    const sender = inbox.sender_verified ? "sender verified" : "sender pending";
+    const lines = [
+        `${inbox.address}  [${inbox.status}]`,
+        `id: ${inbox.id} · domain: ${inbox.domain} (${inbox.onboarding_mode}) · ${sender}`,
+    ];
+    // Surface the fixed org/project the inbox lives in (RFC D9) when present.
+    if (inbox.project_id || inbox.org_id) {
+        lines.push(`org: ${inbox.org_id ?? "(none)"} · project: ${inbox.project_id ?? "(none)"}`);
+    }
+    if (inbox.display_name)
+        lines.push(`display name: ${inbox.display_name}`);
+    lines.push(`daily send limit: ${inbox.daily_send_limit} recipients / rolling 24h`);
+    // The policy governs EVERY send from this inbox, so print it: an agent that reads
+    // it here composes an intent up front instead of learning the policy by being
+    // refused mid-task.
+    if (inbox.effective_review_policy) {
+        const note = inbox.effective_review_policy === "allow_direct"
+            ? "sends go out immediately"
+            : "every send needs an `intent`; a send without one is refused (intent_required)";
+        lines.push(`review policy: ${inbox.effective_review_policy} — ${note}`);
+    }
+    if (inbox.webhook_url)
+        lines.push(`webhook: ${inbox.webhook_url}`);
+    const metaKeys = inbox.metadata ? Object.keys(inbox.metadata) : [];
+    if (metaKeys.length) {
+        const pairs = metaKeys.map((k) => `${k}=${String(inbox.metadata[k])}`).join(", ");
+        lines.push(`metadata: ${pairs}`);
+    }
+    return lines.join("\n");
+}
+function renderMessageHeader(m) {
+    const arrow = m.direction === "inbound" ? "<-" : "->";
+    const who = m.direction === "inbound" ? fmtAddr(m.from) : m.to.map(fmtAddr).join(", ");
+    const seen = m.direction === "inbound" ? (m.seen ? "" : " · unread") : "";
+    return `${arrow} ${who} · ${m.subject} · ${m.date}${seen}\n   id: ${m.id} · thread: ${m.thread_id}`;
+}
+function messagePreview(m) {
+    return m.text?.trim() || m.html?.trim() || "(message has no text/plain or text/html body)";
+}
+function renderMessageBody(m, format, variant) {
+    const text = (variant === "source" ? m.text : m.extracted_text)?.trim() || null;
+    const html = (variant === "source" ? m.html : m.extracted_html)?.trim() || null;
+    const textName = variant === "source" ? "text/plain MIME part" : "extracted_text";
+    const htmlName = variant === "source" ? "text/html MIME part" : "extracted_html";
+    if (format === "text")
+        return text ?? `No ${textName} is present. No content was synthesized.`;
+    if (format === "html")
+        return html ?? `No ${htmlName} is present. No content was synthesized.`;
+    if (format === "both") {
+        return [
+            `Text:\n${text ?? `(no ${textName}; not synthesized)`}`,
+            `HTML:\n${html ?? `(no ${htmlName}; not synthesized)`}`,
+        ].join("\n\n");
+    }
+    if (text)
+        return text;
+    if (html)
+        return html;
+    return `No ${variant} text or HTML content is present.`;
+}
+function fmtAddr(a) {
+    return a.name ? `${a.name} <${a.email}>` : a.email;
+}
+function renderThread(t) {
+    return [
+        `${t.subject} (${t.message_count} msg)`,
+        `   id: ${t.id} · last: ${t.last_message_at}`,
+        `   with: ${t.participants.join(", ")}`,
+        `   ${t.snippet}`,
+    ].join("\n");
+}
+function renderSendResult(r) {
+    const review = r.review_id ? ` · review: ${r.review_id}` : "";
+    return `message_id: ${r.message_id || "(queued)"} · thread: ${r.thread_id}${review}`;
+}
+/**
+ * Render the outcome of a BARE send/reply/forward.
+ *
+ * The endpoint has two outcomes and the account's policy — not the caller — picks
+ * between them, so a single "Sent." line would be a lie half the time. A queued
+ * result must SAY it was queued and must surface the `rr_…` id: that id is the
+ * only handle an agent has to resume after a crash, and it is what every
+ * follow-up verb (get_review, submit_revision, the event drain) keys on.
+ */
+function renderSendOutcome(verb, result) {
+    if ("kind" in result) {
+        return [
+            `Queued for human review — NOT sent.`,
+            `review: ${result.review.id} · state: ${result.review.state}${result.review.effective_mode ? ` · effective_mode: ${result.review.effective_mode}` : ""}`,
+            `Next: monitor it with wait_for_review_event / list_review_events until a \`sent\` or \`send_failed\` event arrives.`,
+        ].join("\n");
+    }
+    const review = result.review_id ? `\nreview: ${result.review_id}` : "";
+    if ("status" in result) {
+        return `${verb} (policy allows direct send).\nmessage_id: ${result.message_id}${review}`;
+    }
+    return `${verb} (policy allows direct send).\n${renderSendResult(result)}`;
+}
+/** Render the discriminated outcome of a Review Loop submit (queued OR sent). */
+function renderSubmitResult(r) {
+    if (r.kind === "sent") {
+        const review = r.review?.id ? `\nreview: ${r.review.id}` : "";
+        return `Sent.\nmessage_id: ${r.message.id}${r.message.thread_id ? ` · thread: ${r.message.thread_id}` : ""}${review}`;
+    }
+    return [
+        `Queued for review — NOT sent.`,
+        `review: ${r.review.id} · state: ${r.review.state}${r.review.effective_mode ? ` · effective_mode: ${r.review.effective_mode}` : ""}`,
+        `Next: monitor it with wait_for_review_event / list_review_events until a \`sent\` or \`send_failed\` event arrives.`,
+    ].join("\n");
+}
+/**
+ * Render a summary of a review request for tool output.
+ *
+ * `revision` (and `version`) are printed because submit_revision's own contract is
+ * "parent_revision MUST equal the draft's current revision (from get_review)" —
+ * without them here the documented CAS is literally unperformable from the
+ * rendered text, and a text-only agent has no way to redraft. `closed` /
+ * `send_path` / `send_error` are the poll-side "am I done?" answer for an agent
+ * that lost its event cursor.
+ */
+function renderReview(r) {
+    const subject = r.proposed_subject || "(no subject)";
+    const intent = r.intent_summary ? `\n   intent: ${r.intent_summary}` : "";
+    const cat = r.category_id ? ` · category: ${r.category_id}` : "";
+    const version = r.version !== undefined ? ` · version: ${r.version}` : "";
+    const lines = [
+        `${r.id}  [${r.state}]  ${r.kind} from ${r.from_address}${cat}`,
+        `   revision: ${r.revision}${version}  (pass revision as parent_revision to submit_revision)`,
+        `   subject: ${subject}${intent}`,
+    ];
+    if (r.sent_message_id)
+        lines.push(`   sent message: ${r.sent_message_id}`);
+    if (r.send_path)
+        lines.push(`   send path: ${r.send_path}`);
+    if (r.send_error)
+        lines.push(`   send error: ${r.send_error}`);
+    if (r.closed !== undefined) {
+        lines.push(r.closed
+            ? "   closed: yes — this review is finished; stop polling it."
+            : "   closed: no — still open; keep draining review events.");
+    }
+    return lines.join("\n");
+}
+/** Render a one-line summary of a review thread turn. */
+function renderReviewTurn(t) {
+    const body = t.body ? `: ${t.body.replace(/\s+/g, " ").slice(0, 120)}` : "";
+    return `#${t.seq} ${t.turn_type} (${t.actor_kind})${body}`;
+}
+/**
+ * Render a summary of a category for the registry browse.
+ *
+ * `rules_version` / `rule_high_water` are printed because they are the values an
+ * agent pins into `submit_revision`'s `rules_version_seen` — the born-stale basis.
+ * Omitting them made that argument unfillable from the rendered text, so a
+ * redraft could never truthfully claim what it was composed against.
+ */
+function renderCategory(c) {
+    const desc = c.description ? `\n   ${c.description}` : "";
+    const versions = c.rules_version !== undefined || c.rule_high_water !== undefined
+        ? `\n   rules_version: ${c.rules_version} · rule_high_water: ${c.rule_high_water}` +
+            `  (pass rule_high_water as submit_revision's rules_version_seen)`
+        : "";
+    return `${c.id}  [${c.state}]  ${c.name} (${c.scope})${versions}${desc}`;
+}
+/** Render a one-line summary of a writing rule for the ordered get_rules ladder. */
+function renderRule(r) {
+    const where = r.scope === "general" ? "house-style" : `category ${r.category_id ?? ""}`;
+    const tag = r.scope_agent_id ? " · per-agent" : "";
+    const layer = r.rule_layer ? ` · ${r.rule_layer}-layer` : "";
+    return `${r.id} (rev ${r.rev}) [${r.kind}/${r.author_kind}${tag}${layer}] ${where}\n   ${r.rule_text}`;
+}
+/** Render a one-line summary of a change/undo audit row. */
+function renderRuleAudit(e) {
+    const undone = e.undone ? " (undone)" : "";
+    return `${e.id}  ${e.action} ${e.entity_kind} ${e.entity_id} by ${e.actor_kind}${undone}`;
+}
+function renderWebhook(w) {
+    const scope = w.inbox ? `inbox ${w.inbox}` : "all inboxes";
+    const lines = [
+        `${w.url}  [${w.active ? "active" : "inactive"}]`,
+        `id: ${w.id} · events: ${w.events.join(", ")} · scope: ${scope}`,
+    ];
+    if (w.agent_id)
+        lines.push(`agent: ${w.agent_id}`);
+    if (w.secret)
+        lines.push(`secret (shown once): ${w.secret}`);
+    else
+        lines.push(`secret: ${w.secret_prefix}… (set at registration, not retrievable)`);
+    return lines.join("\n");
+}
+function renderContactListEntry(e) {
+    const scope = e.inbox ? `inbox ${e.inbox}` : "all inboxes (account-wide)";
+    return `${e.kind.toUpperCase()} ${e.pattern}  [${e.direction}]\n   id: ${e.id} · scope: ${scope}`;
+}
+/** Render a one-line summary of a recipient suppression (opt-out) row. */
+function renderSuppression(s) {
+    const status = s.revoked ? "revoked" : "active";
+    const narrow = s.narrow_agent_id || s.narrow_mailbox ? " · narrowed" : "";
+    const lines = [
+        `${s.recipient}  [${status}]`,
+        `   id: ${s.id} · scope: ${s.scope} · source: ${s.source}${narrow} · since ${s.created_at}`,
+    ];
+    if (s.revoked)
+        lines.push(`   revoked ${s.revoked_at ?? ""} by ${s.revoked_by ?? "?"}: ${s.revoke_reason ?? ""}`);
+    return lines.join("\n");
+}
+function renderDomain(d) {
+    const lines = [
+        `${d.domain}  [${d.verification_status}]`,
+        `id: ${d.id} · mode: ${d.mode} · dkim: ${d.dkim_status}${d.shared ? " · shared" : ""}`,
+    ];
+    if (d.provisioning_phase)
+        lines.push(`phase: ${d.provisioning_phase}`);
+    if (d.provisioning_error)
+        lines.push(`error: ${d.provisioning_error}`);
+    const recs = [...(d.delegation_ns ?? []), ...(d.records ?? [])];
+    if (recs.length) {
+        lines.push("DNS records to set:");
+        for (const r of recs) {
+            const prio = r.priority != null ? ` priority ${r.priority}` : "";
+            lines.push(`   ${r.name}  ${r.type}  ${r.value}${prio}  (ttl ${r.ttl})`);
+        }
+    }
+    if (d.instruction)
+        lines.push(d.instruction);
+    return lines.join("\n");
+}
+function renderJob(j) {
+    const lines = [`${j.id}  [${j.status}]`, `type: ${j.type} · created ${j.created_at} · updated ${j.updated_at}`];
+    if (j.finished_at)
+        lines.push(`finished: ${j.finished_at}`);
+    const terminal = j.status === "succeeded" || j.status === "failed" || j.status === "cancelled";
+    lines.push(terminal ? "terminal — no further polling needed." : "not terminal yet — keep polling.");
+    return lines.join("\n");
+}
+function ok(text, structured) {
+    return { content: [{ type: "text", text }], structuredContent: structured };
+}
+// ---------------------------------------------------------------------------
+// Tool definitions
+// ---------------------------------------------------------------------------
+const redeemEnrollment = defineTool({
+    name: "redeem_enrollment",
+    title: "Redeem enrollment key",
+    description: "Exchange a single-use enrollment token (pk_enroll_…) for a SCOPED agent key (pk_agent_…) bound to this agent. " +
+        "Call this first when the host was started without EXTROVERT_API_KEY. The returned agent_key is shown once — store it " +
+        "securely; it carries only the granted scopes (e.g. mailbox:create) and can be revoked independently. Pass a stable agent_handle " +
+        "to make redemption idempotent (re-redeeming returns the same agent).",
+    inputSchema: {
+        enrollment_token: z
+            .string()
+            .min(8)
+            .describe("The enrollment token to redeem, e.g. pk_enroll_42_aZ9…."),
+        agent_handle: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Optional stable handle for idempotent enrollment (à la a client id)."),
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Optional idempotency key. Re-redeeming with the same client_id replays the original enrollment response."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const result = await client.redeemEnrollment({
+            enrollment_token: args.enrollment_token,
+            agent_handle: args.agent_handle,
+            client_id: args.client_id,
+        });
+        const text = [
+            `Enrollment redeemed. Agent ${result.agent_id} is ready.`,
+            `agent_key (shown once): ${result.agent_key}`,
+            // Surface the FIXED org/project the minted key is bound to (enroll now resolves
+            // and returns them), so the agent sees its scope at mint time without a second
+            // whoami call — consistent with whoami's text.
+            `org: ${result.org_id || "(none)"} · project: ${result.project_id || "(none)"} (fixed — bound to this key)`,
+            `scopes: ${result.scopes.join(", ") || "(none)"}`,
+            "This MCP session will use the returned key. Store the complete returned agent_key as EXTROVERT_API_KEY for future sessions; it is not retrievable again.",
+        ].join("\n");
+        return ok(text, result);
+    },
+});
+const signUp = defineTool({
+    name: "sign_up",
+    title: "Sign up for a free account",
+    description: "Grab a free Extrovert account in one call (no enrollment token needed). Provisions a tenant and a first inbox, then " +
+        "emails a one-time verification code to your human_email. Returns a LIMITED (read-only) agent key that this " +
+        "MCP session keeps for verify_signup; store it as EXTROVERT_API_KEY for future sessions. Re-calling with the same " +
+        "human_email rotates the key and resends the code.",
+    inputSchema: {
+        human_email: emailAddress.describe("Your email — receives the one-time verification code."),
+        username: z
+            .string()
+            .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/i, "local-part of an email address")
+            .max(64)
+            .optional()
+            .describe("Desired local-part for the first inbox (optional)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.signUp({ human_email: args.human_email, username: args.username });
+        const text = [
+            `Account created. A verification code was sent to ${res.otp_sent_to}.`,
+            `inbox: ${res.address}`,
+            `agent_key (limited, shown once): ${res.agent_key}`,
+            `scopes: ${res.scopes.join(", ")}`,
+            `This MCP session will use the limited key. Call verify_signup with the code to unlock full scopes; store the key as EXTROVERT_API_KEY for future sessions if needed.`,
+        ].join("\n");
+        return ok(text, res);
+    },
+});
+const verifySignup = defineTool({
+    name: "verify_signup",
+    title: "Verify signup code",
+    description: "Confirm the one-time code emailed by sign_up. On success you receive a NEW full-scope agent key (create/read/send) — " +
+        "this MCP session switches to it automatically. Store it as EXTROVERT_API_KEY for future sessions.",
+    inputSchema: {
+        otp: z.string().min(4).max(12).describe("The verification code from your signup email."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.verify({ otp: args.otp });
+        const text = [
+            `Verified. ${res.message}`,
+            `agent_key (full, shown once): ${res.agent_key}`,
+            `scopes: ${res.scopes.join(", ")}`,
+        ].join("\n");
+        return ok(text, res);
+    },
+});
+const whoami = defineTool({
+    name: "whoami",
+    title: "Who am I",
+    description: "Introspect the principal behind the current agent key: the tenant (customer), the FIXED org and project the key " +
+        "is bound to, the agent, key id, and granted scopes. The org/project are stamped on the key when it is issued and " +
+        "cannot be changed at runtime — there is no project selector; this is the canonical place to read which project " +
+        "this key acts in. Use it to check what the active key can do before attempting a scoped action.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (_args, { client }) => {
+        const me = await client.whoami();
+        const text = [
+            `agent: ${me.agent_id} · customer: ${me.customer_id} · key: ${me.key_id}`,
+            `org: ${me.org_id || "(none)"} · project: ${me.project_id || "(none)"} (fixed — bound to this key)`,
+            `scopes: ${me.scopes.join(", ") || "(none)"}`,
+        ].join("\n");
+        return ok(text, me);
+    },
+});
+const createInbox = defineTool({
+    name: "create_inbox",
+    title: "Create inbox",
+    description: "Provision a real, persistent inbox for this agent in one call. Omit username/domain to mint an instant address on a " +
+        "pre-warmed, verified shared smtp.extrovert.dev subdomain (default, zero-config). Sender registration is always included " +
+        "— the inbox can send and receive immediately. Attach arbitrary metadata (string/number/boolean values) to tag the " +
+        "inbox; it is echoed back and replayed on idempotent retries. The inbox is created in the key's fixed project. " +
+        "Returns the address and inbox id.",
+    inputSchema: {
+        username: z
+            .string()
+            .regex(/^[a-z0-9](?:[a-z0-9._-]*[a-z0-9])?$/i, "local-part of an email address")
+            .max(64)
+            .optional()
+            .describe("Desired local-part (before the @). Omit for an auto-generated handle."),
+        domain: z
+            .string()
+            .optional()
+            .describe("Domain to mint on (must be an org domain). Omit for the default shared subdomain."),
+        display_name: z.string().max(128).optional().describe("Display name on outbound mail."),
+        inbound_webhook_url: z
+            .string()
+            .url()
+            .optional()
+            .describe("HTTPS URL to receive HMAC-signed message.received webhooks."),
+        metadata: createMetadata.optional(),
+        project_id: projectAssertion,
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Optional idempotency key. Re-calling with the same client_id returns the existing inbox instead of creating a duplicate."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const inbox = await client.createInbox({
+            username: args.username,
+            domain: args.domain,
+            display_name: args.display_name,
+            inbound_webhook_url: args.inbound_webhook_url,
+            metadata: args.metadata,
+            project_id: args.project_id,
+            client_id: args.client_id,
+        });
+        return ok(`Inbox live.\n${renderInbox(inbox)}`, inbox);
+    },
+});
+const listInboxes = defineTool({
+    name: "list_inboxes",
+    title: "List inboxes",
+    description: "List the inboxes this agent owns, newest first. Scope is in the KEY: a project " +
+        "(default) key lists its project's inboxes with no extra args. An ORG-tier key " +
+        "must pick a breadth — pass `project` (a concrete project id) or `wildcard:true` " +
+        "(the whole org subtree); a bare org-key list is rejected (breadth_required).",
+    inputSchema: {
+        limit: z.number().int().min(1).max(100).default(20).describe("Max inboxes to return."),
+        project: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Narrow to a concrete project id (org-tier keys, or a project key for its own project). " +
+            "Omit for a project/inbox key — its project is implicit."),
+        wildcard: z
+            .boolean()
+            .optional()
+            .describe("Org-tier keys only: list inboxes across the WHOLE org subtree (the `/v1/projects/-/inboxes` " +
+            "form). Rows carry org_id + project_id. A non-org key using this is rejected (forbidden_scope)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const page = await client.listInboxes({
+            limit: args.limit,
+            project: args.project,
+            wildcard: args.wildcard,
+        });
+        const text = page.items.length
+            ? page.items.map(renderInbox).join("\n\n")
+            : "No inboxes yet. Create one with create_inbox.";
+        return ok(`${page.items.length} inbox(es).\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+            next_cursor: page.next_cursor,
+        });
+    },
+});
+const getInbox = defineTool({
+    name: "get_inbox",
+    title: "Get inbox",
+    description: "Fetch one inbox by id or address (includes its metadata).",
+    inputSchema: { inbox: inboxRef },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const inbox = await client.getInbox(args.inbox);
+        return ok(renderInbox(inbox), inbox);
+    },
+});
+const updateInbox = defineTool({
+    name: "update_inbox",
+    title: "Update inbox",
+    description: "Update an inbox's settings in place — no delete+recreate. Set display_name to change the 'From' name shown on " +
+        "outbound mail (propagated to the authenticated sender), or inbound_webhook_url to change/clear the inbound webhook. " +
+        "Set daily_send_limit to an integer from 1 through 10,000 to change the effective rolling-24-hour recipient cap; " +
+        "this field requires the opt-in mailbox:quota scope. " +
+        "Patch metadata with a shallow merge: pass an object to merge in (a key whose value is null DELETES that key), pass " +
+        "a top-level null to clear ALL metadata, or omit metadata to leave it unchanged. Returns the updated inbox.",
+    inputSchema: {
+        inbox: inboxRef,
+        display_name: z
+            .string()
+            .max(128)
+            .optional()
+            .describe("New sender display / 'From' name. Empty string falls back to the address local-part."),
+        inbound_webhook_url: z
+            .string()
+            .optional()
+            .describe("Replace the inbound webhook target (empty string clears it). HTTPS URL."),
+        daily_send_limit: z
+            .number()
+            .int()
+            .min(1)
+            .max(10_000)
+            .optional()
+            .describe("Effective recipient cap per rolling 24 hours (1–10,000). Requires mailbox:quota."),
+        metadata: updateMetadata.optional(),
+        project_id: projectAssertion,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const inbox = await client.updateInbox(args.inbox, {
+            display_name: args.display_name,
+            inbound_webhook_url: args.inbound_webhook_url,
+            daily_send_limit: args.daily_send_limit,
+            metadata: args.metadata,
+            project_id: args.project_id,
+        });
+        return ok(`Inbox updated.\n${renderInbox(inbox)}`, inbox);
+    },
+});
+const exportEmailConfig = defineTool({
+    name: "export_email_config",
+    title: "Export email client config",
+    description: "Export an inbox's IMAP/SMTP server settings + login so you can configure a real mail client (e.g. Himalaya). " +
+        "Direct SMTP is an explicit unreviewed delivery path: it bypasses Extrovert approval/review, suppression and " +
+        "contact-list enforcement, List-Unsubscribe injection, and Extrovert billing/accounting. API/MCP sends keep those " +
+        "controls. Returns a ready-to-use config; use format=json for raw connection fields.",
+    inputSchema: {
+        inbox: inboxRef,
+        format: z
+            .enum(["himalaya", "json"])
+            .default("himalaya")
+            .describe("Output format: a Himalaya config.toml account block, or raw JSON connection fields."),
+        account_name: z
+            .string()
+            .max(64)
+            .optional()
+            .describe("Himalaya account name (defaults to the address local-part)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const creds = await client.getCredentials(args.inbox);
+        const warning = "DIRECT SMTP BYPASS: SMTP sends do not pass through Extrovert review, suppression/contact-list checks, " +
+            "List-Unsubscribe injection, or Extrovert billing/accounting. Use MCP/API send tools when those controls matter.";
+        if (args.format === "json") {
+            const warnedCredentials = {
+                ...creds,
+                warning,
+            };
+            return ok(JSON.stringify(warnedCredentials, null, 2), warnedCredentials);
+        }
+        const toml = renderHimalayaConfig(creds, args.account_name);
+        const warnedToml = `# WARNING: ${warning}\n${toml}`;
+        return ok(warnedToml, {
+            format: "himalaya",
+            config: warnedToml,
+            credentials: creds,
+            warning,
+        });
+    },
+});
+const deleteInbox = defineTool({
+    name: "delete_inbox",
+    title: "Delete inbox",
+    description: "Permanently delete an inbox and all of its messages, and tear down its sender identity. Requires mailbox:delete, " +
+        "or mailbox:create for the owning agent as the lifecycle-cleanup fallback. " +
+        "This cannot be undone or recovered.",
+    inputSchema: { inbox: inboxRef },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const result = await client.deleteInbox(args.inbox);
+        return ok(`Deleted inbox ${result.id}.`, result);
+    },
+});
+const sendEmail = defineTool({
+    name: "send_email",
+    title: "Send email",
+    description: "Compose a new email from one of this agent's inboxes and submit it for HUMAN REVIEW — the default path. " +
+        "Starts a new thread. Use reply_email to respond within an existing thread.\n\n" +
+        "ALWAYS pass `intent`. The account's review policy governs EVERY send, and the default policy is " +
+        "`require_review`: a send with no `intent` is REFUSED with 422 intent_required, and nothing is sent OR queued. " +
+        "With an intent you get 202 queued_for_review plus a review id (rr_…) — the message has NOT gone out yet. Then " +
+        "monitor that review with wait_for_review_event / list_review_events until a `sent` or `send_failed` event " +
+        "arrives. After `send_failed`, close the failed row with cancel_review and ack the following `cancelled` event. " +
+        "Read `effective_review_policy` from get_inbox once at the start to know which path you are on; only an " +
+        "account explicitly set to `allow_direct` delivers immediately.\n\n" +
+        "`mode`/`category_id` refine the routing but never bypass it: the policy resolves the mode, so `mode:\"direct\"` " +
+        "under require_review is still queued. `intent.summary` is the first thing the human reviewer reads.\n\n" +
+        "Opt-outs and contact lists are enforced at SUBMIT, before the review is created: if ANY recipient is blocked or " +
+        "has unsubscribed, the whole request is rejected (recipient_blocked 403 / recipient_suppressed 422) and no review " +
+        "is queued for a human to waste time on. The error names the addresses to drop. Use check_suppression first to " +
+        "avoid the round-trip.",
+    inputSchema: {
+        inbox: inboxRef,
+        to: z.array(emailAddress).min(1).describe("One or more recipient addresses."),
+        subject: z.string().max(255).describe("Subject line."),
+        text: z.string().describe("Plain-text body."),
+        html: z.string().optional().describe("Optional HTML body."),
+        cc: z.array(emailAddress).optional().describe("Optional Cc recipients."),
+        bcc: z.array(emailAddress).optional().describe("Optional Bcc recipients."),
+        reply_to: emailAddress.optional().describe("Override the Reply-To header."),
+        headers: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe("Optional custom headers (e.g. List-Unsubscribe); reserved/unsafe names are dropped."),
+        attachments: z
+            .array(attachmentInput)
+            .max(20)
+            .optional()
+            .describe("Optional files to attach (base64); sent as a multipart/mixed message."),
+        mode: reviewModeEnum.optional(),
+        intent: reviewIntent.optional(),
+        category_id: z
+            .string()
+            .optional()
+            .describe("Opaque category id (cat_…) matched from the registry. Never a name."),
+        category_confidence: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Your confidence (0..1) in the category match. Feeds the min_confidence auto-send gate ONLY; " +
+            "the server never scores. Below the threshold (or omitted when one is set) the would-be auto-send " +
+            "routes to needs_review (gate_outcome held:low_confidence)."),
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Stable Idempotency-Key for this exact send intent. Reuse it after a transport timeout."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        // Review Loop overload: any of mode/intent/category_id opts into the richer
+        // discriminated response. It does NOT decide whether a human sees the message —
+        // the policy does that either way; this only shapes what comes back.
+        if (args.mode !== undefined || args.intent !== undefined || args.category_id !== undefined) {
+            const result = await client.submitForReview({
+                inbox: args.inbox,
+                to: args.to,
+                subject: args.subject,
+                text: args.text,
+                html: args.html,
+                cc: args.cc,
+                bcc: args.bcc,
+                reply_to: args.reply_to,
+                headers: args.headers,
+                // Attachments survive submit -> review row -> approval dispatch, so the
+                // human reviews the message WITH its files. Dropping them here would have
+                // shipped a message the reviewer approved with an attachment and the
+                // recipient received without one.
+                attachments: args.attachments,
+                mode: args.mode,
+                intent: args.intent,
+                category_id: args.category_id,
+                category_confidence: args.category_confidence,
+                client_id: args.client_id,
+            });
+            return ok(renderSubmitResult(result), result);
+        }
+        const result = await client.sendEmail({
+            inbox: args.inbox,
+            to: args.to,
+            subject: args.subject,
+            text: args.text,
+            html: args.html,
+            cc: args.cc,
+            bcc: args.bcc,
+            reply_to: args.reply_to,
+            headers: args.headers,
+            attachments: args.attachments,
+            client_id: args.client_id,
+        });
+        return ok(renderSendOutcome("Sent", result), result);
+    },
+});
+const replyEmail = defineTool({
+    name: "reply_email",
+    title: "Reply to thread",
+    description: "Compose a reply within an existing thread and submit it for HUMAN REVIEW — the default path, exactly like " +
+        "send_email. Select the parent with thread_id (the latest message in that thread) OR message_id (that specific " +
+        "message). Recipients, subject, and In-Reply-To/References are derived server-side — you do NOT pass `to`.\n\n" +
+        "ALWAYS pass `intent`. Under the default `require_review` policy a reply with no intent is REFUSED with 422 " +
+        "intent_required (nothing sent, nothing queued); with one it returns 202 queued_for_review and a review id " +
+        "(rr_…), and the reply has NOT gone out until a `sent` review event arrives. The envelope is resolved at submit, " +
+        "so the human reviews a message with its real subject and recipients.\n\n" +
+        "Opt-outs: a reply to a suppressed recipient is rejected with recipient_suppressed (HTTP 422) at SUBMIT, before a " +
+        "review is queued. Replies get ONE narrow exception: a suppressed recipient is allowed when this reply answers an " +
+        "inbound message FROM them that arrived AFTER their opt-out (a recipient-re-initiated exchange). Nothing else " +
+        "qualifies — send_email and forward_email get no exception at all.",
+    inputSchema: {
+        inbox: inboxRef,
+        thread_id: z.string().min(1).optional().describe("Thread to reply within (thr_…). One of thread_id / message_id."),
+        message_id: z.string().min(1).optional().describe("Specific message to reply to (msg_…). One of thread_id / message_id."),
+        text: z.string().optional().describe("Plain-text reply body."),
+        html: z.string().optional().describe("Optional HTML reply body."),
+        cc: z.array(emailAddress).optional().describe("Optional Cc recipients."),
+        bcc: z.array(emailAddress).optional().describe("Optional Bcc recipients."),
+        reply_to: emailAddress.optional().describe("Override the Reply-To header."),
+        headers: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe("Optional custom headers (e.g. List-Unsubscribe); reserved/unsafe names are dropped."),
+        reply_all: z.boolean().default(false).describe("Reply to all thread recipients, not just the original sender."),
+        attachments: z
+            .array(attachmentInput)
+            .max(20)
+            .optional()
+            .describe("Optional files to attach (base64); sent as a multipart/mixed message."),
+        mode: reviewModeEnum.optional(),
+        intent: reviewIntent.optional(),
+        category_id: z
+            .string()
+            .optional()
+            .describe("Opaque category id (cat_…) matched from the registry. Never a name."),
+        category_confidence: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Your confidence (0..1) in the category match. Feeds the min_confidence auto-send gate only."),
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Stable Idempotency-Key for this exact reply intent. Reuse it after a transport timeout."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        if (!args.thread_id && !args.message_id) {
+            throw new ExtrovertApiError("Provide thread_id or message_id to reply.", 400, "invalid_argument");
+        }
+        // Review Loop overload: any of mode/intent/category_id opts into review.
+        if (args.mode !== undefined || args.intent !== undefined || args.category_id !== undefined) {
+            const result = await client.submitReplyForReview({
+                inbox: args.inbox,
+                thread_id: args.thread_id,
+                message_id: args.message_id,
+                text: args.text ?? "",
+                html: args.html,
+                cc: args.cc,
+                bcc: args.bcc,
+                reply_to: args.reply_to,
+                headers: args.headers,
+                reply_all: args.reply_all,
+                attachments: args.attachments,
+                mode: args.mode,
+                intent: args.intent,
+                category_id: args.category_id,
+                category_confidence: args.category_confidence,
+                client_id: args.client_id,
+            });
+            return ok(renderSubmitResult(result), result);
+        }
+        const res = await client.replyEmail({
+            inbox: args.inbox,
+            thread_id: args.thread_id,
+            message_id: args.message_id,
+            text: args.text,
+            html: args.html,
+            cc: args.cc,
+            bcc: args.bcc,
+            reply_to: args.reply_to,
+            headers: args.headers,
+            reply_all: args.reply_all,
+            attachments: args.attachments,
+            client_id: args.client_id,
+        });
+        return ok(renderSendOutcome("Replied", res), res);
+    },
+});
+const forwardEmail = defineTool({
+    name: "forward_email",
+    title: "Forward a message",
+    description: "Forward an existing message (by its opaque id) to new recipients and submit it for HUMAN REVIEW — the default " +
+        "path, exactly like send_email and reply_email. Optionally prepend a plain-text note.\n\n" +
+        "ALWAYS pass `intent`. A forward is an outbound message to arbitrary NEW recipients that quotes an entire " +
+        "received thread, so the review policy binds it just as hard as a send — otherwise it would be the way around " +
+        "review, and a worse one, because it exfiltrates a conversation. Under the default `require_review` policy a " +
+        "forward with no intent is REFUSED with 422 intent_required (nothing sent, nothing queued); with one it returns " +
+        "202 queued_for_review and a review id (rr_…). The subject and quoted body are materialized at SUBMIT, so the " +
+        "human reviews the exact bytes that go out and an approved forward delivers the reviewer's edit.\n\n" +
+        "Opt-outs: a forward to a suppressed recipient is ALWAYS rejected (recipient_suppressed 422). Forward gets NO " +
+        "solicited-response exception — that exception exists only for a reply answering an inbound message from the " +
+        "person who opted out.\n\n" +
+        "A forward is deliberately NOT threaded to its parent (no In-Reply-To): the new recipients were never part of " +
+        "that conversation.",
+    inputSchema: {
+        inbox: inboxRef,
+        message_id: z.string().min(1).describe("Opaque id of the message to forward (msg_…)."),
+        to: z.array(emailAddress).min(1).describe("One or more recipient addresses."),
+        cc: z.array(emailAddress).optional().describe("Optional Cc recipients."),
+        bcc: z.array(emailAddress).optional().describe("Optional Bcc recipients."),
+        text: z.string().optional().describe("Optional note to prepend (plain text)."),
+        html: z
+            .string()
+            .optional()
+            .describe("Accepted for wire compatibility but ignored. Forwards use one plain-text body containing the note and quote."),
+        mode: reviewModeEnum.optional(),
+        intent: reviewIntent.optional(),
+        category_id: z
+            .string()
+            .optional()
+            .describe("Opaque category id (cat_…) matched from the registry. Never a name."),
+        category_confidence: z
+            .number()
+            .min(0)
+            .max(1)
+            .optional()
+            .describe("Your confidence (0..1) in the category match. Feeds the min_confidence auto-send gate only."),
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Stable Idempotency-Key for this exact forward intent. Reuse it after a transport timeout."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        // Same opt-in predicate as send/reply: mode/intent/category_id select the
+        // richer discriminated response; the policy governs the routing regardless.
+        if (args.mode !== undefined || args.intent !== undefined || args.category_id !== undefined) {
+            const result = await client.submitForwardForReview({
+                inbox: args.inbox,
+                message_id: args.message_id,
+                to: args.to,
+                cc: args.cc,
+                bcc: args.bcc,
+                text: args.text,
+                html: args.html,
+                mode: args.mode,
+                intent: args.intent,
+                category_id: args.category_id,
+                category_confidence: args.category_confidence,
+                client_id: args.client_id,
+            });
+            return ok(renderSubmitResult(result), result);
+        }
+        const res = await client.forwardEmail({
+            inbox: args.inbox,
+            message_id: args.message_id,
+            to: args.to,
+            cc: args.cc,
+            bcc: args.bcc,
+            text: args.text,
+            html: args.html,
+            client_id: args.client_id,
+        });
+        return ok(renderSendOutcome("Forwarded", res), res);
+    },
+});
+// --- Review Loop (HITL) reads (spec §5.2) ---
+const listReviews = defineTool({
+    name: "list_reviews",
+    title: "List reviews",
+    description: "List the review requests submitted in this account so a sending agent can monitor its submissions in the human " +
+        "review queue. Filter by `state` (one or more), `category_id`, or `inbox`. Human-authority actions (approve/reject/" +
+        "edit-send) happen in the console, never via tools.",
+    inputSchema: {
+        state: z
+            .union([
+            z.enum(REVIEW_STATES),
+            z.array(z.enum(REVIEW_STATES)),
+        ])
+            .optional()
+            .describe("Filter by one or more review states (e.g. needs_review)."),
+        category_id: z.string().optional().describe("Filter by opaque category id (cat_…)."),
+        inbox: z.string().optional().describe("Filter by composer inbox address."),
+        limit: z.number().int().min(1).max(200).optional().describe("Max reviews to return."),
+        page: z.string().optional().describe("Opaque page cursor from a previous call."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const pageResult = await client.listReviews({
+            state: args.state,
+            category_id: args.category_id,
+            inbox: args.inbox,
+            limit: args.limit,
+            page: args.page,
+        });
+        const text = pageResult.items.length
+            ? pageResult.items.map(renderReview).join("\n\n")
+            : "No reviews match.";
+        return ok(`${pageResult.items.length} review(s).\n\n${text}`, {
+            items: pageResult.items,
+            total: pageResult.total,
+        });
+    },
+});
+const getReview = defineTool({
+    name: "get_review",
+    title: "Get review",
+    description: "Fetch one review request by id (rr_…): its current state, `revision` (pass it as submit_revision's " +
+        "parent_revision), the proposed draft, the intent, the category, and (once sent) the sent body + diff.\n\n" +
+        "This is the DEFINITIVE per-review 'am I done?' answer, and the poll-side companion to the event drain — use it " +
+        "after a crash, when your event cursor is gone. `closed` is true for sent, auto_sent, cancelled AND failed " +
+        "(failed is absorbing: nobody will ever move that row, so waiting on it hangs forever). `send_path` says how it " +
+        "got out; `send_error` says why it did not.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…) from list_reviews or a queued send/reply."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const review = await client.getReview(args.id);
+        return ok(renderReview(review), review);
+    },
+});
+const getReviewTurns = defineTool({
+    name: "get_review_turns",
+    title: "Get review thread turns",
+    description: "Fetch the append-only thread turns for a review (rr_…): the intent, every draft revision, human comments/edits/" +
+        "decisions, captured diffs, and state changes — the full audit + learning trail.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const pageResult = await client.getReviewTurns(args.id);
+        const text = pageResult.items.length
+            ? pageResult.items.map(renderReviewTurn).join("\n")
+            : "No turns yet.";
+        return ok(`${pageResult.items.length} turn(s).\n\n${text}`, {
+            items: pageResult.items,
+            total: pageResult.total,
+        });
+    },
+});
+// --- Review Loop (HITL) per-message CHAT + revision + cancel + feedback (M5) ---
+/** Render the human's assembled review feedback (diff + comments + decision + new rules). */
+function renderReviewFeedback(f) {
+    const lines = [`feedback for ${f.review_id} — decision: ${f.decision}`];
+    if (f.diff_unified)
+        lines.push(`diff:\n${f.diff_unified}`);
+    for (const c of f.comments) {
+        lines.push(`• [${c.actor_kind}] ${c.body.replace(/\s+/g, " ").slice(0, 200)}`);
+    }
+    if (f.new_rules.length)
+        lines.push(`rules born from this review: ${f.new_rules.join(", ")}`);
+    return lines.join("\n");
+}
+/** Render the reviewer's decision context (intent + draft + breaker budget). */
+function renderDecisionContext(dc) {
+    const lines = [renderReview(dc.review)];
+    lines.push(`   breakers: hops ${dc.hop_count}/${dc.max_hops}${dc.hops_exhausted ? " (EXHAUSTED)" : ""}` +
+        ` · deadline ${dc.review_deadline}${dc.deadline_passed ? " (PASSED)" : ""}`);
+    if (dc.force_to_human) {
+        lines.push(`   ⚠ a reject will be FORCED to the human (${dc.force_reason}) — the human is the only terminal authority.`);
+    }
+    if (dc.turns.length) {
+        lines.push("   thread:");
+        for (const t of dc.turns.slice(-6))
+            lines.push(`     ${renderReviewTurn(t)}`);
+    }
+    return lines.join("\n");
+}
+/** Render a reviewer-decision outcome. */
+function renderReviewerDecision(res) {
+    if (res.sent) {
+        return `Sent via the composer's creds (reviewer_approved).\n${renderReview(res.review)}${res.message_id ? `\n   message: ${res.message_id}` : ""}`;
+    }
+    const forced = res.forced_by_breaker ? ` (FORCED by ${res.forced_by_breaker})` : "";
+    return `Returned to the human queue${forced}.\n${renderReview(res.review)}`;
+}
+const getReviewDecisionContext = defineTool({
+    name: "get_review_decision_context",
+    title: "Get a review's decision context (reviewer)",
+    description: "REVIEWER PLANE (review:act): fetch your read-only decision surface for a review (rr_…) you're linked to — the intent + " +
+        "current draft + the append-only thread + the TWO circuit-breaker budgets (hop_count vs max_hops, and the hard " +
+        "review_deadline). force_to_human=true means a reject would be FORCED to the human regardless of your intent (the human " +
+        "is the only terminal authority, D17). You can only see reviews your active review-link covers (per-inbox beats " +
+        "account-wide); review:act alone is not enough. Read this, then reviewer_decide. $0 LLM — pure assembly on our side.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…) you are the linked reviewer for."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const dc = await client.getReviewDecisionContext(args.id);
+        return ok(renderDecisionContext(dc), dc);
+    },
+});
+const reviewerDecide = defineTool({
+    name: "reviewer_decide",
+    title: "Decide a review as the linked reviewer",
+    description: "REVIEWER PLANE (review:act): submit your decision on a review (rr_…) you're linked to. action=approve|edit|reject|" +
+        "escalate. approve/edit → the PLATFORM sends with the COMPOSER's credentials (you NEVER hold mailbox:send on an inbox " +
+        "you don't own — the credential boundary); edit also supplies a new subject/body. reject → back to the composer to " +
+        "redraft (hop_count++). escalate → straight to the human queue. revision is the CAS — it MUST equal the draft's current " +
+        "revision (from get_review_decision_context): a mismatch is a 409 STALE with NO change (re-read, re-decide; 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 your intent — the result's forced_by_breaker names it. $0 LLM — YOU judge; we route, send, and " +
+        "enforce the breakers.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…)."),
+        action: z.enum(["approve", "edit", "reject", "escalate"]).describe("approve | edit | reject | escalate."),
+        revision: z.number().int().min(0).describe("The revision you decided against (PRIMARY CAS; 409 STALE on mismatch)."),
+        version: z.number().int().optional().describe("Optional row-version CAS (defense in depth)."),
+        subject: z.string().optional().describe("Edited subject (edit action)."),
+        body: z.string().optional().describe("Edited body text (edit action)."),
+        feedback: z.string().optional().describe("Your note (reject: the rule-birth signal; escalate: the human-facing reason)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.reviewerDecide({
+            id: args.id,
+            action: args.action,
+            revision: args.revision,
+            version: args.version,
+            subject: args.subject,
+            body: args.body,
+            feedback: args.feedback,
+        });
+        return ok(renderReviewerDecision(res), res);
+    },
+});
+const postReviewChat = defineTool({
+    name: "post_review_chat",
+    title: "Post a chat turn on a review",
+    description: "Ask the human reviewer a clarifying question on a review's thread (rr_…) — append an agent_question turn.\n\n" +
+        "LEGAL FROM: needs_review, in_review, chatting. A question on a needs_review draft does NOT open it: the draft " +
+        "stays in the human queue, no reviewer is assigned, and no nudge is sent. Only an in_review draft flips to " +
+        "chatting. (A HUMAN comment on a needs_review draft DOES open it — that asymmetry is deliberate: an agent must " +
+        "not be able to pull a draft out of the queue by asking a question.)\n\n" +
+        "The human sees your question on the console stream and replies with a comment (read it via get_review_turns / " +
+        "get_review_feedback). Idempotent on client_id (the Idempotency-Key). Use this when you are UNSURE what the human " +
+        "wants; otherwise just submit_revision a redraft. $0 LLM — YOU compose the question.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…)."),
+        text: z.string().min(1).describe("Your question/comment for the human reviewer."),
+        client_id: z.string().optional().describe("Idempotency key (Idempotency-Key); a retry with the same key never doubles the turn."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const review = await client.postReviewChat({ id: args.id, text: args.text, client_id: args.client_id });
+        return ok(`Posted.\n${renderReview(review)}`, review);
+    },
+});
+const submitRevision = defineTool({
+    name: "submit_revision",
+    title: "Submit a redrafted revision",
+    description: "Post a NEW draft for a review (rr_…) under a parent_revision CAS — the way to redraft after feedback, a chat " +
+        "answer, or a rule_changed / recheck_category nudge. `parent_revision` MUST equal the draft's current `revision`, " +
+        "which get_review prints.\n\n" +
+        "LEGAL FROM: needs_review, in_review, chatting, rejected. needs_review IS legal — a reviewer reject, a born-stale " +
+        "rule change and a recheck_category nudge all hand the draft back to you sitting in needs_review, and redrafting " +
+        "it is exactly what you are being asked to do. On success the draft is re-rendered in place (revision++), stays/" +
+        "returns to needs_review, and the reviewer is nudged.\n\n" +
+        "The three 409s are DIFFERENT errors — read `code`, not just the status:\n" +
+        "  • `stale` — your (revision, version) is no longer current and NOTHING was mutated. RETRY, bounded (≤3): " +
+        "re-read get_review + get_review_feedback, re-apply your edit on top of theirs, resubmit with the new " +
+        "parent_revision. The human always wins (D17).\n" +
+        "  • `wrong_state` — this verb is illegal from the current state but the draft is still live. NEVER retry it; " +
+        "read the allowed_action hints in the error and pick a legal verb.\n" +
+        "  • `terminal` — the review is sent/auto_sent/cancelled. STOP. Nothing will ever succeed, and a `front_run_next` " +
+        "event is waiting in your drain.\n\n" +
+        "Pin `rules_version_seen` to the category's rule_high_water (get_category prints it). $0 LLM — YOU compose the " +
+        "redraft.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…)."),
+        parent_revision: z
+            .number()
+            .int()
+            .min(0)
+            .describe("The revision you composed against, from get_review's `revision` (PRIMARY CAS; 409 `stale` on mismatch)."),
+        version: z.number().int().optional().describe("Optional row-version CAS (defense in depth)."),
+        subject: z.string().optional().describe("New subject."),
+        text: z.string().optional().describe("New body text (canonical — matches send/reply/forward's `text`)."),
+        body: z
+            .string()
+            .optional()
+            .describe("DEPRECATED alias for `text`, still accepted. Sending both with different content is rejected."),
+        html: z.string().optional().describe("New HTML body."),
+        attachments: z
+            .array(attachmentInput)
+            .max(20)
+            .optional()
+            .describe("REPLACES the draft's attachments. Omit to leave them untouched; pass [] to clear them. Without this a " +
+            "redraft could never restore a file the human reviewed the message with."),
+        built_at: z.string().optional().describe("When you built this draft (informational)."),
+        rules_version_seen: z.number().int().optional().describe("Rule high-water this draft was composed against (born-stale basis)."),
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Stable Idempotency-Key for this exact revision. Reuse it after a transport timeout."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const review = await client.submitRevision({
+            id: args.id,
+            parent_revision: args.parent_revision,
+            version: args.version,
+            subject: args.subject,
+            text: args.text,
+            body: args.body,
+            html: args.html,
+            attachments: args.attachments,
+            built_at: args.built_at,
+            rules_version_seen: args.rules_version_seen,
+            client_id: args.client_id,
+        });
+        return ok(`Revised.\n${renderReview(review)}`, review);
+    },
+});
+const cancelReview = defineTool({
+    name: "cancel_review",
+    title: "Withdraw a pending review",
+    description: "Withdraw your own pending review (rr_…) to the terminal cancelled state — you decided not to send it after all. " +
+        "Only the composing agent may cancel its own review. It is also the ONLY legal close-out for a `failed` review: " +
+        "after a send_failed event the row cannot be retried by anyone, so cancel it and compose a NEW message.\n\n" +
+        "An already-terminal (sent/auto_sent/cancelled) review answers 409 `terminal` — STOP, do not retry. An `approved` " +
+        "review answers 409 `wrong_state`: it is mid-delivery, so wait for the `sent` or `send_failed` event instead.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…)."),
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Stable Idempotency-Key for this cancellation. Reuse it after a transport timeout."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const review = await client.cancelReview({ id: args.id, client_id: args.client_id });
+        return ok(`Cancelled.\n${renderReview(review)}`, review);
+    },
+});
+const restampReview = defineTool({
+    name: "restamp_review",
+    title: "Re-stamp a draft's rules-version without redrafting ($0)",
+    description: "The $0 escape valve when a rule_changed/recheck nudge fires AND the draft genuinely already complies (D19/§8). " +
+        "Use it ONLY for 'I read the new rules and no change is needed'. If the draft DOES need to change, use " +
+        "submit_revision — re-stamping a draft that should have been redrafted makes you lie to the born-stale " +
+        "accounting, and the reconciliation sweep will then RELEASE a pre-rule draft to a human as if it were current. " +
+        "Instead of an " +
+        "expensive redraft, assert 'I reviewed this against rules vX and no change is needed' — the server advances the draft's " +
+        "composed_* rules-versions to vX WITHOUT a new draft (no revision bump, no body change, no nudge). A born-stale draft " +
+        "re-stamped to the CURRENT version becomes current-enough and is releasable on the next reconciliation sweep. " +
+        "against_version must NOT exceed the category's current rules-version (you can't claim a version that doesn't exist). " +
+        "Use submit_revision instead when the draft DOES need to change. $0 LLM — you judged.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…)."),
+        against_version: z
+            .number()
+            .int()
+            .min(0)
+            .describe("The category rules-version you reviewed against (≤ the category's current rules-version)."),
+        house_style_version: z
+            .number()
+            .int()
+            .optional()
+            .describe("Optional: re-stamp the house-style axis to this version (≤ the org's current house_style_version)."),
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Stable Idempotency-Key for this exact re-stamp. Reuse it after a transport timeout."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const review = await client.restampReview({
+            id: args.id,
+            against_version: args.against_version,
+            house_style_version: args.house_style_version,
+            client_id: args.client_id,
+        });
+        return ok(`Re-stamped (no redraft).\n${renderReview(review)}`, review);
+    },
+});
+const getReviewFeedback = defineTool({
+    name: "get_review_feedback",
+    title: "Get the human's feedback on a review",
+    description: "Fetch the human's assembled feedback for a review (rr_…): the unified + structured diff of the human's edit, the human " +
+        "comments / rejection feedback, the decision (edited|approved|rejected|…), and the rules already born from this review. " +
+        "Read this after a rejected/edited nudge to learn what the human wanted, then judge whether a generalizable rule exists " +
+        "(save_rule) and/or submit_revision a redraft. $0 LLM — pure assembly on our side.",
+    inputSchema: {
+        id: z.string().min(1).describe("Review id (rr_…)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const fb = await client.getReviewFeedback(args.id);
+        return ok(renderReviewFeedback(fb), fb);
+    },
+});
+// --- Category registry (Review Loop, D9/D10) — browse / propose / curate -----
+const CATEGORY_SCOPES = ["org_shared", "agent_private"];
+const listCategories = defineTool({
+    name: "list_categories",
+    title: "Browse the category registry",
+    description: "Browse the categories in this account (id + name + description + scope + state) so you can MATCH an existing " +
+        "category before composing a new one — like a skills registry. The optional `match` is a pure lexical/substring " +
+        "filter (every word must appear in the name+description); it does NO semantic matching — YOU read the descriptions " +
+        "and pick the best fit. Categories are shared across the account's agents. Use the returned cat_ id (never the " +
+        "name) as category_id on send/reply.",
+    inputSchema: {
+        match: z.string().optional().describe("Lexical substring filter over name+description (every word must match)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const pageResult = await client.listCategories(args.match);
+        const text = pageResult.items.length
+            ? pageResult.items.map(renderCategory).join("\n\n")
+            : "No categories match. Propose one with propose_category if none fits.";
+        return ok(`${pageResult.items.length} categor${pageResult.items.length === 1 ? "y" : "ies"}.\n\n${text}`, {
+            items: pageResult.items,
+            total: pageResult.total,
+        });
+    },
+});
+const getCategory = defineTool({
+    name: "get_category",
+    title: "Get category",
+    description: "Fetch one category by id (cat_…): its name, description, scope, and graduation state.",
+    inputSchema: {
+        id: z.string().min(1).describe("Category id (cat_…) from list_categories."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const cat = await client.getCategory(args.id);
+        return ok(renderCategory(cat), cat);
+    },
+});
+const proposeCategory = defineTool({
+    name: "propose_category",
+    title: "Propose a category",
+    description: "Propose a NEW category with a name + a skill-style description (D9). It stands immediately and is shared across " +
+        "the account's agents. ONLY propose after browsing the registry with list_categories and finding no good match — " +
+        "duplicates fragment the rules. Returns the cat_ id to use as category_id on send/reply.",
+    inputSchema: {
+        name: z.string().min(1).describe("Display name (mutable; never used as a reference key)."),
+        description: z.string().optional().describe("Skill-style matcher text describing when this category applies."),
+        scope: z.enum(CATEGORY_SCOPES).optional().describe("org_shared (default) or agent_private."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const cat = await client.proposeCategory({ name: args.name, description: args.description, scope: args.scope });
+        return ok(`Proposed.\n${renderCategory(cat)}`, cat);
+    },
+});
+const updateCategory = defineTool({
+    name: "update_category",
+    title: "Rename / re-describe a category",
+    description: "Update a category's name and/or description — metadata ONLY (D10). Renaming never breaks a reference because " +
+        "nothing keys on the name. Any agent in the account may edit; a rename/redescribe entry is written to the audit log. " +
+        "Merging or deleting a category is a human (console) action, never a tool.",
+    inputSchema: {
+        id: z.string().min(1).describe("Category id (cat_…)."),
+        name: z.string().optional().describe("New display name."),
+        description: z.string().optional().describe("New skill-style description."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const cat = await client.updateCategory({ id: args.id, name: args.name, description: args.description });
+        return ok(`Updated.\n${renderCategory(cat)}`, cat);
+    },
+});
+// --- Graduation + risk dial (Review Loop, D16/D6/D17) — agent READ + PROPOSE ----
+/** Render a one-line summary of the graduation gate status. */
+function renderGraduationStatus(st) {
+    const next = st.next_state ? `→ ${st.next_state}` : "(top rung)";
+    const gate = st.next_state === "auto_silent"
+        ? ` · maturity ${st.maturity_gate_met ? "MET" : "unmet"} (approvals ${st.clean_approval_count}/${st.graduate_min_approvals}, age ${st.age_met ? "ok" : "young"})`
+        : "";
+    const lock = st.never_graduate ? " · LOCKED (never_graduate)" : "";
+    return `${st.category_id} [${st.state}] ${next}${gate} · drift ${st.drift_count}/${st.drift_demote_after} · can_graduate=${st.can_graduate}${lock}`;
+}
+const getRiskDial = defineTool({
+    name: "get_risk_dial",
+    title: "Read the effective risk dial",
+    description: "Read the brand-risk dial that governs auto-send: the account-wide default plus every category's per-category " +
+        "overrides (each with its RESOLVED effective value — the override applied over the account default; a null override " +
+        "means the category inherits that value, D12). Fields: min_confidence, first_contact_gate, drift_demote_after (K), " +
+        "canary_rate, graduate_min_approvals + graduate_min_age_hours (the maturity gate), auto_send_cap_per_day (the per-day " +
+        "volume cap). READ-ONLY — you can never flip the dial; setting it is a human (console) action (D16).",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (_args, { client }) => {
+        const dial = await client.getRiskDial();
+        const lines = [
+            `Account default: min_confidence ${dial.account.min_confidence}, canary ${dial.account.canary_rate}, ` +
+                `K ${dial.account.drift_demote_after}, maturity ${dial.account.graduate_min_approvals} approvals / ` +
+                `${dial.account.graduate_min_age_hours}h, cap ${dial.account.auto_send_cap_per_day}/day.`,
+            dial.categories.length
+                ? dial.categories
+                    .map((c) => `• ${c.category_id}: min_confidence ${c.effective.min_confidence}` +
+                    (c.min_confidence === null ? " (inherited)" : " (override)"))
+                    .join("\n")
+                : "No category overrides.",
+        ];
+        return ok(lines.join("\n"), dial);
+    },
+});
+const getGraduationStatus = defineTool({
+    name: "get_graduation_status",
+    title: "Read a category's graduation status",
+    description: "Read whether a category is ready to graduate to the NEXT rung (supervised→auto_notify→auto_silent). Reports the " +
+        "gates passed / still needed: clean approvals (N / needed), category age, the maturity gate (required for auto_silent, " +
+        "D16), the drift counter vs K, and can_graduate (would a human graduate succeed right now). Use this to decide when " +
+        "to propose_graduation — you can never flip the bit yourself (a human confirms; D16/D6).",
+    inputSchema: {
+        id: z.string().min(1).describe("Category id (cat_…)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const st = await client.getGraduationStatus(args.id);
+        return ok(renderGraduationStatus(st), st);
+    },
+});
+const getBacklogStatus = defineTool({
+    name: "get_backlog_status",
+    title: "Read the D19 backlog-reconciliation status",
+    description: "Read the category's backlog reconciliation picture (D19/§8): how many of its QUEUED drafts are STALE (composed under " +
+        "older rules — they need a redraft) vs CURRENT-ENOUGH (within tolerance of the current rules-version) against the " +
+        "current category rules-version + house-style version. A pure $0-LLM integer compare. Read-only — you READ the picture; " +
+        "the human (console scan-backlog) or the graduate/rule-change hooks TRIGGER the actual sweep that releases current-enough " +
+        "drafts and nudges stale ones. Use it to see whether your queued drafts are about to be re-checked.",
+    inputSchema: {
+        id: z.string().min(1).describe("Category id (cat_…)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const st = await client.getBacklogStatus(args.id);
+        const text = `backlog for ${st.category_id} (${st.state}): ${st.queued} queued — ` +
+            `${st.current_enough} current-enough, ${st.stale} stale ` +
+            `(category rules v${st.current_category_rules_version}, house-style v${st.current_house_style_version}, ` +
+            `tolerance ${st.staleness_tolerance})`;
+        return ok(text, st);
+    },
+});
+const getPacingState = defineTool({
+    name: "get_pacing_state",
+    title: "Read the demand-driven pacing state for a category",
+    description: "Read the category's demand-driven pacing snapshot (M7 Slice B/§8): the human review CURSOR position, 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 — one nudge can never fan to 500), the per-agent nudge interval, and each queued draft's " +
+        "classification (behind_cursor | in_window_fresh | in_window_redrafting | ahead). A pure $0-LLM read; the cursor advances " +
+        "from the human's console approve/reject/edit actions. Use it to see which of your drafts are about to surface (and should " +
+        "be redrafted against current rules) vs already passed.",
+    inputSchema: {
+        id: z.string().min(1).describe("Category id (cat_…)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const st = await client.getPacingState(args.id);
+        const text = `pacing for ${st.category_id}: cursor ${st.cursor_review_id ?? "(start)"} ` +
+            `(advanced ${st.cursor_advanced_count}×) — ${st.queued} queued, ${st.in_window} in-window ` +
+            `(${st.redrafting} redrafting), window ${st.lookahead_window}, ceiling ${st.rework_batch_max}, ` +
+            `interval ${st.nudge_min_interval_ms}ms`;
+        return ok(text, st);
+    },
+});
+const proposeGraduation = defineTool({
+    name: "propose_graduation",
+    title: "Propose graduating a category",
+    description: "PROPOSE graduating a category (D16/D6): records your request (with optional evidence) for a human to review and " +
+        "returns the current gate status. It does NOT change the category state — flipping the graduation bit is a human " +
+        "(console) action; an agent can only propose. A never_graduate category stays locked. Check get_graduation_status " +
+        "first so you only propose when the gates are (nearly) met.",
+    inputSchema: {
+        id: z.string().min(1).describe("Category id (cat_…)."),
+        evidence: z
+            .record(z.unknown())
+            .optional()
+            .describe("Optional structured evidence for the human (e.g. {approvals: 20, last_edits: 0})."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const st = await client.proposeGraduation(args.id, args.evidence);
+        return ok(`Requested (a human confirms).\n${renderGraduationStatus(st)}`, st);
+    },
+});
+// --- Writing rules + house-style + precedence ladder + audit/undo (D2/D11) ---
+const RULE_SCOPES = ["general", "category"];
+const RULE_KINDS = ["soft", "hard"];
+const AUDIT_ENTITY_KINDS = ["rule", "category"];
+const getRules = defineTool({
+    name: "get_rules",
+    title: "Get the ordered writing-rule set",
+    description: "Get the ORDERED active writing rules for a compose/redraft. The §7 precedence ladder is applied SERVER-SIDE " +
+        "(deterministic, NO LLM on our side): a project-layer rule outranks the broader org-layer (house-style) rules it " +
+        "inherits; within a layer, hard before soft; specificity per-agent > category > general; human before agent; newest " +
+        "rev; higher priority. Each rule carries its rule_layer (org | project) so you can see where it came from. Returns " +
+        "the general/house-style layer IN ADDITION to the named category's rules (category rules first), capped. YOU reconcile " +
+        "the list semantically and write the draft; we never apply a rule. Pass category_id to include that category's rules; " +
+        "omit it for ONLY the house-style layer.",
+    inputSchema: {
+        category_id: z.string().optional().describe("Category id (cat_…). Empty returns ONLY house-style/general rules."),
+        scope: z.enum(RULE_SCOPES).optional().describe("Narrow to one layer (general | category). Default returns both."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.getRules({ category_id: args.category_id, scope: args.scope });
+        const text = res.items.length ? res.items.map(renderRule).join("\n\n") : "No rules yet.";
+        return ok(`${res.items.length} rule(s), highest precedence first.\n\n${text}`, {
+            items: res.items,
+            total: res.total,
+        });
+    },
+});
+const saveRule = defineTool({
+    name: "save_rule",
+    title: "Save / edit a writing rule",
+    description: "Save a learned writing rule (D11; ANY agent may write shared rules within its project — the audit log + undo is the " +
+        "safety net). scope='general' iff category_id is empty (house-style, applies to ALL categories — D2); else " +
+        "category-scoped. Saves are ALWAYS project-layer: the new rule is bound to this key's fixed project (see whoami) and " +
+        "its rule_layer is 'project'. Org-layer / org-wide house-style rules are console/admin-only in v1 — an agent cannot " +
+        "create them here. With supersedes_id the write is an EDIT (append-only by supersession: a new rev of the same " +
+        "lineage, the prior superseded). Use this AFTER you judge a diff/comment is a generalizable rule (the judgment is " +
+        "yours; we never run an LLM). Returns the new active rule (with its rule_layer/org_id/project_id).",
+    inputSchema: {
+        rule_text: z.string().min(1).describe("The rule body, e.g. 'no em-dashes' or 'be more pushy, we need MRR'."),
+        category_id: z.string().optional().describe("Category id (cat_…). Empty = house-style/general (D2)."),
+        scope: z.enum(RULE_SCOPES).optional().describe("Defaults from category_id (general iff empty)."),
+        kind: z.enum(RULE_KINDS).optional().describe("soft (default) or hard (non-overridable)."),
+        priority: z.number().int().optional().describe("Higher wins the last ladder tiebreak."),
+        source_review_id: z.string().optional().describe("Provenance: the review this rule was learned from (rr_…)."),
+        source_turn_id: z.string().optional().describe("Provenance: the thread turn (turn_…)."),
+        supersedes_id: z.string().optional().describe("Set to EDIT the prior version (rule_…)."),
+        scope_agent_id: z.string().optional().describe("Set for a per-agent override; empty = all org agents."),
+        propagate_to_pending: z
+            .boolean()
+            .optional()
+            .describe("D8 retro-propagation HUMAN OPT-IN (default false). Set ONLY when the human said 'apply to N pending?'. " +
+            "Enqueues a propagate_general_rule nudge to pending siblings of a NEW category rule so you redraft a FEW " +
+            "at a time — never the whole queue."),
+        suggested_batch: z
+            .number()
+            .int()
+            .optional()
+            .describe("Override the propagate batch (0 = base 3, bounded by rework_batch_max). Never fans one nudge to the whole queue."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const rule = await client.saveRule({
+            rule_text: args.rule_text,
+            category_id: args.category_id,
+            scope: args.scope,
+            kind: args.kind,
+            priority: args.priority,
+            source_review_id: args.source_review_id,
+            source_turn_id: args.source_turn_id,
+            supersedes_id: args.supersedes_id,
+            scope_agent_id: args.scope_agent_id,
+            propagate_to_pending: args.propagate_to_pending,
+            suggested_batch: args.suggested_batch,
+        });
+        return ok(`Saved.\n${renderRule(rule)}`, rule);
+    },
+});
+const promoteRule = defineTool({
+    name: "promote_rule",
+    title: "Promote a rule between layers",
+    description: "Move a rule between the category and general/house-style layers (via a supersession). Promote to 'general' to make a " +
+        "category rule apply across ALL categories (house-style); promote to 'category' to scope a general rule down. Never " +
+        "promote to general without a human signal — house-style has account-wide blast radius (D2).",
+    inputSchema: {
+        id: z.string().min(1).describe("Rule id (rule_…)."),
+        to_scope: z.enum(RULE_SCOPES).describe("general (house-style) or category."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const rule = await client.promoteRule(args.id, args.to_scope);
+        return ok(`Promoted.\n${renderRule(rule)}`, rule);
+    },
+});
+const retireRule = defineTool({
+    name: "retire_rule",
+    title: "Retire a rule",
+    description: "Soft-delete a rule (status='retired'); the history survives as training data (there is NO hard delete). Use this to " +
+        "drop a rule that no longer applies — consolidate redundant rules by saving one merged rule and retiring the originals.",
+    inputSchema: {
+        id: z.string().min(1).describe("Rule id (rule_…)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const rule = await client.retireRule(args.id);
+        return ok(`Retired.\n${renderRule(rule)}`, rule);
+    },
+});
+const getRuleAudit = defineTool({
+    name: "get_rule_audit",
+    title: "Read the rule/category change audit log",
+    description: "Read the append-only change/undo audit log spanning rules AND categories (D11) — the safety net for the shared/house-" +
+        "style rule governance. Optionally narrow to one entity. Each row carries a before/after snapshot; undo a change with " +
+        "undo_rule_change.",
+    inputSchema: {
+        entity_kind: z.enum(AUDIT_ENTITY_KINDS).optional().describe("Narrow to one entity kind."),
+        entity_id: z.string().optional().describe("Narrow to one entity (rule_… or cat_…)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.getRuleAudit({ entity_kind: args.entity_kind, entity_id: args.entity_id });
+        const text = res.items.length ? res.items.map(renderRuleAudit).join("\n") : "No audit entries.";
+        return ok(`${res.items.length} audit entr${res.items.length === 1 ? "y" : "ies"}.\n\n${text}`, {
+            items: res.items,
+            total: res.total,
+        });
+    },
+});
+const undoRuleChange = defineTool({
+    name: "undo_rule_change",
+    title: "Undo a rule change",
+    description: "Undo a rule change by its audit-row id (udo_…): restore the prior version as a NEW forward supersession (action=" +
+        "'restore'). Agents may undo too (the audit safety net is in both planes — D11). Idempotent: a re-undo of an already-" +
+        "undone row is a clean 409. Find the udo_ id via get_rule_audit.",
+    inputSchema: {
+        udo_id: z.string().min(1).describe("Audit row id to undo (udo_…)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const rule = await client.undoRuleChange(args.udo_id);
+        return ok(`Undone — restored.\n${renderRule(rule)}`, rule);
+    },
+});
+// --- Review Loop (HITL) realtime — durable nudge drain/ack/wait (spec §5.9) ---
+/**
+ * Render one review event (durable nudge).
+ *
+ * The PAYLOAD is printed, not just the reason. Every reason's guidance lives in
+ * its payload — the delivered `message_id` on `sent`, the scrubbed `error` and
+ * `agent_retryable:false` on `send_failed`, the pacing/rule details on
+ * `rule_changed`, the `current_revision` on `front_run_next`. A reason with no
+ * payload tells a text-only agent that SOMETHING happened and nothing about what
+ * to do, which makes the whole drain loop unactionable.
+ */
+function renderReviewEvent(e) {
+    const scope = e.review_id ? ` · review: ${e.review_id}` : " · broadcast";
+    const terminal = isTerminalReviewEvent(e.reason) ? "  [TERMINAL — this review is done]" : "";
+    const lines = [`• seq ${e.seq} · ${e.reason}${scope} · ${e.id}${terminal}`];
+    const payload = e.payload ?? {};
+    const keys = Object.keys(payload);
+    if (keys.length) {
+        lines.push(`   ${keys.map((k) => `${k}=${formatPayloadValue(payload[k])}`).join(" · ")}`);
+    }
+    return lines.join("\n");
+}
+/** One nudge-payload value, flattened to a single readable line. */
+function formatPayloadValue(v) {
+    if (v === null || v === undefined)
+        return "";
+    if (typeof v === "string")
+        return truncate(v, 200);
+    if (typeof v === "number" || typeof v === "boolean")
+        return String(v);
+    return truncate(JSON.stringify(v), 200);
+}
+const listReviewEvents = defineTool({
+    name: "list_review_events",
+    title: "Drain review events",
+    description: "Non-blocking drain of the next un-acked review nudges for this agent, in FIFO order (strict per review), with " +
+        "the per-review cursors. The durable nudge queue is the authoritative liveness source; webhook/SSE are " +
+        "best-effort fast paths on top of it. Side-effect free: re-calling returns the same frontier until you ack. " +
+        "After acting on an event, call ack_review_event to advance the cursor.\n\n" +
+        "HOW A LOOP TERMINATES: every review that reaches sent / auto_sent / failed / cancelled emits EXACTLY ONE " +
+        "terminal event — `sent`, `send_failed` or `cancelled` — and it is the last and highest-seq event that review " +
+        "will ever produce. Ack it and stop polling that review. `front_run_next` also means stop: you tried to mutate a " +
+        "review somebody already finished.\n\n" +
+        "Non-terminal reasons: `redraft_requested` and `rejected` (redraft via submit_revision), `feedback_added` (a " +
+        "HUMAN commented — answer or redraft), `rule_changed` and `propagate_general_rule` (re-read get_rules, then " +
+        "redraft or restamp_review), `recheck_category` (re-check the category assignment). `staleness` and `approved` " +
+        "are RESERVED and never emitted. Handle any unknown reason by acking and ignoring it — the set grows additively.\n\n" +
+        "Each event's `payload` carries the actionable detail (the delivered message_id, the scrubbed send error, the " +
+        "current revision) and is printed with the event.",
+    inputSchema: {
+        review_id: z.string().optional().describe("Restrict the drain to one review's events (rr_…)."),
+        limit: z.number().int().min(1).max(100).optional().describe("Max events to return."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.listReviewEvents({ review_id: args.review_id, limit: args.limit });
+        const text = res.events.length ? res.events.map(renderReviewEvent).join("\n") : "No review events.";
+        return ok(`${res.events.length} review event(s).\n\n${text}`, {
+            events: res.events,
+            cursors: res.cursors ?? [],
+        });
+    },
+});
+const waitForReviewEvent = defineTool({
+    name: "wait_for_review_event",
+    title: "Wait for a review event",
+    description: "Long-poll (~25–55s) for the next review nudge: blocks until one is available OR the deadline, then returns like " +
+        "list_review_events (empty on timeout — re-call to keep watching). Use this for an always-on agent that wants to " +
+        "react the instant a human approves/edits/rejects; use list_review_events for a heartbeat drain.",
+    inputSchema: {
+        review_id: z.string().optional().describe("Restrict the wait to one review's events (rr_…)."),
+        wait_seconds: z.number().int().min(1).max(55).optional().describe("Long-poll budget in seconds (default ~30)."),
+        limit: z.number().int().min(1).max(100).optional().describe("Max events to return."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.waitForReviewEvent({
+            review_id: args.review_id,
+            wait_seconds: args.wait_seconds,
+            limit: args.limit,
+        });
+        const text = res.events.length ? res.events.map(renderReviewEvent).join("\n") : "No review events (timed out).";
+        return ok(`${res.events.length} review event(s).\n\n${text}`, {
+            events: res.events,
+            cursors: res.cursors ?? [],
+        });
+    },
+});
+const ackReviewEvent = defineTool({
+    name: "ack_review_event",
+    title: "Ack review events",
+    description: "Advance the agent's per-review cursor(s) to the supplied through_seq and/or mark broadcast nudges done. Idempotent " +
+        "and monotonic — re-acking an older seq is a no-op (exactly-once effect). Call this AFTER you have acted on the " +
+        "events from list_review_events / wait_for_review_event so the queue does not keep re-surfacing them.",
+    inputSchema: {
+        acks: z
+            .array(z.object({
+            review_id: z.string().describe("The review (rr_…) whose cursor to advance."),
+            through_seq: z.number().int().min(0).describe("Advance the cursor through this seq (inclusive)."),
+        }))
+            .optional()
+            .describe("Per-review cursor advances."),
+        broadcast_ids: z.array(z.string()).optional().describe("Broadcast nudge ids (ndg_…) to mark done."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.ackReviewEvent({ acks: args.acks, broadcast_ids: args.broadcast_ids });
+        const cursors = res.cursors ?? [];
+        const text = cursors.length
+            ? cursors.map((c) => `• ${c.review_id} → last_acked_seq ${c.last_acked_seq}`).join("\n")
+            : "Acked.";
+        return ok(`Acked review events.\n\n${text}`, { cursors });
+    },
+});
+const readMessages = defineTool({
+    name: "read_messages",
+    title: "Read messages",
+    description: "List messages in an inbox, newest first. Narrow with exact-field filters (from/to/subject substring) or " +
+        "unread_only to focus on what's new (native IMAP read state). Page with limit + offset. Returns headers and bodies.",
+    inputSchema: {
+        inbox: inboxRef,
+        limit: z.number().int().min(1).max(100).default(20).describe("Max messages to return."),
+        offset: z.number().int().min(0).default(0).describe("Number of messages to skip (paging)."),
+        unread_only: z.boolean().default(false).describe("Only return unread messages (\\Seen flag clear)."),
+        from: z.string().optional().describe("Only messages whose sender contains this substring."),
+        to: z.string().optional().describe("Only messages whose recipient contains this substring."),
+        subject: z.string().optional().describe("Only messages whose subject contains this substring."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const page = await client.listMessages({
+            inbox: args.inbox,
+            limit: args.limit,
+            offset: args.offset,
+            unread_only: args.unread_only,
+            from: args.from,
+            to: args.to,
+            subject: args.subject,
+        });
+        const text = page.items.length
+            ? page.items
+                .map((m) => `${renderMessageHeader(m)}\n   ${truncate(messagePreview(m), 160)}`)
+                .join("\n\n")
+            : "No messages.";
+        return ok(`${page.items.length} message(s).\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+        });
+    },
+});
+const getMessage = defineTool({
+    name: "get_message",
+    title: "Get message",
+    description: "Fetch one message by its opaque id (msg_…), as returned by read_messages / search / wait_for_email. The owning " +
+        "inbox is resolved from the id. Structured output carries nullable source text/HTML fields and their nullable " +
+        "best-effort extracted variants; choose the presentation format below.",
+    inputSchema: {
+        id: z.string().min(1).describe("Opaque message id (msg_…)."),
+        format: z
+            .enum(["auto", "text", "html", "both"])
+            .default("auto")
+            .describe("Presentation format. auto returns an actual text/plain part when present, otherwise the actual HTML part. Missing alternatives are never synthesized."),
+        variant: z
+            .enum(["source", "extracted"])
+            .default("source")
+            .describe("source is authoritative MIME content; extracted is a best-effort quote/signature-stripped derivative."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const m = await client.getMessage(args.id);
+        const body = renderMessageBody(m, args.format, args.variant);
+        return ok(`${renderMessageHeader(m)}\n\n${truncate(body, 12_000)}`, m);
+    },
+});
+const listAttachments = defineTool({
+    name: "list_attachments",
+    title: "List attachments",
+    description: "List the attachments on a message: their opaque id, filename, content type, and size. Use the returned id with " +
+        "get_attachment to download the bytes. The inbox owns the message.",
+    inputSchema: {
+        inbox: inboxRef,
+        message_id: z.string().min(1).describe("Opaque message id (msg_…) whose attachments to list."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const page = await client.listAttachments({
+            inbox: args.inbox,
+            message_id: args.message_id,
+        });
+        const text = page.items.length
+            ? page.items
+                .map((a) => `${a.filename} · ${a.content_type} · ${a.size} bytes\n   id: ${a.id}`)
+                .join("\n\n")
+            : "No attachments on this message.";
+        return ok(`${page.items.length} attachment(s).\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+        });
+    },
+});
+const getAttachment = defineTool({
+    name: "get_attachment",
+    title: "Download an attachment",
+    description: "Download one attachment's bytes (returned base64) by its id (from list_attachments), with its filename and content " +
+        "type. This is the easy attachment fetch: list_attachments to find the id, then get_attachment to pull the file. The " +
+        "inbox owns the message.",
+    inputSchema: {
+        inbox: inboxRef,
+        message_id: z.string().min(1).describe("Opaque message id (msg_…) the attachment belongs to."),
+        attachment_id: z.string().min(1).describe("Opaque attachment id (att_…) from list_attachments."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const att = await client.getAttachment({
+            inbox: args.inbox,
+            message_id: args.message_id,
+            attachment_id: args.attachment_id,
+        });
+        const text = [
+            `Downloaded ${att.filename || "attachment"} (${att.content_type}).`,
+            `Bytes are base64 in structuredContent.content_base64.`,
+        ].join("\n");
+        return ok(text, att);
+    },
+});
+const markRead = defineTool({
+    name: "mark_read",
+    title: "Mark message read / unread",
+    description: "Set or clear a message's read state via the native IMAP \\Seen flag (Extrovert's label-free read tracking). Pass " +
+        "read=false to mark unread. The message is resolved from its id; inbox is required to open the right inbox.",
+    inputSchema: {
+        inbox: inboxRef,
+        id: z.string().min(1).describe("Opaque message id (msg_…)."),
+        read: z.boolean().default(true).describe("true to mark read, false to mark unread."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const m = await client.markRead({ inbox: args.inbox, id: args.id, read: args.read });
+        return ok(`Marked ${m.id} as ${m.seen ? "read" : "unread"}.`, m);
+    },
+});
+const listThreads = defineTool({
+    name: "list_threads",
+    title: "List threads",
+    description: "List conversation threads in an inbox, most-recently-active first.",
+    inputSchema: {
+        inbox: inboxRef,
+        limit: z.number().int().min(1).max(100).default(20).describe("Max threads to return."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const page = await client.listThreads({ inbox: args.inbox, limit: args.limit });
+        const text = page.items.length ? page.items.map(renderThread).join("\n\n") : "No threads.";
+        return ok(`${page.items.length} thread(s).\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+        });
+    },
+});
+const getThread = defineTool({
+    name: "get_thread",
+    title: "Get thread",
+    description: "Fetch one conversation thread by its stable id (thr_…), with all its messages oldest-first. Use this to read a full " +
+        "back-and-forth before replying. The inbox owns the thread.",
+    inputSchema: {
+        inbox: inboxRef,
+        thread_id: z.string().min(1).describe("Stable thread id (thr_…) from list_threads or a message."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const thread = await client.getThread({
+            inbox: args.inbox,
+            thread_id: args.thread_id,
+        });
+        const head = renderThread(thread);
+        const body = thread.messages
+            .map((m) => `${renderMessageHeader(m)}\n   ${truncate(messagePreview(m), 200)}`)
+            .join("\n\n");
+        return ok(`${head}\n\n${body}`, thread);
+    },
+});
+const deleteMessage = defineTool({
+    name: "delete_message",
+    title: "Delete a message",
+    description: "Delete one message by its opaque id (msg_…). By default it is moved to the Trash folder (a recoverable soft " +
+        "delete); pass expunge=true to permanently remove it. A message already in Trash is always expunged. The inbox " +
+        "owns the message. Returns {id, deleted, expunged, count}.",
+    inputSchema: {
+        inbox: inboxRef.describe("Owned inbox the message belongs to."),
+        id: z.string().min(1).describe("Opaque message id (msg_…)."),
+        expunge: z.boolean().default(false).describe("true to permanently remove instead of moving to Trash."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const result = await client.deleteMessage({ inbox: args.inbox, id: args.id, expunge: args.expunge });
+        const where = result.expunged ? "permanently deleted" : "moved to Trash";
+        return ok(`Message ${result.id} ${where}.`, result);
+    },
+});
+const deleteThread = defineTool({
+    name: "delete_thread",
+    title: "Delete a thread",
+    description: "Delete an entire conversation thread by its stable id (thr_…) — every message in it (across INBOX and Sent). By " +
+        "default the messages are moved to Trash (recoverable); pass expunge=true to permanently remove them. The inbox " +
+        "owns the thread. Returns {id, deleted, expunged, count} where count is the number of messages removed.",
+    inputSchema: {
+        inbox: inboxRef.describe("Owned inbox the thread belongs to."),
+        thread_id: z.string().min(1).describe("Stable thread id (thr_…) from list_threads or a message."),
+        expunge: z.boolean().default(false).describe("true to permanently remove instead of moving to Trash."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const result = await client.deleteThread({
+            inbox: args.inbox,
+            thread_id: args.thread_id,
+            expunge: args.expunge,
+        });
+        const where = result.expunged ? "permanently deleted" : "moved to Trash";
+        return ok(`Thread ${result.id} ${where} (${result.count} message(s)).`, result);
+    },
+});
+const batchUpdateMessages = defineTool({
+    name: "batch_update_messages",
+    title: "Batch update messages",
+    description: "Mark read/unread and/or move folder for a list of message ids that all belong to one inbox, in a single call. " +
+        "Set read (true=read, false=unread) and/or folder (one of INBOX, Sent, Trash, Junk, Archive) — at least one is " +
+        "required. Ids that are malformed or not owned by the inbox come back in `failed` rather than failing the batch. " +
+        "Returns {updated, failed}.",
+    inputSchema: {
+        inbox: inboxRef.describe("Owned inbox the messages belong to."),
+        ids: z.array(z.string().min(1)).min(1).max(200).describe("Opaque message ids (msg_…), all in this inbox."),
+        read: z.boolean().optional().describe("Set (true) or clear (false) the read flag on each id."),
+        folder: z
+            .enum(["INBOX", "Sent", "Trash", "Junk", "Archive"])
+            .optional()
+            .describe("Move each message to this folder."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        if (args.read === undefined && args.folder === undefined) {
+            throw new ExtrovertApiError("Set read and/or folder to update.", 400, "invalid_argument");
+        }
+        const result = await client.batchUpdateMessages({
+            inbox: args.inbox,
+            ids: args.ids,
+            read: args.read,
+            folder: args.folder,
+        });
+        return ok(`Updated ${result.updated.length} message(s); ${result.failed.length} skipped.`, result);
+    },
+});
+const search = defineTool({
+    name: "search",
+    title: "Search messages",
+    description: "Full-text search across messages (subject, body, sender). Scope to one inbox with `inbox`, or omit to search all of " +
+        "this agent's inboxes.",
+    inputSchema: {
+        query: z.string().min(1).describe("Search terms."),
+        inbox: inboxRef.optional(),
+        limit: z.number().int().min(1).max(100).default(20).describe("Max results."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const page = await client.search({
+            query: args.query,
+            inbox: args.inbox,
+            limit: args.limit,
+        });
+        const text = page.items.length
+            ? page.items.map((m) => `${renderMessageHeader(m)}\n   ${truncate(messagePreview(m), 160)}`).join("\n\n")
+            : "No matches.";
+        return ok(`${page.items.length} match(es) for "${args.query}".\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+        });
+    },
+});
+const waitForEmail = defineTool({
+    name: "wait_for_email",
+    title: "Wait for email (blocking)",
+    description: "Block until the next matching message arrives in an inbox, then return it with any OTP code / verification link " +
+        "already extracted. This is the killer primitive for sign-in and verification flows: trigger the email elsewhere, then " +
+        "call this and act on otp_code / verification_link in the same turn. Narrow the wait with from / subject / regex. " +
+        "Returns matched=false if nothing arrives before timeout — retry or lengthen the timeout if expected.",
+    inputSchema: {
+        inbox: inboxRef,
+        from: z
+            .string()
+            .optional()
+            .describe("Only match senders containing this substring (e.g. 'stripe.com')."),
+        subject: z.string().optional().describe("Only match subjects containing this substring."),
+        regex: z
+            .string()
+            .optional()
+            .describe("Case-sensitive Go RE2 expression over subject or readable body. Prefix with (?i) for case-insensitive matching."),
+        link_hint: z
+            .string()
+            .optional()
+            .describe("Prefer an extracted verification link containing this substring; it does not filter message matches."),
+        since_now: z
+            .boolean()
+            .default(true)
+            .describe("Only match emails that arrive AFTER this call (default). Set false to also match an already-delivered message."),
+        timeout_ms: z
+            .number()
+            .int()
+            .min(1_000)
+            .max(600_000)
+            .default(120_000)
+            .describe("How long to block before giving up, in milliseconds (default 120s)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client, config }) => {
+        const timeout = Math.min(args.timeout_ms, config.maxWaitMs);
+        const result = await client.waitForEmail({
+            inbox: args.inbox,
+            from: args.from,
+            subject: args.subject,
+            regex: args.regex,
+            link_hint: args.link_hint,
+            since_now: args.since_now,
+            timeout_ms: timeout,
+        });
+        if (!result.matched || !result.message) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `No matching email arrived within ${result.waited_ms} ms. Trigger the email and retry, or raise timeout_ms.`,
+                    },
+                ],
+                structuredContent: result,
+            };
+        }
+        const m = result.message;
+        const parts = [
+            `Matched after ${result.waited_ms} ms.`,
+            renderMessageHeader(m),
+            "",
+            truncate(messagePreview(m), 600),
+        ];
+        if (result.otp_code)
+            parts.push("", `OTP code: ${result.otp_code}`);
+        if (result.verification_link)
+            parts.push(`verification link: ${result.verification_link}`);
+        return ok(parts.join("\n"), result);
+    },
+});
+const webhookEventEnum = z
+    .enum(["message.received", "unsubscribe.received"])
+    .describe("A webhook event type delivered by Extrovert. `message.received` fires on inbound mail; " +
+    "`unsubscribe.received` fires when a recipient opts out (one-click List-Unsubscribe or a STOP reply), which is " +
+    "what lets you drop them from your own lists before the next send is refused.");
+const registerWebhook = defineTool({
+    name: "register_webhook",
+    title: "Register inbound webhook",
+    description: "Register an HTTPS endpoint to receive HMAC-signed inbound-message deliveries. Each delivery carries " +
+        "X-Extrovert-Signature: t=<unix>,v1=<hex hmac-sha256 over \"<t>.<rawbody>\"> — verify it with the signing secret " +
+        "returned ONCE here. Scope to one inbox with `inbox`, or omit to cover every inbox this agent owns. Defaults to " +
+        "the message.received event; subscribe to unsubscribe.received as well to hear about opt-outs.",
+    inputSchema: {
+        url: z.string().url().describe("HTTPS endpoint that receives POSTed deliveries."),
+        events: z
+            .array(webhookEventEnum)
+            .min(1)
+            .optional()
+            .describe("Event types to subscribe to. Defaults to [message.received]."),
+        inbox: inboxRef.optional().describe("Scope to one owned inbox. Omit to cover all of this agent's inboxes."),
+        client_id: z
+            .string()
+            .min(1)
+            .max(128)
+            .optional()
+            .describe("Optional idempotency key. Re-registering with the same client_id replays the original webhook instead of creating a duplicate."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const webhook = await client.registerWebhook({
+            url: args.url,
+            events: args.events,
+            inbox: args.inbox,
+            client_id: args.client_id,
+        });
+        return ok(`Webhook registered.\n${renderWebhook(webhook)}`, webhook);
+    },
+});
+const listWebhooks = defineTool({
+    name: "list_webhooks",
+    title: "List webhooks",
+    description: "List this agent's registered inbound webhooks. Signing secrets are redacted (only the prefix is shown).",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (_args, { client }) => {
+        const page = await client.listWebhooks();
+        const text = page.items.length ? page.items.map(renderWebhook).join("\n\n") : "No webhooks registered.";
+        return ok(`${page.items.length} webhook(s).\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+        });
+    },
+});
+const getWebhook = defineTool({
+    name: "get_webhook",
+    title: "Get webhook",
+    description: "Fetch one registered webhook by id (whk_…). The signing secret is redacted.",
+    inputSchema: {
+        id: z.string().min(1).describe("Webhook id (whk_…) from register_webhook / list_webhooks."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const webhook = await client.getWebhook(args.id);
+        return ok(renderWebhook(webhook), webhook);
+    },
+});
+const updateWebhook = defineTool({
+    name: "update_webhook",
+    title: "Update webhook",
+    description: "Update a registered webhook in place by id (whk_…). Change the delivery `url`, the subscribed `events`, the " +
+        "`inbox` filter (empty string clears it so the webhook covers every inbox this agent owns), or `active` to " +
+        "enable/disable delivery without deleting. Omitted fields are left unchanged. The signing secret is immutable and " +
+        "stays redacted. Returns the updated webhook.",
+    inputSchema: {
+        id: z.string().min(1).describe("Webhook id (whk_…) from register_webhook / list_webhooks."),
+        url: z.string().url().optional().describe("Replace the HTTPS delivery endpoint."),
+        events: z
+            .array(webhookEventEnum)
+            .min(1)
+            .optional()
+            .describe("Replace the subscribed event types."),
+        inbox: z
+            .string()
+            .optional()
+            .describe("Replace the inbox filter. Empty string clears it (covers all of this agent's inboxes)."),
+        active: z.boolean().optional().describe("Enable or disable delivery without deleting the webhook."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const webhook = await client.updateWebhook(args.id, {
+            url: args.url,
+            events: args.events,
+            inbox: args.inbox,
+            active: args.active,
+        });
+        return ok(`Webhook updated.\n${renderWebhook(webhook)}`, webhook);
+    },
+});
+const deleteWebhook = defineTool({
+    name: "delete_webhook",
+    title: "Delete webhook",
+    description: "Delete a registered webhook by id (whk_…). Deliveries stop immediately. This cannot be undone.",
+    inputSchema: {
+        id: z.string().min(1).describe("Webhook id (whk_…) to delete."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const result = await client.deleteWebhook(args.id);
+        return ok(`Deleted webhook ${result.id}.`, result);
+    },
+});
+const addContactListEntry = defineTool({
+    name: "add_contact_list_entry",
+    title: "Add a contact allow/block entry",
+    description: "Add an allow or block entry to an inbox's contact lists. A `block` entry rejects a send to a matching " +
+        "recipient; once any `allow` entry exists for an inbox, sends from it are restricted to recipients that match " +
+        "one of them (allowlist mode). `pattern` is a bare email address (matched in full) or a bare domain " +
+        "(matches any address in that domain). Returns the created entry (addressable by its opaque id for delete).",
+    inputSchema: {
+        inbox: inboxRef.describe("Owned inbox to attach the entry to (its sends are governed)."),
+        kind: z.enum(["allow", "block"]).describe("allow = permit; block = reject a matching recipient."),
+        direction: z
+            .enum(["send", "receive"])
+            .optional()
+            .describe("Traffic direction. Defaults to send (only send is enforced today)."),
+        pattern: z.string().min(1).describe("A bare email address (bob@acme.com) or a bare domain (acme.com)."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const entry = await client.addContactListEntry({
+            inbox: args.inbox,
+            kind: args.kind,
+            direction: args.direction,
+            pattern: args.pattern,
+        });
+        return ok(`Contact list entry added.\n${renderContactListEntry(entry)}`, entry);
+    },
+});
+const listContactListEntries = defineTool({
+    name: "list_contact_lists",
+    title: "List contact allow/block entries",
+    description: "List the allow/block contact-list entries that govern an inbox: its inbox-specific entries plus any " +
+        "account-wide entries that apply to every inbox this agent owns.",
+    inputSchema: {
+        inbox: inboxRef.describe("Owned inbox whose governing entries to list."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const page = await client.listContactListEntries(args.inbox);
+        const text = page.items.length
+            ? page.items.map(renderContactListEntry).join("\n\n")
+            : "No contact-list entries for this inbox.";
+        return ok(`${page.items.length} entry(ies).\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+        });
+    },
+});
+const deleteContactListEntry = defineTool({
+    name: "delete_contact_list_entry",
+    title: "Delete a contact allow/block entry",
+    description: "Delete a contact-list entry by id (lst_…). The allow/block rule stops applying immediately.",
+    inputSchema: {
+        inbox: inboxRef.describe("Owned inbox the entry belongs to."),
+        id: z.string().min(1).describe("Entry id (lst_…) from add_contact_list_entry / list_contact_lists."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const result = await client.deleteContactListEntry(args.inbox, args.id);
+        return ok(`Deleted contact list entry ${result.id}.`, result);
+    },
+});
+// ---------------------------------------------------------------------------
+// Suppressions (recipient opt-outs / list-unsubscribe)
+// ---------------------------------------------------------------------------
+const checkSuppression = defineTool({
+    name: "check_suppression",
+    title: "Check whether a recipient has opted out",
+    description: "Pre-check, BEFORE you compose, whether a recipient has opted out of this org's mail (list-unsubscribe / " +
+        "suppression). If suppressed=true, a send to that address WILL be rejected with recipient_suppressed — do NOT " +
+        "include them; drop that recipient or pick another. This checks your OWN org's opt-outs only (it never reveals " +
+        "a platform-wide or other-tenant opt-out). Returns suppressed (bool) plus the matching org rows (each with an id " +
+        "you can revoke_suppression if the recipient asked to resume).",
+    inputSchema: {
+        recipient: emailAddress.describe("The recipient address to pre-check for an opt-out."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const res = await client.precheckSuppression(args.recipient);
+        const head = res.suppressed
+            ? `SUPPRESSED — do NOT send to ${res.recipient} (it will be rejected with recipient_suppressed).`
+            : `Not suppressed — ${res.recipient} may be mailed.`;
+        const rows = res.rows.length ? "\n\n" + res.rows.map(renderSuppression).join("\n\n") : "";
+        return ok(`${head}${rows}`, {
+            recipient: res.recipient,
+            suppressed: res.suppressed,
+            rows: res.rows,
+        });
+    },
+});
+const listSuppressions = defineTool({
+    name: "list_suppressions",
+    title: "List recipient opt-outs (suppressions)",
+    description: "List this org's recipient opt-outs (list-unsubscribe / suppression rows), newest first. These are recipients " +
+        "the org may no longer email — a send to one is rejected with recipient_suppressed. Active rows only by default; " +
+        "pass include_revoked=true to also see revoked rows. Only your OWN org's rows are returned (never platform-wide " +
+        "or other-tenant opt-outs). Use check_suppression to test one specific address instead.",
+    inputSchema: {
+        include_revoked: z
+            .boolean()
+            .default(false)
+            .describe("Also include revoked rows (default false = active opt-outs only)."),
+        limit: z.number().int().min(1).max(200).optional().describe("Max rows to return."),
+        cursor: z.string().optional().describe("Opaque cursor from a previous call's next_cursor."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const page = await client.listSuppressions({
+            include_revoked: args.include_revoked,
+            limit: args.limit,
+            cursor: args.cursor,
+        });
+        const text = page.items.length
+            ? page.items.map(renderSuppression).join("\n\n")
+            : "No suppressions.";
+        return ok(`${page.items.length} suppression(s).\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+            next_cursor: page.next_cursor,
+        });
+    },
+});
+const revokeSuppression = defineTool({
+    name: "revoke_suppression",
+    title: "Revoke a suppression (re-enable a recipient)",
+    description: "Revoke ONE of this org's suppression rows so the recipient can be emailed again — e.g. the recipient explicitly " +
+        "asked to resubscribe. A reason is REQUIRED and is audit-logged (do not revoke without a genuine recipient signal: " +
+        "re-suppressing after a revoke flags the org for abuse review). You may only revoke your OWN org's rows (a foreign, " +
+        "platform-global, or shared-domain id is an indistinguishable not-found). Find the id via list_suppressions or " +
+        "check_suppression. Returns the revoked row.",
+    inputSchema: {
+        id: z.string().min(1).describe("Suppression row id (sup_…) from list_suppressions / check_suppression."),
+        reason: z
+            .string()
+            .min(1)
+            .describe("Why the opt-out is being revoked (required, audit-logged). E.g. 'recipient re-subscribed via reply'."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        if (!args.reason.trim()) {
+            throw new ExtrovertApiError("A reason is required to revoke a suppression.", 400, "invalid_argument");
+        }
+        const row = await client.revokeSuppression(args.id, args.reason);
+        return ok(`Revoked — ${row.recipient} may be emailed again.\n${renderSuppression(row)}`, row);
+    },
+});
+// ---------------------------------------------------------------------------
+// Reputation / deliverability (diverse-smtp M7) — read-only, org-scoped
+// ---------------------------------------------------------------------------
+const getDeliverabilityStatus = defineTool({
+    name: "get_deliverability_status",
+    title: "Get deliverability status",
+    description: "Read this org's outbound deliverability health: an overall status badge (healthy / at_risk / paused / enforced / " +
+        "unknown), each sending provider/tenant's status, the latest window's Sends/Bounces/Complaints (with rates), and " +
+        "the count of open findings. Use it before a large send to check the org isn't paused or at risk. Read-only, " +
+        "org-scoped — there is no pause/unpause control here. Advisor findings show 'unavailable_vdm_disabled' when the " +
+        "provider's deliverability manager is off (status and metrics are still shown).",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (_args, { client }) => {
+        const rep = await client.getReputation();
+        const m = rep.metrics;
+        const lines = [
+            `status: ${rep.status} · sending: ${rep.sending_status} · open findings: ${rep.open_findings}`,
+            `metrics: ${m.sends} sends · ${m.bounces} bounces (${(m.bounce_rate * 100).toFixed(2)}%) · ${m.complaints} complaints (${(m.complaint_rate * 100).toFixed(3)}%)`,
+            ...rep.providers.map((p) => `- ${p.provider} ${p.label ?? p.provider_account_id}: ${p.sending_status}` +
+                ` · advisor: ${p.advisor_findings_status}`),
+        ];
+        return ok(lines.join("\n"), rep);
+    },
+});
+const listDeliverabilityFindings = defineTool({
+    name: "list_deliverability_findings",
+    title: "List deliverability findings",
+    description: "List this org's deliverability findings (bounce/complaint/auth/blocklist issues affecting sending), newest first. " +
+        "Filter by status (open/resolved), severity (low/high), domain, or sender. Read-only, org-scoped. When the provider's " +
+        "deliverability manager (VDM) is off, advisor findings are unavailable and this returns an empty list — use " +
+        "get_deliverability_status for the always-available status and metrics.",
+    inputSchema: {
+        status: z.enum(["open", "resolved"]).optional().describe("Filter by finding status."),
+        severity: z.enum(["low", "high", "unknown"]).optional().describe("Filter by severity."),
+        domain: z.string().optional().describe("Filter to one sending domain."),
+        sender: z.string().optional().describe("Filter to one sender address."),
+        limit: z.number().int().min(1).max(200).optional().describe("Max rows to return."),
+        cursor: z.string().optional().describe("Opaque cursor from a previous call's next_cursor."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const page = await client.listDeliverabilityFindings({
+            status: args.status,
+            severity: args.severity,
+            domain: args.domain,
+            sender: args.sender,
+            limit: args.limit,
+            cursor: args.cursor,
+        });
+        const text = page.items.length
+            ? page.items
+                .map((f) => `[${f.severity}/${f.status}] ${f.type}${f.domain ? ` (${f.domain})` : ""}: ${f.title} — ${f.detail}`)
+                .join("\n")
+            : "No findings.";
+        return ok(`${page.items.length} finding(s).\n\n${text}`, {
+            items: page.items,
+            total: page.total,
+            next_cursor: page.next_cursor,
+        });
+    },
+});
+// ---------------------------------------------------------------------------
+// Domains (Slice 5) — privileged (domain:manage scope)
+// ---------------------------------------------------------------------------
+const listDomains = defineTool({
+    name: "list_domains",
+    title: "List the customer's domains",
+    description: "List the domains onboarded for this agent's customer, each with its onboarding mode and " +
+        "verification/DKIM status. Domain management is privileged — the agent key must carry the " +
+        "domain:manage scope or these tools return a 403.",
+    inputSchema: {},
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (_args, { client }) => {
+        const page = await client.listDomains();
+        const text = page.items.length ? page.items.map(renderDomain).join("\n\n") : "No domains onboarded.";
+        return ok(`${page.items.length} domain(s).\n\n${text}`, { items: page.items, total: page.total });
+    },
+});
+const getDomain = defineTool({
+    name: "get_domain",
+    title: "Get a domain's status and DNS records",
+    description: "Get one domain's verification status plus the DNS records the customer must set, inline. For " +
+        "ns_delegated domains this also returns the single NS delegation to add at the registrar.",
+    inputSchema: {
+        domain: z.string().min(1).describe("The fully-qualified domain name (e.g. mail.acme.com)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const domain = await client.getDomain(args.domain);
+        return ok(renderDomain(domain), domain);
+    },
+});
+const onboardDomain = defineTool({
+    name: "onboard_domain",
+    title: "Onboard (add) a domain",
+    description: "Onboard a domain for the customer. `mode` selects the path: `shared` (instant, no DNS), " +
+        "`ns_delegated` (default; delegate one NS record and we serve the zone + rotate the signing keys), `manual` " +
+        "(returns the record set to add yourself), or `purchased` (buy-through-us; runs as a money-safe " +
+        "background job). All modes require the domain:manage scope; `purchased` ADDITIONALLY requires the explicit, " +
+        "default-off domain:purchase scope (because it spends money at the registrar) and is bounded by the org/project " +
+        "purchased-domain cap — check whoami's scopes before requesting it. Use `scope` to make the domain org-shared " +
+        "(default) or bind it to this key's fixed project. Returns the record set / NS instruction.",
+    inputSchema: {
+        domain: z.string().min(1).describe("The domain to onboard (e.g. mail.acme.com)."),
+        mode: z
+            .enum(["shared", "ns_delegated", "manual", "purchased"])
+            .optional()
+            .describe("Onboarding path. Defaults to ns_delegated. `purchased` additionally requires the domain:purchase scope (opt-in)."),
+        mail_host_ip: z
+            .string()
+            .optional()
+            .describe("A-record IP served at a delegated zone's apex (ns_delegated only)."),
+        scope: z
+            .enum(["org", "project"])
+            .optional()
+            .describe("Domain visibility. `org` (default) lets every project in the org use it; `project` binds it to this key's " +
+            "fixed project only (never client-selected — derived from the key)."),
+        project_id: projectAssertion,
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const domain = await client.onboardDomain({
+            domain: args.domain,
+            mode: args.mode,
+            mail_host_ip: args.mail_host_ip,
+            scope: args.scope,
+            project_id: args.project_id,
+        });
+        return ok(`Domain onboarded.\n${renderDomain(domain)}`, domain);
+    },
+});
+const verifyDomain = defineTool({
+    name: "verify_domain",
+    title: "Trigger or refresh domain verification",
+    description: "Trigger/refresh verification for an onboarded domain and return its (possibly advanced) status. " +
+        "For purchased domains this re-drives the resumable buy/verify pipeline; for manual/ns_delegated " +
+        "it re-reads status and returns the records still to set. Idempotent.",
+    inputSchema: {
+        domain: z.string().min(1).describe("The domain to (re)verify."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const domain = await client.verifyDomain(args.domain);
+        return ok(`Verification refreshed.\n${renderDomain(domain)}`, domain);
+    },
+});
+const offboardDomain = defineTool({
+    name: "offboard_domain",
+    title: "Offboard (remove) a domain",
+    description: "Remove a domain from the customer. DESTRUCTIVE AND IRREVERSIBLE: the teardown job's FIRST step " +
+        "cascade-deletes EVERY inbox on that domain — the mailbox itself, its stored messages and its " +
+        "sender identity — and only then reaps the outbound provider senders + routing and scrubs the DNS " +
+        "zone and the domain record. Nothing on the domain survives; there is no undo. Move or export " +
+        "anything you need before calling this. Runs as an async job: this ACCEPTS the request and returns " +
+        "a job id + poll URL (status_url). Poll the returned job_id with get_job until its status is " +
+        "terminal (succeeded/failed/cancelled) to confirm teardown finished. Requires the domain:manage " +
+        "scope.",
+    inputSchema: {
+        domain: z.string().min(1).describe("The domain to offboard."),
+    },
+    annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const result = await client.offboardDomain(args.domain);
+        return ok(`Offboard accepted for ${result.domain} (status: ${result.status}). Poll ${result.status_url} (get_job with job_id "${result.job_id}") until it is terminal (succeeded/failed/cancelled).`, result);
+    },
+});
+const getJob = defineTool({
+    name: "get_job",
+    title: "Poll an async job's status",
+    description: "Poll an async job like the offboard_domain teardown until its status is terminal " +
+        "(succeeded/failed/cancelled). Pass the job_id returned by the tool that started the job " +
+        "(e.g. offboard_domain's job_id / status_url). An unknown or foreign job id is a 404.",
+    inputSchema: {
+        job_id: z.string().min(1).describe("The job id to poll (e.g. from offboard_domain's job_id)."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { client }) => {
+        const job = await client.getJob(args.job_id);
+        return ok(renderJob(job), job);
+    },
+});
+const streamInfo = defineTool({
+    name: "stream_info",
+    title: "Real-time stream (SSE) info",
+    description: "Describe the real-time Server-Sent-Events (SSE) endpoints for watching inboxes live. MCP is request/response and " +
+        "cannot hold an open stream, so this tool does NOT stream — it returns the endpoint URLs + how to consume them " +
+        "directly (curl / EventSource / the @extrovert.dev/sdk `inbox.stream()` / `extrovert.stream()` helper). Each SSE event " +
+        "carries a monotonic `id:` (the resume token); reconnect with the `Last-Event-ID` header (or `?last_event_id=`) to " +
+        "replay everything after it. Events use the same envelope a webhook delivers (e.g. message.received). To get pushed " +
+        "deliveries inside an MCP-only setup, use register_webhook instead.",
+    inputSchema: {
+        inbox: inboxRef.optional().describe("Scope the stream to one owned inbox. Omit for the all-inboxes stream."),
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    handler: async (args, { config }) => {
+        const base = config.apiBaseUrl.replace(/\/+$/, "");
+        const inboxPath = args.inbox
+            ? `/v1/inboxes/${encodeURIComponent(args.inbox)}/stream`
+            : undefined;
+        const allPath = "/v1/events";
+        const url = (path) => `${base}${path}`;
+        const target = inboxPath ?? allPath;
+        const lines = [
+            "Extrovert exposes a real-time SSE stream. MCP cannot hold the connection open — consume it directly:",
+            "",
+            args.inbox
+                ? `• One inbox:   GET ${url(inboxPath)}`
+                : `• All inboxes: GET ${url(allPath)}`,
+            args.inbox ? `• All inboxes: GET ${url(allPath)}` : `• One inbox:   GET ${url("/v1/inboxes/{address}/stream")}`,
+            "",
+            "Headers: Authorization: Bearer <agent key>, Accept: text/event-stream.",
+            "Resume:  set Last-Event-ID: <last seq> (or ?last_event_id=<seq>) to replay events after it.",
+            "Events:  same envelope as webhooks (e.g. message.received) in each frame's data: line.",
+            "",
+            `curl:    curl -N -H "Authorization: Bearer $EXTROVERT_API_KEY" ${url(target)}`,
+            "SDK:     for await (const ev of inbox.stream()) { /* ev.event, ev.seq, ev.message */ }",
+            "         (or extrovert.stream() for all inboxes; pass { lastEventId } to resume)",
+        ];
+        return ok(lines.join("\n"), {
+            stream_url: url(target),
+            all_inboxes_url: url(allPath),
+            inbox_url: inboxPath ? url(inboxPath) : null,
+            resume_header: "Last-Event-ID",
+            resume_query_param: "last_event_id",
+            content_type: "text/event-stream",
+            mcp_can_stream: false,
+        });
+    },
+});
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+const ALL_TOOLS = [
+    redeemEnrollment,
+    signUp,
+    verifySignup,
+    whoami,
+    createInbox,
+    listInboxes,
+    getInbox,
+    updateInbox,
+    exportEmailConfig,
+    deleteInbox,
+    sendEmail,
+    replyEmail,
+    forwardEmail,
+    listReviews,
+    getReview,
+    getReviewTurns,
+    getReviewFeedback,
+    getReviewDecisionContext,
+    reviewerDecide,
+    postReviewChat,
+    submitRevision,
+    cancelReview,
+    restampReview,
+    listCategories,
+    getCategory,
+    proposeCategory,
+    updateCategory,
+    getRiskDial,
+    getGraduationStatus,
+    getBacklogStatus,
+    getPacingState,
+    proposeGraduation,
+    getRules,
+    saveRule,
+    promoteRule,
+    retireRule,
+    getRuleAudit,
+    undoRuleChange,
+    listReviewEvents,
+    waitForReviewEvent,
+    ackReviewEvent,
+    readMessages,
+    getMessage,
+    listAttachments,
+    getAttachment,
+    markRead,
+    listThreads,
+    getThread,
+    deleteMessage,
+    deleteThread,
+    batchUpdateMessages,
+    search,
+    waitForEmail,
+    registerWebhook,
+    listWebhooks,
+    getWebhook,
+    updateWebhook,
+    deleteWebhook,
+    addContactListEntry,
+    listContactListEntries,
+    deleteContactListEntry,
+    checkSuppression,
+    listSuppressions,
+    revokeSuppression,
+    getDeliverabilityStatus,
+    listDeliverabilityFindings,
+    listDomains,
+    getDomain,
+    onboardDomain,
+    verifyDomain,
+    offboardDomain,
+    getJob,
+    streamInfo,
+];
+/** The set of tool names this server exposes (handy for tests/docs). */
+export const TOOL_NAMES = ALL_TOOLS.map((t) => t.name);
+/** Register every Extrovert tool onto an MCP server instance. */
+export function registerTools(server, ctx) {
+    for (const tool of ALL_TOOLS) {
+        tool.register(server, ctx);
+    }
+}
+// ---------------------------------------------------------------------------
+// helpers
+// ---------------------------------------------------------------------------
+function truncate(text, max) {
+    const trimmed = text.trim();
+    return trimmed.length <= max ? trimmed : `${trimmed.slice(0, max)}…`;
+}
+/**
+ * Map an offline-store sentinel error (by class name, to avoid importing the
+ * fixtures module) to the contract's problem-code + HTTP status (redesign §5.1
+ * closed enum). The live path already carries these via {@link ExtrovertApiError};
+ * this keeps the OFFLINE error surface identical so an agent switching between
+ * mock and live sees the same machine codes.
+ */
+const MOCK_ERROR_MAP = {
+    NotFoundError: { status: 404, code: "not_found" },
+    ForbiddenError: { status: 403, code: "forbidden_scope" },
+    BreadthRequiredError: { status: 400, code: "breadth_required" },
+    BlockedError: { status: 403, code: "recipient_blocked" },
+    SuppressedError: { status: 422, code: "recipient_suppressed" },
+    // `intent_required`, NOT `bad_request`: it is its own closed code with its own
+    // remediation, and an agent that saw the generic code had no way to tell "add an
+    // intent and retry" from "your request was malformed".
+    IntentRequiredError: { status: 422, code: "intent_required" },
+    ConflictingAliasError: { status: 400, code: "bad_request" },
+    // The 409 SPLIT. `stale` is the only one of these worth retrying; `wrong_state`
+    // needs a different verb and `terminal` needs the agent to STOP. Collapsing them
+    // into one `conflict` is what let a single 409 handler retry a sent message
+    // forever, so the mock must distinguish them exactly as the live API does.
+    StaleError: { status: 409, code: "stale" },
+    WrongStateError: { status: 409, code: "wrong_state" },
+    TerminalError: { status: 409, code: "terminal" },
+    ConflictError: { status: 409, code: "conflict" },
+};
+/**
+ * Render the `{field, code, detail}` hints a problem body carries.
+ *
+ * This surface renders TEXT: anything left in `structuredContent` is invisible to
+ * a text-only model. The server puts the full remediation prose in `detail` for
+ * exactly that reason, and `errors[]` carries the machine duplicate — the exact
+ * JSON to add on a 422 `intent_required`, the current revision to re-CAS against
+ * and the legal verbs on a 409. Dropping them here is what made the remediation
+ * unreachable.
+ */
+function renderProblemFields(fields) {
+    if (!fields?.length)
+        return "";
+    const lines = fields.map((f) => `  - ${f.field} (${f.code})${f.detail ? `: ${f.detail}` : ""}`);
+    return `\nDetails:\n${lines.join("\n")}`;
+}
+function toErrorResult(err) {
+    if (err instanceof ExtrovertApiError) {
+        const detail = err.status ? ` (HTTP ${err.status}${err.code ? `, ${err.code}` : ""})` : "";
+        return {
+            content: [
+                { type: "text", text: `Extrovert error${detail}: ${err.message}${renderProblemFields(err.problemErrors)}` },
+            ],
+            isError: true,
+        };
+    }
+    // Offline-store sentinels carry a stable class name; surface the SAME problem
+    // code/status AND the same field hints the live API would return, so an agent
+    // that learned to recover offline recovers identically against production.
+    if (err instanceof Error && MOCK_ERROR_MAP[err.name]) {
+        const { status, code } = MOCK_ERROR_MAP[err.name];
+        const fields = err.problemErrors;
+        return {
+            content: [
+                { type: "text", text: `Extrovert error (HTTP ${status}, ${code}): ${err.message}${renderProblemFields(fields)}` },
+            ],
+            isError: true,
+        };
+    }
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: `Error: ${message}` }], isError: true };
+}
+//# sourceMappingURL=tools.js.map