@bubblebrain-ai/bubble 0.0.1

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

@@ -0,0 +1,68 @@
+/**
+ * exit_plan_mode tool - proposes a plan, awaits user approval, and (on approve) flips the
+ * agent out of plan mode so subsequent turns may execute it.
+ *
+ * The tool is read-only from the agent's perspective; the side effects (prompting the user,
+ * flipping mode) happen via the injected PlanController.
+ */
+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. " +
+            "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.",
+        parameters: {
+            type: "object",
+            properties: {
+                plan: {
+                    type: "string",
+                    description: "The plan to present to the user. Should be concrete, step-by-step, and cover all changes you intend to make.",
+                },
+            },
+            required: ["plan"],
+        },
+        async execute(args) {
+            // Hard gate: this tool is a no-op outside plan mode. Without this check some
+            // models call it during normal work (misled by the word "plan" in the schema),
+            // which pops a confusing approval dialog to the user.
+            if (controller.getMode() !== "plan") {
+                return {
+                    content: "Error: exit_plan_mode is only valid while plan mode is active. " +
+                        "You are currently NOT in plan mode — proceed with the user's request directly using the regular tools.",
+                    isError: true,
+                };
+            }
+            const plan = typeof args.plan === "string" ? args.plan.trim() : "";
+            if (!plan) {
+                return { content: "Error: plan is required and must be a non-empty string", isError: true };
+            }
+            let decision;
+            try {
+                decision = await controller.requestApproval(plan);
+            }
+            catch (err) {
+                return {
+                    content: `Error requesting plan approval: ${err?.message || String(err)}`,
+                    isError: true,
+                };
+            }
+            if (decision.action === "approve") {
+                controller.setMode("default");
+                const finalPlan = decision.plan.trim() || plan;
+                const edited = finalPlan !== plan;
+                return {
+                    content: `User approved the plan${edited ? " (with edits)" : ""}. ` +
+                        `Agent mode has been switched to default — you may now execute the plan using any tools. ` +
+                        `Approved plan:\n\n${finalPlan}`,
+                };
+            }
+            const reason = decision.reason?.trim();
+            return {
+                content: `User rejected the plan. Remain in plan mode and revise your approach. ` +
+                    (reason ? `Reason: ${reason}` : "No reason provided; ask for clarification or gather more context."),
+            };
+        },
+    };
+}

package/dist/tools/glob.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Glob tool - discover files by path pattern without shell access.
+ */
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createGlobTool(cwd: string): ToolRegistryEntry;

package/dist/tools/glob.js

@@ -0,0 +1,129 @@
+/**
+ * Glob tool - discover files by path pattern without shell access.
+ */
+import { readdir, stat } from "node:fs/promises";
+import { relative, resolve } from "node:path";
+import picomatch from "picomatch";
+import { isSensitivePath } from "./sensitive-paths.js";
+const MAX_RESULTS = 100;
+const DEFAULT_IGNORES = new Set([
+    ".git",
+    "node_modules",
+    "dist",
+    "build",
+    ".next",
+    ".turbo",
+    ".cache",
+    "coverage",
+]);
+export function createGlobTool(cwd) {
+    return {
+        name: "glob",
+        readOnly: true,
+        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",
+            properties: {
+                pattern: { type: "string", description: "Glob pattern to match files, e.g. '**/*', '**/*.ts', 'src/**/*.tsx'" },
+                path: { type: "string", description: "Directory to search in (optional, default: cwd)" },
+            },
+            required: ["pattern"],
+        },
+        async execute(args, ctx) {
+            const root = resolve(cwd, typeof args.path === "string" && args.path.trim() ? args.path : ".");
+            const pattern = String(args.pattern || "").trim();
+            if (!pattern) {
+                return { content: "Error: glob pattern is required", isError: true, status: "command_error" };
+            }
+            if (isSensitivePath(root)) {
+                return {
+                    content: `Error: Glob blocked for sensitive credential storage: ${root}`,
+                    isError: true,
+                    status: "blocked",
+                    metadata: {
+                        kind: "security",
+                        path: root,
+                        pattern,
+                        reason: "Sensitive credential storage is not searchable from general-purpose tasks.",
+                    },
+                };
+            }
+            const matcher = picomatch(pattern, { dot: true });
+            const files = [];
+            const truncated = { value: false };
+            try {
+                const rootStat = await stat(root);
+                if (!rootStat.isDirectory()) {
+                    return { content: `Error: Path is not a directory: ${root}`, isError: true, status: "command_error" };
+                }
+                await walk(root, root, matcher, files, truncated, ctx.abortSignal);
+            }
+            catch (error) {
+                return { content: `Error: Cannot glob path: ${root} (${error?.message || String(error)})`, isError: true, status: "command_error" };
+            }
+            files.sort((a, b) => b.mtimeMs - a.mtimeMs || a.path.localeCompare(b.path));
+            const matches = files.slice(0, MAX_RESULTS).map((item) => item.path);
+            const wasTruncated = truncated.value || files.length > MAX_RESULTS;
+            if (matches.length === 0) {
+                return {
+                    content: "No files found.",
+                    status: "no_match",
+                    metadata: {
+                        kind: "search",
+                        path: root,
+                        pattern,
+                        matches: 0,
+                        truncated: false,
+                        searchSignature: `glob:${root}:${pattern}`,
+                        searchFamily: `glob:${pattern}`,
+                    },
+                };
+            }
+            return {
+                content: `${matches.join("\n")}${wasTruncated ? `\n[More than ${MAX_RESULTS} files, output truncated]` : ""}`,
+                status: wasTruncated ? "partial" : "success",
+                metadata: {
+                    kind: "search",
+                    path: root,
+                    pattern,
+                    matches: matches.length,
+                    truncated: wasTruncated,
+                    searchSignature: `glob:${root}:${pattern}`,
+                    searchFamily: `glob:${pattern}`,
+                },
+            };
+        },
+    };
+}
+async function walk(root, dir, matcher, files, truncated, abortSignal) {
+    if (abortSignal?.aborted || files.length >= MAX_RESULTS) {
+        truncated.value = true;
+        return;
+    }
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (abortSignal?.aborted || files.length >= MAX_RESULTS) {
+            truncated.value = true;
+            return;
+        }
+        if (entry.isDirectory() && DEFAULT_IGNORES.has(entry.name)) {
+            continue;
+        }
+        const absolute = resolve(dir, entry.name);
+        const rel = toPosix(relative(root, absolute));
+        if (entry.isDirectory()) {
+            await walk(root, absolute, matcher, files, truncated, abortSignal);
+            continue;
+        }
+        if (!entry.isFile()) {
+            continue;
+        }
+        if (matcher(rel)) {
+            const info = await stat(absolute);
+            files.push({ path: rel, mtimeMs: info.mtimeMs });
+        }
+    }
+}
+function toPosix(path) {
+    return path.split("\\").join("/");
+}

package/dist/tools/grep.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Grep tool - search file contents using ripgrep.
+ */
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createGrepTool(cwd: string): ToolRegistryEntry;

package/dist/tools/grep.js

@@ -0,0 +1,111 @@
+/**
+ * Grep tool - search file contents using ripgrep.
+ */
+import { execFile } from "node:child_process";
+import { resolve } from "node:path";
+import { isSensitivePath } from "./sensitive-paths.js";
+import { analyzeToolIntent } from "../agent/tool-intent.js";
+const MAX_MATCHES = 100;
+export function createGrepTool(cwd) {
+    return {
+        name: "grep",
+        readOnly: true,
+        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",
+            properties: {
+                pattern: { type: "string", description: "Regex pattern to search for" },
+                path: { type: "string", description: "Directory or file to search in (optional, default: cwd)" },
+                glob: { type: "string", description: "Glob pattern to filter files (optional, e.g. '*.ts')" },
+            },
+            required: ["pattern"],
+        },
+        async execute(args) {
+            const searchPath = args.path ? resolve(cwd, args.path) : cwd;
+            const pattern = String(args.pattern);
+            const intent = analyzeToolIntent({
+                name: "grep",
+                parsedArgs: {
+                    pattern,
+                    path: args.path,
+                    glob: args.glob,
+                },
+            });
+            if (isSensitivePath(searchPath)) {
+                return {
+                    content: `Error: Search blocked for sensitive credential storage: ${searchPath}`,
+                    isError: true,
+                    status: "blocked",
+                    metadata: {
+                        kind: "security",
+                        path: searchPath,
+                        pattern,
+                        searchSignature: intent.search?.signature,
+                        searchFamily: intent.search?.familyKey,
+                        reason: "Sensitive credential storage is not searchable from general-purpose tasks.",
+                    },
+                };
+            }
+            const rgArgs = ["--json", "-n", "--max-count", String(MAX_MATCHES), pattern];
+            if (args.glob) {
+                rgArgs.push("--glob", String(args.glob));
+            }
+            rgArgs.push(searchPath);
+            return new Promise((resolve) => {
+                execFile("rg", rgArgs, { cwd, maxBuffer: 10 * 1024 * 1024 }, (error, stdout, stderr) => {
+                    // rg returns exit code 1 when no matches found, which is not an error for us
+                    const lines = stdout.split("\n").filter((l) => l.trim() !== "");
+                    const matches = [];
+                    for (const line of lines) {
+                        try {
+                            const obj = JSON.parse(line);
+                            if (obj.type === "match") {
+                                const path = obj.data.path.text;
+                                const lineNum = obj.data.line_number;
+                                const text = obj.data.lines.text?.trim() ?? "";
+                                matches.push(`${path}:${lineNum}: ${text}`);
+                            }
+                        }
+                        catch {
+                            // ignore parse errors
+                        }
+                    }
+                    if (matches.length === 0) {
+                        resolve({
+                            content: "No matches found.",
+                            status: "no_match",
+                            metadata: {
+                                kind: "search",
+                                path: searchPath,
+                                pattern,
+                                matches: 0,
+                                truncated: false,
+                                searchSignature: intent.search?.signature,
+                                searchFamily: intent.search?.familyKey,
+                            },
+                        });
+                        return;
+                    }
+                    let output = matches.join("\n");
+                    const truncated = matches.length >= MAX_MATCHES;
+                    if (matches.length >= MAX_MATCHES) {
+                        output += `\n[More than ${MAX_MATCHES} matches, output truncated]`;
+                    }
+                    resolve({
+                        content: output,
+                        status: truncated ? "partial" : "success",
+                        metadata: {
+                            kind: "search",
+                            path: searchPath,
+                            pattern,
+                            matches: matches.length,
+                            truncated,
+                            searchSignature: intent.search?.signature,
+                            searchFamily: intent.search?.familyKey,
+                        },
+                    });
+                });
+            });
+        },
+    };
+}

package/dist/tools/index.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Tool registry factory.
+ */
+export { createReadTool } from "./read.js";
+export { createBashTool } from "./bash.js";
+export { createWriteTool } from "./write.js";
+export { createEditTool } from "./edit.js";
+export { createGlobTool } from "./glob.js";
+export { createGrepTool } from "./grep.js";
+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 { createTodoTool, type TodoStore } from "./todo.js";
+export { createExitPlanModeTool, type PlanController } from "./exit-plan-mode.js";
+export { createToolSearchTool, type ToolSearchController } from "./tool-search.js";
+export { createQuestionTool } from "./question.js";
+export { createMemoryReadSummaryTool, createMemorySearchTool } from "./memory.js";
+import type { ToolRegistryEntry } from "../types.js";
+import type { ApprovalController } from "../approval/types.js";
+import type { SkillRegistry } from "../skills/registry.js";
+import { type PlanController } from "./exit-plan-mode.js";
+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";
+export interface CreateAllToolsOptions {
+    todoStore?: TodoStore;
+    planController?: PlanController;
+    approvalController?: ApprovalController;
+    questionController?: QuestionController;
+    toolSearchController?: ToolSearchController;
+    lspService?: LspService;
+}
+export declare function createAllTools(cwd: string, skillRegistry?: SkillRegistry, options?: CreateAllToolsOptions): ToolRegistryEntry[];

package/dist/tools/index.js

@@ -0,0 +1,59 @@
+/**
+ * Tool registry factory.
+ */
+export { createReadTool } from "./read.js";
+export { createBashTool } from "./bash.js";
+export { createWriteTool } from "./write.js";
+export { createEditTool } from "./edit.js";
+export { createGlobTool } from "./glob.js";
+export { createGrepTool } from "./grep.js";
+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 { createTodoTool } from "./todo.js";
+export { createExitPlanModeTool } from "./exit-plan-mode.js";
+export { createToolSearchTool } from "./tool-search.js";
+export { createQuestionTool } from "./question.js";
+export { createMemoryReadSummaryTool, createMemorySearchTool } from "./memory.js";
+import { createBashTool } from "./bash.js";
+import { createEditTool } from "./edit.js";
+import { createExitPlanModeTool } from "./exit-plan-mode.js";
+import { createGlobTool } from "./glob.js";
+import { createGrepTool } from "./grep.js";
+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 { createTodoTool } from "./todo.js";
+import { createToolSearchTool } from "./tool-search.js";
+import { createWebFetchTool } from "./web-fetch.js";
+import { createWebSearchTool } from "./web-search.js";
+import { createWriteTool } from "./write.js";
+import { createQuestionTool } from "./question.js";
+import { createMemoryReadSummaryTool, createMemorySearchTool } from "./memory.js";
+export function createAllTools(cwd, skillRegistry, options = {}) {
+    const approval = options.approvalController;
+    const lsp = options.lspService ?? getLspService(cwd);
+    return [
+        createReadTool(cwd, approval, lsp),
+        createBashTool(cwd, approval),
+        createWriteTool(cwd, { refuseOverwrite: true }, approval, lsp),
+        createEditTool(cwd, approval, lsp),
+        createGlobTool(cwd),
+        createGrepTool(cwd),
+        createLspTool(cwd, lsp, approval),
+        createWebSearchTool(),
+        createWebFetchTool(approval),
+        createMemorySearchTool(cwd),
+        createMemoryReadSummaryTool(cwd),
+        createTaskTool(),
+        ...(options.questionController ? [createQuestionTool(options.questionController)] : []),
+        ...(skillRegistry ? [createSkillTool(skillRegistry)] : []),
+        ...(options.todoStore ? [createTodoTool(options.todoStore)] : []),
+        ...(options.planController ? [createExitPlanModeTool(options.planController)] : []),
+        ...(options.toolSearchController ? [createToolSearchTool(options.toolSearchController)] : []),
+    ];
+}

package/dist/tools/lsp.d.ts

@@ -0,0 +1,4 @@
+import type { ApprovalController } from "../approval/types.js";
+import { type LspService } from "../lsp/index.js";
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createLspTool(cwd: string, lsp?: LspService, approval?: ApprovalController): ToolRegistryEntry;

package/dist/tools/lsp.js

@@ -0,0 +1,92 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { resolve } from "node:path";
+import { gateToolAction } from "../approval/tool-helper.js";
+import { getLspService } from "../lsp/index.js";
+const OPERATIONS = [
+    "goToDefinition",
+    "findReferences",
+    "hover",
+    "documentSymbol",
+    "workspaceSymbol",
+    "goToImplementation",
+    "prepareCallHierarchy",
+    "incomingCalls",
+    "outgoingCalls",
+];
+export function createLspTool(cwd, lsp = getLspService(cwd), approval) {
+    return {
+        name: "lsp",
+        readOnly: true,
+        description: "Use the language server for code navigation. Supports goToDefinition, findReferences, hover, documentSymbol, workspaceSymbol, goToImplementation, prepareCallHierarchy, incomingCalls, and outgoingCalls.",
+        parameters: {
+            type: "object",
+            properties: {
+                operation: { type: "string", enum: [...OPERATIONS], description: "LSP operation to perform" },
+                filePath: { type: "string", description: "Path to the file, relative or absolute" },
+                line: { type: "number", description: "1-based line number for position-based operations" },
+                character: { type: "number", description: "1-based character offset for position-based operations" },
+                query: { type: "string", description: "Optional query for workspaceSymbol" },
+            },
+            required: ["operation", "filePath"],
+        },
+        async execute(args) {
+            const operation = args.operation;
+            if (!OPERATIONS.includes(operation)) {
+                return { content: `Error: Unsupported LSP operation: ${args.operation}`, isError: true };
+            }
+            const file = resolve(cwd, String(args.filePath));
+            try {
+                await access(file, constants.R_OK);
+            }
+            catch {
+                return { content: `Error: File not found or not readable: ${file}`, isError: true };
+            }
+            const available = await lsp.hasClients(file);
+            if (!available) {
+                return { content: "Error: No LSP server available for this file type.", isError: true };
+            }
+            const gate = await gateToolAction(approval, {
+                type: "lsp",
+                path: file,
+                operation,
+            });
+            if (!gate.approved)
+                return gate.result;
+            await lsp.touchFile(file, "document");
+            const position = {
+                file,
+                line: Math.max(0, Number(args.line ?? 1) - 1),
+                character: Math.max(0, Number(args.character ?? 1) - 1),
+            };
+            const result = await runOperation(lsp, operation, position, String(args.query ?? ""));
+            return {
+                content: result.length === 0 ? `No results found for ${operation}` : JSON.stringify(result, null, 2),
+                status: "success",
+                metadata: { kind: "lsp", path: file },
+            };
+        },
+    };
+}
+async function runOperation(lsp, operation, position, query) {
+    switch (operation) {
+        case "goToDefinition":
+            return lsp.definition(position);
+        case "findReferences":
+            return lsp.references(position);
+        case "hover":
+            return lsp.hover(position);
+        case "documentSymbol":
+            return lsp.documentSymbol(position.file);
+        case "workspaceSymbol":
+            return lsp.workspaceSymbol(query);
+        case "goToImplementation":
+            return lsp.implementation(position);
+        case "prepareCallHierarchy":
+            return lsp.prepareCallHierarchy(position);
+        case "incomingCalls":
+            return lsp.incomingCalls(position);
+        case "outgoingCalls":
+            return lsp.outgoingCalls(position);
+    }
+}

package/dist/tools/memory.d.ts

@@ -0,0 +1,3 @@
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createMemorySearchTool(cwd: string): ToolRegistryEntry;
+export declare function createMemoryReadSummaryTool(cwd: string): ToolRegistryEntry;

package/dist/tools/memory.js

@@ -0,0 +1,90 @@
+import { readMemorySummary, searchMemory } from "../memory/index.js";
+const MEMORY_SCOPE_ENUM = ["project", "global", "all"];
+export function createMemorySearchTool(cwd) {
+    return {
+        name: "memory_search",
+        description: "Search persistent Bubble memory for prior project facts, user preferences, workflows, decisions, and gotchas.",
+        readOnly: true,
+        parameters: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Search query. Use concrete terms such as file names, feature names, commands, or error text.",
+                },
+                scope: {
+                    type: "string",
+                    enum: MEMORY_SCOPE_ENUM,
+                    description: "Memory scope to search. Defaults to all, with project memory first.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Maximum number of results to return. Defaults to 12.",
+                },
+            },
+            required: ["query"],
+            additionalProperties: false,
+        },
+        async execute(args) {
+            const query = typeof args.query === "string" ? args.query.trim() : "";
+            if (!query) {
+                return { content: "query is required", isError: true, status: "no_match" };
+            }
+            const scope = parseScope(args.scope);
+            const limit = typeof args.limit === "number" && Number.isFinite(args.limit)
+                ? Math.max(1, Math.min(50, Math.floor(args.limit)))
+                : undefined;
+            const results = searchMemory(cwd, query, { scope, limit });
+            if (results.length === 0) {
+                return { content: `No memory matches for "${query}".`, status: "no_match" };
+            }
+            return {
+                content: [
+                    `Memory search results for "${query}":`,
+                    ...results.flatMap((result) => [
+                        `- ${result.scope} ${result.path}:${result.line}`,
+                        `  ${result.text}`,
+                    ]),
+                ].join("\n"),
+                metadata: { kind: "search", matches: results.length },
+            };
+        },
+    };
+}
+export function createMemoryReadSummaryTool(cwd) {
+    return {
+        name: "memory_read_summary",
+        description: "Read the concise persistent memory summary for the current project, global scope, or both.",
+        readOnly: true,
+        parameters: {
+            type: "object",
+            properties: {
+                scope: {
+                    type: "string",
+                    enum: MEMORY_SCOPE_ENUM,
+                    description: "Memory scope to read. Defaults to project.",
+                },
+            },
+            additionalProperties: false,
+        },
+        async execute(args) {
+            const scope = parseScope(args.scope, "project");
+            const summaries = readMemorySummary(cwd, scope);
+            if (summaries.length === 0) {
+                return { content: `No ${scope} memory summary is available.`, status: "no_match" };
+            }
+            return {
+                content: summaries.map((summary) => [
+                    `# ${summary.scope} memory summary`,
+                    `Path: ${summary.path}`,
+                    "",
+                    summary.content,
+                ].join("\n")).join("\n\n---\n\n"),
+                metadata: { kind: "read", matches: summaries.length },
+            };
+        },
+    };
+}
+function parseScope(value, fallback = "all") {
+    return value === "project" || value === "global" || value === "all" ? value : fallback;
+}

package/dist/tools/question.d.ts

@@ -0,0 +1,3 @@
+import type { ToolRegistryEntry } from "../types.js";
+import type { QuestionController } from "../question/index.js";
+export declare function createQuestionTool(controller: QuestionController): ToolRegistryEntry;