shennian 0.2.6 → 0.2.8

package/dist/src/agents/pi.js

@@ -0,0 +1,793 @@
+// @arch docs/architecture/cli/agent-adapters.md#pi-agent-上下文管理
+// @test src/__tests__/pi-context.test.ts
+import { randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { Agent, streamProxy } from '@mariozechner/pi-agent-core';
+import { Type } from '@sinclair/typebox';
+import { AgentAdapter, registerAgent } from './adapter.js';
+import { loadConfig, resolveShennianPath } from '../config/index.js';
+import { SERVERS } from '../region.js';
+const execFileAsync = promisify(execFile);
+const PI_DEFAULT_MODEL_ID = 'qwen3.6-plus';
+function createPiModel(modelId = PI_DEFAULT_MODEL_ID) {
+    return {
+        id: modelId,
+        name: modelId,
+        api: 'openai-completions',
+        provider: 'shennian-proxy',
+        baseUrl: '',
+        reasoning: false,
+        input: ['text', 'image'],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 8192,
+    };
+}
+const SYSTEM_PROMPT = `你是神念内置编程助手，运行在用户本地机器上。
+你可以读写文件、执行 shell 命令、帮助用户完成编程和系统管理任务。
+工作目录已设置，操作文件时使用相对路径或绝对路径均可。
+保持回复简洁、准确，中文回复。`;
+// ── Context compression ──────────────────────────────────────────────────────
+const CONTEXT_TOKEN_THRESHOLD = 90_000;
+const KEEP_RECENT_MESSAGES = 6;
+const SESSIONS_DIR = resolveShennianPath('sessions');
+const SUMMARY_FILENAME = 'summary.json';
+const SNAPSHOT_FILENAME = 'snapshot.json';
+const MESSAGES_FILENAME = 'messages.jsonl';
+const LEGACY_SUMMARY_FILENAME = 'pi-context.json';
+function estimateTokens(messages) {
+    let chars = 0;
+    for (const msg of messages)
+        chars += JSON.stringify(msg).length;
+    return Math.ceil(chars / 3);
+}
+function messagesToText(messages) {
+    const lines = [];
+    for (const msg of messages) {
+        const m = msg;
+        const role = String(m.role ?? 'unknown');
+        if (!Array.isArray(m.content))
+            continue;
+        for (const c of m.content) {
+            if (c.type === 'text' && typeof c.text === 'string') {
+                lines.push(`[${role}] ${c.text.slice(0, 500)}`);
+            }
+            else if (c.type === 'toolCall') {
+                const name = typeof c.name === 'string' ? c.name : typeof c.toolName === 'string' ? c.toolName : 'tool';
+                const args = c.arguments ?? c.args ?? {};
+                lines.push(`[${role}] tool:${name}(${JSON.stringify(args).slice(0, 200)})`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+function cloneMessages(messages) {
+    return JSON.parse(JSON.stringify(messages));
+}
+function getSessionDir(sessionId) {
+    return path.join(SESSIONS_DIR, sessionId);
+}
+function getMessageContentText(content) {
+    if (!content || typeof content !== 'object')
+        return null;
+    const chunk = content;
+    if (chunk.type === 'text' && typeof chunk.text === 'string')
+        return chunk.text;
+    if (chunk.type === 'thinking' && typeof chunk.thinking === 'string')
+        return `[thinking] ${chunk.thinking}`;
+    if (chunk.type === 'toolCall') {
+        const name = typeof chunk.name === 'string'
+            ? chunk.name
+            : typeof chunk.toolName === 'string'
+                ? chunk.toolName
+                : 'tool';
+        const args = chunk.arguments ?? chunk.args ?? {};
+        return `[toolCall] ${name}(${JSON.stringify(args).slice(0, 300)})`;
+    }
+    if (chunk.type === 'image' && typeof chunk.mimeType === 'string') {
+        return `[image] ${chunk.mimeType}`;
+    }
+    return null;
+}
+function buildRollingSummary(cachedSummary, messages) {
+    const recentLines = [];
+    for (const msg of messages) {
+        const role = String(msg.role ?? 'unknown');
+        const content = Array.isArray(msg.content)
+            ? msg.content
+            : [];
+        for (const chunk of content) {
+            const text = getMessageContentText(chunk);
+            if (text)
+                recentLines.push(`[${role}] ${text}`);
+        }
+    }
+    const recent = recentLines.slice(-8).join('\n').trim();
+    const summary = recent || cachedSummary?.trim() || null;
+    if (!summary)
+        return null;
+    return summary.length > 2000 ? summary.slice(summary.length - 2000) : summary;
+}
+function longestCommonPrefixLength(left, right) {
+    const max = Math.min(left.length, right.length);
+    for (let i = 0; i < max; i++) {
+        if (JSON.stringify(left[i]) !== JSON.stringify(right[i]))
+            return i;
+    }
+    return max;
+}
+async function requestProxySummary(proxyUrl, authToken, prompt) {
+    const response = await fetch(`${proxyUrl}/api/stream`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${authToken}`,
+        },
+        body: JSON.stringify({
+            model: createPiModel('qwen-plus'),
+            context: {
+                messages: [
+                    {
+                        role: 'user',
+                        content: [{ type: 'text', text: prompt }],
+                    },
+                ],
+            },
+            options: {
+                temperature: 0.3,
+                maxTokens: 500,
+            },
+        }),
+    });
+    if (!response.ok || !response.body)
+        return null;
+    const reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    const parts = [];
+    let buffer = '';
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        buffer += decoder.decode(value, { stream: true });
+        const lines = buffer.split('\n');
+        buffer = lines.pop() ?? '';
+        for (const line of lines) {
+            if (!line.startsWith('data: '))
+                continue;
+            const raw = line.slice(6).trim();
+            if (!raw)
+                continue;
+            const event = JSON.parse(raw);
+            if (event.type === 'text_delta' && typeof event.delta === 'string') {
+                parts.push(event.delta);
+            }
+        }
+    }
+    return parts.join('').trim() || null;
+}
+// ── Local tools ───────────────────────────────────────────────────────────────
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function makeTools(workDir) {
+    return [
+        {
+            name: 'read_file',
+            label: '读取文件',
+            description: 'Read the full content of a file at the given path.',
+            parameters: Type.Object({
+                path: Type.String({ description: 'Absolute or relative file path' }),
+            }),
+            async execute(_id, { path: filePath }) {
+                const resolved = path.resolve(workDir, filePath);
+                try {
+                    const content = fs.readFileSync(resolved, 'utf-8');
+                    return {
+                        content: [{ type: 'text', text: content }],
+                        details: { path: resolved },
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                            },
+                        ],
+                        details: { path: resolved },
+                    };
+                }
+            },
+        },
+        {
+            name: 'write_file',
+            label: '写入文件',
+            description: 'Write content to a file, creating it or overwriting if it exists.',
+            parameters: Type.Object({
+                path: Type.String({ description: 'Absolute or relative file path' }),
+                content: Type.String({ description: 'File content to write' }),
+            }),
+            async execute(_id, { path: filePath, content }) {
+                const resolved = path.resolve(workDir, filePath);
+                try {
+                    fs.mkdirSync(path.dirname(resolved), { recursive: true });
+                    fs.writeFileSync(resolved, content, 'utf-8');
+                    return {
+                        content: [
+                            { type: 'text', text: `Written ${content.length} bytes to ${resolved}` },
+                        ],
+                        details: { path: resolved },
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                            },
+                        ],
+                        details: { path: resolved },
+                    };
+                }
+            },
+        },
+        {
+            name: 'list_directory',
+            label: '列出目录',
+            description: 'List files and directories at the given path.',
+            parameters: Type.Object({
+                path: Type.String({ description: 'Directory path to list', default: '.' }),
+            }),
+            async execute(_id, { path: dirPath }) {
+                const resolved = path.resolve(workDir, dirPath);
+                try {
+                    const entries = fs.readdirSync(resolved, { withFileTypes: true });
+                    const lines = entries.map((e) => `${e.isDirectory() ? 'd' : 'f'} ${e.name}`).join('\n');
+                    return {
+                        content: [{ type: 'text', text: lines || '(empty)' }],
+                        details: { path: resolved },
+                    };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                            },
+                        ],
+                        details: { path: resolved },
+                    };
+                }
+            },
+        },
+        {
+            name: 'bash',
+            label: '执行命令',
+            description: 'Execute a shell command in the working directory. Timeout: 30s.',
+            parameters: Type.Object({
+                command: Type.String({ description: 'Shell command to execute' }),
+            }),
+            async execute(_id, { command }, signal) {
+                try {
+                    const { stdout, stderr } = await execFileAsync('bash', ['-c', command], {
+                        cwd: workDir,
+                        timeout: 30_000,
+                        signal,
+                        maxBuffer: 1024 * 1024,
+                    });
+                    const output = [stdout, stderr].filter(Boolean).join('\n---stderr---\n');
+                    return {
+                        content: [{ type: 'text', text: output || '(no output)' }],
+                        details: { command },
+                    };
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    return {
+                        content: [{ type: 'text', text: `Error: ${msg}` }],
+                        details: { command },
+                    };
+                }
+            },
+        },
+        {
+            name: 'read_image',
+            label: '读取图片',
+            description: 'Read an image file and return its content for visual analysis. Supports png, jpg, jpeg, gif, webp. Max 10 MB.',
+            parameters: Type.Object({
+                path: Type.String({ description: 'Absolute or relative path to the image file' }),
+            }),
+            async execute(_id, { path: filePath }) {
+                const resolved = path.resolve(workDir, filePath);
+                const ext = path.extname(resolved).toLowerCase().slice(1);
+                const mimeMap = {
+                    png: 'image/png',
+                    jpg: 'image/jpeg',
+                    jpeg: 'image/jpeg',
+                    gif: 'image/gif',
+                    webp: 'image/webp',
+                };
+                const mimeType = mimeMap[ext];
+                if (!mimeType) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: unsupported image type ".${ext}". Supported: png, jpg, jpeg, gif, webp`,
+                            },
+                        ],
+                        details: { path: resolved },
+                    };
+                }
+                try {
+                    const stat = fs.statSync(resolved);
+                    if (stat.size > 10 * 1024 * 1024) {
+                        return {
+                            content: [
+                                {
+                                    type: 'text',
+                                    text: `Error: image too large (${(stat.size / 1024 / 1024).toFixed(1)} MB, max 10 MB)`,
+                                },
+                            ],
+                            details: { path: resolved },
+                        };
+                    }
+                    const data = fs.readFileSync(resolved).toString('base64');
+                    const imageContent = { type: 'image', data, mimeType };
+                    return { content: [imageContent], details: { path: resolved, mimeType, size: stat.size } };
+                }
+                catch (err) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                            },
+                        ],
+                        details: { path: resolved },
+                    };
+                }
+            },
+        },
+    ];
+}
+// ── PiAdapter ─────────────────────────────────────────────────────────────────
+export class PiAdapter extends AgentAdapter {
+    type = 'pi';
+    agent = null;
+    sessionId = null;
+    workDir = null;
+    seq = 0;
+    runId = '';
+    emittedLengths = new Map();
+    terminalState = 'open';
+    authToken = null;
+    proxyUrl = null;
+    sessionDir = null;
+    messagesPath = null;
+    snapshotPath = null;
+    summaryPath = null;
+    cachedSummary = null;
+    restoredMessages = [];
+    compressing = false;
+    lastSummaryMsgCount = 0;
+    pendingBaseMessages = [];
+    finalizePromise = Promise.resolve();
+    pendingSendStart = null;
+    async start(sessionId, workDir, _agentSessionId) {
+        this.sessionId = sessionId;
+        this.workDir = workDir;
+        this.seq = 0;
+        this.sessionDir = getSessionDir(sessionId);
+        this.messagesPath = path.join(this.sessionDir, MESSAGES_FILENAME);
+        this.snapshotPath = path.join(this.sessionDir, SNAPSHOT_FILENAME);
+        this.summaryPath = path.join(this.sessionDir, SUMMARY_FILENAME);
+        this.loadSnapshot();
+        this.loadSummary();
+    }
+    async send(text, modelId) {
+        this.agent?.abort();
+        const config = loadConfig();
+        const authToken = config.machineToken ?? config.accessToken;
+        if (!authToken) {
+            this.emit('agentEvent', {
+                state: 'error',
+                runId: this.runId,
+                seq: ++this.seq,
+                message: '未配对，请先运行 shennian 完成机器配对',
+            });
+            return;
+        }
+        this.authToken = authToken;
+        this.proxyUrl = (config.serverUrl ?? SERVERS.global.url).replace(/\/$/, '');
+        this.runId = randomUUID();
+        this.seq = 0;
+        this.emittedLengths.clear();
+        this.terminalState = 'open';
+        if (!this.agent) {
+            this.initAgent();
+        }
+        await this.finalizePromise.catch(() => { });
+        this.agent?.setModel(createPiModel(modelId ?? PI_DEFAULT_MODEL_ID));
+        this.pendingBaseMessages = cloneMessages(this.agent?.state.messages ?? []);
+        const runId = this.runId;
+        const sendAccepted = new Promise((resolve, reject) => {
+            this.pendingSendStart = { runId, resolve, reject };
+        });
+        this.emit('agentEvent', { state: 'init', runId, seq: ++this.seq });
+        void this.agent.prompt(text)
+            .then(async () => {
+            this.resolvePendingSendStart(runId);
+            await this.finalizePromise.catch(() => { });
+        })
+            .catch((err) => {
+            this.rejectPendingSendStart(runId, err);
+            if (this.terminalState !== 'open')
+                return;
+            this.terminalState = 'error';
+            const message = err instanceof Error ? err.message : String(err);
+            if (message.includes('429') || message.includes('daily_quota_exceeded')) {
+                this.emit('agentEvent', {
+                    state: 'error',
+                    runId,
+                    seq: ++this.seq,
+                    message: '今日免费额度已用完，可在 ~/.shennian/config.json 中配置 apiKey 字段（兼容 OpenAI 格式）继续使用。',
+                });
+            }
+            else {
+                this.emit('agentEvent', {
+                    state: 'error',
+                    runId,
+                    seq: ++this.seq,
+                    message,
+                });
+            }
+        });
+        await sendAccepted;
+    }
+    // ── Agent lifecycle ──────────────────────────────────────────────────────────
+    initAgent() {
+        const workDir = this.workDir ?? process.cwd();
+        const tools = makeTools(workDir);
+        const agent = new Agent({
+            initialState: {
+                systemPrompt: SYSTEM_PROMPT + `\n\n当前工作目录：${workDir}`,
+                model: createPiModel(),
+                tools,
+            },
+            streamFn: (model, context, options) => streamProxy(model, context, {
+                ...options,
+                authToken: this.authToken,
+                proxyUrl: this.proxyUrl,
+            }),
+            transformContext: (messages) => this.compressContext(messages),
+        });
+        this.agent = agent;
+        if (this.restoredMessages.length > 0) {
+            agent.replaceMessages(cloneMessages(this.restoredMessages));
+        }
+        else if (this.cachedSummary) {
+            agent.appendMessage({
+                role: 'user',
+                content: [{ type: 'text', text: `[之前的对话摘要]\n${this.cachedSummary}` }],
+                timestamp: Date.now(),
+            });
+            agent.appendMessage({
+                role: 'assistant',
+                content: [{ type: 'text', text: '好的，我已了解之前的对话上下文，请继续。' }],
+                timestamp: Date.now(),
+            });
+        }
+        agent.subscribe((evt) => {
+            if (this.terminalState !== 'open')
+                return;
+            const seq = ++this.seq;
+            const runId = this.runId;
+            switch (evt.type) {
+                case 'agent_start':
+                    this.resolvePendingSendStart(runId);
+                    this.emit('agentEvent', { state: 'start', runId, seq });
+                    break;
+                case 'message_update': {
+                    const msg = evt.message;
+                    if (msg.role !== 'assistant')
+                        break;
+                    const content = msg.content ?? [];
+                    for (let i = 0; i < content.length; i++) {
+                        const c = content[i];
+                        if (c.type === 'text' && c.text) {
+                            const key = `text:${i}`;
+                            const prev = this.emittedLengths.get(key) ?? 0;
+                            if (c.text.length > prev) {
+                                const delta = c.text.slice(prev);
+                                this.emittedLengths.set(key, c.text.length);
+                                this.emit('agentEvent', { state: 'delta', runId, seq, text: delta });
+                            }
+                        }
+                        else if (c.type === 'thinking' && c.thinking) {
+                            const key = `thinking:${i}`;
+                            const prev = this.emittedLengths.get(key) ?? 0;
+                            if (c.thinking.length > prev) {
+                                const delta = c.thinking.slice(prev);
+                                this.emittedLengths.set(key, c.thinking.length);
+                                this.emit('agentEvent', { state: 'delta', runId, seq, text: delta, thinking: true });
+                            }
+                        }
+                    }
+                    break;
+                }
+                case 'tool_execution_start':
+                    this.emit('agentEvent', {
+                        state: 'tool-call',
+                        runId,
+                        seq,
+                        name: evt.toolName,
+                        args: evt.args,
+                    });
+                    break;
+                case 'tool_execution_end':
+                    this.emit('agentEvent', {
+                        state: 'tool-result',
+                        runId,
+                        seq,
+                        name: evt.toolName,
+                        result: typeof evt.result === 'string' ? evt.result : JSON.stringify(evt.result),
+                    });
+                    break;
+                case 'agent_end': {
+                    this.terminalState = 'final';
+                    const msgs = evt.messages;
+                    const lastAssistant = [...msgs].reverse().find((m) => m.role === 'assistant');
+                    const usage = lastAssistant?.usage;
+                    this.emit('agentEvent', {
+                        state: 'final',
+                        runId,
+                        seq,
+                        usage: usage
+                            ? {
+                                inputTokens: usage.input ?? 0,
+                                outputTokens: usage.output ?? 0,
+                            }
+                            : undefined,
+                    });
+                    this.finalizePromise = this.finalizeTurn(msgs);
+                    break;
+                }
+            }
+        });
+    }
+    // ── Context compression ────────────────────────────────────────────────────
+    /**
+     * After each turn, compress old messages and actually replace them in the
+     * Agent's internal state. This is the primary compression mechanism.
+     */
+    async compressAndReplace() {
+        if (!this.agent || this.compressing)
+            return;
+        const messages = this.agent.state.messages;
+        const tokens = estimateTokens(messages);
+        if (tokens < CONTEXT_TOKEN_THRESHOLD)
+            return;
+        const split = this.splitMessages(messages);
+        if (!split)
+            return;
+        const summary = await this.generateSummary(split.toCompress);
+        if (!summary)
+            return;
+        this.cachedSummary = summary;
+        this.lastSummaryMsgCount += split.toCompress.length;
+        const replacement = [
+            {
+                role: 'user',
+                content: [{ type: 'text', text: `[历史对话摘要]\n${summary}` }],
+                timestamp: Date.now(),
+            },
+            {
+                role: 'assistant',
+                content: [{ type: 'text', text: '好的，我已了解上下文。' }],
+                timestamp: Date.now(),
+            },
+            ...split.toKeep,
+        ];
+        this.agent.replaceMessages(replacement);
+    }
+    /**
+     * Safety fallback: if messages somehow exceed the threshold at LLM call time
+     * (e.g. compressAndReplace hasn't run yet), return a truncated view using
+     * the cached summary. Does NOT call LLM — avoids nested async delays.
+     */
+    async compressContext(messages) {
+        const tokens = estimateTokens(messages);
+        if (tokens < CONTEXT_TOKEN_THRESHOLD)
+            return messages;
+        if (!this.cachedSummary)
+            return messages;
+        const split = this.splitMessages(messages);
+        if (!split)
+            return messages;
+        return [
+            {
+                role: 'user',
+                content: [{ type: 'text', text: `[历史对话摘要]\n${this.cachedSummary}` }],
+                timestamp: Date.now(),
+            },
+            ...split.toKeep,
+        ];
+    }
+    splitMessages(messages) {
+        const nonSystem = messages.filter((m) => m.role !== 'system');
+        if (nonSystem.length <= KEEP_RECENT_MESSAGES)
+            return null;
+        let splitIdx = nonSystem.length - KEEP_RECENT_MESSAGES;
+        while (splitIdx > 0 &&
+            nonSystem[splitIdx].role === 'toolResult') {
+            splitIdx--;
+        }
+        if (splitIdx <= 0)
+            return null;
+        return { toCompress: nonSystem.slice(0, splitIdx), toKeep: nonSystem.slice(splitIdx) };
+    }
+    async generateSummary(messages) {
+        if (!this.authToken || !this.proxyUrl || this.compressing)
+            return this.cachedSummary;
+        this.compressing = true;
+        try {
+            const text = messagesToText(messages);
+            if (text.length < 100)
+                return null;
+            const truncated = text.length > 10000 ? text.slice(0, 10000) + '\n...(已截断)' : text;
+            return await requestProxySummary(this.proxyUrl, this.authToken, `请将以下对话历史压缩为简洁摘要，保留关键信息：讨论的文件和目录、做出的技术决定、当前任务进度、未完成的工作。摘要控制在 300 字以内。\n\n${truncated}`);
+        }
+        catch {
+            return this.cachedSummary;
+        }
+        finally {
+            this.compressing = false;
+        }
+    }
+    // ── Summary persistence ────────────────────────────────────────────────────
+    loadSnapshot() {
+        if (!this.snapshotPath)
+            return;
+        try {
+            const raw = fs.readFileSync(this.snapshotPath, 'utf-8');
+            const data = JSON.parse(raw);
+            this.restoredMessages = Array.isArray(data.messages) ? data.messages : [];
+            this.cachedSummary = data.summary ?? this.cachedSummary;
+            this.lastSummaryMsgCount = data.summarizedCount ?? this.lastSummaryMsgCount;
+        }
+        catch {
+            this.restoredMessages = [];
+        }
+    }
+    loadSummary() {
+        if (!this.summaryPath)
+            return;
+        try {
+            const raw = fs.readFileSync(this.summaryPath, 'utf-8');
+            const data = JSON.parse(raw);
+            this.cachedSummary = data.summary ?? null;
+            this.lastSummaryMsgCount = data.summarizedCount ?? 0;
+        }
+        catch {
+            if (!this.sessionDir)
+                return;
+            try {
+                const legacyPath = path.join(this.sessionDir, LEGACY_SUMMARY_FILENAME);
+                const raw = fs.readFileSync(legacyPath, 'utf-8');
+                const data = JSON.parse(raw);
+                this.cachedSummary = data.summary ?? null;
+                this.lastSummaryMsgCount = data.summarizedCount ?? 0;
+            }
+            catch {
+                // File doesn't exist or is corrupt — start fresh
+            }
+        }
+    }
+    saveSummary(messages) {
+        if (!this.summaryPath)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.summaryPath), { recursive: true });
+            const summary = buildRollingSummary(this.cachedSummary, messages);
+            this.cachedSummary = summary;
+            fs.writeFileSync(this.summaryPath, JSON.stringify({
+                version: 1,
+                summary,
+                summarizedCount: this.lastSummaryMsgCount,
+                updatedAt: Date.now(),
+            }, null, 2));
+        }
+        catch {
+            // Best-effort persistence
+        }
+    }
+    saveSnapshot(messages) {
+        if (!this.snapshotPath || !this.sessionId || !this.workDir)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.snapshotPath), { recursive: true });
+            fs.writeFileSync(this.snapshotPath, JSON.stringify({
+                version: 1,
+                sessionId: this.sessionId,
+                workDir: this.workDir,
+                summary: this.cachedSummary,
+                summarizedCount: this.lastSummaryMsgCount,
+                messages,
+                updatedAt: Date.now(),
+            }, null, 2));
+            this.restoredMessages = cloneMessages(messages);
+        }
+        catch {
+            // Best-effort persistence
+        }
+    }
+    appendMessagesLog(messages) {
+        if (!this.messagesPath || messages.length === 0)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(this.messagesPath), { recursive: true });
+            const lines = messages.map((message) => JSON.stringify(message)).join('\n') + '\n';
+            fs.appendFileSync(this.messagesPath, lines, 'utf-8');
+        }
+        catch {
+            // Best-effort persistence
+        }
+    }
+    getTurnMessages(finalMessages) {
+        const prefixLength = longestCommonPrefixLength(this.pendingBaseMessages, finalMessages);
+        return cloneMessages(finalMessages.slice(prefixLength));
+    }
+    async finalizeTurn(finalMessages) {
+        const clonedFinalMessages = cloneMessages(finalMessages);
+        const newMessages = this.getTurnMessages(clonedFinalMessages);
+        this.appendMessagesLog(newMessages);
+        await this.compressAndReplace();
+        const currentMessages = this.agent
+            ? cloneMessages(this.agent.state.messages)
+            : clonedFinalMessages;
+        if (!this.cachedSummary) {
+            this.cachedSummary = buildRollingSummary(null, clonedFinalMessages);
+        }
+        this.saveSummary(currentMessages);
+        this.saveSnapshot(currentMessages);
+    }
+    async resume(_agentSessionId) {
+        this.loadSnapshot();
+        this.loadSummary();
+        if (this.agent && this.restoredMessages.length > 0) {
+            this.agent.replaceMessages(cloneMessages(this.restoredMessages));
+        }
+    }
+    async stop() {
+        this.rejectPendingSendStart(this.runId, new Error('Pi run stopped before dispatch completed'));
+        await this.finalizePromise.catch(() => { });
+        if (this.agent) {
+            const currentMessages = cloneMessages(this.agent.state.messages ?? []);
+            this.saveSummary(currentMessages);
+            this.saveSnapshot(currentMessages);
+        }
+        this.agent?.abort();
+        this.agent = null;
+    }
+    resolvePendingSendStart(runId) {
+        if (!this.pendingSendStart || this.pendingSendStart.runId !== runId)
+            return;
+        const { resolve } = this.pendingSendStart;
+        this.pendingSendStart = null;
+        resolve();
+    }
+    rejectPendingSendStart(runId, error) {
+        if (!this.pendingSendStart || this.pendingSendStart.runId !== runId)
+            return;
+        const { reject } = this.pendingSendStart;
+        this.pendingSendStart = null;
+        reject(error);
+    }
+}
+registerAgent('pi', () => new PiAdapter());