minimal-agent 0.2.0 → 0.3.1

package/src/context/compact.js

@@ -0,0 +1,357 @@
+/**
+ * ============================================================
+ *  src/context/compact.ts —— 自动压缩逻辑（v0.2 修复版）
+ * ============================================================
+ *  做的事：
+ *    1. 估算当前历史的 token 数
+ *    2. 若超过阈值（contextWindow - AUTOCOMPACT_BUFFER_TOKENS），触发压缩
+ *    3. 压缩流程：
+ *         a. 把整段历史 + 9 段式压缩 prompt 发给 LLM（非流式）
+ *         b. 提取 <summary> 块
+ *         c. 用"会话延续"包装把摘要做成 user 消息，紧跟最后 N 条原消息
+ *
+ *  v0.2 修复说明（2026-05-08）：
+ *    - 🚨 修复致命 bug：/compact 后 tool_call / tool_result 配对关系破坏
+ *      导致 MiniMax API 返回 400 "tool id not found" 错误
+ *    - ✅ 新增 findTailWithCompleteToolChains() 函数
+ *      智能截取尾部消息，保证每条 tool 消息都有对应的 tool_call 父消息
+ *    - ✅ 不再使用固定的 KEEP_RECENT_MESSAGES = 4 简单切片
+ *    - 改为动态扫描算法：从末尾向前检查完整性，必要时自动扩展
+ *
+ *  为什么保留最后 N 条？
+ *    模型刚执行完工具的 tool_result 不能丢，否则后续推理失去依据。
+ *    但现在不是固定 N 条，而是动态保证 tool 消息完整性。
+ *
+ *  为什么用"延续"包装而不是直接塞摘要？
+ *    借鉴 kakadeai：在摘要前后加上"this session is continued from..."
+ *    + "Recent messages are preserved verbatim" + "Continue from where it
+ *    left off without asking" 三句话，可以让模型直接接着干活而不是把摘要
+ *    当成新任务"重新介绍一遍"。
+ *
+ *  ---- prompt 模板内联自 src/prompts/compact.ts ----
+ */
+import { chat } from '../llm/client.js';
+import { countMessagesTokens } from './tokenCounter.js';
+/** 压缩这一轮严禁调工具——前置警告 */
+const NO_TOOLS_PREAMBLE = `CRITICAL: Respond with TEXT ONLY. Do NOT call any tools.
+
+- Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool.
+- You already have all the context you need in the conversation above.
+- Tool calls will be REJECTED and will waste your only turn — you will fail the task.
+- Your entire response must be plain text: an <analysis> block followed by a <summary> block.
+
+`;
+/** 同样的警告再放在 prompt 末尾——adaptive-thinking 模型在长 prompt 末尾容易"飘" */
+const NO_TOOLS_TRAILER = '\n\nREMINDER: Do NOT call any tools. Respond with plain text only — ' +
+    'an <analysis> block followed by a <summary> block. ' +
+    'Tool calls will be rejected and you will fail the task.';
+/**
+ * 9 段式压缩模板主体——UP_TO 变体。
+ */
+const COMPACT_PROMPT_BODY = `Your task is to create a detailed summary of this conversation. This summary will be placed at the start of a continuing session; newer messages that build on this context will follow after your summary. Summarize thoroughly so that someone reading only your summary and then the newer messages can fully understand what happened and continue the work.
+
+Before providing your final summary, wrap your analysis in <analysis> tags to organize your thoughts and ensure you've covered all necessary points. In your analysis process:
+
+1. Chronologically analyze each message and section of the conversation. For each section thoroughly identify:
+   - The user's explicit requests and intents
+   - Your approach to addressing the user's requests
+   - Key decisions, technical concepts and code patterns
+   - Specific details like file names, full code snippets, function signatures, file edits
+   - Errors that you ran into and how you fixed them
+   - Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+2. Double-check for technical accuracy and completeness, addressing each required element thoroughly.
+
+Your summary should include the following sections:
+
+1. Primary Request and Intent: Capture all of the user's explicit requests and intents in detail
+2. Key Technical Concepts: List all important technical concepts, technologies, and frameworks discussed.
+3. Files and Code Sections: Enumerate specific files and code sections examined, modified, or created. Include FULL code snippets where applicable and include a summary of why this file read or edit is important. (Code snippets are NOT compressed — preserve them verbatim.)
+4. Errors and fixes: List all errors that you ran into, and how you fixed them. Pay special attention to specific user feedback that you received, especially if the user told you to do something differently.
+5. Problem Solving: Document problems solved and any ongoing troubleshooting efforts.
+6. All user messages: List ALL user messages that are not tool results. These are critical for understanding the users' feedback and changing intent. (User messages are NOT compressed — preserve them verbatim.)
+7. Pending Tasks: Outline any pending tasks that you have explicitly been asked to work on.
+8. Work Completed: Describe what was accomplished by the end of this portion.
+9. Context for Continuing Work: Summarize any context, decisions, or state that would be needed to understand and continue the work in subsequent messages. Include direct quotes from the most recent conversation showing exactly where work was left off — this should be verbatim to ensure there's no drift.
+
+Here's an example of how your output should be structured:
+
+<example>
+<analysis>
+[Your thought process, ensuring all points are covered thoroughly and accurately]
+</analysis>
+
+<summary>
+1. Primary Request and Intent:
+   [Detailed description]
+
+2. Key Technical Concepts:
+   - [Concept 1]
+   - [...]
+
+3. Files and Code Sections:
+   - [File Name 1]
+      - [Summary of why this file is important]
+      - [Important Code Snippet]
+   - [...]
+
+4. Errors and fixes:
+    - [Detailed description of error 1]:
+      - [How you fixed the error]
+      - [User feedback on the error if any]
+    - [...]
+
+5. Problem Solving:
+  [Description of solved problems and ongoing troubleshooting]
+
+6. All user messages:
+    - [Detailed non tool use user message]
+    - [...]
+
+7. Pending Tasks:
+   - [Task 1]
+   - [...]
+
+8. Work Completed:
+  [What was accomplished]
+
+9. Context for Continuing Work:
+  [Key context, decisions, or state needed to continue]
+
+</summary>
+</example>
+
+Please provide your summary following this structure, ensuring precision and thoroughness in your response.`;
+/**
+ * 完整的压缩 prompt：preamble + 9 段模板 + 可选的 customInstructions + trailer.
+ */
+export function buildCompactPrompt(customInstructions) {
+    let prompt = NO_TOOLS_PREAMBLE + COMPACT_PROMPT_BODY;
+    if (customInstructions && customInstructions.trim() !== '') {
+        prompt += `\n\nAdditional Instructions:\n${customInstructions.trim()}`;
+    }
+    prompt += NO_TOOLS_TRAILER;
+    return prompt;
+}
+/**
+ * 兼容旧名：现在等价于 buildCompactPrompt() 的默认调用。
+ */
+export const BASE_COMPACT_PROMPT = buildCompactPrompt();
+/**
+ * 把摘要包装成"会话延续"指令——这是让 LLM 接着干活而不是"重新介绍一遍"的关键。
+ */
+export function buildContinuationUserMessage(args) {
+    const { summary, recentMessagesPreserved } = args;
+    let msg = `This session is being continued from a previous conversation that ran out of context. The summary below covers the earlier portion of the conversation.
+
+${summary}`;
+    if (recentMessagesPreserved) {
+        msg += `\n\nRecent messages are preserved verbatim.`;
+    }
+    msg += `\n\nContinue the conversation from where it left off without asking the user any further questions. Resume directly — do not acknowledge the summary, do not recap what was happening, do not preface with "I'll continue" or similar. Pick up the last task as if the break never happened.`;
+    return msg;
+}
+/**
+ * 从 LLM 的压缩响应里提取 <summary>...</summary> 内的内容。
+ */
+export function formatCompactSummary(rawResponse) {
+    const match = rawResponse.match(/<summary>([\s\S]*?)<\/summary>/);
+    if (match)
+        return match[1].trim();
+    // 退化路径：去掉 <analysis> 块（如果有）
+    const stripped = rawResponse.replace(/<analysis>[\s\S]*?<\/analysis>/g, '').trim();
+    return stripped || rawResponse.trim();
+}
+/**
+ * autoCompact 触发阈值的安全 buffer。
+ *
+ * 设计意图：在 contextWindow 被撑满之前留出"必须装得下"的两块空间：
+ *   - 下一次 LLM 完整输出（assistant message + 多个 tool_calls）约 ~12K
+ *   - 发起压缩调用时把 9 段模板 prompt 也算上的余量 ~13K
+ *
+ * 对比：kakadeai 主项目用 ~33K（output 20K + buffer 13K），但它有
+ * prompt cache 收益所以可以更激进；我们没有 cache，25K 是稳健折中。
+ *
+ * 主动触发优先于 reactive 兜底——把 buffer 留宽一点，让 autoCompact
+ * 在 LLM 真撑爆之前先把上下文摘要掉，reactive 几乎不会被触发。
+ */
+export const AUTOCOMPACT_BUFFER_TOKENS = 25_000;
+/**
+ * 最少保留的消息数（即使没有 tool 调用也要保留这么多最近对话）
+ */
+export const MIN_KEEP_RECENT_MESSAGES = 4;
+/**
+ * 给定 provider 的压缩触发阈值
+ */
+export function getCompactThreshold(provider) {
+    return Math.max(1000, provider.contextWindow - AUTOCOMPACT_BUFFER_TOKENS);
+}
+/**
+ * ✅ 核心修复函数：智能截取尾部消息，保证 tool_call / tool_result 完整性。
+ *
+ * 问题背景：
+ *   OpenAI 协议要求 tool 消息的 tool_call_id 必须对应前面某条 assistant 消息
+ *   的 tool_calls[].id。如果压缩时只保留 tool 消息但丢掉了对应的 tool_call，
+ *   API 会返回 400 错误 "tool id not found"。
+ *
+ * 算法：
+ *   1. 从消息数组末尾开始，至少保留 minKeep 条消息
+ *   2. 维护一个 Set<tool_call_id> 记录已见过的 tool_call ID
+ *   3. 遇到 tool 消息时，检查其 tool_call_id 是否在 Set 中
+ *      - 如果不在 → 说明对应的 tool_call 消息被截断了 → 继续向前扩展
+ *      - 如果在 → 正常保留
+ *   4. 遇到 assistant 消息且有 tool_calls → 把所有 ID 加入 Set
+ *   5. 直到所有 tool 消息都有父级或到达数组开头
+ *
+ * @param messages 非系统消息数组
+ * @param minKeep 最少保留条数（默认 4）
+ * @returns 截取后的尾部子数组（保证 tool 消息完整性）
+ *
+ * 示例：
+ *   输入: [user, assistant(tool:A), tool(id:A), user, assistant]
+ *   minKeep: 3
+ *   输出: [assistant(tool:A), tool(id:A), user, assistant] (4条，自动扩展)
+ *
+ * 时间复杂度: O(N × M), N=消息数, M=平均扩展次数(通常<5)
+ * 空间复杂度: O(T), T=唯一 tool_call_id 数量(通常<20)
+ */
+export function findTailWithCompleteToolChains(messages, minKeep = MIN_KEEP_RECENT_MESSAGES) {
+    if (messages.length <= minKeep)
+        return [...messages];
+    // 至少保留 minKeep 条
+    const tailEnd = messages.length;
+    let tailStart = tailEnd - minKeep;
+    // 收集已经保留的 assistant 消息中的 tool_call IDs
+    const knownToolCallIds = new Set();
+    // 初始化已知 ID（从 minKeep 范围内）
+    for (let i = tailStart; i < tailEnd; i++) {
+        const msg = messages[i];
+        if (msg.role === 'assistant' && msg.tool_calls) {
+            for (const tc of msg.tool_calls) {
+                knownToolCallIds.add(tc.id);
+            }
+        }
+    }
+    // 检查是否有孤儿 tool 消息，如果有则向前扩展
+    let needsExpansion = true;
+    while (needsExpansion && tailStart > 0) {
+        needsExpansion = false;
+        for (let i = tailStart; i < tailEnd; i++) {
+            const msg = messages[i];
+            // 检查 tool 消息是否孤儿
+            if (msg.role === 'tool' && msg.tool_call_id) {
+                if (!knownToolCallIds.has(msg.tool_call_id)) {
+                    // ❌ 找到孤儿 tool 消息！需要向前扩展
+                    needsExpansion = true;
+                    tailStart--;
+                    // 把新加入的消息中的 tool_call ID 也加入集合
+                    const newMsg = messages[tailStart];
+                    if (newMsg.role === 'assistant' && newMsg.tool_calls) {
+                        for (const tc of newMsg.tool_calls) {
+                            knownToolCallIds.add(tc.id);
+                        }
+                    }
+                    // 重新开始检查（因为新加入的消息可能也是 tool 孤儿）
+                    break;
+                }
+            }
+        }
+    }
+    return messages.slice(tailStart);
+}
+/**
+ * 检查并按需压缩历史。
+ *
+ * @param messages 当前完整历史（必含一条 system）
+ * @param provider 当前 provider（取 contextWindow）
+ * @returns 可能更短的新 messages 数组（不修改原数组）
+ *
+ * 当 tokens 不超阈值时**直接返回原数组**（同引用），调用方可据此判断"是否压缩了"。
+ */
+export async function autoCompactIfNeeded(messages, provider) {
+    const before = countMessagesTokens(messages);
+    const threshold = getCompactThreshold(provider);
+    if (before < threshold) {
+        return { messages, compacted: false, before, after: before };
+    }
+    // 真正要压缩了
+    const compactedMessages = await runCompaction(messages, provider);
+    const after = countMessagesTokens(compactedMessages);
+    return { messages: compactedMessages, compacted: true, before, after };
+}
+/**
+ * 不看阈值，直接执行一次压缩。供 `/compact` 手动命令使用。
+ *
+ * 与 autoCompactIfNeeded 共用同一段 runCompaction 逻辑；区别仅在于此函数
+ * 永远跑压缩、不返回 `compacted` 字段（由调用方决定如何反馈）。
+ */
+export async function forceCompact(messages, provider) {
+    const before = countMessagesTokens(messages);
+    const compactedMessages = await runCompaction(messages, provider);
+    const after = countMessagesTokens(compactedMessages);
+    return { messages: compactedMessages, before, after };
+}
+/**
+ * 真正执行压缩（一轮非流式 LLM 调用）。
+ *
+ * 输入：原始历史
+ * 输出：[原 system, "会话延续指令 + 摘要" 的 user 消息, 最后 N 条原消息（保证完整性）]
+ *
+ * ✅ 关键修复：使用 findTailWithCompleteToolChains() 替代简单的 slice(-N)
+ * 保证压缩后的消息结构符合 OpenAI 协议要求（tool 消息必须有对应的 tool_call 父消息）。
+ */
+async function runCompaction(messages, provider) {
+    // 1. 找出原 system（保留它，避免 agent 失忆）
+    const systemMsg = messages.find((m) => m.role === 'system');
+    const nonSystem = messages.filter((m) => m.role !== 'system');
+    // 2. 构造给"压缩用"的请求：完整历史 + 9 段式压缩 prompt
+    //    （即使最后 N 条会被原样保留在新历史里，也送给 LLM 看 —— 让它写得出
+    //     高质量的 "Context for Continuing Work" 节，知道当前停在哪儿。）
+    const compactRequest = [
+        ...(systemMsg ? [systemMsg] : []),
+        ...nonSystem,
+        {
+            role: 'user',
+            content: buildCompactPrompt(),
+        },
+    ];
+    // 3. 调 LLM（用同一个 chat() 但不传工具，避免模型尝试调用工具）
+    let summary = '';
+    try {
+        for await (const ev of chat({
+            provider,
+            messages: compactRequest,
+            tools: [],
+        })) {
+            if (ev.type === 'text_delta')
+                summary += ev.delta;
+        }
+    }
+    catch (e) {
+        // 压缩失败时降级：保留原历史的最后 N 条 + 一条用 user 消息说明压缩失败
+        // ✅ 即使降级也要使用智能截取保证完整性
+        return [
+            ...(systemMsg ? [systemMsg] : []),
+            {
+                role: 'user',
+                content: `(自动压缩失败：${e.message}，已直接截断旧历史)`,
+            },
+            ...findTailWithCompleteToolChains(nonSystem),
+        ];
+    }
+    const cleanSummary = formatCompactSummary(summary);
+    // ✅ 核心修复：智能截取尾部，保证 tool 消息完整性
+    // 不再使用固定的 slice(-KEEP_RECENT_MESSAGES)
+    const recentTail = findTailWithCompleteToolChains(nonSystem);
+    // 4. 组装新历史：用"会话延续"包装把摘要做成 user 消息
+    return [
+        ...(systemMsg ? [systemMsg] : []),
+        {
+            role: 'user',
+            content: buildContinuationUserMessage({
+                summary: cleanSummary,
+                recentMessagesPreserved: recentTail.length > 0,
+            }),
+        },
+        ...recentTail,
+    ];
+}

package/src/context/microCompactLite.js

@@ -0,0 +1,151 @@
+/**
+ * ============================================================
+ *  src/context/microCompactLite.ts —— 工具结果微压缩（v2）
+ * ------------------------------------------------------------
+ *  对齐 kakadeai 的 microCompact 设计，纯规则实现，零 LLM 调用。
+ *
+ *  核心思路：
+ *    工具执行结果在写入 history 前经过一道"单向检查门"，
+ *    用规则压缩冗余内容，减少 token 消耗但不丢失关键信息。
+ *
+ *  对齐 kakadeai 的两条有效路径：
+ *    Path A: Cached MC → 本方案用 SHA-1 进程缓存 + 计数淘汰实现
+ *    Path B: Time-based MC → 本方案用轮次衰减实现
+ *
+ *  kakadeai 已删除 Legacy LLM path → 本方案不实现 LLM 压缩
+ * ============================================================
+ */
+import { createHash } from 'node:crypto';
+// ==================== 配置常量 ====================
+/** 同一内容最多原样保留多少次，之后用压缩引用替代 */
+const MAX_REPEAT_COUNT = 3;
+/** 触发截断的字符数阈值（仅白名单内的工具） */
+const MAX_RESULT_SIZE = 4000;
+/** 截断时保留的头部字符数 */
+const HEAD_KEEP_CHARS = 2000;
+/** 截断时保留的尾部字符数 */
+const TAIL_KEEP_CHARS = 1000;
+/** 时间衰减：条目首次出现后超过多少轮自动清理 */
+const MAX_KEEP_ROUNDS = 10;
+/** 短内容阈值：不超过此长度的内容直接放行（不做任何处理） */
+const SHORT_CONTENT_THRESHOLD = 200;
+export function createMicroCompactState() {
+    return { turn: 0, cache: new Map() };
+}
+const defaultState = createMicroCompactState();
+export function incrementTurn(state = defaultState) {
+    state.turn++;
+}
+export function resetTurn(state = defaultState) {
+    state.turn = 0;
+}
+/** 获取当前缓存统计 */
+export function getCacheStats(state = defaultState) {
+    let compressedCount = 0;
+    let expiredCount = 0;
+    let truncatedCount = 0;
+    let totalCharsSaved = 0;
+    let repeatedCount = 0;
+    for (const entry of state.cache.values()) {
+        if (entry.count > 1)
+            repeatedCount++;
+        if (entry.count > MAX_REPEAT_COUNT) {
+            compressedCount++;
+            totalCharsSaved += (entry.count - MAX_REPEAT_COUNT) * 500;
+        }
+        if (state.turn - entry.firstSeenTurn > MAX_KEEP_ROUNDS) {
+            expiredCount++;
+        }
+    }
+    return { totalEntries: state.cache.size, repeatedCount, compressedCount, expiredCount, truncatedCount, totalCharsSaved };
+}
+/** 清空缓存（供 /new 命令或测试使用） */
+export function clearCache(state = defaultState) {
+    state.cache.clear();
+    state.turn = 0;
+}
+// ==================== 工具白名单 ====================
+/**
+ * 只有这些工具的返回值参与微压缩（长度截断 + SHA-1 去重）。
+ *
+ * 排除 Read/Edit/Write 的原因：输出本身就短，有独立的大小限制。
+ * 排除 WebSearch 的原因：搜索结果是"一次性知识注入"，首次必须完整展示给模型；
+ *   后续重复时由 SHA-1 去重处理，但不做长度截断（避免丢失关键信息）。
+ */
+const COMPRESSIBLE_TOOLS = new Set([
+    'Grep',
+    'Bash',
+    'WebFetch',
+    'Glob',
+]);
+// ==================== 核心函数 ====================
+/**
+ * 对一条工具执行结果进行微压缩处理。
+ *
+ * 这是整个模块唯一的对外接口。loop.ts 在把 tool_result 塞入 history 之前调用它。
+ *
+ * 处理流水线（按优先级）：
+ *   Rule 0: 错误/短内容 → 原样放行
+ *   Rule 1: SHA-1 去重 → 相同内容第 4 次起压缩为引用标记
+ *   Rule 2: 时间衰减 → 超过 N 轮未再出现的内容清理掉
+ *   Rule 3: 长度截断 → 白名单工具超长内容保留头尾 + 省略标记
+ *
+ * @param toolName 工具名
+ * @param content 工具返回的原始内容
+ * @returns 处理后的内容（可能被压缩、截断、或原样返回）
+ */
+export function microCompact(toolName, content, state = defaultState) {
+    if (!content)
+        return content;
+    // Rule 0: 错误信息原样保留
+    if (content.startsWith('Error:') || content.startsWith('错误')) {
+        return content;
+    }
+    // Rule 0b: 短内容直接放行
+    if (content.length <= SHORT_CONTENT_THRESHOLD) {
+        return content;
+    }
+    // Rule 1: SHA-1 去重
+    const hash = sha1(content);
+    const existing = state.cache.get(hash);
+    if (existing) {
+        existing.count++;
+        if (existing.count > MAX_REPEAT_COUNT) {
+            return `[↑ ${existing.firstToolName} 结果已重复出现 ${existing.count} 次（相同内容已省略）]`;
+        }
+        return content;
+    }
+    // 首次看到此内容
+    state.cache.set(hash, { count: 1, firstToolName: toolName, firstSeenTurn: state.turn });
+    // Rule 2: 不需要——首次出现不存在时间衰减问题
+    // Rule 3: 长度截断（仅白名单工具）
+    if (content.length > MAX_RESULT_SIZE && COMPRESSIBLE_TOOLS.has(toolName)) {
+        return truncateContent(content);
+    }
+    return content;
+}
+/**
+ * 清理过期条目（每轮开始前调用）。
+ * 将超过 MAX_KEEP_ROUNDS 未被再次访问的条目标记为过期，
+ * 后续如果这些条目的 hash 再次命中，会作为"新内容"重新计数。
+ */
+export function expireOldEntries(state = defaultState) {
+    let expired = 0;
+    for (const [hash, entry] of state.cache) {
+        if (state.turn - entry.firstSeenTurn > MAX_KEEP_ROUNDS) {
+            state.cache.delete(hash);
+            expired++;
+        }
+    }
+    return expired;
+}
+// ==================== 内部函数 ====================
+function sha1(str) {
+    return createHash('sha1').update(str).digest('hex');
+}
+function truncateContent(content) {
+    const omitted = content.length - HEAD_KEEP_CHARS - TAIL_KEEP_CHARS;
+    return (content.slice(0, HEAD_KEEP_CHARS) +
+        `\n\n[... 省略了 ${omitted.toLocaleString()} 字符 ...]\n\n` +
+        content.slice(-TAIL_KEEP_CHARS));
+}

package/src/context/persistContext.js

@@ -0,0 +1,109 @@
+/**
+ * ============================================================
+ *  src/context/persistContext.ts —— 单上下文持久化（无会话管理）
+ * ------------------------------------------------------------
+ *  做的事：
+ *    把"上一次关闭时的对话历史"落盘到一个固定文件。下次启动（TUI 或 -p）
+ *    自动加载，等于无缝续上。整个项目就一个上下文，不存在 session id /
+ *    list / resume 之类的概念。
+ *
+ *  文件路径：
+ *    ~/.minimal-agent/sessions/<目录哈希>.json
+ *    （按当前工作目录隔离；可用 MINIMAL_AGENT_CONTEXT_FILE 覆盖，给测试用）
+ *
+ *  存储格式：
+ *    { updatedAt: number; messages: Message[] }
+ *
+ *  抉择：
+ *    - load 出来若为空或损坏 → 当作"没历史"返回 null，调用方 fallback 到
+ *      只含 system prompt 的 fresh history。永不抛错。
+ *    - save 直接覆写整个文件，不做 atomic（教学项目可接受；进程崩溃丢的
+ *      就是当前这一轮）。
+ *    - 不做 system prompt 替换：调用方拿到 messages 后想替/不替自己决定。
+ * ============================================================
+ */
+import { mkdir, readFile, readdir, rmdir, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+import { sessionFileFor } from './sessionPath.js';
+/** 上下文文件路径（按工作目录隔离，可用环境变量覆盖） */
+export function getContextPath() {
+    if (process.env.MINIMAL_AGENT_CONTEXT_FILE) {
+        return process.env.MINIMAL_AGENT_CONTEXT_FILE;
+    }
+    return sessionFileFor(getWorkingDir());
+}
+/**
+ * 加载上次的上下文。
+ *  - 文件不存在 / 解析失败 / 格式不符 → 返回 null（调用方应当 fallback）
+ *  - 成功 → 返回 messages 数组（可能为空数组）
+ *  - 显式传入 file 时优先使用，便于 HTTP 模式按 sessionKey 隔离
+ */
+export async function loadContext(file) {
+    const target = file ?? getContextPath();
+    try {
+        const raw = await readFile(target, 'utf8');
+        const data = JSON.parse(raw);
+        if (!Array.isArray(data.messages))
+            return null;
+        return data.messages;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 保存当前 messages 为"上下文文件"，覆盖之前内容。
+ * 写失败不抛——丢一次落盘比把进程崩掉划算。
+ */
+export async function saveContext(messages, file) {
+    const target = file ?? getContextPath();
+    try {
+        await mkdir(dirname(target), { recursive: true });
+        const data = { updatedAt: Date.now(), messages };
+        await writeFile(target, JSON.stringify(data), 'utf8');
+    }
+    catch {
+        // 静默吞：持久化失败不该影响对话本身
+    }
+}
+/**
+ * 清空上下文文件（/new 用）。文件不存在也算成功。
+ *
+ * 同时清理当前工作目录下所有 `.minimal-agent` / `.minimal-agent-<tag>/`
+ * 状态目录（各类插件可能在 cwd 下创建多个 sessionTag 目录）。
+ * 注意：只扫当前 cwd 的子目录，不递归、不跨工作目录，保证并行 session 不串台。
+ */
+export async function clearContext(file) {
+    const target = file ?? getContextPath();
+    try {
+        await unlink(target);
+    }
+    catch {
+    }
+    const cwd = getWorkingDir();
+    let topEntries;
+    try {
+        topEntries = await readdir(cwd);
+    }
+    catch {
+        return;
+    }
+    const stateDirs = topEntries.filter((name) => name === '.minimal-agent' || name.startsWith('.minimal-agent-'));
+    for (const name of stateDirs) {
+        const dir = join(cwd, name);
+        try {
+            const entries = await readdir(dir);
+            for (const entry of entries) {
+                try {
+                    await unlink(join(dir, entry));
+                }
+                catch {
+                }
+            }
+            await rmdir(dir);
+        }
+        catch {
+        }
+    }
+}