dsh-email 0.17.3 → 0.18.0

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,8 @@ 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;
@@ -258,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 阅读全文。');
@@ -285,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,
@@ -304,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 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": '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 = {
@@ -331,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' },
@@ -362,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' },
@@ -376,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)) {
@@ -131,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 不能为空');
@@ -175,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.
@@ -214,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;

package/lib/types.d.ts

@@ -5,7 +5,7 @@ export interface AddressEntry {
 }
 /** One listed message: everything cheap to fetch without the body. */
 export interface ListedMessage {
-    uid: number;
+    uid: number | string;
     /** ISO 8601 string, or '' when unknown. */
     date: string;
     from: AddressEntry[];
@@ -36,6 +36,9 @@ export interface ReadMessageBody {
     truncated: boolean;
 }
 export interface EmailListResult {
+    countExact?: boolean;
+    hasMore?: boolean;
+    order?: 'relevance';
     account: string;
     count: number;
     folder: string;
@@ -45,8 +48,9 @@ export interface EmailListResult {
 }
 export interface EmailReadResult extends ReadMessageBody {
     account: string;
-    uid: number;
+    uid: number | string;
     folder: string;
+    uidValidity?: number;
 }
 export interface EmailSearchOptions {
     /** Local header window; independent of result offset and bodySearchLimit. */
@@ -63,6 +67,9 @@ export interface EmailHeaderScan {
     nextScanOffset?: number;
 }
 export interface EmailSearchResult {
+    countExact?: boolean;
+    hasMore?: boolean;
+    order?: 'relevance';
     account: string;
     query: string;
     /** Server candidates, local header-window matches, or body-fallback page rows; inspect searchSource and coverage. */
@@ -75,7 +82,7 @@ export interface EmailSearchResult {
     countKind?: 'scanned';
     /** Header rows actually scanned, or the configured body window for legacy renderers. */
     scannedLimit?: number;
-    searchSource?: 'server' | 'local-headers' | 'local-body';
+    searchSource?: 'server' | 'local-headers' | 'local-body' | 'api';
     serverMatchCount?: number;
     serverSearchFailed?: boolean;
     headerScan?: EmailHeaderScan;
@@ -103,7 +110,7 @@ export interface EmailFoldersResult {
 }
 export interface EmailAttachmentResult {
     account: string;
-    uid: number;
+    uid: number | string;
     filename: string;
     contentType: string;
     size: number;
@@ -123,7 +130,7 @@ export interface EmailListArgs extends AccountArg {
     until?: string;
 }
 export interface EmailReadArgs extends AccountArg {
-    uid: number;
+    uid: number | string;
     folder?: string;
 }
 export interface EmailSearchArgs extends AccountArg {
@@ -148,7 +155,7 @@ export interface EmailFoldersArgs extends AccountArg {
     subscribedOnly?: boolean;
 }
 export interface EmailAttachmentArgs extends AccountArg {
-    uid: number;
+    uid: number | string;
     /** 0-based index into the attachments of email_read. Default 0. */
     index?: number;
     folder?: string;
@@ -160,7 +167,7 @@ export interface EmailWatchArgs extends AccountArg {
 }
 export type EmailMarkAction = 'read' | 'unread' | 'star' | 'unstar' | 'move';
 export interface EmailMarkArgs extends AccountArg {
-    uid: number;
+    uid: number | string;
     action: EmailMarkAction;
     /** Target folder path; only used (and required) when action is 'move'. */
     toFolder?: string;
@@ -168,7 +175,7 @@ export interface EmailMarkArgs extends AccountArg {
 }
 export interface EmailMarkResult {
     account: string;
-    uid: number;
+    uid: number | string;
     folder: string;
     action: EmailMarkAction;
     seen: boolean;
@@ -180,7 +187,7 @@ export interface EmailMarkResult {
 }
 export type EmailReplyMode = 'reply' | 'reply-all' | 'forward';
 export interface EmailReplyArgs extends AccountArg {
-    uid: number;
+    uid: number | string;
     /** The new text to write; the original is quoted below it automatically. */
     text: string;
     mode?: EmailReplyMode;
@@ -193,7 +200,7 @@ export interface EmailReplyResult {
     account: string;
     mode: EmailReplyMode;
     /** uid of the original message that was answered/forwarded. */
-    originalUid: number;
+    originalUid: number | string;
     messageId: string;
     accepted: string[];
     rejected: string[];
@@ -202,6 +209,7 @@ export interface EmailReplyResult {
     subject: string;
 }
 export interface EmailWatchResult {
+    totalUnreadExact?: boolean;
     account: string;
     folder: string;
     /** True on the first call for this account+folder: it sets the baseline. */

package/lib/web.d.ts

@@ -175,7 +175,8 @@ export declare class EmailSettingsBackend {
     private readonly ctx;
     private readonly scope;
     private readonly rowConfig;
-    constructor(ctx: any, scope: any, rowConfig: EmailConfig);
+    private readonly apiFetch?;
+    constructor(ctx: any, scope: any, rowConfig: EmailConfig, apiFetch?: typeof fetch | undefined);
     /** Wired by apply(): the email_watch core; 'web' keeps its own cursor scope. */
     watchImpl?: (account: string, folder: string, limit: number, scope: string) => Promise<EmailWatchResult>;
     private get namespace();
@@ -262,11 +263,18 @@ export declare class EmailSettingsBackend {
      * what was actually tried — including on failure.
      */
     test(value: EmailSettingsValue, accountName?: string): Promise<{
+        ok: boolean;
+        account: string;
+        apiHost: "https://api.agentmail.to" | "https://api.agentmail.eu" | undefined;
+        message: string;
+    } | {
         account: string;
         imapHost: string;
         imapPort: number;
         ok: boolean;
         ms: number;
+        apiHost?: undefined;
+        message?: undefined;
     }>;
     /**
      * Resolve one named account of the *stored* settings — the same accounts the

package/lib/web.js

@@ -6,6 +6,7 @@ import { SETTINGS_NAMESPACE, toEmailConfig, validateSettingsValue } from './sett
 import { isOAuth2Account, OUTLOOK_OAUTH2_CLIENT_ID, parseAccountsYaml, parseServerPresets, presetNamesIn, PROVIDER_PRESETS, resolveEmailSettings, serializeAccountsYaml, } from './config.js';
 import { clearTokenFor, getFreshAccessToken, oauth2StateOf, pollDeviceFlow, startDeviceFlow, } from './oauth2.js';
 import { EmailPool, messageOf, redactCredentials } from './mail-client.js';
+import { AgentMailClient } from './agentmail.js';
 /** Same-origin route the browser settings section talks to. */
 export const SETTINGS_ROUTE = '/_dsh/dsh-email/settings';
 /** Same-origin route serving the whale-girl courier image to the widget. */
@@ -98,7 +99,7 @@ function buildAccountCards(raw, defaultAccount, presets, tokens = () => ({ state
             provider: providerName,
             ...(preset?.label !== undefined && preset.label !== '' ? { providerLabel: preset.label } : {}),
             user,
-            hasPassword: typeof account.password === 'string' && account.password !== '',
+            hasPassword: typeof account.password === 'string' && account.password !== '' || typeof account.apiKey === 'string' && account.apiKey !== '',
             authKind,
             ...(pinned === 'oauth2' || pinned === 'password' ? { authKindDeclared: pinned } : {}),
             ...(clientId !== '' ? { clientId } : {}),
@@ -308,6 +309,8 @@ function washEndpoint(account, key) {
 function persistedProvider(provider, customNames) {
     if (typeof provider !== 'string' || provider === '')
         return undefined;
+    if (provider === 'agentmail' || provider === 'agentmail-eu')
+        return provider;
     if (Object.prototype.hasOwnProperty.call(PROVIDER_PRESETS, provider))
         return provider;
     return customNames.has(provider) ? provider : undefined;
@@ -520,6 +523,15 @@ function serializeAccountsDraft(source, cards, defaultAccount, customNames) {
         // never written — a stored copy is washed out below instead.
         const previousProvider = account.get('provider');
         const nextProvider = persistedProvider(card.provider, customNames);
+        const apiProvider = (value) => value === 'agentmail' || value === 'agentmail-eu';
+        if (apiProvider(previousProvider) !== apiProvider(nextProvider)) {
+            account.delete('password');
+            account.delete('apiKey');
+            account.delete('authPassword');
+            account.delete('authKind');
+        }
+        if (card.password !== undefined && apiProvider(nextProvider))
+            account.delete('apiKey');
         writeField(account, 'provider', nextProvider);
         writeField(account, 'user', card.user);
         // senderName / authUser are plain three-state fields (undefined = 保持原样,
@@ -749,10 +761,12 @@ export class EmailSettingsBackend {
     ctx;
     scope;
     rowConfig;
-    constructor(ctx, scope, rowConfig) {
+    apiFetch;
+    constructor(ctx, scope, rowConfig, apiFetch) {
         this.ctx = ctx;
         this.scope = scope;
         this.rowConfig = rowConfig;
+        this.apiFetch = apiFetch;
     }
     /** Wired by apply(): the email_watch core; 'web' keeps its own cursor scope. */
     watchImpl;
@@ -886,6 +900,10 @@ export class EmailSettingsBackend {
         if (cfg === undefined) {
             throw new Error(`未知账号 "${name}"，可用：${available.join('、')}`);
         }
+        if (cfg.transport === 'agentmail') {
+            await new AgentMailClient(settings, this.apiFetch).test(name);
+            return { ok: true, account: name, apiHost: cfg.apiBase, message: 'AgentMail API 连接成功 / AgentMail API connection successful' };
+        }
         const target = { account: name, imapHost: cfg.imap.host, imapPort: cfg.imap.port };
         const targetDescription = '账号 "' + name + '" · IMAP ' + cfg.imap.host + ':' + cfg.imap.port;
         // An OAuth2 account has no password to check: without a token there is

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "dsh-email",
-  "version": "0.17.3",
-  "description": "在 DSH 中收发、搜索和整理邮件，支持多个邮箱账号。",
+  "version": "0.18.0",
+  "description": "在 DSH 中浏览、收发、搜索和整理邮件，支持 IMAP/SMTP 与 AgentMail 多账号。",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
@@ -34,7 +34,8 @@
     "dsh",
     "email",
     "imap",
-    "smtp"
+    "smtp",
+    "agentmail"
   ],
   "author": "stardustlc",
   "repository": {