@bubblebrain-ai/bubble 0.0.4 → 0.0.6

package/dist/tools/edit.js

@@ -9,10 +9,15 @@ import { resolve } from "node:path";
 import { createTwoFilesPatch } from "diff";
 import { gateToolAction } from "../approval/tool-helper.js";
 import { formatDiagnosticBlocks } from "../lsp/index.js";
-export function createEditTool(cwd, approval, lsp) {
+import { applyEditsToContent, EditApplyError, formatEditMatchNotes } from "./edit-apply.js";
+import { withFileMutationQueue } from "./file-mutation-queue.js";
+import { isWithinWorkspace } from "./file-state.js";
+export function createEditTool(cwd, approval, lsp, fileState) {
     return {
         name: "edit",
-        description: "Apply targeted string replacements to a file. Each oldText must match exactly once. All edits apply to the original file contents simultaneously.",
+        effect: "write_direct",
+        requiresApproval: true,
+        description: "Apply targeted string replacements to a file. Prefer exact oldText. The tool can tolerate line ending, trailing whitespace, Unicode punctuation/space, and blank-line differences only when the target is unique.",
         parameters: {
             type: "object",
             properties: {
@@ -34,67 +39,81 @@ export function createEditTool(cwd, approval, lsp) {
         },
         async execute(args) {
             const filePath = resolve(cwd, args.path);
-            try {
-                await access(filePath, constants.R_OK | constants.W_OK);
-            }
-            catch {
-                return { content: `Error: Cannot read/write file: ${filePath}`, isError: true };
-            }
-            const original = await readFile(filePath, "utf-8");
-            let content = original;
-            const edits = args.edits;
-            if (!Array.isArray(edits) || edits.length === 0) {
-                return { content: "Error: No edits provided", isError: true };
+            if (!isWithinWorkspace(cwd, filePath)) {
+                return {
+                    content: `Error: Edit path is outside the workspace: ${filePath}`,
+                    isError: true,
+                    status: "blocked",
+                    metadata: {
+                        kind: "security",
+                        path: filePath,
+                        reason: "Edit path is outside the workspace.",
+                    },
+                };
             }
-            // Validate each oldText exists exactly once
-            for (const edit of edits) {
-                const count = content.split(edit.oldText).length - 1;
-                if (count === 0) {
-                    return {
-                        content: `Error: oldText not found in file: "${edit.oldText.slice(0, 50)}..."`,
-                        isError: true,
-                    };
+            return withFileMutationQueue(filePath, async () => {
+                try {
+                    await access(filePath, constants.R_OK | constants.W_OK);
                 }
-                if (count > 1) {
-                    return {
-                        content: `Error: oldText appears ${count} times in file. Must be unique: "${edit.oldText.slice(0, 50)}..."`,
-                        isError: true,
-                    };
+                catch {
+                    return { content: `Error: Cannot read/write file: ${filePath}`, isError: true };
                 }
-            }
-            // Apply all edits in-memory to compute the proposed next content + diff.
-            for (const edit of edits) {
-                content = content.replace(edit.oldText, edit.newText);
-            }
-            const diff = createTwoFilesPatch(filePath, filePath, original, content, "original", "modified", { context: 3 });
-            // Gate on the approval controller BEFORE persisting the change.
-            const gate = await gateToolAction(approval, {
-                type: "edit",
-                path: filePath,
-                diff,
-                fileExists: true,
-            });
-            if (!gate.approved)
-                return gate.result;
-            await writeFile(filePath, content, "utf-8");
-            let output = `Edited ${filePath}\n\nDiff:\n${diff}`;
-            if (lsp) {
+                const original = await readFile(filePath, "utf-8");
+                let applied;
                 try {
-                    await lsp.touchFile(filePath, "document");
-                    output += formatDiagnosticBlocks(cwd, filePath, lsp.diagnostics());
+                    applied = applyEditsToContent(original, args.edits);
                 }
-                catch {
-                    // LSP diagnostics should not turn a successful edit into a failed tool call.
+                catch (err) {
+                    if (err instanceof EditApplyError) {
+                        return { content: err.message, isError: true, status: err.status };
+                    }
+                    throw err;
                 }
-            }
-            return {
-                content: output,
-                status: "success",
-                metadata: {
-                    kind: "edit",
+                const diff = createTwoFilesPatch(filePath, filePath, original, applied.content, "original", "modified", { context: 3 });
+                // Gate on the approval controller BEFORE persisting the change.
+                const gate = await gateToolAction(approval, {
+                    type: "edit",
                     path: filePath,
-                },
-            };
+                    diff,
+                    fileExists: true,
+                });
+                if (!gate.approved)
+                    return gate.result;
+                const latest = await readFile(filePath, "utf-8");
+                if (latest !== original) {
+                    return {
+                        content: `Error: Cannot safely edit ${filePath} because it changed while approval was pending.\n\n`
+                            + "Re-read the file and retry the edit against the latest content.",
+                        isError: true,
+                        status: "blocked",
+                        metadata: {
+                            kind: "security",
+                            path: filePath,
+                            reason: "changed",
+                        },
+                    };
+                }
+                await writeFile(filePath, applied.content, "utf-8");
+                await fileState?.observe(filePath, "edit", applied.content).catch(() => undefined);
+                let output = `Edited ${filePath}${formatEditMatchNotes(applied.matches)}\n\nDiff:\n${diff}`;
+                if (lsp) {
+                    try {
+                        await lsp.touchFile(filePath, "document");
+                        output += formatDiagnosticBlocks(cwd, filePath, lsp.diagnostics());
+                    }
+                    catch {
+                        // LSP diagnostics should not turn a successful edit into a failed tool call.
+                    }
+                }
+                return {
+                    content: output,
+                    status: "success",
+                    metadata: {
+                        kind: "edit",
+                        path: filePath,
+                    },
+                };
+            });
         },
     };
 }

package/dist/tools/exit-plan-mode.js

@@ -9,7 +9,9 @@ export function createExitPlanModeTool(controller) {
     return {
         name: "exit_plan_mode",
         readOnly: true,
-        description: "ONLY call this tool when the harness has told you (via a <system-reminder>) that plan mode is ACTIVE. " +
+        effect: "read",
+        requiresApproval: true,
+        description: "ONLY call this tool when the harness has told you via a runtime reminder that plan mode is ACTIVE. " +
             "Do NOT call it during ordinary work — in default mode you should just use the regular tools directly. " +
             "In plan mode: after investigating, call this with a concrete step-by-step plan so the user can approve, edit, or reject. " +
             "Approval automatically switches the agent out of plan mode.",

package/dist/tools/file-mutation-queue.d.ts

@@ -0,0 +1 @@
+export declare function withFileMutationQueue<T>(filePath: string, fn: () => Promise<T>): Promise<T>;

package/dist/tools/file-mutation-queue.js

@@ -0,0 +1,32 @@
+import { realpathSync } from "node:fs";
+import { resolve } from "node:path";
+const queues = new Map();
+function queueKey(filePath) {
+    const resolved = resolve(filePath);
+    try {
+        return realpathSync.native(resolved);
+    }
+    catch {
+        return resolved;
+    }
+}
+export async function withFileMutationQueue(filePath, fn) {
+    const key = queueKey(filePath);
+    const current = queues.get(key) ?? Promise.resolve();
+    let release;
+    const next = new Promise((resolveNext) => {
+        release = resolveNext;
+    });
+    const chained = current.then(() => next);
+    queues.set(key, chained);
+    await current;
+    try {
+        return await fn();
+    }
+    finally {
+        release();
+        if (queues.get(key) === chained) {
+            queues.delete(key);
+        }
+    }
+}

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

@@ -0,0 +1,25 @@
+export type FileObservationSource = "read" | "write" | "edit";
+export interface FileVersion {
+    hash: string;
+    mtimeMs: number;
+    size: number;
+}
+export type FileFreshnessResult = {
+    ok: true;
+    version: FileVersion;
+} | {
+    ok: false;
+    reason: "unobserved" | "missing" | "changed";
+    observed?: FileVersion;
+    current?: FileVersion;
+};
+export declare class FileStateTracker {
+    private readonly cwd;
+    private readonly observed;
+    constructor(cwd: string);
+    observe(filePath: string, source: FileObservationSource, content?: string): Promise<FileVersion>;
+    checkFresh(filePath: string): Promise<FileFreshnessResult>;
+    private resolvePath;
+    private computeVersion;
+}
+export declare function isWithinWorkspace(cwd: string, filePath: string): boolean;

package/dist/tools/file-state.js

@@ -0,0 +1,52 @@
+import { createHash } from "node:crypto";
+import { stat, readFile } from "node:fs/promises";
+import { isAbsolute, relative, resolve } from "node:path";
+export class FileStateTracker {
+    cwd;
+    observed = new Map();
+    constructor(cwd) {
+        this.cwd = cwd;
+    }
+    async observe(filePath, source, content) {
+        const absolute = this.resolvePath(filePath);
+        const version = await this.computeVersion(absolute, content);
+        this.observed.set(absolute, { ...version, source, observedAt: Date.now() });
+        return version;
+    }
+    async checkFresh(filePath) {
+        const absolute = this.resolvePath(filePath);
+        const observed = this.observed.get(absolute);
+        if (!observed) {
+            return { ok: false, reason: "unobserved" };
+        }
+        let current;
+        try {
+            current = await this.computeVersion(absolute);
+        }
+        catch {
+            return { ok: false, reason: "missing", observed };
+        }
+        if (current.hash === observed.hash && current.size === observed.size) {
+            return { ok: true, version: current };
+        }
+        return { ok: false, reason: "changed", observed, current };
+    }
+    resolvePath(filePath) {
+        return resolve(this.cwd, filePath);
+    }
+    async computeVersion(filePath, content) {
+        const [stats, bytes] = await Promise.all([
+            stat(filePath),
+            content === undefined ? readFile(filePath) : Promise.resolve(Buffer.from(content, "utf-8")),
+        ]);
+        return {
+            hash: createHash("sha256").update(bytes).digest("hex"),
+            mtimeMs: stats.mtimeMs,
+            size: stats.size,
+        };
+    }
+}
+export function isWithinWorkspace(cwd, filePath) {
+    const rel = relative(resolve(cwd), filePath);
+    return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}

package/dist/tools/glob.js

@@ -20,6 +20,7 @@ export function createGlobTool(cwd) {
     return {
         name: "glob",
         readOnly: true,
+        effect: "read",
         description: `Find files by glob pattern without using the shell. Use this for project structure discovery and filename searches. Returns up to ${MAX_RESULTS} files sorted by recent modification time.`,
         parameters: {
             type: "object",

package/dist/tools/grep.js

@@ -10,6 +10,7 @@ export function createGrepTool(cwd) {
     return {
         name: "grep",
         readOnly: true,
+        effect: "read",
         description: `Search file contents using regex (via ripgrep). Use this instead of running grep, rg, or ripgrep through bash. Returns up to ${MAX_MATCHES} matches.`,
         parameters: {
             type: "object",

package/dist/tools/index.d.ts

@@ -11,7 +11,7 @@ export { createLspTool } from "./lsp.js";
 export { createWebFetchTool } from "./web-fetch.js";
 export { createWebSearchTool } from "./web-search.js";
 export { createSkillTool } from "./skill.js";
-export { createTaskTool } from "./task.js";
+export { createAgentLifecycleTools, createCloseAgentTool, createSendInputTool, createSpawnAgentTool, createWaitAgentTool } from "./agent-lifecycle.js";
 export { createTodoTool, type TodoStore } from "./todo.js";
 export { createExitPlanModeTool, type PlanController } from "./exit-plan-mode.js";
 export { createToolSearchTool, type ToolSearchController } from "./tool-search.js";
@@ -25,6 +25,7 @@ import { type LspService } from "../lsp/index.js";
 import { type TodoStore } from "./todo.js";
 import { type ToolSearchController } from "./tool-search.js";
 import type { QuestionController } from "../question/index.js";
+import { FileStateTracker } from "./file-state.js";
 export interface CreateAllToolsOptions {
     todoStore?: TodoStore;
     planController?: PlanController;
@@ -32,5 +33,6 @@ export interface CreateAllToolsOptions {
     questionController?: QuestionController;
     toolSearchController?: ToolSearchController;
     lspService?: LspService;
+    fileStateTracker?: FileStateTracker;
 }
 export declare function createAllTools(cwd: string, skillRegistry?: SkillRegistry, options?: CreateAllToolsOptions): ToolRegistryEntry[];

package/dist/tools/index.js

@@ -11,7 +11,7 @@ export { createLspTool } from "./lsp.js";
 export { createWebFetchTool } from "./web-fetch.js";
 export { createWebSearchTool } from "./web-search.js";
 export { createSkillTool } from "./skill.js";
-export { createTaskTool } from "./task.js";
+export { createAgentLifecycleTools, createCloseAgentTool, createSendInputTool, createSpawnAgentTool, createWaitAgentTool } from "./agent-lifecycle.js";
 export { createTodoTool } from "./todo.js";
 export { createExitPlanModeTool } from "./exit-plan-mode.js";
 export { createToolSearchTool } from "./tool-search.js";
@@ -26,7 +26,7 @@ import { getLspService } from "../lsp/index.js";
 import { createLspTool } from "./lsp.js";
 import { createReadTool } from "./read.js";
 import { createSkillTool } from "./skill.js";
-import { createTaskTool } from "./task.js";
+import { createAgentLifecycleTools } from "./agent-lifecycle.js";
 import { createTodoTool } from "./todo.js";
 import { createToolSearchTool } from "./tool-search.js";
 import { createWebFetchTool } from "./web-fetch.js";
@@ -34,14 +34,16 @@ import { createWebSearchTool } from "./web-search.js";
 import { createWriteTool } from "./write.js";
 import { createQuestionTool } from "./question.js";
 import { createMemoryReadSummaryTool, createMemorySearchTool } from "./memory.js";
+import { FileStateTracker } from "./file-state.js";
 export function createAllTools(cwd, skillRegistry, options = {}) {
     const approval = options.approvalController;
     const lsp = options.lspService ?? getLspService(cwd);
+    const fileState = options.fileStateTracker ?? new FileStateTracker(cwd);
     return [
-        createReadTool(cwd, approval, lsp),
-        createBashTool(cwd, approval),
-        createWriteTool(cwd, { refuseOverwrite: true }, approval, lsp),
-        createEditTool(cwd, approval, lsp),
+        createReadTool(cwd, approval, lsp, fileState),
+        createBashTool(cwd, approval, fileState),
+        createWriteTool(cwd, { refuseOverwrite: true }, approval, lsp, fileState),
+        createEditTool(cwd, approval, lsp, fileState),
         createGlobTool(cwd),
         createGrepTool(cwd),
         createLspTool(cwd, lsp, approval),
@@ -49,7 +51,7 @@ export function createAllTools(cwd, skillRegistry, options = {}) {
         createWebFetchTool(approval),
         createMemorySearchTool(cwd),
         createMemoryReadSummaryTool(cwd),
-        createTaskTool(),
+        ...createAgentLifecycleTools(),
         ...(options.questionController ? [createQuestionTool(options.questionController)] : []),
         ...(skillRegistry ? [createSkillTool(skillRegistry)] : []),
         ...(options.todoStore ? [createTodoTool(options.todoStore)] : []),

package/dist/tools/lsp.js

@@ -18,6 +18,8 @@ export function createLspTool(cwd, lsp = getLspService(cwd), approval) {
     return {
         name: "lsp",
         readOnly: true,
+        effect: "read",
+        requiresApproval: true,
         description: "Use the language server for code navigation. Supports goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, prepareCallHierarchy, incomingCalls, and outgoingCalls.",
         parameters: {
             type: "object",

package/dist/tools/memory.js

@@ -5,6 +5,7 @@ export function createMemorySearchTool(cwd) {
         name: "memory_search",
         description: "Search persistent Bubble memory for prior project facts, user preferences, workflows, decisions, and gotchas.",
         readOnly: true,
+        effect: "read",
         parameters: {
             type: "object",
             properties: {
@@ -56,6 +57,7 @@ export function createMemoryReadSummaryTool(cwd) {
         name: "memory_read_summary",
         description: "Read the concise persistent memory summary for the current project, global scope, or both.",
         readOnly: true,
+        effect: "read",
         parameters: {
             type: "object",
             properties: {

package/dist/tools/question.js

@@ -3,6 +3,8 @@ export function createQuestionTool(controller) {
     return {
         name: "question",
         readOnly: true,
+        effect: "read",
+        requiresApproval: true,
         description: `Ask the user one or more structured questions during execution.
 
 Use this when you need to:

package/dist/tools/read.d.ts

@@ -4,4 +4,5 @@
 import type { ApprovalController } from "../approval/types.js";
 import type { ToolRegistryEntry } from "../types.js";
 import type { LspService } from "../lsp/index.js";
-export declare function createReadTool(cwd: string, approval?: ApprovalController, lsp?: LspService): ToolRegistryEntry;
+import type { FileStateTracker } from "./file-state.js";
+export declare function createReadTool(cwd: string, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker): ToolRegistryEntry;

package/dist/tools/read.js

@@ -7,10 +7,11 @@ import { resolve } from "node:path";
 import { isSensitivePath } from "./sensitive-paths.js";
 const MAX_LINES = 250;
 const MAX_BYTES = 100 * 1024;
-export function createReadTool(cwd, approval, lsp) {
+export function createReadTool(cwd, approval, lsp, fileState) {
     return {
         name: "read",
         readOnly: true,
+        effect: "read",
         description: `Read the contents of a file. Output is truncated to ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB (whichever is hit first). Use offset/limit for large files.`,
         parameters: {
             type: "object",
@@ -69,6 +70,10 @@ export function createReadTool(cwd, approval, lsp) {
             if (truncated) {
                 result += `\n[Output truncated: exceeded ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB limit]`;
             }
+            const isFullRead = offset === 0 && !truncated && offset + limit >= lines.length;
+            if (isFullRead) {
+                await fileState?.observe(filePath, "read", content).catch(() => undefined);
+            }
             void lsp?.touchFile(filePath).catch(() => undefined);
             return {
                 content: result,

package/dist/tools/skill.js

@@ -21,6 +21,7 @@ export function createSkillTool(registry) {
     return {
         name: "skill",
         readOnly: true,
+        effect: "read",
         description: "Load a named skill on demand. Use this when a task clearly matches one of the available skills.",
         parameters: {
             type: "object",

package/dist/tools/task.js

@@ -2,6 +2,7 @@ export function createTaskTool() {
     return {
         name: "task",
         readOnly: true,
+        effect: "read",
         description: `Delegate a bounded investigative subtask to a read-only sub-agent and return a concise summary.
 
 Use this when:

package/dist/tools/todo.js

@@ -8,6 +8,7 @@ export function createTodoTool(store) {
     return {
         name: "todo_write",
         readOnly: true,
+        effect: "read",
         description: `Create or update the task list for the current work. Send the COMPLETE list each call; this overwrites the prior list entirely.
 
 ## When to use

package/dist/tools/tool-search.js

@@ -17,8 +17,9 @@ export function createToolSearchTool(controller) {
     return {
         name: "tool_search",
         readOnly: true,
+        effect: "read",
         description: 'Fetches full schema definitions for deferred tools so they can be called. ' +
-            'Deferred tools appear by name in <system-reminder> messages; their parameters are unknown ' +
+            'Deferred tools appear by name in hidden runtime reminders; their parameters are unknown ' +
             'until loaded. Use this tool with query "select:<name>[,<name>...]" to load specific tools, ' +
             'or with free-text keywords to search for relevant tools.',
         parameters: {

package/dist/tools/web-fetch.js

@@ -6,6 +6,7 @@ export function createWebFetchTool(approval) {
     return {
         name: "web_fetch",
         readOnly: true,
+        effect: "read",
         description: "Fetch and extract the contents of a specific URL using a remote web crawling service.",
         parameters: {
             type: "object",

package/dist/tools/web-search.js

@@ -7,6 +7,7 @@ export function createWebSearchTool() {
     return {
         name: "web_search",
         readOnly: true,
+        effect: "read",
         description: "Search the web using a remote search service and return current, structured results.",
         parameters: {
             type: "object",

package/dist/tools/write.d.ts

@@ -1,11 +1,12 @@
 /**
- * Write tool - create or overwrite files.
+ * Write tool - create files or safely replace full file contents.
  */
 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 WriteToolOptions {
-    /** If true, refuse to overwrite existing files */
+    /** If true, existing files require overwrite=true plus a fresh agent-observed version. */
     refuseOverwrite?: boolean;
 }
-export declare function createWriteTool(cwd: string, options?: WriteToolOptions, approval?: ApprovalController, lsp?: LspService): ToolRegistryEntry;
+export declare function createWriteTool(cwd: string, options?: WriteToolOptions, approval?: ApprovalController, lsp?: LspService, fileState?: FileStateTracker): ToolRegistryEntry;