read-email-mcp 1.0.0 → 2.0.0

package/dist/tools.js

@@ -1,24 +1,83 @@
 import { z } from "zod";
+import { simpleParser } from "mailparser";
 import fs from "node:fs/promises";
+import path from "node:path";
+import { encodeCursor } from "./store.js";
+const accountSelectorFields = {
+    account: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Account name or email. Omit to use all configured accounts (where supported)."),
+    accounts: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Restrict to specific accounts by name/email ('*' wildcard supported), e.g. [\"work\", \"*-gmail\"]"),
+    accountGroup: z
+        .string()
+        .min(1)
+        .optional()
+        .describe("Restrict to accounts in this configured group (accounts file \"groups\" field)")
+};
+const durationParam = z
+    .string()
+    .regex(/^\d+[smhdw]$/)
+    .optional()
+    .describe("Relative lookback window like \"24h\", \"7d\", \"4w\" — sets startDate to now minus the duration");
+const isoDateTime = () => z.iso.datetime({ offset: true });
 export const toolSchemas = {
-    sync_email: z.object({
+    sync_email: z
+        .object({
+        ...accountSelectorFields,
         mailbox: z.string().min(1).optional(),
+        mailboxes: z.array(z.string().min(1)).optional(),
+        excludeMailboxes: z.array(z.string().min(1)).optional(),
+        excludeFlags: z.array(z.string().min(1)).optional(),
         limit: z.number().int().positive().max(1000).optional(),
-        since: z.string().datetime().optional()
+        since: isoDateTime().optional(),
+        uids: z
+            .string()
+            .regex(/^\d+([:,\-]\d+)*$/)
+            .optional(),
+        search: z
+            .object({
+            from: z.string().min(1).optional(),
+            to: z.string().min(1).optional(),
+            cc: z.string().min(1).optional(),
+            subject: z.string().min(1).optional(),
+            since: isoDateTime().optional(),
+            before: isoDateTime().optional(),
+            unseen: z.boolean().optional(),
+            flagged: z.boolean().optional()
+        })
+            .optional(),
+        refreshFlags: z.boolean().optional(),
+        pruneExpunged: z.boolean().optional(),
+        resetMailbox: z.boolean().optional()
+    })
+        .refine((value) => !value.uids || value.mailbox || value.mailboxes?.length === 1, {
+        message: "uids requires exactly one mailbox (pass mailbox, or mailboxes with a single entry)"
     }),
-    get_sync_status: z.object({}),
-    list_mailboxes: z.object({}),
+    list_accounts: z.object({}),
+    get_sync_status: z.object({ ...accountSelectorFields }),
+    list_mailboxes: z.object({ ...accountSelectorFields }),
     get_recent_emails: z.object({
+        ...accountSelectorFields,
         mailbox: z.string().min(1).optional(),
+        mailboxes: z.array(z.string().min(1)).optional(),
         unreadOnly: z.boolean().optional(),
         flaggedOnly: z.boolean().optional(),
+        last: durationParam,
         limit: z.number().int().positive().max(100).optional()
     }),
     browse_email_dates: z.object({
+        ...accountSelectorFields,
         granularity: z.enum(["day", "week", "month"]).default("day"),
         mailbox: z.string().min(1).optional(),
-        startDate: z.string().datetime().optional(),
-        endDate: z.string().datetime().optional()
+        mailboxes: z.array(z.string().min(1)).optional(),
+        startDate: isoDateTime().optional(),
+        endDate: isoDateTime().optional(),
+        last: durationParam
     }),
     search_emails: messageFilterSchema().extend({
         query: z.string().min(1).optional()
@@ -26,114 +85,392 @@ export const toolSchemas = {
     list_emails: messageFilterSchema(),
     get_email: z
         .object({
+        ...accountSelectorFields,
         id: z.number().int().positive().optional(),
         mailbox: z.string().min(1).optional(),
         uid: z.number().int().positive().optional(),
-        messageId: z.string().min(1).optional()
+        messageId: z.string().min(1).optional(),
+        format: z.enum(["full", "text", "headers", "summary"]).optional(),
+        maxBodyChars: z.number().int().positive().max(500_000).optional()
     })
         .refine((value) => value.id || value.messageId || (value.mailbox && value.uid), {
         message: "Provide id, messageId, or mailbox plus uid"
     }),
+    get_emails: z.object({
+        ...accountSelectorFields,
+        ids: z.array(z.number().int().positive()).min(1).max(25),
+        format: z.enum(["full", "text", "headers", "summary"]).optional(),
+        maxBodyChars: z.number().int().positive().max(500_000).optional()
+    }),
     get_thread: z
         .object({
+        ...accountSelectorFields,
         id: z.number().int().positive().optional(),
-        messageId: z.string().min(1).optional()
+        messageId: z.string().min(1).optional(),
+        format: z.enum(["full", "text", "headers", "summary"]).optional(),
+        maxBodyChars: z.number().int().positive().max(500_000).optional()
     })
         .refine((value) => value.id || value.messageId, {
         message: "Provide id or messageId"
     }),
+    list_attachments: emailLocatorBaseSchema()
+        .extend({ ...accountSelectorFields })
+        .refine((value) => value.id || value.messageId || (value.mailbox && value.uid), {
+        message: "Provide id, messageId, or mailbox plus uid"
+    }),
+    get_attachment: emailLocatorBaseSchema()
+        .extend({
+        ...accountSelectorFields,
+        index: z.number().int().min(0).optional(),
+        filename: z.string().min(1).optional(),
+        saveTo: z.string().min(1).optional(),
+        maxBytes: z.number().int().positive().max(5_000_000).default(262_144)
+    })
+        .refine((value) => value.id || value.messageId || (value.mailbox && value.uid), {
+        message: "Provide id, messageId, or mailbox plus uid"
+    })
+        .refine((value) => value.index !== undefined || value.filename !== undefined, {
+        message: "Provide index or filename to select the attachment"
+    }),
+    get_inbox_summary: z.object({
+        ...accountSelectorFields,
+        unreadLimit: z.number().int().positive().max(50).optional()
+    }),
+    list_senders: z.object({
+        ...accountSelectorFields,
+        unreadOnly: z.boolean().optional(),
+        limit: z.number().int().positive().max(100).optional()
+    }),
+    check_accounts: z.object({ ...accountSelectorFields }),
     get_raw_email: emailLocatorBaseSchema()
         .extend({
+        ...accountSelectorFields,
         maxBytes: z.number().int().positive().max(1_000_000).default(65_536)
     })
         .refine((value) => value.id || value.messageId || (value.mailbox && value.uid), {
         message: "Provide id, messageId, or mailbox plus uid"
     }),
-    get_storage_stats: z.object({}),
-    optimize_email_store: z.object({})
+    get_storage_stats: z.object({ ...accountSelectorFields }),
+    optimize_email_store: z.object({ ...accountSelectorFields })
 };
 export const toolDescriptions = {
-    sync_email: "Pull new messages from the IMAP server into the local mirror. Call this first (or after a gap) before browsing/searching, since every other tool reads the local copy. Tip: start with a small limit on one mailbox (e.g. { mailbox: 'INBOX', limit: 10 }) to verify credentials, then sync more. Without a mailbox, syncs all selectable mailboxes. Uses read-only IMAP access and never mutates the server mailbox.",
-    get_sync_status: "Check how fresh the local mirror is: total messages, latest message date, per-mailbox counts, and the last sync result. Good first call to see whether a sync is needed and whether the previous sync succeeded.",
-    list_mailboxes: "List the mailboxes known locally (e.g. INBOX, Sent, Drafts) with message counts and last-sync time. Use this to discover mailbox names to pass to sync_email, get_recent_emails, or list_emails.",
-    get_recent_emails: "Show the latest emails, newest first. This is the everyday 'what's new in my inbox' tool. Set unreadOnly: true to see only unread messages, or flaggedOnly: true for starred messages. Returns summaries (subject, from, date, preview, attachments, read/flagged state); pass the returned id to get_email for the full body, or get_thread to see the whole conversation.",
-    browse_email_dates: "Summarize message volume over time as counts per day, week, or month. Useful for 'how much email did I get this month' or finding a busy period before drilling in with list_emails/search_emails over that date range.",
-    search_emails: "Full-text search across subject, sender/recipient addresses, preview, and body text, with the same filters as list_emails (mailbox, from, to, cc, subject, date range, attachments, unread, flagged). Use this when looking for specific content or a topic. Returns paginated summaries; use get_email on a hit for the full message.",
-    list_emails: "List email summaries in chronological order with filters (mailbox, from, to, cc, subject, date range, attachments, unread, flagged) and keyset pagination, but without full-text search. Prefer this over search_emails when browsing by sender, date, or mailbox rather than searching body text. Defaults to newest first with a page size of 25.",
-    get_email: "Return the full metadata and body (text and HTML) for a single message. Resolve it by the id returned from get_recent_emails/list_emails/search_emails, by Message-ID, or by mailbox plus UID. Use this after finding a summary you want to read in full.",
-    get_thread: "Return all locally known messages in one conversation, matched via Message-ID, In-Reply-To, and References headers. Give the id or messageId of any message in the thread. Use this to follow a discussion after get_email or when a search hit looks like part of a longer thread.",
+    sync_email: "Pull messages from IMAP into the local mirror. Call this first (or after a gap) before browsing/searching, since every other tool reads the local copy. Default mode is incremental: only UIDs above the per-mailbox high-water mark are fetched. Targeted mode (pass uids, search, or since) fetches exactly the matching messages without moving the incremental cursor — use it to backfill or fetch specific mail, e.g. { mailbox: 'INBOX', uids: '12,15,20-30' } or { mailbox: 'INBOX', search: { from: 'alice@x.com', unseen: true } }. Targeted fetches upsert messages, so they also refresh stored flags/content for those UIDs. Options: mailboxes/excludeMailboxes select folders ('*' wildcard supported), excludeFlags skips special-use folders (default excludes \\All to avoid double-mirroring Gmail-style All Mail), refreshFlags re-syncs \\Seen/\\Flagged state on already-synced messages, pruneExpunged (default on with refreshFlags) removes local copies of server-deleted mail, resetMailbox restarts the incremental scan from UID 1. With multiple accounts, pass account (or accounts/accountGroup for a subset) to scope the sync; omit to sync every account in parallel. Uses read-only IMAP access and never mutates the server mailbox.",
+    list_accounts: "List the configured email accounts (name, address, provider, groups, storage path, message counts). Use the returned name as the account parameter on other tools, or a group name as accountGroup, to scope reads and syncs.",
+    get_sync_status: "Check how fresh the local mirror is: total messages, latest message date, per-mailbox counts, and the last sync result. Good first call to see whether a sync is needed and whether the previous sync succeeded. Pass account to check one account, or omit for a per-account summary.",
+    list_mailboxes: "List the mailboxes known locally (e.g. INBOX, Sent, Drafts) with message counts and last-sync time. Use this to discover mailbox names to pass to sync_email, get_recent_emails, or list_emails. Pass account to list one account's folders.",
+    get_recent_emails: "Show the latest emails, newest first. This is the everyday 'what's new in my inbox' tool. Set unreadOnly: true to see only unread messages, or flaggedOnly: true for starred messages; last: '24h' limits to a lookback window. Omit account for a unified inbox across all configured accounts (each item is tagged with its account). Returns summaries; pass the returned id plus its account to get_email for the full body, or get_thread for the whole conversation.",
+    browse_email_dates: "Summarize message volume over time as counts per day, week, or month. Useful for 'how much email did I get this month' or finding a busy period before drilling in with list_emails/search_emails over that date range. Omit account for a merged view across accounts.",
+    search_emails: "Full-text search across subject, sender/recipient addresses, preview, and body text, with the same filters as list_emails (mailbox/mailboxes, from, to, cc, subject, date range or last: '7d', attachments, unread, flagged). sort: 'relevance' ranks hits by FTS match quality and interleaves each account's best results first. Use this when looking for specific content or a topic. Scope with account, accounts (list/'*' wildcard), or accountGroup; omit all to search every configured account and merge hits. Returns paginated summaries; use get_email on a hit for the full message.",
+    list_emails: "List email summaries in chronological order with filters (mailbox/mailboxes, from, to, cc, subject, date range or last: '7d', attachments, unread, flagged) and keyset pagination, but without full-text search. Prefer this over search_emails when browsing by sender, date, or mailbox rather than searching body text. Scope with account, accounts, or accountGroup; omit to merge all accounts into one timeline. Defaults to newest first with a page size of 25.",
+    get_email: "Return the full metadata and body for a single message. Resolve it by the id returned from get_recent_emails/list_emails/search_emails, by Message-ID, or by mailbox plus UID. With multiple accounts, pass the account shown on the summary when resolving by id or mailbox+uid (Message-ID lookups search all accounts automatically). Use format 'text' (drop HTML), 'headers' (metadata + headers only), or 'summary' (metadata only), and maxBodyChars to truncate long bodies and save context.",
+    get_emails: "Read a group of messages in one call. Pass up to 25 ids returned by get_recent_emails/list_emails/search_emails plus their account (required with multiple accounts). Prefer this over looping get_email when you need several full bodies. Supports the same format/maxBodyChars options as get_email.",
+    get_thread: "Return all locally known messages in one conversation, matched via Message-ID, In-Reply-To, and References headers. Give the id or messageId of any message in the thread (plus account when multiple accounts are configured and you resolve by id). Threads are assembled within a single account's mirror. Supports format/maxBodyChars like get_email.",
+    list_attachments: "List the attachments on a message (index, filename, content type, size) without downloading them. Resolve the message the same way as get_email. Follow up with get_attachment to extract one.",
+    get_attachment: "Extract one attachment from a stored message by index or filename (find indexes with list_attachments). Returns base64 content up to maxBytes (default 256 KiB), or saves to a local path with saveTo for larger files.",
+    get_inbox_summary: "One-call triage overview per account: total/unread/flagged counts, mailbox count, latest message date, and the newest unread summaries (unreadLimit, default 10). Omit account for a per-account briefing across everything — the 'what needs attention' tool.",
+    list_senders: "Rank senders by message count with unread counts per sender, merged across the selected accounts (each sender lists which accounts they hit). Use unreadOnly for 'who's emailing me that I haven't read'. Great for finding a person before a targeted search.",
+    check_accounts: "Test IMAP connectivity for each account: connects, lists mailboxes, disconnects. Reports ok/mailbox count or the error per account — use it to diagnose auth or network problems before a sync.",
     get_raw_email: "Return the raw RFC822/MIME source for one message, byte-limited (default 64 KiB). Use this only when you need original headers or MIME structure not exposed by get_email, for example to inspect a specific header or attachment encoding.",
-    get_storage_stats: "Report SQLite database, WAL, and shared-memory file sizes plus page counts for the local mirror. Use this to understand disk usage after large syncs.",
-    optimize_email_store: "Run lightweight SQLite and FTS maintenance (ANALYZE/optimize) to keep queries fast. Safe to call occasionally after large syncs or before packaging a local archive."
+    get_storage_stats: "Report SQLite database, WAL, and shared-memory file sizes plus page counts for the local mirror. Pass account for one account's database or omit for all. Use this to understand disk usage after large syncs.",
+    optimize_email_store: "Run lightweight SQLite and FTS maintenance (ANALYZE/optimize) to keep queries fast. Safe to call occasionally after large syncs or before packaging a local archive. Omit account to optimize every account's database."
 };
 export function createToolHandlers(context) {
     return {
         sync_email: async (input) => {
-            const args = toolSchemas.sync_email.parse(input);
-            const result = await context.sync.sync(args);
-            return json(result);
+            const { account, accounts: accountList, accountGroup, ...syncArgs } = toolSchemas.sync_email.parse(input);
+            const accounts = resolveAccounts(context, { account, accounts: accountList, accountGroup });
+            const settled = await Promise.allSettled(accounts.map((runtime) => runtime.sync.sync(syncArgs)));
+            const results = settled.map((outcome, index) => {
+                const name = accounts[index].name;
+                if (outcome.status === "fulfilled") {
+                    return { ...outcome.value, account: name };
+                }
+                const message = outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason);
+                return {
+                    ok: false,
+                    mode: "incremental",
+                    mailbox: null,
+                    startedAt: "",
+                    finishedAt: new Date().toISOString(),
+                    message,
+                    syncedMessages: 0,
+                    mailboxes: [],
+                    refreshedFlags: 0,
+                    prunedMessages: 0,
+                    errors: [{ mailbox: "*", message }],
+                    account: name
+                };
+            });
+            if (results.length === 1) {
+                return json(results[0]);
+            }
+            return json({ ok: results.every((result) => result.ok), results });
+        },
+        list_accounts: async (input) => {
+            toolSchemas.list_accounts.parse(input);
+            const accounts = context.accounts.map((runtime) => {
+                const status = runtime.store.getSyncStatus();
+                return {
+                    name: runtime.name,
+                    email: runtime.email,
+                    provider: runtime.provider,
+                    groups: runtime.groups,
+                    storagePath: runtime.storagePath,
+                    totalMessages: status.totalMessages,
+                    latestMessageDate: status.latestMessageDate
+                };
+            });
+            return json({ accounts });
         },
         get_sync_status: async (input) => {
-            toolSchemas.get_sync_status.parse(input);
+            const args = toolSchemas.get_sync_status.parse(input);
+            const accounts = resolveAccounts(context, args);
+            if (accounts.length === 1) {
+                const runtime = accounts[0];
+                return json({
+                    account: runtime.name,
+                    email: runtime.email,
+                    storagePath: runtime.storagePath,
+                    ...runtime.store.getSyncStatus()
+                });
+            }
             return json({
-                account: context.accountEmail,
-                storagePath: context.storagePath,
-                ...context.store.getSyncStatus()
+                accounts: accounts.map((runtime) => ({
+                    account: runtime.name,
+                    email: runtime.email,
+                    storagePath: runtime.storagePath,
+                    ...runtime.store.getSyncStatus()
+                }))
             });
         },
         list_mailboxes: async (input) => {
-            toolSchemas.list_mailboxes.parse(input);
-            return json({ mailboxes: context.store.listMailboxes() });
+            const args = toolSchemas.list_mailboxes.parse(input);
+            const accounts = resolveAccounts(context, args);
+            if (accounts.length === 1) {
+                return json({ account: accounts[0].name, mailboxes: accounts[0].store.listMailboxes() });
+            }
+            return json({
+                accounts: accounts.map((runtime) => ({ account: runtime.name, mailboxes: runtime.store.listMailboxes() }))
+            });
         },
         get_recent_emails: async (input) => {
             const args = toolSchemas.get_recent_emails.parse(input);
-            return json(context.store.listMessages({
+            const accounts = resolveAccounts(context, args);
+            return json(queryAccounts(accounts, {
                 mailbox: args.mailbox,
+                mailboxes: args.mailboxes,
                 isUnread: args.unreadOnly,
                 isFlagged: args.flaggedOnly,
+                startDate: durationToSince(args.last),
                 limit: args.limit,
                 sort: "date_desc"
             }));
         },
         browse_email_dates: async (input) => {
             const args = toolSchemas.browse_email_dates.parse(input);
-            return json({ buckets: context.store.getDateBuckets(args) });
+            const accounts = resolveAccounts(context, args);
+            const options = {
+                granularity: args.granularity,
+                mailbox: args.mailbox,
+                mailboxes: args.mailboxes,
+                startDate: args.startDate ?? durationToSince(args.last),
+                endDate: args.endDate
+            };
+            const perAccount = accounts.map((runtime) => ({
+                account: runtime.name,
+                buckets: runtime.store.getDateBuckets(options)
+            }));
+            if (perAccount.length === 1) {
+                return json({ account: perAccount[0].account, buckets: perAccount[0].buckets });
+            }
+            const merged = new Map();
+            for (const { buckets } of perAccount) {
+                for (const bucket of buckets) {
+                    merged.set(bucket.bucket, (merged.get(bucket.bucket) ?? 0) + bucket.count);
+                }
+            }
+            const mergedBuckets = [...merged.entries()]
+                .map(([bucket, count]) => ({ bucket, count }))
+                .sort((a, b) => a.bucket.localeCompare(b.bucket));
+            return json({ buckets: mergedBuckets, accounts: perAccount });
         },
         search_emails: async (input) => {
             const args = toolSchemas.search_emails.parse(input);
-            return json(context.store.searchMessages(args));
+            const accounts = resolveAccounts(context, args);
+            return json(queryAccounts(accounts, withDuration(args), "search"));
         },
         list_emails: async (input) => {
             const args = toolSchemas.list_emails.parse(input);
-            return json(context.store.listMessages(args));
+            const accounts = resolveAccounts(context, args);
+            return json(queryAccounts(accounts, withDuration(args)));
         },
         get_email: async (input) => {
             const args = toolSchemas.get_email.parse(input);
-            const message = findMessage(context.store, args);
-            if (!message) {
+            const found = findMessage(context, args);
+            if (!found) {
                 throw new Error("Email message not found");
             }
-            return json({ message });
+            return json({
+                account: found.account.name,
+                message: annotateMessage(shapeMessage(found.message, args.format, args.maxBodyChars), found.account)
+            });
+        },
+        get_emails: async (input) => {
+            const args = toolSchemas.get_emails.parse(input);
+            const runtime = requireSingleAccount(context, args);
+            const found = runtime.store.getMessagesByIds(args.ids);
+            const foundIds = new Set(found.map((message) => message.id));
+            return json({
+                account: runtime.name,
+                items: found.map((message) => annotateMessage(shapeMessage(message, args.format, args.maxBodyChars), runtime)),
+                missing: args.ids.filter((id) => !foundIds.has(id))
+            });
         },
         get_thread: async (input) => {
             const args = toolSchemas.get_thread.parse(input);
-            return json({ items: context.store.getThread(args.id ?? args.messageId) });
+            const found = findMessage(context, args);
+            if (!found) {
+                return json({ items: [] });
+            }
+            const thread = found.account.store.getThread(found.message.id);
+            return json({
+                account: found.account.name,
+                items: thread.map((message) => annotateMessage(shapeMessage(message, args.format, args.maxBodyChars), found.account))
+            });
+        },
+        list_attachments: async (input) => {
+            const args = toolSchemas.list_attachments.parse(input);
+            const found = findMessage(context, args);
+            if (!found) {
+                throw new Error("Email message not found");
+            }
+            return json({
+                account: found.account.name,
+                id: found.message.id,
+                count: found.message.attachments.length,
+                attachments: found.message.attachments.map((attachment, index) => ({ index, ...attachment }))
+            });
+        },
+        get_attachment: async (input) => {
+            const args = toolSchemas.get_attachment.parse(input);
+            const found = findMessage(context, args);
+            if (!found) {
+                throw new Error("Email message not found");
+            }
+            const resolvedPath = resolveRawPath(found.account, found.message);
+            const raw = await fs.readFile(resolvedPath);
+            const parsed = await simpleParser(raw);
+            const attachment = selectAttachment(parsed.attachments, args);
+            const meta = {
+                account: found.account.name,
+                id: found.message.id,
+                index: parsed.attachments.indexOf(attachment),
+                filename: attachment.filename ?? null,
+                contentType: attachment.contentType,
+                size: attachment.size
+            };
+            if (args.saveTo) {
+                const target = path.resolve(args.saveTo);
+                await fs.mkdir(path.dirname(target), { recursive: true });
+                await fs.writeFile(target, attachment.content);
+                return json({ ...meta, savedTo: target });
+            }
+            if (attachment.size > args.maxBytes) {
+                throw new Error(`Attachment is ${attachment.size} bytes, above maxBytes ${args.maxBytes}. Raise maxBytes (max 5000000) or pass saveTo to write it to disk.`);
+            }
+            return json({ ...meta, encoding: "base64", content: attachment.content.toString("base64") });
+        },
+        get_inbox_summary: async (input) => {
+            const args = toolSchemas.get_inbox_summary.parse(input);
+            const accounts = resolveAccounts(context, args);
+            const unreadLimit = args.unreadLimit ?? 10;
+            const summaries = accounts.map((runtime) => {
+                const counts = runtime.store.getMessageCounts();
+                const status = runtime.store.getSyncStatus();
+                const summary = {
+                    account: runtime.name,
+                    email: runtime.email,
+                    totalMessages: counts.total,
+                    unreadMessages: counts.unread,
+                    flaggedMessages: counts.flagged,
+                    mailboxCount: status.mailboxes.length,
+                    latestMessageDate: status.latestMessageDate,
+                    recentUnread: runtime.store
+                        .listMessages({ isUnread: true, limit: unreadLimit })
+                        .items.map((item) => annotateMessage(item, runtime))
+                };
+                return summary;
+            });
+            return summaries.length === 1 ? json(summaries[0]) : json({ accounts: summaries });
+        },
+        list_senders: async (input) => {
+            const args = toolSchemas.list_senders.parse(input);
+            const accounts = resolveAccounts(context, args);
+            const limit = Math.min(Math.max(Math.trunc(args.limit ?? 25), 1), 100);
+            const merged = new Map();
+            for (const runtime of accounts) {
+                for (const sender of runtime.store.getTopSenders({ limit, unreadOnly: args.unreadOnly })) {
+                    const existing = merged.get(sender.address);
+                    if (existing) {
+                        existing.count += sender.count;
+                        existing.unreadCount += sender.unreadCount;
+                        if (!existing.name && sender.name) {
+                            existing.name = sender.name;
+                        }
+                        if (!existing.accounts?.includes(runtime.name)) {
+                            existing.accounts = [...(existing.accounts ?? []), runtime.name];
+                        }
+                    }
+                    else {
+                        merged.set(sender.address, { ...sender, accounts: [runtime.name] });
+                    }
+                }
+            }
+            const senders = [...merged.values()]
+                .sort((a, b) => b.count - a.count || a.address.localeCompare(b.address))
+                .slice(0, limit);
+            return json({ senders });
+        },
+        check_accounts: async (input) => {
+            const args = toolSchemas.check_accounts.parse(input);
+            const accounts = resolveAccounts(context, args);
+            const settled = await Promise.allSettled(accounts.map((runtime) => runtime.sync.check()));
+            const results = settled.map((outcome, index) => {
+                const name = accounts[index].name;
+                if (outcome.status === "fulfilled") {
+                    return { account: name, ...outcome.value };
+                }
+                return {
+                    account: name,
+                    ok: false,
+                    host: "",
+                    mailboxCount: 0,
+                    mailboxes: [],
+                    error: outcome.reason instanceof Error ? outcome.reason.message : String(outcome.reason)
+                };
+            });
+            return results.length === 1
+                ? json(results[0])
+                : json({ ok: results.every((result) => result.ok), accounts: results });
         },
         get_raw_email: async (input) => {
             const args = toolSchemas.get_raw_email.parse(input);
-            const message = findMessage(context.store, args);
-            if (!message) {
+            const found = findMessage(context, args);
+            if (!found) {
                 throw new Error("Email message not found");
             }
-            const stats = await fs.stat(message.rawPath);
-            const handle = await fs.open(message.rawPath, "r");
+            const { account, message } = found;
+            const resolvedPath = resolveRawPath(account, message);
+            const stats = await fs.stat(resolvedPath);
+            const handle = await fs.open(resolvedPath, "r");
             try {
                 const bytesToRead = Math.min(args.maxBytes, stats.size);
                 const buffer = Buffer.alloc(bytesToRead);
                 const { bytesRead } = await handle.read(buffer, 0, bytesToRead, 0);
                 return json({
+                    account: account.name,
                     id: message.id,
-                    rawPath: message.rawPath,
+                    rawPath: resolvedPath,
                     sizeBytes: stats.size,
                     returnedBytes: bytesRead,
                     truncated: bytesRead < stats.size,
@@ -145,19 +482,340 @@ export function createToolHandlers(context) {
             }
         },
         get_storage_stats: async (input) => {
-            toolSchemas.get_storage_stats.parse(input);
-            return json(context.store.getStorageStats());
+            const args = toolSchemas.get_storage_stats.parse(input);
+            const accounts = resolveAccounts(context, args);
+            if (accounts.length === 1) {
+                return json({ account: accounts[0].name, ...accounts[0].store.getStorageStats() });
+            }
+            return json({
+                accounts: accounts.map((runtime) => ({ account: runtime.name, ...runtime.store.getStorageStats() }))
+            });
         },
         optimize_email_store: async (input) => {
-            toolSchemas.optimize_email_store.parse(input);
-            return json(context.store.optimize());
+            const args = toolSchemas.optimize_email_store.parse(input);
+            const accounts = resolveAccounts(context, args);
+            const results = accounts.map((runtime) => ({ account: runtime.name, ...runtime.store.optimize() }));
+            return results.length === 1 ? json(results[0]) : json({ results });
         }
     };
 }
-function emailLocatorSchema() {
-    return emailLocatorBaseSchema().refine((value) => value.id || value.messageId || (value.mailbox && value.uid), {
-        message: "Provide id, messageId, or mailbox plus uid"
+function resolveAccounts(context, selector = {}) {
+    const matched = new Set();
+    const patterns = [selector.account, ...(selector.accounts ?? [])].filter((value) => Boolean(value));
+    for (const pattern of patterns) {
+        const matches = matchAccounts(context.accounts, pattern);
+        if (matches.length === 0) {
+            const available = context.accounts.map((runtime) => runtime.name).join(", ");
+            throw new Error(`Unknown account "${pattern}". Configured accounts: ${available}`);
+        }
+        for (const runtime of matches) {
+            matched.add(runtime);
+        }
+    }
+    if (selector.accountGroup) {
+        const group = selector.accountGroup.trim().toLowerCase();
+        const members = context.accounts.filter((runtime) => runtime.groups.includes(group));
+        if (members.length === 0) {
+            const groups = [...new Set(context.accounts.flatMap((runtime) => runtime.groups))].join(", ");
+            throw new Error(`Unknown account group "${selector.accountGroup}".` +
+                (groups ? ` Configured groups: ${groups}` : " No groups are configured."));
+        }
+        for (const runtime of members) {
+            matched.add(runtime);
+        }
+    }
+    if (matched.size === 0) {
+        return context.accounts;
+    }
+    return context.accounts.filter((runtime) => matched.has(runtime));
+}
+function matchAccounts(accounts, pattern) {
+    const needle = pattern.trim().toLowerCase();
+    if (needle.includes("*")) {
+        const regex = new RegExp(`^${needle.split("*").map(escapeRegex).join(".*")}$`);
+        return accounts.filter((runtime) => regex.test(runtime.name.toLowerCase()) || regex.test(runtime.email.toLowerCase()));
+    }
+    const exact = accounts.find((runtime) => runtime.name.toLowerCase() === needle || runtime.email.toLowerCase() === needle);
+    return exact ? [exact] : [];
+}
+function escapeRegex(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function requireSingleAccount(context, selector = {}) {
+    const accounts = resolveAccounts(context, selector);
+    if (accounts.length === 1) {
+        return accounts[0];
+    }
+    const available = context.accounts.map((runtime) => runtime.name).join(", ");
+    throw new Error(`Multiple accounts matched — narrow to one account (one of: ${available})`);
+}
+function annotateMessage(message, account) {
+    return { ...message, account: account.name };
+}
+const DEFAULT_MAX_BODY_CHARS = 50_000;
+function shapeMessage(message, format, maxBodyChars) {
+    const mode = format ?? "full";
+    const cap = maxBodyChars ?? DEFAULT_MAX_BODY_CHARS;
+    const keepText = mode === "full" || mode === "text";
+    const keepHtml = mode === "full";
+    const keepHeaders = mode !== "summary";
+    const truncated = {};
+    const text = keepText ? truncateBody(message.text, cap, truncated, "text") : null;
+    const html = keepHtml ? truncateBody(message.html, cap, truncated, "html") : null;
+    const shaped = { ...message, text, html, headers: keepHeaders ? message.headers : {} };
+    if (truncated.text || truncated.html) {
+        return { ...shaped, truncated };
+    }
+    return shaped;
+}
+function truncateBody(value, cap, truncated, key) {
+    if (value === null || value.length <= cap) {
+        return value;
+    }
+    truncated[key] = true;
+    return value.slice(0, cap);
+}
+function selectAttachment(attachments, args) {
+    if (args.index !== undefined) {
+        const attachment = attachments[args.index];
+        if (!attachment) {
+            throw new Error(`No attachment at index ${args.index} — message has ${attachments.length} attachment(s)`);
+        }
+        return attachment;
+    }
+    const needle = args.filename.toLowerCase();
+    const attachment = attachments.find((candidate) => candidate.filename?.toLowerCase() === needle);
+    if (!attachment) {
+        const names = attachments.map((candidate) => candidate.filename ?? "(unnamed)").join(", ");
+        throw new Error(`No attachment named "${args.filename}". Available: ${names || "none"}`);
+    }
+    return attachment;
+}
+function resolveRawPath(account, message) {
+    const rawRoot = path.resolve(account.rawDir);
+    const resolvedPath = path.resolve(message.rawPath);
+    if (resolvedPath !== rawRoot && !resolvedPath.startsWith(rawRoot + path.sep)) {
+        throw new Error("Stored raw path for this message is outside the account storage directory");
+    }
+    return resolvedPath;
+}
+const DURATION_UNITS_MS = {
+    s: 1_000,
+    m: 60_000,
+    h: 3_600_000,
+    d: 86_400_000,
+    w: 604_800_000
+};
+function durationToSince(last) {
+    if (!last) {
+        return undefined;
+    }
+    const amount = Number(last.slice(0, -1));
+    const unit = last.slice(-1);
+    const ms = DURATION_UNITS_MS[unit];
+    if (!Number.isFinite(amount) || !ms) {
+        return undefined;
+    }
+    return new Date(Date.now() - amount * ms).toISOString();
+}
+function withDuration(args) {
+    const { last, ...rest } = args;
+    if (last && rest.startDate) {
+        throw new Error("Pass either last or startDate, not both");
+    }
+    return { ...rest, startDate: rest.startDate ?? durationToSince(last) };
+}
+function findMessage(context, locator) {
+    const needsAccount = Boolean(locator.id || (locator.mailbox && locator.uid));
+    const hasSelector = Boolean(locator.account || locator.accounts?.length || locator.accountGroup);
+    if (hasSelector || needsAccount) {
+        const runtime = requireSingleAccount(context, locator);
+        const message = locator.id
+            ? runtime.store.getMessageById(locator.id)
+            : locator.messageId
+                ? runtime.store.getMessageByMessageId(locator.messageId)
+                : runtime.store.getMessageByMailboxUid(locator.mailbox, locator.uid);
+        return message ? { account: runtime, message } : null;
+    }
+    for (const runtime of context.accounts) {
+        const message = runtime.store.getMessageByMessageId(locator.messageId);
+        if (message) {
+            return { account: runtime, message };
+        }
+    }
+    return null;
+}
+function encodeMergedCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeMergedCursor(cursor) {
+    if (!cursor) {
+        return null;
+    }
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if ((decoded.sort === "date_asc" || decoded.sort === "date_desc") &&
+            decoded.per &&
+            typeof decoded.per === "object" &&
+            Array.isArray(decoded.done)) {
+            return {
+                sort: decoded.sort,
+                per: decoded.per,
+                done: decoded.done.filter((name) => typeof name === "string")
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function queryAccounts(accounts, filters, mode = "list") {
+    if (mode === "search" && filters.sort === "relevance" && filters.query?.trim()) {
+        return queryAccountsRanked(accounts, filters);
+    }
+    if (filters.sort === "relevance") {
+        filters = { ...filters, sort: "date_desc" };
+    }
+    if (accounts.length === 1) {
+        const runtime = accounts[0];
+        const result = queryStore(runtime, filters, mode);
+        return { items: result.items.map((item) => annotateMessage(item, runtime)), nextCursor: result.nextCursor };
+    }
+    const sort = filters.sort ?? "date_desc";
+    const limit = Math.min(Math.max(Math.trunc(filters.limit ?? 25), 1), 100);
+    const decoded = decodeMergedCursor(filters.cursor);
+    const prior = decoded && decoded.sort === sort ? decoded.per : {};
+    const doneAccounts = new Set(decoded && decoded.sort === sort ? decoded.done : []);
+    const direction = sort === "date_asc" ? 1 : -1;
+    const perAccountResults = accounts.map((runtime) => {
+        const priorEntry = prior[runtime.name];
+        const storeCursor = priorEntry ? encodeCursor(priorEntry, sort) : undefined;
+        const result = doneAccounts.has(runtime.name)
+            ? { items: [], nextCursor: undefined }
+            : queryStore(runtime, { ...filters, limit, cursor: storeCursor }, mode);
+        return { runtime, result, priorEntry: priorEntry ?? null };
+    });
+    const candidates = perAccountResults.flatMap(({ runtime, result }) => result.items.map((item) => annotateMessage(item, runtime)));
+    candidates.sort((a, b) => {
+        if (a.date !== b.date) {
+            return a.date < b.date ? -direction : direction;
+        }
+        if (a.id !== b.id) {
+            return (a.id - b.id) * direction;
+        }
+        return (a.account ?? "").localeCompare(b.account ?? "");
+    });
+    const page = candidates.slice(0, limit);
+    const includedByAccount = new Map();
+    for (const item of page) {
+        const list = includedByAccount.get(item.account ?? "") ?? [];
+        list.push(item);
+        includedByAccount.set(item.account ?? "", list);
+    }
+    const nextPer = {};
+    const nextDone = [];
+    for (const { runtime, result, priorEntry } of perAccountResults) {
+        if (doneAccounts.has(runtime.name)) {
+            nextDone.push(runtime.name);
+            continue;
+        }
+        const included = includedByAccount.get(runtime.name) ?? [];
+        const hasMore = result.nextCursor !== undefined || result.items.length > included.length;
+        if (!hasMore) {
+            nextDone.push(runtime.name);
+            continue;
+        }
+        if (included.length > 0) {
+            const last = included[included.length - 1];
+            nextPer[runtime.name] = { date: last.date, id: last.id };
+        }
+        else {
+            nextPer[runtime.name] = priorEntry;
+        }
+    }
+    return {
+        items: page,
+        nextCursor: Object.keys(nextPer).length > 0 ? encodeMergedCursor({ sort, per: nextPer, done: nextDone }) : undefined
+    };
+}
+function encodeRelevanceCursor(cursor) {
+    return Buffer.from(JSON.stringify(cursor), "utf8").toString("base64url");
+}
+function decodeRelevanceCursor(cursor) {
+    if (!cursor) {
+        return null;
+    }
+    try {
+        const decoded = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+        if (decoded.sort === "relevance" &&
+            decoded.per &&
+            typeof decoded.per === "object" &&
+            Array.isArray(decoded.done)) {
+            const per = Object.fromEntries(Object.entries(decoded.per).filter((entry) => typeof entry[1] === "number" && entry[1] >= 0));
+            return {
+                sort: "relevance",
+                per,
+                done: decoded.done.filter((name) => typeof name === "string")
+            };
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function queryAccountsRanked(accounts, filters) {
+    const limit = Math.min(Math.max(Math.trunc(filters.limit ?? 25), 1), 100);
+    const decoded = decodeRelevanceCursor(filters.cursor);
+    const prior = decoded?.per ?? {};
+    const doneAccounts = new Set(decoded?.done ?? []);
+    const perAccountResults = accounts.map((runtime) => {
+        const offset = prior[runtime.name] ?? 0;
+        if (doneAccounts.has(runtime.name)) {
+            return { runtime, items: [], hasMore: false, offset };
+        }
+        const result = runtime.store.searchRanked(filters, { limit, offset });
+        return {
+            runtime,
+            items: result.items.map((item) => annotateMessage(item, runtime)),
+            hasMore: result.hasMore,
+            offset
+        };
     });
+    const candidates = perAccountResults.flatMap(({ runtime, items }) => items.map((item, position) => ({ item, position, runtime })));
+    candidates.sort((a, b) => a.position - b.position ||
+        (a.item.rank ?? 0) - (b.item.rank ?? 0) ||
+        a.runtime.name.localeCompare(b.runtime.name));
+    const page = candidates.slice(0, limit).map((candidate) => candidate.item);
+    const includedByAccount = new Map();
+    for (const candidate of candidates.slice(0, limit)) {
+        includedByAccount.set(candidate.runtime.name, (includedByAccount.get(candidate.runtime.name) ?? 0) + 1);
+    }
+    const nextPer = {};
+    const nextDone = [];
+    for (const { runtime, items, hasMore, offset } of perAccountResults) {
+        if (doneAccounts.has(runtime.name)) {
+            nextDone.push(runtime.name);
+            continue;
+        }
+        const included = includedByAccount.get(runtime.name) ?? 0;
+        const isDone = !hasMore && included === items.length;
+        if (isDone) {
+            nextDone.push(runtime.name);
+            continue;
+        }
+        nextPer[runtime.name] = offset + included;
+    }
+    return {
+        items: page,
+        nextCursor: Object.keys(nextPer).length > 0
+            ? encodeRelevanceCursor({ sort: "relevance", per: nextPer, done: nextDone })
+            : undefined
+    };
+}
+function queryStore(runtime, filters, mode) {
+    return mode === "search" ? runtime.store.searchMessages(filters) : runtime.store.listMessages(filters);
 }
 function emailLocatorBaseSchema() {
     return z.object({
@@ -169,28 +827,24 @@ function emailLocatorBaseSchema() {
 }
 function messageFilterSchema() {
     return z.object({
+        ...accountSelectorFields,
         mailbox: z.string().min(1).optional(),
+        mailboxes: z.array(z.string().min(1)).optional(),
         from: z.string().min(1).optional(),
         to: z.string().min(1).optional(),
         cc: z.string().min(1).optional(),
         subject: z.string().min(1).optional(),
-        startDate: z.string().datetime().optional(),
-        endDate: z.string().datetime().optional(),
+        startDate: isoDateTime().optional(),
+        endDate: isoDateTime().optional(),
+        last: durationParam,
         hasAttachments: z.boolean().optional(),
         isUnread: z.boolean().optional(),
         isFlagged: z.boolean().optional(),
         limit: z.number().int().positive().max(100).optional(),
         cursor: z.string().min(1).optional(),
-        sort: z.enum(["date_asc", "date_desc"]).optional()
+        sort: z.enum(["date_asc", "date_desc", "relevance"]).optional()
     });
 }
-function findMessage(store, locator) {
-    return locator.id
-        ? store.getMessageById(locator.id)
-        : locator.messageId
-            ? store.getMessageByMessageId(locator.messageId)
-            : store.getMessageByMailboxUid(locator.mailbox, locator.uid);
-}
 function json(value) {
     return {
         content: [