dsh-email 0.10.2 → 0.10.4

package/README.en.md

@@ -6,7 +6,7 @@
 
 ![dsh-email banner](https://raw.githubusercontent.com/STARDUSTLC666/dsh-email/main/assets/banner.png)
 
-Email tools for DeepSeek Harness: let the agent **check the inbox, read mail, search mail, send mail on your behalf, and send/receive attachments** through standard IMAP/SMTP — with one-line presets for QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud. Pure plugin implementation, zero core changes, works out of the box.
+Email plugin for DeepSeek Harness: **10 IMAP/SMTP tools** cover reading and searching mail, sending, replies and forwarding, attachments, message flags and moves, incremental new-mail checks, and connection health. Supports multiple accounts, send approval, Web settings and new-mail popups. Configure an account with presets for QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud to get started.
 
 Pure Node, **cross-platform** (one codebase for Windows / macOS / Linux), no shell, no native binaries.
 
@@ -20,7 +20,10 @@ Pure Node, **cross-platform** (one codebase for Windows / macOS / Linux), no she
 | `email_send` | Send mail on your behalf (attachments supported). **Prompts for confirmation before sending by default**, showing recipients, subject and attachment count; only sends after you approve |
 | `email_folders` | List the mailbox folders (INBOX/Sent/Junk/custom…); feed the `path` to other tools |
 | `email_attachment` | Download an attachment by index (saved to the session workspace by default so the model can read it directly; size capped by `maxAttachmentBytes`) |
+| `email_health` | Check account configuration and IMAP/SMTP connectivity to diagnose connection problems |
 | `email_watch` | Incremental new-mail check: the first call seeds a baseline, every later call reports only unread mail newer than the last check — ideal for scheduled new-mail notifications |
+| `email_mark` | Mark messages as read/unread, add/remove stars, or move messages to another folder |
+| `email_reply` | Reply, reply-all or forward with thread headers and quoted content; uses the same send-approval gate |
 
 ### New-mail notifications (web UI)
 
@@ -34,6 +37,7 @@ Example:
 
 ### Changelog
 
+- **0.10.4 (2026-09-07)**: raise the minimum `mailparser` version to `3.9.22` and update the lockfile to use the patched `html-to-text 10.0.1 → deepmerge-ts 8.0.2` dependency chain for [CVE-2026-40345](https://github.com/RebeccaStevens/deepmerge-ts/security/advisories/GHSA-ggr8-5vv4-36mx). This does not rely on root-only `pnpm.overrides`, which cannot fix consumers installing this plugin as a dependency. Add runtime dependency-chain and HTML-message parsing regression tests. An affected dependency is not proof that mail input can trigger this vulnerability.
 - **0.9.0**: new `email_watch` incremental new-mail tool (cursor-based, ideal for scheduled notifications); new "whale-girl courier" new-mail popup in the web UI (local skin artwork read at runtime + built-in fallback).
 - **0.8.2**: `since` / `until` parameter descriptions unified to English, consistent with the other parameters, so multilingual agents read them correctly.
 - **0.8.0/0.8.1**: `email_list` / `email_search` gained `since` / `until` date-range filters; new `email_health` self-check (account/connection/config in one call); adapted to harness 0.1.2 (removed the deleted client-injection declaration).
@@ -42,7 +46,7 @@ Example:
 
 ## Compatibility
 
-Verified against source-run `@deepseek-ai/dsh@0.1.2-alpha.4` on 2026-09-02 (69 tests plus a Web-profile startup smoke test). Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
+Plugin contracts and Web-profile co-loading verified against the official source-run `@deepseek-ai/dsh@0.1.3-alpha.1` baseline on 2026-09-07; this does not claim real-mailbox send/receive verification. Built for the cordis patch-bundle plugin model (`cordis.patch.yml` + `dsh.bundle.patch`). No runtime imports of `@deepseek-ai/*` internals.
 
 ## Installation
 
@@ -149,9 +153,13 @@ Every provider requires an authorization code / app-specific password instead of
 ```sh
 pnpm install
 pnpm run build   # tsc → lib/
-pnpm test        # 构建 + node --test（配置/解析/注册与审批门，44 个用例，无需真实邮箱）
+pnpm test        # build + offline tests; no real mailbox required
 ```
 
+`src/index.ts` composes the plugin. `runtime.ts` owns live settings, account pools, and separate tool/web watch cursors. `tools.ts` wires the ten tool implementations. `tool-contract.ts` defines parameters, output schemas, and text rendering. `approval.ts` owns the outgoing-mail gate. IMAP/SMTP transport remains in `mail-client.ts`, and browser routes remain in `web.ts`.
+
+Tests cover pool replacement after live settings changes, unload cleanup, cancellation and workspace propagation, independent tool/web cursors, and rejected approval preventing send execution. In-memory clients replace mailbox connections.
+
 ## License
 
 MIT. This is a community plugin, not affiliated with DeepSeek; `@deepseek-ai/*` is an officially reserved namespace.

package/README.md

@@ -2,7 +2,7 @@
 
 # dsh-email
 
-> **给 agent 一个邮箱**：八个国内邮箱预设开箱即用，收发/搜索/附件下载全搞定。
+> **让 agent 协助处理邮件**：收发、搜索、回复转发、附件、邮件整理与新邮件提醒，支持八种常见邮箱服务预设。
 
 ![npm version](https://img.shields.io/npm/v/dsh-email?label=npm&color=blue) ![npm downloads](https://img.shields.io/npm/dm/dsh-email) ![license](https://img.shields.io/npm/l/dsh-email) ![stars](https://img.shields.io/github/stars/STARDUSTLC666/dsh-email?style=social)
 
@@ -12,9 +12,9 @@
 ![dsh-email banner](https://raw.githubusercontent.com/STARDUSTLC666/dsh-email/main/assets/banner.png)
 
 
-DeepSeek Harness 邮件工具插件：让 agent 能**查收件箱、读邮件、搜邮件、代发邮件、收发附件**。纯插件实现，零核心改动，安装即可用。
+DeepSeek Harness 邮件插件：通过标准 IMAP/SMTP 提供 **10 个工具**，覆盖邮件查收与搜索、发送与回复转发、附件处理、标记与移动、增量收件和健康检查。支持多个账号、发信审批、Web 设置页与新邮件弹窗；配置邮箱账号后即可使用。
 
-Email tools for DeepSeek Harness: list, read, search and send mail through standard IMAP/SMTP — with one-line presets for QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud.
+IMAP/SMTP email tools for DeepSeek Harness, with replies, forwarding, mailbox organization and new-mail notifications. Presets: QQ / 163 / 126 / Sina / Aliyun / Gmail / Outlook / iCloud.
 
 纯 Node 实现，**全平台通用**（Windows / macOS / Linux 同一份代码），不依赖 shell、无原生二进制。
 
@@ -28,6 +28,7 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 | `email_send` | 代发邮件（支持带附件）。**默认发信前会弹确认**，显示收件人、主题和附件数，由你批准后才发出 |
 | `email_folders` | 列出邮箱的文件夹（INBOX/已发送/垃圾邮件/自定义…），拿 path 喂给其他工具 |
 | `email_attachment` | 按序号下载邮件附件（默认存到会话工作区，模型可直接读取；大小受 maxAttachmentBytes 限制） |
+| `email_health` | 检查账号配置及 IMAP/SMTP 连接，定位邮箱连接问题 |
 | `email_watch` | 增量检查新邮件：首次调用建立基线，之后每次只报告比上次多出来的未读邮件，适合定时任务做新邮件提醒 |
 | `email_mark` | 修改邮件状态：标记已读/未读、加/取消星标，或移动到别的文件夹（归档、丢回收站），收发闭环的「收完之后」那一半 |
 | `email_reply` | 回复/回复全部/转发已有邮件：自动带上 In-Reply-To/References 线程头与原文引文，收件人自动排除自己，主题不重复叠 Re:/Fwd:；同样走发信审批门 |
@@ -44,6 +45,7 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 
 ### 版本记录
 
+- **0.10.4（2026-09-07）**：将 `mailparser` 最低版本提升到 `3.9.22` 并更新锁文件，使用 `html-to-text 10.0.1 → deepmerge-ts 8.0.2` 的修复链处理 [CVE-2026-40345](https://github.com/RebeccaStevens/deepmerge-ts/security/advisories/GHSA-ggr8-5vv4-36mx)。不依赖插件作为下游依赖安装时不生效的根级 `pnpm.overrides`；新增真实依赖链与 HTML 邮件解析回归测试。依赖告警不等于已证实邮件输入可触发该漏洞。
 - **0.10.1**：补发制品——已发布的 0.10.0 打包时只含 `email_mark`，本版同时包含 `email_mark` 与 `email_reply`，代码与 0.10.0 的 main 一致。
 - **0.10.0**：新增 `email_mark`（已读/未读/星标/移动文件夹，补齐收发闭环的整理侧）与 `email_reply`（回复/回复全部/转发，自动线程头+引文，走发信审批门）；连接池按读/写模式分别管理邮箱打开状态。
 - **0.9.1**：修复设置页空主机遮蔽 provider 预设（#3/#6）；IMAP 连接超时不再杀死整个 DSH 进程（#4）；暗色模式输入控件可见（#2）；密码栏提示环境变量 `DSH_EMAIL_PASSWORD` 免明文方案（#5）。
@@ -55,7 +57,7 @@ Email tools for DeepSeek Harness: list, read, search and send mail through stand
 
 ## 兼容性
 
-在 `@deepseek-ai/dsh@0.1.2-alpha.4` 源码模式下实测通过（2026-09-02，69 项测试及 Web profile 启动冒烟）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
+已在 `@deepseek-ai/dsh@0.1.3-alpha.1` 官方源码基线上验证插件接口与 Web profile 同载（2026-09-07；不代表已实测真实邮箱收发）。遵循 cordis 组合包补丁模型（`cordis.patch.yml` + `dsh.bundle.patch`），运行时不 import 任何 `@deepseek-ai/*` 内部模块。
 
 ## 安装
 
@@ -183,9 +185,13 @@ dsh plugin --profile web remove dsh-email
 ```sh
 pnpm install
 pnpm run build   # tsc → lib/
-pnpm test        # 构建 + node --test（配置/解析/注册与审批门，44 个用例，无需真实邮箱）
+pnpm test        # 构建 + 离线测试，无需真实邮箱
 ```
 
+`src/index.ts` 只负责组合插件。`runtime.ts` 管理动态设置、账号连接池和网页/工具各自的监视游标；`tools.ts` 接线十个工具的执行逻辑；`tool-contract.ts` 集中维护参数、输出 schema 和中文渲染；`approval.ts` 管理发信审批。IMAP/SMTP 传输仍由 `mail-client.ts` 负责，网页路由由 `web.ts` 负责。
+
+测试覆盖动态配置换池、卸载释放、取消信号与工作区透传、工具/网页游标隔离，以及审批拒绝时不会进入发送执行。测试用内存客户端替代邮箱连接。
+
 ## 协议
 
 MIT。这是一个社区插件，与 DeepSeek 官方无关；`@deepseek-ai/*` 为官方保留命名空间。

package/lib/approval.d.ts

@@ -0,0 +1,34 @@
+/** Outgoing-mail approval is independent of tool execution. */
+import type { EmailRuntime } from './runtime.js';
+type ApprovalDecision = {
+    kind: 'allow';
+} | {
+    kind: 'deny';
+    reason: string;
+} | {
+    kind: 'ask';
+    reason?: string;
+};
+interface PendingExecution {
+    name: string;
+    arguments?: unknown;
+    agent?: unknown;
+    callId?: string;
+    signal?: AbortSignal;
+}
+interface ApprovalContext {
+    on(event: 'tools/pre-execute', listener: (exec: PendingExecution, next: () => Promise<ApprovalDecision>) => Promise<ApprovalDecision>, options: {
+        prepend: boolean;
+    }): unknown;
+    get(name: 'approval'): {
+        request(input: {
+            agent?: unknown;
+            toolName: string;
+            callId?: string;
+            reason: string;
+            signal?: AbortSignal;
+        }): Promise<string>;
+    } | undefined;
+}
+export declare function installSendApproval(ctx: ApprovalContext, runtime: Pick<EmailRuntime, 'getSettingsValue' | 'getEffectiveSettings'>): void;
+export {};

package/lib/approval.js

@@ -0,0 +1,55 @@
+export function installSendApproval(ctx, runtime) {
+    ctx.on('tools/pre-execute', async (exec, next) => {
+        if (exec?.name !== 'email_send' && exec?.name !== 'email_reply')
+            return next();
+        const value = runtime.getSettingsValue();
+        if (value.sendApproval === false)
+            return next();
+        try {
+            runtime.getEffectiveSettings();
+        }
+        catch {
+            return next(); // unconfigured: let the tool report the actionable hint
+        }
+        let reason;
+        if (exec.name === 'email_send') {
+            const args = (exec.arguments ?? {});
+            const attachCount = Array.isArray(args.attachments) ? args.attachments.length : 0;
+            reason = '发送邮件给 ' + args.to + '，主题「' + args.subject + '」' + (attachCount > 0 ? '，附件 ' + attachCount + ' 个' : '');
+        }
+        else {
+            const args = (exec.arguments ?? {});
+            const mode = typeof args.mode === 'string' && args.mode.trim() !== '' ? args.mode.trim().toLowerCase() : 'reply';
+            const modeLabel = mode === 'forward' ? '转发' : mode === 'reply-all' ? '回复全部' : '回复';
+            reason = modeLabel + '邮件（原邮件 uid=' + args.uid + '）' + (mode === 'forward' && typeof args.to === 'string' && args.to.trim() !== '' ? '，收件人 ' + args.to : '');
+        }
+        // Gate-owned approval: we run the approval round-trip ourselves so the
+        // denial reason is always honest and actionable — including the Full
+        // Access case where the harness policy answers 'rejected' without ever
+        // showing a dialog.
+        const approval = ctx.get('approval');
+        if (approval === undefined) {
+            return {
+                kind: 'deny',
+                reason: 'email_send 需要确认，但当前环境没有审批通道（如 headless）。如确定安全，可在配置中设置 sendApproval: false 后直接发送。',
+            };
+        }
+        const outcome = await approval.request({
+            agent: exec.agent,
+            toolName: exec.name,
+            callId: exec.callId,
+            reason,
+            signal: exec.signal,
+        });
+        if (outcome === 'allowed-once')
+            return next();
+        if (outcome === 'cancelled')
+            return { kind: 'deny', reason: '发信确认被取消，邮件未发送。' };
+        if (outcome === 'unavailable')
+            return { kind: 'deny', reason: '发信确认不可用（没有可用的审批界面），邮件未发送。' };
+        return {
+            kind: 'deny',
+            reason: '发信未获批准：要么你拒绝了，要么当前会话处于 Full Access（审批策略 never，不会弹框）。若在 Full Access：切到 Read Only / Write 再发，或关闭 sendApproval（自行承担风险）。',
+        };
+    }, { prepend: true });
+}

package/lib/index.d.ts

@@ -1,16 +1,12 @@
-import { type EmailConfig } from './config.js';
+import type { EmailConfig } from './config.js';
 export declare const name = "tool-email";
 export declare const inject: string[];
 export type Config = EmailConfig;
-/**
- * 解析天级日期参数为 Date。接受 YYYY-MM-DD 或完整 ISO 时间。
- * endInclusive=true 时返回“该日结束”（次日零点），用于 until 语义（IMAP BEFORE 是不含当天的）。
- */
-export declare function parseEmailDay(input: string, label: string, endInclusive?: boolean): Date;
+/** Compose settings/pool lifecycle, tools, browser routes and the outgoing-mail gate. */
 export declare function apply(ctx: any, config?: Config): void;
-export { PROVIDER_NAMES, EMAIL_PASSWORD_ENV } from './config.js';
-export { resolveEmailConfig, resolveEmailSettings, parseAccountsYaml, clampInt, defaultDownloadDir } from './config.js';
-export { stripHtml, truncateText, flattenAddresses, sanitizeFilename, parseRawMessage } from './parse.js';
-export { EmailPool, MailError, messageOf, validateAttachmentPaths, selectAttachmentPart, messageMatchesQuery, buildReplyMessage, extractMessageIds } from './mail-client.js';
-export { SETTINGS_NAMESPACE, EmailSettingsSchema, toSettingsBase, toEmailConfig, validateSettingsValue } from './settings.js';
-export { SETTINGS_ROUTE, EmailSettingsBackend, installEmailSettingsWeb } from './web.js';
+export { clampInt, defaultDownloadDir, EMAIL_PASSWORD_ENV, parseAccountsYaml, PROVIDER_NAMES, resolveEmailConfig, resolveEmailSettings } from './config.js';
+export { buildReplyMessage, EmailPool, extractMessageIds, MailError, messageMatchesQuery, messageOf, selectAttachmentPart, validateAttachmentPaths } from './mail-client.js';
+export { flattenAddresses, parseRawMessage, sanitizeFilename, stripHtml, truncateText } from './parse.js';
+export { EmailSettingsSchema, SETTINGS_NAMESPACE, toEmailConfig, toSettingsBase, validateSettingsValue } from './settings.js';
+export { parseEmailDay } from './tool-contract.js';
+export { EmailSettingsBackend, installEmailSettingsWeb, SETTINGS_ROUTE } from './web.js';