pi2web 0.2.6 → 0.2.12

package/README.md

@@ -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：
@@ -188,7 +196,7 @@ python scripts/migrate_data_dir.py             # 复制 ~/.pi/remote-pi -> ~/.pi
 - `workspaces`：Workspace ID、名称、根目录和创建时间。
 - `agents`：Agent 与 Workspace/Session 的映射、cwd、状态、创建/最后活动时间以及 Archive 状态。
 - `sessions`：用于 Session 列表、排序和分页的轻量索引，包括名称、文件路径、消息数量、文件 mtime/size 和最后活动时间。
-- `agents.template`：Agent 创建时选定的 System Prompt 模板快照（JSON），之后不可修改。
+- `agents.template`：Agent 的 System Prompt 模板快照（JSON）。仅在第一条会话消息前可修改，保存成功后才生效；对话开始后固定，卸载或重启不会改变。
 - `agent-templates/*.md`：可分享的 Agent 模板文件，见下文「System Prompt 与 Agent 模板」。
 - `auth.json`：配对码的 SHA-256 hash、创建和轮换时间；认证数据仍单独保存，不保存配对码明文，文件权限为 `0600`。
 
@@ -215,8 +223,9 @@ Web 端能力：
 
 - Workspace 添加、目录浏览、文本文件分页及二进制提示。
 - Workspace 目录右键在交互式 Terminal 中打开；Terminal 与 Agent 显示在同一列表，支持刷新重连、清屏和关闭。
-- 创建/恢复 Session、Agent 列表、停止与 abort；Agent 右键 Archive。
-- Prompt、steer、follow-up 和流式对话。
+- 新建 Agent 时始终创建新 Session；已有 Agent 可在刷新或重启后继续使用。通过 Session 文件恢复对话暂仅支持 API，不在新建弹窗中提供；Agent 列表支持停止与 abort，右键 Archive。
+- Prompt、steer、follow-up 和流式对话。HTTP / WebSocket 发送命令在 Pi 校验并接收消息后即确认，不等待整个回合结束；执行进度继续通过 WebSocket 同步。
+- 手机切后台或网络中断导致发送确认丢失时，显示「送达状态未知」并保留原文供核对，不自动重发或放回输入框。提示在同一页面内切换会话、重连后仍保留，可手动关闭；刷新页面不保留。明确被服务端拒绝的消息仍恢复为草稿。
 - 对话区只保留用户输入、Agent 输出、Thinking、Extension 对话框和错误；Tool call、Session bash 输出、Retry、Summarization retry 等过程事件自动折叠成一张"活动"卡片，卡片标题实时显示最新一项的名称和时间，展开后逐条查看，再点击单条查看内容。
 - 同一次 Tool call 的 start / update / end 合并为一张卡片（参数 + 输出 + 结果），结束后显示 Pi 记录的执行耗时。
 - Tool 自己发起的调用（codemode 脚本、MCP 批量调用）带 `parentToolCallId`，会嵌套显示在发起它的那张卡片里。
@@ -354,6 +363,7 @@ 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` 取消。
+- `POST /api/v1/agents/:id/pause` 安全暂停：对话不再前进——正在执行的工具跑完、结果写入 Session 后，不再产生新的模型回复或工具调用（Agent 循环的下一轮，以及自动重试、溢出压缩后的重试、排队消息、扩展 `agent_before_settle` 要求的续跑都会被拦下；正在等待的重试退避会被立即取消）。Session 以工具结果（或用户消息）结尾，重启后也不丢失，之后发送新消息即从这里继续；暂停时排队的消息留在队列里，随下一次 prompt 送达。不拦截不推进对话的整理性模型调用（压缩摘要、提示缓存保温；保温仅在 `cacheWarming: idle` 时于暂停后继续，最长 30 分钟）。进度通过 `safe_pause` 事件推送：`requested`、`reached`（已拦下一次模型请求，正在收尾）、`paused`、`cancelled`、`finished`（未到暂停点运行就自行结束）；活动状态带 `pauseRequested {since, reached?}`。被暂停运行的 `agent_settled` 带 `paused: true`，邮件通知按“已中断”处理、语音不播报。`DELETE` 同一路径撤回暂停：已到暂停点、运行仍在收尾时（`reached` 之后、`paused` 之前）返回 `PAUSE_ALREADY_REACHED`；没有待生效的暂停时（包括运行已结束）为无操作并返回成功。撤回是否赶上以 `safe_pause` 事件（`cancelled` 或 `paused`）为准。
 - 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` 缓存头，浏览器可永久缓存。
 
@@ -376,7 +386,7 @@ mode: append        # append：追加在 Pi Prompt 之后；replace：替换 Pi
 You are a meticulous code reviewer. ...
 ```
 
-新建 Agent 时可选择模板（默认是 Pi 自己的 Prompt）。模板内容在创建时复制到 Agent 记录中，**之后不能更改**：修改或删除模板文件不影响已有 Agent，Fork 出的 Agent 沿用同一模板。两种模式下 Pi 仍会加上 AGENTS.md 等项目上下文、skills 和 cwd；`replace` 会去掉 Pi 内置的工具说明、规则和文档段落，`APPEND_SYSTEM.md` 仍然生效。Agent 工具栏的「Prompt」按钮显示该 Agent 当前生效的完整 System Prompt。
+新建 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

@@ -22,6 +22,7 @@ const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? va
 export class ActivityTracker {
     now;
     state;
+    lastMetricsPublish = 0;
     constructor(now = Date.now) {
         this.now = now;
         this.state = { run: null, phase: { kind: 'idle', since: now() }, bash: [], dialogs: [] };
@@ -32,7 +33,7 @@ export class ActivityTracker {
     /** 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)
+        if (!s.run && s.phase.kind === 'idle' && !s.bash.length && !s.dialogs.length && !s.pauseRequested)
             return false;
         this.state = { run: null, phase: { kind: 'idle', since: this.now() }, bash: [], dialogs: [] };
         return true;
@@ -51,26 +52,52 @@ export class ActivityTracker {
                 const startedRun = !s.run;
                 if (startedRun)
                     s.run = { startedAt: this.now() };
+                if (startedRun)
+                    s.metrics = { turnStartedAt: this.now(), chars: 0, estimatedTokens: 0 };
                 return this.setPhase({ kind: 'waiting_llm' }) || startedRun;
             }
             case 'turn_start':
-                return this.setPhase({ kind: 'waiting_llm' });
+                s.metrics = { turnStartedAt: this.now(), chars: 0, estimatedTokens: 0 };
+                this.lastMetricsPublish = 0;
+                this.setPhase({ kind: 'waiting_llm' });
+                // Even when the last tool already moved us to waiting_llm, clients need the cleared metrics.
+                return true;
             case 'message_update': {
                 const update = e.assistantMessageEvent, type = str(update?.type);
+                const at = this.now();
+                const firstResponse = !!s.metrics &&
+                    s.metrics.firstResponseAt === undefined &&
+                    (type === 'thinking_delta' || type === 'text_delta' || type === 'toolcall_delta');
+                if (firstResponse)
+                    s.metrics.firstResponseAt = at;
+                let changed, lateName = false;
                 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') {
+                    changed = this.setPhase({ kind: 'thinking' });
+                else if (type === 'text_start' || type === 'text_delta')
+                    changed = this.setPhase({ kind: 'generating' });
+                else 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;
+                        changed = lateName = true;
                     }
-                    return this.setPhase({ kind: 'preparing_tool', ...(toolName ? { toolName } : {}) });
+                    else
+                        changed = this.setPhase({ kind: 'preparing_tool', ...(toolName ? { toolName } : {}) });
                 }
-                return false;
+                else
+                    return false;
+                // Throughput is per stream: each content block, e.g. each of two consecutive `write` calls,
+                // and each phase, so thinking does not dilute the text rate.
+                // A late tool name only labels the stream already running; it does not start a new one.
+                const cleared = ((changed && !lateName) || type.endsWith('_start')) && this.clearStream();
+                const counted = this.countDelta(update);
+                // Publish a stream's first count at once; later ones at most once a second.
+                if (counted && (counted === 'first' || at - this.lastMetricsPublish >= 1000)) {
+                    this.lastMetricsPublish = at;
+                    return true;
+                }
+                return changed || cleared || firstResponse;
             }
             case 'tool_execution_start': {
                 // Tools called by other tools run inside their caller's time; show only top-level calls.
@@ -143,6 +170,23 @@ export class ActivityTracker {
                 s.dialogs.push({ requestId, title: str(e.title) ?? str(e.message), since: this.now() });
                 return true;
             }
+            case 'safe_pause':
+                if (e.state === 'requested') {
+                    if (s.pauseRequested)
+                        return false;
+                    s.pauseRequested = { since: this.now() };
+                    return true;
+                }
+                if (e.state === 'reached') {
+                    if (s.pauseRequested?.reached)
+                        return false;
+                    s.pauseRequested = { since: s.pauseRequested?.since ?? this.now(), reached: true };
+                    return true;
+                }
+                if (!s.pauseRequested)
+                    return false;
+                delete s.pauseRequested;
+                return true;
             case 'extension_ui_response': {
                 const before = s.dialogs.length;
                 s.dialogs = s.dialogs.filter(d => d.requestId !== e.requestId);
@@ -152,9 +196,39 @@ export class ActivityTracker {
                 return false;
         }
     }
+    /** Adds a thinking, text or tool call delta to the current stream's estimate. Returns whether it counted. */
+    /** Restarts the current stream's counters. Returns whether there was anything to clear. */
+    clearStream() {
+        const metrics = this.state.metrics;
+        if (!metrics || (metrics.streamStartedAt === undefined && !metrics.chars))
+            return false;
+        delete metrics.streamStartedAt;
+        metrics.chars = 0;
+        metrics.estimatedTokens = 0;
+        return true;
+    }
+    /**
+     * Adds a thinking, text or tool call delta to the current stream's estimate. Returns `'first'` for
+     * the stream's first counted delta, `true` for later ones and `false` if nothing was counted.
+     */
+    countDelta(update) {
+        const metrics = this.state.metrics, delta = update?.delta;
+        if (!metrics || !String(update?.type).endsWith('_delta') || typeof delta !== 'string' || !delta)
+            return false;
+        const first = metrics.streamStartedAt === undefined;
+        if (first)
+            metrics.streamStartedAt = this.now();
+        // Approximate Latin/code text at 4 chars/token, CJK at 1.5 chars/token.
+        const cjk = delta.match(/[\u3400-\u9fff\u3040-\u30ff\uac00-\ud7af]/gu)?.length ?? 0;
+        const chars = [...delta].length;
+        metrics.chars += chars;
+        metrics.estimatedTokens += (chars - cjk) / 4 + cjk / 1.5;
+        return first ? 'first' : true;
+    }
     endRun(settled = false) {
         const hadRun = !!this.state.run;
         this.state.run = null;
+        delete this.state.metrics;
         // Compaction may continue after the run has ended; agent_settled closes it.
         if (this.state.phase.kind === 'compacting' && !settled)
             return hadRun;

package/dist/agents.js

@@ -5,6 +5,7 @@ import { createSdkBackend } from './sdk-backend.js';
 import { ActivityTracker } from './activity.js';
 import { AgentFeed } from './agent-feed.js';
 import { buildTimeline, itemBody, pageTimeline } from './timeline.js';
+import { sessionPerformance } from './session-performance.js';
 /**
  * Reduce a Pi SDK event to the fields server-side consumers and clients use, or drop it.
  * Heavy SDK events are whitelisted field by field (Pi attaches whole messages to many of
@@ -56,6 +57,7 @@ export class MockBackend {
     entries = [];
     timer;
     queue = { steering: [], followUp: [] };
+    pauseRequested = false;
     constructor(agentId, cwd, sessionId = randomUUID(), options = {}) {
         this.options = options;
         this.state = { agentId, sessionId, cwd, status: 'idle' };
@@ -81,11 +83,12 @@ export class MockBackend {
             this.timer = setTimeout(r, 0);
         });
     }
-    async prompt(message) {
+    async prompt(message, onAccepted) {
         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 });
+        onAccepted?.();
         await this.runTurn();
         const user = { role: 'user', content: message };
         this.emit({ type: 'message_end', message: user });
@@ -97,6 +100,25 @@ export class MockBackend {
         this.append(assistant);
         this.state.status = 'idle';
         this.emit({ type: 'agent_end' });
+        // A mock run is a single final answer, so a pending pause never finds a safe point.
+        if (this.pauseRequested) {
+            this.pauseRequested = false;
+            this.emit({ type: 'safe_pause', state: 'finished' });
+        }
+    }
+    async requestPause() {
+        if (this.state.status !== 'streaming')
+            throw Object.assign(new Error('Agent is not running'), { code: 'AGENT_NOT_RUNNING' });
+        if (this.pauseRequested)
+            return;
+        this.pauseRequested = true;
+        this.emit({ type: 'safe_pause', state: 'requested' });
+    }
+    async cancelPause() {
+        if (!this.pauseRequested)
+            return;
+        this.pauseRequested = false;
+        this.emit({ type: 'safe_pause', state: 'cancelled' });
     }
     async steer(message) {
         const queued = this.state.status === 'streaming';
@@ -125,6 +147,17 @@ export class MockBackend {
         this.emitQueue();
         return cleared;
     }
+    async moveQueue(from, index, expected) {
+        if (this.state.status !== 'streaming' || this.queue[from][index] !== expected)
+            throw Object.assign(new Error('Queued message has changed or already been consumed'), {
+                code: 'QUEUE_CHANGED'
+            });
+        const to = from === 'steering' ? 'followUp' : 'steering';
+        this.queue[from].splice(index, 1);
+        this.queue[to].push(expected);
+        this.emitQueue();
+        return this.getQueue();
+    }
     emitQueue() {
         this.emit({ type: 'queue_update', steering: [...this.queue.steering], followUp: [...this.queue.followUp] });
     }
@@ -134,6 +167,10 @@ export class MockBackend {
                 clearTimeout(this.timer);
             this.state.status = 'idle';
             this.emit({ type: 'agent_end', aborted: true });
+            if (this.pauseRequested) {
+                this.pauseRequested = false;
+                this.emit({ type: 'safe_pause', state: 'finished' });
+            }
         }
     }
     async getState() {
@@ -340,6 +377,7 @@ export class AgentManager {
         const entry = {
             record,
             backend,
+            writes: 0,
             activity: new ActivityTracker(),
             dialogRequests: new Map(),
             queue: emptyQueue()
@@ -369,6 +407,7 @@ export class AgentManager {
                 };
                 this.agents.set(saved.agentId, {
                     record,
+                    writes: 0,
                     activity: new ActivityTracker(),
                     dialogRequests: new Map(),
                     queue: emptyQueue()
@@ -391,8 +430,31 @@ export class AgentManager {
     isLoaded(id) {
         return !!this.get(id).backend;
     }
+    assertCurrent(entry, backend) {
+        if (entry.unloading ||
+            this.agents.get(entry.record.agentId) !== entry ||
+            (backend && entry.backend !== backend))
+            throw Object.assign(new Error('Agent session changed; retry the command'), { code: 'SESSION_BUSY' });
+    }
+    /** All session mutations share admission. Replacement is exclusive; ordinary writes remain concurrent. */
+    async writeSession(id, action) {
+        const entry = this.get(id);
+        this.assertCurrent(entry);
+        if (entry.templateChanging)
+            throw Object.assign(new Error('System Prompt is being changed'), { code: 'SESSION_BUSY' });
+        entry.writes++;
+        try {
+            const backend = await this.ensureLoaded(id);
+            this.assertCurrent(entry, backend);
+            return await action(backend, entry);
+        }
+        finally {
+            entry.writes--;
+        }
+    }
     async ensureLoaded(id) {
         const entry = this.get(id);
+        this.assertCurrent(entry);
         if (entry.backend)
             return entry.backend;
         if (entry.record.status === 'stopped')
@@ -403,7 +465,15 @@ export class AgentManager {
         entry.loading = (async () => {
             try {
                 const backend = await this.factory(id, entry.record.cwd, entry.record.sessionFile, entry.record.profile, entry.record.template ? { template: entry.record.template } : {});
-                const state = await backend.getState();
+                let state;
+                try {
+                    state = await backend.getState();
+                    this.assertCurrent(entry);
+                }
+                catch (error) {
+                    await backend.dispose();
+                    throw error;
+                }
                 entry.record = {
                     ...entry.record,
                     ...state,
@@ -416,7 +486,8 @@ export class AgentManager {
                 return backend;
             }
             catch (error) {
-                entry.record.status = 'error';
+                if (!entry.unloading)
+                    entry.record.status = 'error';
                 throw error;
             }
             finally {
@@ -425,19 +496,55 @@ export class AgentManager {
         })();
         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);
+    /** Transport acknowledgement: an accepted prompt keeps running under the normal write admission. */
+    submitCommand(id, kind, message = '') {
+        return new Promise((resolve, reject) => {
+            let accepted = false;
+            void this.command(id, kind, message, () => {
+                accepted = true;
+                resolve();
+            }).then(resolve, error => {
+                if (!accepted)
+                    return reject(error);
+                // The sender already has its acknowledgement. Report execution errors through the existing
+                // event stream rather than turning a delivered prompt into a failed send.
+                const entry = this.agents.get(id);
+                if (entry)
+                    this.publish(entry, {
+                        type: 'extension_ui_notify',
+                        notificationType: 'error',
+                        message: error instanceof Error ? error.message : String(error)
+                    });
+            });
+        });
+    }
+    async command(id, kind, message = '', onAccepted) {
         if (kind === 'abort') {
+            const entry = this.get(id);
+            if (!entry.backend)
+                return;
             if (entry.activity.stopping())
                 this.publishActivity(entry);
-            return backend.abort();
+            return entry.backend.abort();
         }
-        return backend[kind === 'follow-up' ? 'followUp' : kind](message);
+        return this.writeSession(id, async (backend, entry) => {
+            const state = await backend.getState();
+            this.assertCurrent(entry, backend);
+            // Read and reserve without yielding: simultaneous idle inputs start exactly one turn.
+            const busy = entry.promptPending || entry.streaming || state.status === 'streaming';
+            const effective = busy ? (kind === 'prompt' ? 'follow-up' : kind) : 'prompt';
+            if (effective === 'prompt')
+                entry.promptPending = true;
+            try {
+                return effective === 'prompt'
+                    ? await backend.prompt(message, onAccepted)
+                    : await backend[effective === 'follow-up' ? 'followUp' : 'steer'](message);
+            }
+            finally {
+                if (effective === 'prompt' && entry.backend === backend)
+                    entry.promptPending = false;
+            }
+        });
     }
     /** Queued steering and follow-up messages waiting for the running turn. */
     // Both read through to the backend and leave the cache to `queue_update`, which stays correct when a
@@ -451,7 +558,10 @@ export class AgentManager {
     /** Drop queued messages and return them so the caller can restore them to its composer. */
     async clearQueue(id) {
         const entry = this.get(id);
-        return entry.backend ? entry.backend.clearQueue() : emptyQueue();
+        return entry.backend ? this.writeSession(id, backend => backend.clearQueue()) : emptyQueue();
+    }
+    async moveQueue(id, from, index, expected) {
+        return this.writeSession(id, backend => backend.moveQueue(from, index, expected));
     }
     snapshotState(id) {
         const a = this.get(id);
@@ -490,20 +600,36 @@ export class AgentManager {
         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.feed?.close();
-        a.feed = undefined;
-        a.record.status = 'unloaded';
-        a.streaming = false;
-        a.dialogRequests.clear();
-        a.activity.reset(); // agent_unloaded below tells clients the activity is gone.
-        a.queue = emptyQueue();
-        this.publish(a, { type: 'agent_unloaded' });
+    dispose(id) {
+        const entry = this.get(id);
+        if (entry.unloading)
+            return entry.unloading;
+        // Reserve Stop synchronously. In-flight loads/replacements must validate before attaching.
+        entry.unloading = Promise.resolve()
+            .then(async () => {
+            if (entry.loading)
+                await entry.loading.catch(() => { });
+            const backend = entry.backend;
+            entry.backend = undefined;
+            entry.feed?.close();
+            entry.feed = undefined;
+            try {
+                await backend?.dispose();
+            }
+            finally {
+                entry.record.status = 'unloaded';
+                entry.streaming = false;
+                entry.promptPending = false;
+                entry.dialogRequests.clear();
+                entry.activity.reset();
+                entry.queue = emptyQueue();
+                this.publish(entry, { type: 'agent_unloaded' });
+            }
+        })
+            .finally(() => {
+            entry.unloading = undefined;
+        });
+        return entry.unloading;
     }
     async remove(id) {
         await this.dispose(id);
@@ -530,6 +656,11 @@ export class AgentManager {
             throw Object.assign(new Error('Timeline item not found'), { code: 'TIMELINE_ITEM_NOT_FOUND' });
         return { sessionId: source.sessionId, ...page };
     }
+    /** All timing records of the current branch; older sessions only have partial tool timings. */
+    async performance(id) {
+        const source = (await this.ensureLoaded(id)).timeline();
+        return { sessionId: source.sessionId, ...sessionPerformance(source.entries()) };
+    }
     /** The full body of one timeline item of the given session. It never changes. */
     async item(id, sessionId, itemId) {
         const source = (await this.ensureLoaded(id)).timeline(), body = source.sessionId === sessionId ? itemBody(buildTimeline(source.entries()), itemId) : undefined;
@@ -541,6 +672,57 @@ export class AgentManager {
         const info = await (await this.ensureLoaded(id)).getSystemPrompt();
         return { ...info, template: this.get(id).record.template ?? null };
     }
+    /** Prepare → persist → activate under the template lock. A failed save leaves the old session intact. */
+    async setTemplate(id, template, persist) {
+        const entry = this.get(id);
+        this.assertCurrent(entry);
+        if (entry.record.profile !== 'default' ||
+            entry.record.status === 'stopped' ||
+            entry.streaming ||
+            entry.writes)
+            throw Object.assign(new Error('System Prompt can only change before the first turn'), {
+                code: 'SESSION_STARTED'
+            });
+        if (entry.templateChanging)
+            throw Object.assign(new Error('System Prompt is being changed'), { code: 'SESSION_BUSY' });
+        entry.templateChanging = true;
+        try {
+            const old = await this.ensureLoaded(id);
+            this.assertCurrent(entry, old);
+            const session = await old.getSession();
+            if (session.entries.some(x => x.type === 'message'))
+                throw Object.assign(new Error('This session already has messages'), { code: 'SESSION_STARTED' });
+            const capabilities = await old.getCapabilities();
+            this.assertCurrent(entry, old);
+            const replacement = await this.factory(id, entry.record.cwd, entry.record.sessionFile, entry.record.profile, template ? { template } : {});
+            try {
+                const model = capabilities.model;
+                if (model?.provider && model?.id)
+                    await replacement.setModel(model.provider, model.id);
+                if (typeof capabilities.thinkingLevel === 'string')
+                    await replacement.setThinkingLevel(capabilities.thinkingLevel);
+                if (entry.record.sessionName)
+                    await replacement.setSessionName(entry.record.sessionName);
+                const state = await replacement.getState();
+                this.assertCurrent(entry, old);
+                const record = { ...entry.record, ...state, template };
+                // Persistence is synchronous: no command can observe a choice that has not been committed.
+                persist(record);
+                entry.record = record;
+                this.connect(entry, replacement);
+                this.publish(entry, { type: 'agent_loaded' });
+                await old.dispose().catch(() => { });
+                return record;
+            }
+            catch (error) {
+                await replacement.dispose();
+                throw error;
+            }
+        }
+        finally {
+            entry.templateChanging = false;
+        }
+    }
     async capabilities(id) {
         return (await this.ensureLoaded(id)).getCapabilities();
     }
@@ -557,40 +739,59 @@ export class AgentManager {
         return { ...info, sessionName: name };
     }
     async compact(id, instructions) {
-        return (await this.ensureLoaded(id)).compact(instructions);
+        return this.writeSession(id, backend => backend.compact(instructions));
     }
     async setModel(id, provider, modelId) {
-        return (await this.ensureLoaded(id)).setModel(provider, modelId);
+        return this.writeSession(id, backend => backend.setModel(provider, modelId));
     }
     async setThinkingLevel(id, level) {
-        return (await this.ensureLoaded(id)).setThinkingLevel(level);
+        return this.writeSession(id, backend => backend.setThinkingLevel(level));
     }
     async setSessionName(id, name) {
-        await (await this.ensureLoaded(id)).setSessionName(name);
-        this.get(id).record.sessionName = name.trim();
+        return this.writeSession(id, async (backend, entry) => {
+            await backend.setSessionName(name);
+            this.assertCurrent(entry, backend);
+            entry.record.sessionName = name.trim();
+        });
     }
     async navigate(id, entryId) {
-        const result = await (await this.ensureLoaded(id)).navigate(entryId);
-        this.get(id).feed?.sync(); // Moving the leaf back is no event; tell viewers to reload.
-        return result;
+        return this.writeSession(id, async (backend, entry) => {
+            const result = await backend.navigate(entryId);
+            this.assertCurrent(entry, backend);
+            entry.feed?.sync(); // Moving the leaf back is no event; tell viewers to reload.
+            return result;
+        });
     }
     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, source.record.profile, source.record.template);
-        return { agent, selectedText: result.selectedText };
+        return this.writeSession(id, async (backend, source) => {
+            const result = await backend.fork(entryId);
+            this.assertCurrent(source, backend);
+            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, source.record.profile, source.record.template);
+            return { agent, selectedText: result.selectedText };
+        });
     }
     async extensionResponse(id, requestId, value) {
-        return (await this.ensureLoaded(id)).extensionResponse(requestId, value);
+        return this.writeSession(id, backend => backend.extensionResponse(requestId, value));
     }
     async listCommands(id) {
         return (await this.ensureLoaded(id)).listCommands();
     }
     /** Session-scoped bash. Output is streamed as `bash_execution_update` events and recorded in the Session. */
     async runBash(id, command, excludeFromContext = false) {
-        return (await this.ensureLoaded(id)).runBash(command, excludeFromContext);
+        return this.writeSession(id, backend => backend.runBash(command, excludeFromContext));
+    }
+    /** Stop the running turn at its next safe point: after its tools, before the next model request. */
+    async requestPause(id) {
+        const entry = this.get(id);
+        if (!entry.backend)
+            throw Object.assign(new Error('Agent is not running'), { code: 'AGENT_NOT_RUNNING' });
+        return entry.backend.requestPause();
+    }
+    async cancelPause(id) {
+        return this.get(id).backend?.cancelPause();
     }
     async abortBash(id) {
         const entry = this.get(id);