pi2web 0.2.1 → 0.2.8

package/README.md

@@ -19,7 +19,7 @@ npm 包名为 `pi2web`，全局命令同名（`pi2web`）。安装时会准备 `
 
 ```bash
 pi2web --host 127.0.0.1 --port 11318
-pi2web --data-dir ~/.pi/remote-pi
+pi2web --data-dir ~/.pi/pi2web     # 默认值；也可用环境变量 PI2WEB_DIR
 pi2web --rotate-access-token   # 旧配对码立即失效，输出新配对码
 pi2web --set-access-token <token>          # 手动设置配对码（16–128 位 URL-safe 字符）
 pi2web --set-access-token-env MY_TOKEN_ENV # 从环境变量读取配对码，推荐方式
@@ -110,11 +110,19 @@ pi2web \
 - 摘要 LLM 使用流式 Chat Completions；Remote Pi 在完整句子出现后立即调用流式 TTS，因此无需等待整段摘要完成。
 - Web UI 中点击“启用语音”后，会播放服务端推送的 PCM16 或 MP3 音频；新的 Agent 运行会取消该 Agent 尚未完成的播报。
 - 多个 Session 接近同时完成时，语音摘要会进入全局队列依次播放，不会重叠；有 Session 名称时以“会话{name}已完成：”开头。
-- 只有配置 `--voice-stt-model` 时，Web UI 才显示麦克风按钮；识别文字只插入输入框，不会自动发送。
+- 只有配置 `--voice-stt-model`，或在 Web UI「配置 → Sotto 语音输入」开启 Sotto 时，才显示麦克风按钮；识别文字只插入输入框，不会自动发送。
 - API key 通过 `--voice-api-key-env` 和 `--voice-summary-api-key-env` 指定环境变量名，避免把密钥放入命令行参数。
 
 语音流目前通过已认证的 Agent WebSocket 发送，只会实时投递，不写入 Session 或事件 replay。浏览器麦克风通常要求 HTTPS 安全上下文（`localhost` 例外）。
 
+### 使用本机 Sotto 进行语音输入（无需另一份 STT 模型）
+
+先在**与 pi2web Backend 同一台机器**启动支持 `/api/capabilities` 和 `/api/transcribe` 的 Sotto Web 版本，再在 pi2web 网页「配置 → Sotto 语音输入」勾选启用并保存。默认 endpoint 为 `http://127.0.0.1:8766`，指的是 **Backend 所在机器**，不是访问网页的手机或电脑；服务端只允许配置 IPv4 回环 HTTP 地址，不允许指向公网。启用时会探测 endpoint，不可用则不会保存开启状态。设置保存在 pi2web 的数据目录，所有使用该 Backend 的网页共享；默认关闭，不配语音识别时麦克风按钮保持隐藏。
+
+浏览器点击麦克风后持续采集单声道 float32 PCM，经 pi2web 已认证的 Agent WebSocket 转发至本机 Sotto；Sotto 持续返回 **partial/final**，网页边说边更新输入框；再次点击停止并定稿，**不会自动发送给 Agent**。切到 Terminal 等其他视图时录音继续；连续 1 分钟没有新的识别文字会自动停止并保留已识别内容。Sotto 复用已加载的 ASR（首次请求才加载一次），使用独立本机 WS 端口（默认 `8768`，即 Web 端口 +2），不对外开放。浏览器需支持安全上下文、Web Audio、麦克风权限；`Alt+Shift+V` 可启停。Sotto 的 ASR 实时测试运行时不能并用实时输入，普通监听可并存但共享同一个识别器。原有 `--voice-*` 语音摘要和 STT 功能保持独立；不要同时配置另一套 STT 模型，除非确实需要第二个识别服务。
+
+实时听写采用**点击开始、再次点击停止**：停顿只用于分句定稿，不会结束录音，也没有固定一分钟的录音上限。停止时先发送 Worklet 中尚未发送的尾部音频，再等待最终结果。切换 Agent 或归档录音所属 Agent 会取消录音，切到 Terminal 则继续；关闭 Sotto 或修改其服务地址会结束该 Backend 所有网页已经建立的实时语音连接，当前网页尚在启动的采集也会取消。停止已有录音不受“能否开始新录音”的条件限制；连接、麦克风或音频积压异常会停止并提示原因。代理仍限制单帧大小及发送积压，连续 30 秒没有收到音频帧会报错关闭连接（静音也会产生音频帧，因此不是“静音超时”）。启动中再次点击可取消；后台运行时请留意浏览器的麦克风指示并主动停止录音。
+
 ### Edge TTS（仅语音合成）
 
 项目提供了一个基于 Python `edge-tts` 和 `aiohttp` 的轻量本地服务。它直接返回 MP3，不需要 Docker 或 FFmpeg：
@@ -145,7 +153,7 @@ pi2web \
 
 自动命名是独立于语音的功能，**默认开启**：Agent 每次任务结束（`agent_settled`）后，如果 Session 还没有名字，就用一个 OpenAI 兼容的接口生成简短标题并写入 Session。不开语音时只生成标题，不会产生任何语音；开了语音播报时仍然只由命名器负责命名，语音负责朗读摘要。
 
-默认值：`--session-name-base-url http://localhost:8313/`、`--session-name-model gpt-5-mini`、无 API Key。可用参数：
+默认值：`--session-name-base-url http://localhost:8313/`、`--session-name-model gpt-5.4-nano`、无 API Key。可用参数：
 
 ```
 --session-naming <on|off>            关闭或开启自动命名（默认 on）
@@ -170,13 +178,26 @@ npm test
 npm run dev -- --port 11318
 ```
 
+源码使用 Prettier 统一格式：`npm run format` 和 `npm run format:check` 覆盖 `src/**/*.ts` 与 `web/*.js`；不要格式化 `dist/` 或网站生成文件 `website/public/`，也不要把纯格式改动与功能修改混在同一次提交。
+
 ## 数据持久化
 
-Remote Pi 的服务端元数据保存在 `~/.pi/remote-pi/remote-pi.db` SQLite 数据库中：
+pi2web 的服务端数据目录是 `~/.pi/pi2web`（`--data-dir` 或 `PI2WEB_DIR` 可覆盖）。旧版本使用的 `~/.pi/remote-pi` 不再读取，请在停止服务后运行一次迁移脚本：
+
+```bash
+python scripts/migrate_data_dir.py --dry-run   # 查看计划
+python scripts/migrate_data_dir.py             # 复制 ~/.pi/remote-pi -> ~/.pi/pi2web，remote-pi.db 改名为 pi2web.db
+```
+
+脚本使用 SQLite backup API（包含 WAL 中尚未落盘的数据），不修改源目录；目标目录已有同名文件时会中止，`--force` 会先把它们移到 `pre-migration-<时间>/`。
+
+元数据保存在 `~/.pi/pi2web/pi2web.db` SQLite 数据库中：
 
 - `workspaces`：Workspace ID、名称、根目录和创建时间。
 - `agents`：Agent 与 Workspace/Session 的映射、cwd、状态、创建/最后活动时间以及 Archive 状态。
 - `sessions`：用于 Session 列表、排序和分页的轻量索引，包括名称、文件路径、消息数量、文件 mtime/size 和最后活动时间。
+- `agents.template`：Agent 的 System Prompt 模板快照（JSON）。仅在第一条会话消息前可修改，保存成功后才生效；对话开始后固定，卸载或重启不会改变。
+- `agent-templates/*.md`：可分享的 Agent 模板文件，见下文「System Prompt 与 Agent 模板」。
 - `auth.json`：配对码的 SHA-256 hash、创建和轮换时间；认证数据仍单独保存，不保存配对码明文，文件权限为 `0600`。
 
 数据库使用 WAL、短事务、部分索引和批量延迟更新。Session 活动时间不会随每个 streaming token 写入，而是在完整消息、Agent 完成和 Session 信息变化时合并持久化。旧版 `workspaces.json`、`agents.json` 和 `agents_archive.json` 不会被读取、迁移或继续写入。
@@ -233,7 +254,7 @@ Terminal 是以 Remote Pi 进程用户身份运行的完整宿主机 Shell。Wor
 
 这些约定针对上述 Nozzala 固件，不是所有相同 VID/PID 设备的通用规范。连接前请退出其他控制该键盘的 ChatGPT/Codex App，避免设备占用或灯光互相覆盖。
 
-灯效恢复使用服务器活动快照：`state.activity.bashIds` 表示在途的独立 Shell，`state.activity.dialogIds` 表示待回答的扩展对话框。这些 ID 只保存在服务进程内存中，不写入数据库或 Pi Session；LLM 的 `idle` 不代表它们已结束。回放缺口通过 `agent_snapshot.state` 恢复，随后按序补发快照构建期间的事件。每次订阅在回放完成后、实时事件开始前发送 `agent_state` 当前状态；首次 `fromNow` 订阅或已有游标但无新事件时也会发送，因此刷新页面无需等下一段 Shell 输出才能恢复灯效。旧服务端未提供 `activity` 时仍按普通 Agent 状态降级显示。不支持 WebHID 或安全上下文的浏览器会静默跳过自动连接，配置页保留原因说明。
+灯效直接映射服务器维护的 Agent 活动状态（`state.activity`：当前阶段、在途的独立 Shell、待回答的扩展对话框），连接时随 `agent_state` 下发、变化时以 `activity_changed` 推送；这些状态只保存在服务进程内存中，不写入数据库或 Pi Session，LLM 的 `idle` 不代表独立 Shell 或对话框已结束。不支持 WebHID 或安全上下文的浏览器会静默跳过自动连接，配置页保留原因说明。
 
 活动快照中的 `state.activity.dialogRequests` 还包含待回答对话框的原始请求（不含用户答案），刷新或回放缺口后可恢复回答控件。服务端复用同一份内存请求记录，前端按 request ID 避免重复创建对话框；已结束的请求不会再出现在快照中。
 
@@ -327,6 +348,10 @@ Web 看板在 `/collab.html`（首页顶部"协作"入口）：会话列表与
 - `GET /api/v1/sessions`
 - `GET/POST /api/v1/agents`（创建时可带 `profile`：`default`（默认）或 `collab`；`collab` 会加载协作工具，供协作看板占座使用）
 - `GET/DELETE /api/v1/agents/:id`
+- `POST /api/v1/agents` 可带 `templateId` 选择 Agent 模板；`GET /api/v1/agents/:id/system-prompt` 返回该 Agent 当前生效的 System Prompt、模板快照及来源文件。
+- `GET/PUT /api/v1/system-prompt`：读取 / 写入 Pi 全局 `~/.pi/agent/SYSTEM.md`、`APPEND_SYSTEM.md`（`{kind: "system"|"append", content}`，空内容即删除文件）。
+- `GET /api/v1/system-prompt/preview?workspaceId=&relativeCwd=&templateId=&source=pi-default`：生成指定 cwd 下的有效 System Prompt；`source=pi-default` 忽略 SYSTEM.md / APPEND_SYSTEM.md，显示 Pi 内置 Prompt。
+- `GET /api/v1/agent-templates`、`GET/PUT/DELETE /api/v1/agent-templates/:id`：管理 Agent 模板文件。
 - `GET/POST /api/v1/collab/sessions`、`/sessions/:id`、`/participants`（含 `/participants/:pid/binding`、`/participants/:pid/budget`）、`/advance`、`/ready`、`/recheck`（**仅人**，重开时轮换每个座位的 token 并在响应 `participantTokens` 里返回一次）、`/policy`、`/events`（`?since=` 游标或 `?tail=` 取最新若干条）、`/digest`、`/issues`、`/findings`、`/issue-votes`、`/merge-votes`、`/issue-discussions`、`/review-consensus`、`/review-rounds`（**仅人**）、`/retry-waiting`、`/escalations`、`/report`（**仅人**），以及 scoring 场景的 `/nominations`、`/votes`、`/criteria`、`/scores`、`/analysis`、`/debates`、`/finalize`（**仅人**，且只在 `awaiting_human` 阶段接受，必须为每个争议维度给一个合刻度的分数）
 - `GET /api/v1/collab/escalations`、`POST /api/v1/collab/escalations/:id/resolve`
 - `GET/POST /api/v1/terminals`
@@ -337,7 +362,29 @@ Web 看板在 `/collab.html`（首页顶部"协作"入口）：会话列表与
 - `GET /api/v1/agents/:id/mcp` 返回该 Agent cwd 下的 MCP 服务器配置（全局 `mcp.json` 与受信任项目的 `.pi/mcp.json`），`POST` 用 `{name, enabled}` 启用或停用。只有项目被 Pi 显式信任时才会写入项目级覆盖，否则写全局文件。修改在 Agent 下次加载时生效。
 - `GET /api/v1/agents/:id/commands` 返回该 Agent cwd 下可用的 prompt template 和 skill（`{name, description, argumentHint, source}`）。`prompt` 接口本身会展开 `/命令`、skill 和 prompt template。
 - `POST /api/v1/agents/:id/bash` 在 Agent Session 内执行命令（`{command, excludeFromContext}`），输出通过 `bash_execution_update` 事件流式推送并记录到 Session；`POST /api/v1/agents/:id/bash-abort` 取消。
-- WebSocket `/api/v1/ws` 支持 sequence、replay、snapshot、`fromNow` 和 Agent command；`subscribe_collab` 推送协作事件。
+- WebSocket `/api/v1/ws`（协议 v2，不做事件回放）：`subscribe_all` 先下发每个 Agent 的当前状态，再推送所有 Agent 的概览事件（状态、活动、队列、对话框、通知）；`focus` 选定正在查看的 Agent，只为它推送流式文本、时间线条目变化和用户 Shell 输出；`watch` 订阅已展开的运行中工具的输出；`subscribe_collab` 推送协作事件。
+- 会话内容通过 HTTP 时间线读取：`GET /api/v1/agents/:id/timeline?limit&before` 返回条目摘要（正文较小或需要阅读的条目内联），`GET /api/v1/agents/:id/sessions/:sessionId/items/:itemId` 按需返回完整正文；已完成条目永不改变，响应带 `immutable` 缓存头，浏览器可永久缓存。
+
+## System Prompt 与 Agent 模板
+
+Web UI「配置 → 管理 System Prompt…」可以：
+
+- 预览当前 Workspace / 工作路径下 Agent 实际会使用的 System Prompt，或忽略全局文件的 Pi 内置 Prompt；
+- 编辑 Pi 自己的全局 `~/.pi/agent/SYSTEM.md`（替换 Pi 基础 Prompt）和 `APPEND_SYSTEM.md`（追加），这两个文件同样作用于 Pi CLI；受信任项目的 `.pi/SYSTEM.md`、`.pi/APPEND_SYSTEM.md` 优先；
+- 管理 Agent 模板。
+
+Agent 模板是 `~/.pi/pi2web/agent-templates/<id>.md` 文件，直接复制即可分享，手动放进目录的文件会立即出现：
+
+```markdown
+---
+name: Code reviewer
+description: 只审查，不修改文件
+mode: append        # append：追加在 Pi Prompt 之后；replace：替换 Pi 基础 Prompt（等同 SYSTEM.md）
+---
+You are a meticulous code reviewer. ...
+```
+
+新建 Agent 时可选择模板（默认是 Pi 自己的 Prompt）。模板内容复制为 Agent 自己的快照；**第一条会话消息前可以修改，开始对话后不能更改**。模板替换与会话写入共用准入检查，写入期间不能替换，替换期间不能写入。修改操作先保存到数据库再启用，保存失败则保留原模板；Stop 或归档会使未完成的替换失效，迟到的候选会话会被释放，不会重新启用 Agent。后端重启或 Agent 重新加载仍使用最后保存的快照，不会退回创建时的选择。修改或删除模板文件不影响已有 Agent，Fork 出的 Agent 沿用同一模板。两种模式下 Pi 仍会加上 AGENTS.md 等项目上下文、skills 和 cwd；`replace` 会去掉 Pi 内置的工具说明、规则和文档段落，`APPEND_SYSTEM.md` 仍然生效。Agent 工具栏的「Prompt」按钮显示该 Agent 当前生效的完整 System Prompt。
 
 运行时使用真实 `@earendil-works/pi-coding-agent` SDK，并复用 Pi CLI 的 `~/.pi/agent` 模型、认证和设置。`MockBackend` 只用于自动化测试。
 

package/dist/activity.js

@@ -0,0 +1,178 @@
+const SUMMARY_LIMIT = 80;
+const SUMMARY_KEYS = ['command', 'path', 'file_path', 'pattern', 'query', 'url'];
+/** A one-line hint of what a tool call works on: its command, path, pattern... */
+export function toolSummary(args) {
+    if (!args || typeof args !== 'object')
+        return undefined;
+    const record = args;
+    const value = SUMMARY_KEYS.map(key => record[key]).find(v => typeof v === 'string' && v.trim()) ??
+        Object.values(record).find(v => typeof v === 'string' && v.trim());
+    if (typeof value !== 'string')
+        return undefined;
+    const line = value.trim().replace(/\s+/g, ' ');
+    return line.length > SUMMARY_LIMIT ? `${line.slice(0, SUMMARY_LIMIT - 1)}…` : line;
+}
+const str = (value) => (typeof value === 'string' ? value : undefined);
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+/**
+ * Server-side state machine over raw Pi events. It is the single source of truth for
+ * "what is this Agent doing and since when", so any client can show it at any time,
+ * including after switching sessions, reloading or reconnecting.
+ */
+export class ActivityTracker {
+    now;
+    state;
+    constructor(now = Date.now) {
+        this.now = now;
+        this.state = { run: null, phase: { kind: 'idle', since: now() }, bash: [], dialogs: [] };
+    }
+    snapshot() {
+        return structuredClone(this.state);
+    }
+    /** Forget everything, e.g. when the backend is unloaded. Returns whether anything changed. */
+    reset() {
+        const s = this.state;
+        if (!s.run && s.phase.kind === 'idle' && !s.bash.length && !s.dialogs.length)
+            return false;
+        this.state = { run: null, phase: { kind: 'idle', since: this.now() }, bash: [], dialogs: [] };
+        return true;
+    }
+    /** The user asked to abort the current run. */
+    stopping() {
+        if (!this.state.run || this.state.phase.kind === 'stopping')
+            return false;
+        return this.setPhase({ kind: 'stopping' });
+    }
+    /** Apply one raw Pi event. Returns whether the activity changed, so callers publish only real changes. */
+    apply(event) {
+        const e = event, s = this.state;
+        switch (event.type) {
+            case 'agent_start': {
+                const startedRun = !s.run;
+                if (startedRun)
+                    s.run = { startedAt: this.now() };
+                return this.setPhase({ kind: 'waiting_llm' }) || startedRun;
+            }
+            case 'turn_start':
+                return this.setPhase({ kind: 'waiting_llm' });
+            case 'message_update': {
+                const update = e.assistantMessageEvent, type = str(update?.type);
+                if (type === 'thinking_start' || type === 'thinking_delta')
+                    return this.setPhase({ kind: 'thinking' });
+                if (type === 'text_start' || type === 'text_delta')
+                    return this.setPhase({ kind: 'generating' });
+                if (type === 'toolcall_start' || type === 'toolcall_delta') {
+                    const toolName = str(update.partial?.content?.[update.contentIndex]?.name);
+                    // The name may only arrive with a later delta: fill it in without restarting the timer.
+                    if (s.phase.kind === 'preparing_tool' && !s.phase.toolName && toolName) {
+                        s.phase.toolName = toolName;
+                        return true;
+                    }
+                    return this.setPhase({ kind: 'preparing_tool', ...(toolName ? { toolName } : {}) });
+                }
+                return false;
+            }
+            case 'tool_execution_start': {
+                // Tools called by other tools run inside their caller's time; show only top-level calls.
+                if (e.parentToolCallId)
+                    return false;
+                const tool = {
+                    toolCallId: String(e.toolCallId ?? ''),
+                    toolName: str(e.toolName) ?? 'tool',
+                    summary: toolSummary(e.args),
+                    since: this.now()
+                };
+                if (s.phase.kind === 'running_tools') {
+                    s.phase.tools.push(tool);
+                    return true;
+                }
+                return this.setPhase({ kind: 'running_tools', tools: [tool] });
+            }
+            case 'tool_execution_end': {
+                if (e.parentToolCallId || s.phase.kind !== 'running_tools')
+                    return false;
+                const tools = s.phase.tools.filter(tool => tool.toolCallId !== e.toolCallId);
+                if (tools.length === s.phase.tools.length)
+                    return false;
+                if (tools.length) {
+                    s.phase.tools = tools;
+                    return true;
+                }
+                return this.setPhase({ kind: 'waiting_llm' });
+            }
+            case 'auto_retry_start': {
+                if (!s.run)
+                    s.run = { startedAt: this.now() };
+                const delay = num(e.delayMs);
+                return this.setPhase({
+                    kind: 'retrying',
+                    attempt: num(e.attempt),
+                    maxAttempts: num(e.maxAttempts),
+                    retryAt: delay === undefined ? undefined : this.now() + delay,
+                    error: str(e.errorMessage)
+                }, true);
+            }
+            case 'compaction_start':
+                return this.setPhase({ kind: 'compacting', reason: str(e.reason) });
+            case 'compaction_end':
+                return this.setPhase({ kind: s.run ? 'waiting_llm' : 'idle' });
+            case 'agent_end':
+                if (e.willRetry === true)
+                    return false;
+                return this.endRun();
+            case 'agent_settled':
+                // Settled: nothing of the run is left, compaction included. Shell commands and dialogs stay.
+                return this.endRun(true);
+            case 'bash_execution_start':
+            case 'bash_execution_update': {
+                const id = str(e.id);
+                if (!id || s.bash.some(b => b.id === id))
+                    return false;
+                s.bash.push({ id, command: str(e.command), since: this.now() });
+                return true;
+            }
+            case 'bash_execution_end': {
+                const before = s.bash.length;
+                s.bash = s.bash.filter(b => b.id !== e.id);
+                return s.bash.length !== before;
+            }
+            case 'extension_ui_request': {
+                const requestId = str(e.requestId);
+                if (!requestId || s.dialogs.some(d => d.requestId === requestId))
+                    return false;
+                s.dialogs.push({ requestId, title: str(e.title) ?? str(e.message), since: this.now() });
+                return true;
+            }
+            case 'extension_ui_response': {
+                const before = s.dialogs.length;
+                s.dialogs = s.dialogs.filter(d => d.requestId !== e.requestId);
+                return s.dialogs.length !== before;
+            }
+            default:
+                return false;
+        }
+    }
+    endRun(settled = false) {
+        const hadRun = !!this.state.run;
+        this.state.run = null;
+        // Compaction may continue after the run has ended; agent_settled closes it.
+        if (this.state.phase.kind === 'compacting' && !settled)
+            return hadRun;
+        return this.setPhase({ kind: 'idle' }) || hadRun;
+    }
+    /**
+     * Enter a phase. Staying in the same phase keeps its start time, so a stream of deltas
+     * neither resets the timer nor counts as a change. `force` restarts it (e.g. each retry).
+     */
+    setPhase(next, force = false) {
+        const current = this.state.phase;
+        if (!force && current.kind === next.kind && Object.keys(next).every(key => current[key] === next[key]))
+            return false;
+        const phase = { ...next, since: this.now() };
+        for (const key of Object.keys(phase))
+            if (phase[key] === undefined)
+                delete phase[key];
+        this.state.phase = phase;
+        return true;
+    }
+}

package/dist/agent-feed.js

@@ -0,0 +1,133 @@
+import { buildTimeline, contentText, pageTimeline } from './timeline.js';
+/**
+ * Turns one backend's raw events into the detail stream. After any event, if the session's
+ * leaf moved, the branch is projected again and the items after the published ones are sent.
+ */
+export class AgentFeed {
+    source;
+    emit;
+    published;
+    live = { active: false, text: '', thinking: '' };
+    clearLive = false;
+    outputs = new Map();
+    timer;
+    closed = false;
+    constructor(source, emit) {
+        this.source = source;
+        this.emit = emit;
+        this.published = this.project().published;
+    }
+    /**
+     * Everything a client needs to start viewing: the newest page and the text streamed so far.
+     * Publishes pending changes first, so the next message a subscriber gets is newer than this.
+     */
+    snapshot(limit) {
+        this.sync();
+        const source = this.source(), { active, text, thinking } = this.live;
+        return {
+            sessionId: source.sessionId,
+            page: pageTimeline(buildTimeline(source.entries()), limit),
+            live: active || text || thinking ? { text, thinking } : null
+        };
+    }
+    output(toolCallId) {
+        return this.outputs.get(toolCallId);
+    }
+    handle(event) {
+        const e = event;
+        switch (event.type) {
+            case 'message_start':
+                if (e.message?.role === 'assistant' || e.role === 'assistant') {
+                    // The previous message is persisted by now; publish it before streaming the next.
+                    this.sync();
+                    this.live = { active: true, text: '', thinking: '' };
+                }
+                break;
+            case 'message_update': {
+                const update = e.assistantMessageEvent;
+                if ((update?.type === 'text_delta' || update?.type === 'thinking_delta') &&
+                    typeof update.delta === 'string') {
+                    const kind = update.type === 'text_delta' ? 'text' : 'thinking';
+                    this.live[kind] += update.delta;
+                    this.emit({ type: 'delta', kind, delta: update.delta });
+                }
+                return; // Deltas never change the persisted timeline.
+            }
+            case 'message_end':
+                if (this.live.active) {
+                    this.live.active = false;
+                    this.clearLive = true;
+                }
+                break;
+            case 'tool_execution_update':
+                if (!e.parentToolCallId && typeof e.toolCallId === 'string') {
+                    const result = e.partialResult, output = contentText(result?.content ?? result) || (result ? JSON.stringify(result) : '');
+                    this.outputs.set(e.toolCallId, output);
+                    this.emit({ type: 'tool_output', toolCallId: e.toolCallId, output });
+                }
+                return;
+            case 'tool_execution_end':
+                this.outputs.delete(String(e.toolCallId));
+                break;
+            case 'bash_execution_start':
+            case 'bash_execution_update':
+            case 'bash_execution_end':
+                this.emit({ type: 'event', event });
+                break;
+        }
+        this.schedule();
+    }
+    /** Pi persists a message right after notifying listeners of it, so look once the event has finished. */
+    schedule() {
+        if (this.timer || this.closed)
+            return;
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.sync();
+        }, 0);
+    }
+    /** Publish what changed on the timeline since the last call. Cheap when the leaf did not move. */
+    sync() {
+        if (this.closed)
+            return;
+        const source = this.source(), previous = this.published;
+        if (source.sessionId === previous.sessionId && source.leafId === previous.leafId && !this.clearLive)
+            return;
+        const { published, records, entries } = this.project(source);
+        this.published = published;
+        // An append keeps the old leaf on the branch and every item published so far.
+        const appended = source.sessionId === previous.sessionId &&
+            (previous.leafId === null || entries.some(entry => entry.id === previous.leafId)) &&
+            previous.ids.every((id, i) => published.ids[i] === id);
+        const clearLive = this.clearLive;
+        this.clearLive = false;
+        if (clearLive)
+            this.live = { active: false, text: '', thinking: '' };
+        if (!appended) {
+            this.emit({ type: 'timeline_reset', sessionId: source.sessionId });
+            return;
+        }
+        const items = records.slice(previous.ids.length).map(r => r.item);
+        if (!items.length && !clearLive)
+            return;
+        this.emit({
+            type: 'items',
+            sessionId: source.sessionId,
+            items,
+            ...(clearLive ? { clearLive: true } : {})
+        });
+    }
+    close() {
+        this.closed = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+    }
+    project(source = this.source()) {
+        const entries = source.entries(), records = buildTimeline(entries);
+        return {
+            published: { sessionId: source.sessionId, leafId: source.leafId, ids: records.map(r => r.item.id) },
+            records,
+            entries
+        };
+    }
+}

package/dist/agent-templates.js

@@ -0,0 +1,144 @@
+import { getAgentDir, parseFrontmatter } from '@earendil-works/pi-coding-agent';
+import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const MAX_PROMPT = 200_000;
+const invalid = (message) => Object.assign(new Error(message), { code: 'INVALID_REQUEST' });
+export const validTemplateId = (id) => typeof id === 'string' && ID.test(id) && !id.endsWith('.') && id !== 'default';
+const asMode = (value) => value === 'replace' || value === 'append' ? value : undefined;
+/** Serialize a template as Markdown with YAML front matter; JSON strings are valid YAML scalars. */
+export const formatTemplateFile = (template) => [
+    '---',
+    `name: ${JSON.stringify(template.name)}`,
+    ...(template.description ? [`description: ${JSON.stringify(template.description)}`] : []),
+    `mode: ${template.mode}`,
+    '---',
+    '',
+    template.systemPrompt.trim(),
+    ''
+].join('\n');
+/**
+ * Agent templates are plain files under `<data-dir>/agent-templates/<id>.md` so they can be shared by copying:
+ *
+ * ```markdown
+ * ---
+ * name: Code reviewer
+ * description: Reviews diffs, never edits files
+ * mode: replace        # or append
+ * ---
+ * You are a meticulous code reviewer...
+ * ```
+ *
+ * Files are re-read on every call, so templates dropped into the directory by hand show up immediately.
+ */
+export class AgentTemplateStore {
+    dir;
+    constructor(dir) {
+        this.dir = dir;
+    }
+    fileFor(id) {
+        if (!validTemplateId(id))
+            throw invalid('Template id must be 1-64 letters, digits, dot, underscore or hyphen');
+        return path.join(this.dir, `${id}.md`);
+    }
+    read(id, file) {
+        const raw = readFileSync(file, 'utf8');
+        let frontmatter = {}, body = raw;
+        try {
+            ({ frontmatter, body } = parseFrontmatter(raw));
+        }
+        catch (error) {
+            throw Object.assign(new Error(`Invalid front matter in ${file}: ${error.message}`), {
+                code: 'INVALID_TEMPLATE'
+            });
+        }
+        const name = typeof frontmatter.name === 'string' && frontmatter.name.trim() ? frontmatter.name.trim() : id;
+        return {
+            id,
+            name,
+            description: typeof frontmatter.description === 'string' ? frontmatter.description.trim() : '',
+            mode: asMode(frontmatter.mode) ?? 'append',
+            systemPrompt: body.trim(),
+            file,
+            updatedAt: statSync(file).mtime.toISOString()
+        };
+    }
+    list() {
+        if (!existsSync(this.dir))
+            return { templates: [], errors: [] };
+        const templates = [], errors = [];
+        for (const entry of readdirSync(this.dir, { withFileTypes: true })) {
+            if (!entry.isFile() || !entry.name.endsWith('.md'))
+                continue;
+            const id = entry.name.slice(0, -3);
+            if (!validTemplateId(id)) {
+                errors.push(`Ignored ${entry.name}: invalid template id`);
+                continue;
+            }
+            try {
+                templates.push(this.read(id, path.join(this.dir, entry.name)));
+            }
+            catch (error) {
+                errors.push(error.message);
+            }
+        }
+        templates.sort((a, b) => a.name.localeCompare(b.name) || a.id.localeCompare(b.id));
+        return { templates, errors };
+    }
+    get(id) {
+        const file = this.fileFor(id);
+        if (!existsSync(file))
+            throw Object.assign(new Error(`Agent template not found: ${id}`), { code: 'TEMPLATE_NOT_FOUND' });
+        return this.read(id, file);
+    }
+    save(id, input) {
+        const file = this.fileFor(id);
+        const name = typeof input.name === 'string' && input.name.trim() ? input.name.trim() : id;
+        if (name.length > 100 || /[\r\n]/.test(name))
+            throw invalid('name must be a single line of at most 100 characters');
+        const description = typeof input.description === 'string' ? input.description.trim() : '';
+        if (description.length > 500 || /[\r\n]/.test(description))
+            throw invalid('description must be a single line of at most 500 characters');
+        const mode = asMode(input.mode);
+        if (!mode)
+            throw invalid('mode must be replace or append');
+        if (typeof input.systemPrompt !== 'string' || !input.systemPrompt.trim())
+            throw invalid('systemPrompt is required');
+        if (input.systemPrompt.length > MAX_PROMPT)
+            throw invalid('systemPrompt is too long');
+        mkdirSync(this.dir, { recursive: true });
+        writeFileSync(file, formatTemplateFile({ name, description, mode, systemPrompt: input.systemPrompt }), 'utf8');
+        return this.read(id, file);
+    }
+    remove(id) {
+        const file = this.fileFor(id);
+        if (!existsSync(file))
+            throw Object.assign(new Error(`Agent template not found: ${id}`), { code: 'TEMPLATE_NOT_FOUND' });
+        rmSync(file);
+    }
+    snapshot(id) {
+        const { name, mode, systemPrompt } = this.get(id);
+        return { id, name, mode, systemPrompt };
+    }
+}
+const PI_PROMPT_FILES = { system: 'SYSTEM.md', append: 'APPEND_SYSTEM.md' };
+export const piPromptFile = (kind, agentDir = getAgentDir()) => path.join(agentDir, PI_PROMPT_FILES[kind]);
+export function readPiPromptFiles(agentDir = getAgentDir()) {
+    const read = (kind) => {
+        const file = piPromptFile(kind, agentDir), exists = existsSync(file);
+        return { path: file, exists, content: exists ? readFileSync(file, 'utf8') : '' };
+    };
+    return { agentDir, system: read('system'), append: read('append') };
+}
+/** Write (or, for an empty value, delete) a global Pi prompt file. Deleting SYSTEM.md restores Pi's built-in prompt. */
+export function writePiPromptFile(kind, content, agentDir = getAgentDir()) {
+    if (content.length > MAX_PROMPT)
+        throw invalid('content is too long');
+    const file = piPromptFile(kind, agentDir);
+    if (!content.trim())
+        rmSync(file, { force: true });
+    else {
+        mkdirSync(agentDir, { recursive: true });
+        writeFileSync(file, content, 'utf8');
+    }
+}