@bubblebrain-ai/bubble 0.0.1

package/dist/tools/tool-search.js

@@ -0,0 +1,124 @@
+/**
+ * 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.
+ */
+export function createToolSearchTool(controller) {
+    return {
+        name: "tool_search",
+        readOnly: true,
+        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 ' +
+            '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: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: 'Query to find deferred tools. Use "select:<name>,<name>" for direct selection, or keywords to search.',
+                },
+                max_results: {
+                    type: "number",
+                    description: "Maximum number of matches to return (default 5).",
+                },
+            },
+            required: ["query"],
+        },
+        async execute(args) {
+            const query = typeof args.query === "string" ? args.query : "";
+            const maxResults = typeof args.max_results === "number" && args.max_results > 0
+                ? Math.min(Math.floor(args.max_results), 25)
+                : 5;
+            const deferred = controller.listDeferred();
+            if (deferred.length === 0) {
+                return { content: "No deferred tools are registered in this session." };
+            }
+            let matches;
+            const selectPrefix = "select:";
+            if (query.startsWith(selectPrefix)) {
+                const names = new Set(query
+                    .slice(selectPrefix.length)
+                    .split(",")
+                    .map((s) => s.trim())
+                    .filter(Boolean));
+                matches = deferred.filter((t) => names.has(t.name));
+                if (matches.length === 0) {
+                    const available = deferred.map((t) => t.name).join(", ");
+                    return {
+                        content: `No deferred tool matched select list. Known deferred tools: ${available}`,
+                        isError: true,
+                    };
+                }
+            }
+            else {
+                matches = rankByKeywords(deferred, query).slice(0, maxResults);
+                if (matches.length === 0) {
+                    return {
+                        content: `No deferred tools matched "${query}". Use query "select:<name>" to fetch by exact name, or try different keywords.`,
+                    };
+                }
+            }
+            controller.unlock(matches.map((t) => t.name));
+            const lines = ["<functions>"];
+            for (const tool of matches) {
+                const schema = {
+                    description: tool.description,
+                    name: tool.name,
+                    parameters: tool.parameters,
+                };
+                lines.push(`<function>${JSON.stringify(schema)}</function>`);
+            }
+            lines.push("</functions>");
+            lines.push("");
+            lines.push(`Loaded ${matches.length} tool${matches.length === 1 ? "" : "s"}. They are now available and callable on the next turn.`);
+            return { content: lines.join("\n") };
+        },
+    };
+}
+function rankByKeywords(tools, rawQuery) {
+    const terms = rawQuery.toLowerCase().split(/\s+/).filter(Boolean);
+    if (terms.length === 0)
+        return [];
+    const requiredTerms = [];
+    const optionalTerms = [];
+    for (const term of terms) {
+        if (term.startsWith("+") && term.length > 1) {
+            requiredTerms.push(term.slice(1));
+        }
+        else {
+            optionalTerms.push(term);
+        }
+    }
+    const scored = [];
+    for (const tool of tools) {
+        const haystack = `${tool.name} ${tool.description}`.toLowerCase();
+        if (!requiredTerms.every((t) => haystack.includes(t)))
+            continue;
+        let score = 0;
+        for (const t of optionalTerms) {
+            if (tool.name.toLowerCase().includes(t))
+                score += 3;
+            if (tool.description.toLowerCase().includes(t))
+                score += 1;
+        }
+        if (requiredTerms.length > 0 && optionalTerms.length === 0) {
+            // Required-only query: every required term already matched, surface by name strength.
+            score = requiredTerms.reduce((acc, t) => acc + (tool.name.toLowerCase().includes(t) ? 3 : 1), 0);
+        }
+        if (score > 0)
+            scored.push({ tool, score });
+    }
+    scored.sort((a, b) => b.score - a.score);
+    return scored.map((s) => s.tool);
+}

package/dist/tools/web-fetch.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Web fetch tool - remote Exa MCP-backed page extraction.
+ */
+import type { ApprovalController } from "../approval/types.js";
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createWebFetchTool(approval?: ApprovalController): ToolRegistryEntry;

package/dist/tools/web-fetch.js

@@ -0,0 +1,75 @@
+/**
+ * Web fetch tool - remote Exa MCP-backed page extraction.
+ */
+import { callExaMcpTool } from "./exa-mcp.js";
+export function createWebFetchTool(approval) {
+    return {
+        name: "web_fetch",
+        readOnly: true,
+        description: "Fetch and extract the contents of a specific URL using a remote web crawling service.",
+        parameters: {
+            type: "object",
+            properties: {
+                url: { type: "string", description: "The URL to fetch and extract" },
+                query: { type: "string", description: "Optional topic to focus the extracted summary/highlights on" },
+                maxCharacters: {
+                    type: "number",
+                    description: "Maximum number of characters to include in the extracted context",
+                },
+                livecrawl: {
+                    type: "string",
+                    description: "Live crawl mode",
+                    enum: ["never", "fallback", "preferred", "always"],
+                },
+                livecrawlTimeout: {
+                    type: "number",
+                    description: "Maximum live crawl time in milliseconds",
+                },
+                subpages: {
+                    type: "number",
+                    description: "Optional number of linked subpages to fetch as well",
+                },
+                subpageTarget: {
+                    type: "string",
+                    description: "Optional guidance for which subpages matter most",
+                },
+            },
+            required: ["url"],
+        },
+        async execute(args) {
+            const url = typeof args.url === "string" ? args.url.trim() : "";
+            if (!url) {
+                return { content: "Error: url is required", isError: true };
+            }
+            if (approval) {
+                const result = approval.checkRules({ tool: "WebFetch", url });
+                if (result.decision === "deny") {
+                    return {
+                        content: `Error: WebFetch blocked by deny rule: ${result.rule?.source ?? "<unknown>"} (${url})`,
+                        isError: true,
+                    };
+                }
+            }
+            const query = typeof args.query === "string" ? args.query.trim() : undefined;
+            return callExaMcpTool("crawling_exa", {
+                urls: [url],
+                livecrawl: typeof args.livecrawl === "string" ? args.livecrawl : "fallback",
+                ...(typeof args.livecrawlTimeout === "number" ? { livecrawlTimeout: args.livecrawlTimeout } : {}),
+                ...(typeof args.subpages === "number" ? { subpages: args.subpages } : {}),
+                ...(typeof args.subpageTarget === "string" && args.subpageTarget.trim()
+                    ? { subpageTarget: args.subpageTarget.trim() }
+                    : {}),
+                text: true,
+                context: typeof args.maxCharacters === "number" ? { maxCharacters: args.maxCharacters } : true,
+                summary: query ? { query } : true,
+                highlights: query
+                    ? {
+                        query,
+                        numSentences: 3,
+                        highlightsPerUrl: 5,
+                    }
+                    : undefined,
+            });
+        },
+    };
+}

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

@@ -0,0 +1,5 @@
+/**
+ * Web search tool - remote Exa MCP-backed search.
+ */
+import type { ToolRegistryEntry } from "../types.js";
+export declare function createWebSearchTool(): ToolRegistryEntry;

package/dist/tools/web-search.js

@@ -0,0 +1,49 @@
+/**
+ * Web search tool - remote Exa MCP-backed search.
+ */
+import { callExaMcpTool } from "./exa-mcp.js";
+const DEFAULT_RESULTS = 8;
+export function createWebSearchTool() {
+    return {
+        name: "web_search",
+        readOnly: true,
+        description: "Search the web using a remote search service and return current, structured results.",
+        parameters: {
+            type: "object",
+            properties: {
+                query: { type: "string", description: "Web search query" },
+                numResults: { type: "number", description: `Number of search results to return (default: ${DEFAULT_RESULTS})` },
+                livecrawl: {
+                    type: "string",
+                    description: "Live crawl mode",
+                    enum: ["fallback", "preferred"],
+                },
+                type: {
+                    type: "string",
+                    description: "Search type",
+                    enum: ["auto", "fast", "deep"],
+                },
+                contextMaxCharacters: {
+                    type: "number",
+                    description: "Maximum number of characters to return in the result context",
+                },
+            },
+            required: ["query"],
+        },
+        async execute(args) {
+            const query = typeof args.query === "string" ? args.query.trim() : "";
+            if (!query) {
+                return { content: "Error: query is required", isError: true };
+            }
+            return callExaMcpTool("web_search_exa", {
+                query,
+                type: typeof args.type === "string" ? args.type : "auto",
+                numResults: typeof args.numResults === "number" ? args.numResults : DEFAULT_RESULTS,
+                livecrawl: typeof args.livecrawl === "string" ? args.livecrawl : "fallback",
+                ...(typeof args.contextMaxCharacters === "number"
+                    ? { contextMaxCharacters: args.contextMaxCharacters }
+                    : {}),
+            });
+        },
+    };
+}

package/dist/tools/write.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Write tool - create or overwrite files.
+ */
+import type { ApprovalController } from "../approval/types.js";
+import type { ToolRegistryEntry } from "../types.js";
+import { type LspService } from "../lsp/index.js";
+export interface WriteToolOptions {
+    /** If true, refuse to overwrite existing files */
+    refuseOverwrite?: boolean;
+}
+export declare function createWriteTool(cwd: string, options?: WriteToolOptions, approval?: ApprovalController, lsp?: LspService): ToolRegistryEntry;

package/dist/tools/write.js

@@ -0,0 +1,77 @@
+/**
+ * Write tool - create or overwrite files.
+ */
+import { constants } from "node:fs";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createTwoFilesPatch } from "diff";
+import { gateToolAction } from "../approval/tool-helper.js";
+import { formatDiagnosticBlocks } from "../lsp/index.js";
+export function createWriteTool(cwd, options = {}, approval, lsp) {
+    return {
+        name: "write",
+        description: `Write a file to disk. Creates parent directories if needed.${options.refuseOverwrite ? " Will not overwrite existing files." : ""}`,
+        parameters: {
+            type: "object",
+            properties: {
+                path: { type: "string", description: "Path to the file (relative or absolute)" },
+                content: { type: "string", description: "File contents" },
+            },
+            required: ["path", "content"],
+        },
+        async execute(args) {
+            const filePath = resolve(cwd, args.path);
+            if (options.refuseOverwrite) {
+                try {
+                    await access(filePath, constants.F_OK);
+                    return {
+                        content: `Error: File already exists: ${filePath}. Use edit tool to modify existing files.`,
+                        isError: true,
+                    };
+                }
+                catch {
+                    // file doesn't exist, proceed
+                }
+            }
+            let existed = false;
+            let oldContent = "";
+            try {
+                oldContent = await readFile(filePath, "utf-8");
+                existed = true;
+            }
+            catch {
+                // new file
+            }
+            const diff = createTwoFilesPatch(filePath, filePath, oldContent, args.content, "original", "modified", { context: 3 });
+            const gate = await gateToolAction(approval, {
+                type: "write",
+                path: filePath,
+                content: args.content,
+                diff,
+                fileExists: existed,
+            });
+            if (!gate.approved)
+                return gate.result;
+            try {
+                await mkdir(dirname(filePath), { recursive: true });
+                await writeFile(filePath, args.content, "utf-8");
+                const lineCount = args.content.split("\n").length;
+                const verb = existed ? "Updated" : "Wrote";
+                let content = `${verb} ${lineCount} lines to ${filePath}`;
+                if (lsp) {
+                    try {
+                        await lsp.touchFile(filePath, "document");
+                        content += formatDiagnosticBlocks(cwd, filePath, lsp.diagnostics());
+                    }
+                    catch {
+                        // LSP diagnostics should not turn a successful write into a failed tool call.
+                    }
+                }
+                return { content };
+            }
+            catch (err) {
+                return { content: `Error: ${err.message}`, isError: true };
+            }
+        },
+    };
+}

package/dist/tui/display-history.d.ts

@@ -0,0 +1,35 @@
+import type { ToolResultMetadata } from "../types.js";
+export interface CompactionMeta {
+    turns: number;
+    messages: number;
+    tokensSaved: number;
+    summarySections: Array<{
+        label: string;
+        content: string;
+    }>;
+    contextWindow?: number;
+    compactedAt: number;
+}
+export interface DisplayMessage {
+    role: "user" | "assistant" | "error";
+    content: string;
+    reasoning?: string;
+    toolCalls?: DisplayToolCall[];
+    status?: "thinking" | "responding";
+    streaming?: boolean;
+    syntheticKind?: "ui_compact_card";
+    hiddenCount?: number;
+    compactionMeta?: CompactionMeta;
+}
+export interface DisplayToolCall {
+    id: string;
+    name: string;
+    args: Record<string, any>;
+    status?: "pending" | "running" | "completed" | "error";
+    result?: string;
+    isError?: boolean;
+    metadata?: ToolResultMetadata;
+}
+export declare function compactDisplayMessages(messages: DisplayMessage[]): DisplayMessage[];
+export declare function truncateText(value: string, maxChars: number): string;
+export declare function formatCompactNumber(n: number): string;

package/dist/tui/display-history.js

@@ -0,0 +1,243 @@
+const MAX_VISIBLE_MESSAGES = 80;
+const FULL_DETAIL_WINDOW = 24;
+const MAX_OLD_CONTENT_CHARS = 1200;
+const MAX_OLD_REASONING_CHARS = 600;
+const MAX_OLD_TOOL_RESULT_CHARS = 800;
+const COMPACTION_SUMMARY_ITEMS = 6;
+const COMPACTION_FILE_LIMIT = 8;
+const TOOL_PATH_KEYS = ["file", "path", "paths", "filePath"];
+export function compactDisplayMessages(messages) {
+    if (messages.length === 0) {
+        return messages;
+    }
+    let hiddenCount = 0;
+    let accumulatedTurns = 0;
+    let accumulatedTokens = 0;
+    const summarySections = [];
+    const withoutSynthetic = messages.filter((message) => {
+        if (message.syntheticKind !== "ui_compact_card") {
+            return true;
+        }
+        hiddenCount += message.hiddenCount ?? 0;
+        if (message.compactionMeta) {
+            accumulatedTurns += message.compactionMeta.turns;
+            accumulatedTokens += message.compactionMeta.tokensSaved;
+            for (const section of message.compactionMeta.summarySections) {
+                summarySections.push(section);
+            }
+        }
+        return false;
+    });
+    const overflow = Math.max(0, withoutSynthetic.length - MAX_VISIBLE_MESSAGES);
+    hiddenCount += overflow;
+    const visible = overflow > 0 ? withoutSynthetic.slice(overflow) : withoutSynthetic;
+    const detailStart = Math.max(0, visible.length - FULL_DETAIL_WINDOW);
+    const compacted = visible.map((message, index) => {
+        if (message.syntheticKind === "ui_compact_card") {
+            return message;
+        }
+        return index < detailStart ? compactDisplayMessage(message) : message;
+    });
+    if (hiddenCount === 0) {
+        return compacted;
+    }
+    const truncatedMessages = visible.slice(0, Math.max(1, detailStart));
+    const extractedMeta = extractCompactionMeta(truncatedMessages, hiddenCount, accumulatedTurns, accumulatedTokens, summarySections);
+    return [buildCompactCard(extractedMeta), ...compacted];
+}
+function extractCompactionMeta(truncatedMessages, hiddenCount, previousTurns, previousTokens, previousSections) {
+    const turnsInBatch = countUserTurns(truncatedMessages);
+    const totalTurns = previousTurns + turnsInBatch;
+    const messagesInBatch = truncatedMessages.length;
+    const totalMessages = hiddenCount;
+    const estimatedTokens = estimateTokenSavings(truncatedMessages);
+    const totalTokens = previousTokens + estimatedTokens;
+    const sections = [
+        ...previousSections,
+        ...extractSummarySections(truncatedMessages),
+    ];
+    return {
+        turns: totalTurns,
+        messages: totalMessages,
+        tokensSaved: totalTokens > 0 ? totalTokens : estimatedTokens,
+        summarySections: mergeSummarySections(sections, COMPACTION_SUMMARY_ITEMS),
+        compactedAt: Date.now(),
+    };
+}
+function countUserTurns(messages) {
+    return messages.filter((message) => message.role === "user").length;
+}
+function estimateTokenSavings(messages) {
+    let chars = 0;
+    for (const message of messages) {
+        chars += message.content.length;
+        chars += (message.reasoning?.length ?? 0);
+        for (const tool of message.toolCalls ?? []) {
+            chars += (tool.result?.length ?? 0);
+            chars += JSON.stringify(tool.args).length;
+        }
+    }
+    return Math.ceil(chars / 4);
+}
+function extractSummarySections(messages) {
+    const sections = [];
+    const userMessages = messages
+        .filter((m) => m.role === "user")
+        .map((m) => m.content);
+    if (userMessages.length > 0) {
+        sections.push({
+            label: "Progress",
+            content: userMessages.slice(0, 5).map((c) => `- ${shorten(c, 100)}`).join("\n"),
+        });
+    }
+    const assistantInsights = messages
+        .filter((m) => m.role === "assistant" && m.content.trim())
+        .map((m) => m.content.trim());
+    if (assistantInsights.length > 0) {
+        sections.push({
+            label: "Decisions",
+            content: assistantInsights.slice(0, 3).map((c) => `- ${shorten(c, 120)}`).join("\n"),
+        });
+    }
+    const files = collectFiles(messages);
+    if (files.length > 0) {
+        sections.push({
+            label: "Files",
+            content: files.slice(0, COMPACTION_FILE_LIMIT).join(", "),
+        });
+    }
+    const toolFindings = collectToolFindings(messages);
+    if (toolFindings.length > 0) {
+        sections.push({
+            label: "Tools",
+            content: toolFindings.slice(0, 5).map((f) => `- ${f}`).join("\n"),
+        });
+    }
+    return sections;
+}
+function collectFiles(messages) {
+    const files = new Set();
+    for (const message of messages) {
+        for (const tool of message.toolCalls ?? []) {
+            for (const key of TOOL_PATH_KEYS) {
+                const value = tool.args[key];
+                if (typeof value === "string" && value) {
+                    files.add(value);
+                }
+                if (Array.isArray(value)) {
+                    for (const item of value) {
+                        if (typeof item === "string" && item) {
+                            files.add(item);
+                        }
+                    }
+                }
+            }
+        }
+    }
+    return [...files].slice(0, COMPACTION_FILE_LIMIT);
+}
+function collectToolFindings(messages) {
+    const findings = [];
+    for (const message of messages) {
+        for (const tool of message.toolCalls ?? []) {
+            if (tool.result && tool.result.length > 0) {
+                findings.push(`${tool.name}: ${shorten(tool.result, 80)}`);
+                if (findings.length >= 10)
+                    break;
+            }
+        }
+        if (findings.length >= 10)
+            break;
+    }
+    return findings;
+}
+function mergeSummarySections(sections, maxItems) {
+    const merged = new Map();
+    for (const section of sections) {
+        const existing = merged.get(section.label);
+        if (existing) {
+            merged.set(section.label, `${existing}\n${section.content}`);
+        }
+        else {
+            merged.set(section.label, section.content);
+        }
+    }
+    return [...merged.entries()]
+        .map(([label, content]) => ({ label, content }))
+        .slice(0, maxItems);
+}
+function buildCompactCard(meta) {
+    const formatNum = (n) => {
+        if (n >= 1_000_000)
+            return `${(n / 1_000_000).toFixed(1)}M`;
+        if (n >= 1_000)
+            return `${(n / 1_000).toFixed(1)}K`;
+        return String(n);
+    };
+    const parts = [];
+    if (meta.turns > 0) {
+        parts.push(`${meta.turns} turn${meta.turns === 1 ? "" : "s"}`);
+    }
+    if (meta.messages > 0) {
+        parts.push(`${meta.messages} message${meta.messages === 1 ? "" : "s"}`);
+    }
+    if (meta.tokensSaved > 0) {
+        parts.push(`~${formatNum(meta.tokensSaved)} tokens`);
+    }
+    const statsLine = parts.length > 0 ? `┃ ${parts.join(" · ")}` : "";
+    const sectionLines = [];
+    for (const section of meta.summarySections) {
+        sectionLines.push(`┃ ${section.label}: ${section.content.split("\n")[0]}`);
+    }
+    const content = [statsLine, ...sectionLines].filter(Boolean).join("\n");
+    return {
+        role: "assistant",
+        content,
+        syntheticKind: "ui_compact_card",
+        hiddenCount: meta.messages,
+        compactionMeta: meta,
+        status: "responding",
+    };
+}
+function compactDisplayMessage(message) {
+    if (message.syntheticKind === "ui_compact_card") {
+        return message;
+    }
+    return {
+        ...message,
+        content: truncateText(message.content, MAX_OLD_CONTENT_CHARS),
+        reasoning: message.reasoning
+            ? truncateText(message.reasoning, MAX_OLD_REASONING_CHARS)
+            : message.reasoning,
+        toolCalls: message.toolCalls?.map((toolCall) => ({
+            ...toolCall,
+            result: toolCall.result
+                ? truncateText(toolCall.result, MAX_OLD_TOOL_RESULT_CHARS)
+                : toolCall.result,
+        })),
+    };
+}
+export function truncateText(value, maxChars) {
+    if (value.length <= maxChars) {
+        return value;
+    }
+    const head = Math.max(1, Math.floor(maxChars * 0.7));
+    const tail = Math.max(1, maxChars - head - 32);
+    const omitted = value.length - head - tail;
+    const separator = "─".repeat(12);
+    return `${value.slice(0, head)}\n${separator} ✂ ${omitted} chars truncated ${separator}\n${value.slice(-tail)}`;
+}
+function shorten(text, maxChars) {
+    const normalized = text.replace(/\s+/g, " ").trim();
+    if (normalized.length <= maxChars) {
+        return normalized;
+    }
+    return `${normalized.slice(0, maxChars - 1)}…`;
+}
+export function formatCompactNumber(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}K`;
+    return String(n);
+}

package/dist/tui/file-mentions.d.ts

@@ -0,0 +1,29 @@
+export interface AtContext {
+    start: number;
+    end: number;
+    query: string;
+}
+export interface FileSuggestion {
+    path: string;
+    score: number;
+}
+export interface ExpandedMention {
+    path: string;
+    bytes: number;
+    truncated: boolean;
+}
+export interface ExpandResult {
+    text: string;
+    expanded: ExpandedMention[];
+    missing: string[];
+    skipped: Array<{
+        path: string;
+        reason: string;
+        bytes?: number;
+    }>;
+}
+export declare function findAtContext(text: string, cursor: number): AtContext | null;
+export declare function filterFileSuggestions(files: string[], query: string, limit?: number): FileSuggestion[];
+export declare function listProjectFiles(cwd: string): Promise<string[]>;
+export declare function invalidateFileListCache(cwd?: string): void;
+export declare function expandAtMentions(text: string, cwd: string): Promise<ExpandResult>;