@bubblebrain-ai/bubble 0.0.1

package/README.md

@@ -0,0 +1,70 @@
+# Bubble
+
+Bubble is a terminal coding agent for working inside local project folders. It can read and edit files, run commands with approval controls, use project skills, connect MCP tools, and keep persistent memory across sessions.
+
+## Requirements
+
+- Bun
+- Node.js and npm
+
+Install Bun if it is not already available:
+
+```bash
+curl -fsSL https://bun.sh/install | bash
+```
+
+## Install
+
+From npm:
+
+```bash
+npm install -g @bubblebrain-ai/bubble
+```
+
+From a local package tarball:
+
+```bash
+npm install -g ./bubblebrain-ai-bubble-0.0.1.tgz
+```
+
+## Usage
+
+Start Bubble in the current directory:
+
+```bash
+bubble
+```
+
+Start Bubble for a specific project:
+
+```bash
+bubble --cwd /path/to/project
+```
+
+Show CLI options:
+
+```bash
+bubble --help
+```
+
+## Configuration
+
+Bubble stores user configuration, sessions, permissions, skills, and memory under:
+
+```text
+~/.bubble
+```
+
+In the app, use `/login` or provider commands to configure model access.
+
+## Memory
+
+Bubble maintains persistent memory automatically from prior sessions. Useful commands:
+
+```text
+/memory status
+/memory search <query>
+/memory refresh
+```
+
+Memory is maintained by a background pipeline and can be refreshed manually when you want new session information to be indexed immediately.

package/dist/agent/evidence-tracker.d.ts

@@ -0,0 +1,15 @@
+import type { ParsedToolCall, ToolResult } from "../types.js";
+export interface InvestigationCoverage {
+    configLoadPaths: boolean;
+    envReads: boolean;
+    persistencePaths: boolean;
+    exposurePaths: boolean;
+    maskingSignals: boolean;
+}
+export declare class EvidenceTracker {
+    private coverage;
+    observe(toolCall: Pick<ParsedToolCall, "name" | "parsedArgs">, result: ToolResult): void;
+    snapshot(): InvestigationCoverage;
+    key(): string;
+    isCoreCoverageComplete(): boolean;
+}

package/dist/agent/evidence-tracker.js

@@ -0,0 +1,93 @@
+const DEFAULT_COVERAGE = {
+    configLoadPaths: false,
+    envReads: false,
+    persistencePaths: false,
+    exposurePaths: false,
+    maskingSignals: false,
+};
+const CONFIG_PATTERNS = [
+    /\bconfig\.(json|ya?ml|toml|ini)\b/i,
+    /\bsettings\.(json|ya?ml|toml)\b/i,
+    /\bauth\.json\b/i,
+    /\buserconfig\b/i,
+    /\breadfilesync\b/i,
+];
+const ENV_PATTERNS = [
+    /\bprocess\.env\b/i,
+    /\bimport\.meta\.env\b/i,
+    /\bgetenv\(/i,
+    /\bloadenv\b/i,
+    /\bdotenv\b/i,
+    /\b\.env\b/i,
+];
+const PERSISTENCE_PATTERNS = [
+    /\bwritefilesync\b/i,
+    /\bwritefile\b/i,
+    /\bauth\.json\b/i,
+    /\bconfig\.json\b/i,
+    /\blocalstorage\b/i,
+    /\bsqlite\b/i,
+    /\bkeychain\b/i,
+    /\bcredential\b/i,
+    /\bstore\b/i,
+];
+const EXPOSURE_PATTERNS = [
+    /\bconsole\.log\b/i,
+    /\blogger\./i,
+    /\bres\.json\b/i,
+    /\breturn\s+\{/i,
+    /\bwindow\./i,
+    /\bdocument\./i,
+    /\bserialize\b/i,
+    /\bresponse\b/i,
+];
+const MASKING_PATTERNS = [
+    /\bmask(key|ed)?\b/i,
+    /\bredact(ed|ion)?\b/i,
+    /\bhidden\b/i,
+    /\bobfuscated\b/i,
+    /\*\*\*\*/i,
+    /\.\.\./i,
+];
+export class EvidenceTracker {
+    coverage = { ...DEFAULT_COVERAGE };
+    observe(toolCall, result) {
+        const haystack = [
+            typeof toolCall.parsedArgs.path === "string" ? toolCall.parsedArgs.path : "",
+            typeof toolCall.parsedArgs.command === "string" ? toolCall.parsedArgs.command : "",
+            typeof toolCall.parsedArgs.pattern === "string" ? toolCall.parsedArgs.pattern : "",
+            result.content,
+        ].join("\n");
+        if (!this.coverage.configLoadPaths && matchesAny(CONFIG_PATTERNS, haystack)) {
+            this.coverage.configLoadPaths = true;
+        }
+        if (!this.coverage.envReads && matchesAny(ENV_PATTERNS, haystack)) {
+            this.coverage.envReads = true;
+        }
+        if (!this.coverage.persistencePaths && matchesAny(PERSISTENCE_PATTERNS, haystack)) {
+            this.coverage.persistencePaths = true;
+        }
+        if (!this.coverage.exposurePaths && matchesAny(EXPOSURE_PATTERNS, haystack)) {
+            this.coverage.exposurePaths = true;
+        }
+        if (!this.coverage.maskingSignals && matchesAny(MASKING_PATTERNS, haystack)) {
+            this.coverage.maskingSignals = true;
+        }
+    }
+    snapshot() {
+        return { ...this.coverage };
+    }
+    key() {
+        const coverage = this.snapshot();
+        return Object.values(coverage).map((value) => (value ? "1" : "0")).join("");
+    }
+    isCoreCoverageComplete() {
+        return this.coverage.configLoadPaths
+            && this.coverage.envReads
+            && this.coverage.persistencePaths
+            && this.coverage.exposurePaths;
+    }
+}
+function matchesAny(patterns, haystack) {
+    return patterns.some((pattern) => pattern.test(haystack));
+}

package/dist/agent/execution-governor.d.ts

@@ -0,0 +1,30 @@
+import type { ParsedToolCall, ToolRegistryEntry, ToolResult } from "../types.js";
+import type { TaskType } from "./task-classifier.js";
+export interface GovernorDecision {
+    blockedResult?: ToolResult;
+}
+export declare class ExecutionGovernor {
+    private taskType;
+    private budget;
+    private history;
+    private totalSteps;
+    private searchSteps;
+    private searchFrozen;
+    private reminderQueue;
+    private warnedFamilies;
+    private softTotalWarned;
+    private softSearchWarned;
+    constructor(taskType: TaskType);
+    consumePendingReminders(): string[];
+    snapshot(): {
+        totalSteps: number;
+        searchSteps: number;
+        searchFrozen: boolean;
+    };
+    filterToolDefinitions(toolDefinitions: ToolRegistryEntry[]): ToolRegistryEntry[];
+    beforeToolCall(toolCall: ParsedToolCall): GovernorDecision;
+    afterToolResult(toolCall: ParsedToolCall, result: ToolResult): void;
+    private trailingNoProgressCount;
+    private freezeSearch;
+    private maybeWarnOnSoftBudgets;
+}

package/dist/agent/execution-governor.js

@@ -0,0 +1,169 @@
+import { analyzeToolIntent } from "./tool-intent.js";
+import { buildInvestigationReminder, buildLoopWarningReminder, buildSearchFreezeReminder } from "../prompt/reminders.js";
+const BUDGETS = {
+    security_investigation: {
+        softTotalSteps: 14,
+        softSearchSteps: 6,
+        maxNoProgressExactRepeats: 2,
+        maxNoProgressFamilyRepeats: 3,
+        warningFamilyRepeats: 2,
+    },
+    code_search: {
+        softTotalSteps: 16,
+        softSearchSteps: 8,
+        maxNoProgressExactRepeats: 3,
+        maxNoProgressFamilyRepeats: 4,
+        warningFamilyRepeats: 3,
+    },
+    general: {
+        softTotalSteps: 18,
+        softSearchSteps: 8,
+        maxNoProgressExactRepeats: 3,
+        maxNoProgressFamilyRepeats: 4,
+        warningFamilyRepeats: 3,
+    },
+};
+const SEARCH_TOOLS_DISABLED = new Set(["grep", "web_search", "web_fetch"]);
+export class ExecutionGovernor {
+    taskType;
+    budget;
+    history = [];
+    totalSteps = 0;
+    searchSteps = 0;
+    searchFrozen = false;
+    reminderQueue = [];
+    warnedFamilies = new Set();
+    softTotalWarned = false;
+    softSearchWarned = false;
+    constructor(taskType) {
+        this.taskType = taskType;
+        this.budget = BUDGETS[taskType];
+        if (taskType === "security_investigation") {
+            this.reminderQueue.push(buildInvestigationReminder());
+        }
+    }
+    consumePendingReminders() {
+        const reminders = [...this.reminderQueue];
+        this.reminderQueue.length = 0;
+        return reminders;
+    }
+    snapshot() {
+        return {
+            totalSteps: this.totalSteps,
+            searchSteps: this.searchSteps,
+            searchFrozen: this.searchFrozen,
+        };
+    }
+    filterToolDefinitions(toolDefinitions) {
+        if (!this.searchFrozen) {
+            return toolDefinitions;
+        }
+        return toolDefinitions.filter((tool) => !SEARCH_TOOLS_DISABLED.has(tool.name));
+    }
+    beforeToolCall(toolCall) {
+        const intent = analyzeToolIntent(toolCall);
+        if (intent.family === "search") {
+            if (this.searchFrozen) {
+                return {
+                    blockedResult: blockedResult("Search blocked: repeated low-yield searching is now frozen for this task.", "blocked", "Search frozen due to repeated low-yield searching."),
+                };
+            }
+            const signature = intent.search?.signature;
+            const familyKey = intent.search?.familyKey;
+            if (signature && this.trailingNoProgressCount((entry) => entry.signature === signature) >= this.budget.maxNoProgressExactRepeats) {
+                this.freezeSearch(`Repeated the same search signature without new evidence: ${signature}`);
+                return {
+                    blockedResult: blockedResult("Search blocked: repeated the same search multiple times without new evidence.", "blocked", "Repeated identical search without progress."),
+                };
+            }
+            if (familyKey) {
+                const familyNoProgress = this.trailingNoProgressCount((entry) => entry.familyKey === familyKey);
+                if (familyNoProgress >= this.budget.maxNoProgressFamilyRepeats) {
+                    this.freezeSearch(`Repeated the same search family without new evidence: ${familyKey}`);
+                    return {
+                        blockedResult: blockedResult("Search blocked: repeated the same search family without new evidence.", "blocked", "Repeated similar searches without progress."),
+                    };
+                }
+                if (familyNoProgress >= this.budget.warningFamilyRepeats && !this.warnedFamilies.has(familyKey)) {
+                    this.warnedFamilies.add(familyKey);
+                    this.reminderQueue.push(buildLoopWarningReminder("Repeated searches are yielding little new evidence. Change your hypothesis, narrow the path, or summarize current findings instead of repeating variants."));
+                }
+            }
+        }
+        this.totalSteps += 1;
+        if (intent.family === "search") {
+            this.searchSteps += 1;
+        }
+        this.maybeWarnOnSoftBudgets(intent.family === "search");
+        return {};
+    }
+    afterToolResult(toolCall, result) {
+        const intent = analyzeToolIntent(toolCall);
+        const progress = inferProgress(intent, result);
+        this.history.push({
+            family: intent.family,
+            signature: intent.search?.signature,
+            familyKey: intent.search?.familyKey,
+            progress,
+        });
+    }
+    trailingNoProgressCount(predicate) {
+        let count = 0;
+        for (let index = this.history.length - 1; index >= 0; index--) {
+            const entry = this.history[index];
+            if (!predicate(entry)) {
+                break;
+            }
+            if (entry.progress) {
+                break;
+            }
+            count += 1;
+        }
+        return count;
+    }
+    freezeSearch(reason) {
+        if (this.searchFrozen) {
+            return;
+        }
+        this.searchFrozen = true;
+        this.reminderQueue.push(buildSearchFreezeReminder(reason));
+    }
+    maybeWarnOnSoftBudgets(isSearchStep) {
+        if (!this.softTotalWarned && this.totalSteps >= this.budget.softTotalSteps) {
+            this.softTotalWarned = true;
+            this.reminderQueue.push(buildLoopWarningReminder("This task has already used many tool steps. Do not keep exploring by default; synthesize what you know unless a concrete missing gap remains."));
+        }
+        if (isSearchStep && !this.softSearchWarned && this.searchSteps >= this.budget.softSearchSteps) {
+            this.softSearchWarned = true;
+            this.reminderQueue.push(buildLoopWarningReminder("This task has already used many search steps. Stop broad searching unless you can point to a specific remaining evidence gap."));
+        }
+    }
+}
+function inferProgress(intent, result) {
+    if (result.status === "blocked" || result.status === "timeout" || result.status === "command_error") {
+        return false;
+    }
+    if (intent.family === "search") {
+        const matches = result.metadata?.matches;
+        if (typeof matches === "number") {
+            return matches > 0;
+        }
+        const normalized = result.content.toLowerCase();
+        if (normalized.includes("no matches found") || normalized.includes("(no matches)")) {
+            return false;
+        }
+        return !result.isError;
+    }
+    return !result.isError;
+}
+function blockedResult(content, status, reason) {
+    return {
+        content,
+        isError: true,
+        status,
+        metadata: {
+            kind: "security",
+            reason,
+        },
+    };
+}

package/dist/agent/subtask-policy.d.ts

@@ -0,0 +1,14 @@
+import type { ToolRegistryEntry, ToolResultStatus } from "../types.js";
+export type SubtaskType = "search" | "security_investigation" | "evidence_correlation" | "general_readonly";
+export interface SubtaskPolicy {
+    type: SubtaskType;
+    allowedTools: string[];
+    reminder: string;
+    resultStatus: ToolResultStatus;
+    maxTurns?: number;
+    taskBudget?: {
+        total: number;
+    };
+}
+export declare function getSubtaskPolicy(type: SubtaskType | undefined): SubtaskPolicy;
+export declare function filterToolsForSubtask(tools: ToolRegistryEntry[], type: SubtaskType | undefined): ToolRegistryEntry[];

package/dist/agent/subtask-policy.js

@@ -0,0 +1,60 @@
+const POLICY_MAP = {
+    search: {
+        type: "search",
+        allowedTools: ["read", "glob", "grep", "web_search", "web_fetch", "skill", "todo_write"],
+        reminder: [
+            "Subtask policy: search",
+            "- Focus on locating relevant files, symbols, and evidence quickly.",
+            "- Use glob for file discovery and grep for content search.",
+            "- Return a concise summary of what you found and where.",
+        ].join("\n"),
+        resultStatus: "success",
+        maxTurns: 6,
+        taskBudget: { total: 180_000 },
+    },
+    security_investigation: {
+        type: "security_investigation",
+        allowedTools: ["read", "glob", "grep", "web_search", "web_fetch", "skill", "todo_write"],
+        reminder: [
+            "Subtask policy: security_investigation",
+            "- Investigate only in read-only mode.",
+            "- Collect evidence about config load paths, environment reads, persistence paths, masking, and exposure paths.",
+            "- Do not loop on broad keyword search; summarize evidence and uncertainty.",
+        ].join("\n"),
+        resultStatus: "success",
+        maxTurns: 8,
+        taskBudget: { total: 220_000 },
+    },
+    evidence_correlation: {
+        type: "evidence_correlation",
+        allowedTools: ["read", "skill", "todo_write"],
+        reminder: [
+            "Subtask policy: evidence_correlation",
+            "- Correlate evidence already discovered.",
+            "- Avoid new broad searches; read only the specific files that matter.",
+            "- Produce a reasoning-focused summary that states what the evidence supports.",
+        ].join("\n"),
+        resultStatus: "success",
+        maxTurns: 4,
+        taskBudget: { total: 120_000 },
+    },
+    general_readonly: {
+        type: "general_readonly",
+        allowedTools: ["read", "glob", "grep", "web_search", "web_fetch", "skill", "todo_write"],
+        reminder: [
+            "Subtask policy: general_readonly",
+            "- Stay in read-only mode.",
+            "- Keep the scope tightly bounded and summarize findings concisely.",
+        ].join("\n"),
+        resultStatus: "success",
+        maxTurns: 6,
+        taskBudget: { total: 180_000 },
+    },
+};
+export function getSubtaskPolicy(type) {
+    return POLICY_MAP[type ?? "general_readonly"];
+}
+export function filterToolsForSubtask(tools, type) {
+    const policy = getSubtaskPolicy(type);
+    return tools.filter((tool) => policy.allowedTools.includes(tool.name));
+}

package/dist/agent/task-classifier.d.ts

@@ -0,0 +1,3 @@
+import type { ContentPart } from "../types.js";
+export type TaskType = "security_investigation" | "code_search" | "general";
+export declare function classifyTask(input: string | ContentPart[]): TaskType;

package/dist/agent/task-classifier.js

@@ -0,0 +1,36 @@
+const SECURITY_PATTERNS = [
+    /\bapi[\s_-]?key\b/i,
+    /\bsecret(s)?\b/i,
+    /\btoken(s)?\b/i,
+    /\bcredential(s)?\b/i,
+    /\bleak(ed|age)?\b/i,
+    /\bexpos(e|ed|ure)\b/i,
+    /\bstored?\b/i,
+    /\bwhere\b/i,
+    /\bconfig\b/i,
+    /\benv\b/i,
+];
+const SEARCH_PATTERNS = [
+    /\bfind\b/i,
+    /\bsearch\b/i,
+    /\blook for\b/i,
+    /\bwhere\b/i,
+    /\blocate\b/i,
+    /\btrace\b/i,
+];
+export function classifyTask(input) {
+    const text = typeof input === "string"
+        ? input
+        : input
+            .filter((part) => part.type === "text")
+            .map((part) => part.text)
+            .join("\n");
+    const securityHits = SECURITY_PATTERNS.filter((pattern) => pattern.test(text)).length;
+    if (securityHits >= 2) {
+        return "security_investigation";
+    }
+    if (SEARCH_PATTERNS.some((pattern) => pattern.test(text))) {
+        return "code_search";
+    }
+    return "general";
+}

package/dist/agent/tool-arbiter.d.ts

@@ -0,0 +1,7 @@
+import type { ParsedToolCall } from "../types.js";
+export interface ToolArbitration {
+    toolCall: ParsedToolCall;
+    note?: string;
+}
+export declare function arbitrateToolCall(toolCall: ParsedToolCall): ToolArbitration;
+export declare function isSearchLikeToolCall(toolCall: ParsedToolCall): boolean;

package/dist/agent/tool-arbiter.js

@@ -0,0 +1,33 @@
+import { analyzeToolIntent, parseSearchBashCommand } from "./tool-intent.js";
+export function arbitrateToolCall(toolCall) {
+    if (toolCall.name !== "bash") {
+        return { toolCall };
+    }
+    const command = typeof toolCall.parsedArgs.command === "string"
+        ? toolCall.parsedArgs.command
+        : "";
+    const parsedSearch = parseSearchBashCommand(command);
+    if (!parsedSearch) {
+        return { toolCall };
+    }
+    return {
+        toolCall: {
+            ...toolCall,
+            name: "grep",
+            parsedArgs: {
+                pattern: parsedSearch.pattern,
+                ...(parsedSearch.path ? { path: parsedSearch.path } : {}),
+                ...(parsedSearch.include ? { glob: parsedSearch.include } : {}),
+            },
+            arguments: JSON.stringify({
+                pattern: parsedSearch.pattern,
+                ...(parsedSearch.path ? { path: parsedSearch.path } : {}),
+                ...(parsedSearch.include ? { glob: parsedSearch.include } : {}),
+            }),
+        },
+        note: `Rewrote bash search to grep for structured execution: ${command}`,
+    };
+}
+export function isSearchLikeToolCall(toolCall) {
+    return analyzeToolIntent(toolCall).family === "search";
+}

package/dist/agent/tool-intent.d.ts

@@ -0,0 +1,20 @@
+import type { ParsedToolCall } from "../types.js";
+export type ToolFamily = "search" | "read" | "write" | "edit" | "shell" | "web" | "other";
+export interface SearchIntent {
+    pattern: string;
+    path?: string;
+    include?: string;
+    signature: string;
+    familyKey: string;
+}
+export interface ToolIntent {
+    family: ToolFamily;
+    search?: SearchIntent;
+}
+export declare function analyzeToolIntent(toolCall: Pick<ParsedToolCall, "name" | "parsedArgs">): ToolIntent;
+export interface ParsedSearchCommand {
+    pattern: string;
+    path?: string;
+    include?: string;
+}
+export declare function parseSearchBashCommand(command: string): ParsedSearchCommand | undefined;