@bubblebrain-ai/bubble 0.0.4 → 0.0.6

package/dist/tools/agent-lifecycle.js

@@ -0,0 +1,355 @@
+import { discoverAgentProfiles, findAgentProfile } from "../agent/profiles.js";
+export function createSpawnAgentTool() {
+    return {
+        name: "spawn_agent",
+        readOnly: true,
+        effect: "read",
+        description: [
+            "Start a child subagent in the background and return its agent_id plus random nickname.",
+            "Use this for Codex-style delegation. The child has an independent thread; call wait_agent later to collect its result.",
+            "When the user asks to use a subagent, spawn first with a clear task instead of doing the delegated investigation yourself.",
+            "After spawning, do not duplicate the same delegated work locally; either wait for the child or do clearly non-overlapping work.",
+            "agent_type defaults to default. Built-in types include default, explorer, and worker.",
+        ].join(" "),
+        parameters: {
+            type: "object",
+            properties: {
+                agent_type: { type: "string", description: "Subagent profile or role name. Defaults to default." },
+                agent: { type: "string", description: "Alias for agent_type." },
+                message: { type: "string", description: "Initial task for the subagent." },
+                task: { type: "string", description: "Alias for message." },
+                fork_context: { type: "boolean", description: "When true, copy recent parent conversation into the child thread." },
+                agentScope: {
+                    type: "string",
+                    enum: ["user", "project", "both"],
+                    description: "Which profile locations to load. Defaults to user profiles plus built-ins.",
+                },
+                allowProjectAgents: {
+                    type: "boolean",
+                    description: "Required to run profiles loaded from project-local .bubble/agents.",
+                },
+                approval: {
+                    type: "string",
+                    enum: ["fail", "disabled"],
+                    description: "How this child handles tools that need interactive approval.",
+                },
+            },
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.spawnSubAgent) {
+                return toolRuntimeMissing("spawn_agent");
+            }
+            const message = stringArg(args.message) ?? stringArg(args.task);
+            if (!message) {
+                return { content: "Error: spawn_agent requires message or task.", isError: true };
+            }
+            const profileName = stringArg(args.agent_type) ?? stringArg(args.agent) ?? "default";
+            const resolved = resolveProfile(ctx.cwd, profileName, parseScope(args.agentScope), args.allowProjectAgents === true);
+            if ("error" in resolved)
+                return resolved.error;
+            if (resolved.profile.mode !== "readonly") {
+                return unsupportedProfile(resolved.profile);
+            }
+            try {
+                const snapshot = await ctx.agent.spawnSubAgent(message, ctx.cwd, {
+                    profile: resolved.profile,
+                    parentToolCallId: ctx.toolCall?.id ?? snapshotFallbackId(),
+                    approval: parseApproval(args.approval),
+                    abortSignal: ctx.abortSignal,
+                    forkContext: args.fork_context === true,
+                });
+                return formatLifecycleResult("spawn_agent", [snapshot], [
+                    `Spawned ${snapshot.nickname} (${snapshot.agentName})`,
+                    `agent_id: ${snapshot.agentId}`,
+                    `status: ${snapshot.status}`,
+                    `next: call wait_agent for ${snapshot.agentId} to collect the delegated result`,
+                ]);
+            }
+            catch (error) {
+                return toolError("spawn_agent", error);
+            }
+        },
+    };
+}
+export function createWaitAgentTool() {
+    return {
+        name: "wait_agent",
+        readOnly: true,
+        effect: "read",
+        description: [
+            "Wait for one or more spawned subagents to reach a final status and return snapshots.",
+            "If the wait times out while children are still running, call wait_agent again with a longer timeout instead of redoing the same delegated work locally.",
+        ].join(" "),
+        parameters: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string", description: "A single agent id to wait for." },
+                agent_ids: {
+                    type: "array",
+                    description: "Agent ids to wait for. If omitted, waits for any active subagent.",
+                    items: { type: "string" },
+                },
+                timeout_ms: { type: "number", description: "Maximum wait time in milliseconds. Defaults to 30000." },
+            },
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.waitSubAgents) {
+                return toolRuntimeMissing("wait_agent");
+            }
+            const agentIds = normalizeAgentIds(args.agent_ids, args.agent_id);
+            try {
+                const snapshots = await ctx.agent.waitSubAgents({
+                    agentIds,
+                    timeoutMs: typeof args.timeout_ms === "number" ? args.timeout_ms : undefined,
+                });
+                if (snapshots.length === 0) {
+                    return {
+                        content: "No subagents reached a final status before the timeout.",
+                        status: "timeout",
+                        metadata: { kind: "subagent", mode: "lifecycle", subagents: [] },
+                    };
+                }
+                if (snapshots.some((snapshot) => !isFinalSnapshotStatus(snapshot.status))) {
+                    return formatLifecycleResult("wait_agent", snapshots, [
+                        "wait_agent timed out before a delegated result was ready.",
+                        "The subagent is still running; call wait_agent again with a longer timeout instead of duplicating the same work locally.",
+                        "",
+                        ...snapshots.flatMap((snapshot) => [...formatSnapshot(snapshot), ""]),
+                    ]);
+                }
+                return formatLifecycleResult("wait_agent", snapshots);
+            }
+            catch (error) {
+                return toolError("wait_agent", error);
+            }
+        },
+    };
+}
+export function createSendInputTool() {
+    return {
+        name: "send_input",
+        readOnly: true,
+        effect: "read",
+        description: "Send a follow-up message to an existing subagent thread. If it is still running, pass interrupt:true to cancel and redirect it.",
+        parameters: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string", description: "Target subagent id." },
+                message: { type: "string", description: "Follow-up message." },
+                task: { type: "string", description: "Alias for message." },
+                interrupt: { type: "boolean", description: "Cancel a running child before applying this input." },
+            },
+            required: ["agent_id"],
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.sendSubAgentInput) {
+                return toolRuntimeMissing("send_input");
+            }
+            const agentId = stringArg(args.agent_id);
+            const message = stringArg(args.message) ?? stringArg(args.task);
+            if (!agentId || !message) {
+                return { content: "Error: send_input requires agent_id and message.", isError: true };
+            }
+            try {
+                const snapshot = await ctx.agent.sendSubAgentInput(agentId, message, ctx.cwd, {
+                    interrupt: args.interrupt === true,
+                    parentToolCallId: ctx.toolCall?.id,
+                    abortSignal: ctx.abortSignal,
+                });
+                return formatLifecycleResult("send_input", [snapshot], [
+                    `Sent input to ${snapshot.nickname} (${snapshot.agentName})`,
+                    `agent_id: ${snapshot.agentId}`,
+                    `status: ${snapshot.status}`,
+                ]);
+            }
+            catch (error) {
+                return toolError("send_input", error);
+            }
+        },
+    };
+}
+export function createCloseAgentTool() {
+    return {
+        name: "close_agent",
+        readOnly: true,
+        effect: "read",
+        description: "Close a spawned subagent only when the delegated task is cancelled, stale, or no longer needed. Running children are cancelled before closing; do not close a child just because you started doing the same delegated work locally.",
+        parameters: {
+            type: "object",
+            properties: {
+                agent_id: { type: "string", description: "Subagent id to close." },
+            },
+            required: ["agent_id"],
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            if (!ctx.agent?.closeSubAgent) {
+                return toolRuntimeMissing("close_agent");
+            }
+            const agentId = stringArg(args.agent_id);
+            if (!agentId) {
+                return { content: "Error: close_agent requires agent_id.", isError: true };
+            }
+            try {
+                const snapshot = await ctx.agent.closeSubAgent(agentId);
+                return formatLifecycleResult("close_agent", [snapshot], [
+                    `Closed ${snapshot.nickname} (${snapshot.agentName})`,
+                    `agent_id: ${snapshot.agentId}`,
+                    `status: ${snapshot.status}`,
+                ]);
+            }
+            catch (error) {
+                return toolError("close_agent", error);
+            }
+        },
+    };
+}
+export function createAgentLifecycleTools() {
+    return [
+        createSpawnAgentTool(),
+        createWaitAgentTool(),
+        createSendInputTool(),
+        createCloseAgentTool(),
+    ];
+}
+function resolveProfile(cwd, name, scope, allowProjectAgents) {
+    const discovered = discoverAgentProfiles(cwd, scope);
+    const profile = findAgentProfile(discovered.profiles, name);
+    if (!profile) {
+        const available = discovered.profiles.map((item) => item.name).sort().join(", ") || "none";
+        return {
+            error: {
+                content: `Error: unknown subagent profile "${name}". Available profiles: ${available}`,
+                isError: true,
+            },
+        };
+    }
+    if (profile.source === "project" && !allowProjectAgents) {
+        return {
+            error: {
+                content: [
+                    `Blocked: subagent profile "${profile.name}" was loaded from project-local .bubble/agents.`,
+                    "Pass allowProjectAgents: true only when you trust this repository's agent profile prompts.",
+                ].join("\n"),
+                isError: true,
+                status: "blocked",
+            },
+        };
+    }
+    return { profile };
+}
+function formatLifecycleResult(toolName, snapshots, header) {
+    const lines = header ?? [`${toolName}: ${snapshots.length} subagent${snapshots.length === 1 ? "" : "s"}`];
+    if (!header)
+        lines.push("");
+    if (!header) {
+        for (const snapshot of snapshots) {
+            lines.push(...formatSnapshot(snapshot), "");
+        }
+    }
+    return {
+        content: lines.join("\n").trim(),
+        status: lifecycleStatus(toolName, snapshots),
+        isError: snapshots.length > 0 && snapshots.every((snapshot) => snapshot.status === "failed" || snapshot.status === "blocked"),
+        metadata: {
+            kind: "subagent",
+            mode: "lifecycle",
+            subagents: snapshots.map(snapshotToMetadata),
+        },
+    };
+}
+function lifecycleStatus(toolName, snapshots) {
+    if (toolName === "spawn_agent" || toolName === "send_input" || toolName === "close_agent") {
+        return "success";
+    }
+    if (snapshots.some((snapshot) => !isFinalSnapshotStatus(snapshot.status))) {
+        return "timeout";
+    }
+    return snapshots.every((snapshot) => snapshot.status === "completed" || snapshot.status === "closed") ? "success" : "partial";
+}
+function isFinalSnapshotStatus(status) {
+    return status === "completed"
+        || status === "failed"
+        || status === "blocked"
+        || status === "cancelled"
+        || status === "closed";
+}
+function formatSnapshot(snapshot) {
+    const label = `${snapshot.nickname} (${snapshot.agentName})`;
+    const lines = [
+        `## ${label}`,
+        `agent_id: ${snapshot.agentId}`,
+        `status: ${snapshot.status}`,
+        `task: ${snapshot.task}`,
+    ];
+    if (snapshot.summary) {
+        lines.push("", "Summary:", snapshot.summary);
+    }
+    else if (snapshot.status === "completed") {
+        lines.push("", "Summary: (no final text summary was produced)");
+    }
+    if (snapshot.toolNotes.length > 0) {
+        lines.push("", "Recent tool notes:", ...snapshot.toolNotes.slice(-8).map((note) => `- ${note}`));
+    }
+    if (snapshot.error) {
+        lines.push("", `Error: ${snapshot.error}`);
+    }
+    return lines;
+}
+function snapshotToMetadata(snapshot) {
+    return {
+        subAgentId: snapshot.agentId,
+        agentName: snapshot.agentName,
+        nickname: snapshot.nickname,
+        status: snapshot.status === "closed" ? "cancelled" : snapshot.status,
+        profileSource: snapshot.profileSource,
+        task: snapshot.task,
+        summary: snapshot.summary,
+        toolNotes: snapshot.toolNotes,
+        usage: snapshot.usage,
+        error: snapshot.error,
+    };
+}
+function unsupportedProfile(profile) {
+    return {
+        content: `Error: subagent profile "${profile.name}" uses mode "${profile.mode}", but this runtime only supports readonly lifecycle subagents.`,
+        isError: true,
+        status: "blocked",
+    };
+}
+function parseScope(value) {
+    return value === "project" || value === "both" ? value : "user";
+}
+function parseApproval(value) {
+    return value === "fail" || value === "disabled" ? value : undefined;
+}
+function normalizeAgentIds(value, single) {
+    const out = [];
+    if (typeof single === "string" && single.trim())
+        out.push(single.trim());
+    if (Array.isArray(value)) {
+        for (const item of value) {
+            if (typeof item === "string" && item.trim())
+                out.push(item.trim());
+        }
+    }
+    return out.length > 0 ? [...new Set(out)] : undefined;
+}
+function stringArg(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function snapshotFallbackId() {
+    return `spawn_${Date.now().toString(36)}`;
+}
+function toolRuntimeMissing(name) {
+    return { content: `Error: ${name} requires an agent runtime`, isError: true };
+}
+function toolError(name, error) {
+    return {
+        content: `Error executing ${name}: ${error?.message || String(error)}`,
+        isError: true,
+    };
+}

package/dist/tools/bash.d.ts

@@ -3,4 +3,5 @@
  */
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";
-export declare function createBashTool(cwd: string, approval?: ApprovalController): ToolRegistryEntry;
+import type { FileStateTracker } from "./file-state.js";
+export declare function createBashTool(cwd: string, approval?: ApprovalController, _fileState?: FileStateTracker): ToolRegistryEntry;

package/dist/tools/bash.js

@@ -8,9 +8,11 @@ import { gateToolAction } from "../approval/tool-helper.js";
 import { parseReadBashCommand, parseSearchBashCommand } from "../agent/tool-intent.js";
 import { referencesSensitivePath } from "./sensitive-paths.js";
 const MAX_OUTPUT = 50 * 1024;
-export function createBashTool(cwd, approval) {
+export function createBashTool(cwd, approval, _fileState) {
     return {
         name: "bash",
+        effect: "unknown",
+        requiresApproval: true,
         description: "Execute a bash command in the working directory. Use timeout for long-running commands.",
         parameters: {
             type: "object",

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

@@ -0,0 +1,25 @@
+export interface EditOperation {
+    oldText: string;
+    newText: string;
+}
+export type EditMatchMode = "exact" | "normalized-line";
+export interface EditMatchInfo {
+    editIndex: number;
+    mode: EditMatchMode;
+    start: number;
+    end: number;
+}
+export interface AppliedEditResult {
+    content: string;
+    normalizedOriginal: string;
+    normalizedNext: string;
+    bom: string;
+    lineEnding: "\n" | "\r\n";
+    matches: EditMatchInfo[];
+}
+export declare class EditApplyError extends Error {
+    readonly status: "no_match" | "blocked";
+    constructor(message: string, status?: "no_match" | "blocked");
+}
+export declare function applyEditsToContent(rawContent: string, edits: EditOperation[]): AppliedEditResult;
+export declare function formatEditMatchNotes(matches: EditMatchInfo[]): string;

package/dist/tools/edit-apply.js

@@ -0,0 +1,228 @@
+export class EditApplyError extends Error {
+    status;
+    constructor(message, status = "no_match") {
+        super(message);
+        this.status = status;
+        this.name = "EditApplyError";
+    }
+}
+function detectLineEnding(content) {
+    const crlf = content.indexOf("\r\n");
+    const lf = content.indexOf("\n");
+    return crlf !== -1 && crlf === lf - 1 ? "\r\n" : "\n";
+}
+function stripBom(content) {
+    return content.startsWith("\uFEFF") ? { bom: "\uFEFF", text: content.slice(1) } : { bom: "", text: content };
+}
+function normalizeToLF(text) {
+    return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+function restoreLineEndings(text, lineEnding) {
+    return lineEnding === "\r\n" ? text.replace(/\n/g, "\r\n") : text;
+}
+function normalizeLineForMatch(line) {
+    return line
+        .normalize("NFKC")
+        .trimEnd()
+        .replace(/[\u2018\u2019\u201A\u201B]/g, "'")
+        .replace(/[\u201C\u201D\u201E\u201F]/g, '"')
+        .replace(/[\u2010\u2011\u2012\u2013\u2014\u2015\u2212]/g, "-")
+        .replace(/[\u00A0\u2002-\u200A\u202F\u205F\u3000]/g, " ");
+}
+function findAllOccurrences(content, needle) {
+    const indexes = [];
+    if (needle.length === 0)
+        return indexes;
+    let index = content.indexOf(needle);
+    while (index !== -1) {
+        indexes.push(index);
+        index = content.indexOf(needle, index + needle.length);
+    }
+    return indexes;
+}
+function splitLines(content) {
+    const lines = [];
+    let start = 0;
+    for (let i = 0; i < content.length; i++) {
+        if (content[i] === "\n") {
+            lines.push({ text: content.slice(start, i), start, endNoNewline: i });
+            start = i + 1;
+        }
+    }
+    lines.push({ text: content.slice(start), start, endNoNewline: content.length });
+    return lines;
+}
+function nonBlankLines(lines) {
+    const result = [];
+    for (let i = 0; i < lines.length; i++) {
+        const normalized = normalizeLineForMatch(lines[i].text);
+        if (normalized.trim().length > 0) {
+            result.push({ lineIndex: i, normalized });
+        }
+    }
+    return result;
+}
+function normalizedOldNonBlankLines(oldText) {
+    return splitLines(oldText)
+        .map((line) => normalizeLineForMatch(line.text))
+        .filter((line) => line.trim().length > 0);
+}
+function findNormalizedLineMatches(content, oldText) {
+    const contentLines = splitLines(content);
+    const searchable = nonBlankLines(contentLines);
+    const oldLines = normalizedOldNonBlankLines(oldText);
+    if (oldLines.length === 0)
+        return [];
+    const matches = [];
+    for (let i = 0; i <= searchable.length - oldLines.length; i++) {
+        let matched = true;
+        for (let j = 0; j < oldLines.length; j++) {
+            if (searchable[i + j].normalized !== oldLines[j]) {
+                matched = false;
+                break;
+            }
+        }
+        if (matched) {
+            const first = contentLines[searchable[i].lineIndex];
+            const last = contentLines[searchable[i + oldLines.length - 1].lineIndex];
+            matches.push({ start: first.start, end: last.endNoNewline });
+        }
+    }
+    return matches;
+}
+function summarizeOldText(oldText) {
+    const firstLine = normalizeToLF(oldText).split("\n").find((line) => line.trim().length > 0) ?? oldText;
+    return firstLine.length > 80 ? `${firstLine.slice(0, 80)}...` : firstLine;
+}
+function findBestLineHint(content, oldText) {
+    const oldLines = normalizedOldNonBlankLines(oldText);
+    if (oldLines.length === 0)
+        return undefined;
+    const contentLines = nonBlankLines(splitLines(content));
+    let best;
+    for (let i = 0; i < contentLines.length; i++) {
+        let score = 0;
+        for (let j = 0; j < oldLines.length && i + j < contentLines.length; j++) {
+            if (contentLines[i + j].normalized === oldLines[j])
+                score++;
+        }
+        if (!best || score > best.score)
+            best = { index: i, score };
+    }
+    if (!best || best.score === 0)
+        return undefined;
+    const startLine = contentLines[best.index].lineIndex + 1;
+    return `Closest line-based candidate starts near line ${startLine} and matched ${best.score}/${oldLines.length} non-blank lines.`;
+}
+function matchEdit(content, edit, index, total) {
+    if (edit.oldText.length === 0) {
+        throw new EditApplyError(total === 1 ? "Error: oldText must not be empty." : `Error: edits[${index}].oldText must not be empty.`);
+    }
+    if (edit.oldText === edit.newText) {
+        const header = total === 1
+            ? "Error: This edit is a no-op because oldText and newText are byte-identical."
+            : `Error: edits[${index}] is a no-op because oldText and newText are byte-identical.`;
+        throw new EditApplyError([
+            header,
+            "",
+            "Common causes and how to escape:",
+            "- Your tokenizer may be folding repeated characters into a single token (hex colors like '#ec489' vs '#ec4899', repeated digits, etc.). The two strings feel different in your head but serialize to identical bytes.",
+            "- Use the write tool with overwrite=true and the full new content for full-file replacements that hinge on a single repeated character or trailing digit.",
+            "- Or re-read the file with the read tool, then copy the exact bytes you want to replace before retrying.",
+        ].join("\n"));
+    }
+    const oldText = normalizeToLF(edit.oldText);
+    const exact = findAllOccurrences(content, oldText);
+    if (exact.length === 1) {
+        return { editIndex: index, mode: "exact", start: exact[0], end: exact[0] + oldText.length };
+    }
+    if (exact.length > 1) {
+        const recovery = [
+            "",
+            "Extend oldText with more surrounding context (the lines immediately before/after) until it uniquely identifies the intended span.",
+        ].join("\n");
+        throw new EditApplyError(total === 1
+            ? `Error: oldText appears ${exact.length} times in file. Must be unique: "${summarizeOldText(oldText)}"${recovery}`
+            : `Error: edits[${index}].oldText appears ${exact.length} times in file. Must be unique: "${summarizeOldText(oldText)}"${recovery}`);
+    }
+    const normalizedLineMatches = findNormalizedLineMatches(content, oldText);
+    if (normalizedLineMatches.length === 1) {
+        return {
+            editIndex: index,
+            mode: "normalized-line",
+            start: normalizedLineMatches[0].start,
+            end: normalizedLineMatches[0].end,
+        };
+    }
+    if (normalizedLineMatches.length > 1) {
+        throw new EditApplyError(total === 1
+            ? `Error: oldText matched ${normalizedLineMatches.length} normalized line blocks in file. Provide more surrounding context.`
+            : `Error: edits[${index}].oldText matched ${normalizedLineMatches.length} normalized line blocks in file. Provide more surrounding context.`);
+    }
+    const hint = findBestLineHint(content, oldText);
+    const hintSuffix = hint ? `\n${hint}` : "";
+    const recovery = [
+        "",
+        "How to recover:",
+        "- Re-read the file with the read tool to see its current bytes; the file may have been changed by a prior edit this turn.",
+        "- Shorten oldText to a smaller unique anchor and try again. Long multi-line anchors are fragile to whitespace and indentation.",
+        "- If many lines need to change, use the write tool with overwrite=true and the full new content instead of stacking edits.",
+    ].join("\n");
+    throw new EditApplyError(total === 1
+        ? `Error: oldText not found in file: "${summarizeOldText(oldText)}"${hintSuffix}${recovery}`
+        : `Error: edits[${index}].oldText not found in file: "${summarizeOldText(oldText)}"${hintSuffix}${recovery}`);
+}
+function assertNoOverlaps(matches) {
+    const sorted = [...matches].sort((a, b) => a.start - b.start);
+    for (let i = 1; i < sorted.length; i++) {
+        const previous = sorted[i - 1];
+        const current = sorted[i];
+        if (previous.end > current.start) {
+            throw new EditApplyError(`Error: edits[${previous.editIndex}] and edits[${current.editIndex}] overlap in file. Merge them into one edit or target disjoint regions.`, "blocked");
+        }
+    }
+}
+export function applyEditsToContent(rawContent, edits) {
+    if (!Array.isArray(edits) || edits.length === 0) {
+        throw new EditApplyError("Error: No edits provided");
+    }
+    const { bom, text } = stripBom(rawContent);
+    const lineEnding = detectLineEnding(text);
+    const normalizedOriginal = normalizeToLF(text);
+    const normalizedEdits = edits.map((edit) => ({
+        oldText: normalizeToLF(edit.oldText),
+        newText: normalizeToLF(edit.newText),
+    }));
+    const matches = normalizedEdits.map((edit, index) => matchEdit(normalizedOriginal, edit, index, normalizedEdits.length));
+    assertNoOverlaps(matches);
+    const byDescendingStart = [...matches].sort((a, b) => b.start - a.start);
+    let normalizedNext = normalizedOriginal;
+    for (const match of byDescendingStart) {
+        const edit = normalizedEdits[match.editIndex];
+        normalizedNext = normalizedNext.slice(0, match.start) + edit.newText + normalizedNext.slice(match.end);
+    }
+    if (normalizedNext === normalizedOriginal) {
+        throw new EditApplyError([
+            "Error: No changes made. The replacement produced identical content.",
+            "",
+            "Common causes and how to escape:",
+            "- oldText and newText are byte-identical. Verify newText actually contains the intended change (a missing trailing char like turning '#ec489' into '#ec4899' is a frequent culprit).",
+            "- The file already contains newText. Re-read the file to confirm the current state before editing again.",
+            "- For wholesale rewrites, use the write tool with overwrite=true and the full new content instead.",
+        ].join("\n"));
+    }
+    return {
+        content: bom + restoreLineEndings(normalizedNext, lineEnding),
+        normalizedOriginal,
+        normalizedNext,
+        bom,
+        lineEnding,
+        matches,
+    };
+}
+export function formatEditMatchNotes(matches) {
+    const normalizedCount = matches.filter((match) => match.mode !== "exact").length;
+    if (normalizedCount === 0)
+        return "";
+    return `\n\nNote: ${normalizedCount} edit${normalizedCount === 1 ? "" : "s"} applied using normalized line matching for whitespace/formatting differences.`;
+}

package/dist/tools/edit.d.ts

@@ -6,6 +6,7 @@
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";
 import { type LspService } from "../lsp/index.js";
+import { type FileStateTracker } from "./file-state.js";
 export interface EditArgs {
     path: string;
     edits: Array<{
@@ -13,4 +14,4 @@ export interface EditArgs {
         newText: string;
     }>;
 }
-export declare function createEditTool(cwd: string, approval?: ApprovalController, lsp?: LspService): ToolRegistryEntry;
+export declare function createEditTool(cwd: string, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker): ToolRegistryEntry;