dsh-email 0.17.2 → 0.18.0

package/lib/public-download.js

@@ -0,0 +1,77 @@
+import { lookup } from 'node:dns/promises';
+import { get } from 'node:https';
+import { isIP } from 'node:net';
+export function publicAddress(address) {
+    const lower = address.toLowerCase();
+    if (isIP(lower) === 4) {
+        const [a, b] = lower.split('.').map(Number);
+        return !(a === 0 ||
+            a === 10 ||
+            a === 127 ||
+            a >= 224 ||
+            (a === 169 && b === 254) ||
+            (a === 172 && b >= 16 && b <= 31) ||
+            (a === 192 && (b === 168 || b === 0)) ||
+            (a === 100 && b >= 64 && b <= 127) ||
+            (a === 198 && (b === 18 || b === 19)));
+    }
+    // Global IPv6 unicast only. Mapped/compatible IPv4, loopback, local and multicast are rejected.
+    return (isIP(lower) === 6 && /^[23]/.test(lower) && !lower.startsWith('2001:db8:'));
+}
+/** Download a signed public HTTPS URL without API credentials; pin the validated DNS answers. */
+export async function downloadPublicBytes(input, cap, signal, redirects = 0) {
+    const url = new URL(input);
+    if (url.protocol !== 'https:' ||
+        url.username ||
+        url.password ||
+        (url.port && url.port !== '443') ||
+        redirects > 2)
+        throw new Error('附件下载地址不受支持');
+    const host = url.hostname.replace(/^\[|\]$/g, ''), records = isIP(host)
+        ? [{ address: host, family: isIP(host) }]
+        : await lookup(host, { all: true });
+    if (!records.length ||
+        records.some((record) => !publicAddress(record.address)))
+        throw new Error('附件下载地址必须指向公网 HTTPS 服务');
+    const active = AbortSignal.any([
+        ...(signal ? [signal] : []),
+        AbortSignal.timeout(30000),
+    ]);
+    const res = await new Promise((resolve, reject) => {
+        const req = get(url, {
+            signal: active,
+            lookup: ((_host, options, cb) => {
+                if (options.all)
+                    cb(null, records);
+                else
+                    cb(null, records[0].address, records[0].family);
+            }),
+        }, resolve);
+        req.once('error', reject);
+    });
+    if ([301, 302, 303, 307, 308].includes(res.statusCode ?? 0) &&
+        res.headers.location) {
+        res.destroy();
+        return downloadPublicBytes(new URL(res.headers.location, url).href, cap, active, redirects + 1);
+    }
+    if (res.statusCode !== 200) {
+        res.destroy();
+        throw new Error('附件下载失败，请稍后重试');
+    }
+    const chunks = [];
+    let size = 0;
+    try {
+        for await (const chunk of res) {
+            active.throwIfAborted();
+            const bytes = Buffer.from(chunk);
+            size += bytes.length;
+            if (size > cap)
+                throw new Error('附件超过下载大小上限');
+            chunks.push(bytes);
+        }
+    }
+    finally {
+        res.destroy();
+    }
+    return Buffer.concat(chunks);
+}

package/lib/runtime.d.ts

@@ -1,9 +1,9 @@
 /** Live settings, account-pool ownership, and independent tool/web watch cursors. */
 import { type EmailConfig, type ResolvedEmailSettings } from './config.js';
-import { EmailPool } from './mail-client.js';
+import { EmailService } from './mail-service.js';
 import { type EmailSettingsValue } from './settings.js';
 import type { EmailWatchResult } from './types.js';
-export type EmailClient = Pick<EmailPool, 'list' | 'read' | 'mark' | 'search' | 'send' | 'sendPrepared' | 'reply' | 'folders' | 'downloadAttachment' | 'unseenUids' | 'fetchByUids' | 'startIdleSweep' | 'dispose'>;
+export type EmailClient = Pick<EmailService, 'list' | 'read' | 'mark' | 'search' | 'send' | 'sendPrepared' | 'reply' | 'folders' | 'downloadAttachment' | 'unseenUids' | 'fetchByUids' | 'startIdleSweep' | 'dispose' | 'watchApi'>;
 export interface EmailSettingsScope {
     get(): unknown;
     namespace?: string;

package/lib/runtime.js

@@ -1,6 +1,7 @@
 /** Live settings, account-pool ownership, and independent tool/web watch cursors. */
 import { clampInt, mergeAccountDefaults, presetNamesIn, resolveEmailSettings, serializeAccountsYaml } from './config.js';
-import { EmailPool, messageOf } from './mail-client.js';
+import { messageOf } from './mail-client.js';
+import { EmailService } from './mail-service.js';
 import { EmailSettingsSchema, SETTINGS_NAMESPACE, toEmailConfig, toSettingsBase, validateSettingsValue } from './settings.js';
 import { liveConfig } from './host-config.js';
 function fingerprintSettings(settings) {
@@ -18,7 +19,7 @@ function fingerprintSettings(settings) {
     });
 }
 /** Register live settings and own exactly one pool for their effective value. */
-export function createEmailRuntime(ctx, config, createPool = settings => new EmailPool(settings)) {
+export function createEmailRuntime(ctx, config, createPool = settings => new EmailService(settings)) {
     config = liveConfig(config);
     const legacy = typeof ctx.settings.register === 'function';
     const namespace = legacy ? SETTINGS_NAMESPACE : ctx.fiber?.entry?.options.id ?? 'tool-email';
@@ -40,7 +41,7 @@ export function createEmailRuntime(ctx, config, createPool = settings => new Ema
                     endpointDefaults = { imap: account.imap, smtp: account.smtp };
             }
             catch { /* A fresh installation remains editable before credentials exist. */ }
-            const shared = Object.fromEntries(['provider', 'user', 'password', 'senderName', 'authUser', 'authPassword', 'clientId', 'authKind', 'imap', 'smtp', 'inboxFolder']
+            const shared = Object.fromEntries(['provider', 'user', 'password', 'apiKey', 'senderName', 'authUser', 'authPassword', 'clientId', 'authKind', 'imap', 'smtp', 'inboxFolder']
                 .filter(key => config[key] !== undefined).map(key => [key, config[key]]));
             const cards = config.accounts && Object.keys(config.accounts).length > 0
                 ? Object.fromEntries(Object.entries(config.accounts).map(([key, account]) => [key, mergeAccountDefaults(shared, account)]))
@@ -100,6 +101,9 @@ export function createEmailRuntime(ctx, config, createPool = settings => new Ema
         const pool = getPool();
         // 先只 SEARCH UNSEEN 拿 uid 列表与 totalUnread，再只为本轮要报告的最旧
         // limit 封取信封：网页弹窗每 30 秒轮询一次，不能因为未读多就整批 FETCH。
+        const apiWatch = await pool.watchApi?.(account, folder, capped, scope, signal);
+        if (apiWatch)
+            return apiWatch;
         const index = await pool.unseenUids(account, folder, signal);
         const key = scope + '\u0000' + index.account + '\u0000' + index.folder;
         const stored = watchCursors.get(key);

package/lib/settings.js

@@ -214,7 +214,7 @@ export function validateSettingsValue(value, extraProviders = []) {
         parseRecipientPolicies(draft.trustedRecipientsYaml);
     }
     const provider = draft.provider;
-    if (isSet(provider) && provider !== '' && !PROVIDER_NAMES.includes(provider) && !extraProviders.includes(provider)) {
+    if (isSet(provider) && provider !== '' && !['agentmail', 'agentmail-eu', ...PROVIDER_NAMES].includes(provider) && !extraProviders.includes(provider)) {
         const names = [...PROVIDER_NAMES, ...extraProviders];
         throw new Error('未知的邮箱服务商 ' + describeValue(provider) + '，可选：' + names.join('/') + '（或留空手填 IMAP/SMTP 主机）');
     }

package/lib/tool-contract.d.ts

@@ -10,7 +10,7 @@ export declare const ACCOUNT_HINT = "\u8D26\u53F7\u540D\uFF08\u914D\u7F6E\u4E86
 export declare function parseEmailDay(input: string, label: string, endInclusive?: boolean): Date;
 export declare function executionSignal(exec: unknown): AbortSignal | undefined;
 interface ParameterProperty {
-    type?: string;
+    type?: string | string[];
     required?: boolean;
     description?: string;
     items?: {
@@ -34,7 +34,9 @@ export declare const addrArray: {
 };
 export declare const messageShape: {
     uid: {
-        type: string;
+        oneOf: {
+            type: string;
+        }[];
     };
     date: {
         type: string;
@@ -71,6 +73,18 @@ export declare const listSchema: {
         count: {
             type: string;
         };
+        countExact: {
+            type: string;
+        };
+        hasMore: {
+            type: string;
+        };
+        order: {
+            type: string;
+        };
+        searchSource: {
+            type: string;
+        };
         folder: {
             type: string;
         };
@@ -80,7 +94,9 @@ export declare const listSchema: {
                 type: string;
                 properties: {
                     uid: {
-                        type: string;
+                        oneOf: {
+                            type: string;
+                        }[];
                     };
                     date: {
                         type: string;
@@ -121,7 +137,9 @@ export declare const readSchema: {
             type: string;
         };
         uid: {
-            type: string;
+            oneOf: {
+                type: string;
+            }[];
         };
         folder: {
             type: string;
@@ -233,7 +251,9 @@ export declare const attachmentSchema: {
             type: string;
         };
         uid: {
-            type: string;
+            oneOf: {
+                type: string;
+            }[];
         };
         filename: {
             type: string;
@@ -257,7 +277,9 @@ export declare const markSchema: {
             type: string;
         };
         uid: {
-            type: string;
+            oneOf: {
+                type: string;
+            }[];
         };
         folder: {
             type: string;
@@ -306,7 +328,9 @@ export declare const replySchema: {
             type: string;
         };
         originalUid: {
-            type: string;
+            oneOf: {
+                type: string;
+            }[];
         };
         messageId: {
             type: string;
@@ -359,13 +383,18 @@ export declare const watchSchema: {
         totalUnread: {
             type: string;
         };
+        totalUnreadExact: {
+            type: string;
+        };
         messages: {
             type: string;
             items: {
                 type: string;
                 properties: {
                     uid: {
-                        type: string;
+                        oneOf: {
+                            type: string;
+                        }[];
                     };
                     date: {
                         type: string;

package/lib/tool-contract.js

@@ -35,6 +35,8 @@ export function compileParameters(spec) {
         const node = {};
         if (typeof prop?.type === 'string')
             node.type = prop.type;
+        else if (Array.isArray(prop?.type))
+            node.oneOf = prop.type.map(type => ({ type }));
         if (typeof prop?.description === 'string')
             node.description = prop.description;
         if (prop?.type === 'array' && prop.items !== null && typeof prop.items === 'object') {
@@ -58,7 +60,7 @@ export function normalizeAttachmentPaths(value) {
 export const strArray = { type: 'array', items: { type: 'string' } };
 export const addrArray = { type: 'array', items: { type: 'object', additionalProperties: true } };
 export const messageShape = {
-    uid: { type: 'integer' },
+    uid: { oneOf: [{ type: 'integer' }, { type: 'string' }] },
     date: { type: 'string' },
     from: addrArray,
     subject: { type: 'string' },
@@ -72,6 +74,10 @@ export const listSchema = {
     properties: {
         account: { type: 'string' },
         count: { type: 'integer' },
+        countExact: { type: 'boolean' },
+        hasMore: { type: 'boolean' },
+        order: { type: 'string' },
+        searchSource: { type: 'string' },
         folder: { type: 'string' },
         messages: { type: 'array', items: { type: 'object', properties: messageShape, additionalProperties: true } },
     },
@@ -81,7 +87,7 @@ export const readSchema = {
     type: 'object',
     properties: {
         account: { type: 'string' },
-        uid: { type: 'integer' },
+        uid: { oneOf: [{ type: 'integer' }, { type: 'string' }] },
         folder: { type: 'string' },
         date: { type: 'string' },
         from: addrArray,
@@ -129,7 +135,7 @@ export const attachmentSchema = {
     type: 'object',
     properties: {
         account: { type: 'string' },
-        uid: { type: 'integer' },
+        uid: { oneOf: [{ type: 'integer' }, { type: 'string' }] },
         filename: { type: 'string' },
         contentType: { type: 'string' },
         size: { type: 'integer' },
@@ -141,7 +147,7 @@ export const markSchema = {
     type: 'object',
     properties: {
         account: { type: 'string' },
-        uid: { type: 'integer' },
+        uid: { oneOf: [{ type: 'integer' }, { type: 'string' }] },
         folder: { type: 'string' },
         action: { type: 'string' },
         seen: { type: 'boolean' },
@@ -181,6 +187,8 @@ export function describeMessage(message) {
     return (message.subject || '(无主题)') + ' [' + parts.join(' | ') + ']';
 }
 export function renderList(value) {
+    if (value.countExact !== undefined)
+        return oneText('账号 ' + value.account + '，文件夹 ' + value.folder + '：本页 ' + value.messages.length + ' 封' + (value.hasMore ? '，还有更多' : '') + '（不把 API 页数当作邮箱总数）\n\n' + value.messages.map(describeMessage).join('\n'));
     if (value.messages.length === 0) {
         return oneText('账号 ' + value.account + '，文件夹 "' + value.folder + '" 共 ' + value.count + ' 封邮件，本次没有要列出的邮件。');
     }
@@ -195,6 +203,24 @@ export function renderRead(value) {
     return oneText('账号 ' + value.account + '，主题：' + (value.subject || '(无主题)') + '\n来自：' + from + '\n时间：' + (value.date || '(未知)') + attach + '\n\n' + value.text);
 }
 export function renderSearch(value) {
+    if (value.searchSource === 'api')
+        return oneText('AgentMail 搜索（按相关性，服务排除垃圾箱等特殊邮件）：本页 ' + value.messages.length + ' 条' + (value.hasMore ? '，还有更多；可增加 offset 继续' : '') + '\n\n' + value.messages.map(describeMessage).join('\n'));
+    if (value.headerScan) {
+        const scan = value.headerScan;
+        const window = scan.scanOffset === 0 ? '最近 ' + scan.scanned : '跳过最新 ' + scan.scanOffset + ' 封后的 ' + scan.scanned;
+        const completeness = scan.complete ? '完整信封扫描' : '未覆盖全文件夹';
+        const continuation = scan.nextScanOffset === undefined ? '' : '；继续更早信封可用 headerScanOffset=' + scan.nextScanOffset + '、headerScanLimit=' + scan.scanLimit;
+        const body = value.bodyScan ? '；正文只检查 ' + value.bodyScan.scanned + ' 封（上限 ' + value.bodyScan.scanLimit + '），正文未覆盖全文件夹' : '；未扫描正文';
+        const server = value.serverSearchFailed ? '服务端部分搜索失败' : '服务端候选 ' + (value.serverMatchCount ?? 0) + ' 条';
+        const note = server + '；已扫描' + window + ' 封的信封（文件夹共 ' + scan.mailboxTotal + ' 封，' + completeness + '，窗口内信封命中 ' + scan.matched + ' 条）' + continuation + body;
+        const summary = (value.messages.length ? '本页 ' + value.messages.length + ' 条' : '本页未命中，不能据此断言整个邮箱没有匹配') + (value.offset > 0 ? '，已跳过最新 ' + value.offset + ' 条匹配' : '');
+        const rows = value.messages.map((message, i) => '#' + (i + 1) + ' ' + describeMessage(message));
+        return oneText('账号 ' + value.account + '，在文件夹 "' + value.folder + '" 中搜索 "' + value.query + '"：' + summary + '。' + note + (rows.length ? '\n\n' + rows.join('\n') : ''));
+    }
+    if (value.searchSource === 'server') {
+        const rows = value.messages.map((message, i) => '#' + (i + 1) + ' ' + describeMessage(message));
+        return oneText('账号 ' + value.account + '，在文件夹 "' + value.folder + '" 中搜索 "' + value.query + '"：服务端报告 ' + value.count + ' 个候选；已核实本页 ' + value.messages.length + ' 条（跳过最新 ' + value.offset + ' 条）。' + (rows.length ? '\n\n' + rows.join('\n') : ''));
+    }
     const scanned = value.countKind === 'scanned';
     // 回退扫描只看了最近 scannedLimit 封，不知道全文件夹匹配数：不能把本页条数说成「共 N 条」。
     const scannedNote = '仅扫描最近 ' + (value.scannedLimit ?? 0) + ' 封，未统计全文件夹匹配数';
@@ -242,14 +268,15 @@ export function renderReply(value) {
     return oneText('账号 ' + value.account + ' 已' + REPLY_LABELS[value.mode] + ' uid=' + value.originalUid + ' 的邮件：收件人 ' + value.to.join(', ') + '，主题「' + value.subject + '」，messageId: ' + value.messageId + rejected);
 }
 export function renderWatch(value) {
+    const unread = (value.totalUnreadExact === false ? '本次扫描至少未读 ' : '当前未读 ') + value.totalUnread + ' 封';
     if (value.reset === true) {
         return oneText('账号 ' + value.account + '：文件夹 "' + value.folder + '" 的 UIDVALIDITY 已变化（服务器重新编号了邮件），已重新建立基线（当前未读 ' + value.totalUnread + ' 封）。这次不报告新邮件，之后照常。');
     }
     if (value.firstRun) {
-        return oneText('账号 ' + value.account + '：已建立新邮件监视基线（当前未读 ' + value.totalUnread + ' 封）。之后调用 email_watch 只会报告新到的邮件。');
+        return oneText('账号 ' + value.account + '：已建立新邮件监视基线（' + unread + '）。之后调用 email_watch 只会报告新到的邮件。');
     }
     if (value.newCount === 0) {
-        return oneText('账号 ' + value.account + '：没有新邮件（当前未读 ' + value.totalUnread + ' 封）。');
+        return oneText('账号 ' + value.account + '：没有新邮件（' + unread + '）。');
     }
     const lines = value.messages.map((m, i) => '#' + (i + 1) + ' ' + describeMessage(m));
     return oneText('账号 ' + value.account + ' 有 ' + value.newCount + ' 封新邮件：\n\n' + lines.join('\n') + '\n\n用 email_read 配合 uid 阅读全文。');
@@ -269,7 +296,7 @@ export const replySchema = {
     properties: {
         account: { type: 'string' },
         mode: { type: 'string' },
-        originalUid: { type: 'integer' },
+        originalUid: { oneOf: [{ type: 'integer' }, { type: 'string' }] },
         messageId: { type: 'string' },
         accepted: strArray,
         rejected: strArray,
@@ -288,20 +315,21 @@ export const watchSchema = {
         reset: { type: 'boolean' },
         newCount: { type: 'integer' },
         totalUnread: { type: 'integer' },
+        totalUnreadExact: { type: 'boolean' },
         messages: { type: 'array', items: { type: 'object', properties: messageShape, additionalProperties: true } },
     },
     additionalProperties: true,
 };
 export const descriptions = {
-    "email_list": 'List recent emails in a mailbox folder (newest first). Returns uid, date, sender, subject and flags without message bodies; use email_read with a uid to fetch the full text. Optional since/until (dates like 2026-08-01) filter by received date.',
+    "email_list": 'IMAP uid is a positive integer; AgentMail uid is an opaque string message_id. AgentMail returns page counts: inspect hasMore/countExact instead of assuming mailbox totals. List recent emails in a mailbox folder (newest first). Returns uid, date, sender, subject and flags without message bodies; use email_read with a uid to fetch the full text. Optional since/until (dates like 2026-08-01) filter by received date.',
     "email_read": 'Read one full email message by its uid (from email_list or email_search). Returns the plain-text body (HTML mail is converted; oversized bodies are truncated) plus attachment metadata; use email_attachment to download one.',
-    "email_mark": 'Change an existing message: mark it read/unread, star/unstar it, or move it to another folder. Use after email_list/email_search when the user wants to tidy the mailbox (archive, clear unread, flag important mail). Moving uses the server MOVE/COPY so the uid changes; the new uid is reported when the server provides it.',
-    "email_search": 'Search emails by a keyword. The server first searches sender, recipients and subject; those hits are re-verified against the envelopes and, when none of them really carries the keyword (some servers answer every search with the same uids), recent messages are scanned locally including their body while bodySearchFallback is enabled. offset skips the newest matches for paging; since/until still constrain both paths. Returns the same compact rows as email_list.',
-    "email_send": 'Send an email from a configured account, optionally with file attachments (absolute paths, or relative to the current session workspace; process cwd is the fallback without a session). Saved blocked-address/domain rules reject To/Cc recipients even when sendApproval is off. Plugin confirmation is required by default, unless sendApproval is disabled or every To/Cc recipient matches saved trust rules with skipApproval enabled. Host permissions still apply. Full Access refuses a send that still requires plugin confirmation; use email_draft for human review and explicit sending. Never invent recipients or content without the user\'s instruction.',
-    "email_reply": 'Reply to, reply-all to, or forward an existing message (mode: reply | reply-all | forward). Recipients come from the original message (your own address is excluded automatically), the subject gets a single Re:/Fwd: prefix, the original text is quoted underneath, and In-Reply-To/References headers keep mail clients threading correctly. mode=forward needs the to parameter. Plugin confirmation is required unless sendApproval is disabled; trusted-recipient skipping only applies to email_send. Blocked recipients still stop delivery before SMTP and host permissions remain in effect. Never invent recipients or content without the user\'s instruction.',
+    "email_mark": 'AgentMail supports flags and only INBOX-to-Archive label archiving; arbitrary IMAP moves are not supported there. Change an existing message: mark it read/unread, star/unstar it, or move it to another folder. Use after email_list/email_search when the user wants to tidy the mailbox (archive, clear unread, flag important mail). Moving uses the server MOVE/COPY so the uid changes; the new uid is reported when the server provides it.',
+    "email_search": 'AgentMail accounts use API relevance search (searchSource=api), exclude spam/trash/blocked/unauthenticated mail, and page with offset; headerScanOffset and IMAP fallbacks do not apply. For IMAP: Search sender, recipients and subject; verify server candidates against envelopes and arrival dates. If server SEARCH is empty, fails, or has no confirmed matches, scan local headers in batches without downloading bodies/attachments (default newest 5000, max 20000). headerScanOffset/Limit select an older header window; use headerScan.nextScanOffset to continue. offset pages MATCHES within that window. If no headers match and headerScanOffset=0, optional body fallback scans only bodySearchLimit recent arrivals. Inspect searchSource/headerScan/bodyScan: partial or zero results never prove the whole mailbox has no match. Results use descending mailbox UID arrival order, not Date-header or INTERNALDATE sorting. since/until filter INTERNALDATE (Date header only if unavailable).',
+    "email_send": 'AgentMail has a plugin limit of 10 attachments / 4 MiB total and uses its inbox API; a receipt means submission, not delivery. Send an email from a configured account, optionally with file attachments (absolute paths, or relative to the current session workspace; process cwd is the fallback without a session). Saved blocked-address/domain rules reject To/Cc recipients even when sendApproval is off. Plugin confirmation is required by default, unless sendApproval is disabled or every To/Cc recipient matches saved trust rules with skipApproval enabled. Host permissions still apply. Full Access refuses a send that still requires plugin confirmation; use email_draft for human review and explicit sending. Never invent recipients or content without the user\'s instruction.',
+    "email_reply": 'AgentMail reply/reply-all uses its thread-aware reply API; forwarding creates a new message. Reply to, reply-all to, or forward an existing message (mode: reply | reply-all | forward). Recipients come from the original message (your own address is excluded automatically), the subject gets a single Re:/Fwd: prefix, the original text is quoted underneath, and In-Reply-To/References headers keep mail clients threading correctly. mode=forward needs the to parameter. Plugin confirmation is required unless sendApproval is disabled; trusted-recipient skipping only applies to email_send. Blocked recipients still stop delivery before SMTP and host permissions remain in effect. Never invent recipients or content without the user\'s instruction.',
     "email_folders": 'List the mailbox folders of an account (INBOX, Sent, Trash, custom folders, ...). Use the returned path values as the folder argument of the other email tools.',
-    "email_health": 'Self-check for dsh-email: summarizes configured accounts (provider / IMAP / SMTP hosts) without any network connection and never shows passwords. Run this first when troubleshooting.',
-    "email_attachment": 'Download one attachment of a message to a local file (size capped by maxAttachmentBytes). The index matches the attachments array of email_read. Returns the absolute path of the written file.',
+    "email_health": 'AgentMail accounts show fixed regional API endpoints instead of IMAP/SMTP servers. Self-check for dsh-email: summarizes configured accounts (provider / IMAP / SMTP hosts) without any network connection and never shows passwords. Run this first when troubleshooting.',
+    "email_attachment": 'AgentMail downloads are limited to 20 MiB or the smaller configured maximum. Download one attachment of a message to a local file (size capped by maxAttachmentBytes). The index matches the attachments array of email_read. Returns the absolute path of the written file.',
     "email_watch": 'Check for NEW unread emails since the last check (cursor-based). The first call per account+folder sets the baseline and reports nothing as new; every later call returns only unseen unread messages. Call this periodically (e.g. via a scheduled task) to notify the user about new mail. Returns newCount, the new messages, and totalUnread.'
 };
 export const parameters = {
@@ -315,12 +343,12 @@ export const parameters = {
         account: { type: 'string', description: ACCOUNT_HINT },
     }),
     "email_read": compileParameters({
-        uid: { type: 'integer', required: true, description: 'Message uid from email_list or email_search' },
+        uid: { type: ['integer', 'string'], required: true, description: 'IMAP positive integer uid or unchanged AgentMail string message_id from email_list or email_search' },
         folder: { type: 'string', description: 'IMAP folder the uid belongs to; defaults to the account inboxFolder' },
         account: { type: 'string', description: ACCOUNT_HINT },
     }),
     "email_mark": compileParameters({
-        uid: { type: 'integer', required: true, description: 'Message uid from email_list or email_search' },
+        uid: { type: ['integer', 'string'], required: true, description: 'IMAP positive integer uid or unchanged AgentMail string message_id from email_list or email_search' },
         action: { type: 'string', required: true, description: 'What to do: read, unread, star, unstar, or move' },
         toFolder: { type: 'string', description: 'Destination folder path for action=move (see email_folders for valid paths)' },
         folder: { type: 'string', description: 'IMAP folder the uid belongs to; defaults to the account inboxFolder' },
@@ -331,6 +359,8 @@ export const parameters = {
         folder: { type: 'string', description: 'IMAP folder to search in; defaults to the account inboxFolder' },
         limit: { type: 'integer', description: 'How many matches to return, 1-100, default 10' },
         offset: { type: 'integer', description: 'Skip this many newest matches first, default 0' },
+        headerScanLimit: { type: 'integer', description: 'Local header fallback window size, 1-20000; default 5000. Headers only, no bodies or attachments.' },
+        headerScanOffset: { type: 'integer', description: 'Skip this many newest arrivals for the local header window; default 0. Continue with headerScan.nextScanOffset. Independent of match offset; a nonzero value skips body fallback.' },
         since: { type: 'string', description: 'Only search messages received on or after this date, e.g. 2026-08-01 (optional)' },
         until: { type: 'string', description: 'Only search messages received on or before this date, e.g. 2026-08-26 (optional)' },
         account: { type: 'string', description: ACCOUNT_HINT },
@@ -344,7 +374,7 @@ export const parameters = {
         account: { type: 'string', description: ACCOUNT_HINT },
     }),
     "email_reply": compileParameters({
-        uid: { type: 'integer', required: true, description: 'Message uid to answer/forward, from email_list or email_search' },
+        uid: { type: ['integer', 'string'], required: true, description: 'IMAP positive integer uid or unchanged AgentMail string message_id to answer/forward, from email_list or email_search' },
         text: { type: 'string', required: true, description: 'The new text to write; the original is quoted below it automatically' },
         mode: { type: 'string', description: 'reply (default), reply-all, or forward' },
         to: { type: 'string', description: 'Recipient(s) for mode=forward, comma-separated' },
@@ -358,7 +388,7 @@ export const parameters = {
     }),
     "email_health": compileParameters({}),
     "email_attachment": compileParameters({
-        uid: { type: 'integer', required: true, description: 'Message uid from email_list or email_search' },
+        uid: { type: ['integer', 'string'], required: true, description: 'IMAP positive integer uid or unchanged AgentMail string message_id from email_list or email_search' },
         index: { type: 'integer', description: '0-based attachment index, as listed by email_read; default 0' },
         folder: { type: 'string', description: 'IMAP folder the uid belongs to; defaults to the account inboxFolder' },
         account: { type: 'string', description: ACCOUNT_HINT },

package/lib/tools.js

@@ -6,6 +6,7 @@ import { descriptions, parameters, MAX_LIMIT, MARK_ACTIONS, REPLY_MODES, executi
 /** 单次工具调用的 deadline：普通查询 60s，正文扫描/watch 这类整批操作 120s。 */
 const QUERY_TIMEOUT_MS = 60000;
 const BATCH_TIMEOUT_MS = 120000;
+function validUid(uid) { return typeof uid === 'number' ? Number.isSafeInteger(uid) && uid > 0 : typeof uid === 'string' && uid.length > 0 && uid.length <= 998 && !/[\r\n\0]/.test(uid); }
 function attachmentPaths(value, exec) {
     const context = exec;
     const cwd = context?.agent?.session?.header?.cwd;
@@ -52,8 +53,8 @@ export function buildEmailTools(runtime, drafts) {
             timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
-                if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
-                    throw new Error('uid 必须是正整数（用 email_list 获取）');
+                if (!validUid(args.uid)) {
+                    throw new Error('uid 必须是正整数（IMAP）或 email_list 返回的字符串邮件标识（AgentMail）');
                 }
                 return await getPool().read(args.account, args.uid, args.folder?.trim() || '', executionSignal(exec));
             }
@@ -69,8 +70,8 @@ export function buildEmailTools(runtime, drafts) {
             timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
-                if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
-                    throw new Error('uid 必须是正整数（用 email_list 获取）');
+                if (!validUid(args.uid)) {
+                    throw new Error('uid 必须是正整数（IMAP）或 email_list 返回的字符串邮件标识（AgentMail）');
                 }
                 const action = (typeof args.action === 'string' ? args.action.trim().toLowerCase() : '');
                 if (!MARK_ACTIONS.includes(action)) {
@@ -99,7 +100,10 @@ export function buildEmailTools(runtime, drafts) {
                 const offset = clampInt(args.offset, 0, 0, 10000);
                 const since = args.since?.trim() ? parseEmailDay(args.since, 'since') : undefined;
                 const until = args.until?.trim() ? parseEmailDay(args.until, 'until', true) : undefined;
-                return await getPool().search(args.account, args.query.trim(), args.folder?.trim() || '', limit, offset, since, until, executionSignal(exec));
+                return await getPool().search(args.account, args.query.trim(), args.folder?.trim() || '', limit, offset, since, until, executionSignal(exec), {
+                    headerScanLimit: clampInt(args.headerScanLimit, 5000, 1, 20000),
+                    headerScanOffset: clampInt(args.headerScanOffset, 0, 0, 1_000_000_000),
+                });
             }
         },
         {
@@ -128,8 +132,8 @@ export function buildEmailTools(runtime, drafts) {
             timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
-                if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
-                    throw new Error('uid 必须是正整数（用 email_list 获取）');
+                if (!validUid(args.uid)) {
+                    throw new Error('uid 必须是正整数（IMAP）或 email_list 返回的字符串邮件标识（AgentMail）');
                 }
                 if (typeof args.text !== 'string' || args.text.trim() === '')
                     throw new Error('text 不能为空');
@@ -172,7 +176,7 @@ export function buildEmailTools(runtime, drafts) {
                     const entries = [...effective.accounts.entries()];
                     for (const [accountName, account] of entries.slice(0, 8)) {
                         const provider = Object.entries(PROVIDER_PRESETS).find(([, preset]) => (preset.imap.host === account.imap.host && preset.smtp.host === account.smtp.host))?.[0] ?? 'custom';
-                        const base = provider + ' / ' + account.user + ' / IMAP ' + account.imap.host + ' / SMTP ' + account.smtp.host;
+                        const base = account.transport === 'agentmail' ? 'AgentMail / ' + account.user + ' / ' + account.apiBase : provider + ' / ' + account.user + ' / IMAP ' + account.imap.host + ' / SMTP ' + account.smtp.host;
                         // An OAuth2 account with no token is configured, not broken: the
                         // missing piece is a browser login, and saying so is the whole
                         // point of this check.
@@ -211,8 +215,8 @@ export function buildEmailTools(runtime, drafts) {
             timeoutMs: QUERY_TIMEOUT_MS,
             async execute(rawArgs, exec) {
                 const args = rawArgs;
-                if (typeof args.uid !== 'number' || !Number.isInteger(args.uid) || args.uid <= 0) {
-                    throw new Error('uid 必须是正整数（用 email_list 获取）');
+                if (!validUid(args.uid)) {
+                    throw new Error('uid 必须是正整数（IMAP）或 email_list 返回的字符串邮件标识（AgentMail）');
                 }
                 const index = clampInt(args.index, 0, 0, 999);
                 const workspaceHint = typeof exec?.agent?.session?.header?.cwd === 'string' ? exec.agent.session.header.cwd : undefined;