@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/agent/codebuddy-agent.js

@@ -13,6 +13,7 @@ import { AgentExecutor, setDecisionContextProvider, setICMBridgeProvider, setCod
 import { ToolHandler } from "./tool-handler.js";
 import { BaseAgent } from "./base-agent.js";
 import { createAgentInfrastructureSync } from "./infrastructure/index.js";
+import { MODEL_PRICING, isChatGptSubscriptionModel, isLocalNoCostModel } from "../utils/cost-tracker.js";
 import { getLaneQueue } from "../concurrency/lane-queue.js";
 import { findSkill, findStarterPack, resetSkillRegistry } from "../skills/index.js";
 import { skillMdToUnified } from "../skills/adapters/index.js";
@@ -30,6 +31,10 @@ import { resetConfigWatcher } from "../config/hot-reload/watcher.js";
 import { resetPersonaManager } from "../personas/persona-manager.js";
 import { resetEnhancedMemory } from "../memory/enhanced-memory.js";
 import { resetPluginMarketplace } from "../plugins/marketplace.js";
+import { classifyLisaIntrospection } from '../identity/lisa-introspection.js';
+import { primeLocalRuntimeModelConfig } from '../config/local-runtime-context.js';
+import { getModelToolConfig } from '../config/model-tools.js';
+import { inferCostProvider } from '../analytics/cost-report.js';
 /**
  * Main agent class that orchestrates conversation with CodeBuddy AI and tool execution
  *
@@ -61,6 +66,12 @@ export class CodeBuddyAgent extends BaseAgent {
     visionGroundingModel;
     streamingHandler;
     executor;
+    /**
+     * Counters the provider reported for the most recent completed turn, summed
+     * over its rounds. `null` when the provider reported none — the caller must
+     * then say so rather than pass an estimate off as a measurement.
+     */
+    lastTurnProviderUsage = null;
     toolSelectionStrategy;
     /** Optional peer routing config applied from channel route resolution */
     peerRoutingConfig = null;
@@ -72,6 +83,8 @@ export class CodeBuddyAgent extends BaseAgent {
     /** Budget alert monitoring */
     budgetAlertManager = new BudgetAlertManager();
     _budgetAlertListener;
+    /** Nested host gates currently holding assistant text in a private draft state. */
+    transcriptSnapshotSuspensions = 0;
     /**
      * Create a new CodeBuddyAgent instance
      *
@@ -122,7 +135,7 @@ export class CodeBuddyAgent extends BaseAgent {
             ? envMaxContext
             : undefined;
         // Create infrastructure - encapsulates all manager dependencies
-        this.infrastructure = createAgentInfrastructureSync({ apiKey, model: modelToUse, baseURL, maxContextTokens }, { memoryEnabled: this.memoryEnabled, useModelRouting: this.useModelRouting });
+        this.infrastructure = createAgentInfrastructureSync({ apiKey, model: modelToUse, baseURL, maxContextTokens, workingDirectory: initialWorkingDirectory }, { memoryEnabled: this.memoryEnabled, useModelRouting: this.useModelRouting });
         // Bridge to BaseAgent properties for backwards compatibility
         // Note: We cast interface types to concrete types since BaseAgent uses concrete types
         // This is safe because the singletons returned by getters are the concrete implementations
@@ -214,10 +227,13 @@ export class CodeBuddyAgent extends BaseAgent {
             checkpointManager: this.checkpointManager,
             hooksManager: this.hooksManager,
             marketplace: this.marketplace,
-            repairCoordinator: this.repairCoordinator
+            repairCoordinator: this.repairCoordinator,
+            sessionIdProvider: () => this.sessionStore.getCurrentSessionId() ?? undefined,
+            contextZoomSessionIdProvider: () => this.contextManager.getSessionId(),
         });
         this.toolHandler.setWorkingDirectory(workingDirectory);
         // Initialize Executor
+        const timelineEnabled = process.env.CODEBUDDY_TIMELINE === 'true';
         this.executor = new AgentExecutor({
             client: this.codebuddyClient,
             toolHandler: this.toolHandler,
@@ -228,6 +244,44 @@ export class CodeBuddyAgent extends BaseAgent {
             laneQueue: getLaneQueue(),
             laneId: 'agent-tools',
             messageQueue: this.messageQueue,
+            ...(timelineEnabled
+                ? {
+                    recordTimelineTurn: async (turn) => {
+                        const sessionId = this.sessionStore.getCurrentSessionId();
+                        if (!sessionId)
+                            return;
+                        const { SessionTimeline } = await import('../sessions/timeline.js');
+                        let checkpointId;
+                        try {
+                            const { captureAndSaveTimelineSnapshot } = await import('../sessions/timeline-snapshot.js');
+                            const cwd = this.toolHandler.getWorkingDirectory() || process.cwd();
+                            checkpointId = captureAndSaveTimelineSnapshot({
+                                sessionId,
+                                turn: turn.turn,
+                                cwd,
+                            }).id;
+                        }
+                        catch (error) {
+                            logger.warn('[session-timeline] failed to snapshot working tree', {
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                        }
+                        await new SessionTimeline(sessionId).record({
+                            turn: turn.turn,
+                            ts: turn.ts,
+                            role: turn.role,
+                            textPreview: turn.text,
+                            toolCalls: turn.toolCalls,
+                            filesTouched: turn.filesTouched,
+                            ...(checkpointId ? { checkpointId } : {}),
+                        });
+                    },
+                }
+                : {}),
+            operationalRobotNameProvider: async () => {
+                const { getActivePersonaVoiceAsync } = await import('../personas/persona-manager.js');
+                return (await getActivePersonaVoiceAsync()).robotName;
+            },
             // Phase d.22 — query-aware system prompt rebuild. Called by the
             // executor on toolRounds === 0 so trivial queries on `lite`-profile
             // models (Ollama qwen, llama, deepseek) get a minimal SP (~9 KB)
@@ -255,6 +309,9 @@ export class CodeBuddyAgent extends BaseAgent {
             maxToolRounds: this.maxToolRounds,
             isGrokModel: this.isGrokModel.bind(this),
             recordSessionCost: this.recordSessionCost.bind(this),
+            recordTurnProviderUsage: (usage) => {
+                this.lastTurnProviderUsage = usage ? { ...usage } : null;
+            },
             isSessionCostLimitReached: this.isSessionCostLimitReached.bind(this),
             estimateSessionCostLimitReached: this.estimateSessionCostLimitReached.bind(this),
             getSessionCost: this.getSessionCost.bind(this),
@@ -290,7 +347,6 @@ export class CodeBuddyAgent extends BaseAgent {
                 try {
                     const { CostLimitMiddleware } = await import('./middleware/cost-limit.js');
                     pipeline.use(new CostLimitMiddleware({
-                        recordSessionCost: this.recordSessionCost.bind(this),
                         isSessionCostLimitReached: this.isSessionCostLimitReached.bind(this),
                     }));
                     logger.debug('CostLimitMiddleware registered in pipeline (priority 20)');
@@ -362,6 +418,18 @@ export class CodeBuddyAgent extends BaseAgent {
                 catch (err) {
                     logger.debug('Failed to register VisualValidationMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
                 }
+                // Plan completion audit (priority 157) — Manus "todo.md is a verification
+                // ledger" pattern: when an active PLAN.md still has open items, nudge the
+                // model ONCE to audit its checklist (verify or explicitly skip) before
+                // concluding, instead of declaring done from memory. Inert with no plan.
+                try {
+                    const { createPlanCompletionAuditMiddleware } = await import('./middleware/plan-completion-audit.js');
+                    pipeline.use(createPlanCompletionAuditMiddleware());
+                    logger.debug('PlanCompletionAuditMiddleware registered in pipeline (priority 157)');
+                }
+                catch (err) {
+                    logger.debug('Failed to register PlanCompletionAuditMiddleware (non-critical)', { error: err instanceof Error ? err.message : String(err) });
+                }
                 // Quality gate middleware (priority 200) — auto-delegates to specialized agents
                 try {
                     const { createQualityGateMiddleware } = await import('./middleware/quality-gate-middleware.js');
@@ -412,8 +480,13 @@ export class CodeBuddyAgent extends BaseAgent {
             });
         }).catch((e) => { logger.debug('Agent registry module load failed (optional)', { error: String(e) }); });
         // Load SKILL.md skills so findSkill() returns results
-        import('../skills/index.js').then(({ initializeSkills }) => {
-            initializeSkills().catch((e) => { logger.debug('Skills initialization failed (optional)', { error: String(e) }); });
+        this.skillsReady = import('../skills/index.js').then(async ({ initializeSkills }) => {
+            try {
+                await initializeSkills();
+            }
+            catch (e) {
+                logger.debug('Skills initialization failed (optional)', { error: String(e) });
+            }
         }).catch((e) => { logger.debug('Skills module load failed (optional)', { error: String(e) }); });
         // Initialize MCP servers if configured (can be disabled for headless/one-shot runs).
         if (process.env.CODEBUDDY_DISABLE_MCP !== 'true') {
@@ -422,7 +495,7 @@ export class CodeBuddyAgent extends BaseAgent {
         // Load custom instructions and generate system prompt
         const customInstructions = loadCustomInstructions();
         // Initialize system prompt (async operation) — track readiness
-        this.systemPromptReady = this.initializeAgentSystemPrompt(systemPromptId, modelToUse, customInstructions);
+        this.systemPromptReady = this.initializeAgentSystemPrompt(systemPromptId, modelToUse, customInstructions, baseURL, apiKey);
         // Fire SessionStart user hook (non-blocking)
         getUserHooksManager(initialWorkingDirectory).executeHooks('SessionStart', {}).catch((err) => logger.debug(`[user-hooks] SessionStart error: ${err}`));
         // Wire visual grounding fallback provider into computer-control-tool
@@ -505,6 +578,11 @@ Look at the screenshot and find the element matching the user's intent. Output o
     }
     /** Resolves when the system prompt has been loaded (or failed gracefully). */
     systemPromptReady;
+    /** Resolves when the asynchronous skill registry startup has settled. */
+    skillsReady = Promise.resolve();
+    getSkillsReady() {
+        return this.skillsReady;
+    }
     /**
      * Set the model override to use specifically for visual grounding fallback calls.
      */
@@ -526,8 +604,13 @@ Look at the screenshot and find the element matching the user's intent. Output o
     setChannelBotId(botId) {
         this.toolHandler.setBotId(botId);
     }
-    async initializeAgentSystemPrompt(systemPromptId, modelName, customInstructions) {
+    /** Scope raw tool-result recovery to an embedding host's conversation. */
+    setRecoverySessionId(sessionId) {
+        this.toolHandler.setRecoverySessionId(sessionId);
+    }
+    async initializeAgentSystemPrompt(systemPromptId, modelName, customInstructions, baseURL, apiKey) {
         try {
+            await this.primeLocalRuntimeContext(modelName, baseURL, apiKey);
             const hasInitialOverride = !!this.customSystemPromptOverride;
             let systemPrompt = this.customSystemPromptOverride
                 ?? await this.promptBuilder.buildSystemPrompt(systemPromptId, modelName, customInstructions);
@@ -561,6 +644,39 @@ Look at the screenshot and find the element matching the user's intent. Output o
             });
         }
     }
+    async primeLocalRuntimeContext(modelName, baseURL, apiKey) {
+        try {
+            const runtime = await primeLocalRuntimeModelConfig({
+                model: modelName,
+                baseURL,
+                apiKey,
+            });
+            if (!runtime)
+                return;
+            // CODEBUDDY_MAX_CONTEXT is an explicit user override and therefore wins
+            // over discovery. Otherwise, refresh the manager built synchronously in
+            // the constructor before the first prompt/turn consumes its limits.
+            const envMaxContext = Number(process.env.CODEBUDDY_MAX_CONTEXT);
+            if (Number.isFinite(envMaxContext) && envMaxContext > 0)
+                return;
+            const contextWindow = getModelToolConfig(modelName).contextWindow;
+            if (!contextWindow)
+                return;
+            this.contextManager.updateConfig({
+                maxContextTokens: contextWindow,
+                responseReserveTokens: Math.floor(contextWindow * 0.125),
+                autoCompactThreshold: Math.min(200_000, contextWindow),
+            });
+        }
+        catch (error) {
+            // Discovery must never turn an offline local workstation into a startup
+            // failure. Keep the context manager and config cache exactly as built.
+            logger.debug('Local runtime context probe skipped', {
+                model: modelName,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
     applyRuntimeSystemPromptAppend(systemPrompt) {
         const append = this.systemPromptAppend?.trim();
         if (!append) {
@@ -623,6 +739,59 @@ Look at the screenshot and find the element matching the user's intent. Output o
                 });
             }).catch((e) => { logger.debug('Advisor toml-config import failed (optional)', { error: String(e) }); });
         }).catch((e) => { logger.debug('Advisor config provider wire failed (optional)', { error: String(e) }); });
+        // Wire the Verify tool's LLM bridge so the independent Verifier agent is
+        // REACHABLE at runtime: the `verify` tool delegates to
+        // `registry.executeOn('verifier', …)` which needs an llmCall (to reason)
+        // and an executeTool (to drive read/execute-only oracles). Both are built
+        // from the agent's own client + tool executor — the same plumbing the
+        // SWE/multi-agent bridges use — so nothing new is stood up. The Verifier's
+        // internal toolset gate still refuses writes fail-closed.
+        import('../tools/registry/verify-tools.js').then(({ setVerifyToolProvider }) => {
+            setVerifyToolProvider(() => ({
+                llmCall: async (messages, tools) => {
+                    const resp = await this.codebuddyClient.chat(messages, tools);
+                    const msg = resp.choices?.[0]?.message;
+                    return {
+                        content: msg?.content ?? '',
+                        tool_calls: msg?.tool_calls ?? [],
+                    };
+                },
+                executeTool: async (name, args) => {
+                    const r = await this.executeToolByName(name, args);
+                    return { success: r.success, output: r.output, error: r.error };
+                },
+            }));
+        }).catch((e) => { logger.debug('Verify tool provider wire failed (optional)', { error: String(e) }); });
+        // Wire the delegate_agent tool's LLM bridge so the built-in specialized
+        // agents are REACHABLE at runtime. The deterministic agents (pdf/excel/
+        // data_analysis/sql/archive) need no bridge; the LLM-driven SWE agent needs
+        // an llmCall + executeTool — built from the agent's own client + tool
+        // executor, exactly the same plumbing as the `verify` tool above (this is
+        // the single tolerated contact point, identical to setVerifyToolProvider).
+        import('../tools/registry/delegate-agent-tools.js').then(({ setDelegateAgentProvider }) => {
+            setDelegateAgentProvider(() => ({
+                llmCall: async (messages, tools) => {
+                    const resp = await this.codebuddyClient.chat(messages, tools);
+                    const msg = resp.choices?.[0]?.message;
+                    return {
+                        content: msg?.content ?? '',
+                        tool_calls: msg?.tool_calls ?? [],
+                    };
+                },
+                executeTool: async (name, args, executionExtra) => {
+                    const r = await this.executeToolByName(name, args, executionExtra);
+                    return { success: r.success, output: r.output, error: r.error };
+                },
+            }));
+        }).catch((e) => { logger.debug('Delegate-agent tool provider wire failed (optional)', { error: String(e) }); });
+        // Wire the research-worker factory so WideResearchOrchestrator can spawn
+        // sub-agents WITHOUT importing this module (cycle break — same inversion as
+        // setDelegateAgentProvider). The tool path always runs inside an agent, so
+        // this constructor guarantees the factory is set before any research tool
+        // fires. Idempotent (last-writer-wins).
+        import('./research-worker-provider.js').then(({ setResearchWorkerFactory }) => {
+            setResearchWorkerFactory(({ apiKey, baseURL, model, maxRounds }) => new CodeBuddyAgent(apiKey, baseURL, model, maxRounds));
+        }).catch((e) => { logger.debug('Research-worker factory wire failed (optional)', { error: String(e) }); });
         // Phase (d).21 ship 3 — wake NotificationManager via default sink.
         // Idempotent. Once wired, anyone in the codebase can call notify()
         // / notifyQuick() and it will gate + log + emit on the manager bus.
@@ -751,22 +920,27 @@ Look at the screenshot and find the element matching the user's intent. Output o
         // enabled=true. The /agents slash command can also instantiate it manually
         // at runtime. Wired via audit OpenClaw heritage findings (2026-05-02 — top 4).
         // V0.1: only instantiates the singleton (boot does NOT auto-run a workflow).
-        // Requires GROK_API_KEY env var; logs a warning and skips if absent.
-        import('../config/toml-config.js').then(({ getConfigManager }) => {
+        // Requires any configured provider API key; logs a warning and skips if absent.
+        import('../config/toml-config.js').then(async ({ getConfigManager }) => {
             const masCfg = getConfigManager().getConfig().multi_agent_system;
             if (!masCfg?.enabled)
                 return;
-            const apiKey = process.env.GROK_API_KEY;
+            const { resolveActiveProviderApiKey } = await import('../config/env-schema.js');
+            const apiKey = resolveActiveProviderApiKey();
             if (!apiKey) {
-                logger.warn('MultiAgentSystem boot skipped: GROK_API_KEY not set');
+                logger.warn('MultiAgentSystem boot skipped: no API key set');
                 return;
             }
-            import('../agent/multi-agent/multi-agent-system.js').then(({ getMultiAgentSystem }) => {
+            try {
+                const { getMultiAgentSystem } = await import('../agent/multi-agent/multi-agent-system.js');
                 getMultiAgentSystem(apiKey, process.env.GROK_BASE_URL);
                 logger.info('MultiAgentSystem auto-instantiated from TOML config', {
                     default_strategy: masCfg.default_strategy ?? 'hierarchical',
                 });
-            }).catch((e) => { logger.debug('MultiAgentSystem module load failed (optional)', { error: String(e) }); });
+            }
+            catch (e) {
+                logger.debug('MultiAgentSystem module load failed (optional)', { error: String(e) });
+            }
         }).catch((e) => { logger.debug('Multi-agent system config check failed (optional)', { error: String(e) }); });
         // Boot-time auto-instantiate of EnhancedCoordinator + SessionRegistry
         // when [multi_agent_system.coordination|sessions].enabled = true (Phase F).
@@ -990,13 +1164,22 @@ Look at the screenshot and find the element matching the user's intent. Output o
             logger.debug('Skill matching failed (non-fatal)', { error: String(error) });
         }
     }
-    async processUserMessage(message) {
-        // Lazy-wire decision memory provider on first call
-        this.ensureDecisionMemoryProvider();
-        // Reset cached tools for new conversation turn
-        this.toolSelectionStrategy.clearCache();
+    async processUserMessage(message, options = {}) {
+        const turnStartedAt = Date.now();
+        const introspectionIntent = classifyLisaIntrospection(options.introspectionText ?? message);
+        const readOnlySelfInspection = introspectionIntent === 'describe' || introspectionIntent === 'inspect';
+        // See processUserMessageStream — the system prompt builds async and a
+        // first turn must not race it (embedded hosts don't await it themselves).
+        await this.systemPromptReady;
+        if (!readOnlySelfInspection) {
+            // These global/context services are irrelevant to the deterministic,
+            // root-confined self-report and must not observe or influence that turn.
+            this.ensureDecisionMemoryProvider();
+            this.toolSelectionStrategy.clearCache();
+        }
         // Match user query against skill registry
-        this.applySkillMatching(message);
+        if (!readOnlySelfInspection)
+            this.applySkillMatching(message);
         // Add user message to conversation
         const userEntry = {
             type: "user",
@@ -1007,20 +1190,85 @@ Look at the screenshot and find the element matching the user's intent. Output o
         this.messages.push({ role: "user", content: message });
         // Trim history to prevent memory bloat
         this.trimHistory();
-        const newEntries = await this.executor.processUserMessage(message, this.chatHistory, this.messages);
+        const newEntries = await this.executor.processUserMessage(message, this.chatHistory, this.messages, turnStartedAt, options.transientContext, options.relationshipSafety === true, options.surface, options.introspectionText);
         // Fire-and-forget Hermes-style post-session learning review (interactive only).
-        void this.maybeRunBackgroundReview();
+        if (!readOnlySelfInspection)
+            void this.maybeRunBackgroundReview();
         return [userEntry, ...newEntries];
     }
-    async *processUserMessageStream(message) {
-        // Lazy-wire decision memory provider on first call
-        this.ensureDecisionMemoryProvider();
+    /**
+     * Replace the latest persisted assistant text after a last-mile policy gate.
+     * Both projections must change together so a blocked phrase cannot survive
+     * in the visible transcript or re-enter a later model turn.
+     */
+    replaceLastAssistantResponse(expected, replacement) {
+        let chatIndex = -1;
+        for (let index = this.chatHistory.length - 1; index >= 0; index -= 1) {
+            const entry = this.chatHistory[index];
+            if (entry?.type === 'assistant') {
+                chatIndex = index;
+                break;
+            }
+        }
+        let messageIndex = -1;
+        for (let index = this.messages.length - 1; index >= 0; index -= 1) {
+            const message = this.messages[index];
+            if (message?.role === 'assistant') {
+                messageIndex = index;
+                break;
+            }
+        }
+        if (chatIndex < 0 || messageIndex < 0)
+            return false;
+        if (this.chatHistory[chatIndex]?.content !== expected ||
+            this.messages[messageIndex]?.content !== expected) {
+            return false;
+        }
+        this.chatHistory[chatIndex] = { ...this.chatHistory[chatIndex], content: replacement };
+        this.messages[messageIndex] = { ...this.messages[messageIndex], content: replacement };
+        return true;
+    }
+    /**
+     * Record a deterministic response produced by a trusted local companion
+     * source (for example a dated prefetch digest) without invoking the LLM.
+     * Both projections are updated together so persistence and later follow-ups
+     * see exactly what the person received.
+     */
+    recordTrustedExternalConversationTurn(userContent, assistantContent) {
+        const user = userContent.trim();
+        const assistant = assistantContent.trim();
+        if (!user || !assistant)
+            return false;
+        const now = new Date();
+        this.chatHistory.push({ type: 'user', content: user, timestamp: now });
+        this.chatHistory.push({ type: 'assistant', content: assistant, timestamp: now });
+        this.messages.push({ role: 'user', content: user });
+        this.messages.push({ role: 'assistant', content: assistant });
+        this.trimHistory();
+        return true;
+    }
+    async *processUserMessageStream(message, options = {}) {
+        const turnStartedAt = Date.now();
+        const introspectionIntent = classifyLisaIntrospection(options.introspectionText ?? message);
+        const readOnlySelfInspection = introspectionIntent === 'describe' || introspectionIntent === 'inspect';
+        // The system prompt is built ASYNC at construction. The CLI awaits
+        // systemPromptReady before its first turn, but embedded hosts (Cowork's
+        // engine adapter) did not — a turn fired right after agent creation went
+        // to the LLM with NO system message and no settled tool selection
+        // (observed live: 23-77 input tokens, "je ne peux pas générer d'image").
+        // Await here so every host is covered; resolved-promise cost is ~zero.
+        await this.systemPromptReady;
+        if (!readOnlySelfInspection) {
+            // Keep mutable decision/tool context out of deterministic self-reports.
+            this.ensureDecisionMemoryProvider();
+        }
         // Create new abort controller for this request
         this.abortController = new AbortController();
-        // Reset cached tools for new conversation turn
-        this.toolSelectionStrategy.clearCache();
+        if (!readOnlySelfInspection)
+            this.toolSelectionStrategy.clearCache();
         // Match user query against skill registry
-        this.applySkillMatching(message);
+        if (!readOnlySelfInspection)
+            this.applySkillMatching(message);
         // Add user message to conversation
         const userEntry = {
             type: "user",
@@ -1031,31 +1279,34 @@ Look at the screenshot and find the element matching the user's intent. Output o
         this.messages.push({ role: "user", content: message });
         // Trim history to prevent memory bloat
         this.trimHistory();
-        // Cost prediction before execution
-        const currentModel = this.codebuddyClient.getCurrentModel();
-        const prediction = this.costPredictor.predict(this.messages, currentModel);
-        logger.debug('Cost prediction', {
-            model: prediction.model,
-            estimatedCost: `$${prediction.estimatedCost.toFixed(6)}`,
-            estimatedInputTokens: prediction.estimatedInputTokens,
-            estimatedOutputTokens: prediction.estimatedOutputTokens,
-            confidence: prediction.confidence,
-        });
-        // Warn if predicted cost would exceed remaining budget
-        const remainingBudget = this.sessionCostLimit - this.sessionCost;
-        if (this.sessionCostLimit !== Infinity &&
-            prediction.estimatedCost > remainingBudget) {
-            yield {
-                type: 'content',
-                content: `\nWarning: Estimated cost ($${prediction.estimatedCost.toFixed(4)}) may exceed remaining budget ($${remainingBudget.toFixed(4)}).\n`,
-            };
+        if (!readOnlySelfInspection) {
+            // A local deterministic report makes no provider request, so predicting
+            // or warning about provider cost would be both wasteful and false.
+            const currentModel = this.codebuddyClient.getCurrentModel();
+            const prediction = this.costPredictor.predict(this.messages, currentModel);
+            logger.debug('Cost prediction', {
+                model: prediction.model,
+                estimatedCost: `$${prediction.estimatedCost.toFixed(6)}`,
+                estimatedInputTokens: prediction.estimatedInputTokens,
+                estimatedOutputTokens: prediction.estimatedOutputTokens,
+                confidence: prediction.confidence,
+            });
+            // Warn if predicted cost would exceed remaining budget
+            const remainingBudget = this.sessionCostLimit - this.sessionCost;
+            if (this.sessionCostLimit !== Infinity &&
+                prediction.estimatedCost > remainingBudget) {
+                yield {
+                    type: 'content',
+                    content: `\nWarning: Estimated cost ($${prediction.estimatedCost.toFixed(4)}) may exceed remaining budget ($${remainingBudget.toFixed(4)}).\n`,
+                };
+            }
         }
         // Model routing - select optimal model based on task complexity.
         // Use local variables (not instance state) to avoid race conditions
         // if multiple streams run concurrently.
         let originalModel = null;
         let routingDecision = null;
-        if (this.useModelRouting) {
+        if (!readOnlySelfInspection && this.useModelRouting) {
             const conversationContext = this.chatHistory
                 .slice(-5)
                 .map(e => e.content)
@@ -1070,7 +1321,7 @@ Look at the screenshot and find the element matching the user's intent. Output o
             }
         }
         try {
-            yield* this.executor.processUserMessageStream(message, this.chatHistory, this.messages, this.abortController);
+            yield* this.executor.processUserMessageStream(message, this.chatHistory, this.messages, this.abortController, turnStartedAt, options.transientContext, options.relationshipSafety === true, options.surface, options.introspectionText);
         }
         finally {
             // Restore original model if it was changed by routing.
@@ -1090,7 +1341,8 @@ Look at the screenshot and find the element matching the user's intent. Output o
             this.abortController = null;
         }
         // Fire-and-forget Hermes-style post-session learning review (interactive only).
-        void this.maybeRunBackgroundReview();
+        if (!readOnlySelfInspection)
+            void this.maybeRunBackgroundReview();
     }
     async executeTool(toolCall) {
         return this.toolHandler.executeTool(toolCall);
@@ -1107,6 +1359,28 @@ Look at the screenshot and find the element matching the user's intent. Output o
     getChatHistory() {
         return super.getChatHistory();
     }
+    /** Snapshot only mutable conversation state for HTTP session swapping. */
+    exportConversationState() {
+        return structuredClone({
+            messages: this.historyManager.getMessages(),
+            chatHistory: this.historyManager.getChatHistory(),
+            sessionCost: this.sessionCost,
+            routingSessionCost: this.routingFacade.getSessionCost(),
+            contextManagerState: this.contextManager.exportConversationState(),
+            workingDirectory: this.toolHandler.getWorkingDirectory(),
+        });
+    }
+    /** Restore a snapshot while the HTTP session mutex is held. */
+    importConversationState(state) {
+        const cloned = structuredClone(state);
+        this.historyManager.setMessages(cloned.messages);
+        this.historyManager.setChatHistory(cloned.chatHistory);
+        this.sessionCost = cloned.sessionCost;
+        this.routingFacade.setSessionCost(cloned.routingSessionCost);
+        this.contextManager.importConversationState(cloned.contextManagerState);
+        this.toolHandler.restoreWorkingDirectory(cloned.workingDirectory);
+        this.promptBuilder.updateConfig({ cwd: cloned.workingDirectory });
+    }
     getCurrentDirectory() {
         return this.toolHandler.bash.getCurrentDirectory();
     }
@@ -1121,13 +1395,44 @@ Look at the screenshot and find the element matching the user's intent. Output o
         this.toolHandler.setWorkingDirectory(dir);
         this.promptBuilder.updateConfig({ cwd: dir || process.cwd() });
     }
+    /** Rehydrate chat and LLM history from a persisted session (headless --resume). */
+    hydratePersistedSession(session) {
+        const entries = this.sessionStore.convertMessagesToChatEntries(session.messages);
+        const llmMessages = [];
+        for (const entry of entries) {
+            if (entry.type === 'user' || entry.type === 'assistant') {
+                llmMessages.push({ role: entry.type, content: entry.content });
+            }
+        }
+        this.historyManager.setChatHistory(entries);
+        this.historyManager.setMessages(llmMessages);
+        if (session.workingDirectory) {
+            this.setWorkingDirectory(session.workingDirectory);
+        }
+    }
     setSystemPromptAppend(append) {
         this.systemPromptAppend = append;
     }
+    /** Keep periodic persistence from observing a host-buffered assistant draft. */
+    suspendTranscriptSnapshots() {
+        this.transcriptSnapshotSuspensions += 1;
+        if (this.transcriptSnapshotSuspensions === 1) {
+            this.contextManager.stopPeriodicSnapshot?.();
+        }
+    }
+    /** Resume periodic persistence once every nested draft gate has committed. */
+    resumeTranscriptSnapshots() {
+        if (this.transcriptSnapshotSuspensions <= 0)
+            return;
+        this.transcriptSnapshotSuspensions -= 1;
+        if (this.transcriptSnapshotSuspensions === 0) {
+            this.contextManager.startPeriodicSnapshot?.(() => this.historyManager.getMessagesRef(), undefined, this.toolHandler.getWorkingDirectory());
+        }
+    }
     async executeBashCommand(command) {
         return await this.toolHandler.bash.execute(command);
     }
-    async executeToolByName(name, parameters = {}) {
+    async executeToolByName(name, parameters = {}, executionExtra) {
         return await this.toolHandler.executeTool({
             id: `server_tool_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
             type: 'function',
@@ -1135,11 +1440,77 @@ Look at the screenshot and find the element matching the user's intent. Output o
                 name,
                 arguments: JSON.stringify(parameters),
             },
-        });
+        }, executionExtra);
     }
     getCurrentModel() {
         return this.codebuddyClient.getCurrentModel();
     }
+    /**
+     * Token counters as reported by the PROVIDER for the last completed turn.
+     * Returns `undefined` when the provider reported none, so a consumer never
+     * mistakes an estimate for a measurement.
+     */
+    getLastTurnUsage() {
+        return this.lastTurnProviderUsage ? { ...this.lastTurnProviderUsage } : undefined;
+    }
+    /**
+     * Get extended cost information for the current session.
+     * Returns metadata about whether the cost is based on provider usage or local estimates,
+     * the pricing model used, and billing type.
+     */
+    getSessionCostExtended() {
+        const model = this.getCurrentModel();
+        const report = this.costTracker.getReport();
+        const lastProviderUsage = this.lastTurnProviderUsage;
+        // Determine if we have provider usage
+        const estimated = lastProviderUsage === null || lastProviderUsage === undefined;
+        // Get billing and pricing status
+        const billing = isChatGptSubscriptionModel(model) || isLocalNoCostModel(model)
+            ? 'subscription'
+            : 'pay-per-use';
+        const pricing = billing === 'subscription'
+            ? 'subscription'
+            : MODEL_PRICING[model] ? 'known' : 'unknown';
+        return {
+            total: this.sessionCost,
+            estimated,
+            pricing,
+            billing,
+            inputTokens: report.sessionTokens.input,
+            outputTokens: report.sessionTokens.output,
+        };
+    }
+    saveCurrentSession() {
+        const report = this.costTracker.getReport();
+        const sessionTokens = report.sessionTokens ?? { input: 0, output: 0 };
+        const currentModel = this.getCurrentModel();
+        const model = typeof currentModel === 'string' && currentModel.trim()
+            ? currentModel
+            : 'unknown';
+        const provider = process.env.CODEBUDDY_PROVIDER?.trim() || inferCostProvider(model);
+        const sessionUsage = typeof this.costTracker.getSessionUsage === 'function'
+            ? this.costTracker.getSessionUsage()
+            : [];
+        const turns = sessionUsage.map((row) => ({
+            timestamp: row.timestamp.toISOString(),
+            inputTokens: row.inputTokens,
+            outputTokens: row.outputTokens,
+            costUsd: row.cost,
+            model: row.model,
+            provider: process.env.CODEBUDDY_PROVIDER?.trim() || inferCostProvider(row.model),
+        }));
+        return this.sessionFacade.saveCurrentSession(this.historyManager.getChatHistory(), {
+            provider,
+            model,
+            inputTokens: sessionTokens.input,
+            outputTokens: sessionTokens.output,
+            totalCost: this.getSessionCost(),
+            turns,
+        });
+    }
+    getCurrentSessionId() {
+        return this.sessionStore.getCurrentSessionId();
+    }
     getClient() {
         return this.codebuddyClient;
     }
@@ -1179,6 +1550,9 @@ Look at the screenshot and find the element matching the user's intent. Output o
             this.abortController.abort();
         }
     }
+    requestManualCompaction() {
+        this.contextManager.requestManualCompaction();
+    }
     // Clear chat and reset
     clearChat() {
         super.clearChat();
@@ -1463,15 +1837,34 @@ Look at the screenshot and find the element matching the user's intent. Output o
     }
     /**
      * Record cost for current request
-     * @param inputTokens - Number of input tokens
-     * @param outputTokens - Number of output tokens
+     * @param inputTokens - Number of input tokens (local estimate)
+     * @param outputTokens - Number of output tokens (local estimate)
+     * @param providerUsage - Optional provider-reported usage (takes precedence over local estimates)
      */
-    recordSessionCost(inputTokens, outputTokens) {
+    recordSessionCost(inputTokens, outputTokens, providerUsage) {
         const model = this.codebuddyClient.getCurrentModel();
-        const cost = this.costTracker.calculateCost(inputTokens, outputTokens, model);
+        const cost = this.costTracker.calculateCost(inputTokens, outputTokens, model, 0, providerUsage);
         this.sessionCost += cost;
         this.routingFacade?.addSessionCost(cost);
-        this.costTracker.recordUsage(inputTokens, outputTokens, model);
+        // Record usage with effective tokens (provider if available, otherwise local estimate)
+        const effectiveInput = providerUsage?.promptTokens ?? inputTokens;
+        const effectiveOutput = providerUsage?.completionTokens ?? outputTokens;
+        this.costTracker.recordUsage(effectiveInput, effectiveOutput, model);
+        // Store provider usage for extended cost info retrieval
+        if (providerUsage) {
+            this.lastTurnProviderUsage = { ...providerUsage };
+        }
+        const activeRun = getActiveRunStore();
+        const runId = activeRun?.getCurrentRunId();
+        if (activeRun && runId) {
+            const report = this.costTracker.getReport();
+            activeRun.updateMetrics(runId, {
+                promptTokens: report.sessionTokens.input,
+                completionTokens: report.sessionTokens.output,
+                totalTokens: report.sessionTokens.input + report.sessionTokens.output,
+                totalCost: this.sessionCost,
+            });
+        }
         // Check budget alerts after recording cost
         if (this.sessionCostLimit !== Infinity) {
             this.budgetAlertManager.check(this.sessionCost, this.sessionCostLimit);
@@ -1675,12 +2068,13 @@ Look at the screenshot and find the element matching the user's intent. Output o
      * Clean up all resources
      * Should be called when the agent is no longer needed
      */
-    dispose() {
+    dispose(options = {}) {
         // Fire SessionEnd user hook (non-blocking). Shutdown errors should be
         // visible (warn, not debug) — silent debug logs masked prior bugs.
         getUserHooksManager(process.cwd()).executeHooks('SessionEnd', {}).catch((err) => logger.warn(`[user-hooks] SessionEnd error: ${err instanceof Error ? err.message : String(err)}`));
-        const skipAsyncSessionLearning = process.env.CODEBUDDY_HEADLESS === 'true' ||
+        const headlessProcess = process.env.CODEBUDDY_HEADLESS === 'true' ||
             process.env.CODEBUDDY_HEADLESS === '1';
+        const skipAsyncSessionLearning = options.skipSessionLearning === true || headlessProcess;
         if (!skipAsyncSessionLearning && isFeatureEnabled('USER_MODEL_DIALECTIC_ON_SESSION_END')) {
             const chatHistory = this.historyManager.getChatHistory();
             if (chatHistory && chatHistory.length > 0) {
@@ -1738,7 +2132,7 @@ Look at the screenshot and find the element matching the user's intent. Output o
         this.contextManager.stopPeriodicSnapshot?.();
         this.peerRoutingConfig = null;
         super.dispose();
-        if (skipAsyncSessionLearning) {
+        if (headlessProcess) {
             cleanupHeadlessSingletonWatchers();
         }
     }