teamshare-bridge 0.21.23 → 0.21.26

package/dist/cli/commands/browse.js

@@ -119,6 +119,7 @@ const SYSTEM_PROMPT = `You are a browser automation agent. A screenshot and a gr
 Your task: identify unanswered questions and answer them by clicking the correct elements.
 
 RULES (STRICT):
+0. BE FAST AND DECISIVE. Answer in a single pass with minimal reasoning — do NOT deliberate at length, re-check repeatedly, or restate the page. Emit the final JSON array as your primary output. Speed matters more than exhaustive deliberation.
 1. NEVER click Next, Submit, Back, Save, Continue, or any navigation. ONLY answer questions on the current screen.
 2. NEVER ask for help. If uncertain, pick the BEST GUESS. Always decide — never wait.
 3. Handle MULTIPLE unanswered questions in a SINGLE response.
@@ -257,6 +258,133 @@ RESPONSE FORMAT RULES (CRITICAL — follow exactly):
 - RIGHT: {"text":"say \\"hello\\""}
 - NEVER put raw newlines or unescaped quotes inside the text string.
 - If you need to explain your reasoning, use the "reason" field, NOT the "text" field.`;
+/**
+ * Enable the Page domain and install the per-tab instrumentation the loop
+ * relies on: the stealth console wrapper, the Page.frameNavigated listener and
+ * the debounced MutationObserver. Extracted so every (re)attach - including a
+ * tab switch/close - re-runs it on the NEW tab. All of it must be idempotent
+ * (the injected scripts already early-return when their Symbol key exists).
+ */
+async function instrumentPage(page) {
+    try {
+        await cdpSend(page, 'Page.enable', {});
+        console.log('[browse] Page domain enabled');
+    }
+    catch (err) {
+        console.error(`[browse] Page.enable failed: ${(0, config_1.msg)(err)}`);
+    }
+    // Stealth: install stack trace sanitization to hide CDP frames (global, once)
+    installStackTraceStealth();
+    // Stealth: suppress console serialization leak caused by CDP's Runtime.enable.
+    // Anti-bot probe: Object.defineProperty(obj,'x',{get(){window.__detected=1}});
+    //   console.debug(obj); if(window.__detected) → CDP is serializing args
+    // Countermeasure: wrap console methods to prevent deep serialization.
+    try {
+        await cdpEval(page, `
+      (() => {
+        const CK = Symbol('__ts_cp');
+        if (window[CK]) return;
+        const wrap = (fn) => function(...args) {
+          return fn.apply(console, args.map(a => {
+            if (a && typeof a === 'object' && typeof a !== 'function') {
+              try { return Object.assign(Array.isArray(a) ? [] : {}, a); } catch { return a; }
+            }
+            return a;
+          }));
+        };
+        console.debug = wrap(console.debug);
+        console.log = wrap(console.log);
+        console.warn = wrap(console.warn);
+        console.error = wrap(console.error);
+        window[CK] = true;
+      })()
+    `);
+    }
+    catch { /* non-critical */ }
+    // Register CDP event: Page.frameNavigated (URL/navigation changes)
+    onCdpEvent(page, 'Page.frameNavigated', () => {
+        page._cdpNavigated = Date.now();
+    });
+    // Inject MutationObserver: watches DOM for significant content changes
+    // Uses same fingerprint comparison as Node.js side to prevent false positives.
+    // Filters out: timers, animations, scripts, styles, notifications, toasts.
+    // Debounces mutations (500ms) to batch rapid changes.
+    // Stealth: uses Symbol-keyed property (invisible to Object.keys / anti-bot scans).
+    try {
+        await cdpEval(page, `
+      (() => {
+        const KEY = Symbol('__ts_obs');
+        if (window[KEY]) return 'already attached';
+        const IGNORE = /timer|countdown|elapsed|clock|animation|animate|transition|spinner|progress|loading|toast|notification|alert|banner|snackbar|cookie|consent|modal|overlay|popup|tooltip|badge|tag|avatar|icon|svg|img|video|audio|canvas|font|stylesheet|script|meta|link|head/i;
+        let timer = null;
+        let lastText = '';
+        function getText() {
+          const els = document.querySelectorAll('input[type="radio"],input[type="checkbox"],input[type="text"],input[type="email"],input[type="password"],textarea,label,button');
+          return [...els].map(e => {
+            const t = (e.innerText || e.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 200);
+            return e.type + '|' + t + '|' + (e.checked || false);
+          }).join('\\n');
+        }
+        function check() {
+          try {
+            const curr = getText();
+            if (curr === lastText) return;
+            const prev = lastText;
+            lastText = curr;
+            const prevGroups = prev ? prev.split('\\n').filter(Boolean) : [];
+            const currGroups = curr.split('\\n').filter(Boolean);
+            const prevSet = new Set(prevGroups);
+            const currSet = new Set(currGroups);
+            let removed = 0, changed = 0;
+            for (const g of prevGroups) {
+              if (!currSet.has(g)) {
+                if (prevGroups.indexOf(g) < currGroups.length) changed++;
+                else removed++;
+              }
+            }
+            const added = currGroups.filter(g => !prevSet.has(g)).length;
+            const score = added * 10 + removed * 10 + changed * 8;
+            if (score >= 15) {
+              window[KEY].changed = Date.now();
+            }
+          } catch {}
+        }
+        const obs = new MutationObserver((mutations) => {
+          let hasRelevant = false;
+          for (const m of mutations) {
+            if (m.target instanceof Element) {
+              const tag = m.target.tagName;
+              if (tag === 'SCRIPT' || tag === 'STYLE' || tag === 'HEAD') continue;
+              const cls = m.target.className || '';
+              if (typeof cls === 'string' && IGNORE.test(cls)) continue;
+              const id = m.target.id || '';
+              if (IGNORE.test(id)) continue;
+              if (m.type === 'characterData' && m.target.parentElement) {
+                const ptag = m.target.parentElement.tagName;
+                if (ptag === 'SCRIPT' || ptag === 'STYLE') continue;
+              }
+            }
+            hasRelevant = true;
+          }
+          if (hasRelevant) {
+            clearTimeout(timer);
+            timer = setTimeout(check, 500);
+          }
+        });
+        obs.observe(document.body || document.documentElement, {
+          childList: true, subtree: true, characterData: true
+        });
+        window[KEY] = { observer: obs, changed: 0 };
+        lastText = getText();
+        return 'ok';
+      })()
+    `);
+        console.log('[browse] MutationObserver injected (stealth, debounced, filtered)');
+    }
+    catch (err) {
+        console.error(`[browse] MutationObserver injection failed: ${(0, config_1.msg)(err)}`);
+    }
+}
 async function cmdBrowse(flags) {
     const autoAnswer = flags.get('auto-answer') === 'true';
     if (!autoAnswer) {
@@ -316,9 +444,18 @@ async function cmdBrowse(flags) {
     const maxActions = continuous ? Number.MAX_SAFE_INTEGER : parseInt(flags.get('max-actions') ?? '50', 10);
     const intervalMs = parseInt(flags.get('interval') ?? '2000', 10);
     const modelSpec = flags.get('model') ?? models_1.DEFAULT_VISION_MODEL;
-    const timeoutSec = Math.min(Math.max(parseInt(flags.get('timeout') ?? '300', 10), 30), 600);
+    // Target: a decisive answer in well under a minute. 60s is the abandon
+    // threshold (overridable); the fast abort + short retry below makes giving up
+    // cheap, so we never wait 5 minutes for a stale decision.
+    const timeoutSec = Math.min(Math.max(parseInt(flags.get('timeout') ?? '60', 10), 20), 600);
     const timeoutMs = timeoutSec * 1000;
-    const quality = Math.min(Math.max(parseInt(flags.get('quality') ?? '78', 10), 50), 100);
+    const quality = Math.min(Math.max(parseInt(flags.get('quality') ?? '70', 10), 50), 100);
+    /**
+     * Downscale the screenshot when the viewport is bigger than this many px on
+     * its longest side (fewer image tokens => faster vision response on big
+     * pages; a 1440px page produced 100KB+ images that blew the timeout).
+     */
+    const SCREENSHOT_MAX_EDGE = 1024;
     const maxConsecutiveFailures = parseInt(flags.get('max-consecutive-failures') ?? '0', 10); // 0 = unlimited
     const charDelayMs = Math.min(Math.max(parseInt(flags.get('char-delay') ?? '150', 10), 5), 200);
     const optimize = flags.has('optimize');
@@ -400,125 +537,9 @@ async function cmdBrowse(flags) {
         process.exitCode = 1;
         return;
     }
-    // Enable Page domain (required for captureScreenshot)
-    try {
-        await cdpSend(page, 'Page.enable', {});
-        console.log('[browse] Page domain enabled');
-    }
-    catch (err) {
-        console.error(`[browse] Page.enable failed: ${(0, config_1.msg)(err)}`);
-    }
-    // Stealth: install stack trace sanitization to hide CDP frames
-    installStackTraceStealth();
-    // Stealth: suppress console serialization leak caused by CDP's Runtime.enable.
-    // Anti-bot probe: Object.defineProperty(obj,'x',{get(){window.__detected=1}});
-    //   console.debug(obj); if(window.__detected) → CDP is serializing args
-    // Countermeasure: wrap console methods to prevent deep serialization.
-    try {
-        await cdpEval(page, `
-      (() => {
-        const CK = Symbol('__ts_cp');
-        if (window[CK]) return;
-        const wrap = (fn) => function(...args) {
-          return fn.apply(console, args.map(a => {
-            if (a && typeof a === 'object' && typeof a !== 'function') {
-              try { return Object.assign(Array.isArray(a) ? [] : {}, a); } catch { return a; }
-            }
-            return a;
-          }));
-        };
-        console.debug = wrap(console.debug);
-        console.log = wrap(console.log);
-        console.warn = wrap(console.warn);
-        console.error = wrap(console.error);
-        window[CK] = true;
-      })()
-    `);
-    }
-    catch { /* non-critical */ }
-    // Register CDP event: Page.frameNavigated (URL/navigation changes)
-    onCdpEvent(page, 'Page.frameNavigated', () => {
-        page._cdpNavigated = Date.now();
-    });
-    // Inject MutationObserver: watches DOM for significant content changes
-    // Uses same fingerprint comparison as Node.js side to prevent false positives.
-    // Filters out: timers, animations, scripts, styles, notifications, toasts.
-    // Debounces mutations (500ms) to batch rapid changes.
-    // Stealth: uses Symbol-keyed property (invisible to Object.keys / anti-bot scans).
-    try {
-        await cdpEval(page, `
-      (() => {
-        const KEY = Symbol('__ts_obs');
-        if (window[KEY]) return 'already attached';
-        const IGNORE = /timer|countdown|elapsed|clock|animation|animate|transition|spinner|progress|loading|toast|notification|alert|banner|snackbar|cookie|consent|modal|overlay|popup|tooltip|badge|tag|avatar|icon|svg|img|video|audio|canvas|font|stylesheet|script|meta|link|head/i;
-        let timer = null;
-        let lastText = '';
-        function getText() {
-          const els = document.querySelectorAll('input[type="radio"],input[type="checkbox"],input[type="text"],input[type="email"],input[type="password"],textarea,label,button');
-          return [...els].map(e => {
-            const t = (e.innerText || e.textContent || '').trim().replace(/\\s+/g, ' ').slice(0, 200);
-            return e.type + '|' + t + '|' + (e.checked || false);
-          }).join('\\n');
-        }
-        function check() {
-          try {
-            const curr = getText();
-            if (curr === lastText) return;
-            const prev = lastText;
-            lastText = curr;
-            const prevGroups = prev ? prev.split('\\n').filter(Boolean) : [];
-            const currGroups = curr.split('\\n').filter(Boolean);
-            const prevSet = new Set(prevGroups);
-            const currSet = new Set(currGroups);
-            let removed = 0, changed = 0;
-            for (const g of prevGroups) {
-              if (!currSet.has(g)) {
-                if (prevGroups.indexOf(g) < currGroups.length) changed++;
-                else removed++;
-              }
-            }
-            const added = currGroups.filter(g => !prevSet.has(g)).length;
-            const score = added * 10 + removed * 10 + changed * 8;
-            if (score >= 15) {
-              window[KEY].changed = Date.now();
-            }
-          } catch {}
-        }
-        const obs = new MutationObserver((mutations) => {
-          let hasRelevant = false;
-          for (const m of mutations) {
-            if (m.target instanceof Element) {
-              const tag = m.target.tagName;
-              if (tag === 'SCRIPT' || tag === 'STYLE' || tag === 'HEAD') continue;
-              const cls = m.target.className || '';
-              if (typeof cls === 'string' && IGNORE.test(cls)) continue;
-              const id = m.target.id || '';
-              if (IGNORE.test(id)) continue;
-              if (m.type === 'characterData' && m.target.parentElement) {
-                const ptag = m.target.parentElement.tagName;
-                if (ptag === 'SCRIPT' || ptag === 'STYLE') continue;
-              }
-            }
-            hasRelevant = true;
-          }
-          if (hasRelevant) {
-            clearTimeout(timer);
-            timer = setTimeout(check, 500);
-          }
-        });
-        obs.observe(document.body || document.documentElement, {
-          childList: true, subtree: true, characterData: true
-        });
-        window[KEY] = { observer: obs, changed: 0 };
-        lastText = getText();
-        return 'ok';
-      })()
-    `);
-        console.log('[browse] MutationObserver injected (stealth, debounced, filtered)');
-    }
-    catch (err) {
-        console.error(`[browse] MutationObserver injection failed: ${(0, config_1.msg)(err)}`);
-    }
+    // Enable Page + install per-tab instrumentation. Re-run on every (re)attach
+    // so a tab switch/close leaves the loop fully instrumented.
+    await instrumentPage(page);
     // Agent loop
     let actionCount = 0;
     let llmCallCount = 0;
@@ -527,7 +548,84 @@ async function cmdBrowse(flags) {
     let lastScreenshot = null;
     let lastFingerprint = null;
     let codeConfirmedOptimal = false;
+    /** A 401/403 from the model API: terminal, retrying cannot succeed. */
+    let fatalAuthError = false;
     const maxRetries = 5;
+    /** How often to re-check which tab is active (ms). */
+    const TAB_CHECK_MS = 2000;
+    let lastTabCheck = 0;
+    let consecutiveScreenshotFailures = 0;
+    let reattachFailures = 0;
+    // Latency observability: rolling average of vision-call latency plus
+    // abort/timeout counts, so the operator can see how slow the model is.
+    const llmStats = { calls: 0, ok: 0, screenAborts: 0, timeouts: 0, totalMs: 0 };
+    const logLlmStats = () => {
+        if (llmStats.calls === 0 || llmStats.calls % 5 !== 0)
+            return;
+        const avg = Math.round(llmStats.totalMs / llmStats.calls / 1000);
+        console.log(`[browse] LLM latency: avg ${avg}s over ${llmStats.calls} call(s) — ${llmStats.ok} ok, ${llmStats.screenAborts} screen-abort, ${llmStats.timeouts} timeout`);
+    };
+    /**
+     * (Re)attach to a tab. A closed or switched tab used to leave the loop
+     * hammering a dead target ("CDP timeout: Page.captureScreenshot") forever;
+     * now we detect it and follow the tab the human is actually on.
+     */
+    async function reattach(reason, preferTargetId) {
+        console.log(`[browse] ${reason} - re-attaching...`);
+        try {
+            page.ws.close();
+        }
+        catch {
+            /* already closed */
+        }
+        page = await connectToPage(port, preferTargetId);
+        await instrumentPage(page);
+        // A different tab means different content: reset change trackers.
+        lastFingerprint = null;
+        lastScreenshot = null;
+        codeConfirmedOptimal = false;
+        consecutiveFailures = 0;
+        consecutiveScreenshotFailures = 0;
+        console.log(`[browse] Re-attached to tab: ${page.title} (${page.targetId.slice(0, 8)})`);
+    }
+    /**
+     * Throttled liveness check: is the bound tab still alive and the active one?
+     * Follows the human's active tab (and recovers after it is closed). `force`
+     * skips the throttle (used from the screenshot-failure path).
+     */
+    async function refreshTabIfNeeded(force = false) {
+        if (!force && Date.now() - lastTabCheck < TAB_CHECK_MS)
+            return false;
+        lastTabCheck = Date.now();
+        try {
+            if (page.disconnected) {
+                // The bound tab is gone: move straight to whatever tab is active now.
+                const active = await (0, cdp_1.pickActiveTab)(port).catch(() => null);
+                await reattach('Bound tab closed', active?.id);
+                reattachFailures = 0;
+                return true;
+            }
+            const active = await (0, cdp_1.pickActiveTab)(port, page.targetId);
+            if (!active)
+                return false;
+            if (active.id !== page.targetId) {
+                await reattach(`Active tab changed to "${active.title}"`, active.id);
+                reattachFailures = 0;
+                return true;
+            }
+            return false;
+        }
+        catch (err) {
+            reattachFailures++;
+            console.error(`[browse] Re-attach attempt ${reattachFailures} failed: ${(0, config_1.msg)(err)}`);
+            if (reattachFailures >= 6) {
+                console.error('[browse] Could not re-attach to any tab - stopping.');
+                stopped = true;
+                process.exitCode = 1;
+            }
+            return false;
+        }
+    }
     process.on('SIGINT', () => {
         console.log('\n[browse] Stopped by user');
         stopped = true;
@@ -536,17 +634,26 @@ async function cmdBrowse(flags) {
     console.log(`[browse] Agent started. ${continuous ? 'Running until Ctrl+C.' : `Max ${maxActions} actions.`} Press Ctrl+C to stop.\n`);
     while (!stopped && actionCount < maxActions) {
         try {
+            // Follow the human's active tab: re-attach if the bound tab was closed or
+            // the user switched to another one.
+            await refreshTabIfNeeded();
             // Take screenshot and extract elements in parallel
             const [screenshot, elements, pageContext] = await Promise.all([
-                captureScreenshot(page, quality),
+                captureScreenshot(page, quality, SCREENSHOT_MAX_EDGE),
                 extractElements(page),
                 extractPageContext(page),
             ]);
             if (!screenshot) {
-                console.error('[browse] Failed to capture screenshot, retrying...');
+                consecutiveScreenshotFailures++;
+                console.error(`[browse] Failed to capture screenshot (${consecutiveScreenshotFailures}), retrying...`);
+                // Two failures in a row generally means the target is gone.
+                if (consecutiveScreenshotFailures >= 2) {
+                    await refreshTabIfNeeded(true);
+                }
                 await sleep(intervalMs);
                 continue;
             }
+            consecutiveScreenshotFailures = 0;
             // Detect screen change via question fingerprint comparison
             // Threshold 15: requires ≥1 new/removed question (10) + text change (8) = 18,
             // or 2 text changes (16). Score of 5 (single option change) is too sensitive.
@@ -566,28 +673,61 @@ async function cmdBrowse(flags) {
             const actionLabel = continuous ? `${actionCount + 1}/∞` : `${actionCount + 1}/${maxActions}`;
             console.log(`[browse] [${actionLabel}] Analyzing screenshot...`);
             let result = null;
+            /** The page changed under the LLM: re-analyze immediately, no backoff. */
+            let screenChangedDuringLlm = false;
             for (let attempt = 1; attempt <= maxRetries; attempt++) {
                 result = await analyzeScreenshot(baseUrl, apiKey, model, screenshot, elements, pageContext, timeoutMs, attempt, maxRetries, page, lastFingerprint);
                 llmCallCount++;
+                llmStats.calls++;
+                llmStats.totalMs += result.durationMs;
                 if (llmCallCount > 50 && llmCallCount % 25 === 0) {
                     console.log(`[browse] Warning: ${llmCallCount} LLM calls made — may hit rate limits`);
                 }
-                if (result.actions.length > 0)
+                if (result.actions.length > 0) {
+                    llmStats.ok++;
+                    logLlmStats();
                     break; // success
-                // Timeout → exponential backoff, keep retrying (never count as failure)
+                }
+                // Auth failure is terminal: retrying cannot help.
+                if (result.error === 'auth_error') {
+                    fatalAuthError = true;
+                    break;
+                }
+                // The screen changed while the LLM was thinking: its answer is stale.
+                // Bail out of the retry loop and re-analyze the NEW screen right away
+                // (speed matters: a 30s backoff here livelocked on dynamic pages).
+                if (result.error === 'screen_changed') {
+                    screenChangedDuringLlm = true;
+                    llmStats.screenAborts++;
+                    logLlmStats();
+                    break;
+                }
+                // Genuine timeout → SHORT backoff and retry (was 30/60/120/240/300s).
                 if (result.error === 'timeout') {
-                    const backoff = Math.min(30 * Math.pow(2, attempt - 1), 300); // 30, 60, 120, 240, 300
+                    llmStats.timeouts++;
+                    logLlmStats();
+                    const backoff = Math.min(3 * attempt, 12); // 3, 6, 9, 12, 12
                     console.log(`[browse] LLM timed out — retrying in ${backoff}s (attempt ${attempt}/${maxRetries})...`);
                     await sleep(backoff * 1000);
                     continue;
                 }
-                // Other errors → short backoff
+                // Other errors → very short backoff
                 if (attempt < maxRetries) {
-                    const backoff = attempt === 1 ? 3 : 5;
+                    const backoff = 2;
                     console.log(`[browse] ${result.error === 'empty' ? 'Empty response' : 'Parse failed'} (attempt ${attempt}/${maxRetries}), retrying in ${backoff}s...`);
                     await sleep(backoff * 1000);
                 }
             }
+            if (fatalAuthError) {
+                console.error('[browse] Stopping: the model rejected the API key. Set a valid provider key on the run form (or the agent) and re-run.');
+                stopped = true;
+                process.exitCode = 1;
+                break;
+            }
+            if (screenChangedDuringLlm) {
+                // No sleep: go straight back to the top, re-screenshot + re-analyze.
+                continue;
+            }
             if (!result || result.actions.length === 0) {
                 consecutiveFailures++;
                 console.log(`[browse] No valid response after ${maxRetries} attempts (${consecutiveFailures} consecutive failures)`);
@@ -884,11 +1024,11 @@ Do NOT simplify variable names or change the function signature. Only optimize t
  * Connect directly to a page's WebSocket from /json/list.
  * This avoids the Target.attachToTarget complexity.
  */
-async function connectToPage(port) {
+async function connectToPage(port, preferTargetId) {
     // Shared picker (cdp.ts): prefers a real page, accepts about:blank/new-tab,
     // and opens a blank tab if none exists - so a Chrome launched on the NTP is
     // still attachable. (Was a local chrome:// filter that could never match.)
-    const pageTarget = await (0, cdp_1.resolveAttachablePage)(port);
+    const pageTarget = await (0, cdp_1.resolveAttachablePage)(port, preferTargetId);
     const wsUrl = pageTarget.webSocketDebuggerUrl;
     return new Promise((resolve, reject) => {
         const ws = new ws_1.default(wsUrl);
@@ -945,6 +1085,8 @@ async function connectToPage(port) {
             }
         });
         ws.on('close', () => {
+            // The endpoint is gone: flag it so the agent loop can re-attach.
+            page.disconnected = true;
             // Reject all pending
             for (const [id, p] of page.pending) {
                 p.reject(new Error('WebSocket closed'));
@@ -1009,9 +1151,32 @@ function cdpSend(page, method, params) {
         page.ws.send(JSON.stringify({ id, method, params }));
     });
 }
-async function captureScreenshot(page, quality) {
+/**
+ * Capture the visible viewport as JPEG. When the viewport is larger than
+ * `maxEdge` on either side the capture is scaled down (`clip.scale`) so the
+ * vision call stays fast: a big page produced 100KB+ images that exceeded the
+ * model timeout. Clicking is unaffected — actions use element coordinates
+ * (CSS px), not image pixels.
+ */
+async function captureScreenshot(page, quality, maxEdge = 0) {
     try {
-        const result = await cdpSend(page, 'Page.captureScreenshot', { format: 'jpeg', quality });
+        const params = { format: 'jpeg', quality };
+        if (maxEdge > 0) {
+            try {
+                const metrics = await cdpSend(page, 'Page.getLayoutMetrics', {});
+                const vp = metrics?.cssLayoutViewport ?? metrics?.layoutViewport;
+                const w = Number(vp?.clientWidth ?? 0);
+                const h = Number(vp?.clientHeight ?? 0);
+                if (w > 0 && h > 0 && (w > maxEdge || h > maxEdge)) {
+                    const scale = Math.min(maxEdge / w, maxEdge / h);
+                    params.clip = { x: 0, y: 0, width: w, height: h, scale };
+                }
+            }
+            catch {
+                /* metrics unavailable - capture unscaled */
+            }
+        }
+        const result = await cdpSend(page, 'Page.captureScreenshot', params);
         return result?.data ?? null;
     }
     catch (err) {
@@ -2349,11 +2514,19 @@ async function analyzeScreenshot(baseUrl, apiKey, model, screenshotBase64, eleme
             },
         ],
         temperature: 0.1,
-        max_tokens: 16384,
+        max_tokens: 2048,
         stream: false,
     };
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    // Distinguish a genuine timeout from the heartbeat cancelling a stale request
+    // because the page changed: they need opposite handling (backoff vs re-analyze
+    // now). The old code reported both as "timed out (300s)" and backed off 30s+,
+    // which livelocked on dynamic pages.
+    let abortReason = null;
+    const timeout = setTimeout(() => {
+        abortReason = 'timeout';
+        controller.abort();
+    }, timeoutMs);
     // Heartbeat: check for screen changes every 5s, abort LLM if page changed
     const heartbeat = setInterval(async () => {
         const elapsed = Math.round((Date.now() - startTime) / 1000);
@@ -2399,6 +2572,7 @@ async function analyzeScreenshot(baseUrl, apiKey, model, screenshotBase64, eleme
                 const changeScore = calculateChangeScore(lastFingerprint, freshFingerprint);
                 if (changeScore >= 15) {
                     console.log(`[browse] Fingerprint confirms change (score: ${changeScore}) — aborting LLM (${elapsed}s)`);
+                    abortReason = 'screen_change';
                     controller.abort();
                     return;
                 }
@@ -2427,6 +2601,14 @@ async function analyzeScreenshot(baseUrl, apiKey, model, screenshotBase64, eleme
         if (!res.ok) {
             const errText = await res.text().catch(() => '');
             console.error(`[browse] LLM HTTP ${res.status}: ${errText.slice(0, 200)}`);
+            // 401/403 will never succeed on retry — surface a clear, actionable
+            // diagnosis instead of burning 5 attempts x N rounds.
+            if (res.status === 401 || res.status === 403) {
+                console.error(`[browse] Model auth failed for ${baseUrl} (model ${model}). The API key is invalid, ` +
+                    `expired, or belongs to a different provider. Fix the provider key on the run form ` +
+                    `(or the agent's provider key) and re-run.`);
+                return { actions: [], attempt, durationMs: Date.now() - startTime, error: 'auth_error' };
+            }
             return { actions: [], attempt, durationMs: Date.now() - startTime, error: 'http_error' };
         }
         const json = (await res.json());
@@ -2457,6 +2639,13 @@ async function analyzeScreenshot(baseUrl, apiKey, model, screenshotBase64, eleme
     }
     catch (err) {
         if (err instanceof Error && err.name === 'AbortError') {
+            const elapsed = Math.round((Date.now() - startTime) / 1000);
+            if (abortReason === 'screen_change') {
+                // The page changed while we were waiting: the answer is already stale.
+                // Signal the caller to re-analyze right away (no backoff).
+                console.log(`[browse] LLM aborted at ${elapsed}s — screen changed, re-analyzing now`);
+                return { actions: [], attempt, durationMs: Date.now() - startTime, error: 'screen_changed' };
+            }
             console.error(`[browse] LLM request timed out (${Math.round(timeoutMs / 1000)}s)`);
             return { actions: [], attempt, durationMs: Date.now() - startTime, error: 'timeout' };
         }
@@ -2488,11 +2677,15 @@ async function analyzeScreenshotWithPrompt(baseUrl, apiKey, model, screenshotBas
             },
         ],
         temperature: 0.1,
-        max_tokens: 16384,
+        max_tokens: 2048,
         stream: false,
     };
     const controller = new AbortController();
-    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    let optAbortReason = null;
+    const timeout = setTimeout(() => {
+        optAbortReason = 'timeout';
+        controller.abort();
+    }, timeoutMs);
     // Heartbeat: check for screen changes every 5s, abort if page changed
     const heartbeat = setInterval(async () => {
         const elapsed = Math.round((Date.now() - startTime) / 1000);
@@ -2509,6 +2702,7 @@ async function analyzeScreenshotWithPrompt(baseUrl, apiKey, model, screenshotBas
             const flagTs = flagResult?.result?.value;
             if (flagTs && flagTs > startTime) {
                 console.log(`[browse] DOM mutation detected in opt pass (${elapsed}s) — aborting`);
+                optAbortReason = 'screen_change';
                 controller.abort();
                 return;
             }
@@ -2552,7 +2746,12 @@ async function analyzeScreenshotWithPrompt(baseUrl, apiKey, model, screenshotBas
     }
     catch (err) {
         if (err instanceof Error && err.name === 'AbortError') {
-            return { actions: [], attempt, durationMs: Date.now() - startTime, error: 'timeout' };
+            return {
+                actions: [],
+                attempt,
+                durationMs: Date.now() - startTime,
+                error: optAbortReason === 'screen_change' ? 'screen_changed' : 'timeout',
+            };
         }
         return { actions: [], attempt, durationMs: Date.now() - startTime, error: 'http_error' };
     }