minimal-agent 0.8.2 → 0.10.0

package/src/context/contextLock.js

@@ -0,0 +1,81 @@
+import { mkdir, readFile, rm, stat, utimes, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+const RETRY_MS = 200;
+const STALE_MS = 2 * 60_000;
+function sleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        // acquireContextLock 每 200ms 重试一次都会调用 sleep；listener 必须在正常
+        // 到点后摘掉，否则长等待会在同一个 AbortSignal 上线性堆积 listener。
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(new Error('aborted while waiting for workspace context lock'));
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM = 进程存在但不属于当前用户 → 算活（与 sessionRegistry/configFile 的
+        // processIsAlive 语义对齐）；判死会在共享机器上误抢别的用户的活锁。
+        return e.code === 'EPERM';
+    }
+}
+async function stale(lockDir) {
+    try {
+        const info = await stat(lockDir);
+        if (Date.now() - info.mtimeMs <= STALE_MS)
+            return false;
+        const raw = JSON.parse(await readFile(`${lockDir}/owner.json`, 'utf8'));
+        return typeof raw.pid !== 'number' || !pidAlive(raw.pid);
+    }
+    catch {
+        return true;
+    }
+}
+/**
+ * Cross-process exclusive lock for one canonical context file. A heartbeat keeps
+ * long agent turns from looking stale; dead processes are recovered by PID.
+ */
+export async function acquireContextLock(sessionFile, signal) {
+    const lockDir = `${sessionFile}.lock`;
+    // 父目录（~/.minimal-agent/sessions/）通常早已存在（任何一个 cwd 聊过一轮就会由
+    // saveContext 递归建出来）；只有全新 HOME 的第一次交互恰好落在这条锁路径上时才会
+    // 缺失。用普通 mkdir(lockDir)（不带 recursive）是刻意的——EEXIST 是这把互斥锁的
+    // 判活信号（下面 catch 靠它识别"别人正持锁"），recursive:true 会让已存在的锁目录
+    // 也悄悄"创建成功"、互斥失效。故只把父目录单独递归建好，叶子目录仍走非 recursive
+    // 的 mkdir 以保留 EEXIST 语义。
+    while (true) {
+        signal?.throwIfAborted();
+        try {
+            await mkdir(dirname(lockDir), { recursive: true });
+            await mkdir(lockDir);
+            await writeFile(`${lockDir}/owner.json`, JSON.stringify({ pid: process.pid, startedAt: Date.now() }), 'utf8');
+            const heartbeat = setInterval(() => {
+                const now = new Date();
+                void utimes(lockDir, now, now).catch(() => { });
+            }, 30_000);
+            return async () => {
+                clearInterval(heartbeat);
+                await rm(lockDir, { recursive: true, force: true });
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== 'EEXIST')
+                throw error;
+            if (await stale(lockDir)) {
+                await rm(lockDir, { recursive: true, force: true });
+                continue;
+            }
+            await sleep(RETRY_MS, signal);
+        }
+    }
+}

package/src/context/persistContext.js

@@ -1,14 +1,20 @@
 /**
  * ============================================================
- *  src/context/persistContext.ts —— 单上下文持久化（无会话管理）
+ *  src/context/persistContext.ts —— 单个会话文件的持久化读写
  * ------------------------------------------------------------
  *  做的事：
- *    把"上一次关闭时的对话历史"落盘到一个固定文件。下次启动（TUI 或 -p）
- *    自动加载，等于无缝续上。整个项目就一个上下文，不存在 session id /
- *    list / resume 之类的概念。
+ *    把"上一次关闭时的对话历史"落盘到一个文件。下次启动（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/<目录哈希>.json
+ *    ~/.minimal-agent/sessions/<目录哈希>[--<sessionId>].json
  *    （按当前工作目录隔离；可用 MINIMAL_AGENT_CONTEXT_FILE 覆盖，给测试用）
  *
  *  存储格式：
@@ -17,12 +23,13 @@
  *  抉择：
  *    - load 出来若为空或损坏 → 当作"没历史"返回 null，调用方 fallback 到
  *      只含 system prompt 的 fresh history。永不抛错。
- *    - save 直接覆写整个文件，不做 atomic（教学项目可接受；进程崩溃丢的
- *      就是当前这一轮）。
+ *    - save 使用唯一临时文件 + atomic rename，避免崩溃留下半截 JSON；
+ *      同一 Session 的跨进程互斥由 contextLock 负责。
  *    - 不做 system prompt 替换：调用方拿到 messages 后想替/不替自己决定。
  * ============================================================
  */
-import { mkdir, readFile, readdir, rmdir, unlink, writeFile } from 'node:fs/promises';
+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 { archiveCurrent } from './archive.js';
@@ -74,14 +81,26 @@ export function filterEphemeralMessages(messages) {
  */
 export async function saveContext(messages, file) {
     const target = file ?? getContextPath();
+    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
     try {
         await mkdir(dirname(target), { recursive: true });
         const persistable = filterEphemeralMessages(messages);
         const data = { updatedAt: Date.now(), messages: persistable };
-        await writeFile(target, JSON.stringify(data), 'utf8');
+        await writeFile(temp, JSON.stringify(data), { encoding: 'utf8', mode: 0o600 });
+        await rename(temp, target);
     }
-    catch {
-        // 静默吞：持久化失败不该影响对话本身
+    catch (e) {
+        // 不抛（持久化失败不该影响对话本身），但要出声——磁盘满/权限问题时
+        // 用户整段会话会静默丢失；与 clearContext 的 archive 失败处理风格对齐。
+        try {
+            process.stderr.write(`[minimal-agent] 会话落盘失败（本轮继续）：${e.message}\n`);
+        }
+        catch {
+            /* stderr 不可用也不阻断 */
+        }
+    }
+    finally {
+        await unlink(temp).catch(() => { });
     }
 }
 /**

package/src/context/reactiveCompact.js

@@ -87,8 +87,9 @@ function errorMessage(error) {
  * @param provider 当前 provider（用于 LLM 压缩）
  * @param error    刚刚抛出的错误
  * @param state    可选的独立状态（默认使用进程级单例）
+ * @param signal   用户中断信号（透传给内部的 forceCompact → chat()，让"压缩中"这个阶段也能响应 ESC/Ctrl+C）
  */
-export async function reactiveCompactIfApplicable(messages, provider, error, state = defaultState) {
+export async function reactiveCompactIfApplicable(messages, provider, error, state = defaultState, signal, dependencies = {}) {
     // 非 prompt_too_long 错误：直接短路，不消耗计数
     if (!isPromptTooLongError(error)) {
         return { recovered: false, messages, reason: 'not a prompt-too-long error' };
@@ -103,7 +104,8 @@ export async function reactiveCompactIfApplicable(messages, provider, error, sta
     }
     // Step 1: 先试 LLM 全量压缩
     try {
-        const r = await forceCompact(messages, provider);
+        const compact = dependencies.forceCompact ?? forceCompact;
+        const r = await compact(messages, provider, signal);
         // 救活成功 → 清零计数，让后续继续可用
         state.consecutiveFailures = 0;
         return {

package/src/context/recentDirs.js

@@ -1,66 +1,26 @@
-/**
- * ============================================================
- *  src/context/recentDirs.ts —— 最近工作目录注册表（Web 侧栏用）
- * ------------------------------------------------------------
- *  做的事：
- *    维护 ~/.minimal-agent/recent-dirs.json —— 一个"用过哪些工作目录"的列表。
- *    每个工作目录 = 一个会话（项目"一 cwd 一 session"约束），Web 前端侧栏据此
- *    列出会话；每条记录顺带存该目录的会话文件路径，让前端不必复刻哈希命名规则
- *    即可定位历史。
- *
- *  谁写：stream-json 模式每轮开始时 recordRecentDir(cwd, 首条用户消息)。
- *  谁读：webchat 服务端直接 JSON.parse 本文件（不 import 后端业务模块）。
- *
- *  抉择：读失败返回 []；写失败静默 —— 注册表只是 UI 便利，绝不该影响对话本身。
- * ============================================================
- */
-import { mkdir, readFile, writeFile } from 'node:fs/promises';
-import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
-import { sessionFileFor } from './sessionPath.js';
-/** 注册表上限：只留最近 N 个，防文件无限增长。 */
-const MAX_ENTRIES = 50;
-function registryPath() {
-    return join(homedir(), '.minimal-agent', 'recent-dirs.json');
+/** Compatibility facade over the authoritative Workspace Index. */
+import { workspaceIndexService } from './workspaceIndex.js';
+function asRecent(workspace) {
+    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() {
-    try {
-        const raw = await readFile(registryPath(), 'utf8');
-        const data = JSON.parse(raw);
-        if (!Array.isArray(data))
-            return [];
-        return data
-            .filter((e) => e && typeof e.path === 'string' && typeof e.sessionFile === 'string')
-            .sort((a, b) => b.lastUsedAt - a.lastUsedAt);
-    }
-    catch {
-        return [];
-    }
+    return (await workspaceIndexService.list()).map(asRecent);
 }
-/**
- * 记录/更新一个工作目录。upsert by path：已存在则更新 lastUsedAt（title 给了才覆盖，
- * 否则保留旧 title），不存在则插入。写失败静默。
- */
+export async function upsertRecentDir(cwd, title) {
+    return asRecent(await workspaceIndexService.register(cwd, title));
+}
+/** Best-effort CLI hook: index failure must not fail an Agent turn. */
 export async function recordRecentDir(cwd, title) {
-    try {
-        const abs = resolve(cwd);
-        const list = await listRecentDirs();
-        const prev = list.find((e) => e.path === abs);
-        const rest = list.filter((e) => e.path !== abs);
-        const entry = {
-            path: abs,
-            name: basename(abs) || abs,
-            lastUsedAt: Date.now(),
-            title: title ? title.slice(0, 80) : prev?.title,
-            sessionFile: sessionFileFor(abs),
-        };
-        const next = [entry, ...rest].slice(0, MAX_ENTRIES);
-        const file = registryPath();
-        await mkdir(dirname(file), { recursive: true });
-        await writeFile(file, JSON.stringify(next, null, 2), 'utf8');
-    }
-    catch {
-        // 静默：注册失败不影响对话
-    }
+    await workspaceIndexService.register(cwd, title).then(() => undefined, () => undefined);
+}
+export async function removeRecentDir(cwd) {
+    await workspaceIndexService.removeWorkspace(cwd);
 }

package/src/context/sessionPath.js

@@ -3,19 +3,18 @@
  *  src/context/sessionPath.ts —— 按目录隔离的会话文件路径
  * ------------------------------------------------------------
  *  做的事：
- *    把当前工作目录编码为 ~/.minimal-agent/sessions/<encoded>.json
- *    的文件名，让不同项目目录的对话历史互不覆盖。
+ *    新会话使用 Workspace Index 的稳定 workspaceId，写入
+ *    ~/.minimal-agent/sessions/workspace-<id>--<sessionId>.json。
+ *    因此外接盘挂载名、盘符或 symlink 表达变化时仍指向同一份历史。
  *
- *  命名规则（v2 加 sessionId 后）：
+ *  旧命名规则（路径索引时代，仍用于兼容迁移）：
  *    <sanitized-path>-<6-hex-hash>--<sessionId>.json
  *      sanitized：路径归一化后只保留 [a-z0-9-]，最长 80 字符
  *      hash    ：原始路径 sha1 前 6 位，防 sanitize 后碰撞
  *      sessionId：v2 多 session 支持；默认 'default'
  *
- *    向后兼容：sessionId='default' 时，新文件名 `<sanitized>-<hash>--default.json`
- *    与旧文件名 `<sanitized>-<hash>.json` 都可能存在。resolveSessionFile()
- *    优先返新路径，新路径不存在但旧路径存在时回退到旧路径，保证老用户的
- *    last-context 无缝继承。
+ *    resolveSessionFile() 会验证当前路径及 Workspace Index 中的历史别名，
+ *    首次打开旧文件时复制到稳定文件名；旧文件保留作为恢复依据。
  *
  *  迁移：
  *    旧版 ~/.minimal-agent/last-context.json 启动时一次性 rename 到
@@ -23,10 +22,64 @@
  * ============================================================
  */
 import { createHash } from 'node:crypto';
-import { mkdir, rename, stat } from 'node:fs/promises';
-import { homedir } from 'node:os';
+import { constants, readFileSync, realpathSync } from 'node:fs';
+import { chmod, copyFile, mkdir, rename, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
+import { agentStateDir } from './agentHome.js';
 const DEFAULT_SESSION_ID = 'default';
+const SESSION_ID_RE = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,79}$/;
+function comparablePath(path) {
+    try {
+        return realpathSync(resolve(path)).replace(/\\/g, '/').toLowerCase();
+    }
+    catch {
+        return resolve(path).replace(/\\/g, '/').toLowerCase();
+    }
+}
+function mountStablePath(path) {
+    return comparablePath(path).replace(/^\/volumes\/([^/]+?) \d+(\/|$)/, '/volumes/$1$2');
+}
+function indexedWorkspaceFor(cwd) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(agentStateDir(), 'workspace-index.json'), 'utf8'));
+        const target = comparablePath(cwd);
+        const mountTarget = mountStablePath(cwd);
+        return parsed.workspaces?.find((workspace) => [
+            workspace.canonicalPath,
+            workspace.displayPath,
+            ...(workspace.pathAliases ?? []),
+        ].some((path) => typeof path === 'string'
+            && (comparablePath(path) === target || mountStablePath(path) === mountTarget))) ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function stableSessionFileFor(workspaceId, sessionId) {
+    const safeWorkspaceId = workspaceId.replace(/[^a-zA-Z0-9._-]/g, '');
+    if (!safeWorkspaceId)
+        throw new Error('workspace id 无效');
+    return join(agentStateDir(), 'sessions', `workspace-${safeWorkspaceId}--${validateSessionId(sessionId)}.json`);
+}
+/** 仅用于旧历史识别和迁移；新调用应使用 sessionFileFor。 */
+export function legacyPathSessionFileFor(cwd, sessionId = DEFAULT_SESSION_ID) {
+    const safeSessionId = validateSessionId(sessionId);
+    const normalized = resolve(cwd).replace(/\\/g, '/').toLowerCase();
+    const sanitized = normalized
+        .replace(/:/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 80);
+    const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
+    return join(agentStateDir(), 'sessions', `${sanitized}-${hash}--${safeSessionId}.json`);
+}
+export function validateSessionId(sessionId) {
+    const value = sessionId.trim();
+    if (!SESSION_ID_RE.test(value) || value === '.' || value === '..' || value.includes('..')) {
+        throw new Error('session id 只能包含字母、数字、点、下划线和短横线，且长度不超过 80');
+    }
+    return value;
+}
 /**
  * 把 cwd + sessionId 编码成会话文件绝对路径。
  *
@@ -38,14 +91,11 @@ const DEFAULT_SESSION_ID = 'default';
  * 拿到实际存在的路径用于 load。
  */
 export function sessionFileFor(cwd, sessionId = DEFAULT_SESSION_ID) {
-    const normalized = resolve(cwd).replace(/\\/g, '/').toLowerCase();
-    const sanitized = normalized
-        .replace(/:/g, '')
-        .replace(/[^a-z0-9]+/g, '-')
-        .replace(/^-+|-+$/g, '')
-        .slice(0, 80);
-    const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
-    return join(homedir(), '.minimal-agent', 'sessions', `${sanitized}-${hash}--${sessionId}.json`);
+    const safeSessionId = validateSessionId(sessionId);
+    const workspace = indexedWorkspaceFor(cwd);
+    return workspace
+        ? stableSessionFileFor(workspace.id, safeSessionId)
+        : legacyPathSessionFileFor(cwd, safeSessionId);
 }
 /** 旧格式（v1，不带 `--<id>` 后缀）—— 仅 'default' session 可能存在 */
 function legacySessionFileFor(cwd) {
@@ -56,7 +106,7 @@ function legacySessionFileFor(cwd) {
         .replace(/^-+|-+$/g, '')
         .slice(0, 80);
     const hash = createHash('sha1').update(normalized).digest('hex').slice(0, 6);
-    return join(homedir(), '.minimal-agent', 'sessions', `${sanitized}-${hash}.json`);
+    return join(agentStateDir(), 'sessions', `${sanitized}-${hash}.json`);
 }
 /**
  * 解析 cwd + sessionId 对应的实际存在的会话文件路径。
@@ -74,15 +124,39 @@ export async function resolveSessionFile(cwd, sessionId = DEFAULT_SESSION_ID) {
     catch {
         // 新路径不存在
     }
-    if (sessionId === DEFAULT_SESSION_ID) {
-        const legacy = legacySessionFileFor(cwd);
+    const workspace = indexedWorkspaceFor(cwd);
+    const aliases = workspace
+        ? [cwd, workspace.canonicalPath, workspace.displayPath, ...(workspace.pathAliases ?? [])]
+        : [cwd];
+    const candidates = [...new Set(aliases.filter((value) => typeof value === 'string'))]
+        .flatMap((path) => [
+        legacyPathSessionFileFor(path, sessionId),
+        ...(sessionId === DEFAULT_SESSION_ID ? [legacySessionFileFor(path)] : []),
+    ]);
+    for (const legacy of candidates) {
         try {
             await stat(legacy);
-            return legacy;
         }
         catch {
-            // 旧路径也不存在
+            continue;
+        }
+        if (legacy !== fresh && workspace) {
+            try {
+                await mkdir(dirname(fresh), { recursive: true });
+                await copyFile(legacy, fresh, constants.COPYFILE_EXCL).catch(async (error) => {
+                    if (error.code !== 'EEXIST')
+                        throw error;
+                });
+                await chmod(fresh, 0o600).catch(() => { });
+                return fresh;
+            }
+            catch {
+                // Migration is an optimization. The verified legacy history remains
+                // authoritative when the stable destination cannot be written.
+                return legacy;
+            }
         }
+        return legacy;
     }
     return fresh;
 }
@@ -95,7 +169,7 @@ export async function resolveSessionFile(cwd, sessionId = DEFAULT_SESSION_ID) {
  *  - rename 失败（目标已存在 / 权限等）→ 忽略，旧文件原位等下次启动
  */
 export async function migrateLegacyContext(cwd) {
-    const legacy = join(homedir(), '.minimal-agent', 'last-context.json');
+    const legacy = join(agentStateDir(), 'last-context.json');
     try {
         await stat(legacy);
     }