@prestyj/cli 4.10.3 → 4.12.0

package/dist/core/agent-session.js

@@ -1,5 +1,5 @@
 import { agentLoop, isAbortError } from "@prestyj/agent";
-import { ProviderError } from "@prestyj/ai";
+import { ProviderError, prewarmAnthropicCache, } from "@prestyj/ai";
 import { EventBus } from "./event-bus.js";
 import { SlashCommandRegistry, createBuiltinCommands, } from "./slash-commands.js";
 import { PROMPT_COMMANDS, getPromptCommand } from "./prompt-commands.js";
@@ -16,10 +16,14 @@ import { discoverSkills } from "./skills.js";
 import { ensureAppDirs } from "../config.js";
 import { buildSystemPrompt } from "../system-prompt.js";
 import { createTools, createWebSearchTool, } from "../tools/index.js";
-import { MCPClientManager, getMCPServers, getAllMcpServers } from "./mcp/index.js";
+import { MCPClientManager, getAllMcpServers } from "./mcp/index.js";
 import { log } from "./logger.js";
 import { setEstimatorModel } from "./compaction/token-estimator.js";
 import { discoverAgents } from "./agents.js";
+import { generateSessionTitle } from "../utils/session-title.js";
+import { evaluateIdealReview, buildIdealReviewMessage, } from "./ideal-review.js";
+import { evaluateLoopBreak, buildLoopBreakMessage, toolCallSignature, detectTextRepetition, } from "./loop-breaker.js";
+import { buildRegroundingMessage } from "./regrounding.js";
 import crypto from "node:crypto";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -33,8 +37,44 @@ export class AgentSession {
     extensionLoader = new ExtensionLoader();
     messages = [];
     tools = [];
+    /** Rebuilds the read tool for a new model (video byte cap is baked in at
+     *  creation). Called from switchModel so video-capable models get the
+     *  read-tool's native-video path after a mid-session model change. */
+    rebuildReadTool;
     skills = [];
     cacheKeyLogged = false;
+    // ── Self-correction hook state (mirrors the TUI's useAgentLoop refs) ──
+    // Reset at the start of every run; observed from the event stream; read by
+    // the loop-break (mid-loop) and ideal-review (pre-stop) callbacks.
+    hookStats = {
+        changedLines: 0,
+        toolCalls: 0,
+        toolFailures: 0,
+        turns: 0,
+        writeCalls: 0,
+        editCalls: 0,
+        bashCalls: 0,
+    };
+    hookText = "";
+    hookConsecutiveFailures = 0;
+    hookMaxSignatureRepeats = 0;
+    hookMaxSameFileEdits = 0;
+    hookSignatureCounts = new Map();
+    hookFileEditCounts = new Map();
+    hookToolCalls = new Map();
+    idealReviewInjected = false;
+    loopBreakInjected = false;
+    regroundingInjected = false;
+    compactionOccurred = false;
+    originalRequest = "";
+    /** True after the cache has been pre-warmed for this session. Ensures we only
+     *  fire the warm-up call once (before the first real turn). */
+    cachePrewarmed = false;
+    // Messages queued by the user while a run is in flight. Drained at the
+    // mid-loop steering boundary (user steering wins over the hooks), mirroring
+    // the TUI's getSteeringMessages. Each entry carries its own attachments so a
+    // user can queue media (images/video/files) mid-run, not just plain text.
+    userQueue = [];
     processManager;
     lspManager;
     mcpManager;
@@ -45,6 +85,12 @@ export class AgentSession {
     maxTokens;
     thinkingLevel;
     customSystemPrompt;
+    /** Shared with the tool layer so plan-mode restrictions read live state. */
+    planModeRef = { current: false };
+    /** Path of the approved plan currently being implemented, or undefined. When
+     *  set, the system prompt carries the `[DONE:n]` progress contract so the
+     *  model emits step-completion markers the UI's plan-progress widget reads. */
+    approvedPlanPath;
     sessionId = "";
     sessionPath = "";
     lastPersistedIndex = 0;
@@ -57,10 +103,27 @@ export class AgentSession {
         this.model = options.model;
         this.cwd = options.cwd;
         this.baseUrl = options.baseUrl;
-        this.maxTokens = options.maxTokens ?? getModel(options.model)?.maxOutputTokens ?? 16384;
+        this.maxTokens = this.resolveMaxTokens(options.model);
         this.thinkingLevel = options.thinkingLevel;
         this.customSystemPrompt = options.systemPrompt;
     }
+    /**
+     * Derive the output-token cap for a model. Follows the active model's
+     * `maxOutputTokens` so a session booted on a large-output model (e.g. Kimi's
+     * 256K) doesn't carry that cap to a smaller one (e.g. Opus's 128K) after a
+     * model switch — that mismatch surfaces from the provider as
+     * `max_tokens: 262144 > 128000, which is the maximum allowed …`. An explicit
+     * `maxTokens` override is honored but clamped to the model's ceiling.
+     */
+    resolveMaxTokens(modelId) {
+        const modelInfo = getModel(modelId);
+        if (this.opts.maxTokens) {
+            return modelInfo
+                ? Math.min(this.opts.maxTokens, modelInfo.maxOutputTokens)
+                : this.opts.maxTokens;
+        }
+        return modelInfo?.maxOutputTokens ?? 16384;
+    }
     async initialize() {
         // Set model for accurate token estimation
         setEstimatorModel(this.model);
@@ -87,17 +150,30 @@ export class AgentSession {
             globalAgentsDir: paths.agentsDir,
             projectDir: this.cwd,
         });
-        const { tools, processManager, lspManager } = createTools(this.cwd, {
+        const { tools, processManager, rebuildReadTool, lspManager } = await createTools(this.cwd, {
             agents,
             skills: this.skills,
             provider: this.provider,
             model: this.model,
             lspDiagnostics: this.settingsManager.get("lspDiagnostics"),
-            // Lazy — sessionId isn't assigned yet when createTools() runs, so we
-            // must defer reading the cache key until the sub-agent actually fires.
+            authStorage: this.authStorage,
+            // Lazy — sessionId/model/provider can change after createTools() runs, so
+            // sub-agent spawns read the current parent state at execution time.
+            getProvider: () => this.provider,
+            getModel: () => this.model,
             getCacheKey: () => this.getPromptCacheKey(),
+            // Plan mode: only wired when the host supplies callbacks. The ref is
+            // shared so bash/edit/write enforce read-only restrictions live.
+            ...(this.opts.onEnterPlan || this.opts.onExitPlan
+                ? {
+                    planModeRef: this.planModeRef,
+                    onEnterPlan: this.opts.onEnterPlan,
+                    onExitPlan: this.opts.onExitPlan,
+                }
+                : {}),
         });
         this.tools = tools;
+        this.rebuildReadTool = rebuildReadTool;
         this.processManager = processManager;
         this.lspManager = lspManager;
         // Connect MCP servers (non-blocking — failures are logged and skipped).
@@ -108,23 +184,20 @@ export class AgentSession {
         // skip user servers: a single `/expand` fans out 5 parallel subagents, and
         // cold-spawning every user MCP server (e.g. npx-based remotes) per
         // short-lived child would be slow and could hammer rate-limited endpoints.
+        //
+        // The connect attempt itself can block for up to the per-server connect
+        // timeout (~30s) — a slow stdio server such as a first-run
+        // `npx -y @playwright/mcp` download stalls here. When the host gates its own
+        // readiness on initialize() (the ezcoder-app sidecar can't emit its
+        // listening handshake until this resolves), `backgroundMcpConnect` moves the
+        // connect off the critical path so the session becomes usable immediately
+        // and tools are appended whenever the servers come up.
         this.mcpManager = new MCPClientManager();
-        try {
-            let apiKey;
-            if (this.provider === "glm") {
-                try {
-                    const glmCreds = await this.authStorage.resolveCredentials("glm");
-                    apiKey = glmCreds.accessToken;
-                }
-                catch {
-                    // GLM not configured — skip Z.AI MCP servers
-                }
-            }
-            const mcpTools = await this.mcpManager.connectAll(getMCPServers(this.provider, apiKey));
-            this.tools.push(...mcpTools);
+        if (this.opts.backgroundMcpConnect) {
+            void this.connectMcpServers();
         }
-        catch (err) {
-            log("WARN", "mcp", `MCP initialization failed: ${err instanceof Error ? err.message : String(err)}`);
+        else {
+            await this.connectMcpServers();
         }
         const basePrompt = this.customSystemPrompt ??
             (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider));
@@ -194,6 +267,47 @@ export class AgentSession {
         await this.extensionLoader.loadAll(paths.extensionsDir, extContext);
         this.eventBus.emit("session_start", { sessionId: this.sessionId });
     }
+    /**
+     * Connect all configured MCP servers and append their tools to `this.tools`.
+     * Resolves the GLM api key first (Z.AI's bundled servers need it). Never
+     * throws — a failed connect is logged and skipped — so it is safe to either
+     * `await` (CLI: tools ready before the first turn) or fire-and-forget
+     * (sidecar: `backgroundMcpConnect`, so a slow stdio server can't stall
+     * startup). Tools are pushed onto the live array the agent loop reads each
+     * turn, so background-connected servers become available on the next prompt.
+     */
+    async connectMcpServers() {
+        if (!this.mcpManager)
+            return;
+        try {
+            let apiKey;
+            if (this.provider === "glm") {
+                try {
+                    const glmCreds = await this.authStorage.resolveCredentials("glm");
+                    apiKey = glmCreds.accessToken;
+                }
+                catch {
+                    // GLM not configured — skip Z.AI MCP servers
+                }
+            }
+            const mcpTools = await this.mcpManager.connectAll(await getAllMcpServers(this.provider, apiKey, this.cwd));
+            this.tools.push(...mcpTools);
+            // Background connect resolves AFTER initialize() has already built the
+            // system prompt (the default path awaits this before buildSystemPrompt,
+            // so its prompt already lists the tools). Refresh messages[0] so the
+            // model is also told about the MCP tools by name on its next turn —
+            // mirrors the TUI's replaceSystemPrompt after connectInitialMcpTools.
+            // Safe ordering: this method's first await yields before initialize()
+            // sets `messages`, and connectAll (process spawn / network) always
+            // resolves long after the local-only remainder of init has finished.
+            if (this.opts.backgroundMcpConnect && mcpTools.length > 0) {
+                await this.rebuildSystemPromptInPlace();
+            }
+        }
+        catch (err) {
+            log("WARN", "mcp", `MCP initialization failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
     /**
      * Process user input. Handles slash commands or runs agent loop.
      */
@@ -235,6 +349,225 @@ export class AgentSession {
         this.lastPersistedIndex = this.messages.length;
         await this.runLoop();
     }
+    /**
+     * Prompt with multimodal attachments (images / videos) alongside optional
+     * text. Images and videos become native content blocks the model can see;
+     * non-media files are surfaced as a text note with their saved path so the
+     * agent can open them with its tools. Slash-command parsing is skipped —
+     * attachments are always a direct conversational turn.
+     */
+    async promptWithAttachments(text, attachments) {
+        const parts = this.buildAttachmentParts(text, attachments);
+        if (parts.length === 0)
+            return;
+        const userMessage = { role: "user", content: parts };
+        this.messages.push(userMessage);
+        await this.persistMessage(userMessage);
+        this.lastPersistedIndex = this.messages.length;
+        await this.runLoop();
+    }
+    /**
+     * Build the native content blocks (text + image/video notes + file notes) for
+     * a user message with attachments. Shared by {@link promptWithAttachments} and
+     * the mid-run steering drain so queued media is delivered identically.
+     */
+    buildAttachmentParts(text, attachments) {
+        const parts = [];
+        const fileNotes = [];
+        const modelSupportsVideo = getModel(this.model)?.supportsVideo ?? false;
+        for (const a of attachments) {
+            if (a.kind === "image") {
+                parts.push({ type: "image", mediaType: a.mediaType, data: a.data });
+                if (a.path) {
+                    parts.push({ type: "text", text: `[Image saved at ${a.path}]` });
+                }
+            }
+            else if (a.kind === "video") {
+                // Mirror the CLI's buildUserContentWithAttachments: never send inline
+                // VideoContent in the user message. Video-capable models (Kimi/Gemini/
+                // MiniMax) watch video via the read tool, which auto-compresses to the
+                // model's byte cap and delivers it in the provider's required shape.
+                // Non-video models get a plain note so they know to use ffmpeg. The file
+                // was already saved to disk by prepareAttachments in the sidecar.
+                if (modelSupportsVideo && a.path) {
+                    parts.push({
+                        type: "text",
+                        text: `The user attached a video at ${a.path}. You CAN watch it: call the read tool ` +
+                            `on this exact path now, then answer based on what you see. Do not say you ` +
+                            `cannot watch video — reading the file lets you analyze it.`,
+                    });
+                }
+                else if (a.path) {
+                    parts.push({
+                        type: "text",
+                        text: `[User attached a video file at ${a.path}. You cannot watch video directly; ` +
+                            `if needed, use ffmpeg to extract frames or audio.]`,
+                    });
+                }
+                else {
+                    parts.push({
+                        type: "text",
+                        text: `[User attached a video file but it could not be saved for analysis.]`,
+                    });
+                }
+            }
+            else if (a.path) {
+                fileNotes.push(`- ${a.name} (saved at ${a.path})`);
+            }
+        }
+        const textParts = [];
+        if (text.trim())
+            textParts.push(text.trim());
+        if (fileNotes.length > 0) {
+            textParts.push(`Attached files (inspect with your tools):\n${fileNotes.join("\n")}`);
+        }
+        if (textParts.length > 0)
+            parts.unshift({ type: "text", text: textParts.join("\n\n") });
+        return parts;
+    }
+    /**
+     * Reset per-run self-correction hook state. Mirrors the TUI's run_start
+     * resets so each run evaluates the hooks from a clean slate. `originalRequest`
+     * is the verbatim user ask, pinned for post-compaction re-grounding.
+     */
+    resetHookState(originalRequest) {
+        this.hookStats = {
+            changedLines: 0,
+            toolCalls: 0,
+            toolFailures: 0,
+            turns: 0,
+            writeCalls: 0,
+            editCalls: 0,
+            bashCalls: 0,
+        };
+        this.hookText = "";
+        this.hookConsecutiveFailures = 0;
+        this.hookMaxSignatureRepeats = 0;
+        this.hookMaxSameFileEdits = 0;
+        this.hookSignatureCounts.clear();
+        this.hookFileEditCounts.clear();
+        this.hookToolCalls.clear();
+        this.idealReviewInjected = false;
+        this.loopBreakInjected = false;
+        this.regroundingInjected = false;
+        this.compactionOccurred = false;
+        this.originalRequest = originalRequest;
+    }
+    /**
+     * Fold one agent event into the hook stat accumulators. Pure bookkeeping —
+     * the same signals the TUI's useAgentLoop collects, so the loop-break and
+     * ideal-review decisions match across the CLI and the app.
+     */
+    trackHookEvent(event) {
+        switch (event.type) {
+            case "text_delta":
+                this.hookText += event.text;
+                break;
+            case "tool_call_start":
+                this.hookToolCalls.set(event.toolCallId, { name: event.name, args: event.args ?? {} });
+                break;
+            case "tool_call_end": {
+                const call = this.hookToolCalls.get(event.toolCallId);
+                const name = call?.name ?? "";
+                const args = call?.args;
+                this.hookStats.toolCalls += 1;
+                if (event.isError)
+                    this.hookStats.toolFailures += 1;
+                if (name === "write")
+                    this.hookStats.writeCalls += 1;
+                if (name === "edit")
+                    this.hookStats.editCalls += 1;
+                if (name === "bash")
+                    this.hookStats.bashCalls += 1;
+                this.hookConsecutiveFailures = event.isError ? this.hookConsecutiveFailures + 1 : 0;
+                const sig = toolCallSignature(name, args);
+                const sigNext = (this.hookSignatureCounts.get(sig) ?? 0) + 1;
+                this.hookSignatureCounts.set(sig, sigNext);
+                if (sigNext > this.hookMaxSignatureRepeats)
+                    this.hookMaxSignatureRepeats = sigNext;
+                if ((name === "edit" || name === "write") && args) {
+                    const filePath = args.file_path;
+                    if (typeof filePath === "string") {
+                        const fileNext = (this.hookFileEditCounts.get(filePath) ?? 0) + 1;
+                        this.hookFileEditCounts.set(filePath, fileNext);
+                        if (fileNext > this.hookMaxSameFileEdits)
+                            this.hookMaxSameFileEdits = fileNext;
+                    }
+                }
+                if (name === "edit" && !event.isError) {
+                    const diff = event.details?.diff ?? event.result;
+                    const added = (diff.match(/^\+[^+]/gm) ?? []).length;
+                    const removed = (diff.match(/^-[^-]/gm) ?? []).length;
+                    this.hookStats.changedLines += added + removed;
+                }
+                break;
+            }
+            case "turn_end":
+                this.hookStats.turns = event.turn;
+                break;
+        }
+    }
+    /**
+     * Mid-loop steering hook: fires the loop-breaker when the agent looks stuck,
+     * then post-compaction re-grounding. At most one of each per run. Mirrors the
+     * TUI's getSteeringMessages ordering (minus user steering, which the app
+     * delivers as normal prompts).
+     */
+    getHookSteeringMessages() {
+        // User steering wins: drain any messages queued during this run first so the
+        // agent sees them mid-loop instead of after it stops.
+        if (this.userQueue.length > 0) {
+            const queued = this.userQueue.splice(0);
+            // Plain-text-only queue: keep the simple merged-string message.
+            if (queued.every((m) => m.attachments.length === 0)) {
+                const merged = queued.map((m) => m.text).join("\n\n");
+                return [{ role: "user", content: merged }];
+            }
+            // Any queued attachments → deliver one user message with text + media
+            // blocks built the same way as a non-queued attachment prompt.
+            const parts = [];
+            for (const m of queued)
+                parts.push(...this.buildAttachmentParts(m.text, m.attachments));
+            return [{ role: "user", content: parts }];
+        }
+        if (!this.settingsManager.get("idealReviewEnabled"))
+            return null;
+        if (!this.loopBreakInjected) {
+            const decision = evaluateLoopBreak({
+                consecutiveFailures: this.hookConsecutiveFailures,
+                maxSignatureRepeats: this.hookMaxSignatureRepeats,
+                maxSameFileEdits: this.hookMaxSameFileEdits,
+                textRepetitionDetected: detectTextRepetition(this.hookText),
+            });
+            if (decision.shouldBreak) {
+                this.loopBreakInjected = true;
+                this.eventBus.emit("hook", { kind: "loop_break" });
+                return [buildLoopBreakMessage(decision.reasons)];
+            }
+        }
+        if (!this.regroundingInjected && this.compactionOccurred) {
+            this.regroundingInjected = true;
+            this.eventBus.emit("hook", { kind: "regrounding" });
+            return [buildRegroundingMessage(this.originalRequest)];
+        }
+        return null;
+    }
+    /**
+     * Pre-stop follow-up hook: runs the ideal review once, when the agent would
+     * otherwise finish and the change set is substantial enough to warrant it.
+     */
+    getHookFollowUpMessages() {
+        if (!this.settingsManager.get("idealReviewEnabled"))
+            return null;
+        if (this.idealReviewInjected)
+            return null;
+        const decision = evaluateIdealReview(this.hookStats);
+        if (!decision.shouldReview)
+            return null;
+        this.idealReviewInjected = true;
+        this.eventBus.emit("hook", { kind: "ideal" });
+        return [buildIdealReviewMessage(decision.reasons)];
+    }
     /** Auto-compact if needed, run agent loop with auth retry, and persist messages. */
     async runLoop() {
         // One-shot cache-key marker per session so turn_end cacheRead numbers
@@ -249,6 +582,11 @@ export class AgentSession {
                 transient: String(!!this.opts.transient),
             });
         }
+        // Reset self-correction hook state for this run; pin the latest user message
+        // as the verbatim original request for post-compaction re-grounding.
+        const lastUser = [...this.messages].reverse().find((m) => m.role === "user");
+        const originalRequest = typeof lastUser?.content === "string" ? lastUser.content : "";
+        this.resetHookState(originalRequest);
         // Resolve OAuth credentials and run agent loop.
         // On 401, force-refresh the token and retry once — the provider may have
         // revoked the token server-side before the stored expiry (e.g. after a restart).
@@ -264,6 +602,8 @@ export class AgentSession {
             const threshold = this.settingsManager.get("compactThreshold");
             if (shouldCompact(this.messages, contextWindow, threshold)) {
                 await this.compact(creds);
+                // Re-grounding hook keys off this — the context was just summarized.
+                this.compactionOccurred = true;
             }
         }
         const userAgent = this.provider === "anthropic" ? await getClaudeCliUserAgent() : undefined;
@@ -288,7 +628,9 @@ export class AgentSession {
                 defaultHeaders: this.provider === "moonshot" && isKimiCodingEndpoint(effectiveBaseUrl)
                     ? kimiCodingHeaders()
                     : undefined,
-                cacheRetention: "short",
+                // speedProfile "optimized": 1-h cache TTL (survives turns >5 min apart)
+                // + pre-warm before the first turn. "baseline": current 5-min default.
+                cacheRetention: this.isSpeedOptimized() ? "long" : "short",
                 promptCacheKey: this.getPromptCacheKey(),
                 supportsImages: modelInfo?.supportsImages,
                 supportsVideo: modelInfo?.supportsVideo,
@@ -296,12 +638,22 @@ export class AgentSession {
                 // clearToolUses disabled — causes model to output unsolicited context summaries
                 // Single tool result shouldn't exceed 30% of context window (in chars)
                 maxToolResultChars: Math.floor(getContextWindow(this.model, { provider: this.provider, accountId }) * 3.5 * 0.3),
+                // Self-correction hooks (same as the TUI): loop-break + re-grounding are
+                // polled mid-loop; the ideal review is polled when the agent would stop.
+                getSteeringMessages: () => this.getHookSteeringMessages(),
+                getFollowUpMessages: () => this.getHookFollowUpMessages(),
             });
             for await (const event of generator) {
+                this.trackHookEvent(event);
                 this.eventBus.forwardAgentEvent(event);
             }
         };
         try {
+            // Fire cache pre-warm before the first turn (Anthropic + speedProfile optimized).
+            // Runs concurrently with nothing — it must complete before runAgentLoop so
+            // the cache is warm when the real request arrives. Best-effort: swallowed
+            // inside maybePrewarmCache/prewarmAnthropicCache.
+            await this.maybePrewarmCache(creds);
             await runAgentLoop(creds.accessToken, creds.accountId, creds.projectId);
         }
         catch (err) {
@@ -341,7 +693,25 @@ export class AgentSession {
             this.provider = provider;
         this.model = model;
         setEstimatorModel(model);
-        this.eventBus.emit("model_change", { provider: this.provider, model: this.model });
+        // maxTokens must follow the active model — it was frozen at the boot
+        // model's `maxOutputTokens` in the constructor, so without this a session
+        // booted on e.g. Kimi (256K) keeps sending that cap after switching to a
+        // smaller model (Opus 128K), which the provider rejects.
+        this.maxTokens = this.resolveMaxTokens(model);
+        this.eventBus.emit("model_change", {
+            provider: this.provider,
+            model: this.model,
+            supportsVideo: getModel(this.model)?.supportsVideo ?? false,
+        });
+        // Rebuild the read tool for the new model's video byte cap. The tool's
+        // video capability (description + native-video execute path) is baked in
+        // at creation from the model's maxVideoBytes, so switching to/from a
+        // video-capable model mid-session needs a fresh tool object — mirrors
+        // the TUI's rebuildReadTool call on model switch.
+        if (this.rebuildReadTool) {
+            const newReadTool = this.rebuildReadTool(model);
+            this.tools = this.tools.map((t) => (t.name === "read" ? newReadTool : t));
+        }
         // Update provider-specific tools when provider changes
         if (provider && provider !== prevProvider) {
             // Add/remove client-side web_search tool based on provider.
@@ -425,6 +795,9 @@ export class AgentSession {
         });
     }
     async newSession() {
+        // A fresh session drops any in-flight plan state so its prompt is clean.
+        this.planModeRef.current = false;
+        this.approvedPlanPath = undefined;
         const basePrompt = this.customSystemPrompt ??
             (await buildSystemPrompt(this.cwd, this.skills, false, undefined, this.tools.map((tool) => tool.name), undefined, this.provider));
         this.messages = [{ role: "system", content: basePrompt }];
@@ -485,15 +858,163 @@ export class AgentSession {
             sessionId: this.sessionId,
             sessionPath: this.sessionPath,
             messageCount: this.messages.length,
+            planMode: this.planModeRef.current,
         };
     }
+    getPlanMode() {
+        return this.planModeRef.current;
+    }
+    /** Queue a user message (optionally with attachments) to be injected mid-run
+     *  as steering. Returns the new queue length. No-op semantics are the caller's
+     *  concern. */
+    queueMessage(text, attachments = []) {
+        this.userQueue.push({ text, attachments });
+        return this.userQueue.length;
+    }
+    /** Number of messages currently queued. */
+    getQueuedCount() {
+        return this.userQueue.length;
+    }
+    /** Clear the queue, returning the combined text (to restore to the composer).
+     *  Queued attachments are dropped on cancel — the composer only restores text. */
+    drainQueue() {
+        return this.userQueue
+            .splice(0)
+            .map((m) => m.text)
+            .join("\n\n");
+    }
+    /** Snapshot of background processes (bash run_in_background), newest-state. */
+    listBackgroundProcesses() {
+        return this.processManager?.list() ?? [];
+    }
+    /** Stop a background process by id. Returns a human-readable status string. */
+    async killBackgroundProcess(id) {
+        if (!this.processManager)
+            return `No background process with id "${id}"`;
+        return this.processManager.stop(id);
+    }
+    /**
+     * Toggle plan mode: flips the shared ref (so tools enforce read-only
+     * restrictions) and rebuilds the system prompt in place so the model is told
+     * about the mode change on its next turn. No-op when a custom system prompt
+     * is in force (the host owns the prompt then).
+     */
+    async setPlanMode(active) {
+        this.planModeRef.current = active;
+        // Entering plan mode discards any prior approved-plan contract (a new plan
+        // is about to be drafted); exiting keeps it (set explicitly via accept).
+        if (active)
+            this.approvedPlanPath = undefined;
+        await this.rebuildSystemPromptInPlace();
+    }
+    /**
+     * Bake an approved plan into the system prompt so the model is told to emit
+     * `[DONE:n]` markers as it completes each step (the contract the UI's
+     * plan-progress widget reads). Pass `undefined` to clear it. No-op when a
+     * custom system prompt is in force (the host owns the prompt then).
+     */
+    async setApprovedPlan(approvedPlanPath) {
+        this.approvedPlanPath = approvedPlanPath;
+        await this.rebuildSystemPromptInPlace();
+    }
+    /** Rebuild messages[0] from current plan-mode + approved-plan state. */
+    async rebuildSystemPromptInPlace() {
+        if (this.customSystemPrompt)
+            return;
+        const rebuilt = await buildSystemPrompt(this.cwd, this.skills, this.planModeRef.current, this.approvedPlanPath, this.tools.map((tool) => tool.name), undefined, this.provider);
+        if (this.messages[0]?.role === "system") {
+            this.messages[0] = { role: "system", content: rebuilt };
+        }
+        else {
+            this.messages.unshift({ role: "system", content: rebuilt });
+        }
+    }
     getMessages() {
         return this.messages;
     }
+    /**
+     * Generate a short LLM session title from the conversation so far (first user
+     * message + first assistant reply). Best-effort; returns null on failure or
+     * when there's no user message yet. Uses the cheapest model for the provider.
+     */
+    async generateTitle() {
+        const extractText = (content) => typeof content === "string"
+            ? content
+            : content
+                .map((c) => c.type === "text" && "text" in c && typeof c.text === "string" ? c.text : "")
+                .join(" ");
+        const userMsg = this.messages.find((m) => m.role === "user");
+        const assistantMsg = this.messages.find((m) => m.role === "assistant");
+        const userText = userMsg ? extractText(userMsg.content) : "";
+        if (!userText.trim())
+            return null;
+        try {
+            const creds = await this.authStorage.resolveCredentials(this.provider);
+            const title = await generateSessionTitle({
+                provider: this.provider,
+                userMessage: userText,
+                assistantPreview: assistantMsg ? extractText(assistantMsg.content).slice(0, 200) : "",
+                apiKey: creds.accessToken,
+                baseUrl: this.baseUrl ?? creds.baseUrl,
+                accountId: creds.accountId,
+            });
+            return title || null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Current reasoning/thinking level, or undefined when thinking is off. */
+    getThinkingLevel() {
+        return this.thinkingLevel;
+    }
+    /** Set the reasoning/thinking level (undefined turns thinking off). Takes
+     * effect on the next prompt, since the in-flight loop reads it at start. */
+    setThinkingLevel(level) {
+        this.thinkingLevel = level;
+    }
     /** Replace the abort signal (e.g. after cancellation). */
     setSignal(signal) {
         this.opts = { ...this.opts, signal };
     }
+    /** True when speedProfile is "optimized" (1-h cache TTL + pre-warm). */
+    isSpeedOptimized() {
+        return this.settingsManager?.get("speedProfile") === "optimized";
+    }
+    /** Fire a cache pre-warm request for Anthropic so the first real turn is a
+     *  cache read instead of a cold write. No-op for other providers and when
+     *  speedProfile is not "optimized". Entirely best-effort — any failure is
+     *  swallowed so prewarm never blocks or aborts the real prompt. */
+    async maybePrewarmCache(creds) {
+        if (this.cachePrewarmed || !this.isSpeedOptimized() || this.provider !== "anthropic") {
+            return;
+        }
+        this.cachePrewarmed = true;
+        try {
+            const userAgent = await getClaudeCliUserAgent();
+            const systemText = typeof this.messages[0]?.content === "string" ? this.messages[0].content : "";
+            if (!systemText)
+                return;
+            await prewarmAnthropicCache({
+                apiKey: creds.accessToken,
+                model: this.model,
+                system: systemText,
+                tools: this.tools.map((t) => ({
+                    name: t.name,
+                    description: t.description,
+                    parameters: t.parameters,
+                    ...(t.rawInputSchema ? { rawInputSchema: t.rawInputSchema } : {}),
+                })),
+                baseUrl: this.baseUrl ?? creds.baseUrl,
+                userAgent,
+                cacheRetention: "long",
+                signal: this.opts.signal,
+            });
+        }
+        catch {
+            // Best-effort — prewarm failure must never block the session.
+        }
+    }
     getPromptCacheKey() {
         if (this.opts.promptCacheKey)
             return this.opts.promptCacheKey;