pi2web 0.2.1 → 0.2.8

package/dist/agents.js

@@ -2,79 +2,307 @@ import { EventEmitter } from 'node:events';
 import { randomUUID } from 'node:crypto';
 import { relative as pathRelative } from 'node:path';
 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
+ * them) so new SDK fields never leak into memory or onto the wire; pi2web's own events pass through.
+ */
+export function slimEvent(event) {
+    const e = event;
+    switch (event.type) {
+        // Streamed text and running tool output reach viewing clients through AgentFeed, not as events.
+        case 'message_update':
+        case 'tool_execution_update':
+            return undefined;
+        case 'message_start':
+            return { type: 'message_start', role: e.message?.role ?? e.role };
+        case 'turn_start':
+        case 'turn_end':
+            return { type: event.type };
+        case 'message_end':
+            return { type: 'message_end', message: e.message };
+        case 'agent_end':
+            return { type: 'agent_end', willRetry: e.willRetry, aborted: e.aborted };
+        case 'tool_execution_start':
+            return {
+                type: event.type,
+                toolCallId: e.toolCallId,
+                toolName: e.toolName,
+                args: e.args,
+                parentToolCallId: e.parentToolCallId
+            };
+        case 'tool_execution_end':
+            return {
+                type: event.type,
+                toolCallId: e.toolCallId,
+                toolName: e.toolName,
+                parentToolCallId: e.parentToolCallId,
+                result: e.result,
+                isError: e.isError,
+                durationMs: e.durationMs
+            };
+        default:
+            return event;
+    }
+}
 /** Deterministic backend used by the server and tests. The SDK adapter can implement the same contract. */
 export class MockBackend {
+    options;
     emitter = new EventEmitter();
     state;
-    messages = [];
+    entries = [];
     timer;
     queue = { steering: [], followUp: [] };
-    constructor(agentId, cwd, sessionId = randomUUID()) { this.state = { agentId, sessionId, cwd, status: 'idle' }; }
-    emit(e) { this.emitter.emit('event', e); }
+    constructor(agentId, cwd, sessionId = randomUUID(), options = {}) {
+        this.options = options;
+        this.state = { agentId, sessionId, cwd, status: 'idle' };
+    }
+    emit(e) {
+        this.emitter.emit('event', e);
+    }
+    /** Persist like Pi: append a session entry after listeners have seen the message. */
+    append(message) {
+        const id = randomUUID().slice(0, 8);
+        this.entries.push({
+            type: 'message',
+            id,
+            parentId: this.entries.at(-1)?.id ?? null,
+            timestamp: new Date().toISOString(),
+            message: { timestamp: Date.now(), ...message }
+        });
+        return id;
+    }
     /** The body of a turn. Tests override it to keep a run streaming while they inspect queued input. */
-    runTurn() { return new Promise(r => { this.timer = setTimeout(r, 0); }); }
-    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 this.runTurn(); 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) { const queued = this.state.status === 'streaming'; if (queued)
-        this.queue.steering.push(message); this.emit({ type: 'steer', message }); if (queued)
-        this.emitQueue(); return queued ? 'queued' : 'handled'; }
-    async followUp(message) { const queued = this.state.status === 'streaming'; if (queued)
-        this.queue.followUp.push(message); this.emit({ type: 'follow_up', message }); if (queued)
-        this.emitQueue(); return queued ? 'queued' : 'handled'; }
-    async getQueue() { return { steering: [...this.queue.steering], followUp: [...this.queue.followUp] }; }
-    async clearQueue() { const cleared = await this.getQueue(); this.queue = { steering: [], followUp: [] }; this.emitQueue(); return cleared; }
-    emitQueue() { this.emit({ type: 'queue_update', steering: [...this.queue.steering], followUp: [...this.queue.followUp] }); }
-    async abort() { if (this.state.status === 'streaming') {
-        if (this.timer)
-            clearTimeout(this.timer);
+    runTurn() {
+        return new Promise(r => {
+            this.timer = setTimeout(r, 0);
+        });
+    }
+    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 this.runTurn();
+        const user = { role: 'user', content: message };
+        this.emit({ type: 'message_end', message: user });
+        this.append(user);
+        const text = `Mock response: ${message}`, assistant = { role: 'assistant', content: [{ type: 'text', text }] };
+        this.emit({ type: 'message_start', message: { role: 'assistant', content: [] } });
+        this.emit({ type: 'message_update', assistantMessageEvent: { type: 'text_delta', delta: text } });
+        this.emit({ type: 'message_end', message: assistant });
+        this.append(assistant);
         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' }; }
+        this.emit({ type: 'agent_end' });
+    }
+    async steer(message) {
+        const queued = this.state.status === 'streaming';
+        if (queued)
+            this.queue.steering.push(message);
+        this.emit({ type: 'steer', message });
+        if (queued)
+            this.emitQueue();
+        return queued ? 'queued' : 'handled';
+    }
+    async followUp(message) {
+        const queued = this.state.status === 'streaming';
+        if (queued)
+            this.queue.followUp.push(message);
+        this.emit({ type: 'follow_up', message });
+        if (queued)
+            this.emitQueue();
+        return queued ? 'queued' : 'handled';
+    }
+    async getQueue() {
+        return { steering: [...this.queue.steering], followUp: [...this.queue.followUp] };
+    }
+    async clearQueue() {
+        const cleared = await this.getQueue();
+        this.queue = { steering: [], followUp: [] };
+        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] });
+    }
+    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 };
+    }
+    timeline() {
+        return {
+            sessionId: this.state.sessionId,
+            leafId: this.entries.at(-1)?.id ?? null,
+            entries: () => [...this.entries]
+        };
+    }
+    async getSystemPrompt() {
+        const template = this.options.piDefaultPrompt ? undefined : this.options.template;
+        const base = template?.mode === 'replace' ? template.systemPrompt : 'Mock Pi system prompt';
+        return {
+            systemPrompt: [base, template?.mode === 'append' ? template.systemPrompt : '', `cwd: ${this.state.cwd}`]
+                .filter(Boolean)
+                .join('\n\n'),
+            appendFiles: [],
+            contextFiles: []
+        };
+    }
+    async getCapabilities() {
+        return { model: null, models: [], thinkingLevel: 'off', thinkingLevels: ['off'], supportsThinking: false };
+    }
+    async getSession() {
+        return { ...(await this.getSessionInfo()), entries: [...this.entries], tree: [] };
+    }
+    async getSessionInfo() {
+        return {
+            sessionId: this.state.sessionId,
+            sessionName: this.state.sessionName,
+            stats: { totalMessages: this.entries.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 setSessionName(name) {
+        this.state.sessionName = name;
+        this.emit({ type: 'session_info_changed', name });
+    }
+    /** Move the leaf back to an earlier entry, like rewinding a Pi session. */
+    async navigate(entryId) {
+        const index = this.entries.findIndex(entry => entry.id === entryId);
+        if (index >= 0)
+            this.entries = this.entries.slice(0, index + 1);
+        return { cancelled: false };
+    }
+    async fork(_entryId) {
+        return {};
+    }
     async extensionResponse(_requestId, _value) { }
-    async listCommands() { return [{ name: 'mock', description: 'Mock prompt template', source: 'prompt' }]; }
-    async runBash(command, excludeFromContext = false) { const id = randomUUID(), output = `Mock bash: ${command}`; this.emit({ type: 'bash_execution_start', id, command }); this.emit({ type: 'bash_execution_update', id, delta: `${output}\n` }); const result = { id, output, exitCode: 0, cancelled: false, truncated: false }; this.messages.push({ role: 'bashExecution', command, output, exitCode: 0, cancelled: false, truncated: false, timestamp: Date.now(), excludeFromContext }); this.emit({ type: 'bash_execution_end', command, ...result }); return result; }
+    async listCommands() {
+        return [{ name: 'mock', description: 'Mock prompt template', source: 'prompt' }];
+    }
+    async runBash(command, excludeFromContext = false) {
+        const id = randomUUID(), output = `Mock bash: ${command}`;
+        this.emit({ type: 'bash_execution_start', id, command });
+        this.emit({ type: 'bash_execution_update', id, delta: `${output}\n` });
+        const result = { id, output, exitCode: 0, cancelled: false, truncated: false };
+        this.append({
+            role: 'bashExecution',
+            command,
+            output,
+            exitCode: 0,
+            cancelled: false,
+            truncated: false,
+            excludeFromContext
+        });
+        this.emit({ type: 'bash_execution_end', command, ...result });
+        return result;
+    }
     abortBash() { }
-    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(); }
+    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();
+    }
 }
 const toStringList = (value) => Array.isArray(value) ? value.filter((x) => typeof x === 'string') : [];
 const emptyQueue = () => ({ steering: [], followUp: [] });
+const LIFECYCLE_ONLY = new Set(['agent_loaded', 'agent_unloaded']);
 /** A pending dialog blocks the run until a human answers it, which is a different wait than streaming. */
 const runStatus = (entry, streaming) => entry.dialogRequests.size ? 'waiting_for_user' : streaming ? 'streaming' : 'idle';
 export class AgentManager {
     workspaces;
     factory;
     agents = new Map();
-    listeners = new Map();
+    detailListeners = new Map();
     globalListeners = new Set();
-    constructor(workspaces, factory = createSdkBackend) {
+    constructor(workspaces, factory = (id, cwd, sessionFile, profile, options) => createSdkBackend(id, cwd, sessionFile, profile, undefined, options)) {
         this.workspaces = workspaces;
         this.factory = factory;
     }
-    async resolveCwd(workspaceId, relativeCwd = '.') { 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'); return cwd; }
-    async create(workspaceId, relativeCwd = '.', sessionFile, profile = 'default') { const cwd = await this.resolveCwd(workspaceId, relativeCwd); const id = `agent-${randomUUID()}`, backend = await this.factory(id, cwd, sessionFile, profile), now = new Date().toISOString(); const record = { ...(await backend.getState()), workspaceId, profile, createdAt: now, lastActiveAt: now }; this.attach(id, record, backend); return { ...record }; }
+    async resolveCwd(workspaceId, relativeCwd = '.') {
+        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');
+        return cwd;
+    }
+    async create(workspaceId, relativeCwd = '.', sessionFile, profile = 'default', template) {
+        const cwd = await this.resolveCwd(workspaceId, relativeCwd);
+        const id = `agent-${randomUUID()}`, backend = await this.factory(id, cwd, sessionFile, profile, template ? { template } : {}), now = new Date().toISOString();
+        const record = {
+            ...(await backend.getState()),
+            workspaceId,
+            profile,
+            ...(template ? { template: { ...template } } : {}),
+            createdAt: now,
+            lastActiveAt: now
+        };
+        this.attach(id, record, backend);
+        return { ...record };
+    }
     /** Build a disposable session so the UI sees the models actually available for this project and its extensions. */
-    async capabilityPreview(workspaceId, relativeCwd = '.') { const cwd = await this.resolveCwd(workspaceId, relativeCwd), backend = await this.factory(`preview-${randomUUID()}`, cwd); try {
-        return await backend.getCapabilities();
+    async capabilityPreview(workspaceId, relativeCwd = '.') {
+        const cwd = await this.resolveCwd(workspaceId, relativeCwd), backend = await this.factory(`preview-${randomUUID()}`, cwd);
+        try {
+            return await backend.getCapabilities();
+        }
+        finally {
+            await backend.dispose();
+        }
+    }
+    /**
+     * The system prompt an Agent created here would start with. `template` previews a template;
+     * `piDefaultPrompt` ignores SYSTEM.md / APPEND_SYSTEM.md to show Pi's built-in prompt.
+     */
+    async systemPromptPreview(workspaceId, relativeCwd = '.', options = {}) {
+        const cwd = await this.resolveCwd(workspaceId, relativeCwd), backend = await this.factory(`preview-${randomUUID()}`, cwd, undefined, 'default', options);
+        try {
+            return { ...(await backend.getSystemPrompt()), cwd };
+        }
+        finally {
+            await backend.dispose();
+        }
     }
-    finally {
-        await backend.dispose();
-    } }
     connect(entry, backend) {
         entry.backend = backend;
+        entry.feed?.close();
+        const agentId = entry.record.agentId, feed = new AgentFeed(() => backend.timeline(), message => {
+            for (const listener of this.detailListeners.get(agentId) ?? [])
+                listener(message);
+        });
+        entry.feed = feed;
         backend.subscribe(event => {
             if (entry.backend !== backend)
                 return;
@@ -87,14 +315,8 @@ export class AgentManager {
                 entry.streaming = false;
             if (type === 'queue_update')
                 entry.queue = { steering: toStringList(event.steering), followUp: toStringList(event.followUp) };
-            // Standalone shell runs and dialogs outlive LLM turns. Track them with the
-            // event cursor; keep dialog payloads so reconnecting clients can rebuild controls.
-            if (typeof event.id === 'string') {
-                if (type === 'bash_execution_start' || type === 'bash_execution_update')
-                    entry.bashIds.add(event.id);
-                else if (type === 'bash_execution_end')
-                    entry.bashIds.delete(event.id);
-            }
+            const activityChanged = entry.activity.apply(event);
+            // Keep dialog payloads so reconnecting clients can rebuild their controls.
             if (typeof event.requestId === 'string') {
                 if (type === 'extension_ui_request')
                     entry.dialogRequests.set(event.requestId, event);
@@ -103,122 +325,419 @@ export class AgentManager {
             }
             record.status = runStatus(entry, entry.streaming === true);
             if (type === 'session_info_changed')
-                record.sessionName = typeof event.name === 'string' && event.name.trim() ? event.name.trim() : undefined;
-            this.publish(entry, event);
+                record.sessionName =
+                    typeof event.name === 'string' && event.name.trim() ? event.name.trim() : undefined;
+            feed.handle(event);
+            const slim = slimEvent(event);
+            if (slim)
+                this.publish(entry, slim);
+            if (activityChanged)
+                this.publishActivity(entry);
         });
     }
+    publishActivity(entry) {
+        this.publish(entry, { type: 'activity_changed', activity: entry.activity.snapshot() });
+    }
+    /** Loading or unloading a backend is not activity: it must not reorder the Agent list. */
     publish(entry, event) {
         const record = entry.record;
-        record.lastActiveAt = new Date().toISOString();
+        if (!LIFECYCLE_ONLY.has(event.type))
+            record.lastActiveAt = new Date().toISOString();
         // Every event carries the authoritative status, so clients never have to derive it from event types.
-        const item = { id: randomUUID(), sequence: entry.nextSequence++, timestamp: Math.floor(Date.now() / 1000), status: record.status, event };
-        entry.events.push(item);
-        if (entry.events.length > 1000)
-            entry.events.shift();
-        for (const listener of this.listeners.get(record.agentId) ?? [])
-            listener(item);
+        const item = { timestamp: Date.now(), status: record.status, event };
         for (const listener of this.globalListeners)
             listener(record.agentId, item);
     }
-    attach(id, record, backend) { const entry = { record, backend, events: [], nextSequence: 1, bashIds: new Set(), dialogRequests: new Map(), queue: emptyQueue() }; this.connect(entry, backend); this.agents.set(id, entry); }
-    async restore(records) { for (const saved of records) {
+    attach(id, record, backend) {
+        const entry = {
+            record,
+            backend,
+            writes: 0,
+            activity: new ActivityTracker(),
+            dialogRequests: new Map(),
+            queue: emptyQueue()
+        };
+        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,
+                    profile: saved.profile ?? 'default',
+                    cwd,
+                    status: 'unloaded',
+                    lastActiveAt: sessionModified && sessionModified > saved.lastActiveAt ? sessionModified : saved.lastActiveAt
+                };
+                this.agents.set(saved.agentId, {
+                    record,
+                    writes: 0,
+                    activity: new ActivityTracker(),
+                    dialogRequests: new Map(),
+                    queue: emptyQueue()
+                });
+            }
+            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;
+    }
+    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 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, profile: saved.profile ?? 'default', cwd, status: 'unloaded', lastActiveAt: sessionModified && sessionModified > saved.lastActiveAt ? sessionModified : saved.lastActiveAt };
-            this.agents.set(saved.agentId, { record, events: [], nextSequence: 1, bashIds: new Set(), dialogRequests: new Map(), queue: emptyQueue() });
+            const backend = await this.ensureLoaded(id);
+            this.assertCurrent(entry, backend);
+            return await action(backend, entry);
         }
-        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, entry.record.profile);
-        const state = await backend.getState();
-        entry.record = { ...entry.record, ...state, sessionName: state.sessionName?.trim() || entry.record.sessionName, 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); }
+        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')
+            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, entry.record.profile, entry.record.template ? { template: entry.record.template } : {});
+                let state;
+                try {
+                    state = await backend.getState();
+                    this.assertCurrent(entry);
+                }
+                catch (error) {
+                    await backend.dispose();
+                    throw error;
+                }
+                entry.record = {
+                    ...entry.record,
+                    ...state,
+                    sessionName: state.sessionName?.trim() || entry.record.sessionName,
+                    status: state.status === 'stopped' ? 'idle' : state.status
+                };
+                this.connect(entry, backend);
+                // The status moved from unloaded to idle without a Pi event; tell clients.
+                this.publish(entry, { type: 'agent_loaded' });
+                return backend;
+            }
+            catch (error) {
+                if (!entry.unloading)
+                    entry.record.status = 'error';
+                throw error;
+            }
+            finally {
+                entry.loading = undefined;
+            }
+        })();
+        return entry.loading;
+    }
+    async command(id, kind, message = '') {
+        if (kind === 'abort') {
+            const entry = this.get(id);
+            if (!entry.backend)
+                return;
+            if (entry.activity.stopping())
+                this.publishActivity(entry);
+            return entry.backend.abort();
+        }
+        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 await backend[effective === 'follow-up' ? 'followUp' : effective](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
     // message is queued while these run.
-    async queue(id) { const entry = this.get(id); return entry.backend ? entry.backend.getQueue() : { steering: [...entry.queue.steering], followUp: [...entry.queue.followUp] }; }
+    async queue(id) {
+        const entry = this.get(id);
+        return entry.backend
+            ? entry.backend.getQueue()
+            : { steering: [...entry.queue.steering], followUp: [...entry.queue.followUp] };
+    }
     /** 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(); }
-    events(id, last = 0) { return this.get(id).events.filter(e => e.sequence > last); }
-    currentSequence(id) { return this.get(id).nextSequence - 1; }
+    async clearQueue(id) {
+        const entry = this.get(id);
+        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);
-        return { ...a.record, activity: { bashIds: [...a.bashIds], dialogIds: [...a.dialogRequests.keys()], dialogRequests: [...a.dialogRequests.values()], queue: { steering: [...a.queue.steering], followUp: [...a.queue.followUp] } } };
-    }
-    async snapshot(id, messageLimit) {
-        // Capture state and its cursor before yielding. Events emitted while messages
-        // are being read must be delivered after, not swallowed by, this snapshot.
-        const a = this.get(id), state = this.snapshotState(id), lastSequence = a.nextSequence - 1;
-        const messages = a.backend ? await a.backend.getMessages() : [];
-        if (messageLimit === undefined)
-            return { state, messages, lastSequence };
-        const page = this.paginateMessages(messages, messageLimit);
-        return { state, messages: page.items, messagePage: page, lastSequence };
-    }
-    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';
-        a.streaming = false;
-        a.bashIds.clear();
-        a.dialogRequests.clear();
-        a.queue = emptyQueue();
-        this.publish(a, { type: 'agent_unloaded' });
-    }
-    async remove(id) { await this.dispose(id); 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; }
+        return {
+            ...a.record,
+            activity: {
+                ...a.activity.snapshot(),
+                dialogRequests: [...a.dialogRequests.values()],
+                queue: { steering: [...a.queue.steering], followUp: [...a.queue.followUp] }
+            }
+        };
+    }
+    /**
+     * Start viewing an Agent in detail: load it, then subscribe and take a snapshot together, with
+     * nothing in between, so every message the listener gets is newer than the snapshot.
+     */
+    async focus(id, listener, limit) {
+        await this.ensureLoaded(id);
+        const entry = this.get(id);
+        // Snapshot first: it publishes pending changes, which it includes, before this listener exists.
+        const snapshot = {
+            ...entry.feed.snapshot(limit),
+            // Dialog controls live in the transcript, which a viewer replaces when it starts viewing.
+            dialogRequests: [...entry.dialogRequests.values()]
+        };
+        if (!this.detailListeners.has(id))
+            this.detailListeners.set(id, new Set());
+        this.detailListeners.get(id).add(listener);
+        return { unsubscribe: () => this.detailListeners.get(id)?.delete(listener), snapshot };
+    }
+    toolOutput(id, toolCallId) {
+        return this.get(id).feed?.output(toolCallId);
+    }
+    /** Events of every Agent: server-side consumers and the overview stream. */
+    subscribeAll(listener) {
+        this.globalListeners.add(listener);
+        return () => this.globalListeners.delete(listener);
+    }
+    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);
+        this.agents.delete(id);
+        this.detailListeners.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;
+    }
     // The record status, not the backend's, is authoritative: it also knows about pending dialogs.
-    async state(id) { const state = await (await this.ensureLoaded(id)).getState(), record = this.get(id).record; return { ...state, status: record.status, sessionName: state.sessionName?.trim() || record.sessionName }; }
-    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) { const info = await (await this.ensureLoaded(id)).getSession(), name = typeof info.sessionName === 'string' && info.sessionName.trim() ? info.sessionName : this.get(id).record.sessionName; return { ...info, sessionName: name }; }
-    async sessionInfo(id) { const info = await (await this.ensureLoaded(id)).getSessionInfo(), name = typeof info.sessionName === 'string' && info.sessionName.trim() ? info.sessionName : this.get(id).record.sessionName; return { ...info, sessionName: name }; }
-    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, source.record.profile); return { agent, selectedText: result.selectedText }; }
-    async extensionResponse(id, requestId, value) { return (await this.ensureLoaded(id)).extensionResponse(requestId, value); }
-    async listCommands(id) { return (await this.ensureLoaded(id)).listCommands(); }
+    async state(id) {
+        const state = await (await this.ensureLoaded(id)).getState(), record = this.get(id).record;
+        return { ...state, status: record.status, sessionName: state.sessionName?.trim() || record.sessionName };
+    }
+    /** Older history: the page before item `before` (or the newest one). Live viewers get it from focus(). */
+    async timeline(id, limit, before) {
+        const source = (await this.ensureLoaded(id)).timeline(), page = pageTimeline(buildTimeline(source.entries()), limit, before);
+        if (!page)
+            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;
+        if (body === undefined)
+            throw Object.assign(new Error('Timeline item not found'), { code: 'TIMELINE_ITEM_NOT_FOUND' });
+        return { id: itemId, body };
+    }
+    async systemPrompt(id) {
+        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();
+    }
+    async session(id) {
+        const info = await (await this.ensureLoaded(id)).getSession(), name = typeof info.sessionName === 'string' && info.sessionName.trim()
+            ? info.sessionName
+            : this.get(id).record.sessionName;
+        return { ...info, sessionName: name };
+    }
+    async sessionInfo(id) {
+        const info = await (await this.ensureLoaded(id)).getSessionInfo(), name = typeof info.sessionName === 'string' && info.sessionName.trim()
+            ? info.sessionName
+            : this.get(id).record.sessionName;
+        return { ...info, sessionName: name };
+    }
+    async compact(id, instructions) {
+        return this.writeSession(id, backend => backend.compact(instructions));
+    }
+    async setModel(id, provider, modelId) {
+        return this.writeSession(id, backend => backend.setModel(provider, modelId));
+    }
+    async setThinkingLevel(id, level) {
+        return this.writeSession(id, backend => backend.setThinkingLevel(level));
+    }
+    async setSessionName(id, name) {
+        return this.writeSession(id, async (backend, entry) => {
+            await backend.setSessionName(name);
+            this.assertCurrent(entry, backend);
+            entry.record.sessionName = name.trim();
+        });
+    }
+    async navigate(id, entryId) {
+        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) {
+        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 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); }
-    async abortBash(id) { const entry = this.get(id); if (entry.loading)
-        await entry.loading; entry.backend?.abortBash(); }
+    async runBash(id, command, excludeFromContext = false) {
+        return this.writeSession(id, backend => backend.runBash(command, excludeFromContext));
+    }
+    async abortBash(id) {
+        const entry = this.get(id);
+        if (entry.loading)
+            await entry.loading;
+        entry.backend?.abortBash();
+    }
 }