@bubblebrain-ai/bubble 0.0.7 → 0.0.9

package/dist/agent.js

@@ -6,18 +6,22 @@ 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";
+import { truncateToolOutputForModel } from "./context/tool-output-truncate.js";
 import { buildDeferredToolsReminder, buildToolFreezeReminder, isPermissionModeReminder, reminderForMode } from "./prompt/reminders.js";
 import { HookBus } from "./orchestrator/hooks.js";
 import { createDefaultHooks } from "./orchestrator/default-hooks.js";
+import { resolveModelRoute, resolveSubagentRoute } from "./agent/categories.js";
 import { getSubtaskPolicy } from "./agent/subtask-policy.js";
 import { composeAbortSignals } from "./agent/budget-ledger.js";
 import { assignAgentNickname, builtinAgentProfiles, mergeUsage, selectToolsForAgentProfile, validateAgentProfileTools } from "./agent/profiles.js";
 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 +60,9 @@ export class Agent {
     budgetSource;
     skillSummaries;
     memoryPrompt;
+    fileStateTracker;
+    agentCategories;
+    providerFactory;
     subagentThreads = new Map();
     pendingSubagentUpdates = [];
     lastInputTokens = null;
@@ -80,6 +87,9 @@ export class Agent {
         this.budgetSource = options.budgetSource ?? { runId: this.sessionID ?? "agent" };
         this.skillSummaries = options.skills ?? [];
         this.memoryPrompt = options.memoryPrompt;
+        this.fileStateTracker = options.fileStateTracker;
+        this.agentCategories = options.agentCategories ?? {};
+        this.providerFactory = options.providerFactory;
         if (options.systemPrompt) {
             this.messages.push({ role: "system", content: options.systemPrompt });
         }
@@ -111,11 +121,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 });
     }
@@ -297,6 +322,12 @@ export class Agent {
                 description: t.description,
                 parameters: t.parameters,
             }));
+            // LLM-driven compaction runs ahead of projector's algorithmic passes. If
+            // it succeeds, this.messages is replaced with [preserved system+meta] +
+            // [LLM summary] + [last user msg], and the projector becomes a no-op for
+            // budget. If it fails (network error, etc.), the projector's existing
+            // algorithmic fallback still kicks in.
+            await this.maybeCompactWithLLM();
             try {
                 const projectedMessages = projectMessages(this.messages, {
                     mode: "budgeted",
@@ -320,6 +351,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;
@@ -498,10 +538,14 @@ export class Agent {
                             result = next;
                         },
                     });
+                    // Honor the model's server-declared per-tool-output token cap (e.g.
+                    // gpt-5.5 reports 10000). Without this, 4-5 large file reads in a row
+                    // blow past the input window even though our local estimate looks fine.
+                    const truncatedOutput = truncateToolOutputForModel(result.content, this.providerId, this.apiModel);
                     this.appendMessage({
                         role: "tool",
                         toolCallId: tc.id,
-                        content: result.content,
+                        content: truncatedOutput.content,
                         metadata: result.metadata,
                         isError: result.isError,
                     });
@@ -533,7 +577,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 +593,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 +614,7 @@ export class Agent {
             if (afterTokens < beforeTokens) {
                 this.lastInputTokens = null;
                 this.lastAnchorMessageCount = null;
+                this.fileStateTracker?.invalidateReadHistory();
                 return before - this.messages.length;
             }
         }
@@ -583,6 +629,22 @@ export class Agent {
             this.messages = llmResult.messages;
             this.lastInputTokens = null;
             this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
+            return before - this.messages.length;
+        }
+        // Single-turn capable LLM compactor. compactMessagesWithLLM above no-ops
+        // when there's only one user turn (the "single huge prompt with many tool
+        // calls" case), so try the turn-internal compactor before giving up.
+        const { compactWithLLM } = await import("./context/llm-compactor.js");
+        const singleTurnResult = await compactWithLLM(this.messages, {
+            provider: this.provider,
+            modelId: this.apiModel,
+        });
+        if (singleTurnResult.compacted && singleTurnResult.messages) {
+            this.messages = singleTurnResult.messages;
+            this.lastInputTokens = null;
+            this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
             return before - this.messages.length;
         }
         const fallback = compactMessages(this.messages, { keepRecentTurns });
@@ -590,6 +652,21 @@ export class Agent {
             this.messages = fallback.messages;
             this.lastInputTokens = null;
             this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
+            return before - this.messages.length;
+        }
+        // Codex-style last-resort: drop the single oldest non-protected message
+        // and let the retry loop try again. Cheap, but eventually narrows even an
+        // intractable single-turn overflow.
+        const oldestIdx = this.messages.findIndex((m) => m.role !== "system" && m.role !== "meta");
+        if (oldestIdx >= 0 && oldestIdx < this.messages.length - 1) {
+            this.messages = [
+                ...this.messages.slice(0, oldestIdx),
+                ...this.messages.slice(oldestIdx + 1),
+            ];
+            this.lastInputTokens = null;
+            this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
             return before - this.messages.length;
         }
         return 0;
@@ -597,6 +674,34 @@ export class Agent {
     compactResidentHistory() {
         this.maybeCompactResidentHistory();
     }
+    async maybeCompactWithLLM() {
+        if (!this.providerId || !this.apiModel)
+            return;
+        if (this.messages.length === 0)
+            return;
+        const tail = this.lastAnchorMessageCount !== null
+            ? this.messages.slice(this.lastAnchorMessageCount)
+            : undefined;
+        const budget = getContextBudget(this.providerId, this.apiModel, this.messages, {
+            usageAnchorTokens: this.lastInputTokens ?? undefined,
+            tailMessages: tail,
+        });
+        if (!budget.shouldCompact)
+            return;
+        const { compactWithLLM } = await import("./context/llm-compactor.js");
+        const result = await compactWithLLM(this.messages, {
+            provider: this.provider,
+            modelId: this.apiModel,
+        });
+        if (result.compacted && result.messages) {
+            this.messages = result.messages;
+            this.lastInputTokens = null;
+            this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
+        }
+        // If LLM compaction failed for any reason, leave this.messages alone —
+        // the projector's algorithmic budgeted-mode passes will still try.
+    }
     async runSubtask(input, cwd, options) {
         const subtaskType = options?.subtaskType;
         const profile = builtinAgentProfiles().find((item) => item.subtaskType === (subtaskType ?? "general_readonly"))
@@ -606,6 +711,7 @@ export class Agent {
             runId: randomUUID(),
             subAgentId: randomUUID(),
             parentToolCallId: "task",
+            route: this.resolveRouteForSubagent(profile, undefined),
             description: options?.description,
         });
         const lines = [
@@ -641,6 +747,7 @@ export class Agent {
             parentToolCallId: options.parentToolCallId,
             parentToolName: "subagent",
             nickname: options.nickname,
+            route: options.route ?? this.resolveRouteForSubagent(options.profile, options.category),
         });
         await this.runSubagentThread(record, input, cwd, {
             approval: options.approval ?? options.profile.approval,
@@ -656,6 +763,7 @@ export class Agent {
             task: typeof input === "string" ? input : "(multimodal task)",
             parentToolCallId: options.parentToolCallId,
             parentToolName: "spawn_agent",
+            route: options.route ?? this.resolveRouteForSubagent(options.profile, options.category),
         });
         this.subagentThreads.set(record.agentId, record);
         this.queueSubagentUpdate(record, "queued", undefined, `Queued ${record.nickname} (${record.profile.name})`);
@@ -746,6 +854,31 @@ export class Agent {
     listSubAgents() {
         return [...this.subagentThreads.values()].map(snapshotSubagentThread);
     }
+    resolveRouteForSubagent(profile, category) {
+        const parentRoute = {
+            providerId: this.providerId,
+            model: this.apiModel,
+            thinkingLevel: this.thinkingLevel,
+        };
+        const resolved = resolveSubagentRoute(category ?? profile.category, {
+            ...parentRoute,
+        }, this.agentCategories);
+        if ("error" in resolved) {
+            throw new Error(resolved.error);
+        }
+        if (profile.model && profile.model !== "inherit") {
+            const model = resolveModelRoute(profile.model, parentRoute.providerId);
+            if (model.model !== "inherit") {
+                return {
+                    ...resolved.route,
+                    providerId: model.providerId,
+                    model: model.model,
+                    inherited: false,
+                };
+            }
+        }
+        return resolved.route;
+    }
     createSubagentThreadRecord(options) {
         const now = Date.now();
         const nickname = options.nickname ?? assignAgentNickname(options.profile, this.activeSubagentNicknames());
@@ -754,6 +887,8 @@ export class Agent {
             runId: options.runId ?? randomUUID(),
             nickname,
             profile: options.profile,
+            category: options.route?.category,
+            route: options.route,
             parentToolCallId: options.parentToolCallId,
             parentToolName: options.parentToolName,
             status: "queued",
@@ -789,9 +924,20 @@ export class Agent {
             return;
         }
         const tools = selectToolsForAgentProfile(allTools, record.profile, options.approval);
-        const subAgent = options.reuseAgent && record.agent
-            ? record.agent
-            : this.createSubAgentInstance(record, tools, cwd, options.forkContext);
+        let subAgent;
+        try {
+            subAgent = options.reuseAgent && record.agent
+                ? record.agent
+                : await this.createSubAgentInstance(record, tools, cwd, options.forkContext);
+        }
+        catch (error) {
+            record.status = "blocked";
+            record.error = error?.message || String(error);
+            record.updatedAt = Date.now();
+            emit("blocked", undefined, record.error);
+            this.notifySubagentWaiters(record);
+            return;
+        }
         record.agent = subAgent;
         record.status = "running";
         record.updatedAt = Date.now();
@@ -892,14 +1038,21 @@ export class Agent {
             record.summary = finalSummary;
         }
     }
-    createSubAgentInstance(record, tools, cwd, forkContext) {
+    async createSubAgentInstance(record, tools, cwd, forkContext) {
         const childToolNames = tools.map((tool) => tool.name);
+        const route = record.route ?? {
+            providerId: this.providerId,
+            model: this.apiModel,
+            thinkingLevel: this.thinkingLevel,
+            inherited: true,
+        };
+        const provider = await this.resolveProviderForRoute(route);
         const childSystemPrompt = buildSystemPrompt({
             agentName: "Bubble",
-            configuredProvider: this.providerId || "none",
-            configuredModel: this.model || "none",
-            configuredModelId: this.model || "none",
-            thinkingLevel: this.thinkingLevel,
+            configuredProvider: route.providerId || "none",
+            configuredModel: route.model || "none",
+            configuredModelId: route.providerId && route.model ? `${route.providerId}:${route.model}` : route.model || "none",
+            thinkingLevel: route.thinkingLevel,
             mode: "plan",
             workingDir: cwd,
             tools: childToolNames,
@@ -913,24 +1066,38 @@ export class Agent {
             ].filter(Boolean).join("\n\n"),
         });
         const subAgent = new Agent({
-            provider: this.provider,
-            providerId: this.providerId,
-            model: record.profile.model && record.profile.model !== "inherit" ? record.profile.model : this.model,
+            provider,
+            providerId: route.providerId,
+            model: route.model,
             tools,
             temperature: this.temperature,
-            thinkingLevel: this.thinkingLevel,
+            thinkingLevel: route.thinkingLevel,
             mode: "plan",
             maxTurns: record.profile.maxTurns,
             budgetLedger: this.budgetLedger,
             budgetSource: { runId: record.runId, subAgentId: record.agentId },
             systemPrompt: childSystemPrompt,
             hooks: this.hookDefinitions,
+            agentCategories: this.agentCategories,
+            providerFactory: this.providerFactory,
         });
         if (forkContext) {
             subAgent.messages = this.forkMessagesForSubagent(childSystemPrompt);
         }
         return subAgent;
     }
+    async resolveProviderForRoute(route) {
+        if (!route.providerId || route.providerId === this.providerId) {
+            return this.provider;
+        }
+        if (!this.providerFactory) {
+            throw new Error([
+                `Subagent route requires provider "${route.providerId}" for model "${route.model}",`,
+                `but the parent agent only has provider "${this.providerId || "none"}" and no provider factory is configured.`,
+            ].join(" "));
+        }
+        return this.providerFactory(route);
+    }
     forkMessagesForSubagent(childSystemPrompt) {
         const forked = this.messages
             .filter((message) => {
@@ -955,6 +1122,8 @@ export class Agent {
             subAgentId: record.agentId,
             agentName: record.profile.name,
             nickname: record.nickname,
+            category: record.category,
+            route: record.route,
             status,
             childEvent: event,
             summaryDelta: event?.type === "text_delta" ? event.content : undefined,
@@ -968,6 +1137,8 @@ export class Agent {
                         subAgentId: record.agentId,
                         agentName: record.profile.name,
                         nickname: record.nickname,
+                        category: record.category,
+                        route: record.route,
                         status,
                         profileSource: record.profile.source,
                         task: record.task,
@@ -1056,6 +1227,7 @@ export class Agent {
             this.messages = candidate;
             this.lastInputTokens = null;
             this.lastAnchorMessageCount = null;
+            this.fileStateTracker?.invalidateReadHistory();
         }
     }
     appendMessage(message) {

package/dist/config.d.ts

@@ -3,17 +3,33 @@
  *
  * Uses a single JSON file in Bubble home, normally ~/.bubble/config.json.
  */
+import { type AgentCategoriesConfig } from "./agent/categories.js";
 import type { ProviderProfile } from "./provider-registry.js";
 import type { ThinkingLevel } from "./types.js";
+export type ThemeMode = "auto" | "light" | "dark";
+export interface ThemeConfig {
+    mode: ThemeMode;
+    overrides?: Record<string, string>;
+}
 export interface UserConfigData {
     defaultModel?: string;
     defaultThinkingLevel?: ThinkingLevel;
     skillPaths?: string[];
-    theme?: Record<string, string>;
+    /**
+     * Three shapes are accepted on disk so we can evolve without breaking
+     * existing configs:
+     *   - `"auto" | "light" | "dark"` — mode only
+     *   - `{ mode, overrides? }` — mode + optional per-key palette overrides
+     *   - `Record<string, string>` (legacy) — treated as `{ mode: "dark", overrides }`
+     *     so users who customized colors before light-mode existed keep their
+     *     palette and stay on dark, which was the only palette at the time.
+     */
+    theme?: ThemeMode | ThemeConfig | Record<string, string>;
     recentModels?: string[];
     apiKey?: string;
     providers?: ProviderProfile[];
     defaultProvider?: string;
+    agentCategories?: AgentCategoriesConfig;
 }
 export declare class UserConfig {
     private data;
@@ -34,8 +50,12 @@ export declare class UserConfig {
     setDefaultProvider(id: string): void;
     getSkillPaths(): string[];
     setSkillPaths(paths: string[]): void;
-    getTheme(): Record<string, string>;
-    setTheme(theme: Record<string, string>): void;
+    getTheme(): ThemeConfig;
+    getThemeMode(): ThemeMode;
+    getThemeOverrides(): Record<string, string>;
+    setThemeMode(mode: ThemeMode): void;
+    setThemeOverrides(overrides: Record<string, string>): void;
+    getAgentCategories(): AgentCategoriesConfig;
 }
 /** Mask an API key for safe display. */
 export declare function maskKey(key: string): string;

package/dist/config.js

@@ -6,6 +6,7 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { getBubbleHome } from "./bubble-home.js";
+import { sanitizeAgentCategories } from "./agent/categories.js";
 const HIDDEN_PROVIDER_IDS = new Set(["openrouter", "openai-codex"]);
 function getConfigPath() {
     return join(getBubbleHome(), "config.json");
@@ -36,6 +37,39 @@ function sanitizeDefaultModel(model) {
 function sanitizeDefaultProvider(providerId) {
     return isHiddenProviderId(providerId) ? undefined : providerId;
 }
+function sanitizeTheme(value) {
+    if (value == null)
+        return undefined;
+    if (typeof value === "string") {
+        return value === "auto" || value === "light" || value === "dark"
+            ? { mode: value }
+            : undefined;
+    }
+    if (typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    // Discriminate the new `{ mode, overrides }` shape from the legacy
+    // `Record<string, string>` shape. A legacy config has no `mode` key.
+    const maybeNew = value;
+    if (typeof maybeNew.mode === "string") {
+        const mode = maybeNew.mode;
+        if (mode !== "auto" && mode !== "light" && mode !== "dark")
+            return undefined;
+        const overrides = isStringMap(maybeNew.overrides) ? maybeNew.overrides : undefined;
+        return overrides ? { mode, overrides } : { mode };
+    }
+    const overrides = pickStringEntries(value);
+    if (Object.keys(overrides).length === 0)
+        return undefined;
+    return { mode: "dark", overrides };
+}
+function isStringMap(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return false;
+    return Object.values(value).every((entry) => typeof entry === "string");
+}
+function pickStringEntries(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, v]) => typeof v === "string"));
+}
 export class UserConfig {
     data = {};
     constructor() {
@@ -54,6 +88,8 @@ export class UserConfig {
                 recentModels: sanitizeRecentModels(parsed.recentModels),
                 providers: sanitizeProviders(parsed.providers),
                 defaultProvider: sanitizeDefaultProvider(parsed.defaultProvider),
+                agentCategories: sanitizeAgentCategories(parsed.agentCategories),
+                theme: sanitizeTheme(parsed.theme),
             };
         }
         catch {
@@ -126,15 +162,32 @@ export class UserConfig {
         this.save();
     }
     getTheme() {
-        const theme = this.data.theme;
-        if (!theme || typeof theme !== "object" || Array.isArray(theme))
-            return {};
-        return Object.fromEntries(Object.entries(theme).filter(([, value]) => typeof value === "string"));
+        const theme = sanitizeTheme(this.data.theme);
+        return theme ?? { mode: "auto" };
+    }
+    getThemeMode() {
+        return this.getTheme().mode;
+    }
+    getThemeOverrides() {
+        return this.getTheme().overrides ?? {};
     }
-    setTheme(theme) {
-        this.data.theme = { ...theme };
+    setThemeMode(mode) {
+        const current = this.getTheme();
+        this.data.theme = current.overrides
+            ? { mode, overrides: current.overrides }
+            : { mode };
         this.save();
     }
+    setThemeOverrides(overrides) {
+        const current = this.getTheme();
+        this.data.theme = Object.keys(overrides).length === 0
+            ? { mode: current.mode }
+            : { mode: current.mode, overrides: { ...overrides } };
+        this.save();
+    }
+    getAgentCategories() {
+        return sanitizeAgentCategories(this.data.agentCategories);
+    }
 }
 /** Mask an API key for safe display. */
 export function maskKey(key) {

package/dist/context/budget.d.ts

@@ -16,6 +16,7 @@ export interface ContextBudgetOptions {
     /** Messages appended after the anchor (their tokens are estimated and added). */
     tailMessages?: Message[];
 }
-export declare function estimateMessageTokens(message: Message): number;
-export declare function estimateContextTokens(messages: Message[]): number;
+export declare function estimateMessageTokens(message: Message, providerId?: string): number;
+export declare function estimateContextTokens(messages: Message[], providerId?: string): number;
 export declare function getContextBudget(providerId: string, modelId: string, messages: Message[], options?: ContextBudgetOptions): ContextBudget;
+export declare function estimateTextTokens(text: string, providerId?: string): number;

package/dist/context/budget.js

@@ -1,36 +1,44 @@
 import { getModelContextWindow } from "../model-catalog.js";
+import { getTokenEstimator } from "./token-estimator.js";
 export const OUTPUT_RESERVE_TOKENS = 20_000;
 export const AUTOCOMPACT_BUFFER_TOKENS = 13_000;
 export const PRUNE_BUFFER_TOKENS = 50_000;
 export const MIN_WINDOW_FOR_RESERVE = 40_000;
-export function estimateMessageTokens(message) {
+// Safety margins applied to estimator-derived token counts. The estimator can
+// undercount on dense / CJK / tool-payload content; treating its output as a
+// hard floor means we'd routinely overshoot the real server-side count. These
+// multipliers bias the budget decision toward earlier compaction.
+const TAIL_SAFETY_MARGIN = 1.15; // applied to estimated tail when anchored
+const FIRST_TURN_SAFETY_MARGIN = 1.25; // applied when there's no anchor yet
+export function estimateMessageTokens(message, providerId) {
+    const estimate = (text) => estimateTextTokens(text, providerId);
     switch (message.role) {
         case "system":
         case "meta":
         case "tool":
-            return estimateTextTokens(message.content);
+            return estimate(message.content);
         case "assistant":
-            return estimateTextTokens(message.content)
-                + estimateTextTokens(message.reasoning ?? "")
-                + (message.toolCalls?.reduce((sum, toolCall) => sum + estimateTextTokens(toolCall.arguments) + 12, 0) ?? 0)
+            return estimate(message.content)
+                + estimate(message.reasoning ?? "")
+                + (message.toolCalls?.reduce((sum, toolCall) => sum + estimate(toolCall.arguments) + 12, 0) ?? 0)
                 + 8;
         case "user":
             if (typeof message.content === "string") {
-                return estimateTextTokens(message.content) + 8;
+                return estimate(message.content) + 8;
             }
             return message.content.reduce((sum, part) => {
                 if (part.type === "text") {
-                    return sum + estimateTextTokens(part.text);
+                    return sum + estimate(part.text);
                 }
                 return sum + 256;
             }, 8);
     }
 }
-export function estimateContextTokens(messages) {
-    return messages.reduce((sum, message) => sum + estimateMessageTokens(message), 0);
+export function estimateContextTokens(messages, providerId) {
+    return messages.reduce((sum, message) => sum + estimateMessageTokens(message, providerId), 0);
 }
 export function getContextBudget(providerId, modelId, messages, options = {}) {
-    const estimatedTokens = computeEstimatedTokens(messages, options);
+    const estimatedTokens = computeEstimatedTokens(providerId, messages, options);
     const contextWindow = getModelContextWindow(providerId, modelId);
     const percent = contextWindow ? Math.min(100, (estimatedTokens / contextWindow) * 100) : undefined;
     return {
@@ -41,11 +49,17 @@ export function getContextBudget(providerId, modelId, messages, options = {}) {
         shouldCompact: shouldTriggerCompact(estimatedTokens, contextWindow),
     };
 }
-function computeEstimatedTokens(messages, options) {
+function computeEstimatedTokens(providerId, messages, options) {
     if (options.usageAnchorTokens !== undefined && options.tailMessages) {
-        return options.usageAnchorTokens + estimateContextTokens(options.tailMessages);
+        // Anchor is authoritative (server-reported input tokens from the last
+        // response). Tail goes through our estimator and may undercount on dense /
+        // tool-output content, so we inflate it by a small margin before adding.
+        const tailEstimate = estimateContextTokens(options.tailMessages, providerId);
+        return options.usageAnchorTokens + Math.ceil(tailEstimate * TAIL_SAFETY_MARGIN);
     }
-    return estimateContextTokens(messages);
+    // First turn (or anchor lost): there's no server-reported baseline at all,
+    // so apply a larger safety margin to the pure estimate.
+    return Math.ceil(estimateContextTokens(messages, providerId) * FIRST_TURN_SAFETY_MARGIN);
 }
 function shouldTriggerPrune(estimatedTokens, contextWindow) {
     if (!contextWindow) {
@@ -65,9 +79,9 @@ function shouldTriggerCompact(estimatedTokens, contextWindow) {
         : contextWindow * 0.75;
     return estimatedTokens >= threshold;
 }
-function estimateTextTokens(text) {
+export function estimateTextTokens(text, providerId) {
     if (!text) {
         return 0;
     }
-    return Math.ceil(text.length / 4);
+    return getTokenEstimator(providerId).estimate(text);
 }

package/dist/context/compact.d.ts

@@ -13,3 +13,26 @@ export interface CompactResult {
 }
 export declare function compactSessionEntries(entries: SessionLogEntry[], options?: CompactOptions): CompactResult;
 export declare function compactMessages(messages: Message[], options?: CompactOptions): CompactResult;
+/**
+ * Sub-turn compaction.
+ *
+ * When the active user turn has accumulated many (assistant + tool-result) groups
+ * — typically a single "look at this project" prompt that triggers a dozen file
+ * reads — multi-turn compactMessages above is a no-op (there's only one user turn
+ * to summarize). This variant operates one level finer: it groups messages inside
+ * the last user turn by assistant message, keeps the most recent K groups intact,
+ * and replaces the older ones with a synthetic system message that names the tools
+ * called and files inspected.
+ *
+ * Constraints honored:
+ * - Older groups are dropped WHOLE (assistant + its tool results). Dropping just
+ *   the tool results would leave orphan tool_calls; repairToolCallChains would
+ *   then synthesize "[no result captured]" placeholders, undoing the win.
+ * - Pre-turn content (earlier user turns) is left untouched — that's the
+ *   multi-turn compactor's territory.
+ */
+export interface SubTurnCompactOptions {
+    keepRecentGroups?: number;
+    maxSummaryItems?: number;
+}
+export declare function compactCurrentTurnToolGroups(messages: Message[], options?: SubTurnCompactOptions): CompactResult;