@armadra/agent 0.0.0-stage → 0.2.1

package/dist/tools/bash.js

@@ -0,0 +1,222 @@
+/**
+ * `bash` 工具（设计 §5.2、§4.2）。[B3]
+ *
+ * - `spawn(shell, args, { detached: !win, stdio: [ignore, pipe, pipe] })`，stdout / stderr 合流；
+ * - 超时（缺省 120 s，上限 600 s）与 abort 都走 `killProcessTree`：SIGTERM → 2 s → SIGKILL；
+ * - 滚动尾部节流后经 `ctx.onUpdate` 流出；超限（2000 行 / 50 KB）尾截断并落全文；
+ * - 结构化结果 `{ output, exit_code, truncated, full_output_path?, wall_time_seconds }`；
+ *   信号退出 `128 + signo`；非零退出码 → isError；
+ * - 注入 `AMA_*` 环境变量（shell.ts）。shell 退出后不等仍占着管道的后台进程。
+ */
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import { join } from "node:path";
+import { resolvePath } from "./paths.js";
+import { buildShellArgs, buildToolEnv, resolveShell } from "./shell.js";
+import { exitCodeOf, isGroupAlive, killProcessTree, trackProcessGroup, untrackProcessGroup, } from "./process-tree.js";
+import { OutputAccumulator } from "./output-accumulator.js";
+import { formatSize, resolveOutputDir, safeFileName } from "./truncate.js";
+export const DEFAULT_BASH_TIMEOUT_MS = 120_000;
+export const MAX_BASH_TIMEOUT_MS = 600_000;
+const UPDATE_THROTTLE_MS = 100;
+/** shell 退出后等管道关闭的上限（后台子进程可能一直占着）。 */
+const STDIO_DRAIN_MS = 200;
+function fail(message) {
+    return { content: message, isError: true };
+}
+/** 等 shell 退出；之后最多再等 STDIO_DRAIN_MS 让管道读完，再强制关闭。 */
+function waitForExit(child) {
+    return new Promise((resolve, reject) => {
+        let exit;
+        let settled = false;
+        const done = () => {
+            if (settled || exit === undefined)
+                return;
+            settled = true;
+            resolve(exit);
+        };
+        child.once("error", (err) => {
+            if (!settled) {
+                settled = true;
+                reject(err);
+            }
+        });
+        child.once("close", (code, signal) => {
+            exit ??= { code, signal };
+            done();
+        });
+        child.once("exit", (code, signal) => {
+            exit = { code, signal };
+            setTimeout(() => {
+                child.stdout?.destroy();
+                child.stderr?.destroy();
+                done();
+            }, STDIO_DRAIN_MS).unref();
+        });
+    });
+}
+export async function executeBash(input, ctx, options = {}) {
+    if (typeof input.command !== "string" || input.command.trim() === "") {
+        return fail("command must be a non-empty string");
+    }
+    const timeoutMs = input.timeoutMs ?? options.defaultTimeoutMs ?? DEFAULT_BASH_TIMEOUT_MS;
+    if (!Number.isFinite(timeoutMs) || timeoutMs <= 0 || timeoutMs > MAX_BASH_TIMEOUT_MS) {
+        return fail(`timeoutMs must be between 1 and ${MAX_BASH_TIMEOUT_MS}`);
+    }
+    const cwd = resolvePath(input.cwd ?? ".", ctx.cwd);
+    try {
+        if (!(await stat(cwd)).isDirectory())
+            return fail(`Working directory is not a directory: ${cwd}`);
+    }
+    catch {
+        return fail(`Working directory does not exist: ${cwd}`);
+    }
+    if (ctx.signal.aborted)
+        return fail("aborted by user");
+    const shell = options.shell ? options.shell() : resolveShell();
+    const env = buildToolEnv(options.baseEnv ? options.baseEnv() : process.env, {
+        sessionId: ctx.sessionId,
+        sessionFile: ctx.sessionFile,
+        provider: ctx.model?.provider,
+        model: ctx.model?.id,
+        thinkingLevel: ctx.thinkingLevel,
+        depth: ctx.depth,
+    });
+    const isWindows = (options.processDeps?.platform ?? process.platform) === "win32";
+    const started = Date.now();
+    const acc = new OutputAccumulator({
+        spillPath: () => join(resolveOutputDir(ctx.outputDir), safeFileName(`bash-${ctx.toolCallId}.log`)),
+    });
+    let child;
+    try {
+        child = spawn(shell.shell, buildShellArgs(shell, input.command), {
+            cwd,
+            env,
+            detached: !isWindows,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+    }
+    catch (err) {
+        return fail(`Failed to start shell ${shell.shell}: ${err.message}`);
+    }
+    const pid = child.pid;
+    if (pid !== undefined && !isWindows)
+        trackProcessGroup(pid);
+    let lastUpdate = 0;
+    let pendingUpdate;
+    const emitUpdate = () => {
+        pendingUpdate = undefined;
+        lastUpdate = Date.now();
+        ctx.onUpdate(acc.tail());
+    };
+    const onData = (chunk) => {
+        acc.append(chunk);
+        if (pendingUpdate)
+            return;
+        const wait = Math.max(0, lastUpdate + UPDATE_THROTTLE_MS - Date.now());
+        pendingUpdate = setTimeout(emitUpdate, wait);
+    };
+    child.stdout?.on("data", onData);
+    child.stderr?.on("data", onData);
+    let timedOut = false;
+    let aborted = false;
+    let killing;
+    const kill = () => {
+        if (pid === undefined)
+            return;
+        killing ??= killProcessTree(pid, options.processDeps);
+    };
+    const timer = setTimeout(() => {
+        timedOut = true;
+        kill();
+    }, timeoutMs);
+    const onAbort = () => {
+        aborted = true;
+        kill();
+    };
+    ctx.signal.addEventListener("abort", onAbort, { once: true });
+    let exit;
+    try {
+        exit = await waitForExit(child);
+    }
+    catch (err) {
+        return fail(`Failed to run command with ${shell.shell}: ${err.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+        ctx.signal.removeEventListener("abort", onAbort);
+        if (pendingUpdate) {
+            // 冲掉节流中的最后一次更新，保证 UI 看到的尾部是完整的。
+            clearTimeout(pendingUpdate);
+            emitUpdate();
+        }
+    }
+    const killedWithSigkill = killing ? await killing : false;
+    // 后台子进程仍在组里时保持登记，进程退出时一并清理。
+    if (pid !== undefined && !isWindows && !isGroupAlive(pid))
+        untrackProcessGroup(pid);
+    const out = acc.finish();
+    const exitCode = exitCodeOf(exit.code, exit.signal);
+    const wall = Math.round((Date.now() - started) / 10) / 100;
+    const structured = {
+        output: out.output,
+        exit_code: exitCode,
+        truncated: out.truncated,
+        ...(out.fullOutputPath !== undefined ? { full_output_path: out.fullOutputPath } : {}),
+        wall_time_seconds: wall,
+    };
+    const details = {
+        ...structured,
+        timedOut,
+        aborted,
+        killedWithSigkill,
+        totalLines: out.totalLines,
+        totalBytes: out.totalBytes,
+        cwd,
+        ...(input.description !== undefined ? { description: input.description } : {}),
+    };
+    const parts = [out.output === "" ? "(no output)" : out.output];
+    if (out.truncated) {
+        const where = out.fullOutputPath ? ` Full output: ${out.fullOutputPath}` : "";
+        parts.push(`[Output truncated: showing the last ${out.outputLines} of ${out.totalLines} lines ` +
+            `(${formatSize(out.totalBytes)} total).${where}]`);
+    }
+    if (aborted)
+        parts.push("aborted by user");
+    else if (timedOut)
+        parts.push(`[Command timed out after ${timeoutMs} ms and was killed]`);
+    if (exitCode !== 0)
+        parts.push(`[exit code: ${exitCode}]`);
+    return {
+        content: parts.join("\n\n"),
+        isError: exitCode !== 0 || timedOut || aborted,
+        structured,
+        details,
+    };
+}
+export function createBashTool(options = {}) {
+    return {
+        name: "bash",
+        label: "Bash",
+        description: "Run a shell command. stdout+stderr combined; over 2000 lines or 50 KB keeps the tail " +
+            "and saves the full output to a file. " +
+            `Timeout default ${DEFAULT_BASH_TIMEOUT_MS} ms, max ${MAX_BASH_TIMEOUT_MS} ms.`,
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string" },
+                timeoutMs: { type: "integer" },
+                cwd: { type: "string", description: "Default: session cwd" },
+                description: { type: "string", description: "What this does, briefly" },
+            },
+            required: ["command"],
+            additionalProperties: false,
+        },
+        permission: "execute",
+        executionMode: "sequential",
+        annotations: { destructive: true, openWorld: true },
+        promptSnippet: "bash: run shell commands (AMA_* env vars describe the session)",
+        execute: (input, ctx) => executeBash(input, ctx, options),
+    };
+}

package/dist/tools/edit-fuzzy.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 文本归一与模糊匹配（设计 §5.2 edit：先精确再模糊）。[B3]
+ *
+ * - BOM / 换行：`splitBom`、`detectLineEnding`、`normalizeToLF`、`restoreLineEndings`，write 与
+ *   edit 共用，保证写回时保留原文件的 BOM 与 CRLF。
+ * - 模糊归一 `normalizeForFuzzy`：NFKC、去行尾空白、弯引号 / 各种破折号 / 特殊空格归 ASCII。
+ *   归一**不改变行数**，所以模糊匹配在归一空间算出的替换可以按行映射回原文：
+ *   `applyPreservingLines()` 只重写被替换触及的行，其余行逐字节保留原文。
+ */
+export declare const BOM = "\uFEFF";
+export declare function splitBom(text: string): {
+    bom: string;
+    text: string;
+};
+/** 以第一处换行为准；无换行视为 LF。 */
+export declare function detectLineEnding(text: string): "\r\n" | "\n";
+export declare function normalizeToLF(text: string): string;
+export declare function restoreLineEndings(text: string, ending: "\r\n" | "\n"): string;
+export declare function normalizeForFuzzy(text: string): string;
+/** 不重叠的全部出现位置。 */
+export declare function findAll(haystack: string, needle: string): number[];
+/** 偏移量所在行（1 起）。 */
+export declare function lineNumberAt(text: string, index: number): number;
+export interface Replacement {
+    /** 在基准文本中的起点与长度。 */
+    index: number;
+    length: number;
+    newText: string;
+}
+/** 按起点倒序应用（调用方保证不重叠）。 */
+export declare function applyReplacements(base: string, replacements: readonly Replacement[]): string;
+/**
+ * `base` 是 `original` 的模糊归一视图（同行数）。替换在 base 上算出；被触及的行组从 base 改写，
+ * 其余行原样拷回 original，避免把整份文件的行尾空白、弯引号一并改掉。
+ */
+export declare function applyPreservingLines(original: string, base: string, replacements: readonly Replacement[]): string;

package/dist/tools/edit-fuzzy.js

@@ -0,0 +1,129 @@
+/**
+ * 文本归一与模糊匹配（设计 §5.2 edit：先精确再模糊）。[B3]
+ *
+ * - BOM / 换行：`splitBom`、`detectLineEnding`、`normalizeToLF`、`restoreLineEndings`，write 与
+ *   edit 共用，保证写回时保留原文件的 BOM 与 CRLF。
+ * - 模糊归一 `normalizeForFuzzy`：NFKC、去行尾空白、弯引号 / 各种破折号 / 特殊空格归 ASCII。
+ *   归一**不改变行数**，所以模糊匹配在归一空间算出的替换可以按行映射回原文：
+ *   `applyPreservingLines()` 只重写被替换触及的行，其余行逐字节保留原文。
+ */
+export const BOM = "\uFEFF";
+export function splitBom(text) {
+    return text.startsWith(BOM) ? { bom: BOM, text: text.slice(1) } : { bom: "", text };
+}
+/** 以第一处换行为准；无换行视为 LF。 */
+export function detectLineEnding(text) {
+    const lf = text.indexOf("\n");
+    if (lf === -1)
+        return "\n";
+    return lf > 0 && text[lf - 1] === "\r" ? "\r\n" : "\n";
+}
+export function normalizeToLF(text) {
+    return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+export function restoreLineEndings(text, ending) {
+    return ending === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+export function normalizeForFuzzy(text) {
+    return text
+        .normalize("NFKC")
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        .replace(/[\u2018\u2019\u201A\u201B\u2032]/g, "'")
+        .replace(/[\u201C\u201D\u201E\u201F\u2033]/g, '"')
+        .replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
+        .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
+}
+/** 不重叠的全部出现位置。 */
+export function findAll(haystack, needle) {
+    const out = [];
+    if (needle === "")
+        return out;
+    let from = 0;
+    for (;;) {
+        const idx = haystack.indexOf(needle, from);
+        if (idx === -1)
+            return out;
+        out.push(idx);
+        from = idx + needle.length;
+    }
+}
+/** 偏移量所在行（1 起）。 */
+export function lineNumberAt(text, index) {
+    let line = 1;
+    for (let i = 0; i < index && i < text.length; i++)
+        if (text.charCodeAt(i) === 10)
+            line++;
+    return line;
+}
+/** 按起点倒序应用（调用方保证不重叠）。 */
+export function applyReplacements(base, replacements) {
+    const sorted = [...replacements].sort((a, b) => b.index - a.index);
+    let out = base;
+    for (const r of sorted)
+        out = out.slice(0, r.index) + r.newText + out.slice(r.index + r.length);
+    return out;
+}
+function lineSpans(text) {
+    const spans = [];
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10) {
+            spans.push({ start, end: i + 1 });
+            start = i + 1;
+        }
+    }
+    if (start < text.length || text.length === 0)
+        spans.push({ start, end: text.length });
+    return spans;
+}
+function lineIndexOf(spans, offset) {
+    for (let i = 0; i < spans.length; i++) {
+        const s = spans[i];
+        if (offset >= s.start && offset < s.end)
+            return i;
+    }
+    return spans.length - 1;
+}
+/**
+ * `base` 是 `original` 的模糊归一视图（同行数）。替换在 base 上算出；被触及的行组从 base 改写，
+ * 其余行原样拷回 original，避免把整份文件的行尾空白、弯引号一并改掉。
+ */
+export function applyPreservingLines(original, base, replacements) {
+    const origSpans = lineSpans(original);
+    const baseSpans = lineSpans(base);
+    if (origSpans.length !== baseSpans.length)
+        return applyReplacements(base, replacements);
+    const groups = [];
+    for (const r of [...replacements].sort((a, b) => a.index - b.index)) {
+        const first = lineIndexOf(baseSpans, r.index);
+        const last = lineIndexOf(baseSpans, Math.max(r.index, r.index + r.length - 1));
+        const current = groups[groups.length - 1];
+        if (current && first <= current.last) {
+            current.last = Math.max(current.last, last);
+            current.items.push(r);
+        }
+        else {
+            groups.push({ first, last, items: [r] });
+        }
+    }
+    let out = "";
+    let nextLine = 0;
+    for (const g of groups) {
+        for (let i = nextLine; i < g.first; i++) {
+            const s = origSpans[i];
+            out += original.slice(s.start, s.end);
+        }
+        const gStart = baseSpans[g.first].start;
+        const gEnd = baseSpans[g.last].end;
+        const local = g.items.map((r) => ({ ...r, index: r.index - gStart }));
+        out += applyReplacements(base.slice(gStart, gEnd), local);
+        nextLine = g.last + 1;
+    }
+    for (let i = nextLine; i < origSpans.length; i++) {
+        const s = origSpans[i];
+        out += original.slice(s.start, s.end);
+    }
+    return out;
+}

package/dist/tools/edit.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `edit` 工具（设计 §5.2）。[B3]
+ *
+ * - 每处 `oldText` 都在**原文**上匹配，必须唯一（`replaceAll` 例外）且互不重叠；
+ * - 先精确匹配；任一处精确匹配失败则整批转入模糊空间（edit-fuzzy.ts），只改写被触及的行；
+ * - 不唯一 → 错误里给出现次数与首两处行号；
+ * - 保留 BOM 与 CRLF；要求先 read；`details.diff` 是统一 diff（给 TUI）。
+ */
+import type { ToolContext, ToolDefinition, ToolResult } from "./types.js";
+export interface EditOp {
+    oldText: string;
+    newText: string;
+}
+export interface EditInput {
+    path: string;
+    edits: EditOp[];
+    replaceAll?: boolean;
+}
+export interface EditDetails {
+    path: string;
+    diff: string;
+    replacements: number;
+    fuzzy: boolean;
+    firstChangedLine: number;
+}
+export declare class EditError extends Error {
+}
+export interface EditPlan {
+    result: string;
+    replacements: number;
+    fuzzy: boolean;
+}
+/** 在 LF 归一后的内容上计算替换结果；失败抛 EditError。 */
+export declare function planEdits(content: string, edits: readonly EditOp[], replaceAll?: boolean): EditPlan;
+/** 统一 diff（LF 文本，3 行上下文）；无差异返回空串。 */
+export declare function unifiedDiff(oldText: string, newText: string, path: string, context?: number): string;
+export declare function executeEdit(input: EditInput, ctx: ToolContext): Promise<ToolResult>;
+export declare function createEditTool(): ToolDefinition<EditInput>;

package/dist/tools/edit.js

@@ -0,0 +1,241 @@
+/**
+ * `edit` 工具（设计 §5.2）。[B3]
+ *
+ * - 每处 `oldText` 都在**原文**上匹配，必须唯一（`replaceAll` 例外）且互不重叠；
+ * - 先精确匹配；任一处精确匹配失败则整批转入模糊空间（edit-fuzzy.ts），只改写被触及的行；
+ * - 不唯一 → 错误里给出现次数与首两处行号；
+ * - 保留 BOM 与 CRLF；要求先 read；`details.diff` 是统一 diff（给 TUI）。
+ */
+import { readFile, stat, writeFile } from "node:fs/promises";
+import { displayPath, resolvePath } from "./paths.js";
+import { withFileMutex } from "./file-mutex.js";
+import { applyPreservingLines, applyReplacements, detectLineEnding, findAll, lineNumberAt, normalizeForFuzzy, normalizeToLF, restoreLineEndings, splitBom, } from "./edit-fuzzy.js";
+export class EditError extends Error {
+}
+function label(index, total) {
+    return total === 1 ? "oldText" : `edits[${index}].oldText`;
+}
+/** 在 LF 归一后的内容上计算替换结果；失败抛 EditError。 */
+export function planEdits(content, edits, replaceAll = false) {
+    if (edits.length === 0)
+        throw new EditError("edits must contain at least one item");
+    const ops = edits.map((e, i) => {
+        if (typeof e.oldText !== "string" || typeof e.newText !== "string") {
+            throw new EditError(`edits[${i}] needs string oldText and newText`);
+        }
+        if (e.oldText === "")
+            throw new EditError(`${label(i, edits.length)} must not be empty`);
+        return { oldText: normalizeToLF(e.oldText), newText: normalizeToLF(e.newText) };
+    });
+    const fuzzy = ops.some((op) => !content.includes(op.oldText));
+    const base = fuzzy ? normalizeForFuzzy(content) : content;
+    const reps = [];
+    ops.forEach((op, i) => {
+        const needle = fuzzy ? normalizeForFuzzy(op.oldText) : op.oldText;
+        const hits = needle === "" ? [] : findAll(base, needle);
+        if (hits.length === 0) {
+            throw new EditError(`Could not find ${label(i, ops.length)} in the file. It must match the current content ` +
+                "exactly, including whitespace and line breaks.");
+        }
+        if (hits.length > 1 && !replaceAll) {
+            const lines = hits.slice(0, 2).map((h) => lineNumberAt(base, h));
+            throw new EditError(`${label(i, ops.length)} matches ${hits.length} times (first at lines ${lines.join(" and ")}). ` +
+                "Add surrounding context to make it unique, or set replaceAll.");
+        }
+        for (const index of replaceAll ? hits : hits.slice(0, 1)) {
+            reps.push({ index, length: needle.length, newText: op.newText, edit: i });
+        }
+    });
+    const sorted = [...reps].sort((a, b) => a.index - b.index);
+    for (let i = 1; i < sorted.length; i++) {
+        const prev = sorted[i - 1];
+        const cur = sorted[i];
+        if (prev.index + prev.length > cur.index) {
+            throw new EditError(`edits[${prev.edit}] and edits[${cur.edit}] overlap; merge them into a single edit`);
+        }
+    }
+    const result = fuzzy ? applyPreservingLines(content, base, reps) : applyReplacements(base, reps);
+    if (result === content)
+        throw new EditError("The edits produced no change to the file");
+    return { result, replacements: reps.length, fuzzy };
+}
+function diffOps(a, b) {
+    let pre = 0;
+    while (pre < a.length && pre < b.length && a[pre] === b[pre])
+        pre++;
+    let suf = 0;
+    while (suf < a.length - pre &&
+        suf < b.length - pre &&
+        a[a.length - 1 - suf] === b[b.length - 1 - suf]) {
+        suf++;
+    }
+    const ops = [];
+    for (let i = 0; i < pre; i++)
+        ops.push({ kind: " ", text: a[i], a: i, b: i });
+    const am = a.slice(pre, a.length - suf);
+    const bm = b.slice(pre, b.length - suf);
+    if (am.length * bm.length <= 4_000_000) {
+        // LCS 动态规划（中段通常很小）。
+        const w = bm.length + 1;
+        const dp = new Uint32Array((am.length + 1) * w);
+        for (let i = am.length - 1; i >= 0; i--) {
+            for (let j = bm.length - 1; j >= 0; j--) {
+                dp[i * w + j] =
+                    am[i] === bm[j]
+                        ? (dp[(i + 1) * w + j + 1] ?? 0) + 1
+                        : Math.max(dp[(i + 1) * w + j] ?? 0, dp[i * w + j + 1] ?? 0);
+            }
+        }
+        let i = 0;
+        let j = 0;
+        while (i < am.length || j < bm.length) {
+            if (i < am.length && j < bm.length && am[i] === bm[j]) {
+                ops.push({ kind: " ", text: am[i], a: pre + i, b: pre + j });
+                i++;
+                j++;
+            }
+            else if (i < am.length &&
+                (j >= bm.length || (dp[(i + 1) * w + j] ?? 0) >= (dp[i * w + j + 1] ?? 0))) {
+                ops.push({ kind: "-", text: am[i], a: pre + i, b: pre + j });
+                i++;
+            }
+            else {
+                ops.push({ kind: "+", text: bm[j], a: pre + i, b: pre + j });
+                j++;
+            }
+        }
+    }
+    else {
+        am.forEach((t, i) => ops.push({ kind: "-", text: t, a: pre + i, b: pre }));
+        bm.forEach((t, j) => ops.push({ kind: "+", text: t, a: pre + am.length, b: pre + j }));
+    }
+    for (let k = 0; k < suf; k++) {
+        const ai = a.length - suf + k;
+        ops.push({ kind: " ", text: a[ai], a: ai, b: b.length - suf + k });
+    }
+    return ops;
+}
+function toLines(text) {
+    if (text === "")
+        return [];
+    const lines = text.split("\n");
+    if (lines[lines.length - 1] === "")
+        lines.pop();
+    return lines;
+}
+/** 统一 diff（LF 文本，3 行上下文）；无差异返回空串。 */
+export function unifiedDiff(oldText, newText, path, context = 3) {
+    const ops = diffOps(toLines(oldText), toLines(newText));
+    const changed = ops.map((op, i) => (op.kind === " " ? -1 : i)).filter((i) => i >= 0);
+    if (changed.length === 0)
+        return "";
+    const hunks = [];
+    for (const idx of changed) {
+        const start = Math.max(0, idx - context);
+        const end = Math.min(ops.length, idx + context + 1);
+        const last = hunks[hunks.length - 1];
+        if (last && start <= last.end)
+            last.end = Math.max(last.end, end);
+        else
+            hunks.push({ start, end });
+    }
+    const out = [`--- a/${path}`, `+++ b/${path}`];
+    for (const h of hunks) {
+        const slice = ops.slice(h.start, h.end);
+        const first = slice[0];
+        const aCount = slice.filter((o) => o.kind !== "+").length;
+        const bCount = slice.filter((o) => o.kind !== "-").length;
+        const aStart = aCount === 0 ? first.a : first.a + 1;
+        const bStart = bCount === 0 ? first.b : first.b + 1;
+        out.push(`@@ -${aStart},${aCount} +${bStart},${bCount} @@`);
+        for (const o of slice)
+            out.push(`${o.kind}${o.text}`);
+    }
+    return out.join("\n");
+}
+function firstChangedLine(oldText, newText) {
+    const a = oldText.split("\n");
+    const b = newText.split("\n");
+    let i = 0;
+    while (i < a.length && i < b.length && a[i] === b[i])
+        i++;
+    return i + 1;
+}
+// ---------------------------------------------------------------------------
+// 工具
+// ---------------------------------------------------------------------------
+export async function executeEdit(input, ctx) {
+    const abs = resolvePath(input.path, ctx.cwd);
+    const shown = displayPath(abs, ctx.cwd);
+    return withFileMutex(abs, async () => {
+        try {
+            const info = await stat(abs);
+            if (!info.isFile())
+                return { content: `${shown} is not a regular file`, isError: true };
+        }
+        catch {
+            return { content: `File not found: ${shown}`, isError: true };
+        }
+        if (!ctx.readFiles.has(abs)) {
+            return { content: `Read ${shown} with the read tool before editing it.`, isError: true };
+        }
+        const raw = await readFile(abs, "utf8");
+        const { bom, text } = splitBom(raw);
+        const ending = detectLineEnding(text);
+        const content = normalizeToLF(text);
+        let plan;
+        try {
+            plan = planEdits(content, input.edits ?? [], input.replaceAll === true);
+        }
+        catch (err) {
+            if (err instanceof EditError)
+                return { content: `${shown}: ${err.message}`, isError: true };
+            throw err;
+        }
+        await writeFile(abs, bom + restoreLineEndings(plan.result, ending), "utf8");
+        const details = {
+            path: abs,
+            diff: unifiedDiff(content, plan.result, shown),
+            replacements: plan.replacements,
+            fuzzy: plan.fuzzy,
+            firstChangedLine: firstChangedLine(content, plan.result),
+        };
+        const note = plan.fuzzy ? " (matched after whitespace/quote normalization)" : "";
+        const count = `${plan.replacements} replacement${plan.replacements === 1 ? "" : "s"}`;
+        return { content: `Edited ${shown}: ${count}${note}`, details };
+    });
+}
+export function createEditTool() {
+    return {
+        name: "edit",
+        label: "Edit",
+        description: "Replace text in a file (read it first). Each oldText must be unique in the original " +
+            "(unless replaceAll); edits must not overlap.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string" },
+                edits: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            oldText: { type: "string", description: "Exact text to replace" },
+                            newText: { type: "string" },
+                        },
+                        required: ["oldText", "newText"],
+                        additionalProperties: false,
+                    },
+                },
+                replaceAll: { type: "boolean" },
+            },
+            required: ["path", "edits"],
+            additionalProperties: false,
+        },
+        permission: "write",
+        executionMode: "sequential",
+        annotations: { destructive: true },
+        promptSnippet: "edit: replace text in a file",
+        execute: executeEdit,
+    };
+}

package/dist/tools/file-mutex.d.ts

@@ -0,0 +1,8 @@
+/**
+ * 按路径串行化读 - 改 - 写（设计 §1.2）。[B3]
+ *
+ * 同一绝对路径上的 write / edit 排队执行；不同路径互不阻塞。前一个失败不影响后一个。
+ */
+export declare function withFileMutex<T>(path: string, fn: () => Promise<T>): Promise<T>;
+/** 当前持有队列的路径数（测试用）。 */
+export declare function pendingMutexCount(): number;