minimal-agent 0.18.9 → 0.18.11

package/src/tools/read/read.js

@@ -1,7 +1,6 @@
 import { createReadStream } from 'node:fs';
 import { open, readFile, stat, writeFile } from 'node:fs/promises';
 import { extname } from 'node:path';
-import { createInterface } from 'node:readline';
 import { runBoundedProcess } from '../../runtime/boundedProcess.js';
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -18,6 +17,8 @@ import { pruneRuntimeOutputs, sessionRuntimeDir, } from '../../session/runtimeSt
 import { detectImageMime, resolveLocalImage, } from '../../images/imageResolver.js';
 const inputSchema = z.object({
     file_path: filePathField('读取'),
+    column: z.number().int().positive().optional().describe('超长行续读：起始行内的 1-based UTF-16 字符位置；普通阅读省略。'),
+    max_chars: z.number().int().min(1000).max(1_000_000).optional().describe('期望正文字符预算，最多 100 万；Runtime 会按剩余上下文与并发读取预算收紧。'),
     offset: z
         .number()
         .int()
@@ -56,7 +57,6 @@ const IMAGE_EXTENSIONS = new Set([
 ]);
 const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
 const MAX_NOTEBOOK_BYTES = 32 * 1024 * 1024;
-const SMALL_TEXT_BYTES = 16 * 1024 * 1024;
 const description = `Reads local text files, images, and Jupyter notebooks.
 
 Usage:
@@ -114,7 +114,7 @@ function renderNotebook(raw, offset, limit) {
         partial: start > 0 || end < parsed.cells.length,
     };
 }
-async function readStreamedText(filePath, offset, limit, signal) {
+async function readStreamedText(filePath, offset, limit, signal, maxChars = DEFAULT_MAX_RESULT_SIZE_CHARS, column = 1) {
     const handle = await open(filePath, 'r');
     const prefix = Buffer.alloc(3);
     const { bytesRead } = await handle.read(prefix, 0, 3, 0);
@@ -132,31 +132,81 @@ async function readStreamedText(filePath, offset, limit, signal) {
                 ? 3
                 : 0,
     });
-    const rl = createInterface({ input: stream, crlfDelay: Infinity });
     const lines = [];
-    let line = 0;
+    let line = 1;
     let hasMore = false;
-    for await (const value of rl) {
-        line += 1;
-        if (line >= offset && lines.length < limit)
-            lines.push(`${line}\t${value}`);
-        else if (line >= offset + limit) {
+    let chars = 0;
+    let clippedLine;
+    let pending = '';
+    let skip = column - 1;
+    let sawData = false;
+    const append = (part, end) => {
+        if (line < offset) {
+            if (end)
+                line++;
+            return true;
+        }
+        if (line === offset && skip) {
+            const consumed = Math.min(skip, part.length);
+            part = part.slice(consumed);
+            skip -= consumed;
+        }
+        if (lines.length >= limit) {
             hasMore = true;
-            rl.close();
-            stream.destroy();
-            break;
+            return false;
+        }
+        const allowance = maxChars - chars - String(line).length - 1;
+        if (pending.length + part.length > allowance) {
+            if (!lines.length) {
+                const preview = (pending + part).slice(0, Math.max(0, allowance)).replace(/[\uD800-\uDBFF]$/, '');
+                lines.push(`${line}\t${preview}`);
+                clippedLine = line;
+            }
+            hasMore = true;
+            return false;
         }
+        pending += part;
+        if (end) {
+            const numbered = `${line}\t${pending.replace(/\r$/, '')}`;
+            lines.push(numbered);
+            chars += numbered.length + 1;
+            pending = '';
+            line++;
+        }
+        return true;
+    };
+    try {
+        outer: for await (const chunk of stream) {
+            sawData = true;
+            const text = String(chunk);
+            let start = 0;
+            for (let end = text.indexOf('\n'); end !== -1; end = text.indexOf('\n', start)) {
+                if (!append(text.slice(start, end), true))
+                    break outer;
+                start = end + 1;
+            }
+            if (start < text.length && !append(text.slice(start), false))
+                break;
+        }
+        if (!hasMore && sawData)
+            append('', true);
+    }
+    finally {
+        stream.destroy();
     }
     return {
         numbered: lines.join('\n'),
-        totalKnown: line,
+        totalKnown: hasMore ? line : sawData ? line - 1 : 0,
         selectedCount: lines.length,
         hasMore,
+        clippedLine,
     };
 }
-async function call(input, state, cwd, runtimeIdentity, signal) {
+async function call(input, state, cwd, runtimeIdentity, signal, maxChars = DEFAULT_MAX_RESULT_SIZE_CHARS) {
     if (signal?.aborted)
         return { ok: false, error: 'aborted' };
+    if (maxChars < 1000)
+        return { ok: false, error: '本批读取上下文预算已用完；请先处理已有结果或压缩上下文，再继续读取。' };
     const offset = input.offset ?? 1;
     const limit = input.limit ?? MAX_LINES_TO_READ;
     const resolved = resolveToolPath(input.file_path, cwd);
@@ -351,45 +401,39 @@ async function call(input, state, cwd, runtimeIdentity, signal) {
         let hasMore;
         let completeBytes;
         let totalUnits;
-        if (info.size <= SMALL_TEXT_BYTES) {
-            const snapshot = await readTextFile(filePath);
-            completeBytes = snapshot.bytes;
-            const all = snapshot.content.length === 0 ? [] : snapshot.content.split('\n');
-            const start = offset - 1;
-            const selected = all.slice(start, start + limit);
-            content = selected
-                .map((line, index) => `${start + index + 1}\t${line}`)
-                .join('\n');
-            totalLines = all.length;
-            selectedCount = selected.length;
-            hasMore = start + selected.length < all.length;
-            totalUnits = totalLines;
-        }
-        else {
-            const streamed = await readStreamedText(filePath, offset, limit, signal);
-            content = streamed.numbered;
-            totalLines = streamed.totalKnown;
-            selectedCount = streamed.selectedCount;
-            hasMore = streamed.hasMore;
-            // A streamed read only knows the complete total after consuming EOF.
-            totalUnits = hasMore ? undefined : totalLines;
-        }
+        let clippedLine;
+        const streamed = await readStreamedText(filePath, offset, limit, signal, maxChars, input.column);
+        content = streamed.numbered;
+        totalLines = streamed.totalKnown;
+        selectedCount = streamed.selectedCount;
+        hasMore = streamed.hasMore;
+        clippedLine = streamed.clippedLine;
+        totalUnits = hasMore ? undefined : totalLines;
+        if (!hasMore && offset === 1 && (input.column ?? 1) === 1)
+            completeBytes = await readFile(filePath, { signal });
+        const afterRead = await stat(filePath);
+        if (afterRead.mtimeMs !== info.mtimeMs || afterRead.size !== info.size || afterRead.ino !== info.ino)
+            return { ok: false, error: '读取期间文件发生变化，请重新读取；本次不登记读取覆盖范围。' };
         if (!content)
             content = totalLines === 0 ? '<file is empty>' : `<offset=${offset} 已超出文件末尾，共 ${totalLines} 行>`;
         let truncated = false;
-        if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
-            content = `${content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)}\n\n⚠️ 重要：Read 输出已截断；截断范围外仍有内容。请用较小 limit 重新读取本区间，避免跳过截断行；精确修改用 Edit/ApplyPatch，Write 覆盖要求完整读取（可分段覆盖全部范围）。`;
+        if (content.length > maxChars || clippedLine !== undefined) {
+            const nextColumn = (input.column ?? 1) + Math.max(0, content.length - String(offset).length - 1);
+            content = `${content.slice(0, maxChars)}\n\n⚠️ 重要：Read 输出已截断；截断范围外仍有内容。超长行请提高 max_chars 或使用流式处理，不能跳过未显示内容。`;
+            if (clippedLine !== undefined)
+                content += `\n继续读取 offset=${clippedLine} column=${nextColumn}`;
             truncated = true;
         }
-        const partial = offset !== 1 || hasMore;
+        const partial = offset !== 1 || hasMore || (input.column ?? 1) > 1;
         if (hasMore && !truncated)
-            content += `\n\n... (还有更多内容；继续使用 offset=${offset + limit})`;
+            content += `\n\n... (还有更多内容；继续使用 offset=${offset + selectedCount})`;
         const reads = recordRead(filePath, {
             offset,
+            column: input.column,
             limit,
             partial,
             truncated,
-            range: selectedCount > 0
+            range: selectedCount > 0 && (input.column ?? 1) === 1
                 ? {
                     start: offset,
                     end: offset + selectedCount - 1,
@@ -412,7 +456,7 @@ async function call(input, state, cwd, runtimeIdentity, signal) {
                 path: filePath,
                 unit: 'line',
                 // A truncated response does not establish coverage of its full range.
-                ...(!truncated && selectedCount > 0
+                ...(!truncated && selectedCount > 0 && (input.column ?? 1) === 1
                     ? { start: offset, end: offset + selectedCount - 1 }
                     : {}),
                 truncated,
@@ -544,8 +588,8 @@ export const readTool = {
     parameters: toToolParameters(inputSchema),
     isReadOnly: true,
     isConcurrencySafe: true,
-    maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+    maxResultSizeChars: 1_010_000,
     interruptBehavior: () => 'cancel',
-    call: (input, signal) => call(input, undefined, undefined, undefined, signal),
-    callWithContext: (input, signal, context) => call(input, context.sessionState?.fileReads, context.cwd, context, signal),
+    call: (input, signal) => call(input, undefined, undefined, undefined, signal, input.max_chars ?? DEFAULT_MAX_RESULT_SIZE_CHARS),
+    callWithContext: (input, signal, context) => call(input, context.sessionState?.fileReads, context.cwd, context, signal, context.reserveReadChars?.(input.max_chars) ?? input.max_chars ?? DEFAULT_MAX_RESULT_SIZE_CHARS),
 };

package/src/tools/read/read.ts

@@ -1,7 +1,6 @@
 import { createReadStream } from 'node:fs';
 import { open, readFile, stat, writeFile } from 'node:fs/promises';
 import { extname } from 'node:path';
-import { createInterface } from 'node:readline';
 import { runBoundedProcess } from '../../runtime/boundedProcess.js';
 import { mkdir } from 'node:fs/promises';
 import { join } from 'node:path';
@@ -41,6 +40,8 @@ import {
 
 const inputSchema = z.object({
   file_path: filePathField('读取'),
+  column: z.number().int().positive().optional().describe('超长行续读：起始行内的 1-based UTF-16 字符位置；普通阅读省略。'),
+  max_chars: z.number().int().min(1000).max(1_000_000).optional().describe('期望正文字符预算，最多 100 万；Runtime 会按剩余上下文与并发读取预算收紧。'),
   offset: z
     .number()
     .int()
@@ -83,7 +84,6 @@ const IMAGE_EXTENSIONS = new Set([
 ]);
 const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
 const MAX_NOTEBOOK_BYTES = 32 * 1024 * 1024;
-const SMALL_TEXT_BYTES = 16 * 1024 * 1024;
 
 const description = `Reads local text files, images, and Jupyter notebooks.
 
@@ -164,11 +164,14 @@ async function readStreamedText(
   offset: number,
   limit: number,
   signal?: AbortSignal,
+  maxChars = DEFAULT_MAX_RESULT_SIZE_CHARS,
+  column = 1,
 ): Promise<{
   numbered: string;
   totalKnown: number;
   selectedCount: number;
   hasMore: boolean;
+  clippedLine?: number;
 }> {
   const handle = await open(filePath, 'r');
   const prefix = Buffer.alloc(3);
@@ -187,25 +190,57 @@ async function readStreamedText(
         ? 3
         : 0,
   });
-  const rl = createInterface({ input: stream, crlfDelay: Infinity });
   const lines: string[] = [];
-  let line = 0;
+  let line = 1;
   let hasMore = false;
-  for await (const value of rl) {
-    line += 1;
-    if (line >= offset && lines.length < limit) lines.push(`${line}\t${value}`);
-    else if (line >= offset + limit) {
-      hasMore = true;
-      rl.close();
-      stream.destroy();
-      break;
+  let chars = 0;
+  let clippedLine: number | undefined;
+  let pending = '';
+  let skip = column - 1;
+  let sawData = false;
+  const append = (part: string, end: boolean): boolean => {
+    if (line < offset) { if (end) line++; return true; }
+    if (line === offset && skip) {
+      const consumed = Math.min(skip, part.length);
+      part = part.slice(consumed); skip -= consumed;
     }
-  }
+    if (lines.length >= limit) { hasMore = true; return false; }
+    const allowance = maxChars - chars - String(line).length - 1;
+    if (pending.length + part.length > allowance) {
+      if (!lines.length) {
+        const preview = (pending + part).slice(0, Math.max(0, allowance)).replace(/[\uD800-\uDBFF]$/, '');
+        lines.push(`${line}\t${preview}`);
+        clippedLine = line;
+      }
+      hasMore = true; return false;
+    }
+    pending += part;
+    if (end) {
+      const numbered = `${line}\t${pending.replace(/\r$/, '')}`;
+      lines.push(numbered); chars += numbered.length + 1;
+      pending = ''; line++;
+    }
+    return true;
+  };
+  try {
+    outer: for await (const chunk of stream) {
+      sawData = true;
+      const text = String(chunk);
+      let start = 0;
+      for (let end = text.indexOf('\n'); end !== -1; end = text.indexOf('\n', start)) {
+        if (!append(text.slice(start, end), true)) break outer;
+        start = end + 1;
+      }
+      if (start < text.length && !append(text.slice(start), false)) break;
+    }
+    if (!hasMore && sawData) append('', true);
+  } finally { stream.destroy(); }
   return {
     numbered: lines.join('\n'),
-    totalKnown: line,
+    totalKnown: hasMore ? line : sawData ? line - 1 : 0,
     selectedCount: lines.length,
     hasMore,
+    clippedLine,
   };
 }
 
@@ -215,8 +250,10 @@ async function call(
   cwd?: string,
   runtimeIdentity?: RuntimeIdentity,
   signal?: AbortSignal,
+  maxChars = DEFAULT_MAX_RESULT_SIZE_CHARS,
 ): Promise<ToolResult> {
   if (signal?.aborted) return { ok: false, error: 'aborted' };
+  if (maxChars < 1000) return { ok: false, error: '本批读取上下文预算已用完；请先处理已有结果或压缩上下文，再继续读取。' };
   const offset = input.offset ?? 1;
   const limit = input.limit ?? MAX_LINES_TO_READ;
   const resolved = resolveToolPath(input.file_path, cwd);
@@ -454,47 +491,40 @@ async function call(
     let hasMore: boolean;
     let completeBytes: Buffer | undefined;
     let totalUnits: number | undefined;
-    if (info.size <= SMALL_TEXT_BYTES) {
-      const snapshot = await readTextFile(filePath);
-      completeBytes = snapshot.bytes;
-      const all =
-        snapshot.content.length === 0 ? [] : snapshot.content.split('\n');
-      const start = offset - 1;
-      const selected = all.slice(start, start + limit);
-      content = selected
-        .map((line, index) => `${start + index + 1}\t${line}`)
-        .join('\n');
-      totalLines = all.length;
-      selectedCount = selected.length;
-      hasMore = start + selected.length < all.length;
-      totalUnits = totalLines;
-    } else {
-      const streamed = await readStreamedText(filePath, offset, limit, signal);
-      content = streamed.numbered;
-      totalLines = streamed.totalKnown;
-      selectedCount = streamed.selectedCount;
-      hasMore = streamed.hasMore;
-      // A streamed read only knows the complete total after consuming EOF.
-      totalUnits = hasMore ? undefined : totalLines;
-    }
+    let clippedLine: number | undefined;
+    const streamed = await readStreamedText(filePath, offset, limit, signal, maxChars, input.column);
+    content = streamed.numbered;
+    totalLines = streamed.totalKnown;
+    selectedCount = streamed.selectedCount;
+    hasMore = streamed.hasMore;
+    clippedLine = streamed.clippedLine;
+    totalUnits = hasMore ? undefined : totalLines;
+    if (!hasMore && offset === 1 && (input.column ?? 1) === 1)
+      completeBytes = await readFile(filePath, { signal });
+    const afterRead = await stat(filePath);
+    if (afterRead.mtimeMs !== info.mtimeMs || afterRead.size !== info.size || afterRead.ino !== info.ino)
+      return { ok: false, error: '读取期间文件发生变化，请重新读取；本次不登记读取覆盖范围。' };
     if (!content) content = totalLines === 0 ? '<file is empty>' : `<offset=${offset} 已超出文件末尾，共 ${totalLines} 行>`;
     let truncated = false;
-    if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
-      content = `${content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)}\n\n⚠️ 重要：Read 输出已截断；截断范围外仍有内容。请用较小 limit 重新读取本区间，避免跳过截断行；精确修改用 Edit/ApplyPatch，Write 覆盖要求完整读取（可分段覆盖全部范围）。`;
+    if (content.length > maxChars || clippedLine !== undefined) {
+      const nextColumn = (input.column ?? 1) + Math.max(0, content.length - String(offset).length - 1);
+      content = `${content.slice(0, maxChars)}\n\n⚠️ 重要：Read 输出已截断；截断范围外仍有内容。超长行请提高 max_chars 或使用流式处理，不能跳过未显示内容。`;
+      if (clippedLine !== undefined) content += `\n继续读取 offset=${clippedLine} column=${nextColumn}`;
       truncated = true;
     }
-    const partial = offset !== 1 || hasMore;
+    const partial = offset !== 1 || hasMore || (input.column ?? 1) > 1;
     if (hasMore && !truncated)
-      content += `\n\n... (还有更多内容；继续使用 offset=${offset + limit})`;
+      content += `\n\n... (还有更多内容；继续使用 offset=${offset + selectedCount})`;
     const reads = recordRead(
       filePath,
       {
         offset,
+        column: input.column,
         limit,
         partial,
         truncated,
         range:
-          selectedCount > 0
+          selectedCount > 0 && (input.column ?? 1) === 1
             ? {
                 start: offset,
                 end: offset + selectedCount - 1,
@@ -519,7 +549,7 @@ async function call(
         path: filePath,
         unit: 'line',
         // A truncated response does not establish coverage of its full range.
-        ...(!truncated && selectedCount > 0
+        ...(!truncated && selectedCount > 0 && (input.column ?? 1) === 1
           ? { start: offset, end: offset + selectedCount - 1 }
           : {}),
         truncated,
@@ -687,9 +717,10 @@ export const readTool: Tool<ReadInput> = {
   parameters: toToolParameters(inputSchema),
   isReadOnly: true,
   isConcurrencySafe: true,
-  maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
+  maxResultSizeChars: 1_010_000,
   interruptBehavior: () => 'cancel',
-  call: (input, signal) => call(input, undefined, undefined, undefined, signal),
+  call: (input, signal) => call(input, undefined, undefined, undefined, signal, input.max_chars ?? DEFAULT_MAX_RESULT_SIZE_CHARS),
   callWithContext: (input, signal, context: ToolCallContext) =>
-    call(input, context.sessionState?.fileReads, context.cwd, context, signal),
+    call(input, context.sessionState?.fileReads, context.cwd, context, signal,
+      context.reserveReadChars?.(input.max_chars) ?? input.max_chars ?? DEFAULT_MAX_RESULT_SIZE_CHARS),
 };

package/src/tools/shared/diffSummary.js

@@ -12,16 +12,38 @@ export function buildPatchSummary(before, after, label) {
     const totalBytes = Buffer.byteLength(before) + Buffer.byteLength(after);
     const totalLines = (before.match(/\n/g)?.length ?? 0) + (after.match(/\n/g)?.length ?? 0) + 2;
     if (totalBytes > MAX_BYTES || totalLines > MAX_LINES) {
+        // Strip identical outer lines before expensive diff work. A large file with
+        // a small edit still gets a real preview with original line coordinates.
+        let prefix = 0;
+        while (prefix < Math.min(before.length, after.length) && before[prefix] === after[prefix])
+            prefix++;
+        const start = before.lastIndexOf('\n', Math.max(0, prefix - 1)) + 1;
+        let suffix = 0;
+        while (suffix < Math.min(before.length, after.length) - start &&
+            before[before.length - suffix - 1] === after[after.length - suffix - 1])
+            suffix++;
+        const tail = before.indexOf('\n', before.length - suffix);
+        const suffixLength = tail < 0 ? 0 : before.length - tail - 1;
+        const oldWindow = before.slice(start, before.length - suffixLength);
+        const newWindow = after.slice(start, after.length - suffixLength);
+        if (Buffer.byteLength(oldWindow) + Buffer.byteLength(newWindow) <= MAX_BYTES &&
+            (oldWindow.match(/\n/g)?.length ?? 0) + (newWindow.match(/\n/g)?.length ?? 0) + 2 <= MAX_LINES) {
+            const local = buildPatchSummary(oldWindow, newWindow, label);
+            const shift = (before.slice(0, start).match(/\n/g)?.length ?? 0);
+            return { ...local, beforeHash, afterHash,
+                unifiedDiff: local.unifiedDiff?.replace(/@@ -(\d+)(,\d+)? \+(\d+)(,\d+)? @@/g, (_, a, ac = '', b, bc = '') => `@@ -${Number(a) + shift}${ac} +${Number(b) + shift}${bc} @@`) };
+        }
         return {
             beforeHash,
             afterHash,
-            additions: 0,
-            deletions: 0,
             truncated: true,
             omittedReason: 'too_large',
         };
     }
-    const changes = diffLines(before, after);
+    const changes = diffLines(before, after, { timeout: 500, maxEditLength: 10_000 });
+    if (!changes)
+        return { beforeHash, afterHash,
+            truncated: true, omittedReason: 'too_large' };
     const additions = changes
         .filter((change) => change.added)
         .reduce((sum, change) => sum + (change.count ?? 0), 0);

package/src/tools/shared/diffSummary.ts

@@ -22,17 +22,37 @@ export function buildPatchSummary(
   const totalLines =
     (before.match(/\n/g)?.length ?? 0) + (after.match(/\n/g)?.length ?? 0) + 2;
   if (totalBytes > MAX_BYTES || totalLines > MAX_LINES) {
+    // Strip identical outer lines before expensive diff work. A large file with
+    // a small edit still gets a real preview with original line coordinates.
+    let prefix = 0;
+    while (prefix < Math.min(before.length, after.length) && before[prefix] === after[prefix]) prefix++;
+    const start = before.lastIndexOf('\n', Math.max(0, prefix - 1)) + 1;
+    let suffix = 0;
+    while (suffix < Math.min(before.length, after.length) - start &&
+      before[before.length - suffix - 1] === after[after.length - suffix - 1]) suffix++;
+    const tail = before.indexOf('\n', before.length - suffix);
+    const suffixLength = tail < 0 ? 0 : before.length - tail - 1;
+    const oldWindow = before.slice(start, before.length - suffixLength);
+    const newWindow = after.slice(start, after.length - suffixLength);
+    if (Buffer.byteLength(oldWindow) + Buffer.byteLength(newWindow) <= MAX_BYTES &&
+      (oldWindow.match(/\n/g)?.length ?? 0) + (newWindow.match(/\n/g)?.length ?? 0) + 2 <= MAX_LINES) {
+      const local = buildPatchSummary(oldWindow, newWindow, label);
+      const shift = (before.slice(0, start).match(/\n/g)?.length ?? 0);
+      return { ...local, beforeHash, afterHash,
+        unifiedDiff: local.unifiedDiff?.replace(/@@ -(\d+)(,\d+)? \+(\d+)(,\d+)? @@/g,
+          (_, a, ac = '', b, bc = '') => `@@ -${Number(a) + shift}${ac} +${Number(b) + shift}${bc} @@`) };
+    }
     return {
       beforeHash,
       afterHash,
-      additions: 0,
-      deletions: 0,
       truncated: true,
       omittedReason: 'too_large',
     };
   }
 
-  const changes = diffLines(before, after);
+  const changes = diffLines(before, after, { timeout: 500, maxEditLength: 10_000 });
+  if (!changes) return { beforeHash, afterHash,
+    truncated: true, omittedReason: 'too_large' };
   const additions = changes
     .filter((change) => change.added)
     .reduce((sum, change) => sum + (change.count ?? 0), 0);

package/src/tools/shared/editTransaction.js

@@ -0,0 +1,45 @@
+import { readFile, stat, realpath } from 'node:fs/promises';
+import { atomicWriteFile, encodeTextFile, readTextFile } from './fileUtils.js';
+import { hashFileBytes } from './fileState.js';
+// Bound the in-memory replacement engine independently of model context size.
+export const MAX_EDIT_BYTES = 128 * 1024 * 1024;
+const commits = new Map();
+export async function readEditSnapshot(path) {
+    if ((await stat(path)).size > MAX_EDIT_BYTES)
+        throw new Error('文件超过 128 MiB 内存编辑边界；请使用流式转换写入临时文件并校验，不要用 Write 全文覆盖。');
+    const snapshot = await readTextFile(path);
+    if (snapshot.bytes.length > MAX_EDIT_BYTES)
+        throw new Error('读取期间文件超过编辑边界');
+    return snapshot;
+}
+export async function commitEdit(path, snapshot, content) {
+    const key = await realpath(path);
+    const previous = commits.get(key) ?? Promise.resolve();
+    let release;
+    const current = new Promise(resolve => { release = resolve; });
+    commits.set(key, current);
+    await previous;
+    try {
+        return await commitSnapshot(key, snapshot, content);
+    }
+    finally {
+        release();
+        if (commits.get(key) === current)
+            commits.delete(key);
+    }
+}
+async function commitSnapshot(path, snapshot, content) {
+    const bytes = encodeTextFile(content, snapshot.encoding);
+    if (bytes.length > MAX_EDIT_BYTES)
+        throw new Error('编辑结果超过 128 MiB 内存编辑边界');
+    const beforeHash = hashFileBytes(snapshot.bytes);
+    if (hashFileBytes(await readFile(path)) !== beforeHash)
+        throw new Error('编辑期间文件已被其他操作修改，未提交；请重新读取后再编辑。');
+    // Optimistic conflict check, not an OS-wide compare-and-swap guarantee.
+    if (!bytes.equals(snapshot.bytes))
+        await atomicWriteFile(path, bytes);
+    const afterHash = hashFileBytes(bytes);
+    if (hashFileBytes(await readFile(path)) !== afterHash)
+        throw new Error('提交后文件内容与预期不一致（可能被外部进程改写）；请读取核验，不要盲目重复替换。');
+    return { beforeHash, afterHash };
+}

package/src/tools/shared/editTransaction.ts

@@ -0,0 +1,39 @@
+import { readFile, stat, realpath } from 'node:fs/promises';
+import { atomicWriteFile, encodeTextFile, readTextFile } from './fileUtils.js';
+import { hashFileBytes } from './fileState.js';
+
+// Bound the in-memory replacement engine independently of model context size.
+export const MAX_EDIT_BYTES = 128 * 1024 * 1024;
+const commits = new Map<string, Promise<void>>();
+export async function readEditSnapshot(path: string) {
+  if ((await stat(path)).size > MAX_EDIT_BYTES)
+    throw new Error('文件超过 128 MiB 内存编辑边界；请使用流式转换写入临时文件并校验，不要用 Write 全文覆盖。');
+  const snapshot = await readTextFile(path);
+  if (snapshot.bytes.length > MAX_EDIT_BYTES) throw new Error('读取期间文件超过编辑边界');
+  return snapshot;
+}
+
+export async function commitEdit(path: string, snapshot: Awaited<ReturnType<typeof readEditSnapshot>>, content: string) {
+  const key = await realpath(path);
+  const previous = commits.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const current = new Promise<void>(resolve => { release = resolve; });
+  commits.set(key, current);
+  await previous;
+  try { return await commitSnapshot(key, snapshot, content); }
+  finally { release(); if (commits.get(key) === current) commits.delete(key); }
+}
+
+async function commitSnapshot(path: string, snapshot: Awaited<ReturnType<typeof readEditSnapshot>>, content: string) {
+  const bytes = encodeTextFile(content, snapshot.encoding);
+  if (bytes.length > MAX_EDIT_BYTES) throw new Error('编辑结果超过 128 MiB 内存编辑边界');
+  const beforeHash = hashFileBytes(snapshot.bytes);
+  if (hashFileBytes(await readFile(path)) !== beforeHash)
+    throw new Error('编辑期间文件已被其他操作修改，未提交；请重新读取后再编辑。');
+  // Optimistic conflict check, not an OS-wide compare-and-swap guarantee.
+  if (!bytes.equals(snapshot.bytes)) await atomicWriteFile(path, bytes);
+  const afterHash = hashFileBytes(bytes);
+  if (hashFileBytes(await readFile(path)) !== afterHash)
+    throw new Error('提交后文件内容与预期不一致（可能被外部进程改写）；请读取核验，不要盲目重复替换。');
+  return { beforeHash, afterHash };
+}

package/src/tools/shared/fileActivity.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { readFile, realpath } from 'node:fs/promises';
+import { realpath, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
 import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
 const MIME_BY_EXT = {
@@ -32,7 +33,14 @@ export async function fileActivityMetadata(filePath, activity, verification = 'n
     let sha256;
     if (activity !== 'deleted') {
         try {
-            sha256 = createHash('sha256').update(await readFile(candidate)).digest('hex');
+            // A range Read must not secretly load/hash a gigabyte for UI metadata.
+            // Hash is optional for sources; committed artifacts use bounded buffers.
+            if (activity !== 'read' || (await stat(candidate)).size <= 8 * 1024 * 1024) {
+                const hash = createHash('sha256');
+                for await (const chunk of createReadStream(candidate))
+                    hash.update(chunk);
+                sha256 = hash.digest('hex');
+            }
         }
         catch { /* The file activity remains useful even when hashing fails. */ }
     }

package/src/tools/shared/fileActivity.ts

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
-import { readFile, realpath } from 'node:fs/promises';
+import { realpath, stat } from 'node:fs/promises';
+import { createReadStream } from 'node:fs';
 import { extname, isAbsolute, relative, resolve, sep } from 'node:path';
 
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
@@ -48,7 +49,15 @@ export async function fileActivityMetadata(
 
   let sha256: string | undefined;
   if (activity !== 'deleted') {
-    try { sha256 = createHash('sha256').update(await readFile(candidate)).digest('hex'); }
+    try {
+      // A range Read must not secretly load/hash a gigabyte for UI metadata.
+      // Hash is optional for sources; committed artifacts use bounded buffers.
+      if (activity !== 'read' || (await stat(candidate)).size <= 8 * 1024 * 1024) {
+        const hash = createHash('sha256');
+        for await (const chunk of createReadStream(candidate)) hash.update(chunk);
+        sha256 = hash.digest('hex');
+      }
+    }
     catch { /* The file activity remains useful even when hashing fails. */ }
   }
   return {