@aitne/daemon 0.1.0

package/dist/api/routes/mail.js

@@ -0,0 +1,1406 @@
+import { Hono } from "hono";
+import { streamSSE } from "hono/streaming";
+import { createSettingsStore } from "../../settings/settings-store.js";
+import { applyConfigUpdates } from "../env-writer.js";
+import { markIntegrationWrite } from "../../safety/integration-write-tracker.js";
+import { loadOutlookClientConfig, saveOutlookClientConfig, OUTLOOK_CLIENT_CONFIG_BLOB, } from "../../services/mail/outlook/client-config.js";
+import { runLoopbackOAuth, OAuthLoopbackError, OAuthLoopbackTimeoutError, } from "../../services/mail/outlook/oauth-loopback.js";
+import { runDeviceCodeOAuth } from "../../services/mail/outlook/oauth-device-code.js";
+import { DuplicateAccountError, ProviderNotImplementedError, } from "../../services/mail/account-registry.js";
+import { createLogger } from "../../logging.js";
+import { readJsonBody } from "../json-body.js";
+import { buildImapAccountSecret, isImapAppPasswordKind, serializeImapAccountSecret, } from "../../services/mail/imap/app-password.js";
+import { classifyImapAuthFailure } from "../../services/mail/imap/auth-failure-classifier.js";
+import { verifyImapAccountSecret } from "../../services/mail/imap/client.js";
+import { searchMail } from "../../services/mail/mail-search.js";
+import { extractMailHtmlBody, renderExtractedMailHtmlBody, } from "../../services/mail/html-to-plaintext.js";
+import { isIntegrationDelegated } from "../../core/integration-lifecycle.js";
+import { INTEGRATION_DESCRIPTORS, } from "@aitne/shared";
+import { readIntegrations } from "../../db/integrations-store.js";
+const logger = createLogger("mail-api");
+const ALL_KINDS = [
+    "gmail",
+    "outlook",
+    "yahoo",
+    "icloud",
+];
+const PROVIDER_LABELS = {
+    gmail: "Gmail",
+    outlook: "Outlook",
+    yahoo: "Yahoo Mail",
+    icloud: "iCloud Mail",
+};
+/** Lower bound on the §C6 agent-write-attribution TTL. Covers the common
+ *  case where the poll interval is short (default 180s) — we still want
+ *  enough slack for a user action that triggered the send to settle before
+ *  the next poll picks it up. Real TTL scales with the configured poll
+ *  interval (see {@link computeAgentWriteTtlMs}). */
+const MAIL_AGENT_WRITE_TTL_FLOOR_MS = 5 * 60 * 1000;
+/** The poll-interval multiplier. Two ticks of slack means: a send at T=0
+ *  survives the T=poll and T=2*poll ticks before the mark expires —
+ *  enough to absorb one missed/delayed tick without losing attribution. */
+const MAIL_AGENT_WRITE_TTL_POLL_MULTIPLIER = 2;
+const MAIL_BODY_CHUNK_DEFAULT_CHARS = 12_000;
+const MAIL_BODY_CHUNK_MAX_CHARS = 50_000;
+const MAIL_BODY_METADATA_DEFAULT_LIMIT = 100;
+const MAIL_BODY_METADATA_MAX_LIMIT = 500;
+export function computeAgentWriteTtlMs(pollIntervalSeconds) {
+    const derived = (pollIntervalSeconds ?? 0) * 1000 * MAIL_AGENT_WRITE_TTL_POLL_MULTIPLIER;
+    return Math.max(MAIL_AGENT_WRITE_TTL_FLOOR_MS, derived);
+}
+function gatedIntegrationForKind(kind) {
+    if (kind === "gmail")
+        return "gmail";
+    if (kind === "outlook")
+        return "outlook_mail";
+    return null;
+}
+function delegatedMailIntegrationMessage(key, delegatedBackend) {
+    const descriptor = INTEGRATION_DESCRIPTORS[key];
+    const displayName = descriptor.displayName;
+    const owner = delegatedBackend
+        ? `delegated to ${delegatedBackend}`
+        : "delegated";
+    // User-managed connector integrations (Outlook today) ship no
+    // daemon-side proxy. The agent must use whatever Outlook MCP /
+    // connector the user wired up on the chosen backend; pointing at
+    // `/api/integrations/.../invoke` would be a lie.
+    if (descriptor.userManagedConnector) {
+        return [
+            `${displayName} is in delegated mode (${owner}).`,
+            `The agent backend is expected to use the user-installed ${displayName} MCP / connector tools — the daemon does not proxy this integration.`,
+            "Other mail accounts remain available through /api/mail/*.",
+        ].join(" ");
+    }
+    return [
+        `${displayName} is in delegated mode (${owner}).`,
+        `Same-backend sessions: use the connector's native ${displayName} MCP tools.`,
+        `Cross-backend sessions: call POST /api/integrations/${key}/invoke.`,
+        `Non-${displayName} mail accounts remain available through /api/mail/*.`,
+    ].join(" ");
+}
+export function createMailRoutes(deps) {
+    const app = new Hono();
+    const getSettingsStore = () => deps.settingsStore ?? createSettingsStore(deps.db);
+    const verifyImapCredentials = deps.verifyImapAccountSecret ?? verifyImapAccountSecret;
+    app.get("/mail/providers", (c) => {
+        const registry = deps.services.mail;
+        const accounts = registry?.listAccounts() ?? [];
+        const available = ALL_KINDS.map((kind) => {
+            const ofKind = accounts.filter((a) => a.kind === kind);
+            return {
+                kind,
+                label: PROVIDER_LABELS[kind],
+                accountsConfigured: ofKind.length,
+                accountsHealthy: ofKind.filter((a) => a.authStatus === "healthy").length,
+            };
+        });
+        return c.json({
+            enabledKinds: [...deps.config.enabledMailProviders],
+            available,
+        });
+    });
+    app.patch("/mail/providers", async (c) => {
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const candidate = parsedBody.body?.enabledKinds;
+        if (!Array.isArray(candidate)) {
+            return c.json({ error: "invalid_body", message: "enabledKinds must be an array" }, 400);
+        }
+        const settingsStore = getSettingsStore();
+        const result = await applyConfigUpdates(deps.config, settingsStore, {
+            enabledMailProviders: candidate,
+        });
+        if (Object.keys(result.errors).length > 0) {
+            return c.json({ error: "validation_failed", errors: result.errors }, 400);
+        }
+        const newKinds = deps.config.enabledMailProviders;
+        const registry = deps.services.mail;
+        const before = new Set();
+        const after = new Set(newKinds);
+        const accounts = registry?.listAccounts() ?? [];
+        for (const acct of accounts) {
+            before.add(acct.kind);
+        }
+        const dormantAccounts = accounts
+            .filter((a) => before.has(a.kind) && !after.has(a.kind))
+            .map((a) => a.id);
+        const resumedAccounts = accounts
+            .filter((a) => after.has(a.kind))
+            .map((a) => a.id);
+        registry?.onProviderSelectionChanged(newKinds);
+        logger.info({ enabledKinds: [...newKinds], dormantAccounts, resumedAccounts }, "mail provider selection updated");
+        return c.json({ status: "updated", dormantAccounts, resumedAccounts });
+    });
+    // GET /mail/accounts — all configured accounts (dashboard, setup).
+    // GET /mail/accounts?active=1 — scope-gated subset that matches what
+    // `accounts.md` materializes and what the unified poller observes:
+    //   kind ∈ enabledMailProviders ∧ account.active ∧ authStatus === "healthy".
+    // Skills that need to refresh a stale `accounts.md` MUST pass `?active=1`
+    // — raw listAccounts() includes dormant / unhealthy rows and will mislead
+    // the agent into picking an id that every operation will 4xx on.
+    app.get("/mail/accounts", (c) => {
+        const registry = deps.services.mail;
+        if (!registry) {
+            return c.json({ accounts: [] });
+        }
+        const activeOnly = c.req.query("active") === "1";
+        const accounts = activeOnly
+            ? registry.listActiveAccounts()
+            : registry.listAccounts();
+        return c.json({ accounts });
+    });
+    // POST /mail/accounts blocks for the duration of the loopback PKCE flow —
+    // up to OAuthLoopbackTimeoutError's 5-minute cap (see oauth-loopback.ts).
+    // Dashboard clients MUST configure a long fetch timeout for this route.
+    // Headless environments (SSH, WSL) should use /mail/accounts/device-code.
+    app.post("/mail/accounts", async (c) => {
+        const registry = deps.services.mail;
+        if (!registry)
+            return c.json({ error: "mail_not_configured" }, 503);
+        if (!deps.blobStore)
+            return c.json({ error: "blob_store_unavailable" }, 503);
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        if (body?.kind === "gmail") {
+            // The primary Gmail mailbox now participates in the unified mail
+            // surface via the shared Google OAuth credentials from
+            // /config/google-auth. Additional Gmail accounts still need a
+            // per-account Google OAuth credential store and are intentionally
+            // not wired up yet.
+            return c.json({
+                error: "not_implemented",
+                message: "Additional Gmail accounts are not implemented yet. The primary Gmail identity is configured through /config/google-auth and is exposed on the unified /mail/* surface automatically.",
+            }, 501);
+        }
+        if (body?.kind !== "outlook") {
+            return c.json({
+                error: "unsupported_kind",
+                message: "Only outlook is supported on this endpoint. Yahoo/iCloud use POST /config/mail/app-password. The primary Gmail account uses /config/google-auth; extra Gmail accounts are not implemented.",
+            }, 400);
+        }
+        // §UI v2 auth-then-enable: registration is allowed regardless of
+        // enabledMailProviders. The provider becomes live only when the user
+        // toggles "Enable" on the dashboard mail card.
+        const clientConfig = await loadOutlookClientConfig(deps.blobStore);
+        if (!clientConfig) {
+            return c.json({
+                error: "outlook_client_config_missing",
+                message: "PUT /api/config/mail/outlook/client-config first.",
+            }, 412);
+        }
+        let oauthResult;
+        try {
+            oauthResult = await runLoopbackOAuth({ clientConfig });
+        }
+        catch (err) {
+            if (err instanceof OAuthLoopbackTimeoutError) {
+                return c.json({ error: "oauth_timeout", message: err.message }, 408);
+            }
+            if (err instanceof OAuthLoopbackError) {
+                return c.json({ error: err.code, message: err.message }, 400);
+            }
+            logger.error({ err }, "outlook oauth bootstrap failed");
+            return c.json({ error: "oauth_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        try {
+            const account = await registry.addAccount({
+                kind: "outlook",
+                email: oauthResult.email,
+                label: typeof body?.label === "string" ? body.label : undefined,
+                authType: "oauth",
+                secretPayload: oauthResult.serializedCache,
+            });
+            return c.json({ status: "completed", account });
+        }
+        catch (err) {
+            if (err instanceof DuplicateAccountError) {
+                return c.json({ error: err.code, message: err.message }, 409);
+            }
+            logger.error({ err, email: oauthResult.email }, "outlook addAccount failed after OAuth");
+            return c.json({ error: "add_account_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    // Device-code fallback (§B2). Used by headless/SSH environments where the
+    // loopback flow's browser-open would fail. Streams SSE events:
+    //   `prompt`    { userCode, verificationUri, expiresIn, message }
+    //   `completed` { account }
+    //   `failed`    { error, message }
+    //
+    // MSAL's acquireTokenByDeviceCode blocks until the user completes verification
+    // in their browser, so this endpoint may remain open for several minutes.
+    app.post("/mail/accounts/device-code", async (c) => {
+        const registry = deps.services.mail;
+        if (!registry)
+            return c.json({ error: "mail_not_configured" }, 503);
+        if (!deps.blobStore)
+            return c.json({ error: "blob_store_unavailable" }, 503);
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        if (body?.kind !== "outlook") {
+            return c.json({ error: "unsupported_kind" }, 400);
+        }
+        // §UI v2 auth-then-enable: registration allowed regardless of
+        // enabledMailProviders. The Enable toggle on the dashboard mail card
+        // governs whether the agent observes this account.
+        const clientConfig = await loadOutlookClientConfig(deps.blobStore);
+        if (!clientConfig) {
+            return c.json({ error: "outlook_client_config_missing" }, 412);
+        }
+        const label = typeof body?.label === "string" ? body.label : undefined;
+        return streamSSE(c, async (stream) => {
+            try {
+                const result = await runDeviceCodeOAuth({
+                    clientConfig,
+                    onPrompt: async (info) => {
+                        await stream.writeSSE({
+                            event: "prompt",
+                            data: JSON.stringify(info),
+                        });
+                    },
+                });
+                try {
+                    const account = await registry.addAccount({
+                        kind: "outlook",
+                        email: result.email,
+                        label,
+                        authType: "oauth",
+                        secretPayload: result.serializedCache,
+                    });
+                    await stream.writeSSE({
+                        event: "completed",
+                        data: JSON.stringify({ account }),
+                    });
+                }
+                catch (err) {
+                    if (err instanceof DuplicateAccountError) {
+                        await stream.writeSSE({
+                            event: "failed",
+                            data: JSON.stringify({ error: err.code, message: err.message }),
+                        });
+                        return;
+                    }
+                    throw err;
+                }
+            }
+            catch (err) {
+                logger.error({ err }, "device-code oauth failed");
+                await stream.writeSSE({
+                    event: "failed",
+                    data: JSON.stringify({
+                        error: "device_code_failed",
+                        message: err instanceof Error ? err.message : String(err),
+                    }),
+                });
+            }
+        });
+    });
+    // Active-toggle for a single account. Distinct from provider-level enable
+    // (§6.0): users can disable one Outlook account while keeping the "Outlook"
+    // provider enabled.
+    app.patch("/mail/accounts/:accountId", async (c) => {
+        const registry = deps.services.mail;
+        if (!registry)
+            return c.json({ error: "mail_not_configured" }, 503);
+        const accountId = c.req.param("accountId");
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const active = parsedBody.body?.active;
+        if (typeof active !== "boolean") {
+            return c.json({ error: "invalid_body", message: "active: boolean required" }, 400);
+        }
+        const updated = await registry.setActive(accountId, active);
+        if (!updated)
+            return c.json({ error: "not_found" }, 404);
+        return c.json({ status: "updated", account: updated });
+    });
+    app.delete("/mail/accounts/:accountId", async (c) => {
+        const registry = deps.services.mail;
+        if (!registry) {
+            return c.json({ error: "mail_not_configured" }, 503);
+        }
+        const accountId = c.req.param("accountId");
+        const removed = await registry.removeAccount(accountId);
+        if (!removed) {
+            return c.json({ error: "not_found" }, 404);
+        }
+        return c.json({ status: "removed", accountId });
+    });
+    // ──────────────────────────────────────────────────────────────────────────
+    // Outlook BYOA client config (§6.1).
+    // Stored separately from per-account token cache.
+    // ──────────────────────────────────────────────────────────────────────────
+    app.get("/config/mail/outlook/client-config", async (c) => {
+        if (!deps.blobStore)
+            return c.json({ error: "blob_store_unavailable" }, 503);
+        const config = await loadOutlookClientConfig(deps.blobStore);
+        if (!config)
+            return c.json({ configured: false }, 200);
+        // clientId is technically public per the OAuth "public client" model;
+        // returning it lets the dashboard show a confirmation. Tenant ditto.
+        return c.json({ configured: true, clientId: config.clientId, tenant: config.tenant });
+    });
+    app.put("/config/mail/outlook/client-config", async (c) => {
+        if (!deps.blobStore)
+            return c.json({ error: "blob_store_unavailable" }, 503);
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const candidate = parsedBody.body;
+        const clientId = candidate?.clientId;
+        const tenant = candidate?.tenant;
+        if (typeof clientId !== "string" || clientId.length === 0) {
+            return c.json({ error: "invalid_body", message: "clientId required" }, 400);
+        }
+        const resolved = {
+            clientId,
+            tenant: typeof tenant === "string" && tenant.length > 0 ? tenant : "common",
+        };
+        await saveOutlookClientConfig(deps.blobStore, resolved);
+        return c.json({ status: "saved", clientId: resolved.clientId, tenant: resolved.tenant });
+    });
+    app.delete("/config/mail/outlook/client-config", async (c) => {
+        if (!deps.blobStore)
+            return c.json({ error: "blob_store_unavailable" }, 503);
+        await deps.blobStore.remove(OUTLOOK_CLIENT_CONFIG_BLOB);
+        return c.json({ status: "removed" });
+    });
+    // The Outlook OAuth bootstrap lives on POST /mail/accounts (loopback) or
+    // POST /mail/accounts/device-code (headless). No daemon-side callback
+    // endpoint is needed — the Microsoft redirect targets the ephemeral loopback
+    // http.Server inside runLoopbackOAuth.
+    app.post("/config/mail/app-password", async (c) => {
+        const registry = deps.services.mail;
+        if (!registry)
+            return c.json({ error: "mail_not_configured" }, 503);
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const kindCandidate = typeof body?.kind === "string" ? body.kind : null;
+        const email = typeof body?.email === "string" ? body.email : null;
+        const appPassword = typeof body?.appPassword === "string" ? body.appPassword : null;
+        if (!kindCandidate ||
+            !isImapAppPasswordKind(kindCandidate) ||
+            !email ||
+            email.length === 0 ||
+            !appPassword ||
+            appPassword.length === 0) {
+            return c.json({
+                error: "invalid_body",
+                message: "kind(yahoo|icloud), email, and appPassword are required.",
+            }, 400);
+        }
+        const kind = kindCandidate;
+        // §UI v2 auth-then-enable: registration allowed regardless of
+        // enabledMailProviders. The Enable toggle on the dashboard mail card
+        // governs whether the agent observes this account.
+        const secret = buildImapAccountSecret(kind, email, appPassword);
+        let capabilities;
+        try {
+            capabilities = await verifyImapCredentials(secret);
+        }
+        catch (err) {
+            const classified = classifyImapAuthFailure({
+                errorName: err instanceof Error ? err.name : null,
+                message: getImapErrorMessage(err),
+                responseCode: getErrorResponseCode(err),
+            });
+            if (classified.status === "requires_consent") {
+                return c.json({
+                    error: "imap_auth_failed",
+                    message: "IMAP login failed. Verify the email address and app password, then try again.",
+                }, 400);
+            }
+            if (classified.status === "degraded" || classified.status === "transient") {
+                return c.json({
+                    error: "imap_connect_failed",
+                    message: "The IMAP server could not be reached or rejected the login attempt. Try again shortly.",
+                }, 502);
+            }
+            logger.error({ err, kind, email }, "app-password IMAP verification failed");
+            return c.json({ error: "add_account_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        try {
+            const account = await registry.addAccount({
+                kind,
+                email,
+                label: typeof body?.label === "string" ? body.label : undefined,
+                authType: "app_password",
+                secretPayload: serializeImapAccountSecret(secret),
+                idleEnabled: true,
+                capabilities: capabilities ?? undefined,
+            });
+            return c.json({ status: "completed", account });
+        }
+        catch (err) {
+            if (err instanceof DuplicateAccountError) {
+                return c.json({ error: err.code, message: err.message }, 409);
+            }
+            if (err instanceof ProviderNotImplementedError) {
+                return c.json({ error: err.code, message: err.message }, 400);
+            }
+            logger.error({ err, kind, email }, "app-password account add failed");
+            return c.json({ error: "add_account_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    // Refresh an existing IMAP (Yahoo / iCloud) account's app password without
+    // deleting and re-creating the row. Used when the user rotates the password
+    // at the provider and the account flips to `requires_consent`. The route
+    // verifies the new credentials against the IMAP server before persisting,
+    // then resets `auth_status` to `healthy`.
+    app.post("/config/mail/app-password/:accountId/refresh", async (c) => {
+        const registry = deps.services.mail;
+        if (!registry)
+            return c.json({ error: "mail_not_configured" }, 503);
+        const accountId = c.req.param("accountId");
+        const account = registry.getAccount(accountId);
+        if (!account)
+            return c.json({ error: "not_found" }, 404);
+        if (account.kind !== "yahoo" && account.kind !== "icloud") {
+            return c.json({
+                error: "unsupported_kind",
+                message: "App-password refresh only supports yahoo / icloud. Outlook re-authenticates via the OAuth loopback flow.",
+            }, 400);
+        }
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const appPassword = typeof body?.appPassword === "string" ? body.appPassword : null;
+        if (!appPassword || appPassword.length === 0) {
+            return c.json({ error: "invalid_body", message: "appPassword is required." }, 400);
+        }
+        const secret = buildImapAccountSecret(account.kind, account.email, appPassword);
+        let capabilities;
+        try {
+            capabilities = await verifyImapCredentials(secret);
+        }
+        catch (err) {
+            const classified = classifyImapAuthFailure({
+                errorName: err instanceof Error ? err.name : null,
+                message: getImapErrorMessage(err),
+                responseCode: getErrorResponseCode(err),
+            });
+            if (classified.status === "requires_consent") {
+                return c.json({
+                    error: "imap_auth_failed",
+                    message: "IMAP login failed with the new password. Generate a fresh app password and try again.",
+                }, 400);
+            }
+            if (classified.status === "degraded" || classified.status === "transient") {
+                return c.json({
+                    error: "imap_connect_failed",
+                    message: "The IMAP server could not be reached. Try again shortly.",
+                }, 502);
+            }
+            logger.error({ err, accountId }, "app-password refresh verification failed");
+            return c.json({ error: "refresh_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+        }
+        try {
+            const updated = await registry.refreshImapSecret(accountId, serializeImapAccountSecret(secret), capabilities ?? undefined);
+            if (!updated)
+                return c.json({ error: "not_found" }, 404);
+            return c.json({ status: "refreshed", account: updated });
+        }
+        catch (err) {
+            logger.error({ err, accountId }, "app-password refresh failed");
+            return c.json({ error: "refresh_failed", message: err instanceof Error ? err.message : String(err) }, 500);
+        }
+    });
+    // ──────────────────────────────────────────────────────────────────────────
+    // Cross-account local search backed by the fts_mail_messages virtual
+    // table. Returns a flat list of lightweight summaries sourced
+    // from the index — no provider round-trip. Use this as the first stop for
+    // "find emails about X" queries; fall back to `/mail/:acct/messages?q=`
+    // only when the user wants provider-fresh results or matches bodies older
+    // than the local index.
+    //
+    // Shape matches MailMessageSummary (subset): { accountId, providerMsgId,
+    // subject, snippet, receivedAtUtc, from, isRead }. Results span all
+    // accounts by default; scope with `?accountId=`.
+    // ──────────────────────────────────────────────────────────────────────────
+    app.get("/mail/search", (c) => {
+        const q = c.req.query("q")?.trim() ?? "";
+        if (q.length === 0) {
+            return c.json({ error: "invalid_query", message: "q is required and must be non-empty" }, 400);
+        }
+        const limit = parseIntParam(c.req.query("limit"), 50, { min: 1, max: 500 });
+        const accountId = c.req.query("accountId") ?? undefined;
+        // §4.8 per-account delegated gate for search — if the caller pins the
+        // query to a Gmail account while gmail is delegated, 410. The
+        // unscoped cross-account search path stays open; results for a
+        // delegated Gmail account will just be stale FTS hits (live polling
+        // is off), which is acceptable for Phase 2 and documented in §4.4.
+        if (accountId) {
+            const account = deps.services.mail?.getAccount(accountId);
+            if (account) {
+                const gatedIntegrationKey = gatedIntegrationForKind(account.kind);
+                if (gatedIntegrationKey
+                    && isIntegrationDelegated(deps.db, gatedIntegrationKey)) {
+                    const state = readIntegrations(deps.db)[gatedIntegrationKey];
+                    return c.json({
+                        error: "integration_delegated",
+                        message: delegatedMailIntegrationMessage(gatedIntegrationKey, state.delegatedBackend ?? null),
+                        integration: gatedIntegrationKey,
+                        backend: state.delegatedBackend ?? null,
+                        mode: "delegated",
+                    }, 410);
+                }
+            }
+        }
+        const hits = searchMail(deps.db, q, { accountId, limit });
+        const results = hits.map((h) => ({
+            accountId: h.accountId,
+            providerMsgId: h.providerMsgId,
+            subject: h.subject,
+            snippet: h.snippet,
+            receivedAtUtc: h.receivedAtUtc,
+            from: h.fromEmail ? { email: h.fromEmail } : null,
+            isRead: h.isRead,
+        }));
+        return c.json({ results, count: results.length, query: q });
+    });
+    // Read the mail-side parse_failures diagnostics table. The poller +
+    // ingestion pipeline write a row whenever a Kindle-export / travel /
+    // classification path bails out; this endpoint surfaces the latest
+    // failures so the dashboard (or a curl one-liner) can answer "why
+    // didn't my booking get picked up?". Read-only — no mutation surface.
+    app.get("/mail/parse-failures", (c) => {
+        const limit = parseIntParam(c.req.query("limit"), 50, { min: 1, max: 500 });
+        const accountId = c.req.query("accountId") ?? null;
+        const params = [];
+        let sql = `
+      SELECT id,
+             account_id      AS accountId,
+             provider_msg_id AS providerMsgId,
+             sender,
+             subject,
+             snippet,
+             error_reason    AS errorReason,
+             created_at      AS createdAt
+        FROM parse_failures`;
+        if (accountId) {
+            sql += ` WHERE account_id = ?`;
+            params.push(accountId);
+        }
+        sql += ` ORDER BY id DESC LIMIT ?`;
+        params.push(limit);
+        const rows = deps.db.prepare(sql).all(...params);
+        return c.json({ failures: rows, count: rows.length });
+    });
+    // ──────────────────────────────────────────────────────────────────────────
+    // Per-account operations (§3.3, §3.11 parity table).
+    // Each route resolves a live MailProvider via the registry; error mapping
+    // distinguishes 404 (account not found) / 400 (provider not enabled for
+    // selection) / 501 (provider interface method not implemented yet for this
+    // kind). Write routes call writeTracker.markWriting so the unified poller
+    // suppresses the agent's own operations (§3.2).
+    // ──────────────────────────────────────────────────────────────────────────
+    const resolveProvider = async (accountId) => {
+        const registry = deps.services.mail;
+        if (!registry) {
+            return { ok: false, status: 503, code: "mail_not_configured", message: "Mail registry unavailable." };
+        }
+        const account = registry.getAccount(accountId);
+        if (!account) {
+            return { ok: false, status: 404, code: "not_found", message: `No mail account ${accountId}` };
+        }
+        // §4.8 per-account delegated gate. The route-gate middleware cannot
+        // blanket 410 `/api/mail/*` because it would also stop direct-only
+        // providers (iCloud, Yahoo, IMAP). Instead, accounts whose kind maps
+        // to a delegated integration (Gmail → gmail; Outlook → outlook_mail)
+        // return 410, and the agent backend's MCP / connector is expected to
+        // be the access path. Other kinds fall through unchanged.
+        const gatedIntegrationKey = gatedIntegrationForKind(account.kind);
+        if (gatedIntegrationKey && isIntegrationDelegated(deps.db, gatedIntegrationKey)) {
+            const state = readIntegrations(deps.db)[gatedIntegrationKey];
+            return {
+                ok: false,
+                status: 410,
+                code: "integration_delegated",
+                message: delegatedMailIntegrationMessage(gatedIntegrationKey, state.delegatedBackend ?? null),
+                integration: gatedIntegrationKey,
+                backend: state.delegatedBackend ?? null,
+            };
+        }
+        // Single scope-gate check mirroring `passesScopeGate` used by the
+        // unified poller and `accounts.md` materialization. Clients get one
+        // error shape (`provider_not_enabled`) with a machine-readable `detail`
+        // field so dashboards can render a specific prompt without having to
+        // branch on three near-synonymous codes.
+        //
+        // Recovery endpoints (`POST /config/mail/app-password/:id/refresh`)
+        // intentionally bypass this gate by reading the account directly — users
+        // MUST be able to fix a degraded account. If you add new recovery flows,
+        // keep that property: never route recovery through `resolveProvider`.
+        const detail = !deps.config.enabledMailProviders.includes(account.kind)
+            ? "kind_not_enabled"
+            : !account.active
+                ? "account_inactive"
+                : account.authStatus !== "healthy"
+                    ? "account_unhealthy"
+                    : null;
+        if (detail !== null) {
+            const detailMessages = {
+                kind_not_enabled: `${account.kind} is not in enabledMailProviders.`,
+                account_inactive: `Mail account ${accountId} is disabled.`,
+                account_unhealthy: `Mail account ${accountId} requires re-auth (status: ${account.authStatus}).`,
+            };
+            return {
+                ok: false,
+                status: 400,
+                code: "provider_not_enabled",
+                message: detailMessages[detail],
+                detail,
+            };
+        }
+        try {
+            const provider = await registry.getProvider(accountId);
+            if (!provider) {
+                return {
+                    ok: false,
+                    status: 501,
+                    code: "provider_not_implemented",
+                    message: `Provider ${account.kind} is not wired up.`,
+                };
+            }
+            return { ok: true, provider };
+        }
+        catch (err) {
+            if (err instanceof ProviderNotImplementedError) {
+                return { ok: false, status: 501, code: err.code, message: err.message };
+            }
+            throw err;
+        }
+    };
+    // TTL is derived from the current poll interval so the tracker mark
+    // outlives at least one poll tick (see computeAgentWriteTtlMs). Read at
+    // mark-time — reflects a runtime PATCH /api/config without a restart.
+    const writeTtlMs = () => computeAgentWriteTtlMs(deps.config.mailPollIntervalSeconds);
+    const markAgentWrite = (accountId, providerMsgId) => {
+        deps.writeTracker?.markWriting(`mail:${accountId}:${providerMsgId}`, undefined, {
+            ttlMs: writeTtlMs(),
+        });
+    };
+    // INTEGRATION-DRIFT-DETECTION-PLAN.md §11 Phase 4 — actor attribution
+    // for the persistent `integration_writes` table. Only Gmail accounts
+    // map to an `IntegrationKey` (per `gatedIntegrationForKind`); iCloud /
+    // Outlook / Yahoo / IMAP have no integration descriptor and skip.
+    // Each id passed here is marked under `(gmail, id)` for the Gmail
+    // default TTL (30 min — see INTEGRATION_WRITE_TTL_MS). Non-Gmail
+    // accounts return a no-op; the in-memory `markAgentWrite` above is the
+    // only attribution surface for them.
+    const markGmailIntegrationWrite = (accountId, ...providerIds) => {
+        const registry = deps.services.mail;
+        if (!registry)
+            return;
+        const account = registry.getAccount(accountId);
+        if (!account)
+            return;
+        if (gatedIntegrationForKind(account.kind) !== "gmail")
+            return;
+        for (const id of providerIds) {
+            if (typeof id === "string" && id.length > 0) {
+                markIntegrationWrite(deps.db, "gmail", id);
+            }
+        }
+    };
+    /**
+     * Second-key attribution via RFC-2822 Message-Id. On IMAP, the Sent folder
+     * UID the poller later observes has no relationship to the draft UID the
+     * route marked. The rfc822 key is stable across the transport path so the
+     * poller can still match. Providers that don't surface the id leave this
+     * a no-op (route treats undefined as "skip"). The poller is taught to
+     * check both keys (§MailPoller.pollAccount).
+     */
+    const markAgentWriteRfc822 = (accountId, rfc822MsgId) => {
+        if (!rfc822MsgId)
+            return;
+        deps.writeTracker?.markWriting(`mail:${accountId}:rfc822:${rfc822MsgId}`, undefined, { ttlMs: writeTtlMs() });
+    };
+    const ensureMethod = (provider, method) => typeof provider[method] === "function";
+    /**
+     * Render a `resolveProvider` failure as an HTTP response. The 410
+     * branch carries the §4.5.2 `integration_delegated` body shape (integration,
+     * backend) so the dashboard and agent tooling can uniformly detect the
+     * delegated-mode surface regardless of whether the path was caught by the
+     * global route-gate middleware (§4.5.2) or the per-account gate here (§4.8).
+     */
+    const renderResolveError = (c, resolved) => {
+        if (resolved.status === 410) {
+            return c.json({
+                error: resolved.code,
+                message: resolved.message,
+                integration: resolved.integration ?? null,
+                backend: resolved.backend ?? null,
+                mode: "delegated",
+            }, 410);
+        }
+        return c.json({
+            error: resolved.code,
+            message: resolved.message,
+            detail: resolved.detail,
+        }, resolved.status);
+    };
+    app.get("/mail/:accountId/health", (c) => {
+        const registry = deps.services.mail;
+        if (!registry)
+            return c.json({ error: "mail_not_configured" }, 503);
+        const accountId = c.req.param("accountId");
+        // §4.8 per-account delegated gate — also applies to /health so the
+        // dashboard does not surface a stale poll cursor for a Gmail account
+        // the daemon has stopped touching. Recovery endpoints (`POST
+        // /config/mail/app-password/:id/refresh`) stay outside this gate.
+        const account = registry.getAccount(accountId);
+        if (account) {
+            const gatedIntegrationKey = gatedIntegrationForKind(account.kind);
+            if (gatedIntegrationKey && isIntegrationDelegated(deps.db, gatedIntegrationKey)) {
+                const state = readIntegrations(deps.db)[gatedIntegrationKey];
+                return c.json({
+                    error: "integration_delegated",
+                    message: delegatedMailIntegrationMessage(gatedIntegrationKey, state.delegatedBackend ?? null),
+                    integration: gatedIntegrationKey,
+                    backend: state.delegatedBackend ?? null,
+                    mode: "delegated",
+                }, 410);
+            }
+        }
+        const health = registry.getHealth(accountId);
+        if (!health)
+            return c.json({ error: "not_found" }, 404);
+        return c.json(health);
+    });
+    app.get("/mail/:accountId/messages", async (c) => {
+        const accountId = c.req.param("accountId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        const limit = parseIntParam(c.req.query("limit"), 20, { min: 1, max: 100 });
+        try {
+            const messages = await resolved.provider.list({
+                folder: c.req.query("folder") ?? undefined,
+                q: c.req.query("q") ?? undefined,
+                limit,
+                since: c.req.query("since") ?? undefined,
+                unreadOnly: c.req.query("unreadOnly") === "true",
+            });
+            return c.json({ messages });
+        }
+        catch (err) {
+            return providerError(c, err, "list_failed");
+        }
+    });
+    app.get("/mail/:accountId/messages/:messageId", async (c) => {
+        const accountId = c.req.param("accountId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        const bodyMode = parseBodyMode(c.req.query("body"));
+        if (!bodyMode.ok)
+            return c.json(bodyMode.body, 400);
+        try {
+            const message = await resolved.provider.get(c.req.param("messageId"));
+            return c.json({ message: applyMailMessageBodyMode(message, bodyMode.value) });
+        }
+        catch (err) {
+            return providerError(c, err, "get_failed");
+        }
+    });
+    app.get("/mail/:accountId/messages/:messageId/body", async (c) => {
+        const resolved = await resolveProvider(c.req.param("accountId"));
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        const format = c.req.query("format") ?? "extracted";
+        if (format !== "extracted" && format !== "raw") {
+            return c.json({ error: "invalid_query", message: "format must be extracted or raw" }, 400);
+        }
+        const chunk = parseIntParam(c.req.query("chunk"), 0, { min: 0, max: 100_000 });
+        const maxChars = parseIntParam(c.req.query("maxChars"), MAIL_BODY_CHUNK_DEFAULT_CHARS, {
+            min: 1_000,
+            max: MAIL_BODY_CHUNK_MAX_CHARS,
+        });
+        const metadataOffset = parseIntParam(c.req.query("metadataOffset"), 0, {
+            min: 0,
+            max: 100_000,
+        });
+        const metadataLimit = parseIntParam(c.req.query("metadataLimit"), MAIL_BODY_METADATA_DEFAULT_LIMIT, { min: 1, max: MAIL_BODY_METADATA_MAX_LIMIT });
+        try {
+            const message = await resolved.provider.get(c.req.param("messageId"));
+            return c.json(buildMailBodyResponse({
+                accountId: c.req.param("accountId"),
+                message,
+                format,
+                chunk,
+                maxChars,
+                metadataOffset,
+                metadataLimit,
+            }));
+        }
+        catch (err) {
+            return providerError(c, err, "get_body_failed");
+        }
+    });
+    // /messages/send always *sends*. Draft creation has a dedicated endpoint
+    // (POST /mail/:id/drafts) so the path — not a body flag — determines the
+    // risk tier (§8). This avoids the "every draft DMs the owner" trap that
+    // body-aware classification would require.
+    app.post("/mail/:accountId/messages/send", async (c) => {
+        const accountId = c.req.param("accountId");
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        const input = validateSendInput(parsedBody.body);
+        if (!input.ok)
+            return c.json({ error: input.code, message: input.message }, 400);
+        try {
+            const result = await resolved.provider.send({ ...input.value, draftOnly: false });
+            markAgentWrite(accountId, result.id);
+            markAgentWriteRfc822(accountId, result.rfc822MsgId);
+            // Phase 5 Gmail reconcile (`inbox:7d`) keys snapshots by threadId,
+            // so threadId is the load-bearing mark for actor attribution;
+            // messageId is kept as a forward-compat second key. GmailProvider
+            // surfaces threadId from `users.messages.send`'s response; IMAP /
+            // Outlook leave it undefined and only the messageId mark lands
+            // (those providers don't drive a reconcile path today, so a missed
+            // mark there is a no-op).
+            markGmailIntegrationWrite(accountId, result.id, result.threadId);
+            return c.json({ result });
+        }
+        catch (err) {
+            return providerError(c, err, "send_failed");
+        }
+    });
+    app.post("/mail/:accountId/messages/:messageId/read", async (c) => {
+        const accountId = c.req.param("accountId");
+        const messageId = c.req.param("messageId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const body = parsedBody.body;
+        const read = body?.read;
+        if (typeof read !== "boolean") {
+            return c.json({ error: "invalid_body", message: "read: boolean required" }, 400);
+        }
+        try {
+            await resolved.provider.markRead(messageId, read);
+            markAgentWrite(accountId, messageId);
+            return c.json({ status: "updated", read });
+        }
+        catch (err) {
+            return providerError(c, err, "mark_read_failed");
+        }
+    });
+    app.post("/mail/:accountId/messages/:messageId/trash", async (c) => {
+        const accountId = c.req.param("accountId");
+        const messageId = c.req.param("messageId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        try {
+            await resolved.provider.trash(messageId);
+            markAgentWrite(accountId, messageId);
+            return c.json({ status: "trashed" });
+        }
+        catch (err) {
+            return providerError(c, err, "trash_failed");
+        }
+    });
+    app.post("/mail/:accountId/messages/:messageId/untrash", async (c) => {
+        const accountId = c.req.param("accountId");
+        const messageId = c.req.param("messageId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "untrash")) {
+            return c.json({ error: "not_implemented", message: `untrash not supported on ${resolved.provider.kind}` }, 501);
+        }
+        try {
+            await resolved.provider.untrash(messageId);
+            markAgentWrite(accountId, messageId);
+            return c.json({ status: "untrashed" });
+        }
+        catch (err) {
+            return providerError(c, err, "untrash_failed");
+        }
+    });
+    app.post("/mail/:accountId/messages/:messageId/archive", async (c) => {
+        const accountId = c.req.param("accountId");
+        const messageId = c.req.param("messageId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "archive")) {
+            return c.json({ error: "not_implemented", message: `archive not supported on ${resolved.provider.kind}` }, 501);
+        }
+        try {
+            await resolved.provider.archive(messageId);
+            markAgentWrite(accountId, messageId);
+            return c.json({ status: "archived" });
+        }
+        catch (err) {
+            return providerError(c, err, "archive_failed");
+        }
+    });
+    app.post("/mail/:accountId/messages/:messageId/tags", async (c) => {
+        const accountId = c.req.param("accountId");
+        const messageId = c.req.param("messageId");
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        const body = parsedBody.body;
+        const add = toStringArray(body?.add);
+        const remove = toStringArray(body?.remove);
+        if (!add || !remove) {
+            return c.json({ error: "invalid_body", message: "add: string[], remove: string[] required" }, 400);
+        }
+        try {
+            await resolved.provider.modifyTags(messageId, add, remove);
+            markAgentWrite(accountId, messageId);
+            return c.json({ status: "tags_updated", add, remove });
+        }
+        catch (err) {
+            return providerError(c, err, "modify_tags_failed");
+        }
+    });
+    app.get("/mail/:accountId/tags", async (c) => {
+        const accountId = c.req.param("accountId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "listTags")) {
+            // Minimal fallback: return empty catalog for providers that don't yet
+            // surface a tag list. Keeps callers from needing per-kind branching.
+            return c.json({ system: [], userDefined: [] });
+        }
+        try {
+            const catalog = await resolved.provider.listTags();
+            return c.json(catalog);
+        }
+        catch (err) {
+            return providerError(c, err, "list_tags_failed");
+        }
+    });
+    app.get("/mail/:accountId/folders", async (c) => {
+        const resolved = await resolveProvider(c.req.param("accountId"));
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        try {
+            const folders = await resolved.provider.listFolders();
+            return c.json({ folders });
+        }
+        catch (err) {
+            return providerError(c, err, "list_folders_failed");
+        }
+    });
+    app.get("/mail/:accountId/threads/:threadId", async (c) => {
+        const accountId = c.req.param("accountId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "getThread")) {
+            return c.json({ error: "not_implemented", message: `getThread not supported on ${resolved.provider.kind}` }, 501);
+        }
+        const bodyMode = parseBodyMode(c.req.query("body"));
+        if (!bodyMode.ok)
+            return c.json(bodyMode.body, 400);
+        const limit = parseIntParam(c.req.query("limit"), 25, { min: 1, max: 100 });
+        try {
+            const thread = await resolved.provider.getThread(c.req.param("threadId"), limit);
+            return c.json({ thread: applyThreadBodyMode(thread, bodyMode.value) });
+        }
+        catch (err) {
+            return providerError(c, err, "get_thread_failed");
+        }
+    });
+    app.get("/mail/:accountId/drafts", async (c) => {
+        const accountId = c.req.param("accountId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "listDrafts")) {
+            return c.json({ error: "not_implemented", message: `listDrafts not supported on ${resolved.provider.kind}` }, 501);
+        }
+        const limit = parseIntParam(c.req.query("limit"), 20, { min: 1, max: 100 });
+        try {
+            const drafts = await resolved.provider.listDrafts(limit);
+            return c.json({ drafts });
+        }
+        catch (err) {
+            return providerError(c, err, "list_drafts_failed");
+        }
+    });
+    app.get("/mail/:accountId/drafts/:draftId", async (c) => {
+        const resolved = await resolveProvider(c.req.param("accountId"));
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "getDraft")) {
+            return c.json({ error: "not_implemented", message: `getDraft not supported on ${resolved.provider.kind}` }, 501);
+        }
+        try {
+            const draft = await resolved.provider.getDraft(c.req.param("draftId"));
+            if (!draft)
+                return c.json({ error: "not_found" }, 404);
+            return c.json({ draft });
+        }
+        catch (err) {
+            return providerError(c, err, "get_draft_failed");
+        }
+    });
+    app.post("/mail/:accountId/drafts", async (c) => {
+        const accountId = c.req.param("accountId");
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "createDraft")) {
+            return c.json({ error: "not_implemented", message: `createDraft not supported on ${resolved.provider.kind}` }, 501);
+        }
+        const input = validateSendInput(parsedBody.body);
+        if (!input.ok)
+            return c.json({ error: input.code, message: input.message }, 400);
+        try {
+            const result = await resolved.provider.createDraft(input.value);
+            markAgentWrite(accountId, result.id);
+            return c.json({ draftId: result.id });
+        }
+        catch (err) {
+            return providerError(c, err, "create_draft_failed");
+        }
+    });
+    app.patch("/mail/:accountId/drafts/:draftId", async (c) => {
+        const accountId = c.req.param("accountId");
+        const draftId = c.req.param("draftId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "updateDraft")) {
+            return c.json({ error: "not_implemented", message: `updateDraft not supported on ${resolved.provider.kind}` }, 501);
+        }
+        const parsedBody = await readJsonBody(c);
+        if (!parsedBody.ok)
+            return parsedBody.response;
+        const input = validateUpdateDraftInput(parsedBody.body);
+        if (!input.ok)
+            return c.json({ error: input.code, message: input.message }, 400);
+        try {
+            const result = await resolved.provider.updateDraft(draftId, input.value);
+            markAgentWrite(accountId, result.id);
+            if (result.previousId)
+                markAgentWrite(accountId, result.previousId);
+            // `warnings` surface provider-specific caveats (e.g. Outlook's
+            // reply-threading immutability). Agents need to see them — dropping
+            // them would make the UpdateDraftResult.warnings field a no-op.
+            return c.json({
+                status: "updated",
+                id: result.id,
+                previousId: result.previousId,
+                warnings: result.warnings,
+            });
+        }
+        catch (err) {
+            return providerError(c, err, "update_draft_failed");
+        }
+    });
+    app.delete("/mail/:accountId/drafts/:draftId", async (c) => {
+        const accountId = c.req.param("accountId");
+        const draftId = c.req.param("draftId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "deleteDraft")) {
+            return c.json({ error: "not_implemented", message: `deleteDraft not supported on ${resolved.provider.kind}` }, 501);
+        }
+        try {
+            await resolved.provider.deleteDraft(draftId);
+            markAgentWrite(accountId, draftId);
+            return c.json({ status: "deleted" });
+        }
+        catch (err) {
+            return providerError(c, err, "delete_draft_failed");
+        }
+    });
+    app.post("/mail/:accountId/drafts/:draftId/send", async (c) => {
+        const accountId = c.req.param("accountId");
+        const draftId = c.req.param("draftId");
+        const resolved = await resolveProvider(accountId);
+        if (!resolved.ok)
+            return renderResolveError(c, resolved);
+        if (!ensureMethod(resolved.provider, "sendDraft")) {
+            return c.json({ error: "not_implemented", message: `sendDraft not supported on ${resolved.provider.kind}` }, 501);
+        }
+        try {
+            const result = await resolved.provider.sendDraft(draftId);
+            markAgentWrite(accountId, result.id);
+            // sendDraft is a surface-area subset of send(); if the provider
+            // surfaces the rfc822 Message-Id, it flows through the same field.
+            const rfc = result.rfc822MsgId;
+            markAgentWriteRfc822(accountId, rfc);
+            markGmailIntegrationWrite(accountId, result.id, result.threadId);
+            return c.json({ status: "sent", id: result.id, threadId: result.threadId });
+        }
+        catch (err) {
+            return providerError(c, err, "send_draft_failed");
+        }
+    });
+    return app;
+}
+function getErrorResponseCode(err) {
+    const candidate = err?.responseCode;
+    return typeof candidate === "number" ? candidate : null;
+}
+// ImapFlow sets err.message to the generic "Command failed" and puts the
+// actual IMAP server response code in serverResponseCode (e.g. "AUTHENTICATIONFAILED")
+// and the human text in responseText. Concatenate all three so that the
+// classifyImapAuthFailure patterns can match the real server response.
+function getImapErrorMessage(err) {
+    if (!(err instanceof Error))
+        return String(err);
+    const e = err;
+    return [err.message, e.serverResponseCode, e.responseText].filter(Boolean).join(" ");
+}
+function parseIntParam(raw, fallback, bounds) {
+    if (!raw)
+        return fallback;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n))
+        return fallback;
+    return Math.max(bounds.min, Math.min(bounds.max, n));
+}
+function toStringArray(value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        return null;
+    if (value.every((v) => typeof v === "string"))
+        return value;
+    return null;
+}
+function buildMailBodyResponse(input) {
+    const { message, format, chunk, maxChars, metadataOffset, metadataLimit } = input;
+    const resolved = resolveMailBody(message, format);
+    const totalChars = resolved.content.length;
+    const start = chunk * maxChars;
+    const end = start + maxChars;
+    const content = start < totalChars ? resolved.content.slice(start, end) : "";
+    const hasMore = end < totalChars;
+    const links = resolved.links.slice(metadataOffset, metadataOffset + metadataLimit);
+    const images = resolved.images.slice(metadataOffset, metadataOffset + metadataLimit);
+    const linksHasMore = metadataOffset + metadataLimit < resolved.links.length;
+    const imagesHasMore = metadataOffset + metadataLimit < resolved.images.length;
+    return {
+        accountId: input.accountId,
+        providerMsgId: message.providerMsgId,
+        rfc822MsgId: message.rfc822MsgId,
+        threadId: message.threadId,
+        subject: message.subject,
+        format,
+        source: resolved.source,
+        content,
+        chunk,
+        maxChars,
+        totalChars,
+        hasMore,
+        nextChunk: hasMore ? chunk + 1 : null,
+        rawHtmlAvailable: typeof message.body.html === "string" && message.body.html.length > 0,
+        rawTextAvailable: typeof message.body.text === "string" && message.body.text.length > 0,
+        metadataOffset,
+        metadataLimit,
+        links,
+        images,
+        linkCount: resolved.links.length,
+        imageCount: resolved.images.length,
+        linksHasMore,
+        imagesHasMore,
+        nextMetadataOffset: linksHasMore || imagesHasMore
+            ? metadataOffset + metadataLimit
+            : null,
+    };
+}
+function resolveMailBody(message, format) {
+    const html = message.body.html;
+    const text = message.body.text;
+    if (format === "raw") {
+        if (html)
+            return { content: html, source: "html", links: [], images: [] };
+        if (text)
+            return { content: text, source: "text", links: [], images: [] };
+        return { content: "", source: "empty", links: [], images: [] };
+    }
+    if (html) {
+        const extracted = extractMailHtmlBody(html);
+        return {
+            content: renderExtractedMailHtmlBody(extracted),
+            source: "html",
+            links: extracted.links,
+            images: extracted.images,
+        };
+    }
+    if (text)
+        return { content: text, source: "text", links: [], images: [] };
+    return { content: "", source: "empty", links: [], images: [] };
+}
+function parseBodyMode(raw) {
+    if (raw === undefined || raw === "full")
+        return { ok: true, value: "full" };
+    if (raw === "none")
+        return { ok: true, value: "none" };
+    return {
+        ok: false,
+        body: { error: "invalid_query", message: "body must be full or none" },
+    };
+}
+function applyMailMessageBodyMode(message, mode) {
+    if (mode === "full")
+        return message;
+    return { ...message, body: {} };
+}
+function applyThreadBodyMode(thread, mode) {
+    if (mode === "full")
+        return thread;
+    return {
+        ...thread,
+        messages: thread.messages.map((message) => applyMailMessageBodyMode(message, mode)),
+    };
+}
+function providerError(c, err, tag) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Classify common provider errors where a 404 from the backend should not
+    // become a 500 for the caller. The Graph client throws GraphError with a
+    // httpStatus field; the IMAP layer throws Error with a responseCode.
+    const candidate = err;
+    const status = pickNumber(candidate.httpStatus) ??
+        pickNumber(candidate.statusCode) ??
+        pickNumber(candidate.response?.status);
+    if (status === 404) {
+        return c.json({ error: "not_found", message }, 404);
+    }
+    if (status === 501) {
+        // Providers throw MailOperationNotSupportedError (httpStatus=501) when a
+        // sub-case of an implemented method is out of scope — e.g. IMAP draft
+        // writes. Map to the same shape as the missing-method-on-interface path
+        // so callers can't distinguish the two (both mean "don't retry here").
+        return c.json({ error: "not_implemented", message }, 501);
+    }
+    if (status === 401 || status === 403) {
+        return c.json({ error: "provider_auth_error", message }, 502);
+    }
+    logger.error({ err, tag }, `mail route failure: ${tag}`);
+    return c.json({ error: tag, message }, 500);
+}
+function pickNumber(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function validateSendInput(body) {
+    const raw = body;
+    const to = toStringArray(raw?.to);
+    if (!to || to.length === 0) {
+        return { ok: false, code: "invalid_body", message: "to: non-empty string[] required" };
+    }
+    if (typeof raw.subject !== "string") {
+        return { ok: false, code: "invalid_body", message: "subject: string required" };
+    }
+    const cc = raw.cc === undefined ? undefined : toStringArray(raw.cc);
+    const bcc = raw.bcc === undefined ? undefined : toStringArray(raw.bcc);
+    if (cc === null || bcc === null) {
+        return { ok: false, code: "invalid_body", message: "cc/bcc must be string[] when present" };
+    }
+    const reply = parseReplyContext(raw.reply);
+    if (reply === "invalid") {
+        return {
+            ok: false,
+            code: "invalid_body",
+            message: "reply requires inReplyToRfc822Id (string) and references (string[])",
+        };
+    }
+    return {
+        ok: true,
+        value: {
+            to,
+            cc,
+            bcc,
+            subject: raw.subject,
+            textBody: typeof raw.textBody === "string" ? raw.textBody : undefined,
+            htmlBody: typeof raw.htmlBody === "string" ? raw.htmlBody : undefined,
+            reply,
+            // `draftOnly` is intentionally NOT surfaced at the route boundary.
+            // Drafts go through POST /mail/:id/drafts (Autonomous tier); sends
+            // go through POST /mail/:id/messages/send (Notify tier). Body flags
+            // cannot be classified by the path-prefix risk classifier.
+        },
+    };
+}
+function parseReplyContext(raw) {
+    if (raw === undefined || raw === null)
+        return undefined;
+    if (typeof raw !== "object")
+        return "invalid";
+    const r = raw;
+    if (typeof r.inReplyToRfc822Id !== "string")
+        return "invalid";
+    const refs = toStringArray(r.references);
+    if (!refs)
+        return "invalid";
+    return {
+        inReplyToRfc822Id: r.inReplyToRfc822Id,
+        references: refs,
+        providerThreadId: typeof r.providerThreadId === "string" ? r.providerThreadId : undefined,
+        parentProviderMsgId: typeof r.parentProviderMsgId === "string" ? r.parentProviderMsgId : undefined,
+    };
+}
+function validateUpdateDraftInput(body) {
+    const raw = body;
+    const to = raw.to === undefined ? undefined : toStringArray(raw.to);
+    const cc = raw.cc === undefined ? undefined : toStringArray(raw.cc);
+    const bcc = raw.bcc === undefined ? undefined : toStringArray(raw.bcc);
+    if (to === null || cc === null || bcc === null) {
+        return { ok: false, code: "invalid_body", message: "to/cc/bcc must be string[] when present" };
+    }
+    // `reply` tri-state: undefined = leave existing threading; null = clear;
+    // object = reshape (must include inReplyToRfc822Id + references).
+    let reply;
+    if (raw.reply === null) {
+        reply = null;
+    }
+    else if (raw.reply !== undefined) {
+        const parsed = parseReplyContext(raw.reply);
+        if (parsed === "invalid") {
+            return {
+                ok: false,
+                code: "invalid_body",
+                message: "reply requires inReplyToRfc822Id (string) and references (string[]); pass null to clear",
+            };
+        }
+        reply = parsed;
+    }
+    return {
+        ok: true,
+        value: {
+            to,
+            cc,
+            bcc,
+            subject: typeof raw.subject === "string" ? raw.subject : undefined,
+            textBody: typeof raw.textBody === "string" ? raw.textBody : undefined,
+            htmlBody: typeof raw.htmlBody === "string" ? raw.htmlBody : undefined,
+            reply,
+        },
+    };
+}
+//# sourceMappingURL=mail.js.map