@tangle-network/browser-agent-driver 0.14.5 → 0.16.0

package/dist/runner/runner.js

@@ -31,6 +31,9 @@ import { detectAiTanglePartnerTemplateVisibleState, detectAiTangleVerifiedOutput
 import { shouldUseVisibleLinkScout, shouldUseVisibleLinkScoutPage, shouldUseBoundedBranchExplorer, inspectBranchPreview, scoreBranchPreview } from './scout.js';
 import { buildOverrideProducers, buildScoutLinkRecommendationText, buildBranchLinkRecommendationText } from './overrides.js';
 import { RunRegistry } from '../memory/run-registry.js';
+import { ensureBus } from './events.js';
+import { DecisionCache } from './decision-cache.js';
+import { matchDeterministicPattern } from './deterministic-patterns.js';
 /** Build a structured session record from a completed run */
 function buildSession(scenario, result) {
     const lastTurn = result.turns[result.turns.length - 1];
@@ -79,6 +82,14 @@ export class BrowserAgent {
     knowledge;
     selectorCache;
     cachedPostState;
+    bus;
+    currentRunId = '';
+    // In-session decision cache. Lazy-skips brain.decide() when the (snapshot,
+    // url, goal, last-effect, budget-bucket) is byte-identical to a previous
+    // turn in this run. The cache is fresh per `run()` invocation — never
+    // persists, never crosses runs.
+    decisionCache;
+    extensions;
     constructor(options) {
         this.driver = options.driver;
         this.config = options.config || {};
@@ -86,6 +97,17 @@ export class BrowserAgent {
         this.onTurn = options.onTurn;
         this.onPhaseTiming = options.onPhaseTiming;
         this.referenceTrajectory = options.referenceTrajectory;
+        this.bus = ensureBus(options.eventBus);
+        this.extensions = options.extensions;
+        if (this.extensions) {
+            // Forward extension-supplied prompt rules into the brain so they get
+            // included in every system prompt build. Domain-keyed rules are
+            // matched per-turn against the current URL inside composeSystemPromptParts.
+            this.brain.setExtensionRules(this.extensions.combinedRules, this.extensions.combinedDomainRules);
+            // Subscribe extensions to the event bus so onTurnEvent fires for
+            // every emitted event without callers having to wire it up.
+            this.bus.subscribe(this.extensions.fanOutTurnEvent, false);
+        }
         this.projectStore = options.projectStore;
         this.runRegistry = options.runRegistry;
     }
@@ -100,7 +122,19 @@ export class BrowserAgent {
         const runId = scenario.sessionId
             ? `${scenario.sessionId}_${Date.now()}`
             : RunRegistry.generateRunId();
+        this.currentRunId = runId;
         const domain = safeHostname(scenario.startUrl || '') || 'unknown';
+        // Emit run-started so subscribers (live viewer, events.jsonl sink) can
+        // initialize their state. The bus is a no-op when no eventBus was passed
+        // to the constructor, so this is free for non-live runs.
+        this.bus.emitNow({
+            type: 'run-started',
+            runId,
+            turn: 0,
+            goal: scenario.goal,
+            startUrl: scenario.startUrl,
+            maxTurns,
+        });
         const buildResult = (result) => {
             const agentResult = {
                 ...result,
@@ -118,6 +152,17 @@ export class BrowserAgent {
                 reason: agentResult.reason,
                 turnCount: agentResult.turns.length,
             });
+            // Emit run-completed so the live viewer can swap to a "finished" UI
+            // and the events.jsonl sink can flush its tail.
+            this.bus.emitNow({
+                type: 'run-completed',
+                runId,
+                turn: 0,
+                success: agentResult.success,
+                totalTurns: agentResult.turns.length,
+                totalMs: agentResult.totalMs,
+                ...(agentResult.reason ? { reason: agentResult.reason } : {}),
+            });
             return agentResult;
         };
         // Wrap onTurn to include mid-run manifest updates (every 3 turns)
@@ -138,6 +183,21 @@ export class BrowserAgent {
         this.brain.reset();
         this.cachedPostState = undefined;
         let executeTimeoutRecoveries = 0;
+        // Fresh decision cache per run. The cache is strictly in-session — page
+        // state changes silently between runs and a stale cached decision is a
+        // correctness landmine. Disable via BAD_DECISION_CACHE=0.
+        this.decisionCache = process.env.BAD_DECISION_CACHE === '0'
+            ? undefined
+            : new DecisionCache();
+        // Track the previous turn's expectedEffect so we can include it in the
+        // cache key. Empty string for turn 1.
+        let lastEffectForCacheKey = '';
+        // Pre-warm the provider connection in parallel with everything else.
+        // Without this, turn 1's first LLM call eats 600ms (Anthropic) to
+        // 1200ms (OpenAI) of cold-start TLS+DNS+HTTP/2 setup. By the time
+        // navigation + first observe complete, the connection pool is hot.
+        // Best-effort: failure is swallowed and turn 1 pays the cold-start.
+        const warmupPromise = this.brain.warmup();
         // 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.
@@ -153,6 +213,9 @@ export class BrowserAgent {
             phaseTimings.initialNavigateMs = Date.now() - navigateStartedAt;
             this.onPhaseTiming?.('navigate', phaseTimings.initialNavigateMs);
         }
+        // Don't wait on warmup before entering the loop — it races against the
+        // first observe and decode. Make sure any unhandled rejection is silenced.
+        void warmupPromise.catch(() => undefined);
         // Write run manifest at start
         this.runRegistry?.startRun({
             runId,
@@ -182,9 +245,17 @@ export class BrowserAgent {
                 });
             }
             const turnStart = Date.now();
+            this.bus.emitNow({ type: 'turn-started', runId, turn: i });
             try {
                 // -- 1. Check for recovery before observing --
-                if (turns.length >= 2) {
+                // Only run analyzeRecovery when there's a non-zero error trail. Used
+                // to run unconditionally; lazy-skipping it when there are no recent
+                // errors avoids the per-turn cost on the happy path. (Gen 5 lazy
+                // decision graph computation, change #20 in the pursuit spec.)
+                const hasErrorTrail = turns.length >= 2
+                    && (runState.consecutiveErrors > 0
+                        || turns.slice(-5).some((t) => t.error || t.verified === false));
+                if (hasErrorTrail) {
                     const lastState = turns[turns.length - 1]?.state || { url: '', title: '', snapshot: '' };
                     const recovery = analyzeRecovery({
                         recentTurns: turns.slice(-5),
@@ -192,6 +263,15 @@ export class BrowserAgent {
                         consecutiveErrors: runState.consecutiveErrors,
                     });
                     if (recovery) {
+                        const forcedActionLabel = recovery.forceBrowserAction?.action ?? recovery.forceAction;
+                        this.bus.emitNow({
+                            type: 'recovery-fired',
+                            runId,
+                            turn: i,
+                            strategy: recovery.strategy,
+                            feedback: recovery.feedback,
+                            ...(forcedActionLabel ? { forcedAction: forcedActionLabel } : {}),
+                        });
                         if (this.config.debug) {
                             const forced = recovery.forceBrowserAction
                                 ? ` (force: ${recovery.forceBrowserAction.action})`
@@ -242,6 +322,7 @@ export class BrowserAgent {
                 // -- 2. Observe (with retry) --
                 // Reuse the snapshot from verifyEffect if available (no page mutations between them)
                 const observeStartedAt = Date.now();
+                this.bus.emitNow({ type: 'observe-started', runId, turn: i });
                 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) {
@@ -249,10 +330,29 @@ export class BrowserAgent {
                     }
                 }, scenario.signal);
                 this.cachedPostState = undefined;
+                const observeDurationMs = Date.now() - observeStartedAt;
                 if (phaseTimings.firstObserveMs === undefined) {
-                    phaseTimings.firstObserveMs = Date.now() - observeStartedAt;
+                    phaseTimings.firstObserveMs = observeDurationMs;
                     this.onPhaseTiming?.('observe', phaseTimings.firstObserveMs);
                 }
+                // Snapshot bytes only — never wire the full snapshot, it's huge.
+                // Screenshot data URL travels through observe-completed when vision
+                // is on so the live viewer can render it without a separate fetch.
+                const screenshotDataUrl = state.screenshot
+                    ? (state.screenshot.startsWith('data:')
+                        ? state.screenshot
+                        : `data:image/jpeg;base64,${state.screenshot}`)
+                    : undefined;
+                this.bus.emitNow({
+                    type: 'observe-completed',
+                    runId,
+                    turn: i,
+                    url: state.url,
+                    title: state.title,
+                    snapshotBytes: state.snapshot.length,
+                    ...(screenshotDataUrl ? { screenshot: screenshotDataUrl } : {}),
+                    durationMs: observeDurationMs,
+                });
                 // Auto-navigate: if we're on about:blank with a startUrl, navigate without
                 // consuming an LLM turn. The agent always does wait->navigate on blank pages.
                 if (state.url === 'about:blank' &&
@@ -571,18 +671,106 @@ export class BrowserAgent {
                 const decisionState = forceVision
                     ? await this.attachDecisionScreenshot(state)
                     : state;
-                // -- 4. Decide (with retry) --
+                // -- 4. Decide (deterministic patterns → cache → LLM) --
                 const decideStartedAt = Date.now();
-                const decision = await withRetry(() => this.brain.decide(scenario.goal, decisionState, finalExtraContext || undefined, { current: i, max: maxTurns }, { forceVision }), retries, retryDelayMs, (attempt, err) => {
+                this.bus.emitNow({ type: 'decide-started', runId, turn: i });
+                // Lazy decisions, level 1: deterministic UI pattern matching. If the
+                // page is a recognized pattern (cookie banner with single Accept,
+                // single-button modal close), the action is obvious and we skip the
+                // LLM entirely. Pattern matchers are bypassed under the same
+                // conditions as the cache below.
+                const previousTurn = turns[turns.length - 1];
+                const canSkipDecide = !forceVision
+                    && !finalExtraContext
+                    && !previousTurn?.error
+                    && !previousTurn?.verificationFailure
+                    && process.env.BAD_PATTERN_SKIP !== '0';
+                let patternMatch = null;
+                if (canSkipDecide) {
+                    patternMatch = matchDeterministicPattern(decisionState);
+                }
+                // Lazy decisions, level 2: in-session decision cache.
+                const canUseCache = this.decisionCache !== undefined
+                    && canSkipDecide
+                    && !patternMatch;
+                const cacheKey = canUseCache
+                    ? {
+                        snapshotHash: DecisionCache.hashSnapshot(decisionState.snapshot),
+                        url: decisionState.url,
+                        goal: scenario.goal,
+                        lastEffect: lastEffectForCacheKey,
+                        budgetBucket: DecisionCache.budgetBucket(i, maxTurns),
+                    }
+                    : undefined;
+                const cached = canUseCache && cacheKey
+                    ? this.decisionCache.get(cacheKey)
+                    : undefined;
+                let decision;
+                if (patternMatch) {
+                    // Pattern match — synthesize a decision, no LLM call.
+                    decision = {
+                        action: patternMatch.action,
+                        raw: '[deterministic-pattern]',
+                        reasoning: patternMatch.reasoning,
+                        expectedEffect: patternMatch.expectedEffect,
+                        tokensUsed: 0,
+                        inputTokens: 0,
+                        outputTokens: 0,
+                    };
+                    this.bus.emitNow({
+                        type: 'decide-skipped-pattern',
+                        runId,
+                        turn: i,
+                        action: decision.action,
+                        patternId: patternMatch.patternId,
+                    });
                     if (this.config.debug) {
-                        console.log(`[Runner] LLM retry ${attempt}: ${err.message}`);
+                        console.log(`[Runner] Pattern SKIP (${patternMatch.patternId}, turn ${i}) — skipping LLM`);
                     }
-                }, scenario.signal);
+                }
+                else if (cached) {
+                    // Cache hit — replay the decision, no LLM call.
+                    decision = cached.decision;
+                    this.bus.emitNow({
+                        type: 'decide-skipped-cached',
+                        runId,
+                        turn: i,
+                        action: decision.action,
+                        cacheKey: cached.hash,
+                    });
+                    if (this.config.debug) {
+                        console.log(`[Runner] Decision cache HIT (turn ${i}, key ${cached.hash.slice(0, 8)}…) — skipping LLM`);
+                    }
+                }
+                else {
+                    decision = await withRetry(() => this.brain.decide(scenario.goal, decisionState, finalExtraContext || undefined, { current: i, max: maxTurns }, { forceVision }), retries, retryDelayMs, (attempt, err) => {
+                        if (this.config.debug) {
+                            console.log(`[Runner] LLM retry ${attempt}: ${err.message}`);
+                        }
+                    }, scenario.signal);
+                    if (cacheKey && this.decisionCache) {
+                        // Store the fresh decision so a future identical turn replays it.
+                        this.decisionCache.set(cacheKey, decision);
+                    }
+                }
+                const decideDurationMs = Date.now() - decideStartedAt;
                 if (phaseTimings.firstDecideMs === undefined) {
-                    phaseTimings.firstDecideMs = Date.now() - decideStartedAt;
+                    phaseTimings.firstDecideMs = decideDurationMs;
                     this.onPhaseTiming?.('decide', phaseTimings.firstDecideMs);
                 }
-                let { action, nextActions, raw, reasoning, plan, currentStep, expectedEffect, tokensUsed, inputTokens, outputTokens, modelUsed } = decision;
+                let { action, nextActions, raw, reasoning, plan, currentStep, expectedEffect, tokensUsed, inputTokens, outputTokens, cacheReadInputTokens, cacheCreationInputTokens, modelUsed } = decision;
+                this.bus.emitNow({
+                    type: 'decide-completed',
+                    runId,
+                    turn: i,
+                    action,
+                    ...(reasoning ? { reasoning } : {}),
+                    ...(expectedEffect ? { expectedEffect } : {}),
+                    ...(inputTokens !== undefined ? { inputTokens } : {}),
+                    ...(outputTokens !== undefined ? { outputTokens } : {}),
+                    ...(cacheReadInputTokens !== undefined ? { cacheReadInputTokens } : {}),
+                    durationMs: decideDurationMs,
+                });
                 // -- 4b. Override pipeline — scored selection of post-decision overrides --
                 const overrideCtx = {
                     state,
@@ -602,6 +790,42 @@ export class BrowserAgent {
                     reasoning = `${reasoning}\n[${overrideWinner.reasoningTag}] ${overrideWinner.feedback}`;
                     expectedEffect = overrideWinner.expectedEffect;
                     nextActions = [];
+                    this.bus.emitNow({
+                        type: 'override-applied',
+                        runId,
+                        turn: i,
+                        source: 'override-pipeline',
+                        reasoningTag: overrideWinner.reasoningTag,
+                        feedback: overrideWinner.feedback,
+                    });
+                }
+                // -- 4c. User extension mutateDecision (final say) --
+                // Runs AFTER the built-in override pipeline so user extensions can
+                // veto or replace any decision the built-ins might have produced.
+                // Mutations are emitted as override events on the bus for audit.
+                if (this.extensions?.applyMutateDecision) {
+                    const mutated = this.extensions.applyMutateDecision({ ...decision, action, reasoning, expectedEffect }, {
+                        goal: scenario.goal,
+                        turn: i,
+                        maxTurns,
+                        state: decisionState,
+                        ...(turns[turns.length - 1]?.error
+                            ? { lastError: turns[turns.length - 1].error }
+                            : {}),
+                    });
+                    if (mutated.mutated) {
+                        action = mutated.decision.action;
+                        reasoning = mutated.decision.reasoning ?? reasoning;
+                        expectedEffect = mutated.decision.expectedEffect ?? expectedEffect;
+                        this.bus.emitNow({
+                            type: 'override-applied',
+                            runId,
+                            turn: i,
+                            source: 'extension',
+                            reasoningTag: mutated.sources.join(','),
+                            feedback: 'extension mutateDecision applied',
+                        });
+                    }
                 }
                 const turn = {
                     turn: i,
@@ -615,6 +839,8 @@ export class BrowserAgent {
                     tokensUsed,
                     inputTokens,
                     outputTokens,
+                    cacheReadInputTokens,
+                    cacheCreationInputTokens,
                     modelUsed,
                     durationMs: Date.now() - turnStart,
                 };
@@ -892,8 +1118,9 @@ export class BrowserAgent {
                 // where withOverlayRecovery × withRetry multiplied a 22s timeout to 135s).
                 const executeWallClockMs = 45_000;
                 let execResult;
+                const executeStartedAt = Date.now();
+                this.bus.emitNow({ type: 'execute-started', runId, turn: i, action });
                 try {
-                    const executeStartedAt = Date.now();
                     const executePromise = withRetry(() => this.driver.execute(action), retries, retryDelayMs, (attempt, err) => {
                         if (this.config.debug) {
                             console.log(`[Runner] Execute retry ${attempt}: ${err.message}`);
@@ -905,8 +1132,27 @@ export class BrowserAgent {
                         phaseTimings.firstExecuteMs = Date.now() - executeStartedAt;
                         this.onPhaseTiming?.('execute', phaseTimings.firstExecuteMs);
                     }
+                    this.bus.emitNow({
+                        type: 'execute-completed',
+                        runId,
+                        turn: i,
+                        action,
+                        success: execResult.success,
+                        ...(execResult.error ? { error: execResult.error } : {}),
+                        ...(execResult.bounds ? { bounds: execResult.bounds } : {}),
+                        durationMs: Date.now() - executeStartedAt,
+                    });
                 }
                 catch (err) {
+                    this.bus.emitNow({
+                        type: 'execute-completed',
+                        runId,
+                        turn: i,
+                        action,
+                        success: false,
+                        error: err instanceof Error ? err.message : String(err),
+                        durationMs: Date.now() - executeStartedAt,
+                    });
                     if (err instanceof StaleRefError) {
                         // Stale ref — re-observe and cache for next turn (avoid double observe).
                         // Only inject available refs, not the full snapshot — next turn's observe
@@ -1029,7 +1275,9 @@ export class BrowserAgent {
                 }
                 // -- 8. Post-action verification --
                 if (expectedEffect && !turn.error) {
-                    const verifyResult = await this.verifyEffect(expectedEffect, state);
+                    const verifyStartedAt = Date.now();
+                    this.bus.emitNow({ type: 'verify-started', runId, turn: i, expectedEffect });
+                    const verifyResult = await this.verifyEffect(expectedEffect, state, action.action);
                     turn.verified = verifyResult.verified;
                     if (!verifyResult.verified) {
                         turn.verificationFailure = verifyResult.reason;
@@ -1040,6 +1288,24 @@ export class BrowserAgent {
                     else if (this.config.debug) {
                         console.log(`[Runner] Verification passed`);
                     }
+                    this.bus.emitNow({
+                        type: 'verify-completed',
+                        runId,
+                        turn: i,
+                        verified: verifyResult.verified,
+                        ...(verifyResult.reason ? { reason: verifyResult.reason } : {}),
+                        durationMs: Date.now() - verifyStartedAt,
+                    });
+                }
+                else if (!turn.error
+                    && !this.cachedPostState
+                    && (action.action === 'wait' || action.action === 'scroll')
+                    && executedActions.length === 1) {
+                    // Pure wait/scroll with no expectedEffect: the ARIA tree didn't
+                    // structurally change. Reuse preActionState as the cached post-state
+                    // so the next loop iteration's observe is skipped. The driver's
+                    // refMap is still valid because no observe has reset it.
+                    this.cachedPostState = state;
                 }
                 if (executedActions.length > 1) {
                     turn.executedActions = executedActions;
@@ -1047,6 +1313,12 @@ export class BrowserAgent {
                 turn.durationMs = Date.now() - turnStart;
                 turns.push(turn);
                 this.onTurn?.(turn);
+                this.bus.emitNow({ type: 'turn-completed', runId, turn: i, turnArtifact: turn });
+                // Stash the expectedEffect so the NEXT turn's cache key includes it.
+                // The post-action page state depends on what the agent claimed would
+                // happen, so two turns with the same snapshot but different last
+                // effects might warrant different decisions.
+                lastEffectForCacheKey = expectedEffect ?? '';
             }
             catch (err) {
                 runState.recordError();
@@ -1153,9 +1425,28 @@ export class BrowserAgent {
      * - "text should appear" -> check snapshot
      * - Generic text match -> check if text appears in snapshot
      */
-    async verifyEffect(expectedEffect, preActionState) {
-        await new Promise(r => setTimeout(r, 100));
-        const postState = await this.driver.observe().catch(() => preActionState);
+    async verifyEffect(expectedEffect, preActionState, actionType) {
+        // Only pause for actions that mutate the page in flight (navigation,
+        // clicks that may trigger XHR/route transitions, form submits). For
+        // pure reads, scrolls, hovers, and waits the page state is already
+        // settled by the time execute returns. The previous unconditional
+        // 100ms wait was pure dead time on every turn.
+        const needsSettleWait = actionType === 'click'
+            || actionType === 'navigate'
+            || actionType === 'press'
+            || actionType === 'select';
+        // Kick observe off immediately and let the settle wait race against it.
+        // observe() polls waitForLoadState internally, so the 50ms settle is
+        // really only there to let click handlers schedule their first XHR; we
+        // don't need to *block* on it before starting observe.
+        const observePromise = this.driver.observe().catch(() => preActionState);
+        if (needsSettleWait) {
+            await Promise.all([
+                observePromise,
+                new Promise(r => setTimeout(r, 50)),
+            ]);
+        }
+        const postState = await observePromise;
         this.cachedPostState = postState;
         return verifyExpectedEffect({
             expectedEffect,