@bubblebrain-ai/bubble 0.0.3 → 0.0.5

package/README.md

@@ -4,8 +4,8 @@ Bubble is a terminal coding agent for working inside local project folders. It c
 
 ## Requirements
 
-- Bun
-- Node.js and npm
+- Node.js 20+ and npm for installation
+- Bun for running Bubble
 
 Install Bun if it is not already available:
 
@@ -24,9 +24,14 @@ npm install -g @bubblebrain-ai/bubble
 From a local package tarball:
 
 ```bash
-npm install -g ./bubblebrain-ai-bubble-0.0.1.tgz
+npm install -g ./bubblebrain-ai-bubble-0.0.3.tgz
 ```
 
+The npm command installs a small Node.js launcher named `bubble`. When you run
+`bubble`, the launcher checks for Bun and starts the real Bubble runtime with
+`bun`. If Bun is missing, it prints the install command above instead of failing
+with a low-level runtime error.
+
 ## Usage
 
 Start Bubble in the current directory:

package/dist/agent/budget-ledger.d.ts

@@ -0,0 +1,20 @@
+import type { TokenUsage } from "../types.js";
+export interface BudgetUsageSource {
+    runId: string;
+    subAgentId?: string;
+}
+export interface BudgetSnapshot {
+    spent: number;
+    limit?: number;
+    exhausted: boolean;
+}
+export declare class BudgetLedger {
+    private readonly limit?;
+    private spent;
+    private readonly controller;
+    constructor(limit?: number | undefined);
+    get signal(): AbortSignal;
+    recordUsage(usage: TokenUsage, source: BudgetUsageSource): void;
+    snapshot(): BudgetSnapshot;
+}
+export declare function composeAbortSignals(signals: Array<AbortSignal | undefined>): AbortSignal | undefined;

package/dist/agent/budget-ledger.js

@@ -0,0 +1,51 @@
+export class BudgetLedger {
+    limit;
+    spent = 0;
+    controller = new AbortController();
+    constructor(limit) {
+        this.limit = limit;
+    }
+    get signal() {
+        return this.controller.signal;
+    }
+    recordUsage(usage, source) {
+        const delta = usage.promptTokens + usage.completionTokens;
+        this.spent += delta;
+        if (this.limit !== undefined && this.spent >= this.limit && !this.controller.signal.aborted) {
+            this.controller.abort(budgetAbortError("Budget exhausted"));
+        }
+    }
+    snapshot() {
+        return {
+            spent: this.spent,
+            limit: this.limit,
+            exhausted: this.limit !== undefined && this.spent >= this.limit,
+        };
+    }
+}
+function budgetAbortError(message) {
+    const error = new Error(message);
+    error.name = "AbortError";
+    return error;
+}
+export function composeAbortSignals(signals) {
+    const active = signals.filter((signal) => !!signal);
+    if (active.length === 0)
+        return undefined;
+    if (active.length === 1)
+        return active[0];
+    const controller = new AbortController();
+    const abort = (signal) => {
+        if (controller.signal.aborted)
+            return;
+        controller.abort(signal.reason);
+    };
+    for (const signal of active) {
+        if (signal.aborted) {
+            abort(signal);
+            break;
+        }
+        signal.addEventListener("abort", () => abort(signal), { once: true });
+    }
+    return controller.signal;
+}

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

@@ -3,28 +3,42 @@ import type { TaskType } from "./task-classifier.js";
 export interface GovernorDecision {
     blockedResult?: ToolResult;
 }
+type WorkPhase = "explore" | "modify" | "verify";
 export declare class ExecutionGovernor {
     private taskType;
     private budget;
     private history;
     private totalSteps;
     private searchSteps;
+    private readSteps;
+    private explorationStepsWithoutWrite;
     private searchFrozen;
+    private explorationFrozen;
+    private phase;
+    private codeChanged;
     private reminderQueue;
     private warnedFamilies;
     private softTotalWarned;
     private softSearchWarned;
+    private softReadWarned;
     constructor(taskType: TaskType);
     consumePendingReminders(): string[];
     snapshot(): {
         totalSteps: number;
         searchSteps: number;
+        readSteps: number;
         searchFrozen: boolean;
+        explorationFrozen: boolean;
+        phase: WorkPhase;
     };
     filterToolDefinitions(toolDefinitions: ToolRegistryEntry[]): ToolRegistryEntry[];
     beforeToolCall(toolCall: ParsedToolCall): GovernorDecision;
     afterToolResult(toolCall: ParsedToolCall, result: ToolResult): void;
     private trailingNoProgressCount;
     private freezeSearch;
+    private enterModifyPhase;
+    private isModificationTask;
+    private historyCount;
     private maybeWarnOnSoftBudgets;
 }
+export {};

package/dist/agent/execution-governor.js

@@ -1,9 +1,12 @@
 import { analyzeToolIntent } from "./tool-intent.js";
-import { buildInvestigationReminder, buildLoopWarningReminder, buildSearchFreezeReminder } from "../prompt/reminders.js";
+import { buildExplorationFreezeReminder, buildInvestigationReminder, buildLoopWarningReminder, buildSearchFreezeReminder } from "../prompt/reminders.js";
 const BUDGETS = {
     security_investigation: {
         softTotalSteps: 14,
         softSearchSteps: 6,
+        softReadSteps: 8,
+        maxExplorationStepsWithoutWrite: 12,
+        maxNoProgressReadExactRepeats: 2,
         maxNoProgressExactRepeats: 2,
         maxNoProgressFamilyRepeats: 3,
         warningFamilyRepeats: 2,
@@ -11,30 +14,103 @@ const BUDGETS = {
     code_search: {
         softTotalSteps: 16,
         softSearchSteps: 8,
+        softReadSteps: 10,
+        maxExplorationStepsWithoutWrite: 14,
+        maxNoProgressReadExactRepeats: 2,
         maxNoProgressExactRepeats: 3,
         maxNoProgressFamilyRepeats: 4,
         warningFamilyRepeats: 3,
     },
+    debugging: {
+        softTotalSteps: 18,
+        softSearchSteps: 8,
+        softReadSteps: 7,
+        maxExplorationStepsWithoutWrite: 10,
+        maxNoProgressReadExactRepeats: 1,
+        maxNoProgressExactRepeats: 3,
+        maxNoProgressFamilyRepeats: 4,
+        warningFamilyRepeats: 3,
+    },
+    implementation: {
+        softTotalSteps: 18,
+        softSearchSteps: 8,
+        softReadSteps: 6,
+        maxExplorationStepsWithoutWrite: 8,
+        maxNoProgressReadExactRepeats: 1,
+        maxNoProgressExactRepeats: 3,
+        maxNoProgressFamilyRepeats: 4,
+        warningFamilyRepeats: 3,
+    },
+    code_review: {
+        softTotalSteps: 14,
+        softSearchSteps: 6,
+        softReadSteps: 8,
+        maxExplorationStepsWithoutWrite: 12,
+        maxNoProgressReadExactRepeats: 2,
+        maxNoProgressExactRepeats: 3,
+        maxNoProgressFamilyRepeats: 4,
+        warningFamilyRepeats: 3,
+    },
+    code_explanation: {
+        softTotalSteps: 12,
+        softSearchSteps: 6,
+        softReadSteps: 8,
+        maxExplorationStepsWithoutWrite: 12,
+        maxNoProgressReadExactRepeats: 2,
+        maxNoProgressExactRepeats: 3,
+        maxNoProgressFamilyRepeats: 4,
+        warningFamilyRepeats: 3,
+    },
+    repo_orientation: {
+        softTotalSteps: 12,
+        softSearchSteps: 6,
+        softReadSteps: 8,
+        maxExplorationStepsWithoutWrite: 12,
+        maxNoProgressReadExactRepeats: 2,
+        maxNoProgressExactRepeats: 3,
+        maxNoProgressFamilyRepeats: 4,
+        warningFamilyRepeats: 3,
+    },
+    product_discussion: {
+        softTotalSteps: 10,
+        softSearchSteps: 4,
+        softReadSteps: 4,
+        maxExplorationStepsWithoutWrite: 8,
+        maxNoProgressReadExactRepeats: 2,
+        maxNoProgressExactRepeats: 2,
+        maxNoProgressFamilyRepeats: 3,
+        warningFamilyRepeats: 2,
+    },
     general: {
         softTotalSteps: 18,
         softSearchSteps: 8,
+        softReadSteps: 10,
+        maxExplorationStepsWithoutWrite: 14,
+        maxNoProgressReadExactRepeats: 2,
         maxNoProgressExactRepeats: 3,
         maxNoProgressFamilyRepeats: 4,
         warningFamilyRepeats: 3,
     },
 };
 const SEARCH_TOOLS_DISABLED = new Set(["grep", "web_search", "web_fetch"]);
+const EXPLORATION_TOOLS_DISABLED = new Set(["read", "glob", "grep", "web_search", "web_fetch", "spawn_agent", "wait_agent", "send_input", "tool_search"]);
 export class ExecutionGovernor {
     taskType;
     budget;
     history = [];
     totalSteps = 0;
     searchSteps = 0;
+    readSteps = 0;
+    explorationStepsWithoutWrite = 0;
     searchFrozen = false;
+    explorationFrozen = false;
+    phase = "explore";
+    codeChanged = false;
     reminderQueue = [];
     warnedFamilies = new Set();
     softTotalWarned = false;
     softSearchWarned = false;
+    softReadWarned = false;
     constructor(taskType) {
         this.taskType = taskType;
         this.budget = BUDGETS[taskType];
@@ -51,21 +127,42 @@ export class ExecutionGovernor {
         return {
             totalSteps: this.totalSteps,
             searchSteps: this.searchSteps,
+            readSteps: this.readSteps,
             searchFrozen: this.searchFrozen,
+            explorationFrozen: this.explorationFrozen,
+            phase: this.phase,
         };
     }
     filterToolDefinitions(toolDefinitions) {
-        if (!this.searchFrozen) {
-            return toolDefinitions;
+        let filtered = toolDefinitions;
+        if (this.explorationFrozen) {
+            filtered = filtered.filter((tool) => !EXPLORATION_TOOLS_DISABLED.has(tool.name));
         }
-        return toolDefinitions.filter((tool) => !SEARCH_TOOLS_DISABLED.has(tool.name));
+        else if (this.searchFrozen) {
+            filtered = filtered.filter((tool) => !SEARCH_TOOLS_DISABLED.has(tool.name));
+        }
+        return filtered;
     }
     beforeToolCall(toolCall) {
         const intent = analyzeToolIntent(toolCall);
+        if (this.explorationFrozen && isExplorationIntent(intent)) {
+            return {
+                blockedResult: blockedResult("Exploration blocked: this implementation task already has enough context. Use edit/write, verify an existing change, or explain the blocker.", "blocked", "Exploration frozen because tool calls stopped producing task progress.", metadataKindForFamily(intent.family)),
+            };
+        }
+        if (this.isModificationTask() && !this.codeChanged && intent.family === "read") {
+            const signature = intent.read?.signature;
+            if (signature && this.historyCount((entry) => entry.signature === signature) >= this.budget.maxNoProgressReadExactRepeats) {
+                this.enterModifyPhase(`Repeated the same file range without making progress: ${signature}`);
+                return {
+                    blockedResult: blockedResult("Read blocked: this file range was already read. You have enough context to make the requested change; use edit/write now or explain the blocker.", "blocked", "Repeated identical read before modification.", "read"),
+                };
+            }
+        }
         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."),
+                    blockedResult: blockedResult("Search blocked: repeated low-yield searching is now frozen for this task.", "blocked", "Search frozen due to repeated low-yield searching.", "search"),
                 };
             }
             const signature = intent.search?.signature;
@@ -73,7 +170,7 @@ export class ExecutionGovernor {
             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."),
+                    blockedResult: blockedResult("Search blocked: repeated the same search multiple times without new evidence.", "blocked", "Repeated identical search without progress.", "search"),
                 };
             }
             if (familyKey) {
@@ -81,7 +178,7 @@ export class ExecutionGovernor {
                 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."),
+                        blockedResult: blockedResult("Search blocked: repeated the same search family without new evidence.", "blocked", "Repeated similar searches without progress.", "search"),
                     };
                 }
                 if (familyNoProgress >= this.budget.warningFamilyRepeats && !this.warnedFamilies.has(familyKey)) {
@@ -94,18 +191,38 @@ export class ExecutionGovernor {
         if (intent.family === "search") {
             this.searchSteps += 1;
         }
-        this.maybeWarnOnSoftBudgets(intent.family === "search");
+        if (intent.family === "read") {
+            this.readSteps += 1;
+        }
+        if (isExplorationIntent(intent) && !this.codeChanged) {
+            this.explorationStepsWithoutWrite += 1;
+        }
+        this.maybeWarnOnSoftBudgets(intent.family === "search", intent.family === "read");
         return {};
     }
     afterToolResult(toolCall, result) {
         const intent = analyzeToolIntent(toolCall);
-        const progress = inferProgress(intent, result);
+        const repeatedRead = intent.family === "read"
+            && !!intent.read?.signature
+            && this.history.some((entry) => entry.signature === intent.read?.signature);
+        const progress = inferProgress(intent, result) && !repeatedRead;
         this.history.push({
             family: intent.family,
-            signature: intent.search?.signature,
-            familyKey: intent.search?.familyKey,
+            signature: intent.search?.signature ?? intent.read?.signature,
+            familyKey: intent.search?.familyKey ?? intent.read?.familyKey,
             progress,
         });
+        if (isSuccessfulWriteIntent(intent, result)) {
+            this.codeChanged = true;
+            this.phase = "verify";
+            return;
+        }
+        if (this.isModificationTask()
+            && !this.codeChanged
+            && isExplorationIntent(intent)
+            && this.explorationStepsWithoutWrite >= this.budget.maxExplorationStepsWithoutWrite) {
+            this.enterModifyPhase(`Used ${this.explorationStepsWithoutWrite} exploration tools without editing files.`);
+        }
     }
     trailingNoProgressCount(predicate) {
         let count = 0;
@@ -128,7 +245,22 @@ export class ExecutionGovernor {
         this.searchFrozen = true;
         this.reminderQueue.push(buildSearchFreezeReminder(reason));
     }
-    maybeWarnOnSoftBudgets(isSearchStep) {
+    enterModifyPhase(reason) {
+        if (this.explorationFrozen) {
+            return;
+        }
+        this.phase = "modify";
+        this.explorationFrozen = true;
+        this.searchFrozen = true;
+        this.reminderQueue.push(buildExplorationFreezeReminder(reason));
+    }
+    isModificationTask() {
+        return this.taskType === "implementation" || this.taskType === "debugging";
+    }
+    historyCount(predicate) {
+        return this.history.reduce((count, entry) => count + (predicate(entry) ? 1 : 0), 0);
+    }
+    maybeWarnOnSoftBudgets(isSearchStep, isReadStep) {
         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."));
@@ -137,6 +269,32 @@ export class ExecutionGovernor {
             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."));
         }
+        if (isReadStep && !this.softReadWarned && this.readSteps >= this.budget.softReadSteps) {
+            this.softReadWarned = true;
+            this.reminderQueue.push(buildLoopWarningReminder("This task has already used many file reads. Stop re-reading context unless a concrete edit requires one exact missing snippet."));
+        }
+    }
+}
+function isExplorationIntent(intent) {
+    return intent.family === "search" || intent.family === "read" || intent.family === "web";
+}
+function isSuccessfulWriteIntent(intent, result) {
+    if (result.isError || result.status === "blocked" || result.status === "command_error") {
+        return false;
+    }
+    return intent.family === "write" || intent.family === "edit" || result.metadata?.kind === "write" || result.metadata?.kind === "edit";
+}
+function metadataKindForFamily(family) {
+    switch (family) {
+        case "search":
+        case "read":
+        case "write":
+        case "edit":
+        case "shell":
+        case "web":
+            return family;
+        default:
+            return "security";
     }
 }
 function inferProgress(intent, result) {
@@ -156,13 +314,13 @@ function inferProgress(intent, result) {
     }
     return !result.isError;
 }
-function blockedResult(content, status, reason) {
+function blockedResult(content, status, reason, kind = "security") {
     return {
         content,
         isError: true,
         status,
         metadata: {
-            kind: "security",
+            kind,
             reason,
         },
     };

package/dist/agent/profiles.d.ts

@@ -0,0 +1,59 @@
+import type { ToolRegistryEntry, TokenUsage } from "../types.js";
+import { type SubtaskType } from "./subtask-policy.js";
+export type AgentProfileSource = "user" | "project" | "builtin";
+export type AgentProfileMode = "readonly" | "write_patch" | "write_worktree";
+export type AgentProfileApproval = "fail" | "disabled";
+export type AgentProfileToolPreset = "readonly" | "none" | "explicit";
+export interface AgentProfileTools {
+    preset: AgentProfileToolPreset;
+    include?: string[];
+    exclude?: string[];
+}
+export interface AgentProfile {
+    name: string;
+    description: string;
+    source: AgentProfileSource;
+    filePath?: string;
+    mode: AgentProfileMode;
+    model?: string | "inherit";
+    tools: AgentProfileTools;
+    maxTurns?: number;
+    approval: AgentProfileApproval;
+    nicknameCandidates?: string[];
+    prompt: string;
+    subtaskType?: SubtaskType;
+}
+export interface SubagentRunResult {
+    subAgentId: string;
+    agentName: string;
+    nickname?: string;
+    status: "completed" | "failed" | "blocked" | "cancelled";
+    profileSource: AgentProfileSource;
+    task: string;
+    summary: string;
+    toolNotes: string[];
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+    error?: string;
+}
+export interface DiscoverAgentProfilesResult {
+    profiles: AgentProfile[];
+    projectAgentsDir: string | null;
+    diagnostics: string[];
+}
+export interface AgentProfileDiagnostic {
+    severity: "warning" | "error";
+    message: string;
+    toolName?: string;
+}
+export type AgentProfileScope = "user" | "project" | "both";
+export declare function discoverAgentProfiles(cwd: string, scope?: AgentProfileScope): DiscoverAgentProfilesResult;
+export declare function builtinAgentProfiles(): AgentProfile[];
+export declare function findAgentProfile(profiles: AgentProfile[], name: string): AgentProfile | undefined;
+export declare function assignAgentNickname(profile: AgentProfile, activeNicknames?: Iterable<string>): string;
+export declare function selectToolsForAgentProfile(tools: ToolRegistryEntry[], profile: AgentProfile, approval?: AgentProfileApproval): ToolRegistryEntry[];
+export declare function validateAgentProfileTools(tools: ToolRegistryEntry[], profile: AgentProfile, approval?: AgentProfileApproval): AgentProfileDiagnostic[];
+export declare function mergeUsage(current: SubagentRunResult["usage"], usage: TokenUsage): SubagentRunResult["usage"];