minimal-agent 0.10.0 → 0.12.0

package/src/context/persistContext.ts

@@ -0,0 +1,177 @@
+/**
+ * ============================================================
+ *  src/context/persistContext.ts —— 单个会话文件的持久化读写
+ * ------------------------------------------------------------
+ *  做的事：
+ *    把"上一次关闭时的对话历史"落盘到一个文件。下次启动（TUI 或 -p）
+ *    自动加载，等于无缝续上。
+ *
+ *    ⚠️ 本文件本身不管"同一 cwd 下有哪些 session、怎么列出/切换/新建"——
+ *    那是 context/sessionRegistry.ts 的职责（已支持完整多 session
+ *    CRUD + TUI 的 /session /sessions /resume + CLI 的 --session）。
+ *    这里只负责"给定一个具体文件路径，读/写/清空它"，调用方（TUI 的
+ *    useChat.ts、CLI 的 main.tsx/print.ts/streamJson.ts）决定要读写哪个
+ *    session 对应的文件——不传 file 时缺省走 `default` session（向后兼容）。
+ *
+ *  文件路径：
+ *    ~/.minimal-agent/sessions/<目录哈希>[--<sessionId>].json
+ *    （按当前工作目录隔离；可用 MINIMAL_AGENT_CONTEXT_FILE 覆盖，给测试用）
+ *
+ *  存储格式：
+ *    { updatedAt: number; messages: Message[] }
+ *
+ *  抉择：
+ *    - load 出来若为空或损坏 → 当作"没历史"返回 null，调用方 fallback 到
+ *      只含 system prompt 的 fresh history。永不抛错。
+ *    - save 使用唯一临时文件 + atomic rename，避免崩溃留下半截 JSON；
+ *      同一 Session 的跨进程互斥由 contextLock 负责。
+ *    - 不做 system prompt 替换：调用方拿到 messages 后想替/不替自己决定。
+ * ============================================================
+ */
+
+import { randomUUID } from 'node:crypto';
+import { mkdir, readFile, readdir, rename, rmdir, unlink, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+
+import { getWorkingDir } from '../bootstrap/workingDir.js';
+import type { Message } from '../types.js';
+import { archiveCurrent } from './archive.js';
+import { sessionFileFor } from './sessionPath.js';
+
+interface PersistedFile {
+  updatedAt: number;
+  messages: Message[];
+}
+
+/** 上下文文件路径（按工作目录隔离，可用环境变量覆盖） */
+export function getContextPath(): string {
+  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?: string): Promise<Message[] | null> {
+  const target = file ?? getContextPath();
+  try {
+    const raw = await readFile(target, 'utf8');
+    const data = JSON.parse(raw) as PersistedFile;
+    if (!Array.isArray(data.messages)) return null;
+    return data.messages;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 把 messages 数组过滤掉 _ephemeral=true 的 system 消息。
+ *
+ * v2.x 新增：UI 用 ephemeral system 消息把 slash 命令输出落进 scrollback
+ * （替代 process.stdout.write 旁路 Ink）。这种消息只供 UI 展示，不该污染
+ * 持久化历史；这里在 saveContext 之前做一次过滤。
+ *
+ * 导出供测试断言。
+ */
+export function filterEphemeralMessages(messages: Message[]): Message[] {
+  return messages.filter(
+    (m) => !(m.role === 'system' && (m as { _ephemeral?: true })._ephemeral === true),
+  );
+}
+
+/**
+ * 保存当前 messages 为"上下文文件"，覆盖之前内容。
+ * 写失败不抛——丢一次落盘比把进程崩掉划算。
+ *
+ * v2.x 新增：写盘前过滤掉 _ephemeral=true 的 system 消息（UI 临时提示，
+ * 不应进入持久化历史）。
+ */
+export async function saveContext(messages: Message[], file?: string): Promise<void> {
+  const target = file ?? getContextPath();
+  const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+  try {
+    await mkdir(dirname(target), { recursive: true });
+    const persistable = filterEphemeralMessages(messages);
+    const data: PersistedFile = { updatedAt: Date.now(), messages: persistable };
+    await writeFile(temp, JSON.stringify(data), { encoding: 'utf8', mode: 0o600 });
+    await rename(temp, target);
+  } catch (e) {
+    // 不抛（持久化失败不该影响对话本身），但要出声——磁盘满/权限问题时
+    // 用户整段会话会静默丢失；与 clearContext 的 archive 失败处理风格对齐。
+    try {
+      process.stderr.write(
+        `[minimal-agent] 会话落盘失败（本轮继续）：${(e as Error).message}\n`,
+      );
+    } catch {
+      /* stderr 不可用也不阻断 */
+    }
+  } finally {
+    await unlink(temp).catch(() => {});
+  }
+}
+
+/**
+ * 清空上下文文件（/new 用）。文件不存在也算成功。
+ *
+ * 同时清理当前工作目录下所有 `.minimal-agent` / `.minimal-agent-<tag>/`
+ * 状态目录（各类插件可能在 cwd 下创建多个 sessionTag 目录）。
+ * 注意：只扫当前 cwd 的子目录，不递归、不跨工作目录，保证并行 session 不串台。
+ */
+export async function clearContext(file?: string): Promise<void> {
+  const target = file ?? getContextPath();
+
+  // 归档当前历史（仅含 system 的空对话会跳过）；失败不阻塞 clear
+  // 显式传 file（HTTP 模式 / 测试覆盖路径）或 MINIMAL_AGENT_CONTEXT_FILE 激活时
+  // 跳过 archive：这两种语义下 caller 自管路径，不应污染默认 archive 目录
+  const skipArchive =
+    file !== undefined || !!process.env.MINIMAL_AGENT_CONTEXT_FILE;
+  if (!skipArchive) {
+    try {
+      const current = await loadContext(target);
+      if (current && current.length > 0) {
+        await archiveCurrent(current);
+      }
+    } catch (e) {
+      process.stderr.write(
+        `[minimal-agent] archive 失败（继续 clear）：${(e as Error).message}\n`,
+      );
+    }
+  }
+
+  try {
+    await unlink(target);
+  } catch {
+  }
+
+  const cwd = getWorkingDir();
+  let topEntries: string[];
+  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 {
+    }
+  }
+}

package/src/context/reactiveCompact.js

@@ -88,8 +88,9 @@ function errorMessage(error) {
  * @param error    刚刚抛出的错误
  * @param state    可选的独立状态（默认使用进程级单例）
  * @param signal   用户中断信号（透传给内部的 forceCompact → chat()，让"压缩中"这个阶段也能响应 ESC/Ctrl+C）
+ * @param promptCache 当前 Session 的缓存路由；压缩请求与主回合保持同一 Provider 路由。
  */
-export async function reactiveCompactIfApplicable(messages, provider, error, state = defaultState, signal, dependencies = {}) {
+export async function reactiveCompactIfApplicable(messages, provider, error, state = defaultState, signal, dependencies = {}, promptCache) {
     // 非 prompt_too_long 错误：直接短路，不消耗计数
     if (!isPromptTooLongError(error)) {
         return { recovered: false, messages, reason: 'not a prompt-too-long error' };
@@ -105,18 +106,27 @@ export async function reactiveCompactIfApplicable(messages, provider, error, sta
     // Step 1: 先试 LLM 全量压缩
     try {
         const compact = dependencies.forceCompact ?? forceCompact;
-        const r = await compact(messages, provider, signal);
+        const r = await compact(messages, provider, signal, undefined, promptCache);
         // 救活成功 → 清零计数，让后续继续可用
         state.consecutiveFailures = 0;
         return {
             recovered: true,
             messages: r.messages,
-            reason: `LLM 压缩成功（${r.before} → ${r.after} tokens）`,
+            reason: r.mode === 'snip-fallback'
+                ? `LLM 摘要失败后 snip 兜底成功（${r.before} → ${r.after} tokens）`
+                : `LLM 压缩成功（${r.before} → ${r.after} tokens）`,
             before: r.before,
             after: r.after,
+            mode: r.mode ?? 'llm-summary',
+            degraded: r.degraded ?? false,
+            ...(r.fallbackReason ? { fallbackReason: r.fallbackReason } : {}),
+            ...(r.messagesRemoved !== undefined ? { messagesRemoved: r.messagesRemoved } : {}),
+            ...(r.tokensFreed !== undefined ? { tokensFreed: r.tokensFreed } : {}),
         };
     }
-    catch {
+    catch (error) {
+        if (signal?.aborted || error.name === 'AbortError')
+            throw error;
         // 压缩失败 → 走 snip 兜底
     }
     // Step 2: snip 兜底（更激进 40%）
@@ -132,6 +142,11 @@ export async function reactiveCompactIfApplicable(messages, provider, error, sta
             reason: `snip 兜底成功（删除 ${snipped.messagesRemoved} 条最老消息，释放 ~${snipped.tokensFreed} tokens）`,
             before: beforeSnip,
             after: afterSnip,
+            mode: 'snip-fallback',
+            degraded: true,
+            fallbackReason: 'llm-error',
+            messagesRemoved: snipped.messagesRemoved,
+            tokensFreed: snipped.tokensFreed,
         };
     }
     // 两步都没救活 → 失败计数 +1

package/src/context/reactiveCompact.ts

@@ -0,0 +1,240 @@
+/**
+ * ============================================================
+ *  src/context/reactiveCompact.ts —— 反应式压缩（错误自救）
+ * ------------------------------------------------------------
+ *  对齐 kakadeai 主项目 services/compact/reactiveCompact.ts：
+ *  当 API 返回 "prompt too long" 类错误时，自动触发压缩重试。
+ *
+ *  典型场景：
+ *    用户灌了一大段上下文 → 调 LLM → 返回 400 prompt_too_long
+ *    → 系统不直接报错，而是先调 forceCompact 把上下文摘要一遍
+ *    → 摘要失败再用 snipCompact 砍头兜底
+ *    → 把新上下文交还给调用方，调用方重试一次 chat()
+ *
+ *  防爆约束（circuit breaker）：
+ *    连续自救失败 MAX_CONSECUTIVE_REACTIVE_FAILURES 次才熔断。
+ *    任意一次自救成功（LLM 压缩或 snip 兜底）→ 计数清零，
+ *    允许后续再次触发。行为：压缩成功→继续→再溢出→再压→正常往复。
+ *    用户 /new 重启会话后 consecutiveFailures 也归零。
+ * ============================================================
+ */
+
+import type {
+  CompactionFallbackReason,
+  CompactionMode,
+  Message,
+  PromptCacheContext,
+  Provider,
+} from '../types.js';
+import { forceCompact } from './compact.js';
+import { snipCompactIfNeeded } from './snipCompact.js';
+import { countMessagesTokens } from './tokenCounter.js';
+
+// ==================== Session 级状态 ====================
+
+/**
+ * 反应式压缩的运行时状态。模块级 defaultState 用于单进程场景（TUI / print），
+ * 多并发场景（HTTP server per-request）调 createReactiveCompactState() 拿独立一份。
+ *
+ * consecutiveFailures：连续自救失败次数；成功一次清零，≥上限才熔断拒绝（防死循环）。
+ */
+export interface ReactiveCompactState {
+  consecutiveFailures: number;
+}
+
+export function createReactiveCompactState(): ReactiveCompactState {
+  return { consecutiveFailures: 0 };
+}
+
+/** 连续失败几次触发熔断，拒绝继续自救 */
+export const MAX_CONSECUTIVE_REACTIVE_FAILURES = 3;
+
+const defaultState: ReactiveCompactState = createReactiveCompactState();
+
+/** /new 时调用，允许下一个 session 再次自救 */
+export function resetReactiveCompactState(
+  state: ReactiveCompactState = defaultState,
+): void {
+  state.consecutiveFailures = 0;
+}
+
+/**
+ * 测试 / 调试用：查询 circuit breaker 是否已熔断（连续失败达上限）。
+ *
+ * 原签名 hasAttemptedReactiveCompact 在新语义下映射为「电路是否已断开」：
+ * 单次成功就清零，只有连续失败 ≥ MAX_CONSECUTIVE_REACTIVE_FAILURES 才返回 true。
+ * 效果等价于原先的 attempted 旗标语义的"超集"（原先=1次，新=N次）。
+ * 别名 isReactiveCircuitOpen 供新代码使用，两者完全等价。
+ */
+export function hasAttemptedReactiveCompact(
+  state: ReactiveCompactState = defaultState,
+): boolean {
+  return state.consecutiveFailures >= MAX_CONSECUTIVE_REACTIVE_FAILURES;
+}
+
+/** hasAttemptedReactiveCompact 的语义化别名 */
+export const isReactiveCircuitOpen = hasAttemptedReactiveCompact;
+
+// ==================== 错误识别 ====================
+
+/**
+ * 判断一个错误是否是"提示词太长"类错误。
+ *
+ * 兼容多家 provider 的错误消息格式：
+ *   - OpenAI:   "This model's maximum context length is X tokens..."
+ *   - Anthropic: "prompt is too long"
+ *   - MiniMax:  "input length exceeds the context window"
+ *   - DeepSeek: "context_length_exceeded"
+ *   - 通用:     含 "prompt" / "context" / "token" 且含 "long"/"exceed"/"limit"
+ */
+export function isPromptTooLongError(error: unknown): boolean {
+  const msg = errorMessage(error).toLowerCase();
+  if (!msg) return false;
+
+  // 宽松匹配：提及 prompt/context/token 且提及 long/exceed/limit/max
+  const hasSubject = /prompt|context|token|input length/.test(msg);
+  const hasIssue = /too long|exceed|limit|maximum|over/.test(msg);
+  return hasSubject && hasIssue;
+}
+
+function errorMessage(error: unknown): string {
+  if (typeof error === 'string') return error;
+  if (error instanceof Error) return error.message;
+  if (error && typeof error === 'object' && 'message' in error) {
+    return String((error as { message: unknown }).message ?? '');
+  }
+  return String(error ?? '');
+}
+
+// ==================== 核心函数 ====================
+
+export interface ReactiveCompactResult {
+  /** 是否成功自救（true 表示调用方可以拿 messages 重试 chat()） */
+  recovered: boolean;
+  /** 自救后的新历史（recovered=false 时与原数组等价） */
+  messages: Message[];
+  /** 解释发生了什么；recovered=true 时含简短说明，否则含拒绝理由 */
+  reason: string;
+  /** 压缩前的 token 数（仅 recovered=true 时填充，供 UI 展示压缩效果） */
+  before?: number;
+  /** 压缩后的 token 数（仅 recovered=true 时填充） */
+  after?: number;
+  mode?: CompactionMode;
+  degraded?: boolean;
+  fallbackReason?: CompactionFallbackReason;
+  messagesRemoved?: number;
+  tokensFreed?: number;
+}
+
+export interface ReactiveCompactDependencies {
+  forceCompact?: (
+    messages: Message[],
+    provider: Provider,
+    signal?: AbortSignal,
+    chatFn?: Parameters<typeof forceCompact>[3],
+    promptCache?: PromptCacheContext,
+  ) => Promise<{
+    messages: Message[];
+    before: number;
+    after: number;
+    mode?: CompactionMode;
+    degraded?: boolean;
+    fallbackReason?: CompactionFallbackReason;
+    messagesRemoved?: number;
+    tokensFreed?: number;
+  }>;
+}
+
+/**
+ * 如果当前错误是 prompt_too_long 且 circuit breaker 未熔断，
+ * 执行一次"先 LLM 压缩、失败兜底 snip"的恢复流程。
+ *
+ * circuit breaker 规则：
+ *   - 任意成功（LLM 压缩 or snip 兜底）→ consecutiveFailures 清零
+ *   - 两个步骤都失败 → consecutiveFailures +1
+ *   - consecutiveFailures ≥ MAX_CONSECUTIVE_REACTIVE_FAILURES → 熔断拒绝
+ *
+ * @param messages 当前历史（不修改）
+ * @param provider 当前 provider（用于 LLM 压缩）
+ * @param error    刚刚抛出的错误
+ * @param state    可选的独立状态（默认使用进程级单例）
+ * @param signal   用户中断信号（透传给内部的 forceCompact → chat()，让"压缩中"这个阶段也能响应 ESC/Ctrl+C）
+ * @param promptCache 当前 Session 的缓存路由；压缩请求与主回合保持同一 Provider 路由。
+ */
+export async function reactiveCompactIfApplicable(
+  messages: Message[],
+  provider: Provider,
+  error: unknown,
+  state: ReactiveCompactState = defaultState,
+  signal?: AbortSignal,
+  dependencies: ReactiveCompactDependencies = {},
+  promptCache?: PromptCacheContext,
+): Promise<ReactiveCompactResult> {
+  // 非 prompt_too_long 错误：直接短路，不消耗计数
+  if (!isPromptTooLongError(error)) {
+    return { recovered: false, messages, reason: 'not a prompt-too-long error' };
+  }
+
+  // 电路已熔断：连续失败达上限，拒绝继续
+  if (state.consecutiveFailures >= MAX_CONSECUTIVE_REACTIVE_FAILURES) {
+    return {
+      recovered: false,
+      messages,
+      reason: '反应式压缩已熔断（连续失败达上限）——请 /new 或手动 /compact',
+    };
+  }
+
+  // Step 1: 先试 LLM 全量压缩
+  try {
+    const compact = dependencies.forceCompact ?? forceCompact;
+    const r = await compact(messages, provider, signal, undefined, promptCache);
+    // 救活成功 → 清零计数，让后续继续可用
+    state.consecutiveFailures = 0;
+    return {
+      recovered: true,
+      messages: r.messages,
+      reason: r.mode === 'snip-fallback'
+        ? `LLM 摘要失败后 snip 兜底成功（${r.before} → ${r.after} tokens）`
+        : `LLM 压缩成功（${r.before} → ${r.after} tokens）`,
+      before: r.before,
+      after: r.after,
+      mode: r.mode ?? 'llm-summary',
+      degraded: r.degraded ?? false,
+      ...(r.fallbackReason ? { fallbackReason: r.fallbackReason } : {}),
+      ...(r.messagesRemoved !== undefined ? { messagesRemoved: r.messagesRemoved } : {}),
+      ...(r.tokensFreed !== undefined ? { tokensFreed: r.tokensFreed } : {}),
+    };
+  } catch (error) {
+    if (signal?.aborted || (error as Error).name === 'AbortError') throw error;
+    // 压缩失败 → 走 snip 兜底
+  }
+
+  // Step 2: snip 兜底（更激进 40%）
+  const beforeSnip = countMessagesTokens(messages);
+  const snipped = snipCompactIfNeeded(messages, { force: true, snipPercent: 0.4 });
+  if (snipped.messagesRemoved > 0) {
+    // snip 也算救活 → 清零计数
+    state.consecutiveFailures = 0;
+    const afterSnip = countMessagesTokens(snipped.messages);
+    return {
+      recovered: true,
+      messages: snipped.messages,
+      reason: `snip 兜底成功（删除 ${snipped.messagesRemoved} 条最老消息，释放 ~${snipped.tokensFreed} tokens）`,
+      before: beforeSnip,
+      after: afterSnip,
+      mode: 'snip-fallback',
+      degraded: true,
+      fallbackReason: 'llm-error',
+      messagesRemoved: snipped.messagesRemoved,
+      tokensFreed: snipped.tokensFreed,
+    };
+  }
+
+  // 两步都没救活 → 失败计数 +1
+  state.consecutiveFailures++;
+  return {
+    recovered: false,
+    messages,
+    reason: '反应式压缩失败：LLM 压缩抛错且 snip 也没东西可砍',
+  };
+}

package/src/context/recentDirs.ts

@@ -0,0 +1,42 @@
+/** Compatibility facade over the authoritative Workspace Index. */
+import { workspaceIndexService } from './workspaceIndex.js';
+
+export interface RecentDirEntry {
+  path: string;
+  name: string;
+  lastUsedAt: number;
+  title?: string;
+  /** Legacy v1 hint. It is never used as an existence check. */
+  sessionFile?: string;
+  available?: boolean;
+  workspaceId?: string;
+}
+
+function asRecent(workspace: Awaited<ReturnType<typeof workspaceIndexService.list>>[number]): RecentDirEntry {
+  const latest = [...workspace.sessions].sort((a, b) => b.updatedAt - a.updatedAt)[0];
+  return {
+    path: workspace.displayPath,
+    name: workspace.displayName,
+    lastUsedAt: workspace.lastActiveAt,
+    ...(latest?.title ? { title: latest.title } : {}),
+    available: workspace.available,
+    workspaceId: workspace.id,
+  };
+}
+
+export async function listRecentDirs(): Promise<RecentDirEntry[]> {
+  return (await workspaceIndexService.list()).map(asRecent);
+}
+
+export async function upsertRecentDir(cwd: string, title?: string): Promise<RecentDirEntry> {
+  return asRecent(await workspaceIndexService.register(cwd, title));
+}
+
+/** Best-effort CLI hook: index failure must not fail an Agent turn. */
+export async function recordRecentDir(cwd: string, title?: string): Promise<void> {
+  await workspaceIndexService.register(cwd, title).then(() => undefined, () => undefined);
+}
+
+export async function removeRecentDir(cwd: string): Promise<void> {
+  await workspaceIndexService.removeWorkspace(cwd);
+}