minimal-agent 0.10.0 → 0.12.0

package/src/tools/computeruse/waitFor.ts

@@ -0,0 +1,291 @@
+/**
+ * ============================================================
+ *  waitFor.ts —— 语义等待（wait_for_element / text / window）
+ * ------------------------------------------------------------
+ *  ★ **零协议改动、零 vendor 重编。** 这三个动作本质是「轮询观测直到条件
+ *    成立」，而观测与 AX 树原生侧早已提供 —— 编排是 TS 的事，符合
+ *    「Rust 出像素，TS 做判断」总纲。
+ *
+ *  它们解决的是一个真实的成本问题：在此之前模型只能
+ *  `observe → 看 → observe` 地轮询，而每次 observe 都要组装图（约 1100 token）。
+ *  这里改用**元数据观测**（`includeScreenshot:false`，`list_apps` 已经在走这条
+ *  路径），一轮几乎不花 token，命中才返回。
+ *
+ *  三条刻意的边界，缺任一条都会变成新的故障源：
+ *
+ *   ① **超时不抛异常，而且要说清现场。** 只回一句「等了 5 秒没等到」，模型
+ *      只能盲试；带上「现在前台是谁、有哪些窗口、AX 里有哪些角色」，它才有
+ *      下一步可走。
+ *   ② **AX 不可用时立刻返回**，不空转到超时。微信这类自绘应用的树整棵是空的，
+ *      `wait_for_element` 在那里等多久都不会成立 —— 等 5 秒再报一个含糊的超时
+ *      是纯粹的浪费，且会把「这个能力用不了」误导成「这次没等到」。
+ *   ③ **条件已成立就首轮返回**，不为了「像在等」而先睡一轮。
+ * ============================================================
+ */
+
+import {
+  containsFold,
+  describeNode,
+  findByRole,
+  flattenAx,
+  matchesText,
+  type AxSearchNode,
+} from './axSearch.js';
+import type { ComputerState, ComputerUseAction } from './protocol.js';
+
+/** 本模块接管的动作。 */
+export const WAIT_ACTIONS = [
+  'wait',
+  'wait_for_element',
+  'wait_for_text',
+  'wait_for_window',
+] as const satisfies readonly ComputerUseAction[];
+
+export type WaitAction = (typeof WAIT_ACTIONS)[number];
+
+export function isWaitAction(action: ComputerUseAction): action is WaitAction {
+  return (WAIT_ACTIONS as readonly string[]).includes(action);
+}
+
+export function isSimpleWaitAction(action: ComputerUseAction): action is 'wait' {
+  return action === 'wait';
+}
+
+/** 轮询间隔。200ms 是「人眼觉得即时」与「别把守护进程压满」之间的常用折中。 */
+export const WAIT_POLL_INTERVAL_MS = 200;
+/** 默认等待上限。模型可用 `timeoutMs` 覆盖（schema 限 100–120000）。 */
+export const WAIT_DEFAULT_TIMEOUT_MS = 5_000;
+
+export interface WaitInput {
+  action: WaitAction;
+  /** `wait_for_element` 必填：AX 角色，如 `AXButton`。 */
+  role?: string;
+  /** 名字/文本片段。element 时可选，text/window 时必填。 */
+  text?: string;
+  /** 等待时间（毫秒），仅用于简单 `wait` 动作，默认 1000ms。 */
+  waitMs?: number;
+  timeoutMs?: number;
+}
+
+export interface WaitOutcome {
+  ok: boolean;
+  content: string;
+  /** 命中的控件 id（`wait_for_element` / `wait_for_text` 命中可点控件时才有）。 */
+  elementId?: string;
+  /** 实际等了多久，供遥测。 */
+  waitedMs: number;
+  /** 轮询了几次。 */
+  polls: number;
+}
+
+/** 一次观测的判定结果。`unavailable` = 这条判据在此应用上根本用不了。 */
+type Verdict =
+  | { kind: 'hit'; description: string; elementId?: string }
+  | { kind: 'miss' }
+  | { kind: 'unavailable'; reason: string };
+
+function axNodes(state: ComputerState): AxSearchNode[] {
+  return flattenAx(state.accessibility?.root as AxSearchNode | undefined);
+}
+
+function axUsable(state: ComputerState): boolean {
+  return state.accessibility !== undefined && state.accessibility.truncated !== true;
+}
+
+const AX_BLIND_HINT =
+  '这个应用没有可用的无障碍树（自绘/Electron 应用的常态），按控件等待在这里永远不会成立。'
+  + '改用 `settle` 判断界面稳没稳，再 `observe` 看图确认。';
+
+function evaluate(input: WaitInput, state: ComputerState): Verdict {
+  switch (input.action) {
+    case 'wait':
+      // 简单 wait 不需要评估条件，直接返回 hit（它只 sleep）
+      return { kind: 'hit', description: '等待完成' };
+    case 'wait_for_window': {
+      // 窗口列表不依赖 AX 树的完整性，自绘应用上照样可用 —— 这是三个 wait
+      // 里唯一对微信这类应用有效的那个。
+      const needle = input.text ?? '';
+      const hit = state.windows.find((window) => containsFold(window.title, needle));
+      if (hit) {
+        return { kind: 'hit', description: `窗口「${hit.title ?? '(无标题)'}」（${hit.appId}）` };
+      }
+      return { kind: 'miss' };
+    }
+    case 'wait_for_element': {
+      if (!axUsable(state)) return { kind: 'unavailable', reason: AX_BLIND_HINT };
+      const matches = findByRole(axNodes(state), input.role ?? '', input.text);
+      const hit = matches[0];
+      if (!hit) return { kind: 'miss' };
+      return {
+        kind: 'hit',
+        description: describeNode(hit)
+          + (matches.length > 1 ? `（另有 ${matches.length - 1} 个同样匹配的控件）` : ''),
+        ...(hit.elementId ? { elementId: hit.elementId } : {}),
+      };
+    }
+    case 'wait_for_text': {
+      if (!axUsable(state)) return { kind: 'unavailable', reason: AX_BLIND_HINT };
+      const hit = axNodes(state).find((node) => matchesText(node, input.text ?? ''));
+      if (!hit) return { kind: 'miss' };
+      return {
+        kind: 'hit',
+        description: describeNode(hit),
+        ...(hit.elementId ? { elementId: hit.elementId } : {}),
+      };
+    }
+    default:
+      return { kind: 'miss' };
+  }
+}
+
+/**
+ * 超时时给模型看的现场。
+ *
+ * 这段是本模块最容易被写敷衍的地方，也是最要紧的：模型拿不到现场就只能重试
+ * 同一件事，而重试同一件事正是熔断要拦的行为。
+ */
+function describeScene(input: WaitInput, state: ComputerState | null): string[] {
+  if (!state) return ['  等待期间一次观测都没成功 —— 先检查权限与守护进程。'];
+  const lines = [
+    `  当前前台：${state.activeApp?.name ?? '未知'}（${state.activeApp?.id ?? '无标识'}）`,
+    `  窗口：${state.windows.length > 0
+      ? state.windows.map((w) => `「${w.title ?? '(无标题)'}」`).slice(0, 6).join('、')
+      : '（一个都没有）'}`,
+  ];
+  if (input.action !== 'wait_for_window') {
+    const nodes = axNodes(state);
+    const roles = [...new Set(nodes.map((node) => node.role).filter(Boolean))].slice(0, 12);
+    lines.push(`  无障碍树：${axUsable(state) ? `${nodes.length} 个节点` : '不可用'}`);
+    if (roles.length > 0) lines.push(`  树里出现过的角色：${roles.join('、')}`);
+  }
+  return lines;
+}
+
+function requirementOf(input: WaitInput): string {
+  switch (input.action) {
+    case 'wait':
+      return '等待时间结束';
+    case 'wait_for_element':
+      return `控件 ${input.role}${input.text ? `（名字含「${input.text}」）` : ''}`;
+    case 'wait_for_text':
+      return `文本「${input.text}」`;
+    case 'wait_for_window':
+      return `标题含「${input.text}」的窗口`;
+    default:
+      return '未知条件';
+  }
+}
+
+/** 入参校验。返回非 null 表示参数本身就不成立，不必去等。 */
+export function validateWaitInput(input: WaitInput): string | null {
+  // 简单 wait 不需要任何参数，只需要可选的等待时间
+  if (input.action === 'wait') {
+    if (input.waitMs !== undefined && (input.waitMs < 10 || input.waitMs > 30000)) {
+      return 'wait 的 waitMs 参数必须在 10-30000 毫秒之间（默认 1000ms）。';
+    }
+    return null;
+  }
+  if (input.action === 'wait_for_element' && !input.role?.trim()) {
+    return 'wait_for_element 需要 role（AX 角色，如 AXButton）；只给文本请用 wait_for_text。';
+  }
+  if (input.action !== 'wait_for_element' && !input.text?.trim()) {
+    return `${input.action} 需要 text（要等的文本/窗口标题片段）。`;
+  }
+  return null;
+}
+
+/**
+ * 轮询直到条件成立或超时。
+ *
+ * `observeOnce` 由调用方注入（生产里是一次元数据观测），便于单测用合成状态
+ * 驱动而不碰真实守护进程。
+ */
+export async function waitForCondition(input: WaitInput, deps: {
+  observeOnce: () => Promise<ComputerState | null>;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  signal?: AbortSignal;
+}): Promise<WaitOutcome> {
+  const invalid = validateWaitInput(input);
+  if (invalid) return { ok: false, content: invalid, waitedMs: 0, polls: 0 };
+
+  const now = deps.now ?? (() => Date.now());
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((r) => setTimeout(r, ms)));
+
+  // 简单 wait：纯 sleep，不截图不查 AX 树
+  if (input.action === 'wait') {
+    const waitMs = input.waitMs ?? 2000;
+    const startedAt = now();
+    if (deps.signal) {
+      // 支持中断：用 Promise.race 实现可取消的 sleep
+      await Promise.race([
+        sleep(waitMs),
+        new Promise<void>((_, reject) => {
+          deps.signal?.addEventListener('abort', () => reject(new Error('aborted')), { once: true });
+        }).catch(() => {}),
+      ]);
+    } else {
+      await sleep(waitMs);
+    }
+    const waitedMs = now() - startedAt;
+    if (deps.signal?.aborted) {
+      return { ok: false, content: '等待被中断。', waitedMs, polls: 0 };
+    }
+    return {
+      ok: true,
+      content: `已等待 ${waitMs}ms`,
+      waitedMs,
+      polls: 0,
+    };
+  }
+
+  const timeoutMs = input.timeoutMs ?? WAIT_DEFAULT_TIMEOUT_MS;
+  const startedAt = now();
+
+  let polls = 0;
+  let last: ComputerState | null = null;
+
+  // do-while：**先判一次再睡**。条件已经成立时不该白等一个间隔。
+  do {
+    if (deps.signal?.aborted) {
+      return { ok: false, content: '等待被中断。', waitedMs: now() - startedAt, polls };
+    }
+    polls += 1;
+    last = await deps.observeOnce();
+    if (last) {
+      const verdict = evaluate(input, last);
+      if (verdict.kind === 'hit') {
+        return {
+          ok: true,
+          content: `已等到${requirementOf(input)}：${verdict.description}（用时 ${now() - startedAt}ms）`,
+          ...(verdict.elementId ? { elementId: verdict.elementId } : {}),
+          waitedMs: now() - startedAt,
+          polls,
+        };
+      }
+      if (verdict.kind === 'unavailable') {
+        // 立刻返回，不空转到超时 —— 等下去也不会变成立。
+        return {
+          ok: false,
+          content: `无法等待${requirementOf(input)}：${verdict.reason}`,
+          waitedMs: now() - startedAt,
+          polls,
+        };
+      }
+    }
+    if (now() - startedAt >= timeoutMs) break;
+    await sleep(WAIT_POLL_INTERVAL_MS);
+  } while (now() - startedAt < timeoutMs);
+
+  const waitedMs = now() - startedAt;
+  return {
+    ok: false,
+    content: [
+      `等了 ${waitedMs}ms（${polls} 次观测）仍未出现${requirementOf(input)}。当前实际看到的是：`,
+      ...describeScene(input, last),
+      '别用同样的参数再等一次 —— 要么条件写错了，要么这一步的前置操作没生效。',
+    ].join('\n'),
+    waitedMs,
+    polls,
+  };
+}

package/src/tools/download/download.js

@@ -19,11 +19,13 @@
  *  可测：fetch 经 deps 注入（不连真网）；落盘走真实 fs（测试用 tmp 目录）。
  * ============================================================
  */
-import { mkdir, writeFile } from 'node:fs/promises';
-import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { isAbsolute, join, resolve } from 'node:path';
 import { z } from 'zod';
 import { getWorkingDir } from '../../bootstrap/workingDir.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
+import { fileActivityMetadata } from '../shared/fileActivity.js';
+import { atomicWriteFile } from '../shared/fileUtils.js';
+import { emitFileMutation } from '../shared/fileMutationBus.js';
 const DEFAULT_TIMEOUT_MS = 60_000;
 const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
 // ---------------- 1. Zod 输入 schema ----------------
@@ -70,11 +72,11 @@ const defaultDeps = {
     fetchImpl: globalThis.fetch,
 };
 // ---------------- 3. call() ----------------
-async function call(input, signal, deps = defaultDeps) {
+async function call(input, signal, deps = defaultDeps, cwd = getWorkingDir()) {
     const { url, path } = input;
     const timeout = input.timeout ?? DEFAULT_TIMEOUT_MS;
     const maxBytes = input.max_bytes ?? DEFAULT_MAX_BYTES;
-    const abs = isAbsolute(path) ? path : resolve(join(getWorkingDir(), path));
+    const abs = isAbsolute(path) ? path : resolve(join(cwd, path));
     // 合并外部 signal 与超时
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), timeout);
@@ -118,12 +120,13 @@ async function call(input, signal, deps = defaultDeps) {
                 error: `[Download] 下载 ${buf.byteLength} 字节超过上限 ${maxBytes}（${url}）`,
             };
         }
-        await mkdir(dirname(abs), { recursive: true });
-        await writeFile(abs, buf);
+        await atomicWriteFile(abs, buf);
+        emitFileMutation(abs);
         const ctype = res.headers.get('content-type') ?? 'unknown';
         return {
             ok: true,
             content: `DOWNLOADED: ${buf.byteLength} 字节 → ${abs}（${ctype}）`,
+            metadata: await fileActivityMetadata(abs, 'generated', 'not_run', 'support', cwd),
         };
     }
     finally {
@@ -139,6 +142,7 @@ export const downloadTool = {
     isReadOnly: false,
     isConcurrencySafe: true,
     call,
+    callWithContext: (input, signal, context) => call(input, signal, defaultDeps, context.cwd),
 };
 // 供单测：直接调 call 注入 deps。
 export const _downloadCall = call;

package/src/tools/download/download.ts

@@ -0,0 +1,187 @@
+/**
+ * ============================================================
+ *  src/tools/download/download.ts —— Download 工具（URL → 文件）
+ * ------------------------------------------------------------
+ *  通用基础能力：把一个 URL 的字节流下载落盘。填补 WebFetch（HTML→markdown，
+ *  读文本用）与 Bash（curl/Invoke-WebRequest，跨平台脆）之间的空白——纯 YAML
+ *  工作流要「把图片/资产存盘」时用它（如 illustrate 配图工作流逐图下载候选）。
+ *
+ *  输入：
+ *    url       必填，http(s) 资源地址
+ *    path      必填，落盘路径（相对 getWorkingDir 锚定；绝对路径原样）
+ *    headers   可选，自定义请求头（如 Referer/User-Agent，绕部分防盗链）
+ *    timeout   可选，毫秒，默认 60000（无新字节判死由 fetch/AbortSignal 控）
+ *    max_bytes 可选，体积上限（默认 25MB；超限不写、报错，防失控）
+ *
+ *  输出：成功 = { ok, content: "DOWNLOADED: <bytes> → <path> (<content-type>)" }；
+ *        失败 = { ok:false, error } —— 不抛异常，error 喂回 LLM（同全项目工具约定）。
+ *
+ *  可测：fetch 经 deps 注入（不连真网）；落盘走真实 fs（测试用 tmp 目录）。
+ * ============================================================
+ */
+
+import { isAbsolute, join, resolve } from 'node:path';
+
+import { z } from 'zod';
+
+import type { Tool, ToolCallContext, ToolResult } from '../../types.js';
+import { getWorkingDir } from '../../bootstrap/workingDir.js';
+import { toToolParameters } from '../../utils/zodToJson.js';
+import { fileActivityMetadata } from '../shared/fileActivity.js';
+import { atomicWriteFile } from '../shared/fileUtils.js';
+import { emitFileMutation } from '../shared/fileMutationBus.js';
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_BYTES = 25 * 1024 * 1024;
+
+// ---------------- 1. Zod 输入 schema ----------------
+const inputSchema = z.object({
+  url: z.string().url().describe('http(s) resource URL to download'),
+  path: z
+    .string()
+    .describe('Destination file path (relative paths anchor to the working dir)'),
+  headers: z
+    .record(z.string())
+    .optional()
+    .describe('Optional request headers (e.g. Referer/User-Agent to bypass hotlink guards)'),
+  timeout: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Timeout in milliseconds (default: 60000)'),
+  max_bytes: z
+    .number()
+    .int()
+    .positive()
+    .optional()
+    .describe('Max size in bytes; over this the download is rejected (default: 25MB)'),
+});
+type DownloadInput = z.infer<typeof inputSchema>;
+
+const parameters = toToolParameters(inputSchema);
+
+const description = `Download a URL to a local file (raw bytes).
+
+When to use Download vs WebFetch:
+- WebFetch: read a web page as markdown text (for the model to consume).
+- Download: save the raw bytes of a resource (image / pdf / asset) to disk.
+
+Input parameters:
+  - url (required): http(s) URL.
+  - path (required): destination file path (relative paths anchor to the working dir; parent dirs are created).
+  - headers (optional): request headers (e.g. Referer/User-Agent to bypass hotlink protection).
+  - timeout (optional): milliseconds (default 60000).
+  - max_bytes (optional): reject downloads larger than this (default 25MB).
+
+Notes:
+  - Returns an error (not an exception) on HTTP failure / timeout / oversize.
+  - Overwrites an existing file at path.`;
+
+// ---------------- 2. 依赖注入（仅测试） ----------------
+interface FetchResponseLike {
+  ok: boolean;
+  status: number;
+  statusText: string;
+  headers: { get(name: string): string | null };
+  arrayBuffer(): Promise<ArrayBuffer>;
+}
+type FetchLike = (
+  url: string,
+  init?: { headers?: Record<string, string>; signal?: AbortSignal },
+) => Promise<FetchResponseLike>;
+
+export interface DownloadDeps {
+  fetchImpl: FetchLike;
+}
+
+const defaultDeps: DownloadDeps = {
+  fetchImpl: globalThis.fetch as unknown as FetchLike,
+};
+
+// ---------------- 3. call() ----------------
+async function call(
+  input: DownloadInput,
+  signal?: AbortSignal,
+  deps: DownloadDeps = defaultDeps,
+  cwd = getWorkingDir(),
+): Promise<ToolResult> {
+  const { url, path } = input;
+  const timeout = input.timeout ?? DEFAULT_TIMEOUT_MS;
+  const maxBytes = input.max_bytes ?? DEFAULT_MAX_BYTES;
+
+  const abs = isAbsolute(path) ? path : resolve(join(cwd, path));
+
+  // 合并外部 signal 与超时
+  const ctrl = new AbortController();
+  const timer = setTimeout(() => ctrl.abort(), timeout);
+  if (signal) {
+    if (signal.aborted) ctrl.abort();
+    else signal.addEventListener('abort', () => ctrl.abort(), { once: true });
+  }
+
+  try {
+    let res: FetchResponseLike;
+    try {
+      res = await deps.fetchImpl(url, { headers: input.headers, signal: ctrl.signal });
+    } catch (e) {
+      const msg = ctrl.signal.aborted
+        ? `下载超时（${timeout}ms）或被中断`
+        : e instanceof Error
+          ? e.message
+          : String(e);
+      return { ok: false, error: `[Download] 请求失败：${msg}（${url}）` };
+    }
+
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: `[Download] HTTP ${res.status} ${res.statusText}（${url}）`,
+      };
+    }
+
+    // content-length 预检（有则提前拒绝超大文件，省下载）
+    const declared = Number(res.headers.get('content-length') ?? '');
+    if (Number.isFinite(declared) && declared > maxBytes) {
+      return {
+        ok: false,
+        error: `[Download] 体积 ${declared} 字节超过上限 ${maxBytes}（${url}）`,
+      };
+    }
+
+    const buf = Buffer.from(await res.arrayBuffer());
+    if (buf.byteLength > maxBytes) {
+      return {
+        ok: false,
+        error: `[Download] 下载 ${buf.byteLength} 字节超过上限 ${maxBytes}（${url}）`,
+      };
+    }
+
+    await atomicWriteFile(abs, buf);
+    emitFileMutation(abs);
+
+    const ctype = res.headers.get('content-type') ?? 'unknown';
+    return {
+      ok: true,
+      content: `DOWNLOADED: ${buf.byteLength} 字节 → ${abs}（${ctype}）`,
+      metadata: await fileActivityMetadata(abs, 'generated', 'not_run', 'support', cwd),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+// ---------------- 4. 导出 ----------------
+export const downloadTool: Tool<DownloadInput> = {
+  name: 'Download',
+  description,
+  inputSchema,
+  parameters,
+  isReadOnly: false,
+  isConcurrencySafe: true,
+  call,
+  callWithContext: (input, signal, context: ToolCallContext) => call(input, signal, defaultDeps, context.cwd),
+};
+
+// 供单测：直接调 call 注入 deps。
+export const _downloadCall = call;

package/src/tools/edit/edit.js

@@ -11,15 +11,16 @@
  *    - old_string 找不到时提供模糊匹配提示（最常见模型错误）
  * ============================================================
  */
-import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
-import { dirname } from 'node:path';
 import { z } from 'zod';
 import { DEFAULT_MAX_RESULT_SIZE_CHARS } from '../types.js';
 import { toToolParameters } from '../../utils/zodToJson.js';
-import { resolveToolPath, findActualString, preserveQuoteStyle, detectLineEndingsForString, applyLineEnding, countOccurrences, splitReplaceAll, tryAutoSnapshot, } from '../shared/fileUtils.js';
+import { resolveToolPath, findActualString, preserveQuoteStyle, detectLineEndingsForString, applyLineEnding, countOccurrences, splitReplaceAll, tryAutoSnapshot, atomicWriteFile, encodeTextFile, readTextFile, } from '../shared/fileUtils.js';
 import { filePathField } from '../shared/schemas.js';
-import { assertFresh, recordRead, wasTruncated } from '../shared/fileState.js';
+import { assertFresh, hashFileBytes, recordRead, wasTruncated } from '../shared/fileState.js';
+import { fileActivityMetadata } from '../shared/fileActivity.js';
+import { emitFileMutation } from '../shared/fileMutationBus.js';
+import { buildPatchSummary } from '../shared/diffSummary.js';
 /** 编辑文件大小上限：1GB。防止模型试图 Edit 超大文件撑爆内存。 */
 const MAX_EDIT_FILE_SIZE_BYTES = 1024 * 1024 * 1024;
 // ---------------- 1. Zod 输入 schema ----------------
@@ -50,23 +51,23 @@ Usage:
 - Use \`replace_all\` for replacing and renaming strings across the file. This parameter is useful if you want to rename a variable for instance.
 - Preserve exact indentation (tabs/spaces).`;
 // ---------------- 4. call() ----------------
-async function call(input) {
+async function call(input, state, cwd) {
     const { old_string, new_string } = input;
     const replaceAll = input.replace_all ?? false;
     // 5a. 路径规范化 + 安全校验（含 null byte / UNC / 设备文件拦截 / ~ 展开）
-    const pathResult = resolveToolPath(input.file_path);
+    const pathResult = resolveToolPath(input.file_path, cwd);
     if (!pathResult.ok)
         return pathResult;
     const filePath = pathResult.resolvedPath;
     // 5a-bis. Pre-read guard：文件已存在则必须先 Read（创建新文件场景下 assertFresh 返回 ok:true）
     // 拦截路径自动注入 snippet：让模型在同一轮 tool result 里看到当前内容，无需多绕一次 Read。
     // 安全语义保留：模型必须显式重发 Edit 才会落盘；snippet 只是给模型看的，不静默放行。
-    const freshness = assertFresh(filePath);
+    const freshness = await assertFresh(filePath, {}, state);
     if (!freshness.ok) {
         const snap = await tryAutoSnapshot(filePath);
         if (snap.ok) {
             // 关键：truncated=true 时 wasTruncated 会守住 Write 路径，防止基于残缺 snippet 重写整文件
-            recordRead(filePath, { truncated: snap.truncated });
+            recordRead(filePath, { truncated: snap.truncated, partial: snap.truncated }, state);
             const tail = snap.truncated
                 ? `\n\n⚠️ 仅注入了前 200 行（文件共 ${snap.totalLines} 行 / 上限 32KB）。若要改的位置在范围外，请显式 Read offset=X limit=Y 后再 Edit。`
                 : '';
@@ -93,12 +94,14 @@ async function call(input) {
     // 5b. 创建新文件路径：old_string === '' 且文件不存在
     if (old_string === '' && !existsSync(filePath)) {
         try {
-            await mkdir(dirname(filePath), { recursive: true });
-            await writeFile(filePath, new_string, 'utf8');
-            recordRead(filePath);
+            await atomicWriteFile(filePath, new_string);
+            recordRead(filePath, { contentHash: hashFileBytes(encodeTextFile(new_string, 'utf8')) }, state);
+            emitFileMutation(filePath);
+            const patch = buildPatchSummary('', new_string, input.file_path);
             return {
                 ok: true,
-                content: `已创建新文件：${filePath}（${new_string.length} 字符）`,
+                content: `已创建新文件：${filePath}（${new_string.length} 字符）\n${patch.unifiedDiff ?? '[diff omitted: too large]'}`,
+                metadata: await fileActivityMetadata(filePath, 'created', 'not_run', 'support', cwd, patch),
             };
         }
         catch (e) {
@@ -113,8 +116,11 @@ async function call(input) {
         };
     }
     let original;
+    let sourceEncoding;
     try {
-        original = await readFile(filePath, 'utf8');
+        const snapshot = await readTextFile(filePath);
+        original = snapshot.content;
+        sourceEncoding = snapshot.encoding;
     }
     catch (e) {
         return { ok: false, error: `读取失败：${e.message}` };
@@ -146,7 +152,7 @@ async function call(input) {
     }
     // splitCount = 出现次数
     const occurrences = countOccurrences(original, searchTarget);
-    const truncHint = wasTruncated(filePath)
+    const truncHint = wasTruncated(filePath, state)
         ? `\n\n⚠️ 上次 Read 该文件时被截断了（只看到部分内容）。当前 old_string 可能在截断范围外。请用更小的 limit + offset 精确读取目标行号附近后再 Edit。`
         : '';
     if (occurrences === 0) {
@@ -170,8 +176,11 @@ async function call(input) {
     // 5f. 保持原文件行尾符风格
     const normalizedReplaced = applyLineEnding(replaced, originalLineEnding);
     try {
-        await writeFile(filePath, normalizedReplaced, 'utf8');
-        recordRead(filePath);
+        await atomicWriteFile(filePath, normalizedReplaced, sourceEncoding);
+        recordRead(filePath, {
+            contentHash: hashFileBytes(encodeTextFile(normalizedReplaced, sourceEncoding)),
+        }, state);
+        emitFileMutation(filePath);
     }
     catch (e) {
         return { ok: false, error: `写入失败：${e.message}` };
@@ -179,11 +188,13 @@ async function call(input) {
     // 输出：报告改了几处 + 行变化
     const linesBefore = original.split('\n').length;
     const linesAfter = replaced.split('\n').length;
+    const patch = buildPatchSummary(original, normalizedReplaced, input.file_path);
     return {
         ok: true,
         content: `已编辑 ${filePath}\n` +
             `替换次数：${replaceAll ? occurrences : 1}\n` +
-            `行数：${linesBefore} → ${linesAfter}`,
+            `行数：${linesBefore} → ${linesAfter}\n` + (patch.unifiedDiff ?? '[diff omitted: too large]'),
+        metadata: await fileActivityMetadata(filePath, 'modified', 'not_run', 'support', cwd, patch),
     };
 }
 // ---------------- 5. 模糊匹配提示 ----------------
@@ -277,5 +288,6 @@ export const editTool = {
     isConcurrencySafe: false,
     maxResultSizeChars: DEFAULT_MAX_RESULT_SIZE_CHARS,
     interruptBehavior: () => 'block',
-    call,
+    call: (input) => call(input),
+    callWithContext: (input, _signal, context) => call(input, context.sessionState?.fileReads, context.cwd),
 };