pi2web 0.2.0

package/VOICE_SERVER_SETUP.md

@@ -0,0 +1,393 @@
+# Remote Pi 本地语音服务器启动指南（Windows）
+
+本文记录两种语音服务启动方式，以及启动 Remote Pi 语音功能的完整步骤：
+
+1. Speaches：本地模型，可同时提供 TTS 和可选 STT。
+2. Edge TTS Server：调用 Microsoft Edge 在线语音，只提供 TTS，不需要 Docker 或 FFmpeg。
+
+## 当前配置
+
+- Speaches 源码目录：`C:\src\opensource\speaches`
+- Speaches 地址：`http://127.0.0.1:8000/v1`
+- 中文 TTS 模型：`speaches-ai/piper-zh_CN-huayan-medium`
+- TTS voice：`huayan`
+- Remote Pi 地址：`http://127.0.0.1:11318`
+
+> Windows 上启动 Speaches 时必须启用 Python UTF-8 模式。否则读取中文 Piper 模型的 `config.json` 时可能发生 `UnicodeDecodeError`，客户端表现为 `HTTP 200, 0 bytes` 或 `curl: (18) transfer closed`。
+
+## 一、每次启动 Speaches
+
+打开一个新的 PowerShell 窗口，执行：
+
+```powershell
+cd C:\src\opensource\speaches
+
+.\.venv\Scripts\python.exe -X utf8 -m uvicorn `
+  --factory `
+  --host 127.0.0.1 `
+  --port 8000 `
+  speaches.main:create_app
+```
+
+保持这个窗口运行。看到以下内容表示服务已经启动：
+
+```text
+Uvicorn running on http://127.0.0.1:8000
+```
+
+在另一个 PowerShell 窗口检查服务：
+
+```powershell
+curl.exe --fail-with-body http://127.0.0.1:8000/health
+```
+
+正常响应：
+
+```json
+{"message":"OK"}
+```
+
+Speaches Web UI：
+
+```text
+http://127.0.0.1:8000
+```
+
+## 二、首次安装或模型丢失时下载中文 TTS 模型
+
+模型已经下载后不需要每次执行。
+
+```powershell
+curl.exe --fail-with-body -X POST `
+  "http://127.0.0.1:8000/v1/models/speaches-ai/piper-zh_CN-huayan-medium"
+```
+
+查看已经安装的模型：
+
+```powershell
+curl.exe --fail-with-body http://127.0.0.1:8000/v1/models
+```
+
+输出中应包含：
+
+```text
+speaches-ai/piper-zh_CN-huayan-medium
+```
+
+## 三、测试中文语音合成
+
+先创建测试请求文件：
+
+```powershell
+@'
+{
+  "model": "speaches-ai/piper-zh_CN-huayan-medium",
+  "voice": "huayan",
+  "input": "语音服务器配置成功，这是一段标准普通话测试。",
+  "response_format": "wav",
+  "sample_rate": 24000,
+  "stream_format": "audio"
+}
+'@ | Set-Content "C:\Users\sunxiaowen\piper-request.json" -Encoding utf8
+```
+
+发送请求：
+
+```powershell
+curl.exe --fail-with-body -sS `
+  -X POST "http://127.0.0.1:8000/v1/audio/speech" `
+  -H "Content-Type: application/json" `
+  --data-binary "@C:\Users\sunxiaowen\piper-request.json" `
+  --output "C:\Users\sunxiaowen\piper-test.wav" `
+  -w "`nHTTP %{http_code}, %{size_download} bytes`n"
+```
+
+正常情况下应显示 `HTTP 200`，并且下载大小明显大于零。播放测试文件：
+
+```powershell
+Invoke-Item "C:\Users\sunxiaowen\piper-test.wav"
+```
+
+## 四、启动 Remote Pi 的语音功能
+
+Remote Pi 需要两个服务：
+
+1. OpenAI-compatible 语音服务：可以是 Speaches，也可以是本文第九节的 Edge TTS Server。
+2. OpenAI-compatible 摘要 LLM：把 Agent 最终输出压缩成适合朗读的短摘要。
+
+打开另一个 PowerShell 窗口：
+
+```powershell
+cd C:\src\sxw\remote-pi
+```
+
+如果摘要 LLM 需要 API key，先设置环境变量：
+
+```powershell
+$env:SUMMARY_API_KEY = "替换成摘要服务的实际密钥"
+```
+
+启动 Remote Pi：
+
+```powershell
+npm run dev -- `
+  --voice-base-url "http://127.0.0.1:8000/v1" `
+  --voice-tts-model "speaches-ai/piper-zh_CN-huayan-medium" `
+  --voice-tts-voice "huayan" `
+  --voice-summary-base-url "https://替换成摘要服务地址/v1" `
+  --voice-summary-model "替换成摘要模型ID" `
+  --voice-summary-api-key-env "SUMMARY_API_KEY" `
+  --voice-language "zh-CN"
+```
+
+如果摘要服务不需要 API key，删除下面两项：
+
+```powershell
+$env:SUMMARY_API_KEY = "..."
+--voice-summary-api-key-env "SUMMARY_API_KEY"
+```
+
+如果 Speaches 已经配置 STT 模型，可在启动参数中增加：
+
+```text
+--voice-stt-model "实际的STT模型ID"
+```
+
+未配置 `--voice-stt-model` 时，语音播报仍可使用，但浏览器麦克风转写不可用。
+
+## 五、Web UI 中启用语音
+
+1. 打开 `http://127.0.0.1:11318`。
+2. 输入 Remote Pi 终端显示的配对码。
+3. 点击 Web UI 中的“启用语音”。
+4. Agent 完成任务后，Remote Pi 会先请求摘要 LLM，再调用已配置的语音服务播放中文摘要。
+
+浏览器麦克风通常要求 HTTPS 安全上下文；通过 `localhost` 访问时可以使用 HTTP。
+
+## 六、推荐的日常启动顺序
+
+每次开机后按以下顺序启动：
+
+1. 启动 Speaches，并保持窗口运行。
+2. 调用 `/health` 确认 Speaches 正常。
+3. 启动摘要 LLM（如果是本地服务）。
+4. 启动 Remote Pi。
+5. 打开 Web UI 并启用语音。
+
+## 七、停止服务
+
+在对应的 PowerShell 窗口按：
+
+```text
+Ctrl+C
+```
+
+建议先停止 Remote Pi，再停止 Speaches 或 Edge TTS Server。
+
+## 八、常见问题
+
+### `HTTP 200, 0 bytes` 或 `curl: (18)`
+
+确认 Speaches 是使用下面的 UTF-8 启动方式，而不是直接运行 `uvicorn.exe`：
+
+```powershell
+.\.venv\Scripts\python.exe -X utf8 -m uvicorn --factory --host 127.0.0.1 --port 8000 speaches.main:create_app
+```
+
+### `Failed to open ...piper-request.json`
+
+确认文件存在：
+
+```powershell
+Get-Item "C:\Users\sunxiaowen\piper-request.json"
+```
+
+然后在 `curl.exe --data-binary` 中使用完整绝对路径。
+
+### 模型不存在
+
+重新下载：
+
+```powershell
+curl.exe --fail-with-body -X POST `
+  "http://127.0.0.1:8000/v1/models/speaches-ai/piper-zh_CN-huayan-medium"
+```
+
+### Speaches 无法连接
+
+检查端口：
+
+```powershell
+Test-NetConnection 127.0.0.1 -Port 8000
+```
+
+如果 `TcpTestSucceeded` 为 `False`，说明 Speaches 尚未启动或已经退出。
+
+### 能生成测试音频，但 Remote Pi 没有声音
+
+依次确认：
+
+1. Web UI 已点击“启用语音”。
+2. 摘要 LLM 的 `/v1/chat/completions` 支持流式响应。
+3. Remote Pi 启动终端和语音服务终端没有报错。
+4. 浏览器标签页没有静音，系统输出设备选择正确。
+
+## 九、不使用 Docker 启动 Edge TTS Server
+
+项目内置了一个轻量 Python 服务，源码位于：
+
+```text
+packages/edge-tts-server
+```
+
+它使用：
+
+- `edge-tts` 调用 Microsoft Edge 在线语音服务。
+- `aiohttp` 提供 OpenAI-compatible `POST /v1/audio/speech` 接口。
+- MP3 作为输出格式，由浏览器直接解码播放。
+
+该服务不使用 Docker 或 FFmpeg，也不提供语音识别。
+
+### 9.1 首次安装
+
+打开 PowerShell：
+
+```powershell
+cd C:\src\sxw\remote-pi\packages\edge-tts-server
+python -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -e .
+```
+
+如果 PowerShell 禁止执行激活脚本，可以不激活虚拟环境，直接执行：
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install -e .
+```
+
+### 9.2 每次启动 Edge TTS Server
+
+激活虚拟环境后启动：
+
+```powershell
+cd C:\src\sxw\remote-pi\packages\edge-tts-server
+.\.venv\Scripts\Activate.ps1
+remote-pi-edge-tts
+```
+
+或者直接使用虚拟环境中的 Python：
+
+```powershell
+.\.venv\Scripts\python.exe -m remote_pi_edge_tts
+```
+
+默认配置：
+
+- 地址：`http://127.0.0.1:5050`
+- 默认音色：`zh-CN-XiaoxiaoNeural`
+- 健康检查：`http://127.0.0.1:5050/health`
+
+可以显式指定监听地址、端口和默认音色：
+
+```powershell
+remote-pi-edge-tts `
+  --host 127.0.0.1 `
+  --port 5050 `
+  --voice zh-CN-XiaoxiaoNeural
+```
+
+### 9.3 检查服务
+
+```powershell
+curl.exe --fail-with-body http://127.0.0.1:5050/health
+```
+
+正常响应：
+
+```json
+{"status":"ok","service":"remote-pi-edge-tts"}
+```
+
+### 9.4 测试 Edge 中文语音
+
+先创建请求文件：
+
+```powershell
+@'
+{
+  "model": "edge-tts",
+  "voice": "zh-CN-XiaoxiaoNeural",
+  "input": "Edge 语音服务器配置成功，这是一段普通话测试。",
+  "response_format": "mp3"
+}
+'@ | Set-Content "$env:TEMP\edge-tts-request.json" -Encoding utf8
+```
+
+发送请求：
+
+```powershell
+curl.exe --fail-with-body -sS `
+  -X POST "http://127.0.0.1:5050/v1/audio/speech" `
+  -H "Content-Type: application/json" `
+  --data-binary "@$env:TEMP\edge-tts-request.json" `
+  --output "$env:TEMP\edge-tts-test.mp3" `
+  -w "`nHTTP %{http_code}, %{size_download} bytes`n"
+```
+
+播放测试文件：
+
+```powershell
+Invoke-Item "$env:TEMP\edge-tts-test.mp3"
+```
+
+### 9.5 使用 Edge TTS 启动 Remote Pi
+
+打开另一个 PowerShell 窗口：
+
+```powershell
+cd C:\src\sxw\remote-pi
+$env:SUMMARY_API_KEY = "替换成摘要服务的实际密钥"
+
+npm run dev -- `
+  --voice-base-url "http://127.0.0.1:5050/v1" `
+  --voice-tts-model "edge-tts" `
+  --voice-tts-voice "zh-CN-XiaoxiaoNeural" `
+  --voice-tts-format "mp3" `
+  --voice-summary-base-url "https://替换成摘要服务地址/v1" `
+  --voice-summary-model "替换成摘要模型ID" `
+  --voice-summary-api-key-env "SUMMARY_API_KEY" `
+  --voice-language "zh-CN"
+```
+
+不要配置 `--voice-stt-model`。此时：
+
+- Agent 完成后仍会生成并播放语音摘要。
+- Web UI 会隐藏麦克风按钮。
+- `/api/v1/system/status` 会报告 TTS 可用、STT 不可用。
+
+### 9.6 常用中文音色
+
+可以把 `--voice-tts-voice` 替换为：
+
+- `zh-CN-XiaoxiaoNeural`：通用女声。
+- `zh-CN-YunxiNeural`：年轻男声。
+- `zh-CN-YunyangNeural`：正式男声。
+- `zh-CN-YunjianNeural`：有力男声。
+
+### 9.7 Edge TTS 故障排查
+
+#### `Edge TTS failed` 或 `NoAudioReceived`
+
+依次检查：
+
+1. 当前机器能否正常访问 Microsoft Edge 在线语音服务。
+2. `edge-tts` 是否需要升级：
+
+```powershell
+.\.venv\Scripts\python.exe -m pip install --upgrade "edge-tts>=7.2,<8"
+```
+
+3. 音色名称是否正确。
+4. 重新启动 Edge TTS Server 后再次测试。
+
+Edge TTS 依赖非官方消费者接口，上游协议或可用性可能发生变化，建议仅用于本机或可信私有网络。

package/dist/agents.js

@@ -0,0 +1,123 @@
+import { EventEmitter } from 'node:events';
+import { randomUUID } from 'node:crypto';
+import { relative as pathRelative } from 'node:path';
+import { createSdkBackend } from './sdk-backend.js';
+/** Deterministic backend used by the server and tests. The SDK adapter can implement the same contract. */
+export class MockBackend {
+    emitter = new EventEmitter();
+    state;
+    messages = [];
+    timer;
+    constructor(agentId, cwd, sessionId = randomUUID()) { this.state = { agentId, sessionId, cwd, status: 'idle' }; }
+    emit(e) { this.emitter.emit('event', e); }
+    async prompt(message) { if (this.state.status === 'streaming')
+        throw Object.assign(new Error('Agent is busy'), { code: 'AGENT_BUSY' }); this.state.status = 'streaming'; this.emit({ type: 'agent_start', message }); await new Promise(r => { this.timer = setTimeout(r, 0); }); this.messages.push({ role: 'user', content: message }); this.emit({ type: 'message_start', role: 'assistant' }); this.emit({ type: 'message_update', assistantMessageEvent: { type: 'text_delta', delta: `Mock response: ${message}` } }); this.emit({ type: 'message_end', message: `Mock response: ${message}` }); this.state.status = 'idle'; this.emit({ type: 'agent_end' }); }
+    async steer(message) { this.emit({ type: 'steer', message }); }
+    async followUp(message) { this.emit({ type: 'follow_up', message }); }
+    async abort() { if (this.state.status === 'streaming') {
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.state.status = 'idle';
+        this.emit({ type: 'agent_end', aborted: true });
+    } }
+    async getState() { return { ...this.state }; }
+    async getMessages() { return [...this.messages]; }
+    async getCapabilities() { return { model: null, models: [], thinkingLevel: 'off', thinkingLevels: ['off'], supportsThinking: false }; }
+    async getSession() { return { ...await this.getSessionInfo(), entries: [], tree: [] }; }
+    async getSessionInfo() { return { sessionId: this.state.sessionId, sessionName: this.state.sessionName, stats: { totalMessages: this.messages.length, tokens: { total: 0 }, cost: 0 }, contextUsage: { tokens: null, contextWindow: 0, percent: null } }; }
+    async compact() { return { summary: 'mock' }; }
+    async setModel(_provider, _modelId) { }
+    async setThinkingLevel(_level) { }
+    async setSessionName(name) { this.state.sessionName = name; this.emit({ type: 'session_info_changed', name }); }
+    async navigate(_entryId) { return { cancelled: false }; }
+    async fork(_entryId) { return {}; }
+    async extensionResponse(_requestId, _value) { }
+    subscribe(listener) { this.emitter.on('event', listener); return () => this.emitter.off('event', listener); }
+    async dispose() { await this.abort(); this.state.status = 'stopped'; this.emitter.removeAllListeners(); }
+}
+export class AgentManager {
+    workspaces;
+    factory;
+    agents = new Map();
+    listeners = new Map();
+    globalListeners = new Set();
+    constructor(workspaces, factory = createSdkBackend) {
+        this.workspaces = workspaces;
+        this.factory = factory;
+    }
+    async create(workspaceId, relativeCwd = '.', sessionFile) { const ws = this.workspaces.get(workspaceId); if (!ws)
+        throw Object.assign(new Error('Workspace not found'), { code: 'WORKSPACE_NOT_FOUND' }); const cwd = await this.workspaces.resolve(ws, relativeCwd); if (!(await import('node:fs/promises')).stat(cwd).then(s => s.isDirectory()))
+        throw new Error('cwd is not a directory'); const id = `agent-${randomUUID()}`, backend = await this.factory(id, cwd, sessionFile), now = new Date().toISOString(); const record = { ...(await backend.getState()), workspaceId, createdAt: now, lastActiveAt: now }; this.attach(id, record, backend); return { ...record }; }
+    connect(entry, backend) { entry.backend = backend; backend.subscribe(event => { const record = entry.record; record.status = event.type === 'agent_start' || event.type === 'auto_retry_start' || (event.type === 'agent_end' && event.willRetry === true) ? 'streaming' : event.type === 'agent_end' || event.type === 'agent_settled' ? 'idle' : record.status; if (event.type === 'session_info_changed')
+        record.sessionName = typeof event.name === 'string' && event.name.trim() ? event.name.trim() : undefined; record.lastActiveAt = new Date().toISOString(); const item = { id: randomUUID(), sequence: entry.nextSequence++, timestamp: Math.floor(Date.now() / 1000), event }; entry.events.push(item); if (entry.events.length > 1000)
+        entry.events.shift(); for (const listener of this.listeners.get(record.agentId) ?? [])
+        listener(item); for (const listener of this.globalListeners)
+        listener(record.agentId, item); }); }
+    attach(id, record, backend) { const entry = { record, backend, events: [], nextSequence: 1 }; this.connect(entry, backend); this.agents.set(id, entry); }
+    async restore(records) { for (const saved of records) {
+        try {
+            const ws = this.workspaces.get(saved.workspaceId);
+            if (!ws)
+                continue;
+            const cwd = await this.workspaces.resolve(ws, pathRelative(ws.rootPath, saved.cwd));
+            const sessionModified = saved.sessionFile ? await import('node:fs/promises').then(fs => fs.stat(saved.sessionFile).then(value => value.mtime.toISOString()).catch(() => undefined)) : undefined;
+            const record = { ...saved, cwd, status: 'unloaded', lastActiveAt: sessionModified && sessionModified > saved.lastActiveAt ? sessionModified : saved.lastActiveAt };
+            this.agents.set(saved.agentId, { record, events: [], nextSequence: 1 });
+        }
+        catch { /* Keep server startup resilient to deleted workspaces. */ }
+    } }
+    get(id) { const x = this.agents.get(id); if (!x)
+        throw Object.assign(new Error('Agent not found'), { code: 'AGENT_NOT_FOUND' }); return x; }
+    list() { return [...this.agents.values()].map(x => ({ ...x.record })); }
+    isLoaded(id) { return !!this.get(id).backend; }
+    async ensureLoaded(id) { const entry = this.get(id); if (entry.backend)
+        return entry.backend; if (entry.record.status === 'stopped')
+        throw Object.assign(new Error('Agent is not running'), { code: 'AGENT_NOT_RUNNING' }); if (entry.loading)
+        return entry.loading; entry.record.status = 'starting'; entry.loading = (async () => { try {
+        const backend = await this.factory(id, entry.record.cwd, entry.record.sessionFile);
+        const state = await backend.getState();
+        entry.record = { ...entry.record, ...state, status: state.status === 'stopped' ? 'idle' : state.status };
+        this.connect(entry, backend);
+        return backend;
+    }
+    catch (error) {
+        entry.record.status = 'error';
+        throw error;
+    }
+    finally {
+        entry.loading = undefined;
+    } })(); return entry.loading; }
+    async command(id, kind, message = '') { const entry = this.get(id); if (kind === 'abort' && !entry.backend)
+        return; if (entry.record.status === 'stopped')
+        throw Object.assign(new Error('Agent is not running'), { code: 'AGENT_NOT_RUNNING' }); const backend = await this.ensureLoaded(id); if (kind === 'abort')
+        return backend.abort(); return backend[kind === 'follow-up' ? 'followUp' : kind](message); }
+    events(id, last = 0) { return this.get(id).events.filter(e => e.sequence > last); }
+    currentSequence(id) { return this.get(id).nextSequence - 1; }
+    async snapshot(id, messageLimit) { const a = this.get(id), messages = a.backend ? await a.backend.getMessages() : []; if (messageLimit === undefined)
+        return { state: a.backend ? await a.backend.getState() : { ...a.record }, messages, lastSequence: a.nextSequence - 1 }; const page = this.paginateMessages(messages, messageLimit); return { state: a.backend ? await a.backend.getState() : { ...a.record }, messages: page.items, messagePage: page, lastSequence: a.nextSequence - 1 }; }
+    hasReplayGap(id, last) { const a = this.get(id); const current = a.nextSequence - 1; return last > current || (last > 0 && a.events.length > 0 && last < a.events[0].sequence - 1); }
+    subscribe(id, listener) { this.get(id); if (!this.listeners.has(id))
+        this.listeners.set(id, new Set()); this.listeners.get(id).add(listener); return () => this.listeners.get(id)?.delete(listener); }
+    subscribeAll(listener) { this.globalListeners.add(listener); return () => this.globalListeners.delete(listener); }
+    async dispose(id) { const a = this.get(id); if (a.loading)
+        await a.loading.catch(() => { }); await a.backend?.dispose(); a.backend = undefined; a.record.status = 'unloaded'; }
+    async remove(id) { const a = this.get(id); if (a.loading)
+        await a.loading.catch(() => { }); await a.backend?.dispose(); this.agents.delete(id); this.listeners.delete(id); }
+    async archive(id) { const current = this.get(id).record; if (['starting', 'streaming', 'waiting_for_user', 'stopping'].includes(current.status))
+        throw Object.assign(new Error('Active Agent cannot be archived'), { code: 'AGENT_ACTIVE' }); const record = { ...current, status: 'unloaded' }; await this.remove(id); return record; }
+    async state(id) { return (await this.ensureLoaded(id)).getState(); }
+    async messages(id) { return (await this.ensureLoaded(id)).getMessages(); }
+    async messagePage(id, limit = 25, before) { return this.paginateMessages(await (await this.ensureLoaded(id)).getMessages(), limit, before); }
+    paginateMessages(messages, limit, before) { const safeLimit = Math.min(200, Math.max(1, Math.trunc(Number(limit) || 25))), total = messages.length, end = Math.min(total, Math.max(0, before === undefined ? total : Math.trunc(Number(before) || 0))), start = Math.max(0, end - safeLimit); return { items: messages.slice(start, end), total, start, end, limit: safeLimit, hasMore: start > 0 }; }
+    async capabilities(id) { return (await this.ensureLoaded(id)).getCapabilities(); }
+    async session(id) { return (await this.ensureLoaded(id)).getSession(); }
+    async sessionInfo(id) { return (await this.ensureLoaded(id)).getSessionInfo(); }
+    async compact(id, instructions) { return (await this.ensureLoaded(id)).compact(instructions); }
+    async setModel(id, provider, modelId) { return (await this.ensureLoaded(id)).setModel(provider, modelId); }
+    async setThinkingLevel(id, level) { return (await this.ensureLoaded(id)).setThinkingLevel(level); }
+    async setSessionName(id, name) { await (await this.ensureLoaded(id)).setSessionName(name); this.get(id).record.sessionName = name.trim(); }
+    async navigate(id, entryId) { return (await this.ensureLoaded(id)).navigate(entryId); }
+    async fork(id, entryId) { const source = this.get(id), result = await (await this.ensureLoaded(id)).fork(entryId); if (!result.sessionFile)
+        throw Object.assign(new Error('Session persistence is disabled'), { code: 'SESSION_NOT_PERSISTED' }); const ws = this.workspaces.get(source.record.workspaceId); const agent = await this.create(source.record.workspaceId, pathRelative(ws.rootPath, source.record.cwd), result.sessionFile); return { agent, selectedText: result.selectedText }; }
+    async extensionResponse(id, requestId, value) { return (await this.ensureLoaded(id)).extensionResponse(requestId, value); }
+}

package/dist/auth.js

@@ -0,0 +1,31 @@
+import { randomBytes, createHash, timingSafeEqual } from 'node:crypto';
+import { chmod, mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const hash = (token) => createHash('sha256').update(token).digest('hex');
+export class AuthStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    get file() { return path.join(this.dir, 'auth.json'); }
+    async init() { await mkdir(this.dir, { recursive: true }); try {
+        await readFile(this.file);
+        return {};
+    }
+    catch {
+        const token = randomBytes(32).toString('base64url');
+        await this.save({ tokenHash: hash(token), createdAt: new Date().toISOString() });
+        return { token };
+    } }
+    async save(data) { await writeFile(this.file, JSON.stringify(data, null, 2) + '\n', { mode: 0o600 }); await chmod(this.file, 0o600); }
+    async verify(token) { try {
+        const data = JSON.parse(await readFile(this.file, 'utf8'));
+        const a = Buffer.from(hash(token));
+        const b = Buffer.from(data.tokenHash);
+        return a.length === b.length && timingSafeEqual(a, b);
+    }
+    catch {
+        return false;
+    } }
+    async rotate() { const token = randomBytes(32).toString('base64url'); const old = JSON.parse(await readFile(this.file, 'utf8')); await this.save({ ...old, tokenHash: hash(token), rotatedAt: new Date().toISOString() }); return token; }
+}

package/dist/mail-notifier.js

@@ -0,0 +1,132 @@
+import { randomUUID } from 'node:crypto';
+import { assistantText } from './voice.js';
+const defaultSettings = { enabled: true, aggregationDelaySeconds: 0, includeResponse: true, includeSessionDetails: true };
+const clip = (value, max) => value.length <= max ? value : `${value.slice(0, max)}\n\n[内容过长，已截断]`;
+const oneLine = (value, max) => value.replace(/[\r\n\t]+/g, ' ').replace(/\s{2,}/g, ' ').trim().slice(0, max);
+export class MailNotifier {
+    fetcher;
+    lastAssistant = new Map();
+    queue = [];
+    timer;
+    pending = new Set();
+    closed = false;
+    settings = { ...defaultSettings };
+    config;
+    constructor(config, fetcher = fetch) {
+        this.fetcher = fetcher;
+        this.config = { priority: 100, timeoutMs: 15_000, ...config };
+    }
+    getSettings() { return { ...this.settings }; }
+    updateSettings(value) {
+        const next = { ...this.settings, ...value };
+        next.enabled = Boolean(next.enabled);
+        next.includeResponse = Boolean(next.includeResponse);
+        next.includeSessionDetails = Boolean(next.includeSessionDetails);
+        next.aggregationDelaySeconds = Math.trunc(Number(next.aggregationDelaySeconds));
+        if (!Number.isFinite(next.aggregationDelaySeconds) || next.aggregationDelaySeconds < 0 || next.aggregationDelaySeconds > 86400)
+            throw Object.assign(new Error('aggregationDelaySeconds must be an integer between 0 and 86400'), { code: 'INVALID_MAIL_NOTIFICATION_SETTINGS' });
+        this.settings = next;
+        if (!next.enabled) {
+            this.clearTimer();
+            this.queue = [];
+            return this.getSettings();
+        }
+        if (this.queue.length) {
+            this.clearTimer();
+            this.scheduleFlush();
+        }
+        return this.getSettings();
+    }
+    handleAgentEvent(agentId, event, context = {}) {
+        if (this.closed)
+            return;
+        if (event.type === 'message_end') {
+            const text = assistantText(event.message);
+            if (text)
+                this.lastAssistant.set(agentId, text);
+            return;
+        }
+        if (event.type !== 'agent_settled')
+            return;
+        const finalOutput = this.lastAssistant.get(agentId) ?? '';
+        this.lastAssistant.delete(agentId);
+        if (!this.settings.enabled)
+            return;
+        this.queue.push({ agentId, finalOutput, context });
+        if (!this.timer)
+            this.scheduleFlush();
+    }
+    async close() {
+        this.closed = true;
+        this.clearTimer();
+        if (this.queue.length)
+            await this.flushQueue();
+        await Promise.allSettled([...this.pending]);
+        this.lastAssistant.clear();
+    }
+    scheduleFlush() {
+        const delay = this.settings.aggregationDelaySeconds * 1000;
+        if (delay <= 0) {
+            this.startFlush();
+            return;
+        }
+        this.timer = setTimeout(() => { this.timer = undefined; this.startFlush(); }, delay);
+        this.timer.unref?.();
+    }
+    startFlush() {
+        const job = this.flushQueue().catch(error => console.error(`MailDispatch notification failed: ${error.message}`));
+        this.pending.add(job);
+        void job.finally(() => this.pending.delete(job));
+    }
+    async flushQueue() {
+        const items = this.queue.splice(0);
+        if (!items.length)
+            return;
+        await this.sendBatch(items);
+        if (this.queue.length && !this.timer && !this.closed)
+            this.scheduleFlush();
+    }
+    clearTimer() { if (this.timer) {
+        clearTimeout(this.timer);
+        this.timer = undefined;
+    } }
+    async sendBatch(items) {
+        const includeResponse = this.settings.includeResponse, includeSessionDetails = this.settings.includeSessionDetails, count = items.length;
+        let subject = `[Remote Pi] ${count > 1 ? `${count} 个 Agent 任务` : 'Agent 任务'}已完成`;
+        if (count === 1 && includeSessionDetails) {
+            const label = oneLine(items[0].context.sessionName || '', 80);
+            if (label)
+                subject = `[Remote Pi] ${label}已完成`;
+        }
+        let text;
+        if (!includeResponse && !includeSessionDetails)
+            text = count > 1 ? `${count} 个 Agent 任务已完成。` : '有 Agent 任务完成。';
+        else
+            text = items.map((item, index) => {
+                const lines = count > 1 ? [`任务 ${index + 1}`] : [];
+                if (includeSessionDetails) {
+                    lines.push(`Session：${item.context.sessionName?.trim() || '未命名'}`);
+                    if (item.context.cwd)
+                        lines.push(`路径：${item.context.cwd}`);
+                }
+                if (includeResponse) {
+                    if (lines.length)
+                        lines.push('');
+                    lines.push('Agent 回复：', clip(item.finalOutput.trim() || '（没有可用的最终文本回复）', 24_000));
+                }
+                return lines.join('\n');
+            }).join('\n\n--------------------\n\n');
+        const payload = {
+            to: [this.config.recipient], subject, text, priority: this.config.priority, purpose: 'transactional',
+            metadata: { source: 'remote-pi', task_count: count, notification_id: randomUUID() }
+        };
+        if (this.config.senderId)
+            payload.sender_id = this.config.senderId;
+        const response = await this.fetcher(this.config.endpoint, { method: 'POST', signal: AbortSignal.timeout(this.config.timeoutMs), headers: { authorization: `Bearer ${this.config.apiKey}`, 'content-type': 'application/json; charset=utf-8', accept: 'application/json', 'idempotency-key': randomUUID() }, body: JSON.stringify(payload) });
+        if (!response.ok)
+            throw new Error(`HTTP ${response.status}: ${(await response.text()).slice(0, 500)}`);
+        const result = await response.json().catch(() => undefined);
+        if (!result?.ok)
+            throw new Error('MailDispatch returned an invalid response');
+    }
+}