dsh-email 0.10.2 → 0.10.3

package/README.en.md

@@ -149,9 +149,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

@@ -183,9 +183,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';