@aitne/daemon 0.1.7 → 0.1.9

package/dist/api/routes/mail/app-password.js

@@ -0,0 +1,191 @@
+import { createLogger } from "../../../logging.js";
+import { readJsonBody } from "../../json-body.js";
+import { composeIssue, respondWithAgentError } from "../../helpers/agent-errors.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 { DuplicateAccountError, ProviderNotImplementedError, } from "../../../services/mail/account-registry.js";
+const logger = createLogger("mail-api");
+export function registerAppPasswordRoutes(app, deps) {
+    const verifyImapCredentials = deps.verifyImapAccountSecret ?? verifyImapAccountSecret;
+    app.post("/config/mail/app-password", async (c) => {
+        const registry = deps.services.mail;
+        if (!registry) {
+            return respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
+        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 respondWithAgentError(c, 503, [
+                composeIssue("mail.not_configured", {
+                    field: "services.mail",
+                    received: "<unavailable>",
+                }),
+            ]);
+        }
+        const accountId = c.req.param("accountId");
+        const account = registry.getAccount(accountId);
+        if (!account) {
+            return respondWithAgentError(c, 404, [
+                composeIssue("mail.account_not_found", {
+                    field: "accountId",
+                    received: accountId,
+                }),
+            ]);
+        }
+        if (account.kind !== "yahoo" && account.kind !== "icloud") {
+            return respondWithAgentError(c, 400, [
+                composeIssue("mail.unsupported_kind", {
+                    field: "account.kind",
+                    received: account.kind,
+                    hint: "App-password refresh only supports yahoo / icloud. Outlook re-authenticates via the OAuth loopback flow.",
+                }),
+            ], { legacyFields: { message: "App-password refresh only supports yahoo / icloud. Outlook re-authenticates via the OAuth loopback flow." } });
+        }
+        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 respondWithAgentError(c, 404, [
+                    composeIssue("mail.account_not_found", {
+                        field: "accountId",
+                        received: accountId,
+                    }),
+                ]);
+            }
+            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);
+        }
+    });
+}
+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(" ");
+}

package/dist/api/routes/mail/body-helpers.d.ts

@@ -0,0 +1,55 @@
+import type { MailMessage, ThreadView } from "../../../services/mail/provider.js";
+import { type ExtractedMailHtmlImage, type ExtractedMailHtmlLink } from "../../../services/mail/html-to-plaintext.js";
+export declare const MAIL_BODY_CHUNK_DEFAULT_CHARS = 12000;
+export declare const MAIL_BODY_CHUNK_MAX_CHARS = 50000;
+export declare const MAIL_BODY_METADATA_DEFAULT_LIMIT = 100;
+export declare const MAIL_BODY_METADATA_MAX_LIMIT = 500;
+export type MailBodyFormat = "extracted" | "raw";
+export type MailBodySource = "html" | "text" | "empty";
+export type MailBodyMode = "full" | "none";
+export declare function buildMailBodyResponse(input: {
+    accountId: string;
+    message: MailMessage;
+    format: MailBodyFormat;
+    chunk: number;
+    maxChars: number;
+    metadataOffset: number;
+    metadataLimit: number;
+}): {
+    accountId: string;
+    providerMsgId: string;
+    rfc822MsgId: string | null;
+    threadId: string | null;
+    subject: string | null;
+    format: MailBodyFormat;
+    source: MailBodySource;
+    content: string;
+    chunk: number;
+    maxChars: number;
+    totalChars: number;
+    hasMore: boolean;
+    nextChunk: number | null;
+    rawHtmlAvailable: boolean;
+    rawTextAvailable: boolean;
+    metadataOffset: number;
+    metadataLimit: number;
+    links: ExtractedMailHtmlLink[];
+    images: ExtractedMailHtmlImage[];
+    linkCount: number;
+    imageCount: number;
+    linksHasMore: boolean;
+    imagesHasMore: boolean;
+    nextMetadataOffset: number | null;
+};
+export declare function parseBodyMode(raw: string | undefined): {
+    ok: true;
+    value: MailBodyMode;
+} | {
+    ok: false;
+    body: {
+        error: string;
+        message: string;
+    };
+};
+export declare function applyMailMessageBodyMode(message: MailMessage, mode: MailBodyMode): MailMessage;
+export declare function applyThreadBodyMode(thread: ThreadView, mode: MailBodyMode): ThreadView;

package/dist/api/routes/mail/body-helpers.js

@@ -0,0 +1,90 @@
+import { extractMailHtmlBody, renderExtractedMailHtmlBody, } from "../../../services/mail/html-to-plaintext.js";
+export const MAIL_BODY_CHUNK_DEFAULT_CHARS = 12_000;
+export const MAIL_BODY_CHUNK_MAX_CHARS = 50_000;
+export const MAIL_BODY_METADATA_DEFAULT_LIMIT = 100;
+export const MAIL_BODY_METADATA_MAX_LIMIT = 500;
+export 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: [] };
+}
+export 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" },
+    };
+}
+export function applyMailMessageBodyMode(message, mode) {
+    if (mode === "full")
+        return message;
+    return { ...message, body: {} };
+}
+export function applyThreadBodyMode(thread, mode) {
+    if (mode === "full")
+        return thread;
+    return {
+        ...thread,
+        messages: thread.messages.map((message) => applyMailMessageBodyMode(message, mode)),
+    };
+}

package/dist/api/routes/mail/dependencies.d.ts

@@ -0,0 +1,35 @@
+import type Database from "better-sqlite3";
+import type { AgentConfig } from "../../../config.js";
+import type { ServiceRegistry } from "../../../services/service-registry.js";
+import type { SettingsStore } from "../../../settings/settings-store.js";
+import type { AgentWriteTracker } from "../../../safety/agent-write-tracker.js";
+import type { EncryptedBlobStore } from "../../../secrets/encrypted-blob-store.js";
+import type { ImapAccountSecret } from "../../../services/mail/imap/app-password.js";
+import type { verifyImapAccountSecret } from "../../../services/mail/imap/client.js";
+export interface MailRouteDependencies {
+    db: Database.Database;
+    config: AgentConfig;
+    services: ServiceRegistry;
+    /**
+     * Required to read/write the Outlook BYOA client config blob and to support
+     * future provider blobs. Optional only because Phase 1 routes that don't
+     * touch blobs would still work without it; Phase 2 routes return 503 when
+     * absent.
+     */
+    blobStore?: EncryptedBlobStore;
+    settingsStore?: SettingsStore;
+    verifyImapAccountSecret?: (secret: ImapAccountSecret) => Promise<Awaited<ReturnType<typeof verifyImapAccountSecret>>>;
+    /**
+     * Shared write tracker — used by send/modify/trash routes so the unified
+     * mail-poller suppresses messages the agent just touched (§3.2). Optional
+     * for tests that construct mail routes in isolation.
+     */
+    writeTracker?: AgentWriteTracker;
+    /**
+     * Fired when the set of enabled mail providers or active accounts changes
+     * (toggle, remove, re-consent). Optional; the daemon wires this to wake up
+     * the unified poller so new accounts start being observed immediately
+     * without waiting for the next scheduled tick.
+     */
+    onMailScopeChanged?: (reason: string) => void;
+}

package/dist/api/routes/mail/dependencies.js

@@ -0,0 +1 @@
+export {};

package/dist/api/routes/mail/drafts.d.ts

@@ -0,0 +1,4 @@
+import type { Hono } from "hono";
+import { type ProviderResolver } from "./provider-resolver.js";
+import type { MailRouteDependencies } from "./dependencies.js";
+export declare function registerDraftsRoutes(app: Hono, _deps: MailRouteDependencies, resolver: ProviderResolver): void;

package/dist/api/routes/mail/drafts.js

@@ -0,0 +1,138 @@
+import { readJsonBody } from "../../json-body.js";
+import { notImplementedResponse, providerError, } from "./provider-resolver.js";
+import { parseIntParam, validateSendInput, validateUpdateDraftInput, } from "./validators.js";
+export function registerDraftsRoutes(app, _deps, resolver) {
+    const { resolveProvider, renderResolveError, ensureMethod, markAgentWrite, markAgentWriteRfc822, markGmailIntegrationWrite, } = resolver;
+    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 notImplementedResponse(c, "listDrafts", resolved.provider.kind);
+        }
+        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 notImplementedResponse(c, "getDraft", resolved.provider.kind);
+        }
+        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 notImplementedResponse(c, "createDraft", resolved.provider.kind);
+        }
+        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 notImplementedResponse(c, "updateDraft", resolved.provider.kind);
+        }
+        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 notImplementedResponse(c, "deleteDraft", resolved.provider.kind);
+        }
+        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 notImplementedResponse(c, "sendDraft", resolved.provider.kind);
+        }
+        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");
+        }
+    });
+}

package/dist/api/routes/mail/gating.d.ts

@@ -0,0 +1,44 @@
+import { type IntegrationKey } from "@aitne/shared";
+import type { MailProviderKind } from "../../../services/mail/provider.js";
+export declare const ALL_KINDS: readonly MailProviderKind[];
+export declare const PROVIDER_LABELS: Record<MailProviderKind, string>;
+/**
+ * Maps a mail provider kind to the `IntegrationKey` whose mode gates that
+ * kind under the §4.8 per-account delegated rule. Kinds outside the
+ * registry return null — iCloud, Yahoo, and generic IMAP are direct-only
+ * by design and never enter the delegated surface.
+ */
+export type MailGatedIntegrationKey = Extract<IntegrationKey, "gmail" | "outlook_mail">;
+export declare function gatedIntegrationForKind(kind: MailProviderKind): MailGatedIntegrationKey | null;
+export declare function delegatedMailIntegrationMessage(key: MailGatedIntegrationKey, delegatedBackend: string | null | undefined): string;
+/**
+ * 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.
+ */
+export declare function gatedMailIntegrationResponse(key: MailGatedIntegrationKey, state: {
+    mode: string;
+    delegatedBackend?: string | null;
+    nativeBackend?: string | null;
+}): {
+    error: "integration_delegated" | "integration_native";
+    message: string;
+    integration: MailGatedIntegrationKey;
+    backend: string | null;
+    mode: "delegated" | "native";
+} | null;

package/dist/api/routes/mail/gating.js

@@ -0,0 +1,98 @@
+import { INTEGRATION_DESCRIPTORS, } from "@aitne/shared";
+export const ALL_KINDS = [
+    "gmail",
+    "outlook",
+    "yahoo",
+    "icloud",
+];
+export const PROVIDER_LABELS = {
+    gmail: "Gmail",
+    outlook: "Outlook",
+    yahoo: "Yahoo Mail",
+    icloud: "iCloud Mail",
+};
+export function gatedIntegrationForKind(kind) {
+    if (kind === "gmail")
+        return "gmail";
+    if (kind === "outlook")
+        return "outlook_mail";
+    return null;
+}
+export 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
+    // any daemon-side `/exec` chokepoint (or the retired `/invoke` RPC)
+    // would be a lie because no such proxy exists for user-managed keys.
+    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}/exec (task-mode chokepoint; the legacy /invoke RPC was retired 2026-05-01).`,
+        `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.
+ */
+export 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;
+}