@rubytech/create-maxy-code 0.1.0

package/payload/platform/plugins/email/mcp/dist/tools/email-search.js

@@ -0,0 +1,63 @@
+import { loadCredentials } from "../lib/credentials.js";
+import { searchMessages, MAX_LIMIT } from "../lib/imap.js";
+import { getThreadInfo, stripAngleBrackets } from "../lib/graph.js";
+export async function emailSearch(params) {
+    const result = await loadCredentials(params.accountId);
+    if ("error" in result)
+        throw new Error(result.error);
+    const { config, password } = result.credentials;
+    // Clamp limit to hard cap — silently, per spec
+    const requestedLimit = Math.max(1, params.limit ?? 20);
+    const limit = Math.min(requestedLimit, MAX_LIMIT);
+    // Use agent address for TO filtering when alias is configured
+    // Coerce empty string to undefined to avoid matching nothing silently
+    const to = (params.to || undefined) ?? (config.agentAddress !== config.email ? config.agentAddress : undefined);
+    const { messages, nextBeforeUid } = await searchMessages(config, password, {
+        sender: params.sender,
+        subject: params.subject,
+        body: params.body,
+        since: params.since ? new Date(params.since) : undefined,
+        before: params.before ? new Date(params.before) : undefined,
+        limit,
+        to,
+        folder: params.folder,
+        beforeUid: params.before_uid,
+    });
+    if (messages.length === 0) {
+        return "No messages match the search criteria.";
+    }
+    // Enrich with thread info from the graph (best-effort — failures return empty map)
+    const messageIds = messages.map((m) => m.messageId).filter((id) => !!id);
+    let threadMap = new Map();
+    try {
+        threadMap = await getThreadInfo(messageIds, params.accountId);
+    }
+    catch {
+        // Thread enrichment is optional — continue without it
+    }
+    const lines = messages
+        .map((m) => {
+        let entry = `UID: ${m.uid}\nFrom: ${m.from}\nSubject: ${m.subject}\nDate: ${m.date}`;
+        if (m.messageId)
+            entry += `\nMessage-ID: ${m.messageId}`;
+        if (m.inReplyTo)
+            entry += `\nIn-Reply-To: ${m.inReplyTo}`;
+        const normalisedMid = stripAngleBrackets(m.messageId);
+        if (normalisedMid) {
+            const thread = threadMap.get(normalisedMid);
+            if (thread) {
+                entry += `\nThread-Depth: ${thread.threadDepth}`;
+                entry += `\nThread-ID: ${thread.threadId}`;
+            }
+        }
+        if (m.bodyPreview)
+            entry += `\n\n${m.bodyPreview}`;
+        return entry + "\n---";
+    })
+        .join("\n\n");
+    if (nextBeforeUid) {
+        return `${lines}\n\nPagination: next_before_uid=${nextBeforeUid} (pass as before_uid to get older messages)`;
+    }
+    return lines;
+}
+//# sourceMappingURL=email-search.js.map

package/payload/platform/plugins/email/mcp/dist/tools/email-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-search.js","sourceRoot":"","sources":["../../src/tools/email-search.ts"],"names":[],"mappings":"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"}

package/payload/platform/plugins/email/mcp/dist/tools/email-send.d.ts

@@ -0,0 +1,10 @@
+interface SendParams {
+    accountId: string;
+    to: string;
+    subject: string;
+    body: string;
+    html?: string;
+}
+export declare function emailSend(params: SendParams): Promise<string>;
+export {};
+//# sourceMappingURL=email-send.d.ts.map

package/payload/platform/plugins/email/mcp/dist/tools/email-send.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-send.d.ts","sourceRoot":"","sources":["../../src/tools/email-send.ts"],"names":[],"mappings":"AAGA,UAAU,UAAU;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,wBAAsB,SAAS,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CA8BnE"}

package/payload/platform/plugins/email/mcp/dist/tools/email-send.js

@@ -0,0 +1,31 @@
+import { loadCredentials } from "../lib/credentials.js";
+import { sendEmail } from "../lib/smtp.js";
+export async function emailSend(params) {
+    const result = await loadCredentials(params.accountId);
+    if ("error" in result)
+        throw new Error(result.error);
+    const { config, password } = result.credentials;
+    try {
+        // Append AI provenance disclosure (EU AI Act Code of Practice)
+        const bodyWithDisclosure = params.body + "\n\n---\nThis message was generated by AI.";
+        const htmlWithDisclosure = params.html
+            ? params.html + '<br/><hr style="margin-top:20px;border:none;border-top:1px solid #ccc;"/><p style="color:#888;font-size:12px;">This message was generated by AI.</p>'
+            : undefined;
+        const { messageId } = await sendEmail(config, password, {
+            to: params.to,
+            subject: params.subject,
+            body: bodyWithDisclosure,
+            html: htmlWithDisclosure,
+            headers: { "X-AI-Generated": "true" },
+        });
+        return `Email sent to ${params.to} (Message-ID: ${messageId})`;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (config.agentAddress !== config.email) {
+            throw new Error(`${msg} — Note: sending as ${config.agentAddress} (authenticated as ${config.email}). If your provider doesn't allow sending as this alias, check your catchall or alias settings.`);
+        }
+        throw err;
+    }
+}
+//# sourceMappingURL=email-send.js.map

package/payload/platform/plugins/email/mcp/dist/tools/email-send.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-send.js","sourceRoot":"","sources":["../../src/tools/email-send.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAU3C,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,MAAkB;IAChD,MAAM,MAAM,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,OAAO,IAAI,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAErD,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,CAAC,WAAW,CAAC;IAEhD,IAAI,CAAC;QACH,+DAA+D;QAC/D,MAAM,kBAAkB,GAAG,MAAM,CAAC,IAAI,GAAG,4CAA4C,CAAC;QACtF,MAAM,kBAAkB,GAAG,MAAM,CAAC,IAAI;YACpC,CAAC,CAAC,MAAM,CAAC,IAAI,GAAG,sJAAsJ;YACtK,CAAC,CAAC,SAAS,CAAC;QAEd,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,SAAS,CAAC,MAAM,EAAE,QAAQ,EAAE;YACtD,EAAE,EAAE,MAAM,CAAC,EAAE;YACb,OAAO,EAAE,MAAM,CAAC,OAAO;YACvB,IAAI,EAAE,kBAAkB;YACxB,IAAI,EAAE,kBAAkB;YACxB,OAAO,EAAE,EAAE,gBAAgB,EAAE,MAAM,EAAE;SACtC,CAAC,CAAC;QACH,OAAO,iBAAiB,MAAM,CAAC,EAAE,iBAAiB,SAAS,GAAG,CAAC;IACjE,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC7D,IAAI,MAAM,CAAC,YAAY,KAAK,MAAM,CAAC,KAAK,EAAE,CAAC;YACzC,MAAM,IAAI,KAAK,CACb,GAAG,GAAG,uBAAuB,MAAM,CAAC,YAAY,sBAAsB,MAAM,CAAC,KAAK,iGAAiG,CACpL,CAAC;QACJ,CAAC;QACD,MAAM,GAAG,CAAC;IACZ,CAAC;AACH,CAAC"}

package/payload/platform/plugins/email/mcp/dist/tools/email-setup.d.ts

@@ -0,0 +1,22 @@
+interface SetupParams {
+    email: string;
+    password: string;
+    agentAddress?: string;
+    agentSlug?: string;
+    pollIntervalMinutes?: number;
+    imapHost?: string;
+    imapPort?: number;
+    imapSecurity?: "tls" | "starttls";
+    smtpHost?: string;
+    smtpPort?: number;
+    smtpSecurity?: "tls" | "starttls";
+    accountId: string;
+}
+export declare function emailSetup(params: SetupParams): Promise<{
+    success: boolean;
+    message: string;
+    inboxCount?: number;
+    providerNotes?: string;
+}>;
+export {};
+//# sourceMappingURL=email-setup.d.ts.map

package/payload/platform/plugins/email/mcp/dist/tools/email-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-setup.d.ts","sourceRoot":"","sources":["../../src/tools/email-setup.ts"],"names":[],"mappings":"AAsEA,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IAClC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,KAAK,GAAG,UAAU,CAAC;IAClC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,UAAU,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC;IAC7D,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC,CA8HD"}

package/payload/platform/plugins/email/mcp/dist/tools/email-setup.js

@@ -0,0 +1,183 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { writeConfig, writePassword, removeConfig, checkAddressBinding, writeBindingConfig, } from "../lib/credentials.js";
+import { inferProvider, getProviderNotes } from "../lib/providers.js";
+import * as imap from "../lib/imap.js";
+import * as smtp from "../lib/smtp.js";
+/**
+ * Ensures email cron jobs (email-fetch, email-auto-respond) are registered.
+ * Called after successful email setup so polling starts immediately —
+ * no reinstall or service restart required.
+ *
+ * If the installer already registered the crons (via the brand crons block),
+ * this is a no-op. Handles the case where email is configured on a device
+ * that predates the installer cron registration fix.
+ */
+function ensureEmailCrons(accountId) {
+    try {
+        const listResult = spawnSync("crontab", ["-l"], {
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        const existing = listResult.status === 0 ? listResult.stdout : "";
+        // If email-fetch is already in the crontab, nothing to do
+        if (existing.includes("email-fetch")) {
+            return { registered: true };
+        }
+        // Derive paths from the MCP server's environment
+        const platformRoot = process.env.PLATFORM_ROOT ?? resolve(import.meta.dirname, "../../../..");
+        const nodeBin = (() => {
+            try {
+                return execFileSync("which", ["node"], { encoding: "utf-8" }).trim();
+            }
+            catch {
+                return "/usr/bin/node";
+            }
+        })();
+        const logDir = resolve(homedir(), ".maxy/logs");
+        const cronEntries = [
+            `* * * * * mkdir -p ${logDir} && PLATFORM_ROOT=${platformRoot} ACCOUNT_ID=${accountId} ${nodeBin} ${platformRoot}/plugins/email/mcp/dist/scripts/email-fetch.js >> ${logDir}/email-fetch.log 2>&1`,
+            `* * * * * mkdir -p ${logDir} && PLATFORM_ROOT=${platformRoot} ${nodeBin} ${platformRoot}/plugins/email/mcp/dist/scripts/email-auto-respond.js >> ${logDir}/email-auto-respond.log 2>&1`,
+        ];
+        const newCrontab = existing.trimEnd()
+            ? `${existing.trimEnd()}\n${cronEntries.join("\n")}\n`
+            : `${cronEntries.join("\n")}\n`;
+        const writeResult = spawnSync("crontab", ["-"], {
+            input: newCrontab,
+            encoding: "utf-8",
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        if (writeResult.status !== 0) {
+            return { registered: false, error: (writeResult.stderr || "").trim() };
+        }
+        return { registered: true };
+    }
+    catch (err) {
+        return {
+            registered: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+export async function emailSetup(params) {
+    const { email, password, accountId } = params;
+    // Infer provider defaults if hosts not explicitly provided
+    const provider = inferProvider(email);
+    const providerNotes = getProviderNotes(email) ?? undefined;
+    const agentAddress = params.agentAddress?.trim() || email;
+    const config = {
+        email,
+        agentAddress,
+        imapHost: params.imapHost ?? provider?.imapHost ?? "",
+        imapPort: params.imapPort ?? provider?.imapPort ?? 993,
+        imapSecurity: params.imapSecurity ?? provider?.imapSecurity ?? "tls",
+        smtpHost: params.smtpHost ?? provider?.smtpHost ?? "",
+        smtpPort: params.smtpPort ?? provider?.smtpPort ?? 587,
+        smtpSecurity: params.smtpSecurity ?? provider?.smtpSecurity ?? "starttls",
+    };
+    // Reject if hosts are still empty (unknown provider, user didn't provide)
+    if (!config.imapHost) {
+        return {
+            success: false,
+            message: `Cannot infer IMAP host for ${email}. Provide imapHost and smtpHost explicitly.`,
+            providerNotes,
+        };
+    }
+    if (!config.smtpHost) {
+        return {
+            success: false,
+            message: `Cannot infer SMTP host for ${email}. Provide smtpHost explicitly.`,
+            providerNotes,
+        };
+    }
+    // Validate 1:1 agent-email binding: each address maps to exactly one agent
+    const agentSlug = params.agentSlug ?? "admin";
+    const conflicting = await checkAddressBinding(agentAddress, agentSlug);
+    if (conflicting) {
+        return {
+            success: false,
+            message: `Email address ${agentAddress} is already bound to agent "${conflicting}". Each email address can only be used by one agent.`,
+        };
+    }
+    // Warn about likely misconfigured port/security combinations
+    if (config.imapPort === 993 && config.imapSecurity === "starttls") {
+        return {
+            success: false,
+            message: "Port 993 uses implicit TLS, not STARTTLS. Use imapSecurity: 'tls' with port 993, or port 143 with 'starttls'.",
+        };
+    }
+    if (config.smtpPort === 465 && config.smtpSecurity === "starttls") {
+        return {
+            success: false,
+            message: "Port 465 uses implicit TLS, not STARTTLS. Use smtpSecurity: 'tls' with port 465, or port 587 with 'starttls'.",
+        };
+    }
+    // Test IMAP connectivity
+    const imapError = await imap.testConnection(config, password);
+    if (imapError) {
+        return { success: false, message: imapError, providerNotes };
+    }
+    // Test SMTP connectivity
+    const smtpError = await smtp.testConnection(config, password);
+    if (smtpError) {
+        return { success: false, message: smtpError, providerNotes };
+    }
+    // Both tests passed — persist credentials
+    // Write graph node first (easier to clean up), then password file
+    try {
+        await writeConfig(accountId, config);
+    }
+    catch (err) {
+        return {
+            success: false,
+            message: `IMAP and SMTP connections verified, but failed to store config: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    try {
+        writePassword(password);
+    }
+    catch (err) {
+        // Rollback graph node — best effort, don't mask the original error
+        try {
+            await removeConfig(accountId);
+        }
+        catch { /* rollback failed — next setup will MERGE over it */ }
+        return {
+            success: false,
+            message: `IMAP and SMTP connections verified, but failed to store password file: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+    // Set agent binding and poll config
+    let bindingOk = true;
+    try {
+        await writeBindingConfig(accountId, agentSlug, params.pollIntervalMinutes ?? 5);
+    }
+    catch {
+        bindingOk = false;
+    }
+    // Ensure email cron jobs are registered so polling starts immediately
+    const cronResult = ensureEmailCrons(accountId);
+    // Get inbox count as a confirmation signal
+    let inboxCount;
+    try {
+        inboxCount = await imap.getInboxCount(config, password);
+    }
+    catch {
+        // Non-fatal — setup still succeeded
+    }
+    const aliasNote = agentAddress !== email ? ` Agent address: ${agentAddress} (auth: ${email}).` : "";
+    const pollNote = bindingOk
+        ? ` Email polling enabled (every ${params.pollIntervalMinutes ?? 5} minutes, bound to ${agentSlug}).`
+        : ` Email configured but polling binding could not be set — run email-setup again.`;
+    const cronNote = cronResult.registered
+        ? ""
+        : ` Warning: email cron registration failed (${cronResult.error}). Crons will be registered on next platform update.`;
+    return {
+        success: true,
+        message: `Email configured successfully for ${email}.${aliasNote} IMAP and SMTP connections verified.${inboxCount !== undefined ? ` Inbox has ${inboxCount} messages.` : ""}${pollNote}${cronNote}`,
+        inboxCount,
+        providerNotes,
+    };
+}
+//# sourceMappingURL=email-setup.js.map

package/payload/platform/plugins/email/mcp/dist/tools/email-setup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-setup.js","sourceRoot":"","sources":["../../src/tools/email-setup.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEpC,OAAO,EACL,WAAW,EAAE,aAAa,EAAE,YAAY,EACxC,mBAAmB,EAAE,kBAAkB,GACxC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAC;AAEvC;;;;;;;;GAQG;AACH,SAAS,gBAAgB,CAAC,SAAiB;IACzC,IAAI,CAAC;QACH,MAAM,UAAU,GAAG,SAAS,CAAC,SAAS,EAAE,CAAC,IAAI,CAAC,EAAE;YAC9C,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;QAElE,0DAA0D;QAC1D,IAAI,QAAQ,CAAC,QAAQ,CAAC,aAAa,CAAC,EAAE,CAAC;YACrC,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;QAC9B,CAAC;QAED,iDAAiD;QACjD,MAAM,YAAY,GAAG,OAAO,CAAC,GAAG,CAAC,aAAa,IAAI,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,CAAC,CAAC;QAC9F,MAAM,OAAO,GAAG,CAAC,GAAG,EAAE;YACpB,IAAI,CAAC;gBAAC,OAAO,YAAY,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;YAAC,CAAC;YAC7E,MAAM,CAAC;gBAAC,OAAO,eAAe,CAAC;YAAC,CAAC;QACnC,CAAC,CAAC,EAAE,CAAC;QACL,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;QAEhD,MAAM,WAAW,GAAG;YAClB,sBAAsB,MAAM,qBAAqB,YAAY,eAAe,SAAS,IAAI,OAAO,IAAI,YAAY,qDAAqD,MAAM,uBAAuB;YAClM,sBAAsB,MAAM,qBAAqB,YAAY,IAAI,OAAO,IAAI,YAAY,4DAA4D,MAAM,8BAA8B;SACzL,CAAC;QAEF,MAAM,UAAU,GAAG,QAAQ,CAAC,OAAO,EAAE;YACnC,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,EAAE,KAAK,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;YACtD,CAAC,CAAC,GAAG,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC;QAElC,MAAM,WAAW,GAAG,SAAS,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,EAAE;YAC9C,KAAK,EAAE,UAAU;YACjB,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;SAChC,CAAC,CAAC;QAEH,IAAI,WAAW,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7B,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,WAAW,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC;QACzE,CAAC;QAED,OAAO,EAAE,UAAU,EAAE,IAAI,EAAE,CAAC;IAC9B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,UAAU,EAAE,KAAK;YACjB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC;IACJ,CAAC;AACH,CAAC;AAiBD,MAAM,CAAC,KAAK,UAAU,UAAU,CAAC,MAAmB;IAMlD,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC;IAE9C,2DAA2D;IAC3D,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;IACtC,MAAM,aAAa,GAAG,gBAAgB,CAAC,KAAK,CAAC,IAAI,SAAS,CAAC;IAE3D,MAAM,YAAY,GAAG,MAAM,CAAC,YAAY,EAAE,IAAI,EAAE,IAAI,KAAK,CAAC;IAE1D,MAAM,MAAM,GAAgB;QAC1B,KAAK;QACL,YAAY;QACZ,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,QAAQ,EAAE,QAAQ,IAAI,EAAE;QACrD,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,QAAQ,EAAE,QAAQ,IAAI,GAAG;QACtD,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,QAAQ,EAAE,YAAY,IAAI,KAAK;QACpE,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,QAAQ,EAAE,QAAQ,IAAI,EAAE;QACrD,QAAQ,EAAE,MAAM,CAAC,QAAQ,IAAI,QAAQ,EAAE,QAAQ,IAAI,GAAG;QACtD,YAAY,EAAE,MAAM,CAAC,YAAY,IAAI,QAAQ,EAAE,YAAY,IAAI,UAAU;KAC1E,CAAC;IAEF,0EAA0E;IAC1E,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,8BAA8B,KAAK,6CAA6C;YACzF,aAAa;SACd,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,MAAM,CAAC,QAAQ,EAAE,CAAC;QACrB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,8BAA8B,KAAK,gCAAgC;YAC5E,aAAa;SACd,CAAC;IACJ,CAAC;IAED,2EAA2E;IAC3E,MAAM,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,OAAO,CAAC;IAC9C,MAAM,WAAW,GAAG,MAAM,mBAAmB,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;IACvE,IAAI,WAAW,EAAE,CAAC;QAChB,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,iBAAiB,YAAY,+BAA+B,WAAW,sDAAsD;SACvI,CAAC;IACJ,CAAC;IAED,6DAA6D;IAC7D,IAAI,MAAM,CAAC,QAAQ,KAAK,GAAG,IAAI,MAAM,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;QAClE,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,+GAA+G;SACzH,CAAC;IACJ,CAAC;IACD,IAAI,MAAM,CAAC,QAAQ,KAAK,GAAG,IAAI,MAAM,CAAC,YAAY,KAAK,UAAU,EAAE,CAAC;QAClE,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,+GAA+G;SACzH,CAAC;IACJ,CAAC;IAED,yBAAyB;IACzB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC9D,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;IAC/D,CAAC;IAED,yBAAyB;IACzB,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC9D,IAAI,SAAS,EAAE,CAAC;QACd,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,CAAC;IAC/D,CAAC;IAED,0CAA0C;IAC1C,kEAAkE;IAClE,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACvC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,mEAAmE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SAC/H,CAAC;IACJ,CAAC;IAED,IAAI,CAAC;QACH,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,mEAAmE;QACnE,IAAI,CAAC;YAAC,MAAM,YAAY,CAAC,SAAS,CAAC,CAAC;QAAC,CAAC;QAAC,MAAM,CAAC,CAAC,qDAAqD,CAAC,CAAC;QACtG,OAAO;YACL,OAAO,EAAE,KAAK;YACd,OAAO,EAAE,0EAA0E,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE;SACtI,CAAC;IACJ,CAAC;IAED,oCAAoC;IACpC,IAAI,SAAS,GAAG,IAAI,CAAC;IACrB,IAAI,CAAC;QACH,MAAM,kBAAkB,CAAC,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,mBAAmB,IAAI,CAAC,CAAC,CAAC;IAClF,CAAC;IAAC,MAAM,CAAC;QACP,SAAS,GAAG,KAAK,CAAC;IACpB,CAAC;IAED,sEAAsE;IACtE,MAAM,UAAU,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAE/C,2CAA2C;IAC3C,IAAI,UAA8B,CAAC;IACnC,IAAI,CAAC;QACH,UAAU,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC1D,CAAC;IAAC,MAAM,CAAC;QACP,oCAAoC;IACtC,CAAC;IAED,MAAM,SAAS,GAAG,YAAY,KAAK,KAAK,CAAC,CAAC,CAAC,mBAAmB,YAAY,WAAW,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IACpG,MAAM,QAAQ,GAAG,SAAS;QACxB,CAAC,CAAC,iCAAiC,MAAM,CAAC,mBAAmB,IAAI,CAAC,sBAAsB,SAAS,IAAI;QACrG,CAAC,CAAC,iFAAiF,CAAC;IACtF,MAAM,QAAQ,GAAG,UAAU,CAAC,UAAU;QACpC,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,6CAA6C,UAAU,CAAC,KAAK,sDAAsD,CAAC;IACxH,OAAO;QACL,OAAO,EAAE,IAAI;QACb,OAAO,EAAE,qCAAqC,KAAK,IAAI,SAAS,uCAAuC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,cAAc,UAAU,YAAY,CAAC,CAAC,CAAC,EAAE,GAAG,QAAQ,GAAG,QAAQ,EAAE;QACnM,UAAU;QACV,aAAa;KACd,CAAC;AACJ,CAAC"}

package/payload/platform/plugins/email/mcp/dist/tools/email-status.d.ts

@@ -0,0 +1,6 @@
+interface StatusParams {
+    accountId: string;
+}
+export declare function emailStatus(params: StatusParams): Promise<string>;
+export {};
+//# sourceMappingURL=email-status.d.ts.map

package/payload/platform/plugins/email/mcp/dist/tools/email-status.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-status.d.ts","sourceRoot":"","sources":["../../src/tools/email-status.ts"],"names":[],"mappings":"AAIA,UAAU,YAAY;IACpB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,wBAAsB,WAAW,CAAC,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CA4CvE"}

package/payload/platform/plugins/email/mcp/dist/tools/email-status.js

@@ -0,0 +1,43 @@
+import { readConfig, loadCredentials } from "../lib/credentials.js";
+import * as imap from "../lib/imap.js";
+import * as smtp from "../lib/smtp.js";
+export async function emailStatus(params) {
+    const config = await readConfig(params.accountId);
+    if (!config) {
+        return "Email: not configured. Run email-setup to set up the agent's email account.";
+    }
+    const credResult = await loadCredentials(params.accountId);
+    if ("error" in credResult) {
+        return `Email: ${config.email} — ${credResult.error}`;
+    }
+    const { password } = credResult.credentials;
+    // Test IMAP
+    const imapError = await imap.testConnection(config, password);
+    const imapStatus = imapError ? `FAIL — ${imapError}` : "OK";
+    // Test SMTP
+    const smtpError = await smtp.testConnection(config, password);
+    const smtpStatus = smtpError ? `FAIL — ${smtpError}` : "OK";
+    // Get inbox count if IMAP is healthy
+    let inboxInfo = "";
+    if (!imapError) {
+        try {
+            const count = await imap.getInboxCount(config, password);
+            inboxInfo = `\nInbox: ${count} messages`;
+        }
+        catch {
+            inboxInfo = "\nInbox: could not retrieve count";
+        }
+    }
+    const aliasLine = config.agentAddress !== config.email
+        ? `Agent address: ${config.agentAddress} (auth: ${config.email})`
+        : `Email: ${config.email}`;
+    return [
+        aliasLine,
+        `IMAP: ${config.imapHost}:${config.imapPort} (${config.imapSecurity}) — ${imapStatus}`,
+        `SMTP: ${config.smtpHost}:${config.smtpPort} (${config.smtpSecurity}) — ${smtpStatus}`,
+        inboxInfo,
+    ]
+        .filter(Boolean)
+        .join("\n");
+}
+//# sourceMappingURL=email-status.js.map

package/payload/platform/plugins/email/mcp/dist/tools/email-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-status.js","sourceRoot":"","sources":["../../src/tools/email-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACpE,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAC;AACvC,OAAO,KAAK,IAAI,MAAM,gBAAgB,CAAC;AAMvC,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,MAAoB;IACpD,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAClD,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,6EAA6E,CAAC;IACvF,CAAC;IAED,MAAM,UAAU,GAAG,MAAM,eAAe,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IAC3D,IAAI,OAAO,IAAI,UAAU,EAAE,CAAC;QAC1B,OAAO,UAAU,MAAM,CAAC,KAAK,MAAM,UAAU,CAAC,KAAK,EAAE,CAAC;IACxD,CAAC;IAED,MAAM,EAAE,QAAQ,EAAE,GAAG,UAAU,CAAC,WAAW,CAAC;IAE5C,YAAY;IACZ,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,UAAU,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAE5D,YAAY;IACZ,MAAM,SAAS,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;IAC9D,MAAM,UAAU,GAAG,SAAS,CAAC,CAAC,CAAC,UAAU,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IAE5D,qCAAqC;IACrC,IAAI,SAAS,GAAG,EAAE,CAAC;IACnB,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YACzD,SAAS,GAAG,YAAY,KAAK,WAAW,CAAC;QAC3C,CAAC;QAAC,MAAM,CAAC;YACP,SAAS,GAAG,mCAAmC,CAAC;QAClD,CAAC;IACH,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,YAAY,KAAK,MAAM,CAAC,KAAK;QACpD,CAAC,CAAC,kBAAkB,MAAM,CAAC,YAAY,WAAW,MAAM,CAAC,KAAK,GAAG;QACjE,CAAC,CAAC,UAAU,MAAM,CAAC,KAAK,EAAE,CAAC;IAE7B,OAAO;QACL,SAAS;QACT,SAAS,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,YAAY,OAAO,UAAU,EAAE;QACtF,SAAS,MAAM,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ,KAAK,MAAM,CAAC,YAAY,OAAO,UAAU,EAAE;QACtF,SAAS;KACV;SACE,MAAM,CAAC,OAAO,CAAC;SACf,IAAI,CAAC,IAAI,CAAC,CAAC;AAChB,CAAC"}

package/payload/platform/plugins/email/mcp/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@maxy/email",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js"
+  },
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.81.0",
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "imapflow": "^1.0.171",
+    "neo4j-driver": "^5.28.1",
+    "nodemailer": "^6.10.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/nodemailer": "^6.4.17",
+    "typescript": "^5.7.0"
+  }
+}

package/payload/platform/plugins/email/references/email-reference.md

@@ -0,0 +1,204 @@
+# Email Reference
+
+Full reference for the email plugin. Load with `plugin-read` when detailed configuration or behaviour reference is needed.
+
+## Setup
+
+Collect email credentials via a form. Render this `form` component with `render-component`:
+
+**Fields:**
+
+| name | label | type | required | placeholder |
+|------|-------|------|----------|-------------|
+| `email` | Email address | text | yes | user@example.com |
+| `password` | Password | text | yes | App password or account password |
+| `imapHost` | IMAP host | text | yes | imap.example.com |
+| `imapPort` | IMAP port | number | yes | 993 |
+| `imapSecurity` | IMAP security | select | yes | Options: `tls` (default), `starttls` |
+| `smtpHost` | SMTP host | text | yes | smtp.example.com |
+| `smtpPort` | SMTP port | number | yes | 587 |
+| `smtpSecurity` | SMTP security | select | yes | Options: `tls`, `starttls` (default) |
+| `agentAddress` | Agent email address (if different from login) | text | no | agent@yourdomain.com |
+
+The `agentAddress` field is for catchall/alias setups where the authentication email differs from the address the agent operates as. Leave empty when they're the same.
+
+After form submission, pass all fields to `email-setup`. On success, confirm "credentials stored" and the inbox count. On failure, relay the diagnostic — the tool returns specific guidance (wrong password, connection refused, TLS mismatch).
+
+The agent never displays stored passwords. Never name or recommend specific email providers — the form collects the standard fields every provider gives its users.
+
+## Reading and Searching
+
+`email-read` and `email-search` return message metadata only: UID, sender, subject, and date. Body content is not included — present results as a message list without commenting on missing bodies.
+
+### Pagination
+
+Both tools return up to 50 messages per request (default 20). When more messages exist beyond the returned set, the response includes a `next_before_uid` value. Pass this value as the `before_uid` parameter on the next call to retrieve the next page of older messages. When `next_before_uid` is absent, all matching messages have been returned.
+
+### Folders
+
+Both tools accept a `folder` parameter: `"inbox"` (default) or `"sent"`. The Sent folder is discovered automatically via the IMAP server's special-use flags — no folder name guessing required.
+
+### Filtering
+
+Both tools support filtering by:
+- `sender` — sender address or domain
+- `to` — recipient address
+- `since` / `before` — ISO date range
+- `email-read` additionally supports `subjectPattern` (regex)
+- `email-search` additionally supports `subject` (text) and `body` (keyword)
+
+## Replying
+
+`email-reply` sends a reply to an existing email, threaded correctly in the recipient's mail client.
+
+The tool accepts the `messageId` of the email being replied to (visible in `email-read` output as the `Message-ID` field). It looks up the original email in the graph, sets `In-Reply-To` and `References` headers, derives the recipient from the original sender, and prepends `Re:` to the subject (stripping duplicate prefixes).
+
+- **Reply to sender:** Default behaviour — replies to the original sender only.
+- **Reply all:** Set `replyAll: true` to include all original recipients (TO + CC). The agent's own address is automatically excluded from the recipient list.
+- **Threading:** The reply appears in the same conversation thread in Gmail, Apple Mail, Outlook, and other RFC 2822-compliant clients.
+- **Prerequisite:** The original email must exist in the graph (stored by the background polling job). If the email hasn't been fetched yet, the tool returns a clear error.
+
+Use `email-reply` when responding to a received email. Use `email-send` for new outbound messages.
+
+## Alias Support
+
+When `agentAddress` is set and differs from the auth email:
+
+- **Sending:** emails are sent with the agent address as the From header. SMTP authentication still uses the auth email.
+- **Reading/searching:** only emails whose TO header contains the agent address are returned. The agent ignores emails to other addresses on the same mailbox.
+- **OTP extraction:** only OTPs addressed to the agent address are found.
+- **Status:** reports both the agent address and the auth email.
+
+When `agentAddress` is not set or matches the auth email, all tools behave as before — no filtering, From header uses the auth email.
+
+## Email Persistence
+
+Emails are automatically polled from IMAP and stored as `Email` nodes in the graph. This happens via a background cron job — no manual triggering needed.
+
+- **Polling:** After `email-setup` completes, the platform polls IMAP at the configured interval (default: every 5 minutes). Only emails addressed TO the agent's `agentAddress` are stored.
+- **Deduplication:** Each email is identified by its Message-ID header. Re-polling the same messages does not create duplicates, even if the agent's email address changes between poll cycles. A composite unique constraint on `(messageId, accountId)` provides database-level enforcement.
+- **Semantic search:** Stored emails are vector-indexed (subject + body preview), enabling natural-language search over email history via `email-graph-query`.
+- **Isolation:** Each agent sees only emails addressed to its own bound email address, even when sharing a catchall mailbox.
+
+## Email Threading
+
+Emails are linked into conversation threads via `REPLY_TO` graph edges. When an email has an `In-Reply-To` header, the platform looks up the parent email by `Message-ID` within the same account and creates an edge. Thread linking happens automatically during the polling cron job.
+
+- **Out-of-order delivery:** If a reply arrives before its parent, the edge is created later when the parent is stored (orphan back-fill).
+- **Thread context:** `email-read` and `email-search` include `Thread-Depth` (number of hops to the thread root) and `Thread-ID` (emailId of the root message) for any email that is part of a thread. Root emails (no parent) have no thread fields.
+- **Scope:** Thread edges never cross account boundaries — parent lookups are always scoped to the same account.
+
+## Auto-Respond Audit Trail
+
+When auto-respond sends a reply, the outbound message is stored as an `Email` node with `direction: "outbound"` and a `REPLY_TO` edge to the original inbound email. This creates a queryable audit trail of every automated reply — what the agent said, when, and to whom.
+
+Outbound email nodes have the same properties as inbound emails (subject, bodyPreview, fromAddress, toAddresses, timestamps) plus the `direction` property. They appear in thread traversals alongside inbound messages.
+
+### Agent-Email Binding
+
+Each email address is bound to exactly one agent. Each agent can have at most one email address. This is enforced during `email-setup`:
+
+- The `agentSlug` parameter identifies which agent owns this email address (defaults to `"admin"`)
+- If the address is already bound to a different agent, setup fails with a clear error naming the conflicting agent
+- The binding is on `agentAddress` (the identity the agent presents), not the auth email
+
+### Email Retrieval Paths
+
+Three retrieval paths exist for email data — each scoped to a different purpose:
+
+- **Live inbox** (`email-read`, `email-search`) — queries IMAP directly. Use for checking the inbox, reading recent messages, browsing folders, and real-time inbox state. Requires IMAP connectivity.
+- **Graph list/search** (`email-graph-query`) — queries stored Email nodes in Neo4j. Use for email history, recall, and semantic search ("what emails are in memory?", "find emails about cabbages", "what did Sarah send about the contract?"). Works without IMAP. Supports date/sender/direction filters and natural-language semantic matching.
+- **General knowledge** (`memory-search`) — searches the entire knowledge graph across all node types. Use when the user's question spans all memory, not just emails ("what do you know about contract renewals?").
+
+When the user asks about stored emails, email history, or email recall — use `email-graph-query`. When they ask to check the inbox or read specific recent messages — use the IMAP tools. When the question is broader than emails — use `memory-search`.
+
+## Inbound Email Screening
+
+Every inbound email is classified by Claude Haiku before entering Neo4j. The classifier examines `fromAddress`, `fromName`, `subject`, and the first 1024 characters of `bodyPreview`.
+
+### Verdicts
+
+| Verdict | Stored? | Embedding? | Auto-respond? | Graph query? |
+|---------|---------|------------|---------------|--------------|
+| `clean` | Yes | Yes | Yes | Yes |
+| `suspicious` | Yes (with `screeningReason`) | Yes | No | Yes |
+| `discarded` | Yes (with `screeningReason`) | No | No | No (list mode) |
+
+- **clean** — legitimate personal or business correspondence
+- **suspicious** — phishing indicators (urgency + credential requests, mismatched sender), prompt injection patterns, or classification failure (safe default)
+- **discarded** — obvious spam, marketing bulk mail, auto-generated notifications with no actionable content
+
+### Prompt injection flag
+
+When `promptInjectionFlag` is true (body contains instruction-like patterns targeting an AI agent), auto-respond skips the email entirely regardless of verdict. No reply is generated. The email is visible in Neo4j for admin review.
+
+### Failure handling
+
+If the Haiku API is unavailable (network, rate limit, auth failure), the email defaults to `suspicious`. The entire fetch batch is never blocked — each email is classified independently. API key absence causes all emails in the batch to default to `suspicious`.
+
+### Logs
+
+Classification verdicts are logged to `{accountDir}/logs/email-fetch.log` with per-email detail (fromAddress, verdict, reason, promptInjectionRisk) and batch summaries.
+
+## Security
+
+- Credentials stored as a file with restricted permissions — never in conversation
+- IMAP and SMTP connections require TLS or STARTTLS — plaintext is rejected
+- Only the agent's own dedicated account is accessed — never the user's personal email
+- Email nodes have `scope: "admin"` — never visible to public agents
+- Inbound emails are classified by Haiku before storage — prompt injection and phishing are flagged
+
+## Auto-Respond
+
+When enabled, a public agent automatically replies to incoming emails. A cron job polls the inbox for new messages and generates replies via the assigned agent.
+
+### Setup
+
+To enable auto-respond, call `email-auto-respond-config` with `enabled: true`. The tool requires an `agentSlug` — render a `single-select` component with available public agents so the admin can choose which agent handles responses. The tool returns the agent list when called without a slug.
+
+When called without an `agentSlug`, the tool returns available agents. Present these as a `single-select` component for the admin to choose from, then call the tool again with the selected slug.
+
+### Configuration
+
+- `enabled` — `true` to enable, `false` to disable
+- `agentSlug` — slug of the public agent that responds (required when enabling)
+- `pollIntervalMinutes` — how often to check for new emails (default: 5, range: 1–60)
+- `hourlyLimit` — maximum auto-replies per clock hour UTC (default: 20, range: 1–1000)
+- `dailyLimit` — maximum auto-replies per calendar day UTC (default: 100, range: 1–10000)
+
+### Behaviour
+
+- The cron job runs every minute. Each account's poll is skipped if the configured interval hasn't elapsed since the last poll.
+- Only emails addressed TO the agent's email address are processed (alias filtering applies).
+- Auto-replies, mailing list messages, and emails from the agent's own address are automatically skipped (RFC 3834 loop prevention).
+- Outgoing replies include `In-Reply-To` and `References` headers for correct threading, and `Auto-Submitted: auto-replied` to prevent loops with other auto-responders.
+- Every reply includes a deterministic AI disclosure footer ("This reply was generated by an AI assistant.") appended after the agent's response. This is a regulatory requirement (EU AI Act Article 50) and is not dependent on the LLM including disclosure in its generated text.
+- The subject line carries a single `Re:` prefix (no doubling).
+
+### Rate Limiting
+
+Per-account send caps prevent runaway auto-replies from spam waves, mailing list explosions, or deliberate attacks. Two independent limits:
+
+- **Hourly limit** (default 20) — resets at each UTC clock-hour boundary
+- **Daily limit** (default 100) — resets at midnight UTC
+
+When either limit is reached, remaining emails in the poll cycle are skipped (not replied to). Auto-respond is **not** disabled — counters reset naturally at the next boundary. A medium-priority admin Task is created to notify the admin.
+
+Within a single poll cycle, only one auto-reply is sent per unique sender address. This prevents reply storms when an automated sender delivers multiple messages. Sender deduplication is case-insensitive.
+
+### Circuit Breaker
+
+After 3 consecutive failures (IMAP errors, API failures, SMTP rejections), auto-respond is automatically disabled and a high-priority Task is created for the admin. The admin sees this task at the start of their next session and can re-enable auto-respond after resolving the issue.
+
+### Disabling
+
+Call `email-auto-respond-config` with `enabled: false`. This clears the agent assignment and resets the failure counter.
+
+## OTP Integration
+
+Other skills call `email-otp-extract` during service authentication (Anthropic OAuth, Cloudflare setup) with:
+- `sender` — expected sender domain
+- `subject_pattern` — optional regex for subject line
+- `timeout` — how long to poll (default 60s)
+
+The tool polls at short intervals, extracts the verification code, and returns it. On timeout, it returns a clear failure so the calling skill can ask the user to check manually.