minimal-agent 0.11.0 → 0.12.0

package/src/tools/read/read.ts

@@ -1,14 +1,27 @@
 import { createReadStream } from 'node:fs';
-import { open, readFile, stat } from 'node:fs/promises';
+import { open, readFile, stat, writeFile } from 'node:fs/promises';
 import { extname } from 'node:path';
 import { createInterface } from 'node:readline';
+import { execFile } from 'node:child_process';
+import { mkdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 
 import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
-import { DEFAULT_MAX_RESULT_SIZE_CHARS, MAX_FILE_SIZE_BYTES, MAX_LINES_TO_READ } from '../types.js';
+import {
+  DEFAULT_MAX_RESULT_SIZE_CHARS,
+  MAX_FILE_SIZE_BYTES,
+  MAX_LINES_TO_READ,
+} from '../types.js';
 import { fileActivityMetadata } from '../shared/fileActivity.js';
-import { hashFileBytes, recordRead, type FileReadState } from '../shared/fileState.js';
+import {
+  hashFileBytes,
+  recordRead,
+  type FileReadState,
+} from '../shared/fileState.js';
 import {
   hasBinaryExtension,
   isBlockedDevicePath,
@@ -16,19 +29,48 @@ import {
   resolveToolPath,
 } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
+import {
+  pruneRuntimeOutputs,
+  sessionRuntimeDir,
+  type RuntimeIdentity,
+} from '../../session/runtimeStore.js';
 
 const inputSchema = z.object({
   file_path: filePathField('读取'),
-  offset: z.number().int().positive().optional().describe(
-    '文本文件为 1-indexed 起始行；Jupyter Notebook 为 1-indexed 起始 cell',
-  ),
-  limit: z.number().int().positive().optional().describe(
-    `最多读取的文本行或 Notebook cells；默认 ${MAX_LINES_TO_READ}`,
-  ),
+  offset: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(
+      '文本文件为 1-indexed 起始行；Jupyter Notebook 为 1-indexed 起始 cell',
+    ),
+  limit: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe(`最多读取的文本行或 Notebook cells；默认 ${MAX_LINES_TO_READ}`),
+  pages: z
+    .string()
+    .regex(/^\d+(?:-\d+)?(?:,\d+(?:-\d+)?)*$/)
+    .optional()
+    .describe('PDF 页码，例如 "1-5,8"；每次最多 20 页'),
+  pdf_mode: z
+    .enum(['auto', 'text', 'visual', 'both'])
+    .default('auto')
+    .optional(),
 });
 type ReadInput = z.infer<typeof inputSchema>;
 
-const IMAGE_EXTENSIONS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp']);
+const IMAGE_EXTENSIONS = new Set([
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.webp',
+  '.bmp',
+]);
 const MAX_IMAGE_BYTES = 25 * 1024 * 1024;
 const MAX_NOTEBOOK_BYTES = 32 * 1024 * 1024;
 const SMALL_TEXT_BYTES = 16 * 1024 * 1024;
@@ -38,36 +80,55 @@ const description = `Reads local text files, images, and Jupyter notebooks.
 Usage:
 - Relative paths resolve against the current working directory.
 - Text results use 1-based line numbers. Use offset/limit for targeted ranges.
-- PNG, JPEG, WebP, GIF, BMP, and TIFF files are attached for visual inspection.
+- PNG, JPEG, WebP, GIF, and BMP files are attached for visual inspection.
 - For .ipynb files, offset/limit select cells; results include cell id, type, source, and bounded outputs.
-- PDF and office files are not decoded by this tool. Use the matching project Skill for those formats.
+- PDF supports page-selected text extraction and optional visual page rendering; office files use the matching project Skill.
 - This tool reads files, not directories; use Glob for directory discovery.`;
 
 function notebookSource(value: unknown): string {
-  if (Array.isArray(value)) return value.filter((item): item is string => typeof item === 'string').join('');
+  if (Array.isArray(value))
+    return value
+      .filter((item): item is string => typeof item === 'string')
+      .join('');
   return typeof value === 'string' ? value : '';
 }
 
-function renderNotebook(raw: string, offset: number, limit: number): {
+function renderNotebook(
+  raw: string,
+  offset: number,
+  limit: number,
+): {
   content: string;
   total: number;
   partial: boolean;
 } {
-  const parsed = JSON.parse(raw) as { cells?: unknown[]; metadata?: Record<string, unknown> };
+  const parsed = JSON.parse(raw) as {
+    cells?: unknown[];
+    metadata?: Record<string, unknown>;
+  };
   if (!Array.isArray(parsed.cells)) throw new Error('Notebook 缺少 cells 数组');
   const start = offset - 1;
   const cells = parsed.cells.slice(start, start + limit);
   const parts = cells.map((value, index) => {
-    const cell = value && typeof value === 'object' ? value as Record<string, unknown> : {};
+    const cell =
+      value && typeof value === 'object'
+        ? (value as Record<string, unknown>)
+        : {};
     const outputs = Array.isArray(cell.outputs) ? cell.outputs : [];
-    const renderedOutputs = outputs.slice(0, 8).map((output) => {
-      if (!output || typeof output !== 'object') return String(output ?? '');
-      const item = output as Record<string, unknown>;
-      const text = item.text ?? (item.data && typeof item.data === 'object'
-        ? (item.data as Record<string, unknown>)['text/plain']
-        : undefined);
-      return notebookSource(text).slice(0, 2_000);
-    }).filter(Boolean).join('\n');
+    const renderedOutputs = outputs
+      .slice(0, 8)
+      .map((output) => {
+        if (!output || typeof output !== 'object') return String(output ?? '');
+        const item = output as Record<string, unknown>;
+        const text =
+          item.text ??
+          (item.data && typeof item.data === 'object'
+            ? (item.data as Record<string, unknown>)['text/plain']
+            : undefined);
+        return notebookSource(text).slice(0, 2_000);
+      })
+      .filter(Boolean)
+      .join('\n');
     return [
       `## Cell ${start + index + 1} [selector=cell-${start + index + 1}${typeof cell.id === 'string' ? `; id=${cell.id}` : ''}; type=${String(cell.cell_type ?? 'unknown')}]`,
       notebookSource(cell.source),
@@ -75,8 +136,15 @@ function renderNotebook(raw: string, offset: number, limit: number): {
     ].join('\n');
   });
   const end = start + cells.length;
-  if (end < parsed.cells.length) parts.push(`... (${parsed.cells.length - end} cells remain; continue with offset=${end + 1})`);
-  return { content: parts.join('\n\n'), total: parsed.cells.length, partial: start > 0 || end < parsed.cells.length };
+  if (end < parsed.cells.length)
+    parts.push(
+      `... (${parsed.cells.length - end} cells remain; continue with offset=${end + 1})`,
+    );
+  return {
+    content: parts.join('\n\n'),
+    total: parsed.cells.length,
+    partial: start > 0 || end < parsed.cells.length,
+  };
 }
 
 async function readStreamedText(
@@ -91,7 +159,14 @@ async function readStreamedText(
   const utf16 = bytesRead >= 2 && prefix[0] === 0xff && prefix[1] === 0xfe;
   const stream = createReadStream(filePath, {
     encoding: utf16 ? 'utf16le' : 'utf8',
-    start: utf16 ? 2 : bytesRead >= 3 && prefix[0] === 0xef && prefix[1] === 0xbb && prefix[2] === 0xbf ? 3 : 0,
+    start: utf16
+      ? 2
+      : bytesRead >= 3 &&
+          prefix[0] === 0xef &&
+          prefix[1] === 0xbb &&
+          prefix[2] === 0xbf
+        ? 3
+        : 0,
   });
   const rl = createInterface({ input: stream, crlfDelay: Infinity });
   const lines: string[] = [];
@@ -110,61 +185,193 @@ async function readStreamedText(
   return { numbered: lines.join('\n'), totalKnown: line, hasMore };
 }
 
-async function call(input: ReadInput, state?: FileReadState, cwd?: string): Promise<ToolResult> {
+async function call(
+  input: ReadInput,
+  state?: FileReadState,
+  cwd?: string,
+  runtimeIdentity?: RuntimeIdentity,
+): Promise<ToolResult> {
   const offset = input.offset ?? 1;
   const limit = input.limit ?? MAX_LINES_TO_READ;
   const resolved = resolveToolPath(input.file_path, cwd);
   if (!resolved.ok) return resolved;
   const filePath = resolved.resolvedPath;
-  if (isBlockedDevicePath(filePath)) return { ok: false, error: `不允许读取设备文件：${filePath}` };
+  if (isBlockedDevicePath(filePath))
+    return { ok: false, error: `不允许读取设备文件：${filePath}` };
 
   const info = await stat(filePath).catch((error: Error) => ({ error }));
-  if ('error' in info) return { ok: false, error: `文件不存在或无法读取：${filePath}（${info.error.message}）` };
-  if (!info.isFile()) return { ok: false, error: `${filePath} 不是文件；目录请用 Glob。` };
+  if ('error' in info)
+    return {
+      ok: false,
+      error: `文件不存在或无法读取：${filePath}（${info.error.message}）`,
+    };
+  if (!info.isFile())
+    return { ok: false, error: `${filePath} 不是文件；目录请用 Glob。` };
   const ext = extname(filePath).toLowerCase();
 
+  if (ext === '.pdf') {
+    try {
+      const bytes = await readFile(filePath);
+      if (bytes.subarray(0, 5).toString() !== '%PDF-') {
+        return {
+          ok: false,
+          error: '文件扩展名是 PDF，但缺少有效 %PDF- 文件头',
+        };
+      }
+      const pdfjs = await import('pdfjs-dist/legacy/build/pdf.mjs');
+      const document = await pdfjs.getDocument({
+        data: new Uint8Array(bytes),
+        useSystemFonts: true,
+      }).promise;
+      try {
+        const requested = parsePdfPages(input.pages, document.numPages);
+        if (requested.length > 20)
+          return { ok: false, error: '一次最多读取 20 个 PDF 页面' };
+        const chunks: string[] = [];
+        for (const pageNumber of requested) {
+          const page = await document.getPage(pageNumber);
+          const text = await page.getTextContent();
+          chunks.push(
+            `## Page ${pageNumber}\n${text.items
+              .map((item) =>
+                'str' in item && typeof item.str === 'string' ? item.str : '',
+              )
+              .filter(Boolean)
+              .join(' ')}`,
+          );
+        }
+        const mode = input.pdf_mode ?? 'auto';
+        const sparse =
+          chunks.join('').replace(/\s/g, '').length < requested.length * 80;
+        const wantVisual =
+          mode === 'visual' || mode === 'both' || (mode === 'auto' && sparse);
+        const images = wantVisual
+          ? await renderPdfPages(
+              document,
+              filePath,
+              requested.slice(0, 10),
+              runtimeIdentity,
+            )
+          : [];
+        recordRead(filePath, { contentHash: hashFileBytes(bytes) }, state);
+        const rawText =
+          mode === 'visual' ? '[visual-only mode]' : chunks.join('\n\n');
+        const text =
+          rawText.length > DEFAULT_MAX_RESULT_SIZE_CHARS
+            ? `${rawText.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)}\n... (PDF 文本输出已截断；请缩小 pages 范围继续读取)`
+            : rawText;
+        return {
+          ok: true,
+          content: `PDF ${document.numPages} pages; selected ${requested.join(', ')}.\n\n${text}${wantVisual && !images.length ? '\n\n视觉渲染不可用（Canvas 与 pdftoppm 均不可用）；文本提取结果仍可用。' : ''}`,
+          metadata: await fileActivityMetadata(
+            filePath,
+            'read',
+            'not_run',
+            'source',
+            cwd,
+          ),
+          ...(images.length
+            ? {
+                visionImages: images.map((source) => ({ source })),
+                visionNote:
+                  '这是所选 PDF 页面的视觉渲染，请检查版式、图表和扫描内容。',
+              }
+            : {}),
+        };
+      } finally {
+        await document.destroy().catch(() => undefined);
+      }
+    } catch (error) {
+      const message = (error as Error).message;
+      return {
+        ok: false,
+        error: `PDF 解析失败${/password/i.test(message) ? '（文件可能已加密）' : ''}：${message}`,
+      };
+    }
+  }
+
   if (IMAGE_EXTENSIONS.has(ext)) {
-    if (info.size > MAX_IMAGE_BYTES) return { ok: false, error: `图片超过 ${MAX_IMAGE_BYTES} 字节上限` };
+    if (info.size > MAX_IMAGE_BYTES)
+      return { ok: false, error: `图片超过 ${MAX_IMAGE_BYTES} 字节上限` };
     const bytes = await readFile(filePath);
     recordRead(filePath, { contentHash: hashFileBytes(bytes) }, state);
     return {
       ok: true,
       content: `已读取图片：${filePath}（${info.size} 字节）。图像已附加供视觉模型检查；非视觉模型只能确认文件元数据，不能解读像素内容。`,
-      metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd),
+      metadata: await fileActivityMetadata(
+        filePath,
+        'read',
+        'not_run',
+        'source',
+        cwd,
+      ),
       visionImages: [{ source: filePath }],
       visionNote: '这是 Read 工具读取的本地图片，请直接检查图像内容。',
     };
   }
 
   if (ext === '.ipynb') {
-    if (info.size > MAX_NOTEBOOK_BYTES) return { ok: false, error: `Notebook 超过 ${MAX_NOTEBOOK_BYTES} 字节上限` };
+    if (info.size > MAX_NOTEBOOK_BYTES)
+      return {
+        ok: false,
+        error: `Notebook 超过 ${MAX_NOTEBOOK_BYTES} 字节上限`,
+      };
     try {
       const snapshot = await readTextFile(filePath);
-      const rendered = renderNotebook(snapshot.content, offset, Math.min(limit, 200));
+      const rendered = renderNotebook(
+        snapshot.content,
+        offset,
+        Math.min(limit, 200),
+      );
       let content = rendered.content;
       let truncated = false;
       if (content.length > DEFAULT_MAX_RESULT_SIZE_CHARS) {
         content = `${content.slice(0, DEFAULT_MAX_RESULT_SIZE_CHARS)}\n\n... (Notebook 输出已截断)`;
         truncated = true;
       }
-      recordRead(filePath, {
-        offset,
-        limit,
-        partial: rendered.partial,
-        truncated,
-        ...(!rendered.partial && !truncated ? { contentHash: hashFileBytes(snapshot.bytes) } : {}),
-      }, state);
-      return { ok: true, content, metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd) };
+      recordRead(
+        filePath,
+        {
+          offset,
+          limit,
+          partial: rendered.partial,
+          truncated,
+          ...(!rendered.partial && !truncated
+            ? { contentHash: hashFileBytes(snapshot.bytes) }
+            : {}),
+        },
+        state,
+      );
+      return {
+        ok: true,
+        content,
+        metadata: await fileActivityMetadata(
+          filePath,
+          'read',
+          'not_run',
+          'source',
+          cwd,
+        ),
+      };
     } catch (error) {
-      return { ok: false, error: `Notebook 解析失败：${(error as Error).message}` };
+      return {
+        ok: false,
+        error: `Notebook 解析失败：${(error as Error).message}`,
+      };
     }
   }
 
   if (hasBinaryExtension(filePath)) {
-    return { ok: false, error: `不支持直接读取 ${ext || '该二进制格式'}；PDF/Office 文件请使用对应 Skill。` };
+    return {
+      ok: false,
+      error: `不支持直接读取 ${ext || '该二进制格式'}；PDF/Office 文件请使用对应 Skill。`,
+    };
   }
   if (info.size > MAX_FILE_SIZE_BYTES) {
-    return { ok: false, error: `文件超过 ${MAX_FILE_SIZE_BYTES} 字节硬上限。请用 Grep 定位，或用 Bash 做流式处理。` };
+    return {
+      ok: false,
+      error: `文件超过 ${MAX_FILE_SIZE_BYTES} 字节硬上限。请用 Grep 定位，或用 Bash 做流式处理。`,
+    };
   }
 
   try {
@@ -175,10 +382,13 @@ async function call(input: ReadInput, state?: FileReadState, cwd?: string): Prom
     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 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');
+      content = selected
+        .map((line, index) => `${start + index + 1}\t${line}`)
+        .join('\n');
       totalLines = all.length;
       hasMore = start + selected.length < all.length;
     } else {
@@ -194,24 +404,145 @@ async function call(input: ReadInput, state?: FileReadState, cwd?: string): Prom
       truncated = true;
     }
     const partial = offset !== 1 || hasMore;
-    if (hasMore) content += `\n\n... (还有更多内容；继续使用 offset=${offset + limit})`;
-    const reads = recordRead(filePath, {
-      offset,
-      limit,
-      partial,
-      truncated,
-      ...(!partial && !truncated && completeBytes ? { contentHash: hashFileBytes(completeBytes) } : {}),
-    }, state);
+    if (hasMore)
+      content += `\n\n... (还有更多内容；继续使用 offset=${offset + limit})`;
+    const reads = recordRead(
+      filePath,
+      {
+        offset,
+        limit,
+        partial,
+        truncated,
+        ...(!partial && !truncated && completeBytes
+          ? { contentHash: hashFileBytes(completeBytes) }
+          : {}),
+      },
+      state,
+    );
     if (info.size > 100 * 1024 && offset === 1) {
       content = `⚠️ 大文件：结果受行数和输出字符上限约束，请按需分段读取。\n\n${content}`;
     }
-    if (reads >= 2) content = `⚠️ 重复读取空转：该区间未变化，前一次 Read 结果仍然有效。\n\n${content}`;
-    return { ok: true, content, metadata: await fileActivityMetadata(filePath, 'read', 'not_run', 'source', cwd) };
+    if (reads >= 2)
+      content = `⚠️ 重复读取空转：该区间未变化，前一次 Read 结果仍然有效。\n\n${content}`;
+    return {
+      ok: true,
+      content,
+      metadata: await fileActivityMetadata(
+        filePath,
+        'read',
+        'not_run',
+        'source',
+        cwd,
+      ),
+    };
   } catch (error) {
     return { ok: false, error: `读取失败：${(error as Error).message}` };
   }
 }
 
+async function renderPdfPages(
+  document: Awaited<
+    ReturnType<
+      (typeof import('pdfjs-dist/legacy/build/pdf.mjs'))['getDocument']
+    >
+  >['promise'] extends Promise<infer T>
+    ? T
+    : never,
+  filePath: string,
+  pages: number[],
+  identity?: RuntimeIdentity,
+): Promise<string[]> {
+  const outputDir = join(sessionRuntimeDir(identity ?? {}), 'outputs');
+  const outputPrefix = `pdf_${randomUUID()}`;
+  await mkdir(outputDir, { recursive: true, mode: 0o700 });
+  const images: string[] = [];
+  const dynamicImport = new Function(
+    'specifier',
+    'return import(specifier)',
+  ) as (specifier: string) => Promise<{
+    createCanvas?: (
+      width: number,
+      height: number,
+    ) => {
+      getContext(type: '2d'): unknown;
+      toBuffer(type: 'image/png'): Buffer;
+    };
+  }>;
+  let createCanvas: Awaited<ReturnType<typeof dynamicImport>>['createCanvas'];
+  try {
+    ({ createCanvas } = await dynamicImport('@napi-rs/canvas'));
+  } catch {
+    /* optional adapter */
+  }
+  if (createCanvas) {
+    try {
+      for (const pageNumber of pages) {
+        const page = await document.getPage(pageNumber);
+        const viewport = page.getViewport({ scale: 2 });
+        const canvas = createCanvas(
+          Math.ceil(viewport.width),
+          Math.ceil(viewport.height),
+        );
+        await page.render({
+          canvasContext: canvas.getContext('2d') as never,
+          viewport,
+        }).promise;
+        const target = join(
+          outputDir,
+          `${outputPrefix}-page-${pageNumber}.png`,
+        );
+        await writeFile(target, canvas.toBuffer('image/png'), { mode: 0o600 });
+        images.push(target);
+      }
+      void pruneRuntimeOutputs();
+      return images;
+    } catch {
+      images.length = 0;
+    }
+  }
+  for (const pageNumber of pages) {
+    const prefix = join(outputDir, `${outputPrefix}-page-${pageNumber}`);
+    try {
+      await promisify(execFile)(
+        'pdftoppm',
+        [
+          '-f',
+          String(pageNumber),
+          '-l',
+          String(pageNumber),
+          '-singlefile',
+          '-png',
+          '-r',
+          '144',
+          filePath,
+          prefix,
+        ],
+        { maxBuffer: 1024 * 1024 },
+      );
+      images.push(`${prefix}.png`);
+    } catch {
+      break;
+    }
+  }
+  void pruneRuntimeOutputs();
+  return images;
+}
+
+function parsePdfPages(spec: string | undefined, total: number): number[] {
+  if (!spec)
+    return Array.from({ length: Math.min(total, 20) }, (_, index) => index + 1);
+  const pages = new Set<number>();
+  for (const part of spec.split(',')) {
+    const [first, last] = part.split('-').map(Number);
+    for (let page = first!; page <= (last ?? first!); page += 1) {
+      if (page < 1 || page > total)
+        throw new Error(`PDF 页码超出范围：${page}（共 ${total} 页）`);
+      pages.add(page);
+    }
+  }
+  return [...pages].sort((left, right) => left - right);
+}
+
 export const readTool: Tool<ReadInput> = {
   name: 'Read',
   description,
@@ -222,5 +553,6 @@ export const readTool: Tool<ReadInput> = {
   maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
   interruptBehavior: () => 'cancel',
   call: (input) => call(input),
-  callWithContext: (input, _signal, context: ToolCallContext) => call(input, context.sessionState?.fileReads, context.cwd),
+  callWithContext: (input, _signal, context: ToolCallContext) =>
+    call(input, context.sessionState?.fileReads, context.cwd, context),
 };

package/src/tools/shared/diffSummary.js

@@ -0,0 +1,44 @@
+import { createHash } from 'node:crypto';
+import { createTwoFilesPatch, diffLines } from 'diff';
+const MAX_BYTES = 5 * 1024 * 1024;
+const MAX_LINES = 200_000;
+const MAX_DIFF_CHARS = 16_000;
+function hash(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+export function buildPatchSummary(before, after, label) {
+    const beforeHash = hash(before);
+    const afterHash = hash(after);
+    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) {
+        return {
+            beforeHash,
+            afterHash,
+            additions: 0,
+            deletions: 0,
+            truncated: true,
+            omittedReason: 'too_large',
+        };
+    }
+    const changes = diffLines(before, after);
+    const additions = changes
+        .filter((change) => change.added)
+        .reduce((sum, change) => sum + (change.count ?? 0), 0);
+    const deletions = changes
+        .filter((change) => change.removed)
+        .reduce((sum, change) => sum + (change.count ?? 0), 0);
+    let unifiedDiff = createTwoFilesPatch(`a/${label}`, `b/${label}`, before, after, undefined, undefined, { context: 3 });
+    const truncated = unifiedDiff.length > MAX_DIFF_CHARS;
+    if (truncated) {
+        unifiedDiff = `${unifiedDiff.slice(0, MAX_DIFF_CHARS)}\n... (diff preview truncated)`;
+    }
+    return {
+        unifiedDiff,
+        beforeHash,
+        afterHash,
+        additions,
+        deletions,
+        truncated,
+    };
+}

package/src/tools/shared/diffSummary.ts

@@ -0,0 +1,63 @@
+import { createHash } from 'node:crypto';
+import { createTwoFilesPatch, diffLines } from 'diff';
+
+import type { FilePatchSummary } from '../../types.js';
+
+const MAX_BYTES = 5 * 1024 * 1024;
+const MAX_LINES = 200_000;
+const MAX_DIFF_CHARS = 16_000;
+
+function hash(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+export function buildPatchSummary(
+  before: string,
+  after: string,
+  label: string,
+): FilePatchSummary {
+  const beforeHash = hash(before);
+  const afterHash = hash(after);
+  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) {
+    return {
+      beforeHash,
+      afterHash,
+      additions: 0,
+      deletions: 0,
+      truncated: true,
+      omittedReason: 'too_large',
+    };
+  }
+
+  const changes = diffLines(before, after);
+  const additions = changes
+    .filter((change) => change.added)
+    .reduce((sum, change) => sum + (change.count ?? 0), 0);
+  const deletions = changes
+    .filter((change) => change.removed)
+    .reduce((sum, change) => sum + (change.count ?? 0), 0);
+  let unifiedDiff = createTwoFilesPatch(
+    `a/${label}`,
+    `b/${label}`,
+    before,
+    after,
+    undefined,
+    undefined,
+    { context: 3 },
+  );
+  const truncated = unifiedDiff.length > MAX_DIFF_CHARS;
+  if (truncated) {
+    unifiedDiff = `${unifiedDiff.slice(0, MAX_DIFF_CHARS)}\n... (diff preview truncated)`;
+  }
+  return {
+    unifiedDiff,
+    beforeHash,
+    afterHash,
+    additions,
+    deletions,
+    truncated,
+  };
+}