minimal-agent 0.10.0 → 0.12.0

package/src/tools/shared/fileActivity.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+const MIME_BY_EXT = {
+    '.csv': 'text/csv',
+    '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.html': 'text/html',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.json': 'application/json',
+    '.md': 'text/markdown',
+    '.pdf': 'application/pdf',
+    '.png': 'image/png',
+    '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.txt': 'text/plain',
+    '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
+function within(root, candidate) {
+    const rel = relative(root, candidate);
+    if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return rel === '' ? '' : null;
+    return rel.split(sep).join('/');
+}
+export async function fileActivityMetadata(filePath, activity, verification = 'not_run', purpose = activity === 'read' ? 'source' : 'support', cwd = getWorkingDir(), patch) {
+    const lexicalRoot = resolve(cwd);
+    const root = await realpath(lexicalRoot).catch(() => lexicalRoot);
+    const candidate = await realpath(filePath).catch(() => resolve(filePath));
+    const relativePath = within(root, candidate);
+    if (!relativePath)
+        return undefined;
+    let sha256;
+    if (activity !== 'deleted') {
+        try {
+            sha256 = createHash('sha256').update(await readFile(candidate)).digest('hex');
+        }
+        catch { /* The file activity remains useful even when hashing fails. */ }
+    }
+    return {
+        kind: 'file_activity',
+        files: [{
+                relativePath,
+                activity,
+                ...(sha256 ? { sha256 } : {}),
+                ...(MIME_BY_EXT[extname(relativePath).toLowerCase()] ? { mime: MIME_BY_EXT[extname(relativePath).toLowerCase()] } : {}),
+                verification,
+                purpose,
+                ...(patch ? { patch } : {}),
+            }],
+    };
+}

package/src/tools/shared/fileActivity.ts

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import { readFile, realpath } from 'node:fs/promises';
+import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
+
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import type {
+  ConversationFilePurpose,
+  FileActivityKind,
+  FileActivityMetadata,
+  FileVerification,
+  FilePatchSummary,
+} from '../../types.js';
+
+const MIME_BY_EXT: Record<string, string> = {
+  '.csv': 'text/csv',
+  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+  '.html': 'text/html',
+  '.jpeg': 'image/jpeg',
+  '.jpg': 'image/jpeg',
+  '.json': 'application/json',
+  '.md': 'text/markdown',
+  '.pdf': 'application/pdf',
+  '.png': 'image/png',
+  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+  '.txt': 'text/plain',
+  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+};
+
+function within(root: string, candidate: string): string | null {
+  const rel = relative(root, candidate);
+  if (!rel || rel === '..' || rel.startsWith(`..${sep}`) || isAbsolute(rel)) return rel === '' ? '' : null;
+  return rel.split(sep).join('/');
+}
+
+export async function fileActivityMetadata(
+  filePath: string,
+  activity: FileActivityKind,
+  verification: FileVerification = 'not_run',
+  purpose: ConversationFilePurpose = activity === 'read' ? 'source' : 'support',
+  cwd = getWorkingDir(),
+  patch?: FilePatchSummary,
+): Promise<FileActivityMetadata | undefined> {
+  const lexicalRoot = resolve(cwd);
+  const root = await realpath(lexicalRoot).catch(() => lexicalRoot);
+  const candidate = await realpath(filePath).catch(() => resolve(filePath));
+  const relativePath = within(root, candidate);
+  if (!relativePath) return undefined;
+
+  let sha256: string | undefined;
+  if (activity !== 'deleted') {
+    try { sha256 = createHash('sha256').update(await readFile(candidate)).digest('hex'); }
+    catch { /* The file activity remains useful even when hashing fails. */ }
+  }
+  return {
+    kind: 'file_activity',
+    files: [{
+      relativePath,
+      activity,
+      ...(sha256 ? { sha256 } : {}),
+      ...(MIME_BY_EXT[extname(relativePath).toLowerCase()] ? { mime: MIME_BY_EXT[extname(relativePath).toLowerCase()] } : {}),
+      verification,
+      purpose,
+      ...(patch ? { patch } : {}),
+    }],
+  };
+}

package/src/tools/shared/fileMutationBus.js

@@ -0,0 +1,13 @@
+const listeners = new Set();
+export function onFileMutation(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+export function emitFileMutation(absolutePath) {
+    for (const listener of listeners) {
+        try {
+            listener(absolutePath);
+        }
+        catch { }
+    }
+}

package/src/tools/shared/fileMutationBus.ts

@@ -0,0 +1,14 @@
+export type FileMutationListener = (absolutePath: string) => void;
+
+const listeners = new Set<FileMutationListener>();
+
+export function onFileMutation(listener: FileMutationListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function emitFileMutation(absolutePath: string): void {
+  for (const listener of listeners) {
+    try { listener(absolutePath); } catch {}
+  }
+}

package/src/tools/shared/fileState.js

@@ -1,94 +1,102 @@
-/**
- * ============================================================
- *  src/tools/shared/fileState.ts —— Pre-read Guard 状态表
- * ------------------------------------------------------------
- *  对应上游 D:\code\kakadeai\utils\fileStateCache.ts:4-14
- *  + D:\code\kakadeai\tools\FileWriteTool\FileWriteTool.ts:198-219 的"先读后写"约束。
- *
- *  纯 module-level Map，记录每个文件最近一次被 Read 时的 (mtime, size)。
- *  Write/Edit 在落盘前调用 assertFresh：
- *    1. 没有记录 + 文件已存在 → 报错"请先 Read"
- *    2. 没有记录 + 文件不存在 → 放行（新建场景）
- *    3. 当前 mtime > 记录的 mtime → 报错"文件被外部修改"
- *
- *  /new 调用 clearContext 时连带调 clearFileState() 防残留。
- *
- *  v2 增量（防"读后空转"）：recordRead 额外记录最近一次读取的 (offset, limit)
- *  与"同区连续重读次数"，并返回该次数。Read 工具据此在"同一区间 + 文件未变 +
- *  第二次起"时给模型一行"别重复读、直接用已读内容"的提示（仅提示，不拦截）。
- *  文件一旦被 Edit/Write 或外部改动（mtime 漂移），重读即合法、计数归 1。
- * ============================================================
- */
-import { existsSync, statSync } from 'node:fs';
-const fileState = new Map();
-/**
- * 记录一次 Read，返回本次是"同区重读"的第几次（首次=1）。
- *
- * "同区重读" = 文件 mtime 未漂移（内容没变） + 这次 (offset,limit) 与上次完全相同。
- * 调用方（Read 工具）据返回值 >= 2 判定模型在空转、给提示。
- * 文件被 Edit/Write 或外部改动（mtime 漂移）即视为合法重读，计数归 1、不提示。
- */
-export function recordRead(absPath, opts) {
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+export function createFileReadState() {
+    return { entries: new Map() };
+}
+const defaultState = createFileReadState();
+export function hashFileBytes(bytes) {
+    return createHash('sha256').update(bytes).digest('hex');
+}
+export function recordRead(absPath, opts, state = defaultState) {
     try {
         const st = statSync(absPath);
-        const prev = fileState.get(absPath);
-        const sameRegionUnchanged = prev !== undefined &&
-            st.mtimeMs <= prev.timestamp &&
-            prev.offset === opts?.offset &&
-            prev.limit === opts?.limit;
+        const prev = state.entries.get(absPath);
+        const sameRegionUnchanged = prev !== undefined
+            && st.mtimeMs === prev.timestamp
+            && st.size === prev.size
+            && prev.offset === opts?.offset
+            && prev.limit === opts?.limit;
         const reads = sameRegionUnchanged ? (prev.reads ?? 1) + 1 : 1;
-        fileState.set(absPath, {
+        state.entries.set(absPath, {
             timestamp: st.mtimeMs,
             size: st.size,
             truncated: opts?.truncated ?? false,
+            partial: opts?.partial ?? false,
             offset: opts?.offset,
             limit: opts?.limit,
             reads,
+            ...(opts?.contentHash ? { contentHash: opts.contentHash } : {}),
         });
         return reads;
     }
     catch {
-        // 文件不存在或无权访问 —— 不记录，让 Read 自己处理错误
         return 1;
     }
 }
-/** 查询上次 Read 是否被截断。供 Edit/MultiEdit 给出更精准 error hint、Write 做 hard guard 用。 */
-export function wasTruncated(absPath) {
-    return fileState.get(absPath)?.truncated ?? false;
+export function wasTruncated(absPath, state = defaultState) {
+    return state.entries.get(absPath)?.truncated ?? false;
+}
+export function wasPartial(absPath, state = defaultState) {
+    const entry = state.entries.get(absPath);
+    return entry?.partial === true || entry?.truncated === true;
 }
-export function assertFresh(absPath) {
-    const entry = fileState.get(absPath);
+/**
+ * Verify that the file still matches the session's read evidence. Metadata is
+ * the fast path; a complete-read hash suppresses false conflicts caused by
+ * antivirus/cloud-sync timestamp touches.
+ */
+export function assertFresh(absPath, options = {}, state = defaultState) {
+    const entry = state.entries.get(absPath);
     if (!entry) {
-        if (existsSync(absPath)) {
-            return {
+        return existsSync(absPath)
+            ? {
                 ok: false,
                 reason: 'never-read',
-                error: `文件 ${absPath} 已存在但未在本会话 Read 过。请先用 Read 工具读取，确认内容后再修改。`,
-            };
-        }
-        // 文件不存在 → 新建场景，放行
-        return { ok: true };
+                error: `文件 ${absPath} 已存在但未在本会话 Read 过。请先读取最新内容后再修改。`,
+            }
+            : { ok: true };
+    }
+    if (options.requireComplete && (entry.partial || entry.truncated)) {
+        return {
+            ok: false,
+            reason: 'partial-read',
+            error: `${absPath} 上次 Read 只覆盖了部分内容或发生截断。整文件覆盖会丢失未读取范围；请从头到尾完整 Read，或改用 Edit 精确修改。`,
+        };
     }
+    let current;
     try {
-        const st = statSync(absPath);
-        if (st.mtimeMs > entry.timestamp) {
-            return {
-                ok: false,
-                reason: 'mtime-drift',
-                error: `${absPath} 在 Read 后被外部修改（mtime 漂移）。请重新用 Read 工具读取最新内容。`,
-            };
-        }
+        current = statSync(absPath);
     }
     catch {
-        // 记录存在但文件没了 —— 不阻拦，允许重新创建
         return { ok: true };
     }
-    return { ok: true };
+    if (current.mtimeMs === entry.timestamp && current.size === entry.size)
+        return { ok: true };
+    if (entry.contentHash && !entry.partial && !entry.truncated) {
+        try {
+            const currentHash = hashFileBytes(readFileSync(absPath));
+            if (currentHash === entry.contentHash) {
+                state.entries.set(absPath, {
+                    ...entry,
+                    timestamp: current.mtimeMs,
+                    size: current.size,
+                });
+                return { ok: true };
+            }
+        }
+        catch {
+            // Fall through to a precise conflict result.
+        }
+    }
+    return {
+        ok: false,
+        reason: 'content-drift',
+        error: `${absPath} 在 Read 后发生了外部修改或内容变化。请重新读取最新内容后再修改。`,
+    };
 }
-export function clearFileState() {
-    fileState.clear();
+export function clearFileState(state = defaultState) {
+    state.entries.clear();
 }
-// 测试辅助：只在测试里用，业务代码不要碰
-export function _getFileStateSize() {
-    return fileState.size;
+export function _getFileStateSize(state = defaultState) {
+    return state.entries.size;
 }

package/src/tools/shared/fileState.ts

@@ -0,0 +1,145 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
+
+export interface FileStateEntry {
+  timestamp: number;
+  size: number;
+  truncated: boolean;
+  partial: boolean;
+  offset?: number;
+  limit?: number;
+  reads?: number;
+  /** SHA-256 is recorded only for a complete read. */
+  contentHash?: string;
+}
+
+export interface FileReadState {
+  entries: Map<string, FileStateEntry>;
+}
+
+export function createFileReadState(): FileReadState {
+  return { entries: new Map() };
+}
+
+const defaultState = createFileReadState();
+
+export function hashFileBytes(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export function recordRead(
+  absPath: string,
+  opts?: {
+    truncated?: boolean;
+    partial?: boolean;
+    offset?: number;
+    limit?: number;
+    contentHash?: string;
+  },
+  state: FileReadState = defaultState,
+): number {
+  try {
+    const st = statSync(absPath);
+    const prev = state.entries.get(absPath);
+    const sameRegionUnchanged = prev !== undefined
+      && st.mtimeMs === prev.timestamp
+      && st.size === prev.size
+      && prev.offset === opts?.offset
+      && prev.limit === opts?.limit;
+    const reads = sameRegionUnchanged ? (prev.reads ?? 1) + 1 : 1;
+    state.entries.set(absPath, {
+      timestamp: st.mtimeMs,
+      size: st.size,
+      truncated: opts?.truncated ?? false,
+      partial: opts?.partial ?? false,
+      offset: opts?.offset,
+      limit: opts?.limit,
+      reads,
+      ...(opts?.contentHash ? { contentHash: opts.contentHash } : {}),
+    });
+    return reads;
+  } catch {
+    return 1;
+  }
+}
+
+export function wasTruncated(absPath: string, state: FileReadState = defaultState): boolean {
+  return state.entries.get(absPath)?.truncated ?? false;
+}
+
+export function wasPartial(absPath: string, state: FileReadState = defaultState): boolean {
+  const entry = state.entries.get(absPath);
+  return entry?.partial === true || entry?.truncated === true;
+}
+
+export type AssertFreshResult =
+  | { ok: true }
+  | { ok: false; reason: 'never-read' | 'partial-read' | 'content-drift'; error: string };
+
+/**
+ * Verify that the file still matches the session's read evidence. Metadata is
+ * the fast path; a complete-read hash suppresses false conflicts caused by
+ * antivirus/cloud-sync timestamp touches.
+ */
+export function assertFresh(
+  absPath: string,
+  options: { requireComplete?: boolean } = {},
+  state: FileReadState = defaultState,
+): AssertFreshResult {
+  const entry = state.entries.get(absPath);
+  if (!entry) {
+    return existsSync(absPath)
+      ? {
+          ok: false,
+          reason: 'never-read',
+          error: `文件 ${absPath} 已存在但未在本会话 Read 过。请先读取最新内容后再修改。`,
+        }
+      : { ok: true };
+  }
+
+  if (options.requireComplete && (entry.partial || entry.truncated)) {
+    return {
+      ok: false,
+      reason: 'partial-read',
+      error: `${absPath} 上次 Read 只覆盖了部分内容或发生截断。整文件覆盖会丢失未读取范围；请从头到尾完整 Read，或改用 Edit 精确修改。`,
+    };
+  }
+
+  let current;
+  try {
+    current = statSync(absPath);
+  } catch {
+    return { ok: true };
+  }
+  if (current.mtimeMs === entry.timestamp && current.size === entry.size) return { ok: true };
+
+  if (entry.contentHash && !entry.partial && !entry.truncated) {
+    try {
+      const currentHash = hashFileBytes(readFileSync(absPath));
+      if (currentHash === entry.contentHash) {
+        state.entries.set(absPath, {
+          ...entry,
+          timestamp: current.mtimeMs,
+          size: current.size,
+        });
+        return { ok: true };
+      }
+    } catch {
+      // Fall through to a precise conflict result.
+    }
+  }
+
+  return {
+    ok: false,
+    reason: 'content-drift',
+    error: `${absPath} 在 Read 后发生了外部修改或内容变化。请重新读取最新内容后再修改。`,
+  };
+}
+
+export function clearFileState(state: FileReadState = defaultState): void {
+  state.entries.clear();
+}
+
+export function _getFileStateSize(state: FileReadState = defaultState): number {
+  return state.entries.size;
+}

package/src/tools/shared/fileUtils.js

@@ -9,10 +9,11 @@
  *    4. 引号风格保留（弯引号 ↔ 直引号归一化）
  * ============================================================
  */
+import { randomUUID } from 'node:crypto';
 import { statSync } from 'node:fs';
-import { open, readFile } from 'node:fs/promises';
+import { chmod, mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
-import { extname, resolve } from 'node:path';
+import { dirname, extname, resolve } from 'node:path';
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
 // -------------------- 1. 设备文件路径拦截 --------------------
 const BLOCKED_DEVICE_PATHS = new Set([
@@ -77,8 +78,8 @@ function expandPath(p) {
  * 等价于 `validateAndResolvePath(rawPath, getWorkingDir())`。
  * 让 Read / Write / Edit / MultiEdit 不必各自 import getWorkingDir。
  */
-export function resolveToolPath(rawPath) {
-    return validateAndResolvePath(rawPath, getWorkingDir());
+export function resolveToolPath(rawPath, cwd = getWorkingDir()) {
+    return validateAndResolvePath(rawPath, cwd);
 }
 export function detectLineEndingsForString(content) {
     let crlfCount = 0;
@@ -190,6 +191,82 @@ export async function tryAutoSnapshot(filePath) {
         .join('\n');
     return { ok: true, snippet: numbered, truncated, totalLines };
 }
+/** Decode the text encodings that the editing tools can preserve losslessly. */
+export async function readTextFile(filePath) {
+    const bytes = await readFile(filePath);
+    let encoding = 'utf8';
+    let content;
+    if (bytes.length >= 2 && bytes[0] === 0xff && bytes[1] === 0xfe) {
+        encoding = 'utf16le';
+        content = bytes.subarray(2).toString('utf16le');
+    }
+    else if (bytes.length >= 3 && bytes[0] === 0xef && bytes[1] === 0xbb && bytes[2] === 0xbf) {
+        encoding = 'utf8-bom';
+        content = bytes.subarray(3).toString('utf8');
+    }
+    else {
+        content = bytes.toString('utf8');
+    }
+    return { content, encoding, lineEnding: detectLineEndingsForString(content), bytes };
+}
+export function encodeTextFile(content, encoding) {
+    if (encoding === 'utf16le') {
+        return Buffer.concat([Buffer.from([0xff, 0xfe]), Buffer.from(content, 'utf16le')]);
+    }
+    if (encoding === 'utf8-bom') {
+        return Buffer.concat([Buffer.from([0xef, 0xbb, 0xbf]), Buffer.from(content, 'utf8')]);
+    }
+    return Buffer.from(content, 'utf8');
+}
+/** Write beside the destination, fsync, then replace it. Same-directory temp files keep rename atomic. */
+export async function atomicWriteFile(filePath, data, encoding = 'utf8') {
+    const parent = dirname(filePath);
+    await mkdir(parent, { recursive: true });
+    const temp = resolve(parent, `.${randomUUID()}.minimal-agent.tmp`);
+    const backup = resolve(parent, `.${randomUUID()}.minimal-agent.bak`);
+    const bytes = typeof data === 'string' ? encodeTextFile(data, encoding) : Buffer.from(data);
+    const prior = await stat(filePath).catch(() => null);
+    const handle = await open(temp, 'wx', prior?.mode);
+    try {
+        await handle.writeFile(bytes);
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+    if (prior)
+        await chmod(temp, prior.mode).catch(() => { });
+    try {
+        await rename(temp, filePath);
+    }
+    catch (error) {
+        if (process.platform !== 'win32' || !prior) {
+            await rm(temp, { force: true }).catch(() => { });
+            throw error;
+        }
+        // Windows cannot always replace an open destination. Keep a rollback copy.
+        await rename(filePath, backup);
+        try {
+            await rename(temp, filePath);
+            await rm(backup, { force: true });
+        }
+        catch (replaceError) {
+            await rename(backup, filePath).catch(() => { });
+            await rm(temp, { force: true }).catch(() => { });
+            throw replaceError;
+        }
+    }
+    // Persist the directory entry as well as the file contents. Some platforms do
+    // not permit opening directories; durability is best-effort there.
+    const directory = await open(parent, 'r').catch(() => undefined);
+    if (directory) {
+        try {
+            await directory.sync();
+        }
+        catch { }
+        await directory.close().catch(() => { });
+    }
+}
 /**
  * 读文件前 3 字节，返回 BOM 类型。
  * - EF BB BF → utf8-bom