helixmind 0.1.2 → 0.2.0

package/dist/cli/commands/chat.js

@@ -10,6 +10,7 @@ import { renderError, renderInfo, renderSpiralStatus, renderUserMessage, } from
 import { isInsideToolBlock } from '../ui/tool-output.js';
 import { renderFeedProgress, renderFeedSummary } from '../ui/progress.js';
 import { ActivityIndicator } from '../ui/activity.js';
+import { BottomChrome } from '../ui/bottom-chrome.js';
 import { theme } from '../ui/theme.js';
 import { detectFeedIntent } from '../feed/intent.js';
 import { runFeedPipeline } from '../feed/pipeline.js';
@@ -32,6 +33,8 @@ import { getSuggestions, writeSuggestions, clearSuggestions } from '../ui/comman
 import { selectMenu } from '../ui/select-menu.js';
 import { BugJournal } from '../bugs/journal.js';
 import { detectBugReport } from '../bugs/detector.js';
+import { BrowserController } from '../browser/controller.js';
+import { VisionProcessor } from '../browser/vision.js';
 import { classifyTask } from '../validation/classifier.js';
 import { generateCriteria } from '../validation/criteria.js';
 import { validationLoop } from '../validation/autofix.js';
@@ -100,6 +103,13 @@ const HELP_CATEGORIES = [
             { cmd: '/bugfix', label: '/bugfix', description: 'Review & fix all open bugs' },
         ],
     },
+    {
+        category: 'Browser', color: '#ff8800',
+        items: [
+            { cmd: '/browser', label: '/browser [url]', description: 'Open browser (optional URL)' },
+            { cmd: '/browser close', label: '/browser close', description: 'Close the browser' },
+        ],
+    },
     {
         category: 'Code & Git', color: '#8a2be2',
         items: [
@@ -260,14 +270,21 @@ export async function chatCommand(options) {
     const sessionBuffer = new SessionBuffer();
     // Bug journal (persistent bug tracking)
     const bugJournal = new BugJournal(process.cwd());
-    // Activity indicator (replaces spinner)
-    const activity = new ActivityIndicator();
+    // Browser controller (lazy — instantiated on /browser or agent tool use)
+    let browserController;
+    let visionProcessor;
+    // Bottom chrome (3 fixed rows at terminal bottom: separator, hints, statusbar)
+    const chrome = new BottomChrome();
+    // Activity indicator (renders on chrome row 0 during agent work)
+    const activity = new ActivityIndicator(chrome);
     // Agent controller for pause/resume
     const agentController = new AgentController();
     let agentRunning = false;
     let autonomousMode = false;
     // Forward-declared findings handler (reassigned by control protocol if active)
     let pushFindingsToBrainFn = null;
+    // Forward-declared browser screenshot handler (reassigned when brain server is active)
+    let pushScreenshotToBrainFn = null;
     // Session Manager — manages background sessions (security, auto, etc.)
     const sessionMgr = new SessionManager({
         flags: {
@@ -340,7 +357,7 @@ export async function chatCommand(options) {
     });
     // Single message mode
     if (options.message) {
-        await sendAgentMessage(options.message, agentHistory, provider, project, spiralEngine, config, permissions, undoStack, checkpointStore, agentController, activity, sessionBuffer, (inp, out) => { sessionTokensInput += inp; sessionTokensOutput += out; }, () => { sessionToolCalls++; }, undefined, { enabled: validationEnabled, verbose: validationVerbose, strict: validationStrict }, bugJournal);
+        await sendAgentMessage(options.message, agentHistory, provider, project, spiralEngine, config, permissions, undoStack, checkpointStore, agentController, activity, sessionBuffer, (inp, out) => { sessionTokensInput += inp; sessionTokensOutput += out; }, () => { sessionToolCalls++; }, undefined, { enabled: validationEnabled, verbose: validationVerbose, strict: validationStrict }, bugJournal, browserController, visionProcessor, pushScreenshotToBrainFn);
         spiralEngine?.close();
         return;
     }
@@ -380,7 +397,7 @@ export async function chatCommand(options) {
     // === Register CLI ↔ Web control protocol ===
     if (brainUrl) {
         try {
-            const { registerControlHandlers, setInstanceMeta, getBrainToken, pushSessionCreated, pushSessionUpdate, pushSessionRemoved, pushOutputLine, startRelayClient, } = await import('../brain/generator.js');
+            const { registerControlHandlers, setInstanceMeta, getBrainToken, pushSessionCreated, pushSessionUpdate, pushSessionRemoved, pushOutputLine, pushBugCreated, pushBugUpdated, pushBrowserScreenshot, pushControlEvent, startRelayClient, } = await import('../brain/generator.js');
             const { serializeSession, buildInstanceMeta, resetInstanceStartTime } = await import('../brain/control-protocol.js');
             resetInstanceStartTime();
             // Collected findings for getFindings() handler
@@ -484,12 +501,84 @@ export async function chatCommand(options) {
                     pushSessionUpdate(serializeSession(session));
                     return true;
                 },
-                sendChat: (text) => {
-                    // Queue chat text to be processed as if the user typed it
-                    typeAheadBuffer.push(text);
+                sendChat: (text, chatId, mode) => {
+                    const effectiveChatId = chatId || `web-${Date.now()}`;
+                    // Import web chat handler and run asynchronously
+                    import('../brain/web-chat-handler.js').then(({ handleWebChat }) => {
+                        handleWebChat(text, effectiveChatId, {
+                            provider,
+                            spiralEngine,
+                            project,
+                            config,
+                            checkpointStore,
+                            bugJournal,
+                        }, {
+                            onStarted: (cid) => {
+                                pushControlEvent({ type: 'chat_started', chatId: cid, timestamp: Date.now() });
+                            },
+                            onTextChunk: (cid, chunk) => {
+                                pushControlEvent({ type: 'chat_text_chunk', chatId: cid, text: chunk, timestamp: Date.now() });
+                            },
+                            onToolStart: (cid, stepNum, toolName, toolInput) => {
+                                pushControlEvent({ type: 'chat_tool_start', chatId: cid, stepNum, toolName, toolInput, timestamp: Date.now() });
+                            },
+                            onToolEnd: (cid, stepNum, toolName, status, result) => {
+                                pushControlEvent({ type: 'chat_tool_end', chatId: cid, stepNum, toolName, status, result, timestamp: Date.now() });
+                            },
+                            onComplete: (cid, fullText, steps, tokensUsed) => {
+                                pushControlEvent({ type: 'chat_complete', chatId: cid, text: fullText, steps, tokensUsed, timestamp: Date.now() });
+                            },
+                            onError: (cid, error) => {
+                                pushControlEvent({ type: 'chat_error', chatId: cid, error, timestamp: Date.now() });
+                            },
+                        }).catch((err) => {
+                            pushControlEvent({ type: 'chat_error', chatId: effectiveChatId, error: err?.message || 'Unknown error', timestamp: Date.now() });
+                        });
+                    }).catch(() => { });
                 },
                 getFindings: () => [...collectedFindings],
+                getBugs: () => bugJournal.getAllBugs().map(b => ({
+                    id: b.id,
+                    description: b.description,
+                    file: b.file,
+                    line: b.line,
+                    status: b.status,
+                    createdAt: b.createdAt,
+                    updatedAt: b.updatedAt,
+                    fixedAt: b.fixedAt,
+                    fixDescription: b.fixDescription,
+                })),
+            });
+            // Wire bug journal change events to brain server
+            bugJournal.setOnChange((event, bug) => {
+                const bugInfo = {
+                    id: bug.id,
+                    description: bug.description,
+                    file: bug.file,
+                    line: bug.line,
+                    status: bug.status,
+                    createdAt: bug.createdAt,
+                    updatedAt: bug.updatedAt,
+                    fixedAt: bug.fixedAt,
+                    fixDescription: bug.fixDescription,
+                };
+                if (event === 'bug_created') {
+                    pushBugCreated(bugInfo);
+                }
+                else {
+                    pushBugUpdated(bugInfo);
+                }
             });
+            // Wire browser screenshots to brain server
+            pushScreenshotToBrainFn = (info) => {
+                pushBrowserScreenshot({
+                    url: info.url,
+                    title: info.title,
+                    timestamp: Date.now(),
+                    imageBase64: info.imageBase64,
+                    analysis: info.analysis,
+                });
+            };
             // Override forward-reference to also collect findings for control protocol
             pushFindingsToBrainFn = (session) => {
                 pushFindingsToBrain(session);
@@ -533,8 +622,29 @@ export async function chatCommand(options) {
                     startAuto: (goal) => { /* relay delegates to local handlers — already registered */ return ''; },
                     startSecurity: () => '',
                     abortSession: (id) => { sessionMgr.abort(id); return true; },
-                    sendChat: (text) => { typeAheadBuffer.push(text); },
+                    sendChat: (text, chatId, mode) => {
+                        const effectiveChatId = chatId || `relay-${Date.now()}`;
+                        import('../brain/web-chat-handler.js').then(({ handleWebChat }) => {
+                            handleWebChat(text, effectiveChatId, {
+                                provider, spiralEngine, project, config, checkpointStore, bugJournal,
+                            }, {
+                                onStarted: (cid) => { pushControlEvent({ type: 'chat_started', chatId: cid, timestamp: Date.now() }); },
+                                onTextChunk: (cid, chunk) => { pushControlEvent({ type: 'chat_text_chunk', chatId: cid, text: chunk, timestamp: Date.now() }); },
+                                onToolStart: (cid, sn, tn, ti) => { pushControlEvent({ type: 'chat_tool_start', chatId: cid, stepNum: sn, toolName: tn, toolInput: ti, timestamp: Date.now() }); },
+                                onToolEnd: (cid, sn, tn, st, r) => { pushControlEvent({ type: 'chat_tool_end', chatId: cid, stepNum: sn, toolName: tn, status: st, result: r, timestamp: Date.now() }); },
+                                onComplete: (cid, ft, s, tu) => { pushControlEvent({ type: 'chat_complete', chatId: cid, text: ft, steps: s, tokensUsed: tu, timestamp: Date.now() }); },
+                                onError: (cid, e) => { pushControlEvent({ type: 'chat_error', chatId: cid, error: e, timestamp: Date.now() }); },
+                            }).catch((err) => {
+                                pushControlEvent({ type: 'chat_error', chatId: effectiveChatId, error: err?.message || 'Unknown error', timestamp: Date.now() });
+                            });
+                        }).catch(() => { });
+                    },
                     getFindings: () => [...collectedFindings],
+                    getBugs: () => bugJournal.getAllBugs().map(b => ({
+                        id: b.id, description: b.description, file: b.file, line: b.line,
+                        status: b.status, createdAt: b.createdAt, updatedAt: b.updatedAt,
+                        fixedAt: b.fixedAt, fixDescription: b.fixDescription,
+                    })),
                 }, updateMeta).catch(() => { });
             }
         }
@@ -570,36 +680,64 @@ export async function chatCommand(options) {
         const escaped = gt.replace(/(\x1b\[[0-9;]*m)/g, `${ansiStart}$1${ansiEnd}`);
         return `${escaped} `;
     }
-    /**
-     * Show the full prompt area:
-     *   ──────────────────
-     *   ▸▸ safe permissions · esc = stop · /help
-     *   🌀 L1:... | tokens | model | git
-     *   > _                    ← cursor here (last line)
-     *
-     * Info is written ABOVE the prompt as normal scrolling text.
-     * The prompt is always the last line — no ANSI cursor tricks needed.
-     */
-    function showPrompt() {
-        const w = Math.max(20, (process.stdout.columns || 80) - 2);
-        const sep = chalk.hex('#00d4ff').dim('\u2500'.repeat(w));
+    /** Build separator content for chrome row 0 */
+    function buildSeparator(w) {
+        return chalk.hex('#00d4ff').dim('\u2500'.repeat(w));
+    }
+    /** Build hint line content for chrome row 1 */
+    function buildHintLine() {
         const data = getStatusBarData();
-        const bar = renderStatusBar(data, w);
-        // Build hint line
         const hints = [];
         if (data.permissionMode === 'yolo')
             hints.push(chalk.red('\u25B8\u25B8 yolo mode'));
         else if (data.permissionMode === 'skip')
-            hints.push(chalk.yellow('\u25B8\u25B8 skip permissions'));
+            hints.push(chalk.yellow('\u25B8\u25B8 bypass permissions'));
         else
             hints.push(chalk.green('\u25B8\u25B8 safe permissions'));
-        hints.push(chalk.dim('esc = stop'));
-        hints.push(chalk.dim('/help'));
-        const hintLine = hints.join(chalk.dim(' \u00B7 '));
-        // Write info above the prompt, then the prompt as the last line
+        hints.push(chalk.dim('shift+tab to cycle'));
+        hints.push(chalk.dim('esc to interrupt'));
+        return hints.join(chalk.dim(' \u00B7 '));
+    }
+    /**
+     * Show the full prompt area using sticky bottom chrome:
+     *   > _                    ← cursor here (bottom of scroll region, row N-3)
+     *   ──────────────────     ← row N-2: separator (fixed chrome row 0)
+     *   ▸▸ safe · esc = stop   ← row N-1: hints (fixed chrome row 1)
+     *   🌀 L1:... | statusbar  ← row N:   statusbar (fixed chrome row 2)
+     */
+    function showPrompt() {
+        const w = Math.max(20, (process.stdout.columns || 80) - 2);
+        // Update chrome row content
+        const sep = buildSeparator(w);
+        const hintLine = buildHintLine();
+        const data = getStatusBarData();
+        const bar = renderStatusBar(data, w);
+        // Set separator content on activity indicator (for restore after agent work)
+        activity.setSeparatorContent(sep);
+        // Combine tab bar into statusbar row when sessions exist
+        let statusContent = bar;
+        if (sessionMgr.all.length > 1) {
+            const tabBar = truncateBar(sessionMgr.renderTabs(), w);
+            statusContent = `${tabBar}  ${bar}`;
+        }
+        chrome.setRow(0, sep);
+        chrome.setRow(1, hintLine);
+        chrome.setRow(2, statusContent);
+        // Activate chrome if not already (sets scroll region + hooks stdout)
+        if (!chrome.isActive && !chrome.isInlineMode) {
+            chrome.activate();
+        }
         isAtPrompt = true;
-        process.stdout.write(`\n${sep}\n ${hintLine}\n ${bar}\n`);
-        rl.prompt();
+        if (chrome.isActive) {
+            // Position cursor at the bottom of the scroll region, then prompt
+            chrome.positionCursorForPrompt();
+            rl.prompt();
+        }
+        else {
+            // Inline fallback for small terminals
+            process.stdout.write(`\n${sep}\n ${hintLine}\n ${bar}\n`);
+            rl.prompt();
+        }
     }
     /** Build current status bar data object */
     function getStatusBarData() {
@@ -642,18 +780,22 @@ export async function chatCommand(options) {
             return [[], line];
         },
     });
-    // Update prompt and activity scroll region on terminal resize
+    // Update prompt, chrome, and activity on terminal resize
     process.stdout.on('resize', () => {
         rl.setPrompt(makePrompt());
+        chrome.handleResize();
         activity.handleResize();
+        if (isAtPrompt) {
+            chrome.positionCursorForPrompt();
+            rl.prompt();
+        }
     });
     // Track suggestion overlay state
     let lastSuggestionCount = 0;
     permissions.setReadline(rl);
     permissions.setPromptCallback((active) => { isAtPrompt = active; });
-    // Activity indicator renders on the bottom terminal row (absolute positioned,
-    // same row as statusbar). The footer timer already skips statusbar draws when
-    // activity.isAnimating is true, so there's no conflict.
+    // Activity indicator renders on chrome row 0 (separator/activity row, terminal row N-2).
+    // BottomChrome manages the scroll region and stdout hook for all 3 fixed rows.
     // Ctrl+C behavior:
     // - If there's text on the line → clear the line (like a normal terminal)
     // - If line is empty → count towards exit (double Ctrl+C = exit)
@@ -783,12 +925,12 @@ export async function chatCommand(options) {
             // === Tab switching: Ctrl+PageUp / Ctrl+PageDown ===
             if (key.ctrl && key.name === 'pageup') {
                 sessionMgr.switchPrev();
-                writeTabBar();
+                updateStatusBar();
                 return;
             }
             if (key.ctrl && key.name === 'pagedown') {
                 sessionMgr.switchNext();
-                writeTabBar();
+                updateStatusBar();
                 return;
             }
             // === Command Suggestions ===
@@ -841,8 +983,9 @@ export async function chatCommand(options) {
             // Double-ESC detection (for checkpoint browser when nothing is running)
             const result = processKeypress(key, keyState);
             if (result.action === 'open_browser' && !agentRunning) {
-                // Open checkpoint browser
+                // Open checkpoint browser — deactivate chrome for fullscreen TUI
                 rl.pause();
+                chrome.deactivate();
                 try {
                     const browserResult = await runCheckpointBrowser({
                         store: checkpointStore,
@@ -862,56 +1005,34 @@ export async function chatCommand(options) {
                 catch {
                     // Browser closed unexpectedly
                 }
+                chrome.activate();
                 rl.resume();
                 showPrompt();
             }
         });
     }
-    // Update statusbar — uses save/restore cursor (DECSC/DECRC).
-    // Only called during agent work to update token counts etc.
+    // Update statusbar via BottomChrome row 2.
+    // Called during agent work by the footer timer to update token counts etc.
     function updateStatusBar() {
         if (!process.stdout.isTTY)
             return;
         const data = getStatusBarData();
-        writeStatusBar(data);
-        // Draw tab bar if there are background sessions, otherwise clear stale tab bar
+        const w = (process.stdout.columns || 80) - 2;
+        const bar = renderStatusBar(data, w);
+        // Combine tab bar into statusbar row when background sessions exist
+        let statusContent = bar;
         if (sessionMgr.all.length > 1) {
-            writeTabBar();
+            const tabBar = truncateBar(sessionMgr.renderTabs(), w);
+            statusContent = `${tabBar}  ${bar}`;
+        }
+        if (chrome.isActive) {
+            chrome.setRow(2, statusContent);
         }
         else {
-            // Clear the tab bar row when no background sessions remain
-            clearTabBarRow();
+            // Inline fallback
+            writeStatusBar(data);
         }
     }
-    /** Clear the tab bar row (row N-1) to remove stale tab bar text */
-    function clearTabBarRow() {
-        if (!process.stdout.isTTY)
-            return;
-        const termHeight = process.stdout.rows || 24;
-        process.stdout.write(`\x1b7` + // Save cursor
-            `\x1b[${termHeight - 1};0H` + // Move to tab bar row
-            `\x1b[2K` + // Clear line
-            `\x1b8`);
-    }
-    /** Draw the session tab bar above the statusbar */
-    function writeTabBar() {
-        if (!process.stdout.isTTY)
-            return;
-        if (sessionMgr.all.length <= 1)
-            return;
-        const tabBar = sessionMgr.renderTabs();
-        const termHeight = process.stdout.rows || 24;
-        const termWidth = (process.stdout.columns || 80) - 2;
-        // Truncate tab bar to terminal width to prevent overflow into other rows
-        const safeTabBar = truncateBar(tabBar, termWidth);
-        // Write tab bar above the statusbar (termHeight - 1)
-        // Layout: ..., tabbar(N-1), statusbar(N)
-        process.stdout.write(`\x1b7` + // Save cursor
-            `\x1b[${termHeight - 1};0H` + // Move to row above statusbar
-            `\x1b[2K` + // Clear line
-            ` ${safeTabBar}` + // Tab bar (truncated to fit)
-            `\x1b8`);
-    }
     /** Push session findings to brain visualization */
     function pushFindingsToBrain(session) {
         import('../brain/generator.js').then(mod => {
@@ -958,13 +1079,14 @@ export async function chatCommand(options) {
     const PASTE_THRESHOLD_MS = 100; // Lines arriving faster than this = paste (100ms for Windows compat)
     // Show full prompt area on startup (separator + status + > prompt)
     showPrompt();
-    // Footer timer — redraws status bar during agent work (absolute positioning).
+    // Footer timer — redraws statusbar on chrome row 2 during agent work.
     // Skipped when:
     //   - user is at readline prompt (isAtPrompt) — prevents cursor-jumping
-    //   - activity indicator is animating — prevents flicker collision
     //   - inline progress active (inlineProgressActive) — prevents flicker over feed progress
+    // Note: activity.isAnimating guard no longer needed — activity uses chrome row 0,
+    // statusbar uses chrome row 2, they don't collide.
     const footerTimer = setInterval(() => {
-        if (process.stdout.isTTY && !isAtPrompt && !activity.isAnimating && !inlineProgressActive)
+        if (process.stdout.isTTY && !isAtPrompt && !inlineProgressActive)
             updateStatusBar();
     }, 500);
     footerTimer.unref();
@@ -999,6 +1121,46 @@ export async function chatCommand(options) {
             showPrompt();
             return;
         }
+        // Handle /browser directly (needs access to browserController closure)
+        if (input.startsWith('/browser')) {
+            const browserParts = input.split(/\s+/);
+            const browserArg = browserParts.slice(1).join(' ').trim();
+            if (browserArg === 'close') {
+                if (browserController?.isOpen()) {
+                    await browserController.close();
+                    renderInfo('Browser closed.');
+                }
+                else {
+                    renderInfo('Browser is not open.');
+                }
+                showPrompt();
+                return;
+            }
+            // Initialize browser controller if needed
+            if (!browserController) {
+                browserController = new BrowserController();
+            }
+            if (browserController.isOpen() && !browserArg) {
+                renderInfo(`Browser already open at: ${browserController.getUrl() || 'about:blank'}`);
+                showPrompt();
+                return;
+            }
+            try {
+                if (!browserController.isOpen()) {
+                    await browserController.launch();
+                    renderInfo('Browser opened.');
+                }
+                if (browserArg) {
+                    const result = await browserController.navigate(browserArg);
+                    renderInfo(`Navigated to: ${result.title} (${result.url})`);
+                }
+            }
+            catch (err) {
+                renderInfo(`Browser error: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            showPrompt();
+            return;
+        }
         // Handle slash commands
         if (input.startsWith('/')) {
             const handled = await handleSlashCommand(input, messages, agentHistory, config, spiralEngine, store, rl, permissions, undoStack, checkpointStore, sessionBuffer, { input: sessionTokensInput, output: sessionTokensOutput }, sessionToolCalls, (newProvider) => { provider = newProvider; config = store.getAll(); }, async (newScope) => {
@@ -1213,7 +1375,7 @@ export async function chatCommand(options) {
             // Activity started — readline stays active for type-ahead buffering
             // but we do NOT show a visible prompt (it would collide with tool output)
             isAtPrompt = false;
-        }, { enabled: validationEnabled, verbose: validationVerbose, strict: validationStrict }, bugJournal);
+        }, { enabled: validationEnabled, verbose: validationVerbose, strict: validationStrict }, bugJournal, browserController, visionProcessor, pushScreenshotToBrainFn);
         agentRunning = false;
         // Keep simple message history for state persistence
         messages.push({ role: 'user', content: input });
@@ -1229,7 +1391,7 @@ export async function chatCommand(options) {
                 agentRunning = true;
                 agentController.reset();
                 updateStatusBar();
-                await sendAgentMessage(buffered.trim(), agentHistory, provider, project, spiralEngine, config, permissions, undoStack, checkpointStore, agentController, activity, sessionBuffer, (inp, out) => { sessionTokensInput += inp; sessionTokensOutput += out; }, () => { sessionToolCalls++; roundToolCalls++; }, () => { isAtPrompt = true; rl.prompt(); }, { enabled: validationEnabled, verbose: validationVerbose, strict: validationStrict }, bugJournal);
+                await sendAgentMessage(buffered.trim(), agentHistory, provider, project, spiralEngine, config, permissions, undoStack, checkpointStore, agentController, activity, sessionBuffer, (inp, out) => { sessionTokensInput += inp; sessionTokensOutput += out; }, () => { sessionToolCalls++; roundToolCalls++; }, () => { isAtPrompt = true; rl.prompt(); }, { enabled: validationEnabled, verbose: validationVerbose, strict: validationStrict }, bugJournal, browserController, visionProcessor, pushScreenshotToBrainFn);
                 agentRunning = false;
                 messages.push({ role: 'user', content: buffered.trim() });
             }
@@ -1356,6 +1518,7 @@ export async function chatCommand(options) {
     }
     rl.on('close', async () => {
         clearInterval(footerTimer);
+        chrome.deactivate();
         if (spiralEngine) {
             // Persist session buffer (goals, entities, decisions) into spiral brain
             // so next session with the same brain can recall them
@@ -1377,6 +1540,13 @@ export async function chatCommand(options) {
             catch { /* best effort */ }
             spiralEngine.close();
         }
+        // Close browser if open
+        if (browserController?.isOpen()) {
+            try {
+                await browserController.close();
+            }
+            catch { /* best effort */ }
+        }
         process.stdout.write('\n');
         process.exit(0);
     });
@@ -1404,7 +1574,7 @@ async function runBackgroundSession(session, prompt, provider, project, spiralEn
         durationMs: session.elapsed,
     };
 }
-async function sendAgentMessage(input, agentHistory, provider, project, spiralEngine, config, permissions, undoStack, checkpointStore, controller, activity, sessionBuffer, onTokens, onToolCall, onAgentStart, validationOpts, bugJournal) {
+async function sendAgentMessage(input, agentHistory, provider, project, spiralEngine, config, permissions, undoStack, checkpointStore, controller, activity, sessionBuffer, onTokens, onToolCall, onAgentStart, validationOpts, bugJournal, browserController, visionProcessor, onBrowserScreenshot) {
     // User message was rendered by renderUserMessage() in the caller before entering here.
     // Intent Detection: Check if user wants to feed the codebase
     const feedIntent = detectFeedIntent(input);
@@ -1471,6 +1641,10 @@ async function sendAgentMessage(input, agentHistory, provider, project, spiralEn
     activity.start();
     // Notify caller so it can show the readline prompt for type-ahead
     onAgentStart?.();
+    // Lazy-init vision processor when browser is available
+    if (browserController && !visionProcessor) {
+        visionProcessor = new VisionProcessor(provider);
+    }
     try {
         const result = await runAgentLoop(input, agentHistory, {
             provider,
@@ -1481,6 +1655,9 @@ async function sendAgentMessage(input, agentHistory, provider, project, spiralEn
                 undoStack,
                 spiralEngine,
                 bugJournal,
+                browserController,
+                visionProcessor,
+                onBrowserScreenshot: onBrowserScreenshot ?? undefined,
             },
             checkpointStore,
             sessionBuffer,