@tangle-network/browser-agent-driver 0.8.0 → 0.10.0

package/dist/runner/runner.js

@@ -11,6 +11,7 @@
  */
 import { Brain } from '../brain/index.js';
 import { analyzeRecovery, detectPersistentTerminalBlocker, detectTerminalBlocker } from '../recovery.js';
+import { solveCaptcha, canAttemptSolve } from '../captcha.js';
 import { StaleRefError, AriaSnapshotHelper } from '../drivers/snapshot.js';
 import { verifyPreview } from '../preview.js';
 import { AppKnowledge } from '../memory/knowledge.js';
@@ -28,6 +29,21 @@ import { buildGoalVerificationClaim, collectSearchWorkflowEvidence, shouldAccept
 import { detectAiTanglePartnerTemplateVisibleState, detectAiTangleVerifiedOutputState, shouldEscalateVision } from './page-analysis.js';
 import { shouldUseVisibleLinkScout, shouldUseVisibleLinkScoutPage, shouldUseBoundedBranchExplorer, inspectBranchPreview, scoreBranchPreview } from './scout.js';
 import { buildOverrideProducers, buildScoutLinkRecommendationText, buildBranchLinkRecommendationText } from './overrides.js';
+import { RunRegistry } from '../memory/run-registry.js';
+/** Build a structured session record from a completed run */
+function buildSession(scenario, result) {
+    const lastTurn = result.turns[result.turns.length - 1];
+    return {
+        id: scenario.sessionId || `session_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+        goal: scenario.goal,
+        outcome: result.result || result.reason || (result.success ? 'Goal achieved' : 'Failed'),
+        success: result.success,
+        finalUrl: lastTurn?.state?.url || scenario.startUrl || '',
+        timestamp: new Date().toISOString(),
+        turnsUsed: result.turns.length,
+        durationMs: result.totalMs,
+    };
+}
 const DEFAULT_MAX_TURNS = 20;
 const DEFAULT_RETRIES = 3;
 const DEFAULT_RETRY_DELAY_MS = 1000;
@@ -50,7 +66,7 @@ const DEFI_BRAIN_CONTEXT = '\nWALLET/DeFi MODE ACTIVE — crypto app patterns:\n
     '- NATIVE ETH: Prefer native ETH over wrapped tokens (WETH) when possible — avoids ERC-20 spending approval steps.\n' +
     '- NETWORK SELECTOR: Do NOT change the network/chain. If a network dropdown opens accidentally, close it immediately.\n' +
     '- COOKIE BANNERS: Dismiss immediately via Escape or Reject button — don\'t spend multiple turns on consent dialogs.\n';
-export class AgentRunner {
+export class BrowserAgent {
     driver;
     brain;
     config;
@@ -58,8 +74,10 @@ export class AgentRunner {
     onPhaseTiming;
     referenceTrajectory;
     projectStore;
+    runRegistry;
     knowledge;
     selectorCache;
+    cachedPostState;
     constructor(options) {
         this.driver = options.driver;
         this.config = options.config || {};
@@ -68,6 +86,7 @@ export class AgentRunner {
         this.onPhaseTiming = options.onPhaseTiming;
         this.referenceTrajectory = options.referenceTrajectory;
         this.projectStore = options.projectStore;
+        this.runRegistry = options.runRegistry;
     }
     async run(scenario) {
         const maxTurns = scenario.maxTurns || DEFAULT_MAX_TURNS;
@@ -77,25 +96,70 @@ export class AgentRunner {
         const startTime = Date.now();
         const phaseTimings = {};
         const runState = new RunState(maxTurns);
-        const buildResult = (result) => ({
-            ...result,
-            phaseTimings,
-            wasteMetrics: deriveWasteMetrics(turns, runState.verificationRejectionCount, runState.firstSufficientEvidenceTurn),
-        });
+        const runId = scenario.sessionId
+            ? `${scenario.sessionId}_${Date.now()}`
+            : RunRegistry.generateRunId();
+        const domain = safeHostname(scenario.startUrl || '') || 'unknown';
+        const buildResult = (result) => {
+            const agentResult = {
+                ...result,
+                phaseTimings,
+                wasteMetrics: deriveWasteMetrics(turns, runState.verificationRejectionCount, runState.firstSufficientEvidenceTurn),
+            };
+            this.saveMemory(scenario, agentResult);
+            // Complete run manifest
+            const lastTurn = agentResult.turns[agentResult.turns.length - 1];
+            this.runRegistry?.completeRun(runId, {
+                success: agentResult.success,
+                finalUrl: lastTurn?.state?.url,
+                summary: agentResult.result || agentResult.reason,
+                result: agentResult.result,
+                reason: agentResult.reason,
+                turnCount: agentResult.turns.length,
+            });
+            return agentResult;
+        };
+        // Wrap onTurn to include mid-run manifest updates (every 3 turns)
+        const originalOnTurn = this.onTurn;
+        this.onTurn = (turn) => {
+            originalOnTurn?.(turn);
+            if (this.runRegistry && turns.length % 3 === 0) {
+                try {
+                    this.runRegistry.updateRun(runId, {
+                        turnCount: turns.length,
+                        currentUrl: turn.state?.url,
+                    });
+                }
+                catch { /* best-effort */ }
+            }
+        };
         // Reset brain history for fresh scenario
         this.brain.reset();
-        // Load domain-scoped memory if project store is configured
-        if (this.projectStore && scenario.startUrl) {
-            this.knowledge = new AppKnowledge(this.projectStore.getKnowledgePath(scenario.startUrl), scenario.startUrl);
-            this.selectorCache = new SelectorCache(this.projectStore.getSelectorCachePath(scenario.startUrl));
-        }
-        // Navigate to start URL if provided
+        this.cachedPostState = undefined;
+        // Start navigation and load memory in parallel. Navigation is async (network
+        // I/O) while memory init is sync (readFileSync), so memory completes while
+        // the network request is in flight — saving the serial cost of disk reads.
         if (scenario.startUrl) {
             const navigateStartedAt = Date.now();
-            await withRetry(() => this.driver.execute({ action: 'navigate', url: scenario.startUrl }), retries, retryDelayMs, undefined, scenario.signal);
+            const navPromise = withRetry(() => this.driver.execute({ action: 'navigate', url: scenario.startUrl }), retries, retryDelayMs, undefined, scenario.signal);
+            // Load domain-scoped memory while navigation is in progress
+            if (this.projectStore) {
+                this.knowledge = new AppKnowledge(this.projectStore.getKnowledgePath(scenario.startUrl), scenario.startUrl);
+                this.selectorCache = new SelectorCache(this.projectStore.getSelectorCachePath(scenario.startUrl));
+            }
+            await navPromise;
             phaseTimings.initialNavigateMs = Date.now() - navigateStartedAt;
             this.onPhaseTiming?.('navigate', phaseTimings.initialNavigateMs);
         }
+        // Write run manifest at start
+        this.runRegistry?.startRun({
+            runId,
+            sessionId: scenario.sessionId,
+            parentRunId: scenario.parentRunId,
+            goal: scenario.goal,
+            domain,
+            startUrl: scenario.startUrl,
+        });
         const supervisorConfig = {
             enabled: this.config.supervisor?.enabled ?? DEFAULT_SUPERVISOR.enabled,
             model: this.config.supervisor?.model || this.config.model || 'gpt-5.4',
@@ -174,12 +238,15 @@ export class AgentRunner {
                     }
                 }
                 // -- 2. Observe (with retry) --
+                // Reuse the snapshot from verifyEffect if available (no page mutations between them)
                 const observeStartedAt = Date.now();
-                const state = await withRetry(() => this.driver.observe(), retries, retryDelayMs, (attempt, err) => {
+                const state = this.cachedPostState ?? await withRetry(() => this.driver.observe(), 1, // Observe failures are DOM access issues, not transient — retrying 3x wastes 3s
+                retryDelayMs, (attempt, err) => {
                     if (this.config.debug) {
                         console.log(`[Runner] Observe retry ${attempt}: ${err.message}`);
                     }
                 }, scenario.signal);
+                this.cachedPostState = undefined;
                 if (phaseTimings.firstObserveMs === undefined) {
                     phaseTimings.firstObserveMs = Date.now() - observeStartedAt;
                     this.onPhaseTiming?.('observe', phaseTimings.firstObserveMs);
@@ -194,7 +261,29 @@ export class AgentRunner {
                     const reState = await withRetry(() => this.driver.observe(), retries, retryDelayMs, undefined, scenario.signal);
                     Object.assign(state, reState);
                 }
-                const terminalBlocker = detectTerminalBlocker(state);
+                let terminalBlocker = detectTerminalBlocker(state);
+                // Attempt CAPTCHA solving only if: bot-challenge, enabled, and evidence suggests a solvable CAPTCHA
+                if (terminalBlocker?.kind === 'bot-challenge'
+                    && this.config.captcha?.enabled !== false
+                    && canAttemptSolve(terminalBlocker.evidence)) {
+                    const page = this.driver.getPage?.();
+                    if (page) {
+                        try {
+                            const model = await this.brain.getLanguageModel();
+                            const captchaResult = await solveCaptcha(page, model, {
+                                maxAttempts: this.config.captcha?.maxAttempts ?? 5,
+                            });
+                            if (captchaResult.success) {
+                                await page.waitForLoadState('domcontentloaded', { timeout: 10_000 }).catch(() => { });
+                                const postCaptchaState = await this.driver.observe();
+                                Object.assign(state, postCaptchaState);
+                                this.brain.injectFeedback(`CAPTCHA solved: ${captchaResult.type} in ${captchaResult.attempts} attempt(s), ${captchaResult.durationMs}ms. Continuing.`);
+                                terminalBlocker = detectTerminalBlocker(state);
+                            }
+                        }
+                        catch { /* CAPTCHA solve failed, fall through to abort */ }
+                    }
+                }
                 if (terminalBlocker) {
                     const reason = `${terminalBlocker.reason} (signals: ${terminalBlocker.evidence.join(', ')})`;
                     const blockerTurn = {
@@ -206,7 +295,6 @@ export class AgentRunner {
                     };
                     turns.push(blockerTurn);
                     this.onTurn?.(blockerTurn);
-                    this.saveMemory();
                     return buildResult({
                         success: false,
                         reason,
@@ -226,7 +314,6 @@ export class AgentRunner {
                     };
                     turns.push(blockerTurn);
                     this.onTurn?.(blockerTurn);
-                    this.saveMemory();
                     return buildResult({
                         success: false,
                         reason,
@@ -247,42 +334,23 @@ export class AgentRunner {
                         (prevTurn?.action?.action === 'click' &&
                             /reject|accept|allow|deny|dismiss|consent|cookie/i.test(prevTurn?.action?.selector || prevTurn?.rawLLMResponse || ''));
                     if (modalWasDismissed && prevPrevTurn && state.url === prevPrevTurn.state.url) {
-                        ctxBudget.add('blocker-recovery', '\nBLOCKER RECOVERY NOTE: A blocking dialog was just dismissed, but the URL has not changed ' +
-                            'since before the dialog appeared. Any form submission, search, or navigation that was attempted ' +
-                            'before the dialog may have been intercepted and voided. ' +
-                            'Re-check the page state and re-submit your prior action if needed.\n', 90);
+                        ctxBudget.add('blocker-recovery', '\nDialog dismissed but URL unchanged — prior action may have been voided. Re-submit if needed.\n', 90);
                     }
                 }
                 const turnsLeft = maxTurns - i + 1;
                 if (turnsLeft <= 3) {
-                    let turnBudgetText = `\nTURN-BUDGET CRITICAL: ${turnsLeft} turn(s) left including this one.\n` +
-                        'Do not start new exploratory navigation.\n' +
-                        'Prioritize extracting the final required evidence from the current page context and finish decisively.\n';
-                    if (turnsLeft === 1) {
-                        turnBudgetText +=
-                            'FINAL TURN REQUIREMENT: return a terminal action now (`complete` if enough evidence exists, otherwise `abort` with explicit blocker reason).\n';
-                    }
-                    ctxBudget.add('turn-budget', turnBudgetText, 100);
+                    const finalTurnSuffix = turnsLeft === 1
+                        ? ' FINAL TURN: return complete or abort now.'
+                        : '';
+                    ctxBudget.add('turn-budget', `\nBUDGET: ${turnsLeft} turn(s) left. Extract data and finish.${finalTurnSuffix}\n`, 100);
                 }
                 else if (i >= Math.floor(maxTurns * 0.5) && runState.goalVerificationEvidence.length === 0) {
-                    // Mid-run: agent has used 50%+ turns without extracting any evidence
-                    ctxBudget.add('extraction-reminder', '\nEXTRACTION REMINDER: You have used over half your turn budget without extracting data. ' +
-                        'STOP navigating between individual pages. Use runScript NOW to extract ALL data from the CURRENT page: ' +
-                        'document.querySelectorAll("[class*=card], [class*=result], [class*=listing], li, tr").forEach(el => ...) ' +
-                        'to get names, prices, phone numbers, addresses, ratings. ' +
-                        'If you are on a listing/directory/search results page, extract everything visible and complete. ' +
-                        'Do NOT click into more individual items — extract from the list.\n', 85);
+                    ctxBudget.add('extraction-reminder', '\nHALF BUDGET USED, no data extracted. Use runScript NOW to extract from current page and complete.\n', 85);
                 }
-                // Early filter strategy nudge: if goal mentions filtering and agent hasn't
-                // extracted evidence by turn 8, remind to use filter controls efficiently
                 if (i >= 8 && i < Math.floor(maxTurns * 0.5) && runState.goalVerificationEvidence.length === 0) {
-                    const goalLower = scenario.goal.toLowerCase();
-                    const isFilterTask = /filter|under \$|over \$|\d+\+ (star|rating)|sort by|price range|less than/i.test(goalLower);
+                    const isFilterTask = /filter|under \$|over \$|\d+\+ (star|rating)|sort by|price range|less than/i.test(scenario.goal);
                     if (isFilterTask) {
-                        ctxBudget.add('filter-strategy', '\nFILTER STRATEGY: This goal requires filtering. If you are on the results page, ' +
-                            'use runScript to find filter controls: document.querySelectorAll(\'input[type="range"], select, [class*="filter"], [class*="price"], [class*="slider"]\'). ' +
-                            'Apply the filter, wait 2s, then extract results via runScript. ' +
-                            'Do NOT keep browsing — apply the filter and extract data NOW.\n', 80);
+                        ctxBudget.add('filter-strategy', '\nFILTER GOAL: use runScript to find filter controls, apply filter, extract results.\n', 80);
                     }
                 }
                 const searchResultsGuidance = buildSearchResultsGuidance(state, scenario.goal, scenario.allowedDomains);
@@ -294,11 +362,27 @@ export class AgentRunner {
                 if (visibleLinkRecommendation) {
                     ctxBudget.add('visible-link', `\n${visibleLinkRecommendation}\n`, 60);
                 }
-                const [scoutLinkRecommendation, branchLinkRecommendation, searchScoutFeedback] = await Promise.all([
-                    this.buildVisibleLinkScoutRecommendation(state, scenario.goal, scenario.allowedDomains),
-                    this.buildBranchLinkRecommendation(state, scenario.goal, scenario.allowedDomains),
-                    this.buildSearchResultsScoutFeedback(state, scenario.goal, scenario.allowedDomains, runState.searchScoutUrls),
-                ]);
+                // Gate scout calls: skip on early turns unless the agent appears
+                // stuck (same URL for 2+ consecutive turns). On early turns the agent
+                // is just navigating and doesn't need link recommendations.
+                const stuckOnSameUrl = turns.length >= 2 &&
+                    turns[turns.length - 1].state.url === turns[turns.length - 2].state.url;
+                const shouldScout = i >= 5 || stuckOnSameUrl;
+                let scoutLinkRecommendation;
+                let branchLinkRecommendation;
+                let searchScoutFeedback;
+                if (shouldScout) {
+                    [scoutLinkRecommendation, branchLinkRecommendation, searchScoutFeedback] = await Promise.all([
+                        this.buildVisibleLinkScoutRecommendation(state, scenario.goal, scenario.allowedDomains),
+                        this.buildBranchLinkRecommendation(state, scenario.goal, scenario.allowedDomains),
+                        this.buildSearchResultsScoutFeedback(state, scenario.goal, scenario.allowedDomains, runState.searchScoutUrls),
+                    ]);
+                }
+                else {
+                    scoutLinkRecommendation = undefined;
+                    branchLinkRecommendation = undefined;
+                    searchScoutFeedback = '';
+                }
                 if (scoutLinkRecommendation) {
                     ctxBudget.add('scout-link', `\n${buildScoutLinkRecommendationText(scoutLinkRecommendation)}\n`, 55);
                 }
@@ -368,7 +452,6 @@ export class AgentRunner {
                             };
                             turns.push(supervisorTurn);
                             this.onTurn?.(supervisorTurn);
-                            this.saveMemory();
                             return buildResult({
                                 success: false,
                                 reason,
@@ -409,7 +492,6 @@ export class AgentRunner {
                             turns.push(supervisorTurn);
                             this.onTurn?.(supervisorTurn);
                             if (runState.hasConsecutiveErrorThreshold) {
-                                this.saveMemory();
                                 return buildResult({
                                     success: false,
                                     reason: `${runState.consecutiveErrors} consecutive errors after supervisor action: ${actionError}`,
@@ -418,7 +500,6 @@ export class AgentRunner {
                                 });
                             }
                             if (runState.isErrorBudgetExhausted) {
-                                this.saveMemory();
                                 return buildResult({
                                     success: false,
                                     reason: `Error budget exhausted (${runState.totalErrors}/${runState.maxTotalErrors}) after supervisor action`,
@@ -458,12 +539,12 @@ export class AgentRunner {
                 // Check if last turn had a verification failure
                 const lastTurn = turns[turns.length - 1];
                 if (lastTurn?.verificationFailure) {
-                    ctxBudget.add('verification-failure', `\nVERIFICATION FAILED: ${lastTurn.verificationFailure}\nYour last action did NOT produce the expected effect. Try a different approach.\n`, 85);
+                    ctxBudget.add('verification-failure', `\nVERIFICATION FAILED: ${lastTurn.verificationFailure}. Try different approach.\n`, 85);
                 }
                 // Extraction guard: if the agent just ran a script that returned data,
                 // remind it to consider completing before navigating away.
                 if (lastTurn?.action.action === 'runScript' && !lastTurn.error) {
-                    ctxBudget.add('extraction-guard', '\nYou just extracted data with runScript. If this data answers the goal, use "complete" now instead of navigating away. Do not leave a page with useful data without attempting completion first.\n', 80);
+                    ctxBudget.add('extraction-guard', '\nData extracted. If it answers the goal, complete now.\n', 80);
                 }
                 const extraContext = ctxBudget.build();
                 const forceVision = shouldEscalateVision({
@@ -616,7 +697,30 @@ export class AgentRunner {
                         ...persistentSearchEvidence,
                     ];
                     if (shouldVerifyGoal) {
-                        goalResult = await this.brain.verifyGoalCompletion(state, scenario.goal, buildGoalVerificationClaim(action.result || '', verificationEvidence));
+                        // Fast-path: skip LLM verification when agent provides strong
+                        // evidence and had no recent errors. The detailed result text
+                        // (>50 chars) combined with script-extracted evidence means the
+                        // verifier almost always agrees — save the round-trip.
+                        const agentResult = action.result || '';
+                        const recentErrors = turns.slice(-2).filter(t => t.error).length;
+                        const hasScriptEvidence = verificationEvidence.some(e => e.startsWith('SCRIPT RESULT:'));
+                        const fastPathEligible = agentResult.length > 50 &&
+                            recentErrors === 0 &&
+                            hasScriptEvidence;
+                        if (fastPathEligible) {
+                            goalResult = {
+                                achieved: true,
+                                confidence: 0.9,
+                                evidence: ['Fast-path: agent provided detailed result with script-backed evidence and no recent errors.'],
+                                missing: [],
+                            };
+                            if (this.config.debug) {
+                                console.log('[Runner] Goal verification fast-path: skipped LLM call (strong evidence + no errors)');
+                            }
+                        }
+                        else {
+                            goalResult = await this.brain.verifyGoalCompletion(state, scenario.goal, buildGoalVerificationClaim(agentResult, verificationEvidence));
+                        }
                         if (this.config.debug) {
                             console.log(`[Runner] Goal verification: achieved=${goalResult.achieved}, confidence=${goalResult.confidence}`);
                         }
@@ -699,25 +803,10 @@ export class AgentRunner {
                             turn.verificationFailure = goalResult.missing.join('; ') || 'Goal verification failed';
                             runState.firstSufficientEvidenceTurn ??= i;
                             // Goal not met — reject completion and feed back what's missing
-                            const escalation = runState.verificationRejectionCount >= 3
-                                ? '\nFINAL WARNING: You have been rejected 3+ times. ' +
-                                    'Use runScript NOW to extract the EXACT data the goal asks for: ' +
-                                    'document.querySelector/querySelectorAll to get text content, prices, ratings, dates, etc. ' +
-                                    'Include the extracted data verbatim in your completion result. ' +
-                                    'The verification system trusts runScript evidence — use it.'
-                                : runState.verificationRejectionCount >= 2
-                                    ? '\nYou have been rejected multiple times. CHANGE YOUR STRATEGY: ' +
-                                        'Use runScript to extract the exact data needed: e.g., document.querySelector(".title").textContent. ' +
-                                        'Include ALL extracted data in your completion result. ' +
-                                        'If you need to prove a search was done, complete FROM the search results page. ' +
-                                        'The verifier trusts SCRIPT RESULT evidence — extract data programmatically.'
-                                    : '\nBefore trying again, ensure ALL required evidence is visible or extracted. ' +
-                                        'Use runScript to extract structured data if the a11y tree is incomplete. ' +
-                                        'Complete only when every requirement in the goal can be verified from the page state or extracted via script.';
-                            this.brain.injectFeedback(`COMPLETION REJECTED — goal verification failed (confidence: ${goalResult.confidence.toFixed(2)}).\n` +
-                                `Missing: ${goalResult.missing.join('; ')}\n` +
-                                `Evidence reviewed: ${goalResult.evidence.join('; ')}\n` +
-                                `The goal has NOT been achieved yet. Continue working.${escalation}`);
+                            const escalation = runState.verificationRejectionCount >= 2
+                                ? ' Use runScript to extract exact data and include in completion.'
+                                : '';
+                            this.brain.injectFeedback(`REJECTED (${goalResult.confidence.toFixed(2)}). Missing: ${goalResult.missing.join('; ')}.${escalation}`);
                             turn.durationMs = Date.now() - turnStart;
                             turns.push(turn);
                             this.onTurn?.(turn);
@@ -746,7 +835,6 @@ export class AgentRunner {
                         // Both gates passed
                         turns.push(turn);
                         this.onTurn?.(turn);
-                        this.saveMemory();
                         runState.firstSufficientEvidenceTurn ??= i;
                         return buildResult({
                             success: true,
@@ -766,7 +854,6 @@ export class AgentRunner {
                     // Goal verified (or skipped), no quality gate
                     turns.push(turn);
                     this.onTurn?.(turn);
-                    this.saveMemory();
                     runState.firstSufficientEvidenceTurn ??= i;
                     return buildResult({
                         success: true,
@@ -779,7 +866,6 @@ export class AgentRunner {
                 if (action.action === 'abort') {
                     turns.push(turn);
                     this.onTurn?.(turn);
-                    this.saveMemory();
                     return buildResult({
                         success: false,
                         reason: action.reason,
@@ -820,18 +906,16 @@ export class AgentRunner {
                 }
                 catch (err) {
                     if (err instanceof StaleRefError) {
-                        // Stale ref — re-observe and ask the Brain to pick a new ref
-                        // without burning a full turn. Feed back the fresh snapshot
-                        // so the Brain can immediately re-decide.
+                        // Stale ref — re-observe and cache for next turn (avoid double observe).
+                        // Only inject available refs, not the full snapshot — next turn's observe
+                        // provides the complete snapshot, so duplicating it here wastes 3-8k tokens.
                         if (this.config.debug) {
                             console.log(`[Runner] Stale ref @${err.staleRef} — re-observing for immediate retry`);
                         }
-                        const freshState = await this.driver.observe();
-                        this.brain.injectFeedback(`Your selector @${err.staleRef} was not found in the current page. ` +
+                        this.cachedPostState = await this.driver.observe();
+                        this.brain.injectFeedback(`Your selector @${err.staleRef} was not found. ` +
                             `Available refs: ${err.availableRefs.slice(0, 20).join(', ')}. ` +
-                            `Here is the FRESH page state — pick a valid ref:\n\n` +
-                            `URL: ${freshState.url}\nELEMENTS:\n${freshState.snapshot}`);
-                        // Let the loop continue — Brain sees feedback and next observe() has fresh refs.
+                            `Pick a valid ref from the next observation.`);
                         runState.recordError();
                         turn.error = `Stale ref @${err.staleRef} — auto-retrying`;
                         turn.durationMs = Date.now() - turnStart;
@@ -882,7 +966,8 @@ export class AgentRunner {
                     if (turn.error)
                         break;
                     try {
-                        const followResult = await withRetry(() => this.driver.execute(followUpAction), retries, retryDelayMs, (attempt, err) => {
+                        const followResult = await withRetry(() => this.driver.execute(followUpAction), 1, // Follow-ups are speculative micro-actions — fail fast, don't retry 3x
+                        retryDelayMs, (attempt, err) => {
                             if (this.config.debug) {
                                 console.log(`[Runner] Follow-up retry ${attempt}: ${err.message}`);
                             }
@@ -901,6 +986,7 @@ export class AgentRunner {
                 }
                 const domainBoundaryViolation = await this.enforceAllowedDomainBoundary(state, scenario);
                 if (domainBoundaryViolation) {
+                    this.cachedPostState = undefined; // boundary navigated back — invalidate cache
                     this.brain.injectFeedback(domainBoundaryViolation);
                     turn.error = domainBoundaryViolation;
                     turn.durationMs = Date.now() - turnStart;
@@ -959,7 +1045,6 @@ export class AgentRunner {
                 turns.push(turn);
                 this.onTurn?.(turn);
                 if (runState.hasConsecutiveErrorThreshold) {
-                    this.saveMemory();
                     return buildResult({
                         success: false,
                         reason: `${runState.consecutiveErrors} consecutive errors: ${error}`,
@@ -968,7 +1053,6 @@ export class AgentRunner {
                     });
                 }
                 if (runState.isErrorBudgetExhausted) {
-                    this.saveMemory();
                     return buildResult({
                         success: false,
                         reason: `Error budget exhausted (${runState.totalErrors}/${runState.maxTotalErrors} total errors): ${error}`,
@@ -981,8 +1065,6 @@ export class AgentRunner {
                 }
             }
         }
-        // Persist memory before returning
-        this.saveMemory();
         // Max turns reached
         return buildResult({
             success: false,
@@ -1014,9 +1096,12 @@ export class AgentRunner {
         }
         return selected;
     }
-    /** Persist knowledge and selector cache to disk */
-    saveMemory() {
+    /** Persist knowledge, selector cache, and session history to disk */
+    saveMemory(scenario, result) {
         try {
+            if (this.knowledge && scenario && result) {
+                this.knowledge.recordSession(buildSession(scenario, result));
+            }
             this.knowledge?.save();
             this.selectorCache?.save();
         }
@@ -1040,36 +1125,36 @@ export class AgentRunner {
      * - Generic text match -> check if text appears in snapshot
      */
     async verifyEffect(expectedEffect, preActionState) {
-        // Wait briefly for the effect to take hold
-        await new Promise(r => setTimeout(r, 500));
-        // Re-observe — this resets the refMap but that's OK since the next
-        // turn's observe() will rebuild it fresh before the brain decides.
-        const postState = await this.driver.observe().catch(() => preActionState);
-        // URL-based verification
+        // URL-based verification — no sleep needed, URL commits synchronously with navigation
         if (/url\s+should/i.test(expectedEffect)) {
+            const currentUrl = this.driver.getUrl?.() ?? (await this.driver.observe().catch(() => preActionState)).url;
             // Extract target: prefer quoted value (handles complex phrases like
             // "URL should change to include '/chat/'"), fall back to word after verb
             const quotedVal = expectedEffect.match(/['"]([^'"]+)['"]/);
             const verbVal = expectedEffect.match(/url\s+should\s+(?:contain|include|have)\s+(\S+)/i);
             const expected = quotedVal?.[1] ?? verbVal?.[1];
             if (expected) {
-                if (postState.url.includes(expected)) {
+                if (currentUrl.includes(expected)) {
                     return { verified: true };
                 }
                 return {
                     verified: false,
-                    reason: `Expected URL to contain "${expected}" but got "${postState.url}"`,
+                    reason: `Expected URL to contain "${expected}" but got "${currentUrl}"`,
                 };
             }
             // "URL should change" without a specific target — just check if URL changed
-            if (postState.url !== preActionState.url) {
+            if (currentUrl !== preActionState.url) {
                 return { verified: true };
             }
             return {
                 verified: false,
-                reason: `Expected URL to change but it stayed at "${postState.url}"`,
+                reason: `Expected URL to change but it stayed at "${currentUrl}"`,
             };
         }
+        // Non-URL effects: brief wait for DOM to settle, then observe
+        await new Promise(r => setTimeout(r, 100));
+        const postState = await this.driver.observe().catch(() => preActionState);
+        this.cachedPostState = postState;
         const effect = expectedEffect.toLowerCase();
         // Snapshot content verification (look for mentioned text/elements)
         // Extract quoted text from the expected effect
@@ -1209,16 +1294,16 @@ export class AgentRunner {
         const page = this.driver.getPage();
         if (!page)
             return undefined;
-        const previews = [];
-        for (const candidate of candidates) {
+        const settled = await Promise.all(candidates.map(async (candidate) => {
             const href = await this.driver.inspectSelectorHref(candidate.ref).catch(() => undefined);
             if (!href)
-                continue;
+                return undefined;
             const preview = await inspectBranchPreview(page, href, 8000);
             if (!preview)
-                continue;
-            previews.push({ ref: candidate.ref, text: candidate.text, href, score: scoreBranchPreview(goal, preview, allowedDomains), preview });
-        }
+                return undefined;
+            return { ref: candidate.ref, text: candidate.text, href, score: scoreBranchPreview(goal, preview, allowedDomains), preview };
+        }));
+        const previews = settled.filter((r) => r !== undefined);
         if (previews.length < 2)
             return undefined;
         previews.sort((a, b) => b.score - a.score);
@@ -1239,15 +1324,14 @@ export class AgentRunner {
             return candidates;
         }
         const allowedHosts = new Set(allowedDomains.map((domain) => domain.toLowerCase()));
-        const filtered = [];
-        for (const candidate of candidates) {
+        const resolved = await Promise.all(candidates.map(async (candidate) => {
             const href = await this.driver.inspectSelectorHref(candidate.ref).catch(() => undefined);
             const host = href ? safeHostname(href) : undefined;
-            if (!host || allowedHosts.has(host)) {
-                filtered.push(candidate);
-            }
-        }
-        return filtered;
+            return { candidate, host };
+        }));
+        return resolved
+            .filter(({ host }) => !host || allowedHosts.has(host))
+            .map(({ candidate }) => candidate);
     }
     async inspectDisallowedSearchClick(state, scenario, action) {
         if (action.action !== 'click')
@@ -1280,8 +1364,8 @@ export class AgentRunner {
     async enforceAllowedDomainBoundary(preActionState, scenario) {
         if (!scenario.allowedDomains || scenario.allowedDomains.length === 0)
             return undefined;
-        const postState = await this.driver.observe().catch(() => preActionState);
-        const currentHost = safeHostname(postState.url);
+        const currentUrl = this.driver.getUrl?.() ?? preActionState.url;
+        const currentHost = safeHostname(currentUrl);
         if (!currentHost)
             return undefined;
         const allowedHosts = scenario.allowedDomains.map((domain) => domain.toLowerCase());
@@ -1303,7 +1387,7 @@ export class AgentRunner {
             await this.driver.execute({ action: 'navigate', url: scenario.startUrl }).catch(() => { });
         }
         return [
-            `Boundary violation: landed on ${postState.url}, but the allowed host set is ${allowedHosts.join(', ')}.`,
+            `Boundary violation: landed on ${currentUrl}, but the allowed host set is ${allowedHosts.join(', ')}.`,
             'Return to an allowed host and continue from there; do not rely on disallowed subdomains even if their snippet looks relevant.',
         ].join(' ');
     }
@@ -1320,8 +1404,8 @@ export class AgentRunner {
     }
 }
 /** Convenience function */
-export async function runAgent(driver, scenario, options) {
-    const runner = new AgentRunner({ driver, ...options });
+export async function runBrowserAgent(driver, scenario, options) {
+    const runner = new BrowserAgent({ driver, ...options });
     return runner.run(scenario);
 }
 //# sourceMappingURL=runner.js.map