@bubblebrain-ai/bubble 0.0.1

package/dist/slash-commands/index.d.ts

@@ -0,0 +1,4 @@
+import { SlashCommandRegistry } from "./registry.js";
+export declare const registry: SlashCommandRegistry;
+export * from "./types.js";
+export * from "./registry.js";

package/dist/slash-commands/index.js

@@ -0,0 +1,8 @@
+import { SlashCommandRegistry } from "./registry.js";
+import { builtinSlashCommands } from "./commands.js";
+export const registry = new SlashCommandRegistry();
+for (const cmd of builtinSlashCommands) {
+    registry.register(cmd);
+}
+export * from "./types.js";
+export * from "./registry.js";

package/dist/slash-commands/registry.d.ts

@@ -0,0 +1,31 @@
+import type { SlashCommand, SlashCommandContext } from "./types.js";
+import { type CommandSource, type UnifiedCommand } from "./unified.js";
+/**
+ * Dynamic source: called at lookup time to produce extra commands (e.g. MCP
+ * prompts loaded from a server after connect). The registry only keeps the
+ * callback — commands are never cached, so re-registering after a reconnect
+ * just works.
+ *
+ * Sources may return bare SlashCommand objects for backwards compatibility;
+ * the registry treats unlabelled commands as source: "builtin". MCP's dynamic
+ * source returns UnifiedCommand with source: "mcp".
+ */
+export type DynamicSource = () => SlashCommand[];
+export declare class SlashCommandRegistry {
+    private commands;
+    private dynamicSources;
+    register(cmd: SlashCommand): void;
+    addDynamicSource(source: DynamicSource): void;
+    get(name: string): UnifiedCommand | undefined;
+    list(): UnifiedCommand[];
+    /**
+     * Convenience filter used by UI code that wants to group by source
+     * (e.g. builtin first, then mcp) without filtering in-line every time.
+     */
+    listBySource(source: CommandSource): UnifiedCommand[];
+    execute(input: string, ctx: SlashCommandContext): Promise<{
+        handled: boolean;
+        result?: string;
+        inject?: string;
+    }>;
+}

package/dist/slash-commands/registry.js

@@ -0,0 +1,70 @@
+import { asUnified } from "./unified.js";
+export class SlashCommandRegistry {
+    commands = new Map();
+    dynamicSources = [];
+    register(cmd) {
+        this.commands.set(cmd.name, asUnified(cmd, "builtin"));
+    }
+    addDynamicSource(source) {
+        this.dynamicSources.push(source);
+    }
+    get(name) {
+        const builtin = this.commands.get(name);
+        if (builtin)
+            return builtin;
+        for (const source of this.dynamicSources) {
+            for (const cmd of source()) {
+                if (cmd.name === name)
+                    return asUnified(cmd);
+            }
+        }
+        return undefined;
+    }
+    list() {
+        const out = [...this.commands.values()];
+        for (const source of this.dynamicSources) {
+            for (const cmd of source()) {
+                out.push(asUnified(cmd));
+            }
+        }
+        return out;
+    }
+    /**
+     * Convenience filter used by UI code that wants to group by source
+     * (e.g. builtin first, then mcp) without filtering in-line every time.
+     */
+    listBySource(source) {
+        return this.list().filter((cmd) => cmd.source === source);
+    }
+    async execute(input, ctx) {
+        if (!input.startsWith("/"))
+            return { handled: false };
+        const spaceIndex = input.indexOf(" ");
+        const name = spaceIndex === -1 ? input.slice(1) : input.slice(1, spaceIndex);
+        const args = spaceIndex === -1 ? "" : input.slice(spaceIndex + 1).trim();
+        const cmd = this.get(name);
+        if (!cmd) {
+            const skill = ctx.skillRegistry.get(name);
+            if (skill) {
+                return {
+                    handled: true,
+                    result: `Skill "${skill.meta.name}": ${skill.meta.description}\nUse /${skill.meta.name} <your request> to run with this skill, or /skill ${skill.meta.name} to inspect it.`,
+                };
+            }
+            return {
+                handled: true,
+                result: `Unknown command: /${name}. Use /help to see available commands.`,
+            };
+        }
+        try {
+            const output = await cmd.handler(args, ctx);
+            if (output && typeof output === "object" && "inject" in output) {
+                return { handled: true, inject: output.inject };
+            }
+            return { handled: true, result: typeof output === "string" ? output : undefined };
+        }
+        catch (err) {
+            return { handled: true, result: `Error: ${err.message || String(err)}` };
+        }
+    }
+}

package/dist/slash-commands/types.d.ts

@@ -0,0 +1,44 @@
+import type { Agent } from "../agent.js";
+import type { SessionManager } from "../session.js";
+import type { Provider } from "../types.js";
+import type { ProviderRegistry } from "../provider-registry.js";
+import type { SkillRegistry } from "../skills/registry.js";
+import type { BashAllowlist } from "../approval/session-cache.js";
+import type { SettingsManager } from "../permissions/settings.js";
+import type { McpManager } from "../mcp/manager.js";
+import type { LspService } from "../lsp/index.js";
+import type { MemoryScope } from "../memory/index.js";
+export interface SlashCommandContext {
+    agent: Agent;
+    addMessage: (role: "user" | "assistant" | "error", content: string) => void;
+    clearMessages: () => void;
+    cwd: string;
+    exit: () => void;
+    sessionManager?: SessionManager;
+    createProvider: (providerId: string, apiKey: string, baseURL: string) => Provider;
+    openPicker: (mode: "model" | "key" | "provider" | "provider-add" | "login" | "logout", providerId?: string) => void;
+    registry: ProviderRegistry;
+    skillRegistry: SkillRegistry;
+    bashAllowlist?: BashAllowlist;
+    settingsManager?: SettingsManager;
+    mcpManager?: McpManager;
+    lspService?: LspService;
+    flushMemory?: () => Promise<void>;
+    runMemoryCompaction?: () => Promise<string>;
+    runMemorySummary?: (scope?: MemoryScope) => Promise<string>;
+    runMemoryRefresh?: (scope?: MemoryScope) => Promise<string>;
+}
+/**
+ * Return types for a slash command handler:
+ *   - string | void: the string (if any) is displayed as an assistant message
+ *   - { inject }: the content is sent to the agent as the user's next turn
+ *     (used by MCP prompts that expand a template into a user message)
+ */
+export type SlashCommandOutput = string | void | {
+    inject: string;
+};
+export interface SlashCommand {
+    name: string;
+    description: string;
+    handler: (args: string, ctx: SlashCommandContext) => Promise<SlashCommandOutput>;
+}

package/dist/slash-commands/types.js

@@ -0,0 +1 @@
+export {};

package/dist/slash-commands/unified.d.ts

@@ -0,0 +1,38 @@
+/**
+ * UnifiedCommand — a SlashCommand annotated with its source.
+ *
+ * Mirrors opencode's Command.Info.source field so consumers (TUI autocomplete,
+ * /help, /mcp list) can group and label commands uniformly without knowing
+ * where each one came from.
+ *
+ * Today only "builtin" and "mcp" are produced. A future "skill" source is
+ * reserved in the type so we don't need another migration when skills move
+ * into this abstraction.
+ */
+import type { SlashCommand } from "./types.js";
+export type CommandSource = "builtin" | "mcp" | "skill";
+export interface UnifiedCommand extends SlashCommand {
+    source: CommandSource;
+    /**
+     * For source === "mcp" this is the server name. Used by the TUI to render
+     * a ":mcp" badge and by /mcp list to group prompts under their server.
+     */
+    sourceLabel?: string;
+}
+export declare function isUnifiedCommand(cmd: SlashCommand): cmd is UnifiedCommand;
+/**
+ * Wrap a bare SlashCommand into a UnifiedCommand, defaulting to builtin.
+ * Used by the registry so callers that still pass plain SlashCommand objects
+ * (tests, older code paths) keep working.
+ */
+export declare function asUnified(cmd: SlashCommand, source?: CommandSource): UnifiedCommand;
+/**
+ * Stable source ordering used by UIs that group commands (e.g. the slash
+ * autocomplete). Lower rank renders first.
+ *
+ *   builtin → skill → mcp
+ *
+ * Tuned so that "native" commands dominate the palette and user-installed
+ * MCP servers appear after, echoing opencode's autocomplete layout.
+ */
+export declare function sourceRank(source: CommandSource | undefined): number;

package/dist/slash-commands/unified.js

@@ -0,0 +1,38 @@
+/**
+ * UnifiedCommand — a SlashCommand annotated with its source.
+ *
+ * Mirrors opencode's Command.Info.source field so consumers (TUI autocomplete,
+ * /help, /mcp list) can group and label commands uniformly without knowing
+ * where each one came from.
+ *
+ * Today only "builtin" and "mcp" are produced. A future "skill" source is
+ * reserved in the type so we don't need another migration when skills move
+ * into this abstraction.
+ */
+export function isUnifiedCommand(cmd) {
+    return typeof cmd.source === "string";
+}
+/**
+ * Wrap a bare SlashCommand into a UnifiedCommand, defaulting to builtin.
+ * Used by the registry so callers that still pass plain SlashCommand objects
+ * (tests, older code paths) keep working.
+ */
+export function asUnified(cmd, source = "builtin") {
+    return isUnifiedCommand(cmd) ? cmd : { ...cmd, source };
+}
+/**
+ * Stable source ordering used by UIs that group commands (e.g. the slash
+ * autocomplete). Lower rank renders first.
+ *
+ *   builtin → skill → mcp
+ *
+ * Tuned so that "native" commands dominate the palette and user-installed
+ * MCP servers appear after, echoing opencode's autocomplete layout.
+ */
+export function sourceRank(source) {
+    if (!source || source === "builtin")
+        return 0;
+    if (source === "skill")
+        return 1;
+    return 2; // "mcp"
+}

package/dist/system-prompt.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Backward-compatible system prompt wrapper.
+ */
+import type { PermissionMode, ThinkingLevel } from "./types.js";
+import type { SkillSummary } from "./skills/types.js";
+export interface SystemPromptOptions {
+    /** Agent display name */
+    agentName?: string;
+    /** Configured provider id */
+    configuredProvider?: string;
+    /** Configured model name */
+    configuredModel?: string;
+    /** Full configured model id */
+    configuredModelId?: string;
+    /** Names of available tools */
+    tools?: string[];
+    /** One-line description for each tool */
+    toolSnippets?: Record<string, string>;
+    /** Extra guidelines */
+    guidelines?: string[];
+    /** Working directory to include in prompt */
+    workingDir?: string;
+    /** Current thinking level */
+    thinkingLevel?: ThinkingLevel;
+    /** Current agent mode (default or plan) */
+    mode?: PermissionMode;
+    /** Current date override */
+    currentDate?: string;
+    /** Prompt-visible skills */
+    skills?: SkillSummary[];
+    /** Prompt-visible memory guidance and summaries */
+    memoryPrompt?: string;
+}
+export declare function buildSystemPrompt(options?: SystemPromptOptions): string;

package/dist/system-prompt.js

@@ -0,0 +1,7 @@
+/**
+ * Backward-compatible system prompt wrapper.
+ */
+import { composeSystemPrompt } from "./prompt/compose.js";
+export function buildSystemPrompt(options = {}) {
+    return composeSystemPrompt(options);
+}

package/dist/tools/bash.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Bash tool - execute shell commands with streaming capture.
+ */
+import type { ApprovalController } from "../approval/types.js";
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createBashTool(cwd: string, approval?: ApprovalController): ToolRegistryEntry;

package/dist/tools/bash.js

@@ -0,0 +1,135 @@
+/**
+ * Bash tool - execute shell commands with streaming capture.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { platform } from "node:os";
+import { gateToolAction } from "../approval/tool-helper.js";
+import { parseSearchBashCommand } from "../agent/tool-intent.js";
+import { referencesSensitivePath } from "./sensitive-paths.js";
+const MAX_OUTPUT = 50 * 1024;
+export function createBashTool(cwd, approval) {
+    return {
+        name: "bash",
+        description: "Execute a bash command in the working directory. Use timeout for long-running commands.",
+        parameters: {
+            type: "object",
+            properties: {
+                command: { type: "string", description: "Bash command to execute" },
+                timeout: { type: "number", description: "Timeout in seconds (optional)" },
+            },
+            required: ["command"],
+        },
+        async execute(args) {
+            if (!existsSync(cwd)) {
+                return { content: `Error: Working directory does not exist: ${cwd}`, isError: true };
+            }
+            const command = String(args.command);
+            const timeoutSec = typeof args.timeout === "number" ? args.timeout : 60;
+            const parsedSearch = parseSearchBashCommand(command);
+            if (referencesSensitivePath(command)) {
+                return {
+                    content: "Error: Bash access to sensitive credential storage is blocked.",
+                    isError: true,
+                    status: "blocked",
+                    metadata: {
+                        kind: "security",
+                        reason: "Sensitive credential storage is not accessible from general-purpose bash commands.",
+                    },
+                };
+            }
+            const gate = await gateToolAction(approval, { type: "bash", command, cwd });
+            if (!gate.approved)
+                return gate.result;
+            return new Promise((resolve) => {
+                const shell = platform() === "win32" ? "cmd.exe" : "bash";
+                const shellArgs = platform() === "win32" ? ["/c", command] : ["-c", command];
+                const child = spawn(shell, shellArgs, {
+                    cwd,
+                    stdio: ["ignore", "pipe", "pipe"],
+                    env: process.env,
+                });
+                let stdout = "";
+                let stderr = "";
+                let timedOut = false;
+                const timeoutHandle = setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGTERM");
+                    setTimeout(() => child.kill("SIGKILL"), 5000);
+                }, timeoutSec * 1000);
+                child.stdout?.on("data", (data) => {
+                    stdout += data.toString();
+                });
+                child.stderr?.on("data", (data) => {
+                    stderr += data.toString();
+                });
+                child.on("error", (err) => {
+                    clearTimeout(timeoutHandle);
+                    resolve({ content: `Error: ${err.message}`, isError: true });
+                });
+                child.on("close", (code) => {
+                    clearTimeout(timeoutHandle);
+                    let output = "";
+                    if (stdout)
+                        output += `stdout:\n${stdout}\n`;
+                    if (stderr)
+                        output += `stderr:\n${stderr}\n`;
+                    if (output === "")
+                        output = "(no output)\n";
+                    if (timedOut) {
+                        output += `[Command timed out after ${timeoutSec}s]`;
+                        resolve({
+                            content: output.trim(),
+                            isError: true,
+                            status: "timeout",
+                            metadata: {
+                                kind: parsedSearch ? "search" : "shell",
+                                pattern: parsedSearch?.pattern,
+                                path: parsedSearch?.path,
+                            },
+                        });
+                        return;
+                    }
+                    if (Buffer.byteLength(output, "utf-8") > MAX_OUTPUT) {
+                        output = Buffer.from(output, "utf-8").subarray(0, MAX_OUTPUT).toString("utf-8");
+                        output += "\n[Output truncated]";
+                    }
+                    const normalizedOutput = output.trim();
+                    if (parsedSearch && code === 1 && !stderr.trim()) {
+                        resolve({
+                            content: normalizedOutput === "(no output)" ? "stdout:\n(no matches)" : normalizedOutput,
+                            isError: false,
+                            status: "no_match",
+                            metadata: {
+                                kind: "search",
+                                pattern: parsedSearch.pattern,
+                                path: parsedSearch.path,
+                                matches: 0,
+                            },
+                        });
+                        return;
+                    }
+                    const isError = code !== 0;
+                    resolve({
+                        content: normalizedOutput,
+                        isError,
+                        status: isError ? "command_error" : "success",
+                        metadata: {
+                            kind: parsedSearch ? "search" : "shell",
+                            pattern: parsedSearch?.pattern,
+                            path: parsedSearch?.path,
+                            matches: parsedSearch ? countSearchMatches(stdout) : undefined,
+                        },
+                    });
+                });
+            });
+        },
+    };
+}
+function countSearchMatches(stdout) {
+    return stdout
+        .split("\n")
+        .map((line) => line.trim())
+        .filter(Boolean)
+        .length;
+}

package/dist/tools/edit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Edit tool - targeted string replacements with diff validation.
+ *
+ * This is the safest way to edit files: old_string must exist exactly once.
+ */
+import type { ApprovalController } from "../approval/types.js";
+import type { ToolRegistryEntry } from "../types.js";
+import { type LspService } from "../lsp/index.js";
+export interface EditArgs {
+    path: string;
+    edits: Array<{
+        oldText: string;
+        newText: string;
+    }>;
+}
+export declare function createEditTool(cwd: string, approval?: ApprovalController, lsp?: LspService): ToolRegistryEntry;

package/dist/tools/edit.js

@@ -0,0 +1,95 @@
+/**
+ * Edit tool - targeted string replacements with diff validation.
+ *
+ * This is the safest way to edit files: old_string must exist exactly once.
+ */
+import { constants } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
+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) {
+    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.",
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file" },
+                edits: {
+                    type: "array",
+                    description: "List of replacements. Each oldText must be unique in the file.",
+                    items: {
+                        type: "object",
+                        properties: {
+                            oldText: { type: "string", description: "Exact text to replace" },
+                            newText: { type: "string", description: "Replacement text" },
+                        },
+                        required: ["oldText", "newText"],
+                    },
+                },
+            },
+            required: ["path", "edits"],
+        },
+        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 };
+            }
+            // 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,
+                    };
+                }
+                if (count > 1) {
+                    return {
+                        content: `Error: oldText appears ${count} times in file. Must be unique: "${edit.oldText.slice(0, 50)}..."`,
+                        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) {
+                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,
+            };
+        },
+    };
+}

package/dist/tools/exa-mcp.d.ts

@@ -0,0 +1,3 @@
+import type { ToolResult } from "../types.js";
+export declare function resolveExaMcpUrl(): string;
+export declare function callExaMcpTool(name: string, args: Record<string, unknown>): Promise<ToolResult>;

package/dist/tools/exa-mcp.js

@@ -0,0 +1,74 @@
+const DEFAULT_BASE_URL = "https://mcp.exa.ai/mcp";
+export function resolveExaMcpUrl() {
+    const baseUrl = (process.env.BUBBLE_WEB_SEARCH_URL || DEFAULT_BASE_URL).trim();
+    const url = new URL(baseUrl);
+    const enabledTools = new Set((url.searchParams.get("tools") || "web_search_exa,crawling_exa")
+        .split(",")
+        .map((item) => item.trim())
+        .filter(Boolean));
+    enabledTools.add("web_search_exa");
+    enabledTools.add("crawling_exa");
+    url.searchParams.set("tools", [...enabledTools].join(","));
+    const apiKey = process.env.BUBBLE_EXA_API_KEY?.trim();
+    if (apiKey && !url.searchParams.get("exaApiKey")) {
+        url.searchParams.set("exaApiKey", apiKey);
+    }
+    return url.toString();
+}
+export async function callExaMcpTool(name, args) {
+    const response = await fetch(resolveExaMcpUrl(), {
+        method: "POST",
+        headers: {
+            Accept: "application/json, text/event-stream",
+            "Content-Type": "application/json",
+            "User-Agent": "bubble",
+        },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: 1,
+            method: "tools/call",
+            params: {
+                name,
+                arguments: args,
+            },
+        }),
+    }).catch((error) => {
+        throw new Error(error instanceof Error ? error.message : String(error));
+    });
+    if (!response.ok) {
+        const errorText = await response.text().catch(() => "");
+        return {
+            content: `Error: Remote MCP request failed with status ${response.status}${errorText ? `: ${errorText}` : ""}`,
+            isError: true,
+        };
+    }
+    const text = await response.text();
+    const result = parseMcpResponse(text);
+    if (!result) {
+        return { content: "No results found." };
+    }
+    return { content: result };
+}
+function parseMcpResponse(body) {
+    const lines = body.split("\n");
+    for (const line of lines) {
+        if (!line.startsWith("data: "))
+            continue;
+        try {
+            const parsed = JSON.parse(line.slice(6));
+            const text = parsed.result?.content?.find((item) => item.type === "text")?.text;
+            if (text)
+                return text;
+        }
+        catch {
+            // Ignore malformed SSE lines.
+        }
+    }
+    try {
+        const parsed = JSON.parse(body);
+        return parsed.result?.content?.find((item) => item.type === "text")?.text;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/tools/exit-plan-mode.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.
+ */
+import type { PermissionMode, PlanDecision, ToolRegistryEntry } from "../types.js";
+export interface PlanController {
+    /** Reads the current permission mode (used to gate the tool). */
+    getMode: () => PermissionMode;
+    /** Ask the user to approve/reject/edit the proposed plan. */
+    requestApproval(plan: string): Promise<PlanDecision>;
+    /** Switch the agent's mode. Called after an approval so the next turn runs unconstrained. */
+    setMode(mode: PermissionMode): void;
+}
+export declare function createExitPlanModeTool(controller: PlanController): ToolRegistryEntry;