dsh-email 0.17.3 → 0.18.0

package/lib/mail-client.js

@@ -920,7 +920,7 @@ export class EmailPool {
             return messageMatchesQuery(envelope?.subject ?? '', addressText, '', query);
         })
             .map(message => listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)))
-            .sort((a, b) => b.uid - a.uid);
+            .sort((a, b) => Number(b.uid) - Number(a.uid));
     }
     /** Client-side scan of the tail of the mailbox, newest first. */
     async searchBodies(client, query, folder, limit, offset, since, until, signal) {
@@ -983,7 +983,7 @@ export class EmailPool {
         signal?.throwIfAborted();
         return fetched
             .map(message => listedFrom(message, message.size, structureHasAttachment(message.bodyStructure)))
-            .sort((a, b) => b.uid - a.uid);
+            .sort((a, b) => Number(b.uid) - Number(a.uid));
     }
     async read(accountName, uid, folder, signal) {
         const name = this.resolveName(accountName);
@@ -1015,6 +1015,7 @@ export class EmailPool {
                             account: name,
                             uid,
                             folder: folderName,
+                            uidValidity: this.uidValidityOf(client),
                             date: envelopeDate instanceof Date ? envelopeDate.toISOString() : '',
                             from: flattenAddresses(message.envelope.from),
                             to: flattenAddresses(message.envelope.to),
@@ -1040,7 +1041,7 @@ export class EmailPool {
             const body = await parseRawMessage(full.source, this.settings.maxBodyChars);
             signal?.throwIfAborted();
             this.rememberRead(name, folderName, this.uidValidityOf(client), uid, { attachments: body.attachments, parts: collectAttachmentParts(full.bodyStructure) });
-            return { account: name, uid, folder: folderName, ...body };
+            return { account: name, uid, folder: folderName, uidValidity: this.uidValidityOf(client), ...body };
         }, true, signal);
     }
     async mark(accountName, folder, uid, action, toFolder, signal) {
@@ -1191,11 +1192,25 @@ export class EmailPool {
         };
     }
     /** Send the attachment bytes the human reviewed, without re-reading mutable paths. */
-    async sendPrepared(accountName, to, subject, text, cc, attachments, signal) {
+    async sendPrepared(accountName, to, subject, text, cc, attachments, signal, reply) {
         const name = this.resolveName(accountName), cfg = this.account(name);
         if (attachments.length > 10 || attachments.reduce((sum, file) => sum + file.content.length, 0) > Math.min(this.settings.maxAttachmentBytes, 20 * 1024 * 1024))
             throw new MailError('草稿附件超过大小或数量上限');
-        const info = await this.sendMail(name, cfg, { from: senderOf(cfg), to, cc, subject, text, attachments, disableFileAccess: true, disableUrlAccess: true }, signal);
+        const thread = {};
+        if (reply)
+            await this.withImap(name, reply.folder || cfg.inboxFolder, async (client) => {
+                if (reply.uidValidity !== undefined && reply.uidValidity !== this.uidValidityOf(client))
+                    throw new MailError('原文件夹 UIDVALIDITY 已变化，无法关联旧回复草稿；请重新打开邮件准备回复');
+                const original = await client.fetchOne(reply.uid, { uid: true, headers: ['message-id', 'references'] }, { uid: true });
+                if (!original || !original.headers)
+                    throw new MailError('原邮件不存在或缺少线程头，请重新打开邮件');
+                const ids = extractMessageIds(original.headers);
+                if (!ids.messageId)
+                    throw new MailError('原邮件缺少 Message-ID，无法安全关联回复线程');
+                thread.inReplyTo = '<' + ids.messageId + '>';
+                thread.references = [...(ids.references ?? '').split(' ').filter(Boolean), ids.messageId].map(id => '<' + id + '>');
+            }, true, signal);
+        const info = await this.sendMail(name, cfg, { from: senderOf(cfg), to, cc, subject, text, attachments, ...thread, disableFileAccess: true, disableUrlAccess: true }, signal);
         return { account: name, messageId: String(info.messageId ?? ''), accepted: Array.isArray(info.accepted) ? info.accepted.map(String) : [], rejected: Array.isArray(info.rejected) ? info.rejected.map(String) : [], response: String(info.response ?? '') };
     }
     async reply(accountName, folder, uid, mode, text, forwardTo, cc, signal) {

package/lib/mail-service.d.ts

@@ -0,0 +1,50 @@
+import { EmailPool } from './mail-client.js';
+import { type MessageRef } from './agentmail.js';
+import type { ResolvedEmailSettings } from './config.js';
+import type { EmailFoldersResult, EmailReplyMode, EmailReplyResult, EmailMarkAction, EmailSearchOptions } from './types.js';
+import type { downloadPublicBytes } from './public-download.js';
+export interface ReplyReference {
+    uid: MessageRef;
+    folder: string;
+    uidValidity?: number;
+}
+export interface MailDependencies {
+    fetch?: typeof fetch;
+    download?: typeof downloadPublicBytes;
+}
+/** Route accounts independently. IMAP's numeric UIDs retain their original meaning. */
+export declare class EmailService {
+    private settings;
+    private imap;
+    private api;
+    constructor(settings: ResolvedEmailSettings, dependencies?: MailDependencies);
+    get withImap(): EmailPool['withImap'];
+    set withImap(run: EmailPool['withImap']);
+    private name;
+    private usesApi;
+    private number;
+    private folder;
+    list(account: string | undefined, folder: string, limit: number, offset: number, unread: boolean, since?: Date, until?: Date, signal?: AbortSignal): Promise<import("./types.js").EmailListResult>;
+    read(account: string | undefined, uid: MessageRef, folder: string, signal?: AbortSignal): Promise<import("./types.js").EmailReadResult>;
+    search(account: string | undefined, query: string, folder: string, limit: number, offset: number, since?: Date, until?: Date, signal?: AbortSignal, options?: EmailSearchOptions): Promise<import("./types.js").EmailSearchResult>;
+    mark(account: string | undefined, folder: string, uid: MessageRef, action: EmailMarkAction, target?: string, signal?: AbortSignal): Promise<import("./types.js").EmailMarkResult>;
+    folders(account: string | undefined, subscribed: boolean, signal?: AbortSignal): Promise<EmailFoldersResult>;
+    downloadAttachment(account: string | undefined, folder: string, uid: MessageRef, index: number, workspace?: string, signal?: AbortSignal): Promise<import("./types.js").EmailAttachmentResult>;
+    send(account: string | undefined, to: string, subject: string, text: string | undefined, cc: string | undefined, paths: string[] | undefined, signal?: AbortSignal): Promise<import("./types.js").EmailSendResult>;
+    sendPrepared(account: string, to: string, subject: string, text: string, cc: string, attachments: Array<{
+        filename: string;
+        content: Buffer;
+    }>, signal?: AbortSignal, reply?: ReplyReference): Promise<import("./types.js").EmailSendResult>;
+    reply(account: string | undefined, folder: string, uid: MessageRef, mode: EmailReplyMode, text: string, to: string, cc: string | undefined, signal?: AbortSignal): Promise<EmailReplyResult>;
+    unseenUids(...args: Parameters<EmailPool['unseenUids']>): Promise<{
+        account: string;
+        folder: string;
+        uidValidity: number;
+        count: number;
+        uids: number[];
+    }>;
+    fetchByUids(...args: Parameters<EmailPool['fetchByUids']>): Promise<import("./types.js").ListedMessage[]>;
+    watchApi(account: string, folder: string, limit: number, scope: string, signal?: AbortSignal): Promise<import("./types.js").EmailWatchResult | undefined>;
+    startIdleSweep(): void;
+    dispose(): void;
+}

package/lib/mail-service.js

@@ -0,0 +1,128 @@
+import { EmailPool, buildReplyMessage, validateAttachmentPaths, } from './mail-client.js';
+import { AgentMailClient } from './agentmail.js';
+/** Route accounts independently. IMAP's numeric UIDs retain their original meaning. */
+export class EmailService {
+    settings;
+    imap;
+    api;
+    constructor(settings, dependencies = {}) {
+        this.settings = settings;
+        this.imap = new EmailPool(settings);
+        this.api = new AgentMailClient(settings, dependencies.fetch, dependencies.download);
+    }
+    get withImap() {
+        return this.imap.withImap.bind(this.imap);
+    }
+    set withImap(run) {
+        this.imap.withImap = run;
+    }
+    name(account) {
+        const name = account || this.settings.defaultAccount;
+        if (!this.settings.accounts.has(name))
+            throw new Error('未知邮件账号');
+        return name;
+    }
+    usesApi(account) {
+        return (this.settings.accounts.get(this.name(account))?.transport === 'agentmail');
+    }
+    number(uid) {
+        if (typeof uid !== 'number' || !Number.isSafeInteger(uid) || uid <= 0)
+            throw new Error('IMAP uid 必须是正整数');
+        return uid;
+    }
+    folder(account, folder) {
+        return folder || this.settings.accounts.get(this.name(account)).inboxFolder;
+    }
+    list(account, folder, limit, offset, unread, since, until, signal) {
+        return this.usesApi(account)
+            ? this.api.list(this.name(account), this.folder(account, folder), limit, offset, unread, since, until, signal)
+            : this.imap.list(account, folder, limit, offset, unread, since, until, signal);
+    }
+    read(account, uid, folder, signal) {
+        return this.usesApi(account)
+            ? this.api.read(this.name(account), uid, this.folder(account, folder), signal)
+            : this.imap.read(account, this.number(uid), folder, signal);
+    }
+    search(account, query, folder, limit, offset, since, until, signal, options = {}) {
+        if (this.usesApi(account) && options.headerScanOffset)
+            throw new Error('AgentMail 搜索使用 offset 分页，不使用 IMAP headerScanOffset');
+        return this.usesApi(account)
+            ? this.api.search(this.name(account), query, this.folder(account, folder), limit, offset, since, until, signal)
+            : this.imap.search(account, query, folder, limit, offset, since, until, signal, options);
+    }
+    mark(account, folder, uid, action, target, signal) {
+        return this.usesApi(account)
+            ? this.api.mark(this.name(account), this.folder(account, folder), uid, action, target, signal)
+            : this.imap.mark(account, folder, this.number(uid), action, target, signal);
+    }
+    async folders(account, subscribed, signal) {
+        if (!this.usesApi(account))
+            return this.imap.folders(account, subscribed, signal);
+        signal?.throwIfAborted();
+        return {
+            account: this.name(account),
+            folders: [
+                ['INBOX', '\\Inbox'],
+                ['Sent', '\\Sent'],
+                ['Starred', '\\Flagged'],
+                ['Archive', '\\Archive'],
+                ['All', '\\All'],
+            ].map(([path, specialUse]) => ({
+                name: path,
+                path,
+                specialUse,
+                subscribed: true,
+            })),
+        };
+    }
+    downloadAttachment(account, folder, uid, index, workspace, signal) {
+        return this.usesApi(account)
+            ? this.api.downloadAttachment(this.name(account), folder, uid, index, workspace, signal)
+            : this.imap.downloadAttachment(account, folder, this.number(uid), index, workspace, signal);
+    }
+    async send(account, to, subject, text, cc, paths, signal) {
+        if (!this.usesApi(account))
+            return this.imap.send(account, to, subject, text, cc, paths, signal);
+        await validateAttachmentPaths(paths ?? [], Math.min(this.settings.maxAttachmentBytes, 4 * 1024 * 1024), signal);
+        return this.api.sendPaths(this.name(account), to, subject, text ?? '', cc ?? '', paths ?? [], signal);
+    }
+    sendPrepared(account, to, subject, text, cc, attachments, signal, reply) {
+        return this.usesApi(account)
+            ? this.api.send(this.name(account), to, subject, text, cc, attachments, signal, reply)
+            : this.imap.sendPrepared(account, to, subject, text, cc, attachments, signal, reply ? { ...reply, uid: this.number(reply.uid) } : undefined);
+    }
+    async reply(account, folder, uid, mode, text, to, cc, signal) {
+        if (!this.usesApi(account))
+            return this.imap.reply(account, folder, this.number(uid), mode, text, to, cc, signal);
+        const name = this.name(account), cfg = this.settings.accounts.get(name), original = await this.api.read(name, uid, this.folder(account, folder), signal), built = buildReplyMessage({ ...original, messageId: String(uid), references: '' }, mode, cfg.user, text, to), sent = await this.api.send(name, built.to, built.subject, built.text, cc ?? '', [], signal, mode === 'forward' ? undefined : { uid, folder });
+        return {
+            ...sent,
+            mode,
+            originalUid: uid,
+            to: built.to.split(','),
+            subject: built.subject,
+        };
+    }
+    unseenUids(...args) {
+        if (this.usesApi(args[0]))
+            throw new Error('AgentMail 使用独立的新邮件游标');
+        return this.imap.unseenUids(...args);
+    }
+    fetchByUids(...args) {
+        if (this.usesApi(args[0]))
+            throw new Error('AgentMail 不支持 IMAP 数字 UID 批量读取，请使用列表中的 message_id');
+        return this.imap.fetchByUids(...args);
+    }
+    async watchApi(account, folder, limit, scope, signal) {
+        return this.usesApi(account)
+            ? this.api.watch(this.name(account), this.folder(account, folder), limit, scope, signal)
+            : undefined;
+    }
+    startIdleSweep() {
+        this.imap.startIdleSweep();
+    }
+    dispose() {
+        this.imap.dispose();
+        this.api.clear();
+    }
+}

package/lib/mailbox-web.d.ts

@@ -0,0 +1,11 @@
+import type { EmailRuntime } from './runtime.js';
+import type { EmailDraftBackend } from './draft-web.js';
+export declare const MAILBOX_ROUTE = "/api/dsh-email/mailbox";
+export declare class EmailMailboxBackend {
+    private runtime;
+    private drafts;
+    constructor(runtime: Pick<EmailRuntime, 'getEffectiveSettings' | 'getPool'>, drafts: EmailDraftBackend);
+    action(body: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+    fetch(request: Request): Promise<Response>;
+}
+export declare function installEmailMailbox(ctx: any, backend: EmailMailboxBackend): void;

package/lib/mailbox-web.js

@@ -0,0 +1,219 @@
+import { readFile, unlink } from 'node:fs/promises';
+import { buildReplyMessage } from './mail-client.js';
+import { draftFields } from './draft-store.js';
+import { parseEmailDay } from './tool-contract.js';
+import { clampInt } from './config.js';
+export const MAILBOX_ROUTE = '/api/dsh-email/mailbox';
+const json = (status, value) => new Response(JSON.stringify(value), {
+    status,
+    headers: {
+        'content-type': 'application/json',
+        'cache-control': 'no-store',
+    },
+});
+export class EmailMailboxBackend {
+    runtime;
+    drafts;
+    constructor(runtime, drafts) {
+        this.runtime = runtime;
+        this.drafts = drafts;
+    }
+    async action(body, signal) {
+        const settings = this.runtime.getEffectiveSettings(), account = typeof body.account === 'string' && body.account
+            ? body.account
+            : settings.defaultAccount, cfg = settings.accounts.get(account);
+        if (!cfg)
+            throw new Error('账号不存在，请重新选择');
+        if (body.action === 'accounts')
+            return {
+                accounts: [...settings.accounts].map(([name, c]) => ({
+                    name,
+                    user: c.user,
+                    api: c.transport === 'agentmail',
+                })),
+                defaultAccount: settings.defaultAccount,
+            };
+        const pool = this.runtime.getPool(), folder = typeof body.folder === 'string' && body.folder
+            ? body.folder
+            : cfg.inboxFolder;
+        if (folder.length > 1024 || /[\r\n\0]/.test(folder))
+            throw new Error('无效文件夹');
+        if (body.action === 'folders')
+            return pool.folders(account, false, signal);
+        if (body.action === 'list') {
+            const limit = clampInt(body.limit, 20, 1, 100), offset = clampInt(body.offset, 0, 0, 10000);
+            const since = typeof body.since === 'string' && body.since
+                ? parseEmailDay(body.since, 'since')
+                : undefined, until = typeof body.until === 'string' && body.until
+                ? parseEmailDay(body.until, 'until', true)
+                : undefined;
+            const query = typeof body.query === 'string' ? body.query.trim() : '';
+            if (query.length > 500)
+                throw new Error('搜索词过长');
+            return query
+                ? pool.search(account, query, folder, limit, offset, since, until, signal, {
+                    headerScanOffset: clampInt(body.headerScanOffset, 0, 0, 1_000_000_000),
+                })
+                : pool.list(account, folder, limit, offset, body.unreadOnly === true, since, until, signal);
+        }
+        const uid = body.uid;
+        if (!((typeof uid === 'number' && Number.isSafeInteger(uid) && uid > 0) ||
+            (typeof uid === 'string' &&
+                uid.length > 0 &&
+                uid.length <= 998 &&
+                !/[\r\n\0]/.test(uid))))
+            throw new Error('请从邮件列表重新选择邮件');
+        if (body.action === 'read')
+            return pool.read(account, uid, folder, signal);
+        if (body.action === 'mark') {
+            if (!['read', 'unread', 'star', 'unstar'].includes(String(body.mark)))
+                throw new Error('不支持的邮件状态操作');
+            return pool.mark(account, folder, uid, body.mark, undefined, signal);
+        }
+        if (body.action === 'replyDraft') {
+            const original = await pool.read(account, uid, folder, signal), mode = body.replyAll === true ? 'reply-all' : 'reply';
+            const built = buildReplyMessage({ ...original, messageId: '', references: '' }, mode, [cfg.user, cfg.authUser], '');
+            const created = await this.drafts.store.create(draftFields({
+                account,
+                to: built.to,
+                cc: '',
+                subject: built.subject,
+                text: built.text,
+            }), [], signal);
+            return this.drafts.store.change(created.id, created.revision, (draft) => {
+                draft.reply = {
+                    uid,
+                    folder,
+                    ...(original.uidValidity
+                        ? { uidValidity: original.uidValidity }
+                        : {}),
+                };
+            }, signal);
+        }
+        throw new Error('不支持的邮箱操作');
+    }
+    async fetch(request) {
+        const fail = (status) => json(status, {
+            ok: false,
+            error: {
+                message: '邮件操作失败，请检查账号、连接或稍后重试 / Email action failed; check the account and connection',
+            },
+        });
+        const origin = request.headers.get('origin'), site = request.headers.get('sec-fetch-site');
+        if (request.method !== 'POST' ||
+            request.headers.get('x-dsh-email-mailbox') !== '1' ||
+            request.headers.get('content-type')?.split(';')[0] !==
+                'application/json' ||
+            (site && !['same-origin', 'none'].includes(site)))
+            return fail(403);
+        // DSH's authenticated connection carrier reconstructs the URL internally;
+        // the original Host header identifies the browser-facing origin.
+        if (origin) {
+            try {
+                const source = new URL(origin);
+                if (!['http:', 'https:'].includes(source.protocol) ||
+                    source.host !==
+                        (request.headers.get('host') || new URL(request.url).host))
+                    return fail(403);
+            }
+            catch {
+                return fail(403);
+            }
+        }
+        const reader = request.body?.getReader();
+        if (!reader)
+            return fail(400);
+        try {
+            const chunks = [];
+            let size = 0;
+            for (;;) {
+                const { value, done } = await reader.read();
+                if (done)
+                    break;
+                size += value.length;
+                if (size > 16384) {
+                    await reader.cancel();
+                    return fail(413);
+                }
+                chunks.push(value);
+            }
+            const body = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+            if (!body || typeof body !== 'object' || Array.isArray(body))
+                return fail(400);
+            const signal = AbortSignal.any([
+                request.signal,
+                AbortSignal.timeout(120000),
+            ]);
+            if (body.action === 'download') {
+                // The authenticated file action owns only the copy created by this call.
+                const settings = this.runtime.getEffectiveSettings(), account = typeof body.account === 'string' && body.account
+                    ? body.account
+                    : settings.defaultAccount, cfg = settings.accounts.get(account), folder = typeof body.folder === 'string' && body.folder
+                    ? body.folder
+                    : (cfg?.inboxFolder ?? '');
+                if (!cfg ||
+                    folder.length > 1024 ||
+                    /[\r\n\0]/.test(folder) ||
+                    !Number.isSafeInteger(body.index) ||
+                    body.index < 0 ||
+                    body.index > 999)
+                    return fail(400);
+                if (!((typeof body.uid === 'number' &&
+                    Number.isSafeInteger(body.uid) &&
+                    body.uid > 0) ||
+                    (typeof body.uid === 'string' &&
+                        body.uid.length > 0 &&
+                        body.uid.length <= 998 &&
+                        !/[\r\n\0]/.test(body.uid))))
+                    return fail(400);
+                const file = await this.runtime
+                    .getPool()
+                    .downloadAttachment(account, folder, body.uid, clampInt(body.index, 0, 0, 999), undefined, signal);
+                try {
+                    const bytes = await readFile(file.path);
+                    if (bytes.length >
+                        this.runtime.getEffectiveSettings().maxAttachmentBytes)
+                        return fail(413);
+                    return new Response(new Uint8Array(bytes), {
+                        headers: {
+                            'content-type': 'application/octet-stream',
+                            'content-disposition': "attachment; filename*=UTF-8''" +
+                                encodeURIComponent(file.filename),
+                            'x-content-type-options': 'nosniff',
+                            'cache-control': 'no-store',
+                        },
+                    });
+                }
+                finally {
+                    await unlink(file.path).catch(() => { });
+                }
+            }
+            return json(200, { ok: true, value: await this.action(body, signal) });
+        }
+        catch (error) {
+            let message = error instanceof Error ? error.message : '邮件操作失败';
+            try {
+                for (const cfg of this.runtime.getEffectiveSettings().accounts.values())
+                    for (const key of [cfg.password, cfg.authPassword])
+                        if (key)
+                            message = message.split(key).join('[已隐藏]');
+            }
+            catch { }
+            return json(400, {
+                ok: false,
+                error: { message: message.slice(0, 1000) },
+            });
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
+export function installEmailMailbox(ctx, backend) {
+    ctx.inject?.(['connection'], (host) => host.connection?.fetch?.register?.({
+        path: MAILBOX_ROUTE,
+        methods: ['POST'],
+        requestBody: 'buffered',
+        fetch: (request) => backend.fetch(request),
+    }));
+}

package/lib/public-download.d.ts

@@ -0,0 +1,3 @@
+export declare function publicAddress(address: string): boolean;
+/** Download a signed public HTTPS URL without API credentials; pin the validated DNS answers. */
+export declare function downloadPublicBytes(input: string, cap: number, signal?: AbortSignal, redirects?: number): Promise<Buffer>;

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 主机）');
     }