@tangle-network/browser-agent-driver 0.24.2 → 0.26.0

package/dist/runner/overlay-narration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-narration.js","sourceRoot":"","sources":["../../src/runner/overlay-narration.ts"],"names":[],"mappings":"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"}

package/dist/runner/runner.d.ts

@@ -45,6 +45,14 @@ export interface BrowserAgentOptions {
     config?: AgentConfig;
     /** Called after each turn */
     onTurn?: (turn: Turn) => void;
+    /**
+     * Gen 32 — called at the top of every turn BEFORE observe().
+     * Used by the interrupt controller to block the loop while the user
+     * has the run paused (`p` keypress in an interactive attach). The
+     * promise resolves on resume or rejects with an abort signal to
+     * bail out cleanly.
+     */
+    beforeTurn?: (turn: number) => Promise<void>;
     /** Called when a first-time phase timing is observed */
     onPhaseTiming?: (phase: 'navigate' | 'observe' | 'decide' | 'execute', durationMs: number) => void;
     /** Reference trajectory to inject into brain context */
@@ -120,6 +128,7 @@ export declare class BrowserAgent {
     private brain;
     private config;
     private onTurn?;
+    private beforeTurn?;
     private onPhaseTiming?;
     private referenceTrajectory?;
     private projectStore?;

package/dist/runner/runner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/runner/runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/runner/runner.ts"],"names":[],"mappings":"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"}

package/dist/runner/runner.js

@@ -34,6 +34,7 @@ import { buildOverrideProducers, buildScoutLinkRecommendationText, buildBranchLi
 import { RunRegistry } from '../memory/run-registry.js';
 import { ensureBus } from './events.js';
 import { DecisionCache } from './decision-cache.js';
+import { VerdictTracker, extractCurrentMarker, buildProgressLabel, } from './overlay-narration.js';
 import { matchDeterministicPattern } from './deterministic-patterns.js';
 /**
  * Gen 6.1: detect that the agent is filling a multi-field form one input at
@@ -245,6 +246,7 @@ export class BrowserAgent {
     brain;
     config;
     onTurn;
+    beforeTurn;
     onPhaseTiming;
     referenceTrajectory;
     projectStore;
@@ -267,6 +269,7 @@ export class BrowserAgent {
         this.config = options.config || {};
         this.brain = new Brain(this.config);
         this.onTurn = options.onTurn;
+        this.beforeTurn = options.beforeTurn;
         this.onPhaseTiming = options.onPhaseTiming;
         this.referenceTrajectory = options.referenceTrajectory;
         this.bus = ensureBus(options.eventBus);
@@ -650,7 +653,26 @@ export class BrowserAgent {
                 }
             }
         }
+        // Gen 32 — overlay narration tracker. Per-session; accumulates verdict
+        // markers so a ledger the agent keeps re-emitting doesn't spam badges.
+        const verdictTracker = new VerdictTracker();
         for (let i = 1 + plannerStartTurn; i <= maxTurns; i++) {
+            // Gen 32 — honor user-driven pause from the interrupt controller.
+            // Blocks until `r` is pressed (resume) or `q` is pressed (abort).
+            // A rejected beforeTurn is treated as an abort.
+            if (this.beforeTurn) {
+                try {
+                    await this.beforeTurn(i);
+                }
+                catch (err) {
+                    return buildResult({
+                        success: false,
+                        reason: err instanceof Error ? err.message : 'aborted',
+                        turns,
+                        totalMs: Date.now() - startTime,
+                    });
+                }
+            }
             if (scenario.signal?.aborted) {
                 return buildResult({
                     success: false,
@@ -1255,6 +1277,30 @@ export class BrowserAgent {
                         durationMs: decideDurationMs,
                     });
                 }
+                // -- 4a. Gen 32 — narrate to the cursor overlay. Fire-and-forget.
+                // Four signals pushed to the page-context overlay so a viewer of
+                // the recorded video can READ the agent's work, not just watch it:
+                //   1. Reasoning panel (top-right) — the agent's own text
+                //   2. Progress bar + chip (top) — turn N with optional ledger marker
+                //   3. Verdict badges (bottom-left) — POSITIVE/CLEARED/REVIEW events
+                // All methods are no-ops when the overlay is disabled, and all page
+                // calls are wrapped by the driver so a navigation race here can
+                // never bubble up and break the run.
+                try {
+                    if (this.driver.setOverlayReasoning) {
+                        void this.driver.setOverlayReasoning(reasoning ?? '');
+                    }
+                    if (this.driver.setOverlayProgress) {
+                        const marker = extractCurrentMarker(reasoning);
+                        void this.driver.setOverlayProgress(i, maxTurns, buildProgressLabel(i, maxTurns, marker));
+                    }
+                    if (this.driver.pushOverlayBadge) {
+                        const fresh = verdictTracker.accept(reasoning);
+                        for (const v of fresh)
+                            void this.driver.pushOverlayBadge(v.kind, v.text);
+                    }
+                }
+                catch { /* overlay narration is cosmetic; never let it break a run */ }
                 // -- 4b. Override pipeline — scored selection of post-decision overrides --
                 const overrideCtx = {
                     state,
@@ -1444,6 +1490,53 @@ export class BrowserAgent {
                     this.onTurn?.(turn);
                     continue;
                 }
+                // -- Gen 33: mid-run parallel fan-out. Agent picked N candidates
+                // from the current page and wants to explore each in its own tab.
+                // We spawn sub-agents in the same BrowserContext, collect their
+                // verdicts, and inject the merged result as feedback for the next
+                // turn. Parent page state is untouched.
+                if (action.action === 'fanOut') {
+                    const page = this.driver.getPage?.();
+                    const context = page?.context();
+                    if (!context) {
+                        this.brain.injectFeedback('FAN-OUT ERROR: driver does not expose a BrowserContext — fanOut only works with the Playwright driver.');
+                        turn.durationMs = Date.now() - turnStart;
+                        turns.push(turn);
+                        this.onTurn?.(turn);
+                        continue;
+                    }
+                    const { executeFanOut } = await import('./fan-out.js');
+                    const topDriverOptions = this.driver.getDriverOptions?.();
+                    const fanOutResult = await executeFanOut(action, {
+                        context,
+                        config: this.config,
+                        currentUrl: state.url,
+                        ...(topDriverOptions
+                            ? { driverOptions: (() => { const { showCursor: _sc, ...rest } = topDriverOptions; return rest; })() }
+                            : {}),
+                        ...(this.projectStore ? { projectStore: this.projectStore } : {}),
+                        ...(this.macroPromptBlock ? { macroPromptBlock: this.macroPromptBlock } : {}),
+                        onBranchStart: (_idx, label) => {
+                            // Fire and forget — this is purely cosmetic narration on
+                            // the overlay. Errors are swallowed by the driver.
+                            if (this.driver.setOverlayReasoning) {
+                                void this.driver.setOverlayReasoning(`Fan-out: launching ${label}…`);
+                            }
+                        },
+                    });
+                    // Nice-to-have: surface fan-out completion as a badge moment so
+                    // the viewer sees the parallel exploration punctuated clearly.
+                    if (this.driver.pushOverlayBadge) {
+                        const ok = fanOutResult.branches.filter((b) => b.success).length;
+                        const total = fanOutResult.branches.length;
+                        void this.driver.pushOverlayBadge(ok === total ? 'cleared' : ok === 0 ? 'review' : 'info', `Fan-out · ${ok}/${total} branches ok`);
+                    }
+                    this.brain.injectFeedback(fanOutResult.feedback);
+                    turn.durationMs = Date.now() - turnStart;
+                    turns.push(turn);
+                    this.onTurn?.(turn);
+                    continue;
+                }
                 // -- 6. Check for terminal actions --
                 if (action.action === 'complete') {
                     // Step 1: Goal verification — did the agent actually achieve the goal?