@bubblebrain-ai/bubble 0.0.6 → 0.0.8

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

@@ -3,21 +3,16 @@ 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 mutationVersion;
     private reminderQueue;
     private warnedFamilies;
+    private warnedSignatures;
     private softTotalWarned;
     private softSearchWarned;
     private softReadWarned;
@@ -29,16 +24,13 @@ export declare class ExecutionGovernor {
         readSteps: number;
         searchFrozen: boolean;
         explorationFrozen: boolean;
-        phase: WorkPhase;
+        phase: "observe";
     };
     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 hasCurrentMutationObservation;
+    private warnOnce;
     private maybeWarnOnSoftBudgets;
 }
-export {};

package/dist/agent/execution-governor.js

@@ -1,118 +1,84 @@
 import { analyzeToolIntent } from "./tool-intent.js";
-import { buildExplorationFreezeReminder, buildInvestigationReminder, buildLoopWarningReminder, buildSearchFreezeReminder } from "../prompt/reminders.js";
+import { buildInvestigationReminder, buildLoopWarningReminder } from "../prompt/reminders.js";
 const BUDGETS = {
     security_investigation: {
         softTotalSteps: 14,
         softSearchSteps: 6,
         softReadSteps: 8,
-        maxExplorationStepsWithoutWrite: 12,
-        maxNoProgressReadExactRepeats: 2,
-        maxNoProgressExactRepeats: 2,
-        maxNoProgressFamilyRepeats: 3,
+        warningExactRepeats: 2,
         warningFamilyRepeats: 2,
     },
     code_search: {
         softTotalSteps: 16,
         softSearchSteps: 8,
         softReadSteps: 10,
-        maxExplorationStepsWithoutWrite: 14,
-        maxNoProgressReadExactRepeats: 2,
-        maxNoProgressExactRepeats: 3,
-        maxNoProgressFamilyRepeats: 4,
+        warningExactRepeats: 2,
         warningFamilyRepeats: 3,
     },
     debugging: {
         softTotalSteps: 18,
         softSearchSteps: 8,
         softReadSteps: 7,
-        maxExplorationStepsWithoutWrite: 10,
-        maxNoProgressReadExactRepeats: 1,
-        maxNoProgressExactRepeats: 3,
-        maxNoProgressFamilyRepeats: 4,
+        warningExactRepeats: 1,
         warningFamilyRepeats: 3,
     },
     implementation: {
         softTotalSteps: 18,
         softSearchSteps: 8,
         softReadSteps: 6,
-        maxExplorationStepsWithoutWrite: 8,
-        maxNoProgressReadExactRepeats: 1,
-        maxNoProgressExactRepeats: 3,
-        maxNoProgressFamilyRepeats: 4,
+        warningExactRepeats: 1,
         warningFamilyRepeats: 3,
     },
     code_review: {
         softTotalSteps: 14,
         softSearchSteps: 6,
         softReadSteps: 8,
-        maxExplorationStepsWithoutWrite: 12,
-        maxNoProgressReadExactRepeats: 2,
-        maxNoProgressExactRepeats: 3,
-        maxNoProgressFamilyRepeats: 4,
+        warningExactRepeats: 2,
         warningFamilyRepeats: 3,
     },
     code_explanation: {
         softTotalSteps: 12,
         softSearchSteps: 6,
         softReadSteps: 8,
-        maxExplorationStepsWithoutWrite: 12,
-        maxNoProgressReadExactRepeats: 2,
-        maxNoProgressExactRepeats: 3,
-        maxNoProgressFamilyRepeats: 4,
+        warningExactRepeats: 2,
         warningFamilyRepeats: 3,
     },
     repo_orientation: {
         softTotalSteps: 12,
         softSearchSteps: 6,
         softReadSteps: 8,
-        maxExplorationStepsWithoutWrite: 12,
-        maxNoProgressReadExactRepeats: 2,
-        maxNoProgressExactRepeats: 3,
-        maxNoProgressFamilyRepeats: 4,
+        warningExactRepeats: 2,
         warningFamilyRepeats: 3,
     },
     product_discussion: {
         softTotalSteps: 10,
         softSearchSteps: 4,
         softReadSteps: 4,
-        maxExplorationStepsWithoutWrite: 8,
-        maxNoProgressReadExactRepeats: 2,
-        maxNoProgressExactRepeats: 2,
-        maxNoProgressFamilyRepeats: 3,
+        warningExactRepeats: 2,
         warningFamilyRepeats: 2,
     },
     general: {
         softTotalSteps: 18,
         softSearchSteps: 8,
         softReadSteps: 10,
-        maxExplorationStepsWithoutWrite: 14,
-        maxNoProgressReadExactRepeats: 2,
-        maxNoProgressExactRepeats: 3,
-        maxNoProgressFamilyRepeats: 4,
+        warningExactRepeats: 2,
         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;
+    mutationVersion = 0;
     reminderQueue = [];
     warnedFamilies = new Set();
+    warnedSignatures = new Set();
     softTotalWarned = false;
     softSearchWarned = false;
     softReadWarned = false;
     constructor(taskType) {
-        this.taskType = taskType;
         this.budget = BUDGETS[taskType];
         if (taskType === "security_investigation") {
             this.reminderQueue.push(buildInvestigationReminder());
@@ -128,62 +94,33 @@ export class ExecutionGovernor {
             totalSteps: this.totalSteps,
             searchSteps: this.searchSteps,
             readSteps: this.readSteps,
-            searchFrozen: this.searchFrozen,
-            explorationFrozen: this.explorationFrozen,
-            phase: this.phase,
+            searchFrozen: false,
+            explorationFrozen: false,
+            phase: "observe",
         };
     }
     filterToolDefinitions(toolDefinitions) {
-        let filtered = toolDefinitions;
-        if (this.explorationFrozen) {
-            filtered = filtered.filter((tool) => !EXPLORATION_TOOLS_DISABLED.has(tool.name));
-        }
-        else if (this.searchFrozen) {
-            filtered = filtered.filter((tool) => !SEARCH_TOOLS_DISABLED.has(tool.name));
-        }
-        return filtered;
+        return toolDefinitions;
     }
     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") {
+        if (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 (signature && this.hasCurrentMutationObservation((entry) => entry.signature === signature)) {
+                this.warnOnce(`read:${signature}`, "This exact file range was already read since the last successful edit/write. If the content is still available and nothing changed, use the prior result; otherwise it is okay to re-read to recover context or verify a change.");
             }
         }
         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.", "search"),
-                };
-            }
             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.", "search"),
-                };
+            if (signature && this.trailingNoProgressCount((entry) => entry.signature === signature) >= this.budget.warningExactRepeats) {
+                this.warnOnce(`search:${signature}`, "This search is very similar to one you already ran and it did not produce new evidence. Change the query/path, follow a concrete lead, or summarize the strongest findings.");
             }
             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.", "search"),
-                    };
-                }
                 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.reminderQueue.push(buildLoopWarningReminder("Repeated searches in the same family are yielding little new evidence. Change your hypothesis, narrow the path, follow a specific file lead, or summarize current findings instead of repeating variants."));
                 }
             }
         }
@@ -194,9 +131,6 @@ export class ExecutionGovernor {
         if (intent.family === "read") {
             this.readSteps += 1;
         }
-        if (isExplorationIntent(intent) && !this.codeChanged) {
-            this.explorationStepsWithoutWrite += 1;
-        }
         this.maybeWarnOnSoftBudgets(intent.family === "search", intent.family === "read");
         return {};
     }
@@ -211,23 +145,19 @@ export class ExecutionGovernor {
             signature: intent.search?.signature ?? intent.read?.signature,
             familyKey: intent.search?.familyKey ?? intent.read?.familyKey,
             progress,
+            mutationVersion: this.mutationVersion,
         });
         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.`);
+            this.mutationVersion += 1;
         }
     }
     trailingNoProgressCount(predicate) {
         let count = 0;
         for (let index = this.history.length - 1; index >= 0; index--) {
             const entry = this.history[index];
+            if (entry.mutationVersion !== this.mutationVersion) {
+                break;
+            }
             if (!predicate(entry)) {
                 break;
             }
@@ -238,27 +168,15 @@ export class ExecutionGovernor {
         }
         return count;
     }
-    freezeSearch(reason) {
-        if (this.searchFrozen) {
-            return;
-        }
-        this.searchFrozen = true;
-        this.reminderQueue.push(buildSearchFreezeReminder(reason));
+    hasCurrentMutationObservation(predicate) {
+        return this.history.some((entry) => entry.mutationVersion === this.mutationVersion && predicate(entry));
     }
-    enterModifyPhase(reason) {
-        if (this.explorationFrozen) {
+    warnOnce(key, reason) {
+        if (this.warnedSignatures.has(key)) {
             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);
+        this.warnedSignatures.add(key);
+        this.reminderQueue.push(buildLoopWarningReminder(reason));
     }
     maybeWarnOnSoftBudgets(isSearchStep, isReadStep) {
         if (!this.softTotalWarned && this.totalSteps >= this.budget.softTotalSteps) {
@@ -275,28 +193,12 @@ export class ExecutionGovernor {
         }
     }
 }
-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) {
     if (result.status === "blocked" || result.status === "timeout" || result.status === "command_error") {
         return false;
@@ -314,14 +216,3 @@ function inferProgress(intent, result) {
     }
     return !result.isError;
 }
-function blockedResult(content, status, reason, kind = "security") {
-    return {
-        content,
-        isError: true,
-        status,
-        metadata: {
-            kind,
-            reason,
-        },
-    };
-}

package/dist/agent.d.ts

@@ -2,12 +2,14 @@
  * Agent - The core decision loop.
  * It maintains message state, calls the LLM, executes tools, and auto-continues.
  */
+import { type ContextUsageSnapshot } from "./context/usage.js";
 import type { AgentEvent, ContentPart, PermissionMode, Message, Provider, ThinkingLevel, Todo, ToolResult, ToolRegistryEntry, ToolUpdate } from "./types.js";
 import { type TurnHooks } from "./orchestrator/hooks.js";
 import { BudgetLedger } from "./agent/budget-ledger.js";
 import { type AgentProfile, type SubagentRunResult } from "./agent/profiles.js";
 import { type SubagentThreadSnapshot } from "./agent/subagent-control.js";
 import type { SkillSummary } from "./skills/types.js";
+import type { FileStateTracker } from "./tools/file-state.js";
 export declare class AgentAbortError extends Error {
     constructor(message?: string);
 }
@@ -39,6 +41,7 @@ export interface AgentOptions {
     };
     skills?: SkillSummary[];
     memoryPrompt?: string;
+    fileStateTracker?: FileStateTracker;
 }
 export declare class Agent {
     messages: Message[];
@@ -65,6 +68,7 @@ export declare class Agent {
     private budgetSource;
     private skillSummaries;
     private memoryPrompt?;
+    private fileStateTracker?;
     private subagentThreads;
     private pendingSubagentUpdates;
     private lastInputTokens;
@@ -74,8 +78,10 @@ export declare class Agent {
     unlockDeferredTools(names: string[]): void;
     /** All deferred tools in this session (for tool_search to inspect). */
     listDeferredTools(): ToolRegistryEntry[];
+    getContextUsageSnapshot(): ContextUsageSnapshot;
     /** Whether a given tool is deferred and not yet unlocked. */
     isDeferredAndLocked(name: string): boolean;
+    private getActiveToolEntries;
     injectSystemReminder(content: string): void;
     injectModeReminder(): void;
     get model(): string;

package/dist/agent.js

@@ -6,6 +6,7 @@ import { compactMessages } from "./context/compact.js";
 import { randomUUID } from "node:crypto";
 import { compactMessagesWithLLM } from "./context/compact-llm.js";
 import { getContextBudget } from "./context/budget.js";
+import { buildContextUsageSnapshot } from "./context/usage.js";
 import { isContextOverflowError } from "./context/overflow.js";
 import { projectMessages } from "./context/projector.js";
 import { aggressivePruneMessages } from "./context/prune.js";
@@ -18,6 +19,7 @@ import { assignAgentNickname, builtinAgentProfiles, mergeUsage, selectToolsForAg
 import { snapshotSubagentThread, subagentResultFromThread } from "./agent/subagent-control.js";
 import { buildSystemPrompt } from "./system-prompt.js";
 import { isOnlyProviderProtocolArtifacts, stripProviderProtocolArtifacts } from "./provider-artifacts.js";
+import { debugReasoningStream, summarizeDebugText } from "./reasoning-debug.js";
 const MAX_CONSECUTIVE_OVERFLOW_RECOVERIES = 3;
 const RESIDENT_HISTORY_KEEP_RECENT_TURNS = 3;
 const RESIDENT_HISTORY_MESSAGE_LIMIT = 160;
@@ -56,6 +58,7 @@ export class Agent {
     budgetSource;
     skillSummaries;
     memoryPrompt;
+    fileStateTracker;
     subagentThreads = new Map();
     pendingSubagentUpdates = [];
     lastInputTokens = null;
@@ -80,6 +83,7 @@ export class Agent {
         this.budgetSource = options.budgetSource ?? { runId: this.sessionID ?? "agent" };
         this.skillSummaries = options.skills ?? [];
         this.memoryPrompt = options.memoryPrompt;
+        this.fileStateTracker = options.fileStateTracker;
         if (options.systemPrompt) {
             this.messages.push({ role: "system", content: options.systemPrompt });
         }
@@ -111,11 +115,26 @@ export class Agent {
     listDeferredTools() {
         return [...this.tools.values()].filter((t) => t.deferred);
     }
+    getContextUsageSnapshot() {
+        return buildContextUsageSnapshot({
+            providerId: this.providerId,
+            modelId: this.apiModel,
+            messages: this.messages,
+            toolEntries: this.getActiveToolEntries(),
+            deferredToolEntries: this.listDeferredTools(),
+            skills: this.skillSummaries,
+        });
+    }
     /** Whether a given tool is deferred and not yet unlocked. */
     isDeferredAndLocked(name) {
         const tool = this.tools.get(name);
         return !!tool?.deferred && !this.unlockedDeferred.has(name);
     }
+    getActiveToolEntries() {
+        return [...this.tools.values()]
+            .filter((tool) => !tool.deferred || this.unlockedDeferred.has(tool.name))
+            .filter((tool) => this._mode === "plan" || tool.name !== "exit_plan_mode");
+    }
     injectSystemReminder(content) {
         this.appendMessage({ role: "meta", kind: "system-reminder", content });
     }
@@ -320,6 +339,15 @@ export class Agent {
                             yield { type: "text_delta", content: chunk.content };
                             break;
                         case "reasoning_delta":
+                            debugReasoningStream({
+                                stage: "agent_receive",
+                                providerId: this._providerId,
+                                modelId: this.apiModel,
+                                turnStep: step,
+                                beforeLength: assistantMsg.reasoning?.length ?? 0,
+                                delta: summarizeDebugText(chunk.content),
+                                afterLength: (assistantMsg.reasoning?.length ?? 0) + chunk.content.length,
+                            });
                             assistantMsg.reasoning = (assistantMsg.reasoning || "") + chunk.content;
                             yield { type: "reasoning_delta", content: chunk.content };
                             break;
@@ -533,7 +561,7 @@ export class Agent {
                     },
                 });
                 flushGovernorReminders();
-                yield { type: "turn_end", usage: turnUsage };
+                yield { type: "turn_end", usage: turnUsage, willContinue: true };
                 // Auto-continue: if we have tool results, the LLM needs to respond to them.
                 // Emitting the turn boundary keeps UI renderers aligned with the persisted
                 // assistant/tool message sequence instead of merging the next answer into
@@ -549,8 +577,9 @@ export class Agent {
                 flushReminders: flushGovernorReminders,
             });
             flushGovernorReminders();
-            yield { type: "turn_end", usage: turnUsage };
-            if (hookState.forceContinuationReason) {
+            const willContinue = !!hookState.forceContinuationReason;
+            yield { type: "turn_end", usage: turnUsage, willContinue };
+            if (willContinue) {
                 delete hookState.forceContinuationReason;
                 continue;
             }
@@ -569,6 +598,7 @@ export class Agent {
             if (afterTokens < beforeTokens) {
                 this.lastInputTokens = null;
                 this.lastAnchorMessageCount = null;
+                this.fileStateTracker?.invalidateReadHistory();
                 return before - this.messages.length;
             }
         }
@@ -583,6 +613,7 @@ export class Agent {
             this.messages = llmResult.messages;
             this.lastInputTokens = null;
             this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
             return before - this.messages.length;
         }
         const fallback = compactMessages(this.messages, { keepRecentTurns });
@@ -590,6 +621,7 @@ export class Agent {
             this.messages = fallback.messages;
             this.lastInputTokens = null;
             this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
             return before - this.messages.length;
         }
         return 0;
@@ -1056,6 +1088,7 @@ export class Agent {
             this.messages = candidate;
             this.lastInputTokens = null;
             this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
         }
     }
     appendMessage(message) {

package/dist/context/budget.d.ts

@@ -19,3 +19,4 @@ export interface ContextBudgetOptions {
 export declare function estimateMessageTokens(message: Message): number;
 export declare function estimateContextTokens(messages: Message[]): number;
 export declare function getContextBudget(providerId: string, modelId: string, messages: Message[], options?: ContextBudgetOptions): ContextBudget;
+export declare function estimateTextTokens(text: string): number;

package/dist/context/budget.js

@@ -65,7 +65,7 @@ function shouldTriggerCompact(estimatedTokens, contextWindow) {
         : contextWindow * 0.75;
     return estimatedTokens >= threshold;
 }
-function estimateTextTokens(text) {
+export function estimateTextTokens(text) {
     if (!text) {
         return 0;
     }

package/dist/context/usage.d.ts

@@ -0,0 +1,34 @@
+import type { SkillSummary } from "../skills/types.js";
+import type { Message, ToolRegistryEntry } from "../types.js";
+export interface ContextUsageBucket {
+    label: string;
+    tokens: number;
+    detail?: string;
+}
+export interface ContextUsageSnapshot {
+    providerId: string;
+    modelId: string;
+    contextWindow?: number;
+    usedTokens: number;
+    freeTokens?: number;
+    buckets: {
+        systemPrompt: ContextUsageBucket;
+        tools: ContextUsageBucket;
+        skills: ContextUsageBucket;
+        deferredTools: ContextUsageBucket;
+        other: ContextUsageBucket;
+    };
+    toolCount: number;
+    deferredToolCount: number;
+    skillCount: number;
+    messageCount: number;
+}
+export declare function buildContextUsageSnapshot(input: {
+    providerId: string;
+    modelId: string;
+    messages: Message[];
+    toolEntries: ToolRegistryEntry[];
+    deferredToolEntries?: ToolRegistryEntry[];
+    skills: SkillSummary[];
+}): ContextUsageSnapshot;
+export declare function formatContextUsage(snapshot: ContextUsageSnapshot): string;