@bubblebrain-ai/bubble 0.0.1

package/dist/tools/question.js

@@ -0,0 +1,174 @@
+import { QuestionRejectedError } from "../question/index.js";
+export function createQuestionTool(controller) {
+    return {
+        name: "question",
+        readOnly: true,
+        description: `Ask the user one or more structured questions during execution.
+
+Use this when you need to:
+1. Gather user preferences or requirements
+2. Clarify ambiguous instructions
+3. Get decisions on implementation choices
+4. Offer choices about what direction to take
+
+Usage notes:
+- Each question needs a short header, complete question text, and concise options.
+- When custom is enabled (default), the UI adds "Type your own answer"; do not include "Other" or catch-all options yourself.
+- Answers are returned as arrays of labels; set multiple: true when more than one answer may be selected.
+- If you recommend a specific option, make it the first option and add "(Recommended)" to the label.
+- Ask only targeted questions that unblock real work; do not ask "Should I proceed?".`,
+        parameters: {
+            type: "object",
+            properties: {
+                questions: {
+                    type: "array",
+                    description: "Questions to ask the user.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            header: {
+                                type: "string",
+                                description: "Very short label for this question, ideally 1-4 words.",
+                            },
+                            question: {
+                                type: "string",
+                                description: "Complete user-facing question.",
+                            },
+                            options: {
+                                type: "array",
+                                description: "Available choices. Do not include Other when custom is enabled.",
+                                items: {
+                                    type: "object",
+                                    properties: {
+                                        label: {
+                                            type: "string",
+                                            description: "Display label, concise and selectable.",
+                                        },
+                                        description: {
+                                            type: "string",
+                                            description: "Short explanation of the choice and its tradeoff.",
+                                        },
+                                    },
+                                    required: ["label", "description"],
+                                    additionalProperties: false,
+                                },
+                            },
+                            multiple: {
+                                type: "boolean",
+                                description: "Allow selecting multiple choices.",
+                            },
+                            custom: {
+                                type: "boolean",
+                                description: "Allow typing a custom answer. Defaults to true.",
+                            },
+                        },
+                        required: ["header", "question", "options"],
+                        additionalProperties: false,
+                    },
+                },
+            },
+            required: ["questions"],
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            const normalized = normalizeQuestions(args.questions);
+            if ("error" in normalized) {
+                return { content: normalized.error, isError: true };
+            }
+            try {
+                const answers = await controller.ask({
+                    sessionID: ctx.sessionID,
+                    questions: normalized.questions,
+                    tool: ctx.toolCall ? { callID: ctx.toolCall.id } : undefined,
+                });
+                return {
+                    content: formatQuestionToolResult(normalized.questions, answers),
+                    status: "success",
+                    metadata: {
+                        kind: "question",
+                        questions: normalized.questions,
+                        answers,
+                    },
+                };
+            }
+            catch (err) {
+                const message = err instanceof QuestionRejectedError
+                    ? err.message
+                    : err instanceof Error
+                        ? err.message
+                        : String(err);
+                return {
+                    content: `QuestionRejectedError: ${message}`,
+                    isError: true,
+                    status: "blocked",
+                    metadata: {
+                        kind: "question",
+                        questions: normalized.questions,
+                        rejected: true,
+                    },
+                };
+            }
+        },
+    };
+}
+function normalizeQuestions(input) {
+    if (!Array.isArray(input) || input.length === 0) {
+        return { error: "Error: questions must be a non-empty array." };
+    }
+    if (input.length > 3) {
+        return { error: "Error: ask at most 3 questions at a time." };
+    }
+    const questions = [];
+    for (let index = 0; index < input.length; index++) {
+        const raw = input[index];
+        if (!raw || typeof raw !== "object") {
+            return { error: `Error: question at index ${index} must be an object.` };
+        }
+        const q = raw;
+        const header = typeof q.header === "string" ? q.header.trim() : "";
+        const question = typeof q.question === "string" ? q.question.trim() : "";
+        const options = q.options;
+        if (!header)
+            return { error: `Error: question at index ${index} has an empty header.` };
+        if (!question)
+            return { error: `Error: question at index ${index} has empty question text.` };
+        if (!Array.isArray(options) || options.length === 0) {
+            return { error: `Error: question at index ${index} needs at least one option.` };
+        }
+        if (options.length > 9) {
+            return { error: `Error: question at index ${index} has too many options; max is 9.` };
+        }
+        const normalizedOptions = [];
+        for (let optIndex = 0; optIndex < options.length; optIndex++) {
+            const opt = options[optIndex];
+            if (!opt || typeof opt !== "object") {
+                return { error: `Error: option ${optIndex + 1} for "${header}" must be an object.` };
+            }
+            const value = opt;
+            const label = typeof value.label === "string" ? value.label.trim() : "";
+            const description = typeof value.description === "string" ? value.description.trim() : "";
+            if (!label)
+                return { error: `Error: option ${optIndex + 1} for "${header}" has empty label.` };
+            if (!description)
+                return { error: `Error: option "${label}" for "${header}" has empty description.` };
+            normalizedOptions.push({ label, description });
+        }
+        questions.push({
+            header,
+            question,
+            options: normalizedOptions,
+            multiple: q.multiple === true,
+            custom: q.custom === false ? false : undefined,
+        });
+    }
+    return { questions };
+}
+function formatQuestionToolResult(questions, answers) {
+    const formatted = questions
+        .map((question, index) => {
+        const answer = answers[index]?.length ? answers[index].join(", ") : "Unanswered";
+        return `"${question.question}"="${answer}"`;
+    })
+        .join(", ");
+    return `User has answered your questions: ${formatted}. You can now continue with the user's answers in mind.`;
+}

package/dist/tools/read.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Read tool - read file contents with truncation.
+ */
+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;

package/dist/tools/read.js

@@ -0,0 +1,83 @@
+/**
+ * Read tool - read file contents with truncation.
+ */
+import { constants } from "node:fs";
+import { access, readFile } from "node:fs/promises";
+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) {
+    return {
+        name: "read",
+        readOnly: true,
+        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",
+            properties: {
+                path: { type: "string", description: "Path to the file (relative or absolute)" },
+                offset: { type: "number", description: "Line number to start from (1-indexed)" },
+                limit: { type: "number", description: "Maximum number of lines to read" },
+            },
+            required: ["path"],
+        },
+        async execute(args) {
+            const filePath = resolve(cwd, args.path);
+            if (isSensitivePath(filePath)) {
+                return {
+                    content: `Error: Access to sensitive credential storage is blocked: ${filePath}`,
+                    isError: true,
+                    status: "blocked",
+                    metadata: {
+                        kind: "security",
+                        path: filePath,
+                        reason: "Sensitive credential storage is not readable from general-purpose tasks.",
+                    },
+                };
+            }
+            if (approval) {
+                const result = approval.checkRules({ tool: "Read", path: filePath, cwd });
+                if (result.decision === "deny") {
+                    return {
+                        content: `Error: Read blocked by deny rule: ${result.rule?.source ?? "<unknown>"} (${filePath})`,
+                        isError: true,
+                    };
+                }
+            }
+            try {
+                await access(filePath, constants.R_OK);
+            }
+            catch {
+                return { content: `Error: Cannot read file: ${filePath}`, isError: true };
+            }
+            let content = await readFile(filePath, "utf-8");
+            const lines = content.split("\n");
+            const offset = typeof args.offset === "number" ? Math.max(0, args.offset - 1) : 0;
+            const limit = typeof args.limit === "number" ? args.limit : lines.length;
+            let sliced = lines.slice(offset, offset + limit);
+            let truncated = false;
+            if (sliced.length > MAX_LINES) {
+                sliced = sliced.slice(0, MAX_LINES);
+                truncated = true;
+            }
+            let result = sliced.join("\n");
+            const byteLength = Buffer.byteLength(result, "utf-8");
+            if (byteLength > MAX_BYTES) {
+                result = Buffer.from(result, "utf-8").subarray(0, MAX_BYTES).toString("utf-8");
+                truncated = true;
+            }
+            if (truncated) {
+                result += `\n[Output truncated: exceeded ${MAX_LINES} lines or ${MAX_BYTES / 1024}KB limit]`;
+            }
+            void lsp?.touchFile(filePath).catch(() => undefined);
+            return {
+                content: result,
+                status: "success",
+                metadata: {
+                    kind: "read",
+                    path: filePath,
+                },
+            };
+        },
+    };
+}

package/dist/tools/sensitive-paths.d.ts

@@ -0,0 +1,3 @@
+export declare function getSensitivePaths(): string[];
+export declare function isSensitivePath(filePath: string): boolean;
+export declare function referencesSensitivePath(command: string): boolean;

package/dist/tools/sensitive-paths.js

@@ -0,0 +1,24 @@
+import { homedir } from "node:os";
+import { resolve } from "node:path";
+import { getBubbleHome } from "../bubble-home.js";
+export function getSensitivePaths() {
+    const bubbleHome = getBubbleHome();
+    return [
+        resolve(bubbleHome, "config.json"),
+        resolve(bubbleHome, "auth.json"),
+    ];
+}
+export function isSensitivePath(filePath) {
+    const resolved = resolve(filePath);
+    return getSensitivePaths().includes(resolved);
+}
+export function referencesSensitivePath(command) {
+    const lower = command.toLowerCase();
+    if (lower.includes("~/.bubble/config.json") || lower.includes("~/.bubble/auth.json")) {
+        return true;
+    }
+    return getSensitivePaths().some((filePath) => {
+        const normalized = filePath.replace(/\\/g, "/");
+        return lower.includes(normalized.toLowerCase()) || lower.includes(normalized.toLowerCase().replace(homedir().toLowerCase(), "~"));
+    });
+}

package/dist/tools/skill.d.ts

@@ -0,0 +1,5 @@
+import type { SkillRecord } from "../skills/types.js";
+import type { SkillRegistry } from "../skills/registry.js";
+import type { ToolRegistryEntry } from "../types.js";
+export declare function formatLoadedSkill(skill: SkillRecord): string;
+export declare function createSkillTool(registry: SkillRegistry): ToolRegistryEntry;

package/dist/tools/skill.js

@@ -0,0 +1,51 @@
+export function formatLoadedSkill(skill) {
+    const resources = [
+        ...skill.resources.references,
+        ...skill.resources.scripts,
+        ...skill.resources.assets,
+    ];
+    const sections = [
+        `Skill: ${skill.meta.name}`,
+        `Description: ${skill.meta.description}`,
+        `Base directory: ${skill.rootDir}`,
+        "",
+        skill.content,
+    ];
+    if (resources.length > 0) {
+        sections.push("", "Resources:", ...resources.map((resource) => `- ${resource}`));
+    }
+    sections.push("", "Relative paths mentioned in this skill are resolved from the base directory above.");
+    return sections.join("\n");
+}
+export function createSkillTool(registry) {
+    return {
+        name: "skill",
+        readOnly: true,
+        description: "Load a named skill on demand. Use this when a task clearly matches one of the available skills.",
+        parameters: {
+            type: "object",
+            properties: {
+                name: { type: "string", description: "The exact skill name to load" },
+            },
+            required: ["name"],
+            additionalProperties: false,
+        },
+        async execute(args) {
+            const name = typeof args.name === "string" ? args.name.trim() : "";
+            if (!name) {
+                return { content: "Error: skill name is required", isError: true };
+            }
+            const skill = registry.get(name);
+            if (!skill) {
+                const available = registry.summaries().map((item) => item.name).join(", ");
+                return {
+                    content: available
+                        ? `Error: Unknown skill "${name}". Available skills: ${available}`
+                        : `Error: Unknown skill "${name}". No skills are currently available.`,
+                    isError: true,
+                };
+            }
+            return { content: formatLoadedSkill(skill) };
+        },
+    };
+}

package/dist/tools/task.d.ts

@@ -0,0 +1,2 @@
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createTaskTool(): ToolRegistryEntry;

package/dist/tools/task.js

@@ -0,0 +1,57 @@
+export function createTaskTool() {
+    return {
+        name: "task",
+        readOnly: true,
+        description: `Delegate a bounded investigative subtask to a read-only sub-agent and return a concise summary.
+
+Use this when:
+- a search/investigation can be scoped as a sub-problem
+- you want a focused summary before continuing the main task
+- you need to inspect a specific hypothesis or area without polluting the main loop with exploratory churn
+
+Do not use this for edits or shell-heavy workflows. The subtask agent runs in read-only plan mode.`,
+        parameters: {
+            type: "object",
+            properties: {
+                prompt: {
+                    type: "string",
+                    description: "The focused subtask prompt to investigate.",
+                },
+                description: {
+                    type: "string",
+                    description: "Short description of what this subtask is trying to verify.",
+                },
+                subtaskType: {
+                    type: "string",
+                    enum: ["search", "security_investigation", "evidence_correlation", "general_readonly"],
+                    description: "The bounded subtask policy to apply.",
+                },
+            },
+            required: ["prompt"],
+            additionalProperties: false,
+        },
+        async execute(args, ctx) {
+            const prompt = typeof args.prompt === "string" ? args.prompt.trim() : "";
+            const description = typeof args.description === "string" ? args.description.trim() : "";
+            const subtaskType = typeof args.subtaskType === "string" ? args.subtaskType : undefined;
+            if (!prompt) {
+                return { content: "Error: task prompt is required", isError: true };
+            }
+            if (!ctx.agent?.runSubtask) {
+                return { content: "Error: task tool requires an agent runtime", isError: true };
+            }
+            const composed = description
+                ? `${description}\n\n${prompt}\n\nInvestigate this sub-problem in read-only mode and return a concise evidence-based summary.`
+                : `${prompt}\n\nInvestigate this sub-problem in read-only mode and return a concise evidence-based summary.`;
+            const result = await ctx.agent.runSubtask(composed, ctx.cwd, { subtaskType, description });
+            return {
+                ...result,
+                metadata: {
+                    ...result.metadata,
+                    kind: "security",
+                    reason: description || result.metadata?.reason,
+                },
+            };
+        },
+    };
+}

package/dist/tools/todo.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Todo tool - manage an agent-visible task list for multi-step work.
+ *
+ * The tool overwrites the entire list on each call. The model should re-send the full
+ * array with updated statuses rather than trying to patch individual items.
+ */
+import type { Todo, ToolRegistryEntry } from "../types.js";
+export interface TodoStore {
+    getTodos: () => Todo[];
+    setTodos: (todos: Todo[]) => void;
+}
+export declare function createTodoTool(store: TodoStore): ToolRegistryEntry;

package/dist/tools/todo.js

@@ -0,0 +1,151 @@
+/**
+ * Todo tool - manage an agent-visible task list for multi-step work.
+ *
+ * The tool overwrites the entire list on each call. The model should re-send the full
+ * array with updated statuses rather than trying to patch individual items.
+ */
+export function createTodoTool(store) {
+    return {
+        name: "todo_write",
+        readOnly: true,
+        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
+
+Use this tool proactively when any of these apply:
+1. Complex multi-step work — 3 or more distinct steps or file locations
+2. Non-trivial tasks requiring planning or coordination across multiple operations
+3. The user explicitly asks for a todo list
+4. The user provides a list of things to do (numbered, comma-separated, bulleted)
+5. New instructions arrive mid-session — capture them as todos before starting
+6. Starting work on a task — mark it in_progress BEFORE beginning. Only one item may be in_progress at a time
+7. Finishing a task — mark it completed immediately, don't batch completions
+
+## When NOT to use
+
+Skip this tool when:
+1. There is a single, straightforward task
+2. The task is trivial and tracking provides no organizational benefit
+3. The work can be completed in fewer than 3 trivial steps
+4. The request is purely conversational or informational
+
+If there is only one trivial task, just do it — don't create a todo first.
+
+## Examples
+
+<example>
+User: Add a dark mode toggle to the settings page, then run tests and build.
+Assistant: *creates a 5-item todo: toggle UI, theme state, CSS tokens, update components, run tests + build*
+<reasoning>Multiple distinct steps across UI, state, styles, and verification. User explicitly asked for tests + build.</reasoning>
+</example>
+
+<example>
+User: Rename getCwd to getCurrentWorkingDirectory across the project.
+Assistant: *greps, finds 15 call sites across 8 files, creates a per-file todo list*
+<reasoning>Scope discovered via grep shows many locations; a todo ensures each file is tracked and none are missed.</reasoning>
+</example>
+
+<example>
+User: How do I print "Hello World" in Python?
+Assistant: *answers in one sentence with a snippet — no todo*
+<reasoning>Informational, one-step, no tracking benefit.</reasoning>
+</example>
+
+<example>
+User: Add a comment to calculateTotal explaining what it does.
+Assistant: *calls edit directly — no todo*
+<reasoning>Single, localized change in one file.</reasoning>
+</example>
+
+## Task states
+
+- pending: not yet started
+- in_progress: currently working on — exactly ONE at a time
+- completed: finished successfully
+
+Each item needs:
+- content: imperative form (e.g. "Run tests")
+- activeForm: present continuous, shown while in progress (e.g. "Running tests")
+
+## Rules
+
+- Update status in real time; mark completed IMMEDIATELY on finishing.
+- Never mark completed if tests are failing, implementation is partial, errors are unresolved, or needed files are missing — keep as in_progress.
+- When blocked, add a new task describing what must be resolved.
+- Remove items that are no longer relevant; don't leave stale entries.`,
+        parameters: {
+            type: "object",
+            properties: {
+                todos: {
+                    type: "array",
+                    description: "The complete list of todos. Replaces any existing list.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            content: {
+                                type: "string",
+                                description: "Imperative form describing the task (e.g., 'Add unit tests for foo')",
+                            },
+                            activeForm: {
+                                type: "string",
+                                description: "Present continuous form shown while in progress (e.g., 'Adding unit tests for foo')",
+                            },
+                            status: {
+                                type: "string",
+                                enum: ["pending", "in_progress", "completed"],
+                                description: "Current status of the task",
+                            },
+                        },
+                        required: ["content", "activeForm", "status"],
+                    },
+                },
+            },
+            required: ["todos"],
+        },
+        async execute(args) {
+            if (!Array.isArray(args.todos)) {
+                return { content: "Error: 'todos' must be an array", isError: true };
+            }
+            const normalized = [];
+            for (let i = 0; i < args.todos.length; i++) {
+                const raw = args.todos[i];
+                if (!raw || typeof raw !== "object") {
+                    return { content: `Error: todo at index ${i} is not an object`, isError: true };
+                }
+                const content = typeof raw.content === "string" ? raw.content.trim() : "";
+                const activeForm = typeof raw.activeForm === "string" ? raw.activeForm.trim() : "";
+                const status = raw.status;
+                if (!content) {
+                    return { content: `Error: todo at index ${i} has empty content`, isError: true };
+                }
+                if (!activeForm) {
+                    return { content: `Error: todo at index ${i} has empty activeForm`, isError: true };
+                }
+                if (status !== "pending" && status !== "in_progress" && status !== "completed") {
+                    return {
+                        content: `Error: todo at index ${i} has invalid status "${status}". Must be pending|in_progress|completed`,
+                        isError: true,
+                    };
+                }
+                normalized.push({ content, activeForm, status });
+            }
+            const inProgressCount = normalized.filter((t) => t.status === "in_progress").length;
+            if (inProgressCount > 1) {
+                return {
+                    content: `Error: at most one todo may be in_progress at a time, found ${inProgressCount}`,
+                    isError: true,
+                };
+            }
+            store.setTodos(normalized);
+            const counts = {
+                pending: normalized.filter((t) => t.status === "pending").length,
+                in_progress: inProgressCount,
+                completed: normalized.filter((t) => t.status === "completed").length,
+            };
+            return {
+                content: `Todo list updated: ${normalized.length} item${normalized.length === 1 ? "" : "s"} ` +
+                    `(${counts.completed} completed, ${counts.in_progress} in progress, ${counts.pending} pending).`,
+            };
+        },
+    };
+}

package/dist/tools/tool-search.d.ts

@@ -0,0 +1,23 @@
+/**
+ * tool_search — meta-tool that loads schemas for deferred tools on demand.
+ *
+ * Mirrors Claude Code's ToolSearch. Two query modes:
+ *
+ *   - "select:a,b,c"  → fetch these exact tools by name (ignores ranking)
+ *   - free text       → rank deferred tools by substring match against name
+ *                       and description, return the top N
+ *
+ * Output is a <functions>…</functions> block containing one
+ * `<function>{schema JSON}</function>` per match — the same encoding the
+ * provider uses for the tool list at the top of the prompt. The matched
+ * tools are also unlocked on the agent so subsequent turns include them in
+ * the real tool list.
+ */
+import type { ToolRegistryEntry } from "../types.js";
+export interface ToolSearchController {
+    /** All deferred tools in the current session, whether unlocked or not. */
+    listDeferred: () => ToolRegistryEntry[];
+    /** Mark a set of deferred tool names as unlocked. */
+    unlock: (names: string[]) => void;
+}
+export declare function createToolSearchTool(controller: ToolSearchController): ToolRegistryEntry;