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

package/dist/runner/interrupt-controller.js

@@ -0,0 +1,142 @@
+/**
+ * Gen 32 — pause / resume / abort via keyboard in interactive runs.
+ *
+ * Registers a raw-mode stdin handler that maps three keys:
+ *
+ *   p   → pause the runner before the next turn
+ *   r   → resume a paused run
+ *   q   → abort (the same as Ctrl-C, but doesn't kill the TTY)
+ *
+ * The controller exposes a single `waitIfPaused()` the runner awaits at
+ * the top of every turn. When the user hits `p`, the next call blocks
+ * on a resume promise. On `r`, the promise resolves and the loop
+ * continues. On `q`, it throws an abort signal the runner treats as a
+ * graceful cancellation.
+ *
+ * Design notes:
+ *   - Raw mode only applies to a TTY. Non-interactive runs (CI,
+ *     `bad --cases ... --json`) never engage this controller.
+ *   - Keyboard capture is OPT-IN via `--interrupt`. Without it, the
+ *     stdin is untouched and this module is a no-op.
+ *   - Keyboard capture deliberately does NOT interfere with copy/paste
+ *     — we only listen for the specific bytes `p`, `r`, `q`, and let
+ *     everything else fall through unmodified.
+ */
+import { EventEmitter } from 'node:events';
+export class InterruptAborted extends Error {
+    constructor() {
+        super('run aborted by user (pressed q)');
+        this.name = 'InterruptAborted';
+    }
+}
+export class InterruptController extends EventEmitter {
+    paused = false;
+    aborted = false;
+    resumeResolvers = [];
+    input;
+    onStatus;
+    attached = false;
+    handler = (buf) => this.onKey(buf);
+    prevRaw = false;
+    constructor(opts = {}) {
+        super();
+        this.input = opts.input ?? process.stdin;
+        this.onStatus = opts.onStatus ?? (() => { });
+    }
+    /**
+     * Start listening for keystrokes. Returns a detach function the
+     * caller MUST invoke when the run ends (even on error) — otherwise
+     * stdin stays in raw mode and the TTY is hosed.
+     */
+    attach() {
+        if (this.attached)
+            return () => this.detach();
+        if (!this.input.isTTY)
+            return () => { };
+        this.prevRaw = this.input.isRaw;
+        this.input.setRawMode(true);
+        this.input.resume();
+        this.input.on('data', this.handler);
+        this.attached = true;
+        this.onStatus('interrupt keys: [p] pause · [r] resume · [q] abort');
+        return () => this.detach();
+    }
+    detach() {
+        if (!this.attached)
+            return;
+        try {
+            this.input.off('data', this.handler);
+            this.input.setRawMode(this.prevRaw);
+            if (!process.stdin.isTTY || !this.prevRaw) {
+                this.input.pause();
+            }
+        }
+        catch { /* best-effort on shutdown */ }
+        this.attached = false;
+        // Release any awaiters so the runner can unwind.
+        for (const r of this.resumeResolvers)
+            r();
+        this.resumeResolvers = [];
+    }
+    /**
+     * Called from the runner at the top of each turn. If the run is paused,
+     * awaits resume. If aborted, throws `InterruptAborted`.
+     */
+    async waitIfPaused() {
+        if (this.aborted)
+            throw new InterruptAborted();
+        if (!this.paused)
+            return;
+        await new Promise((resolve) => this.resumeResolvers.push(resolve));
+        if (this.aborted)
+            throw new InterruptAborted();
+    }
+    /** Programmatically pause — useful from tests and SIGUSR1 handlers. */
+    pause() {
+        if (this.paused || this.aborted)
+            return;
+        this.paused = true;
+        this.emit('pause');
+        this.onStatus('⏸  paused — press [r] to resume or [q] to abort');
+    }
+    /** Programmatically resume. */
+    resume() {
+        if (!this.paused || this.aborted)
+            return;
+        this.paused = false;
+        this.emit('resume');
+        this.onStatus('▶  resumed');
+        for (const r of this.resumeResolvers)
+            r();
+        this.resumeResolvers = [];
+    }
+    /** Request a graceful abort. */
+    abort() {
+        if (this.aborted)
+            return;
+        this.aborted = true;
+        this.emit('abort');
+        this.onStatus('■  aborting — run will stop at the end of this turn');
+        for (const r of this.resumeResolvers)
+            r();
+        this.resumeResolvers = [];
+    }
+    get isPaused() { return this.paused; }
+    get isAborted() { return this.aborted; }
+    onKey(buf) {
+        // Match a single byte for p/r/q; fall through for everything else.
+        // Ctrl-C (0x03) from raw mode — forward as abort, else the process stays alive.
+        if (buf.length === 1 && buf[0] === 0x03) {
+            this.abort();
+            return;
+        }
+        const ch = buf.toString('utf-8');
+        if (ch === 'p' || ch === 'P')
+            this.pause();
+        else if (ch === 'r' || ch === 'R')
+            this.resume();
+        else if (ch === 'q' || ch === 'Q')
+            this.abort();
+    }
+}
+//# sourceMappingURL=interrupt-controller.js.map

package/dist/runner/interrupt-controller.js.map

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

package/dist/runner/overlay-narration.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Gen 32 — agent narration hooks for the cursor overlay.
+ *
+ * The runner emits `decide-completed` each turn with the LLM's raw
+ * reasoning text. That text carries three distinct signals the overlay
+ * wants to surface to a viewer:
+ *
+ *   1. **Current step** — a short phrase summarizing what the agent is
+ *      about to do. Extracted from the first sentence of `reasoning`.
+ *   2. **Progress** — turn N of maxTurns, plus any inline progress
+ *      ledger (`Done=[C-001, C-002, ...] Current=C-003`) the agent is
+ *      already using in OFAC/batch-style prompts.
+ *   3. **Verdict moments** — conclusions like "POSITIVE MATCH",
+ *      "CLEARED", "NEEDS REVIEW" that should fire a celebratory badge.
+ *
+ * These are pure functions — no I/O, no driver calls. The driver-facing
+ * hooks in runner.ts call them, then push results via
+ * `driver.setOverlayReasoning` / `setOverlayProgress` / `pushOverlayBadge`.
+ *
+ * Why a separate module: the runner is already 1500+ lines and dense;
+ * parsing logic belongs somewhere testable in isolation. Keeping this
+ * pure makes the overlay story auditable without standing up a browser.
+ */
+/**
+ * Pull the first sentence (or first ~140 chars) of reasoning as a
+ * display summary. The reasoning panel renders the full text; this is a
+ * hook for callers that want a preview (e.g., badge text).
+ */
+export declare function summarizeReasoning(reasoning: string | undefined): string;
+/**
+ * Parse a "Current=C-XXX" marker from the reasoning, if present. Used to
+ * enrich the progress label ("Turn 27 · C-003"). Returns undefined when
+ * the reasoning doesn't carry a ledger marker — NOT every run uses the
+ * ledger shape.
+ */
+export declare function extractCurrentMarker(reasoning: string | undefined): string | undefined;
+/**
+ * Parse a "Done=[...]" ledger from reasoning. Returns the count of
+ * completed items, or undefined when no ledger exists. Used to compute
+ * a second progress indicator (items done vs items total) orthogonal to
+ * turn-of-maxTurns.
+ */
+export declare function extractDoneCount(reasoning: string | undefined): number | undefined;
+export interface VerdictEvent {
+    kind: 'positive' | 'cleared' | 'review';
+    text: string;
+    /** Raw verdict substring so we can dedupe later in the session */
+    marker: string;
+}
+/**
+ * Scan reasoning + action text for new verdict-worthy moments. Returns
+ * an array (possibly empty) of events the driver should surface as
+ * badges. The caller is responsible for deduplication across turns —
+ * this function returns ALL verdict markers visible in the text.
+ *
+ * For a reasoning string like:
+ *   "C-003 PUTIN VLADIMIR: POSITIVE MATCH — Russia-EO14024 / SDN"
+ * emits: { kind: 'positive', text: 'C-003 PUTIN VLADIMIR · POSITIVE MATCH', marker: 'C-003:POSITIVE MATCH' }
+ */
+export declare function detectVerdicts(reasoning: string | undefined): VerdictEvent[];
+/**
+ * Stateful tracker that holds the set of verdict markers already
+ * surfaced this session, so we don't re-emit the same badge every turn
+ * for a verdict the agent keeps mentioning in its progress ledger.
+ */
+export declare class VerdictTracker {
+    private seen;
+    /**
+     * Given new reasoning text, return only the verdicts that are NEW
+     * (haven't been emitted before in this session).
+     */
+    accept(reasoning: string | undefined): VerdictEvent[];
+    reset(): void;
+}
+/**
+ * Build the progress label shown in the top-left chip of the overlay.
+ * Combines turn counter with an optional ledger marker.
+ *
+ *   buildProgressLabel(5, 65) → "Turn 5 · 65 max"
+ *   buildProgressLabel(5, 65, 'C-003') → "Turn 5 · C-003"
+ */
+export declare function buildProgressLabel(turn: number, maxTurns: number, marker?: string): string;
+//# sourceMappingURL=overlay-narration.d.ts.map

package/dist/runner/overlay-narration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-narration.d.ts","sourceRoot":"","sources":["../../src/runner/overlay-narration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAQH;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQxE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAKtF;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAQlF;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,CAAA;IACvC,IAAI,EAAE,MAAM,CAAA;IACZ,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,EAAE,CA2C5E;AAED;;;;GAIG;AACH,qBAAa,cAAc;IACzB,OAAO,CAAC,IAAI,CAAoB;IAEhC;;;OAGG;IACH,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,YAAY,EAAE;IAWrD,KAAK,IAAI,IAAI;CAGd;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,MAAM,CAGR"}

package/dist/runner/overlay-narration.js

@@ -0,0 +1,172 @@
+/**
+ * Gen 32 — agent narration hooks for the cursor overlay.
+ *
+ * The runner emits `decide-completed` each turn with the LLM's raw
+ * reasoning text. That text carries three distinct signals the overlay
+ * wants to surface to a viewer:
+ *
+ *   1. **Current step** — a short phrase summarizing what the agent is
+ *      about to do. Extracted from the first sentence of `reasoning`.
+ *   2. **Progress** — turn N of maxTurns, plus any inline progress
+ *      ledger (`Done=[C-001, C-002, ...] Current=C-003`) the agent is
+ *      already using in OFAC/batch-style prompts.
+ *   3. **Verdict moments** — conclusions like "POSITIVE MATCH",
+ *      "CLEARED", "NEEDS REVIEW" that should fire a celebratory badge.
+ *
+ * These are pure functions — no I/O, no driver calls. The driver-facing
+ * hooks in runner.ts call them, then push results via
+ * `driver.setOverlayReasoning` / `setOverlayProgress` / `pushOverlayBadge`.
+ *
+ * Why a separate module: the runner is already 1500+ lines and dense;
+ * parsing logic belongs somewhere testable in isolation. Keeping this
+ * pure makes the overlay story auditable without standing up a browser.
+ */
+const VERDICT_PATTERNS = [
+    { re: /\bPOSITIVE\s+MATCH\b/i, kind: 'positive' },
+    { re: /\bCLEARED\b/i, kind: 'cleared' },
+    { re: /\bNEEDS\s+REVIEW\b/i, kind: 'review' },
+];
+/**
+ * Pull the first sentence (or first ~140 chars) of reasoning as a
+ * display summary. The reasoning panel renders the full text; this is a
+ * hook for callers that want a preview (e.g., badge text).
+ */
+export function summarizeReasoning(reasoning) {
+    if (!reasoning)
+        return '';
+    const collapsed = reasoning.replace(/\s+/g, ' ').trim();
+    if (!collapsed)
+        return '';
+    // Cut at sentence boundary if short; otherwise hard-truncate.
+    const firstSentence = collapsed.match(/^(.+?[.!?])\s/);
+    if (firstSentence && firstSentence[1].length <= 180)
+        return firstSentence[1];
+    return collapsed.length > 180 ? collapsed.slice(0, 177).trimEnd() + '…' : collapsed;
+}
+/**
+ * Parse a "Current=C-XXX" marker from the reasoning, if present. Used to
+ * enrich the progress label ("Turn 27 · C-003"). Returns undefined when
+ * the reasoning doesn't carry a ledger marker — NOT every run uses the
+ * ledger shape.
+ */
+export function extractCurrentMarker(reasoning) {
+    if (!reasoning)
+        return undefined;
+    const m = reasoning.match(/Current\s*=\s*([A-Za-z0-9][\w-]*)/);
+    if (m)
+        return m[1];
+    return undefined;
+}
+/**
+ * Parse a "Done=[...]" ledger from reasoning. Returns the count of
+ * completed items, or undefined when no ledger exists. Used to compute
+ * a second progress indicator (items done vs items total) orthogonal to
+ * turn-of-maxTurns.
+ */
+export function extractDoneCount(reasoning) {
+    if (!reasoning)
+        return undefined;
+    const m = reasoning.match(/Done\s*=\s*\[([^\]]*)\]/);
+    if (!m)
+        return undefined;
+    const body = m[1].trim();
+    if (!body)
+        return 0;
+    // Count comma-separated entries, tolerate trailing commas
+    return body.split(',').filter((s) => s.trim().length > 0).length;
+}
+/**
+ * Scan reasoning + action text for new verdict-worthy moments. Returns
+ * an array (possibly empty) of events the driver should surface as
+ * badges. The caller is responsible for deduplication across turns —
+ * this function returns ALL verdict markers visible in the text.
+ *
+ * For a reasoning string like:
+ *   "C-003 PUTIN VLADIMIR: POSITIVE MATCH — Russia-EO14024 / SDN"
+ * emits: { kind: 'positive', text: 'C-003 PUTIN VLADIMIR · POSITIVE MATCH', marker: 'C-003:POSITIVE MATCH' }
+ */
+export function detectVerdicts(reasoning) {
+    if (!reasoning)
+        return [];
+    const out = [];
+    // Case: inline customer-ID prefix (OFAC-style)
+    //   "C-003 confirmed POSITIVE MATCH" / "C-003: CLEARED"
+    // Trailer is comma-bounded so enumerations like
+    //   "C-001 POSITIVE MATCH, C-002 CLEARED, C-003 NEEDS REVIEW"
+    // yield one event per customer, not one event for the whole line.
+    const inlineRe = /\b([A-Z]-\d{3,4})[^\w]{1,6}([^.,\n]*?(?:POSITIVE\s+MATCH|CLEARED|NEEDS\s+REVIEW)[^.,\n]*)/gi;
+    let m;
+    const seenInText = new Set();
+    while ((m = inlineRe.exec(reasoning)) !== null) {
+        const cid = m[1];
+        const snippet = m[2].replace(/\s+/g, ' ').trim();
+        const kind = snippet.match(/POSITIVE/i) ? 'positive' : snippet.match(/CLEARED/i) ? 'cleared' : 'review';
+        const marker = `${cid}:${kind.toUpperCase()}`;
+        // Dedupe within a single reasoning string — agent may restate
+        // "C-001 POSITIVE" later in the same line without intending a new event.
+        if (seenInText.has(marker))
+            continue;
+        seenInText.add(marker);
+        const shortSnippet = snippet.length > 60 ? snippet.slice(0, 57) + '…' : snippet;
+        out.push({
+            kind,
+            text: `${cid} · ${shortSnippet}`,
+            marker,
+        });
+    }
+    // Fallback: bare verdict without customer ID. Only emit ONE per reasoning
+    // string in this mode (multiple would be noise without context).
+    if (out.length === 0) {
+        for (const pat of VERDICT_PATTERNS) {
+            const vm = reasoning.match(pat.re);
+            if (vm) {
+                out.push({
+                    kind: pat.kind,
+                    text: vm[0].replace(/\s+/g, ' ').trim().toUpperCase(),
+                    marker: pat.kind.toUpperCase(),
+                });
+                break;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Stateful tracker that holds the set of verdict markers already
+ * surfaced this session, so we don't re-emit the same badge every turn
+ * for a verdict the agent keeps mentioning in its progress ledger.
+ */
+export class VerdictTracker {
+    seen = new Set();
+    /**
+     * Given new reasoning text, return only the verdicts that are NEW
+     * (haven't been emitted before in this session).
+     */
+    accept(reasoning) {
+        const found = detectVerdicts(reasoning);
+        const fresh = [];
+        for (const v of found) {
+            if (this.seen.has(v.marker))
+                continue;
+            this.seen.add(v.marker);
+            fresh.push(v);
+        }
+        return fresh;
+    }
+    reset() {
+        this.seen.clear();
+    }
+}
+/**
+ * Build the progress label shown in the top-left chip of the overlay.
+ * Combines turn counter with an optional ledger marker.
+ *
+ *   buildProgressLabel(5, 65) → "Turn 5 · 65 max"
+ *   buildProgressLabel(5, 65, 'C-003') → "Turn 5 · C-003"
+ */
+export function buildProgressLabel(turn, maxTurns, marker) {
+    if (marker)
+        return `Turn ${turn} · ${marker}`;
+    return `Turn ${turn} / ${maxTurns}`;
+}
+//# sourceMappingURL=overlay-narration.js.map

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,