@aitne/daemon 0.1.7 → 0.1.9

package/dist/api/routes/mail.js

@@ -1,1472 +0,0 @@
-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 { 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(" ");
-}
-/**
- * INTEGRATION_NATIVE_MODE_DESIGN.md §9.2 — `/api/mail/*` cannot be
- * prefix-gated by `integration-route-gate.ts` because it is
- * multi-provider; the gated kinds (Gmail, Outlook) get a per-account
- * 410 inside the handler. This helper produces the body for
- * `delegated` and `native` modes (the two daemonless modes that have
- * an explicit redirect target — the user's MCP). `disabled` is
- * intentionally NOT gated here: the integration map defaults to
- * `disabled`, and a fresh install with Gmail/Outlook accounts already
- * provisioned would otherwise 410 their entire `/api/mail/*` surface
- * before the user has even visited the mode picker. The integration
- * registry's poller filter handles the `disabled` case at the data
- * path; the route-level 410 for disabled is reserved for the
- * centralised middleware where `apiRoutesTouched` declares prefix
- * coverage.
- *
- * The error codes mirror the centralised middleware's vocabulary so
- * dashboards can branch on the same string regardless of which gate
- * fired.
- */
-function gatedMailIntegrationResponse(key, state) {
-    const descriptor = INTEGRATION_DESCRIPTORS[key];
-    const displayName = descriptor.displayName;
-    if (state.mode === "delegated") {
-        return {
-            error: "integration_delegated",
-            message: delegatedMailIntegrationMessage(key, state.delegatedBackend ?? null),
-            integration: key,
-            backend: state.delegatedBackend ?? null,
-            mode: "delegated",
-        };
-    }
-    if (state.mode === "native") {
-        const nb = state.nativeBackend ?? null;
-        // User-managed integrations (Outlook) point at the user's installed
-        // MCP; descriptor-driven (Gmail) point at the backend's hosted
-        // connector and the SKILL.native.<backend>.md body. Mirrors the
-        // central route gate's branching so the agent gets symmetric copy
-        // whether the request hits a prefix-gated route or a multi-provider
-        // route.
-        const message = descriptor.userManagedConnector
-            ? `${displayName} is in native mode (bound to ${nb ?? "main backend"}). The agent backend is expected to use the user-installed ${displayName} MCP / connector tools — the daemon does not poll and does not expose a proxy for this integration. Other mail accounts remain available through /api/mail/*.`
-            : `${displayName} is in native mode (bound to ${nb ?? "main backend"}). Use the backend's native MCP tools (see the SKILL.native.${nb ?? "<backend>"}.md body); the daemon does not poll and does not expose a proxy for this integration. Other mail accounts remain available through /api/mail/*.`;
-        return {
-            error: "integration_native",
-            message,
-            integration: key,
-            backend: nb,
-            mode: "native",
-        };
-    }
-    return null;
-}
-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 mode gate for search — if the caller pins the
-        // query to a Gmail / Outlook account whose integration is in
-        // `delegated` or `native` mode, 410. The unscoped cross-account
-        // search path stays open; results for a gated account would just
-        // be stale FTS hits (live polling is off in both modes), which is
-        // acceptable for Phase 2 and documented in §4.4. Per
-        // INTEGRATION_NATIVE_MODE_DESIGN.md §9.2 the gate widened from
-        // delegated-only to cover native too so the agent gets a consistent
-        // redirect signal when Outlook is flipped to native (user-managed
-        // MCP) or Gmail's native binding is in play. `disabled` is not
-        // gated here — see `gatedMailIntegrationResponse` doc-comment.
-        if (accountId) {
-            const account = deps.services.mail?.getAccount(accountId);
-            if (account) {
-                const gatedIntegrationKey = gatedIntegrationForKind(account.kind);
-                if (gatedIntegrationKey) {
-                    const state = readIntegrations(deps.db)[gatedIntegrationKey];
-                    const gateResponse = gatedMailIntegrationResponse(gatedIntegrationKey, state);
-                    if (gateResponse !== null) {
-                        return c.json(gateResponse, 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 mode 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 gated integration (Gmail → gmail; Outlook → outlook_mail)
-        // return 410 when that integration is in `delegated` or `native`
-        // mode. Per INTEGRATION_NATIVE_MODE_DESIGN.md §9.2 the gate widened
-        // from delegated-only so the agent gets a consistent redirect
-        // signal when Outlook is flipped to native (user-managed MCP).
-        // `disabled` accounts are filtered at the data path (poller) — see
-        // `gatedMailIntegrationResponse` for why we do not gate them here.
-        const gatedIntegrationKey = gatedIntegrationForKind(account.kind);
-        if (gatedIntegrationKey) {
-            const state = readIntegrations(deps.db)[gatedIntegrationKey];
-            const gateResponse = gatedMailIntegrationResponse(gatedIntegrationKey, state);
-            if (gateResponse !== null) {
-                return {
-                    ok: false,
-                    status: 410,
-                    code: gateResponse.error,
-                    message: gateResponse.message,
-                    integration: gateResponse.integration,
-                    backend: gateResponse.backend,
-                    mode: gateResponse.mode,
-                };
-            }
-        }
-        // 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;
-        /* c8 ignore next */ if (!registry)
-            return;
-        const account = registry.getAccount(accountId);
-        /* c8 ignore next */ 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 / §9.2 body shape (integration, backend,
-     * mode) so the dashboard and agent tooling can uniformly detect a
-     * gated-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 + §9.2 native widening). The mode field carries through from
-     * `gatedMailIntegrationResponse`; falling back to "delegated"
-     * preserves the legacy shape for any 410 outcomes that pre-dated the
-     * native widening.
-     */
-    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: resolved.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 mode gate — also applies to /health so the
-        // dashboard does not surface a stale poll cursor for an account
-        // whose integration the daemon has stopped touching (delegated /
-        // native). `disabled` is intentionally not gated here so the dash
-        // can still surface the last-known cursor while the user is
-        // mid-reconfigure. 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) {
-                const state = readIntegrations(deps.db)[gatedIntegrationKey];
-                const gateResponse = gatedMailIntegrationResponse(gatedIntegrationKey, state);
-                if (gateResponse !== null) {
-                    return c.json(gateResponse, 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