@tangle-network/browser-agent-driver 0.22.0 → 0.24.0

package/dist/runner/parallel-runner.js

@@ -0,0 +1,133 @@
+/**
+ * Parallel Runner — executes compound goals across multiple browser tabs.
+ *
+ * Gen 21: takes decomposed sub-goals from GoalDecomposer, creates one
+ * BrowserAgent per sub-goal in separate Pages (shared BrowserContext),
+ * runs them concurrently, and merges results via EvidenceMerger.
+ *
+ * Uses the same PlaywrightDriver + BrowserAgent stack as single-page runs.
+ * The parallel execution layer is thin — the intelligence is in the
+ * GoalDecomposer (split) and EvidenceMerger (combine).
+ */
+import { PlaywrightDriver } from '../drivers/playwright.js';
+import { BrowserAgent } from './runner.js';
+/**
+ * Run sub-goals in parallel across separate browser tabs.
+ *
+ * Creates one Page + PlaywrightDriver + BrowserAgent per sub-goal,
+ * runs them concurrently with per-agent timeouts, and collects results.
+ */
+export async function runParallel(options) {
+    const startTime = Date.now();
+    const { context, config, subGoals, scenario, onTurn } = options;
+    // Per-sub-agent timeout: split the total timeout proportionally
+    const totalTimeout = options.timeoutMs || 600_000;
+    const perAgentTimeout = Math.floor(totalTimeout * 0.85); // 85% of total, leave room for merge
+    // Create and run sub-agents in parallel
+    const subPromises = subGoals.map(async (subGoal, index) => {
+        const label = `sub-${index}`;
+        let page;
+        try {
+            page = await context.newPage();
+            const driver = new PlaywrightDriver(page, {
+                ...options.driverOptions,
+                showCursor: false, // no cursor overlay on parallel tabs
+            });
+            // Set up resource blocking if configured
+            const blocking = config.resourceBlocking;
+            if (blocking) {
+                await driver.setupResourceBlocking(blocking);
+            }
+            const subConfig = {
+                ...config,
+                // Scale token budget by sub-goal's budget fraction
+                tokenBudget: options.totalTokenBudget
+                    ? Math.floor(options.totalTokenBudget * subGoal.budgetFraction)
+                    : undefined,
+            };
+            const agent = new BrowserAgent({
+                driver,
+                config: subConfig,
+                onTurn: onTurn ? (turn) => onTurn(label, turn) : undefined,
+                projectStore: options.projectStore,
+                // extensions passed through if available
+            });
+            const subScenario = {
+                ...scenario,
+                goal: subGoal.goal,
+                startUrl: subGoal.startUrl || scenario.startUrl,
+                // Scale max turns by budget fraction
+                maxTurns: Math.max(10, Math.floor((scenario.maxTurns || 30) * subGoal.budgetFraction * 1.5)),
+            };
+            const result = await Promise.race([
+                agent.run(subScenario),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Sub-agent ${label} timed out`)), perAgentTimeout)),
+            ]);
+            return { subGoal, result };
+        }
+        catch (err) {
+            // Sub-agent failed — return a failure result
+            return {
+                subGoal,
+                result: {
+                    success: false,
+                    reason: `Sub-agent error: ${err instanceof Error ? err.message : String(err)}`,
+                    turns: [],
+                    totalMs: Date.now() - startTime,
+                },
+            };
+        }
+        finally {
+            // Close the page but not the context (shared with other sub-agents)
+            if (page && !page.isClosed()) {
+                await page.close().catch(() => { });
+            }
+        }
+    });
+    const subResults = await Promise.all(subPromises);
+    // Merge results
+    const mergedResult = mergeEvidence(options.originalGoal, subResults);
+    const totalTokens = subResults.reduce((sum, sr) => {
+        const tokens = sr.result.totalTokensUsed || 0;
+        return sum + tokens;
+    }, 0);
+    return {
+        mergedResult: mergedResult.text,
+        success: mergedResult.success,
+        subResults,
+        totalTokens,
+        totalMs: Date.now() - startTime,
+    };
+}
+/**
+ * Merge evidence from parallel sub-agents into one coherent answer.
+ *
+ * For now: deterministic merge (concatenate results with labels).
+ * Future: LLM-based synthesis for complex comparisons.
+ */
+function mergeEvidence(originalGoal, subResults) {
+    const successCount = subResults.filter(sr => sr.result.success).length;
+    const allSucceeded = successCount === subResults.length;
+    const anySucceeded = successCount > 0;
+    // Build merged result text
+    const parts = [`Goal: ${originalGoal}`, ''];
+    for (const { subGoal, result } of subResults) {
+        const status = result.success ? 'COMPLETED' : 'FAILED';
+        parts.push(`[${status}] ${subGoal.goal}:`);
+        if (result.reason) {
+            parts.push(result.reason);
+        }
+        parts.push('');
+    }
+    if (!anySucceeded) {
+        parts.push('None of the sub-goals could be completed.');
+    }
+    else if (!allSucceeded) {
+        parts.push(`${successCount}/${subResults.length} sub-goals completed.`);
+    }
+    return {
+        text: parts.join('\n'),
+        success: anySucceeded, // succeed if at least one sub-goal worked
+    };
+}
+//# sourceMappingURL=parallel-runner.js.map

package/dist/runner/parallel-runner.js.map

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

package/dist/runner/pattern-extractor.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pattern Extractor — learns reusable navigation patterns from completed runs.
+ *
+ * Gen 26b: after a successful run, mechanically extract domain-level patterns
+ * from the turn log and record them as AppKnowledge facts. No LLM call needed —
+ * patterns are detected by observing action/state sequences.
+ *
+ * Extracted patterns:
+ * - Cookie/consent banner dismissal (which action dismissed it, on which turn)
+ * - Page load timing (how long the site takes to settle)
+ * - Form structure (which refs are used for key form fields)
+ * - Navigation paths (effective URL patterns for search/results)
+ * - Blockers encountered (modals, auth walls, rate limits)
+ *
+ * Design constraints:
+ * - No bloat: only records patterns with clear signal (not every action)
+ * - Cleanable: all facts have confidence scores; low-confidence facts auto-prune
+ * - Workspace-isolated: patterns stored per-domain in the knowledge store
+ * - Smart: confirms patterns on repeat observation, decays on contradiction
+ */
+import type { Turn } from '../types.js';
+import type { AppKnowledge, Fact } from '../memory/knowledge.js';
+interface ExtractedPattern {
+    type: Fact['type'];
+    key: string;
+    value: string;
+}
+/**
+ * Extract reusable patterns from a completed run's turns.
+ * Only extracts from SUCCESSFUL runs — failed runs produce unreliable patterns.
+ */
+export declare function extractPatterns(turns: Turn[], domain: string, success: boolean): ExtractedPattern[];
+/**
+ * Record extracted patterns into the knowledge store.
+ * Respects the existing confidence system — repeated patterns gain confidence,
+ * contradicted patterns decay.
+ */
+export declare function recordPatterns(knowledge: AppKnowledge, patterns: ExtractedPattern[]): void;
+export {};
+//# sourceMappingURL=pattern-extractor.d.ts.map

package/dist/runner/pattern-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pattern-extractor.d.ts","sourceRoot":"","sources":["../../src/runner/pattern-extractor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,wBAAwB,CAAA;AAEhE,UAAU,gBAAgB;IACxB,IAAI,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;IAClB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;CACd;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,IAAI,EAAE,EACb,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,OAAO,GACf,gBAAgB,EAAE,CA6FpB;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,YAAY,EACvB,QAAQ,EAAE,gBAAgB,EAAE,GAC3B,IAAI,CAIN"}

package/dist/runner/pattern-extractor.js

@@ -0,0 +1,122 @@
+/**
+ * Pattern Extractor — learns reusable navigation patterns from completed runs.
+ *
+ * Gen 26b: after a successful run, mechanically extract domain-level patterns
+ * from the turn log and record them as AppKnowledge facts. No LLM call needed —
+ * patterns are detected by observing action/state sequences.
+ *
+ * Extracted patterns:
+ * - Cookie/consent banner dismissal (which action dismissed it, on which turn)
+ * - Page load timing (how long the site takes to settle)
+ * - Form structure (which refs are used for key form fields)
+ * - Navigation paths (effective URL patterns for search/results)
+ * - Blockers encountered (modals, auth walls, rate limits)
+ *
+ * Design constraints:
+ * - No bloat: only records patterns with clear signal (not every action)
+ * - Cleanable: all facts have confidence scores; low-confidence facts auto-prune
+ * - Workspace-isolated: patterns stored per-domain in the knowledge store
+ * - Smart: confirms patterns on repeat observation, decays on contradiction
+ */
+/**
+ * Extract reusable patterns from a completed run's turns.
+ * Only extracts from SUCCESSFUL runs — failed runs produce unreliable patterns.
+ */
+export function extractPatterns(turns, domain, success) {
+    if (!success || turns.length < 2)
+        return [];
+    const patterns = [];
+    // 1. Cookie/consent banner dismissal
+    // Look for early turns where the agent clicked something that looks like
+    // cookie/consent/accept and then proceeded normally
+    for (let i = 0; i < Math.min(turns.length, 5); i++) {
+        const turn = turns[i];
+        const action = turn.action;
+        if (action.action === 'click' || action.action === 'clickAt' || action.action === 'clickLabel') {
+            const reasoning = turn.reasoning?.toLowerCase() || '';
+            const snapshot = turn.state?.snapshot?.toLowerCase() || '';
+            if (/cookie|consent|accept.*cookie|gdpr|privacy/i.test(reasoning + snapshot)) {
+                const selector = 'selector' in action ? action.selector : `clickAt(${action.x},${action.y})`;
+                patterns.push({
+                    type: 'pattern',
+                    key: 'cookie-dismiss',
+                    value: `Turn ${i + 1}: ${action.action} ${selector}`,
+                });
+                break; // only record the first one
+            }
+        }
+    }
+    // 2. Page load timing — how many turns before first meaningful action
+    const firstMeaningfulTurn = turns.findIndex(t => t.action.action !== 'wait' && t.action.action !== 'scroll' &&
+        !t.error && t.action.action !== 'navigate');
+    if (firstMeaningfulTurn >= 2) {
+        patterns.push({
+            type: 'timing',
+            key: 'first-meaningful-action',
+            value: `Turn ${firstMeaningfulTurn + 1} (${firstMeaningfulTurn} setup turns)`,
+        });
+    }
+    // 3. Effective search/navigation URL pattern
+    // If the agent used navigate with URL params, record the pattern
+    for (const turn of turns) {
+        if (turn.action.action === 'navigate' && turn.action.url) {
+            try {
+                const url = new URL(turn.action.url);
+                if (url.hostname.includes(domain) && url.search.length > 5) {
+                    // Generalize: replace specific values with placeholders
+                    const pattern = url.pathname + url.search
+                        .replace(/=[^&]+/g, '={value}')
+                        .slice(0, 100);
+                    patterns.push({
+                        type: 'pattern',
+                        key: 'search-url',
+                        value: pattern,
+                    });
+                    break; // only record the first effective search URL
+                }
+            }
+            catch { /* invalid URL, skip */ }
+        }
+    }
+    // 4. Turn efficiency — how many turns the task took
+    patterns.push({
+        type: 'timing',
+        key: 'typical-turns',
+        value: `${turns.length} turns`,
+    });
+    // 5. Form fields used — record which refs were used for form filling
+    const fillTurns = turns.filter(t => t.action.action === 'fill' || t.action.action === 'type');
+    if (fillTurns.length >= 2) {
+        const fields = fillTurns
+            .map(t => {
+            if (t.action.action === 'fill' && 'fields' in t.action && t.action.fields) {
+                return Object.keys(t.action.fields).join(',');
+            }
+            if (t.action.action === 'type' && 'selector' in t.action) {
+                return t.action.selector;
+            }
+            return '';
+        })
+            .filter(Boolean)
+            .slice(0, 5);
+        if (fields.length > 0) {
+            patterns.push({
+                type: 'selector',
+                key: 'form-fields',
+                value: fields.join(' → '),
+            });
+        }
+    }
+    return patterns;
+}
+/**
+ * Record extracted patterns into the knowledge store.
+ * Respects the existing confidence system — repeated patterns gain confidence,
+ * contradicted patterns decay.
+ */
+export function recordPatterns(knowledge, patterns) {
+    for (const p of patterns) {
+        knowledge.recordFact(p.type, p.key, p.value);
+    }
+}
+//# sourceMappingURL=pattern-extractor.js.map

package/dist/runner/pattern-extractor.js.map

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

package/dist/runner/runner.d.ts

@@ -88,6 +88,27 @@ export interface BrowserAgentOptions {
  * actual data (no nulls, no placeholder markers) passes through unchanged.
  */
 export declare function hasPlaceholderPattern(text: string): boolean;
+/**
+ * Gen 9 — runtime two-pass extraction. When the planner emits a single
+ * runScript step (per Gen 7.2 rule #7) and that script returns null /
+ * empty / whitespace / `{x: null}` / a placeholder pattern, the auto-
+ * complete-from-runScript path should NOT fire. Instead the runner should
+ * mark the plan as deviated and fall through to the per-action loop where
+ * Brain.decide can re-observe the loaded page and emit a smarter action
+ * (different selector, click+wait, scroll, etc.).
+ *
+ * This addresses the failure mode the Gen 8 head-to-head gauntlet
+ * surfaced: bad's planner-only path lost to browser-use's per-action loop
+ * on tasks where the first runScript pick was wrong (npm, mdn signature,
+ * w3c, github, wikipedia variance). Two-pass gives bad's per-action loop
+ * the same recovery surface browser-use uses, with the planner's speed
+ * advantage on the cases where runScript succeeds first try.
+ *
+ * "Meaningful" means: not empty/whitespace, not the literal string `null`
+ * or `undefined`, and not matching `hasPlaceholderPattern` (which already
+ * detects JSON null fields, "<from prior step>" markers, etc.).
+ */
+export declare function isMeaningfulRunScriptOutput(output: string | null | undefined): boolean;
 export declare class BrowserAgent {
     private driver;
     private brain;

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

@@ -1 +1 @@
-{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/runner/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAClD,OAAO,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,WAAW,EAAE,IAAI,EAAE,SAAS,EAAkC,MAAM,aAAa,CAAC;AAKvH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAsB/D,OAAO,EAAE,WAAW,EAAE,MAAM,2BAA2B,CAAC;AACxD,OAAO,EAAE,YAAY,EAAa,MAAM,aAAa,CAAC;AAGtD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,IAAI,CAiDzF;AA0CD,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,6BAA6B;IAC7B,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,KAAK,IAAI,CAAC;IAC9B,wDAAwD;IACxD,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,KAAK,IAAI,CAAC;IACnG,wDAAwD;IACxD,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,sEAAsE;IACtE,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,sDAAsD;IACtD,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,kBAAkB,CAAC;CACjC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAgB3D;AAED,qBAAa,YAAY;IACvB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAQ;IACrB,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,MAAM,CAAC,CAAuB;IACtC,OAAO,CAAC,aAAa,CAAC,CAAqF;IAC3G,OAAO,CAAC,mBAAmB,CAAC,CAAS;IACrC,OAAO,CAAC,YAAY,CAAC,CAAe;IACpC,OAAO,CAAC,WAAW,CAAC,CAAc;IAClC,OAAO,CAAC,SAAS,CAAC,CAAe;IACjC,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,eAAe,CAAwB;IAC/C,OAAO,CAAC,GAAG,CAAe;IAC1B,OAAO,CAAC,YAAY,CAAM;IAK1B,OAAO,CAAC,aAAa,CAAC,CAAgB;IACtC,OAAO,CAAC,UAAU,CAAC,CAAqB;gBAE5B,OAAO,EAAE,mBAAmB;IAyBlC,GAAG,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,WAAW,CAAC;IAqtDnD,OAAO,CAAC,qBAAqB;IA2B7B,qEAAqE;IACrE,OAAO,CAAC,UAAU;IAclB;;;;;;;;;;;;OAYG;IACH;;;;;;;;;;;;;;;;;;;OAmBG;YACW,WAAW;YAibX,YAAY;YAkCZ,+BAA+B;YAgE/B,mCAAmC;YAwCnC,6BAA6B;YA4C7B,qCAAqC;YAqBrC,4BAA4B;YA4B5B,4BAA4B;YAkC5B,wBAAwB;CASvC;AAED,2BAA2B;AAC3B,wBAAsB,eAAe,CACnC,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC,GAC5C,OAAO,CAAC,WAAW,CAAC,CAGtB"}
+{"version":3,"file":"runner.d.ts","sourceRoot":"","sources":["../../src/runner/runner.ts"],"names":[],"mappings":"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"}