@tangle-network/browser-agent-driver 0.15.0 → 0.16.1

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,15 @@ 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
@@ -191,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),
@@ -201,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})`
@@ -251,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) {
@@ -258,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' &&
@@ -403,18 +494,23 @@ export class BrowserAgent {
                 if (searchScoutFeedback) {
                     ctxBudget.add('search-scout', `\n${searchScoutFeedback}\n`, 50);
                 }
-                const supervisorSignal = detectSupervisorSignal({
-                    recentTurns: turns,
-                    currentState: state,
-                    currentTurn: i,
-                    maxTurns,
-                    window: supervisorConfig.hardStallWindow,
-                });
-                const shouldInvokeSupervisor = supervisorConfig.enabled &&
-                    supervisorSignal.severity === 'hard' &&
+                // Lazy supervisor signal: only compute when supervisor is enabled
+                // AND we're past the minimum-turns gate. Used to run unconditionally
+                // every turn even when supervisor was disabled. Gen 5 evolve round 1.
+                const supervisorEligible = supervisorConfig.enabled &&
                     i >= supervisorConfig.minTurnsBeforeInvoke &&
                     runState.supervisorInterventions < supervisorConfig.maxInterventions &&
                     i - runState.lastSupervisorTurn > supervisorConfig.cooldownTurns;
+                const supervisorSignal = supervisorEligible
+                    ? detectSupervisorSignal({
+                        recentTurns: turns,
+                        currentState: state,
+                        currentTurn: i,
+                        maxTurns,
+                        window: supervisorConfig.hardStallWindow,
+                    })
+                    : { severity: 'none', reasons: [] };
+                const shouldInvokeSupervisor = supervisorEligible && supervisorSignal.severity === 'hard';
                 if (shouldInvokeSupervisor) {
                     if (this.config.debug) {
                         console.log(`[Runner] Supervisor invoked on turn ${i}: ${formatSupervisorSignal(supervisorSignal)}`);
@@ -580,18 +676,121 @@ 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.
+                //
+                // Patterns look at the SNAPSHOT TEXT only — they don't care about
+                // extraContext, persona injection, vision strategy, or anything
+                // else the LLM would consume. A cookie banner is a cookie banner
+                // regardless of what the goal text says or whether the screenshot
+                // is attached. So the only gate is "did the previous turn fail" —
+                // if so, give the LLM a chance to course-correct instead of
+                // mechanically retrying the same pattern action.
+                const previousTurn = turns[turns.length - 1];
+                const canPatternSkip = !previousTurn?.error
+                    && !previousTurn?.verificationFailure
+                    && process.env.BAD_PATTERN_SKIP !== '0';
+                let patternMatch = null;
+                if (canPatternSkip) {
+                    patternMatch = matchDeterministicPattern(decisionState);
+                }
+                // Lazy decisions, level 2: in-session decision cache.
+                //
+                // The cache DOES care about extraContext: a cached decision was
+                // made under one set of context inputs, and replaying it under a
+                // different set could be wrong. Include the extraContext check
+                // here so the cache only fires when the LLM input would have been
+                // the same shape.
+                const canUseCache = this.decisionCache !== undefined
+                    && canPatternSkip
+                    && !patternMatch
+                    && !finalExtraContext;
+                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, cacheReadInputTokens, cacheCreationInputTokens, modelUsed } = decision;
+                // Only emit decide-completed when the LLM was actually called.
+                // Pattern matches and cache hits already emitted their own
+                // decide-skipped-* event above; double-emitting decide-completed
+                // would inflate the LLM-call count for analytics.
+                if (!patternMatch && !cached) {
+                    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,
@@ -604,13 +803,59 @@ export class BrowserAgent {
                     aiTanglePartnerCompletion: aiTanglePartnerCompletion ?? undefined,
                     aiTangleOutputCompletion: aiTangleOutputCompletion ?? undefined,
                 };
-                const overrideWinner = runOverridePipeline(overrideCtx, buildOverrideProducers());
+                // Lazy override pipeline: only run when at least one input that any
+                // producer might consume is non-null. Skipping when there's nothing
+                // to override avoids the producer-list iteration on the happy path.
+                const anyOverrideInput = visibleLinkMatch !== undefined ||
+                    scoutLinkRecommendation !== undefined ||
+                    branchLinkRecommendation !== undefined ||
+                    aiTanglePartnerCompletion !== null ||
+                    aiTangleOutputCompletion !== null;
+                const overrideWinner = anyOverrideInput
+                    ? runOverridePipeline(overrideCtx, buildOverrideProducers())
+                    : null;
                 if (overrideWinner) {
                     this.brain.injectFeedback(overrideWinner.feedback);
                     action = overrideWinner.action;
                     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,
@@ -903,8 +1148,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}`);
@@ -916,8 +1162,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
@@ -1040,6 +1305,8 @@ export class BrowserAgent {
                 }
                 // -- 8. Post-action verification --
                 if (expectedEffect && !turn.error) {
+                    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) {
@@ -1051,6 +1318,14 @@ 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
@@ -1068,6 +1343,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();