dsh-email 0.10.2 → 0.10.3

package/lib/mail-client.d.ts

@@ -66,7 +66,7 @@ export declare class EmailPool {
     resolveName(name?: string): string;
     /** Serialize operations per account: one IMAP connection serves one op at a time. */
     private enqueue;
-    withImap<T>(accountName: string | undefined, folder: string | null, run: (client: ImapFlow) => Promise<T>, readOnly?: boolean): Promise<T>;
+    withImap<T>(accountName: string | undefined, folder: string | null, run: (client: ImapFlow) => Promise<T>, readOnly?: boolean, signal?: AbortSignal): Promise<T>;
     private createImap;
     private imapRun;
     private normalizeImapError;
@@ -75,20 +75,22 @@ export declare class EmailPool {
     startIdleSweep(): void;
     dispose(): void;
     private transporter;
-    list(accountName: string | undefined, folder: string, limit: number, offset: number, unreadOnly: boolean, since?: Date, until?: Date): Promise<EmailListResult>;
-    search(accountName: string | undefined, query: string, folder: string, limit: number, since?: Date, until?: Date): Promise<EmailSearchResult>;
+    /** Send through the pooled transporter while making cancellation close it. */
+    private sendMail;
+    list(accountName: string | undefined, folder: string, limit: number, offset: number, unreadOnly: boolean, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailListResult>;
+    search(accountName: string | undefined, query: string, folder: string, limit: number, since?: Date, until?: Date, signal?: AbortSignal): Promise<EmailSearchResult>;
     /** Client-side scan of the tail of the mailbox, newest first. */
     private searchBodies;
     private fetchListed;
-    read(accountName: string | undefined, uid: number, folder: string): Promise<EmailReadResult>;
-    mark(accountName: string | undefined, folder: string, uid: number, action: EmailMarkAction, toFolder?: string): Promise<EmailMarkResult>;
-    folders(accountName: string | undefined, subscribedOnly: boolean): Promise<EmailFoldersResult>;
-    downloadAttachment(accountName: string | undefined, folder: string, uid: number, index: number, workspaceHint?: string): Promise<EmailAttachmentResult>;
-    send(accountName: string | undefined, to: string, subject: string, text: string | undefined, cc: string | undefined, attachmentPaths: string[] | undefined): Promise<EmailSendResult>;
-    reply(accountName: string | undefined, folder: string, uid: number, mode: EmailReplyMode, text: string, forwardTo: string, cc: string | undefined): Promise<EmailReplyResult>;
+    read(accountName: string | undefined, uid: number, folder: string, signal?: AbortSignal): Promise<EmailReadResult>;
+    mark(accountName: string | undefined, folder: string, uid: number, action: EmailMarkAction, toFolder?: string, signal?: AbortSignal): Promise<EmailMarkResult>;
+    folders(accountName: string | undefined, subscribedOnly: boolean, signal?: AbortSignal): Promise<EmailFoldersResult>;
+    downloadAttachment(accountName: string | undefined, folder: string, uid: number, index: number, workspaceHint?: string, signal?: AbortSignal): Promise<EmailAttachmentResult>;
+    send(accountName: string | undefined, to: string, subject: string, text: string | undefined, cc: string | undefined, attachmentPaths: string[] | undefined, signal?: AbortSignal): Promise<EmailSendResult>;
+    reply(accountName: string | undefined, folder: string, uid: number, mode: EmailReplyMode, text: string, forwardTo: string, cc: string | undefined, signal?: AbortSignal): Promise<EmailReplyResult>;
 }
 /** Stat every attachment path up front; total size must stay under the cap. */
-export declare function validateAttachmentPaths(paths: string[], maxBytes: number): Promise<Array<{
+export declare function validateAttachmentPaths(paths: string[], maxBytes: number, signal?: AbortSignal): Promise<Array<{
     path: string;
 }>>;
 export {};

package/lib/mail-client.js

@@ -194,16 +194,20 @@ export class EmailPool {
         return name?.trim() || this.settings.defaultAccount;
     }
     /** Serialize operations per account: one IMAP connection serves one op at a time. */
-    enqueue(name, task) {
+    enqueue(name, task, signal) {
         const prev = this.queues.get(name) ?? Promise.resolve();
-        const next = prev.then(task, task);
+        const run = async () => {
+            signal?.throwIfAborted();
+            return task();
+        };
+        const next = prev.then(run, run);
         this.queues.set(name, next.then(() => undefined, () => undefined));
         return next;
     }
-    async withImap(accountName, folder, run, readOnly = true) {
+    async withImap(accountName, folder, run, readOnly = true, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
-        return this.enqueue(name, () => this.imapRun(name, cfg, folder, readOnly, run));
+        return this.enqueue(name, () => this.imapRun(name, cfg, folder, readOnly, run, signal), signal);
     }
     createImap(cfg) {
         const client = new ImapFlow({
@@ -230,35 +234,55 @@ export class EmailPool {
         });
         return client;
     }
-    async imapRun(name, cfg, folder, readOnly, run) {
+    async imapRun(name, cfg, folder, readOnly, run, signal) {
         let entry = this.imaps.get(name);
+        let activeClient = entry?.client;
+        const onAbort = () => {
+            // ImapFlow has no per-command AbortSignal option. Closing the owned
+            // connection is its cooperative cancellation mechanism and makes the
+            // in-flight command settle before this method returns.
+            try {
+                activeClient?.close();
+            }
+            catch { /* already closed */ }
+        };
+        signal?.throwIfAborted();
+        signal?.addEventListener('abort', onAbort, { once: true });
         try {
             if (entry === undefined || !entry.client.usable) {
                 if (entry !== undefined)
                     await this.evictImap(name);
                 const client = this.createImap(cfg);
+                activeClient = client;
+                signal?.throwIfAborted();
                 await client.connect();
+                signal?.throwIfAborted();
                 entry = { client, selected: null, selectedReadOnly: true, lastUsed: Date.now(), inUse: 0 };
                 this.imaps.set(name, entry);
             }
+            activeClient = entry.client;
             entry.lastUsed = Date.now();
             entry.inUse += 1;
             // Reopen when the folder changes or when the caller needs a different
             // access mode (email_mark writes flags / moves messages).
             if (folder !== null && (entry.selected !== folder || entry.selectedReadOnly !== readOnly)) {
                 await entry.client.mailboxOpen(folder, { readOnly });
+                signal?.throwIfAborted();
                 entry.selected = folder;
                 entry.selectedReadOnly = readOnly;
             }
             const result = await run(entry.client);
+            signal?.throwIfAborted();
             entry.lastUsed = Date.now();
             return result;
         }
         catch (error) {
             await this.evictImap(name);
+            signal?.throwIfAborted();
             throw this.normalizeImapError(error, folder);
         }
         finally {
+            signal?.removeEventListener('abort', onAbort);
             if (entry !== undefined)
                 entry.inUse = Math.max(0, entry.inUse - 1);
         }
@@ -328,7 +352,30 @@ export class EmailPool {
         }
         return t;
     }
-    async list(accountName, folder, limit, offset, unreadOnly, since, until) {
+    /** Send through the pooled transporter while making cancellation close it. */
+    async sendMail(name, cfg, message, signal) {
+        signal?.throwIfAborted();
+        const transporter = this.transporter(name, cfg);
+        const onAbort = () => {
+            if (this.smtps.get(name) === transporter)
+                this.smtps.delete(name);
+            transporter.close();
+        };
+        signal?.addEventListener('abort', onAbort, { once: true });
+        try {
+            const info = await transporter.sendMail(message);
+            signal?.throwIfAborted();
+            return info;
+        }
+        catch (error) {
+            signal?.throwIfAborted();
+            throw error;
+        }
+        finally {
+            signal?.removeEventListener('abort', onAbort);
+        }
+    }
+    async list(accountName, folder, limit, offset, unreadOnly, since, until, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
@@ -347,21 +394,23 @@ export class EmailPool {
                 if (until !== undefined)
                     query.before = until;
                 const found = await client.search(query, { uid: true });
+                signal?.throwIfAborted();
                 uids = found === false ? [] : found;
                 scopeCount = uids.length;
             }
             else if (total > 0) {
                 const start = Math.max(1, total - (limit + offset) + 1);
                 const fetched = await client.fetchAll(start + ':*', { uid: true });
+                signal?.throwIfAborted();
                 uids = fetched.map(message => message.uid);
             }
             uids.reverse();
             const window = uids.slice(offset, offset + limit);
-            const messages = await this.fetchListed(client, window);
+            const messages = await this.fetchListed(client, window, signal);
             return { account: name, count: scopeCount, folder: folderName, messages };
-        });
+        }, true, signal);
     }
-    async search(accountName, query, folder, limit, since, until) {
+    async search(accountName, query, folder, limit, since, until, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
@@ -380,30 +429,38 @@ export class EmailPool {
                 client.search({ to: query, ...dateRange }, { uid: true }),
                 client.search({ cc: query, ...dateRange }, { uid: true }),
             ]);
+            signal?.throwIfAborted();
             const uids = [...new Set(found.flatMap(result => result === false ? [] : result))].sort((a, b) => a - b);
             uids.reverse();
             if (uids.length === 0 && this.settings.bodySearchFallback) {
                 // Server-side search found nothing: fall back to a client-side scan of
                 // the most recent messages (subject/from/body), capped for time.
-                const messages = await this.searchBodies(client, query, folderName, limit);
+                const messages = await this.searchBodies(client, query, folderName, limit, since, until, signal);
                 return { account: name, query, count: messages.length, folder: folderName, messages };
             }
-            const messages = await this.fetchListed(client, uids.slice(0, limit));
+            const messages = await this.fetchListed(client, uids.slice(0, limit), signal);
             return { account: name, query, count: uids.length, folder: folderName, messages };
-        });
+        }, true, signal);
     }
     /** Client-side scan of the tail of the mailbox, newest first. */
-    async searchBodies(client, query, folder, limit) {
+    async searchBodies(client, query, folder, limit, since, until, signal) {
+        signal?.throwIfAborted();
         const mailbox = client.mailbox;
         const total = mailbox === false ? 0 : mailbox.exists;
         if (total === 0)
             return [];
         const start = Math.max(1, total - this.settings.bodySearchLimit + 1);
-        const fetched = await client.fetchAll(start + ':*', { uid: true, envelope: true, flags: true, size: true, bodyStructure: true, source: true });
+        const fetched = await client.fetchAll(start + ':*', { uid: true, envelope: true, flags: true, size: true, bodyStructure: true, source: true, internalDate: true });
         const out = [];
         for (const message of [...fetched].reverse()) {
+            signal?.throwIfAborted();
             if (out.length >= limit)
                 break;
+            const receivedAt = message.internalDate ?? message.envelope?.date;
+            if (since !== undefined && (receivedAt === undefined || receivedAt < since))
+                continue;
+            if (until !== undefined && (receivedAt === undefined || receivedAt >= until))
+                continue;
             const subject = message.envelope?.subject ?? '';
             const recipientSearchText = [message.envelope?.from, message.envelope?.to, message.envelope?.cc]
                 .map(flattenAddressText).join(' ');
@@ -411,9 +468,11 @@ export class EmailPool {
             if (message.source !== undefined) {
                 try {
                     const parsed = await parseRawMessage(message.source, 4096);
+                    signal?.throwIfAborted();
                     body = parsed.text;
                 }
-                catch {
+                catch (error) {
+                    signal?.throwIfAborted();
                     // 单封邮件解析失败不应中断整批回退扫描，继续用 subject/from/to/cc 匹配。
                 }
             }
@@ -423,15 +482,17 @@ export class EmailPool {
         }
         return out;
     }
-    async fetchListed(client, uids) {
+    async fetchListed(client, uids, signal) {
+        signal?.throwIfAborted();
         if (uids.length === 0)
             return [];
         const fetched = await client.fetchAll(uids, { uid: true, envelope: true, flags: true, size: true, bodyStructure: true }, { uid: true });
+        signal?.throwIfAborted();
         return fetched
             .map(message => listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)))
             .sort((a, b) => b.uid - a.uid);
     }
-    async read(accountName, uid, folder) {
+    async read(accountName, uid, folder, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
@@ -441,15 +502,17 @@ export class EmailPool {
                 throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
             }
             const body = await parseRawMessage(message.source, this.settings.maxBodyChars);
+            signal?.throwIfAborted();
             return { account: name, uid, folder: folderName, ...body };
-        });
+        }, true, signal);
     }
-    async mark(accountName, folder, uid, action, toFolder) {
+    async mark(accountName, folder, uid, action, toFolder, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
         return this.withImap(name, folderName, async (client) => {
             const before = await client.fetchOne(uid, { uid: true, flags: true }, { uid: true });
+            signal?.throwIfAborted();
             if (before === false) {
                 throw new MailError('找不到 uid=' + uid + ' 的邮件（可能已被删除，或不在文件夹 "' + folderName + '"；可用 email_list 重新获取 uid）');
             }
@@ -457,18 +520,22 @@ export class EmailPool {
             let flagged = before.flags?.has('\\Flagged') === true;
             if (action === 'read' && !seen) {
                 await client.messageFlagsAdd(uid, ['\\Seen'], { uid: true });
+                signal?.throwIfAborted();
                 seen = true;
             }
             else if (action === 'unread' && seen) {
                 await client.messageFlagsRemove(uid, ['\\Seen'], { uid: true });
+                signal?.throwIfAborted();
                 seen = false;
             }
             else if (action === 'star' && !flagged) {
                 await client.messageFlagsAdd(uid, ['\\Flagged'], { uid: true });
+                signal?.throwIfAborted();
                 flagged = true;
             }
             else if (action === 'unstar' && flagged) {
                 await client.messageFlagsRemove(uid, ['\\Flagged'], { uid: true });
+                signal?.throwIfAborted();
                 flagged = false;
             }
             else if (action === 'move') {
@@ -478,10 +545,12 @@ export class EmailPool {
                 if (target === folderName)
                     throw new MailError('邮件已在文件夹 "' + folderName + '" 中，无需移动');
                 const folders = await client.list();
+                signal?.throwIfAborted();
                 if (!folders.some(row => row.path === target)) {
                     throw new MailError('找不到目标文件夹 "' + target + '"，可用：' + folders.map(row => row.path).join('、'));
                 }
                 const moved = await client.messageMove(uid, target, { uid: true });
+                signal?.throwIfAborted();
                 if (moved === false)
                     throw new MailError('移动 uid=' + uid + ' 到 "' + target + '" 失败（服务器拒绝了 MOVE/COPY）');
                 const result = { account: name, uid, folder: folderName, action, seen, flagged, movedTo: target };
@@ -491,12 +560,13 @@ export class EmailPool {
                 return result;
             }
             return { account: name, uid, folder: folderName, action, seen, flagged };
-        }, false);
+        }, false, signal);
     }
-    async folders(accountName, subscribedOnly) {
+    async folders(accountName, subscribedOnly, signal) {
         const name = this.resolveName(accountName);
         return this.withImap(name, null, async (client) => {
             const list = await client.list();
+            signal?.throwIfAborted();
             const folders = list
                 .filter(row => !subscribedOnly || row.subscribed !== false)
                 .map(row => ({
@@ -506,9 +576,9 @@ export class EmailPool {
                 subscribed: row.subscribed !== false,
             }));
             return { account: name, folders };
-        });
+        }, true, signal);
     }
-    async downloadAttachment(accountName, folder, uid, index, workspaceHint) {
+    async downloadAttachment(accountName, folder, uid, index, workspaceHint, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
@@ -520,6 +590,7 @@ export class EmailPool {
             // The mailparser list is authoritative for the index email_read showed;
             // the bodyStructure walk supplies the IMAP part to download.
             const body = await parseRawMessage(message.source, this.settings.maxBodyChars);
+            signal?.throwIfAborted();
             const parts = collectAttachmentParts(message.bodyStructure);
             if (body.attachments.length === 0)
                 throw new MailError('该邮件没有附件');
@@ -534,7 +605,8 @@ export class EmailPool {
                 throw new MailError('附件 "' + att.filename + '" 大小 ' + att.size + ' 字节，超过上限 maxAttachmentBytes=' + this.settings.maxAttachmentBytes);
             }
             const dl = await client.download(uid, att.part, { uid: true, maxBytes: this.settings.maxAttachmentBytes });
-            const buf = await collectStream(dl.content, this.settings.maxAttachmentBytes);
+            signal?.throwIfAborted();
+            const buf = await collectStream(dl.content, this.settings.maxAttachmentBytes, signal);
             const safeName = sanitizeFilename(dl.meta.filename ?? att.filename ?? body.attachments[index].filename);
             // Default the destination to the session workspace so the model can
             // read the file back; an explicit downloadDir always wins.
@@ -544,32 +616,34 @@ export class EmailPool {
                     ? join(workspaceHint, '.dsh-email-downloads')
                     : this.settings.downloadDir);
             await mkdir(dir, { recursive: true });
+            signal?.throwIfAborted();
             const dest = await uniquePath(join(dir, safeName));
-            await writeFile(dest, buf);
+            signal?.throwIfAborted();
+            await writeFile(dest, buf, signal === undefined ? undefined : { signal });
             return { account: name, uid, filename: safeName, contentType: att.contentType, size: buf.length, path: dest };
-        });
+        }, true, signal);
     }
-    async send(accountName, to, subject, text, cc, attachmentPaths) {
+    async send(accountName, to, subject, text, cc, attachmentPaths, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
-        const attachments = await validateAttachmentPaths(attachmentPaths ?? [], this.settings.maxAttachmentBytes);
-        const info = await this.transporter(name, cfg).sendMail({
+        const attachments = await validateAttachmentPaths(attachmentPaths ?? [], this.settings.maxAttachmentBytes, signal);
+        const info = await this.sendMail(name, cfg, {
             from: cfg.user,
             to,
             cc,
             subject,
             text: text ?? '',
             attachments,
-        });
+        }, signal);
         return {
             account: name,
-            messageId: info.messageId,
-            accepted: info.accepted.map(String),
-            rejected: info.rejected.map(String),
-            response: info.response,
+            messageId: typeof info.messageId === 'string' ? info.messageId : String(info.messageId ?? ''),
+            accepted: Array.isArray(info.accepted) ? info.accepted.map(String) : [],
+            rejected: Array.isArray(info.rejected) ? info.rejected.map(String) : [],
+            response: typeof info.response === 'string' ? info.response : String(info.response ?? ''),
         };
     }
-    async reply(accountName, folder, uid, mode, text, forwardTo, cc) {
+    async reply(accountName, folder, uid, mode, text, forwardTo, cc, signal) {
         const name = this.resolveName(accountName);
         const cfg = this.account(name);
         const folderName = folder || cfg.inboxFolder;
@@ -582,9 +656,10 @@ export class EmailPool {
             }
             const ids = extractMessageIds(message.source);
             const body = await parseRawMessage(message.source, this.settings.maxBodyChars);
+            signal?.throwIfAborted();
             return buildReplyMessage({ from: body.from, to: body.to, cc: body.cc, subject: body.subject, date: body.date, text: body.text, messageId: ids.messageId, references: ids.references }, mode, cfg.user, text, forwardTo);
-        });
-        const info = await this.transporter(name, cfg).sendMail({
+        }, true, signal);
+        const info = await this.sendMail(name, cfg, {
             from: cfg.user,
             to: built.to,
             cc,
@@ -592,25 +667,26 @@ export class EmailPool {
             text: built.text,
             ...(built.inReplyTo !== undefined ? { inReplyTo: '<' + built.inReplyTo + '>' } : {}),
             ...(built.references !== undefined ? { references: built.references.split(' ').map(id => '<' + id + '>') } : {}),
-        });
+        }, signal);
         return {
             account: name,
             mode,
             originalUid: uid,
-            messageId: info.messageId,
-            accepted: info.accepted.map(String),
-            rejected: info.rejected.map(String),
-            response: info.response,
+            messageId: typeof info.messageId === 'string' ? info.messageId : String(info.messageId ?? ''),
+            accepted: Array.isArray(info.accepted) ? info.accepted.map(String) : [],
+            rejected: Array.isArray(info.rejected) ? info.rejected.map(String) : [],
+            response: typeof info.response === 'string' ? info.response : String(info.response ?? ''),
             to: built.to.split(',').map(part => part.trim()).filter(part => part !== ''),
             subject: built.subject,
         };
     }
 }
 /** Stat every attachment path up front; total size must stay under the cap. */
-export async function validateAttachmentPaths(paths, maxBytes) {
+export async function validateAttachmentPaths(paths, maxBytes, signal) {
     const out = [];
     let total = 0;
     for (const rawPath of paths) {
+        signal?.throwIfAborted();
         if (typeof rawPath !== 'string' || rawPath.trim() === '') {
             throw new MailError('附件路径无效：' + String(rawPath));
         }
@@ -622,6 +698,7 @@ export async function validateAttachmentPaths(paths, maxBytes) {
         catch {
             throw new MailError('附件路径不存在或不可读：' + path);
         }
+        signal?.throwIfAborted();
         if (!info.isFile())
             throw new MailError('附件路径不是文件：' + path);
         total += info.size;
@@ -633,17 +710,29 @@ export async function validateAttachmentPaths(paths, maxBytes) {
     return out;
 }
 /** Drain a download stream into a Buffer with a hard byte cap. */
-async function collectStream(stream, maxBytes) {
+async function collectStream(stream, maxBytes, signal) {
     const chunks = [];
     let total = 0;
-    for await (const chunk of stream) {
-        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
-        total += buf.length;
-        if (total > maxBytes)
-            throw new MailError('附件超过上限 maxAttachmentBytes=' + maxBytes + ' 字节，下载中止');
-        chunks.push(buf);
-    }
-    return Buffer.concat(chunks);
+    const onAbort = () => {
+        stream.destroy(signal?.reason instanceof Error ? signal.reason : new Error('邮件附件下载已取消'));
+    };
+    signal?.throwIfAborted();
+    signal?.addEventListener('abort', onAbort, { once: true });
+    try {
+        for await (const chunk of stream) {
+            signal?.throwIfAborted();
+            const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            total += buf.length;
+            if (total > maxBytes)
+                throw new MailError('附件超过上限 maxAttachmentBytes=' + maxBytes + ' 字节，下载中止');
+            chunks.push(buf);
+        }
+        signal?.throwIfAborted();
+        return Buffer.concat(chunks);
+    }
+    finally {
+        signal?.removeEventListener('abort', onAbort);
+    }
 }
 /** Avoid overwriting: append -1, -2, ... before the extension. */
 async function uniquePath(path) {

package/lib/runtime.d.ts

@@ -0,0 +1,36 @@
+/** 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 { type EmailSettingsValue } from './settings.js';
+import type { EmailWatchResult } from './types.js';
+export type EmailClient = Pick<EmailPool, 'list' | 'read' | 'mark' | 'search' | 'send' | 'reply' | 'folders' | 'downloadAttachment' | 'startIdleSweep' | 'dispose'>;
+export interface EmailSettingsScope {
+    get(): unknown;
+}
+export interface EmailRuntimeContext {
+    settings: {
+        register(namespace: string, schema: unknown, options: {
+            base: Partial<EmailSettingsValue>;
+            applies: 'live';
+            validate(value: unknown): void;
+        }): EmailSettingsScope;
+        describe?(): Array<{
+            ns: string;
+            user?: Partial<EmailSettingsValue>;
+        }>;
+    };
+    effect(effect: () => () => void): unknown;
+    logger?: {
+        warn?(message: string): void;
+    };
+}
+export interface EmailRuntime {
+    readonly settingsScope: EmailSettingsScope;
+    getSettingsValue(): EmailSettingsValue;
+    getEffectiveSettings(): ResolvedEmailSettings;
+    getPool(): EmailClient;
+    watch(account: string, folder: string, limit: number, scope: string, signal?: AbortSignal): Promise<EmailWatchResult>;
+    dispose(): void;
+}
+/** Register live settings and own exactly one pool for their effective value. */
+export declare function createEmailRuntime(ctx: EmailRuntimeContext, config: EmailConfig, createPool?: (settings: ResolvedEmailSettings) => EmailClient): EmailRuntime;

package/lib/runtime.js

@@ -0,0 +1,92 @@
+/** Live settings, account-pool ownership, and independent tool/web watch cursors. */
+import { clampInt, resolveEmailSettings } from './config.js';
+import { EmailPool, messageOf } from './mail-client.js';
+import { EmailSettingsSchema, SETTINGS_NAMESPACE, toEmailConfig, toSettingsBase, validateSettingsValue } from './settings.js';
+function fingerprintSettings(settings) {
+    return JSON.stringify({
+        accounts: [...settings.accounts.entries()].map(([name, account]) => [name, account]),
+        defaultAccount: settings.defaultAccount,
+        sendApproval: settings.sendApproval,
+        maxBodyChars: settings.maxBodyChars,
+        downloadDir: settings.downloadDir,
+        downloadDirExplicit: settings.downloadDirExplicit,
+        maxAttachmentBytes: settings.maxAttachmentBytes,
+        bodySearchFallback: settings.bodySearchFallback,
+        bodySearchLimit: settings.bodySearchLimit,
+        idleTimeoutMs: settings.idleTimeoutMs,
+    });
+}
+/** Register live settings and own exactly one pool for their effective value. */
+export function createEmailRuntime(ctx, config, createPool = settings => new EmailPool(settings)) {
+    const settingsScope = ctx.settings.register(SETTINGS_NAMESPACE, EmailSettingsSchema, {
+        base: toSettingsBase(config),
+        applies: 'live',
+        validate: value => validateSettingsValue(value),
+    });
+    const getSettingsValue = () => settingsScope.get();
+    const getEffectiveSettings = () => {
+        // Form defaults must not overwrite row settings or provider presets.
+        const descriptor = (ctx.settings.describe?.() ?? []).find(row => row.ns === SETTINGS_NAMESPACE);
+        return resolveEmailSettings({ ...config, ...toEmailConfig(getSettingsValue(), descriptor?.user) });
+    };
+    let pool = null;
+    let poolFingerprint = '';
+    let disposed = false;
+    const getPool = () => {
+        if (disposed)
+            throw new Error('dsh-email 已卸载，不能继续使用邮箱连接池。');
+        const effective = getEffectiveSettings();
+        const fingerprint = fingerprintSettings(effective);
+        if (pool === null || fingerprint !== poolFingerprint) {
+            pool?.dispose();
+            pool = createPool(effective);
+            pool.startIdleSweep();
+            poolFingerprint = fingerprint;
+        }
+        return pool;
+    };
+    // Tool and browser watches share the implementation but never consume each
+    // other's cursor. The first call per scope/account/folder seeds a baseline.
+    const watchCursors = new Map();
+    const watch = async (account, folder, limit, scope, signal) => {
+        const capped = clampInt(limit, 20, 1, 100);
+        const result = await getPool().list(account, folder, 100, 0, true, undefined, undefined, signal);
+        const key = scope + '\u0000' + result.account + '\u0000' + result.folder;
+        const isFirst = !watchCursors.has(key);
+        const cursor = watchCursors.get(key) ?? 0;
+        const fresh = result.messages.filter(message => message.uid > cursor);
+        if (result.messages.length > 0) {
+            watchCursors.set(key, Math.max(cursor, ...result.messages.map(message => message.uid)));
+        }
+        else if (isFirst) {
+            watchCursors.set(key, 0);
+        }
+        return {
+            account: result.account,
+            folder: result.folder,
+            firstRun: isFirst,
+            newCount: isFirst ? 0 : fresh.length,
+            messages: (isFirst ? [] : fresh).slice(0, capped),
+            totalUnread: result.count,
+        };
+    };
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        pool?.dispose();
+        pool = null;
+        poolFingerprint = '';
+        watchCursors.clear();
+    };
+    // Missing credentials never prevent plugin registration. Account tools and
+    // email_health provide the configuration details when invoked.
+    try {
+        getPool();
+    }
+    catch (error) {
+        ctx.logger?.warn?.('[dsh-email] ' + messageOf(error, '未配置邮箱账号'));
+    }
+    ctx.effect(() => dispose);
+    return { settingsScope, getSettingsValue, getEffectiveSettings, getPool, watch, dispose };
+}