@tangle-network/browser-agent-driver 0.7.0 → 0.8.7

package/README.md

@@ -9,26 +9,18 @@ LLM-driven browser automation. Reads page state via accessibility tree, decides
 ### CLI
 
 ```bash
-# global install — gives you the `bad` command
-npm i -g @tangle-network/browser-agent-driver
-npx playwright install chromium
-
-# or run without installing
-npx @tangle-network/browser-agent-driver run --goal "..." --url https://...
+curl -fsSL https://raw.githubusercontent.com/tangle-network/browser-agent-driver/main/scripts/install.sh | sh
 ```
 
-### Standalone (no npm)
+Installs the `bad` command to `~/.local/bin`, downloads Playwright Chromium, and adds PATH instructions. Requires Node.js 20+.
+
+Or via npm:
 
 ```bash
-# download, extract, add to PATH
-curl -fsSL https://github.com/tangle-network/browser-agent-driver/releases/latest/download/bad-v0.7.0-node.tar.gz | tar xz
-export PATH="$PWD/bad-v0.7.0:$PATH"
+npm i -g @tangle-network/browser-agent-driver
 npx playwright install chromium
-bad run --goal "..." --url https://...
 ```
 
-Requires Node.js 20+. See [Releases](https://github.com/tangle-network/browser-agent-driver/releases) for all versions.
-
 ### As a library
 
 ```bash

package/dist/brain/index.d.ts

@@ -4,7 +4,7 @@
  *
  * Uses Vercel AI SDK for multi-provider support (OpenAI, Anthropic, Google, Codex CLI, Claude Code).
  */
-import type { ModelMessage } from 'ai';
+import type { ModelMessage, LanguageModel } from 'ai';
 import type { Action, PageState, AgentConfig, DesignFinding, GoalVerification } from '../types.js';
 export interface BrainDecision {
     action: Action;
@@ -64,6 +64,11 @@ export declare class Brain {
     private resolveModelName;
     private shouldSendTemperature;
     private generationOptions;
+    /** Get a LLM model instance, optionally with provider/model override (e.g. for CAPTCHA fallback) */
+    getLanguageModel(selection?: {
+        provider?: 'openai' | 'anthropic' | 'google';
+        model?: string;
+    }): Promise<LanguageModel>;
     /** Lazily create the LLM model instance based on provider config */
     private getModel;
     private generate;
@@ -78,6 +83,12 @@ export declare class Brain {
      * not for decide(). The flag is kept for future experiments with better routing signals.
      */
     private shouldUseNavigationModel;
+    /**
+     * Build the system prompt dynamically, injecting conditional rule groups
+     * based on goal text, page snapshot content, and turn number.
+     * Saves ~800 tokens per turn on simple navigation tasks.
+     */
+    private buildSystemPrompt;
     /** Reset conversation history (call between scenarios) */
     reset(): void;
     /** Get current conversation history */
@@ -91,15 +102,21 @@ export declare class Brain {
     private buildUserContent;
     /**
      * Compact conversation history: strip ELEMENTS blocks and screenshots
-     * from all but the most recent observation.
+     * from older observations, keeping the last 2 user messages intact.
      *
-     * Note: Aggressive one-line compression was tested (2026-03-08) and found
-     * counterproductive — the agent loses context about visited pages and
-     * wastes turns revisiting them. The current approach (strip snapshots,
-     * keep full text) is the empirically best balance.
+     * For older turns, replaces the full ELEMENTS block with a one-line
+     * summary showing element count and the selectors the agent actually
+     * used, extracted from the paired assistant response.
      */
     private compactHistory;
-    private stripElements;
+    /**
+     * Extract @ref selectors from an assistant JSON response.
+     */
+    private extractSelectorsFromResponse;
+    /**
+     * Replace the ELEMENTS block with a one-line action-only summary.
+     */
+    private summarizeElements;
     decide(goal: string, state: PageState, extraContext?: string, turnInfo?: {
         current: number;
         max: number;
@@ -128,7 +145,7 @@ export declare class Brain {
      * Uses vision to analyze layout, typography, spacing, contrast, and UX.
      * Returns structured findings with categories and severity levels.
      */
-    auditDesign(state: PageState, goal: string, checkpoints: string[]): Promise<{
+    auditDesign(state: PageState, goal: string, checkpoints: string[], systemPrompt?: string): Promise<{
         score: number;
         findings: DesignFinding[];
         raw: string;

package/dist/brain/index.d.ts.map

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

package/dist/brain/index.js

@@ -9,7 +9,8 @@ import { AriaSnapshotHelper } from '../drivers/snapshot.js';
 import { resolveProviderApiKey, resolveProviderModelName } from '../provider-defaults.js';
 import { buildFirstPartyBoundaryNote } from '../domain-policy.js';
 import { generateWithSandboxBackend } from '../providers/sandbox-backend.js';
-const SYSTEM_PROMPT = `You are a senior staff engineer operating a browser via Playwright automation.
+/** Core system prompt: preamble, actions, format, and rules 1-14 (always sent) */
+const CORE_RULES = `You are a senior staff engineer operating a browser via Playwright automation.
 
 You can SEE the page (via screenshot) and READ the page structure (via accessibility tree with @ref IDs).
 Use BOTH inputs together — the screenshot shows layout/design/visual state, the a11y tree shows interactive elements with refs.
@@ -59,17 +60,25 @@ RULES:
 11. After the app builds and a preview is visible, use "verifyPreview" to check for errors before completing
 12. BLOCKER-FIRST POLICY: if a modal, limit, quota, permission, or error dialog blocks progress, resolve THAT first before continuing the main goal
 13. For quota/limit blockers, use an unblock ladder: open manage path -> clean up old test resources if needed -> retry the original action
-14. If the same action triggers the same blocker twice, switch strategy immediately (different button/path), do not repeat blind retries
+14. If the same action triggers the same blocker twice, switch strategy immediately (different button/path), do not repeat blind retries`;
+/** Search-related rules (15-17): injected when page has search elements or /search URL */
+const SEARCH_RULES = `
 15. SEARCH FORMS: Always interact with the form (type in search box, then click Search or press Enter). Do NOT navigate to a URL with search query parameters — many sites require form submission to trigger filtering. If a search yields no results, try the page's own search box rather than the site-wide search
 16. CONTENT DISCOVERY: If the ELEMENTS list doesn't show the link/content you need (e.g., the page has many links but the a11y tree is truncated), use runScript to find it: document.querySelectorAll('a[href]') filtered by keyword. Navigate to the discovered URL directly instead of clicking blindly through menus
-17. EXTERNAL SEARCH REDIRECTS: If a site's search form redirects to an external search engine (e.g., search.usa.gov for .gov sites), the results still link back to the original site. Click a relevant search result link — it will take you to the target domain. Do NOT abandon search results to navigate the target site manually
+17. EXTERNAL SEARCH REDIRECTS: If a site's search form redirects to an external search engine (e.g., search.usa.gov for .gov sites), the results still link back to the original site. Click a relevant search result link — it will take you to the target domain. Do NOT abandon search results to navigate the target site manually`;
+/** Data extraction rules (18, 21-23): injected when goal involves extracting data */
+const DATA_EXTRACTION_RULES = `
 18. DATA EXTRACTION: When the goal asks for specific data (prices, ratings, counts, names) from a list or search results page, use runScript to extract all needed data at once: e.g., document.querySelectorAll('.product-card').forEach(...). Do NOT click into each individual item when the data is visible on the list page. Extract first, then complete with the extracted data
-19. FORM FIELD TARGETING: Before typing, verify you are targeting the correct input field using its @ref from the ELEMENTS list. If multiple inputs are visible (e.g., search box + price filter), ensure you select the right one by checking its label or placeholder text in the a11y tree. Never assume focus — always specify the exact @ref
-20. SECTION NAVIGATION: When you need to find a specific section (e.g., rugby, sports, travel) and the nav links aren't in the truncated a11y tree, use runScript to discover navigation: JSON.stringify(Array.from(document.querySelectorAll('nav a, header a, [role="navigation"] a, .nav a')).slice(0, 30).map(a => ({text: a.textContent.trim(), href: a.href}))). Then navigate directly to the matching section URL
 21. EFFICIENT COMPLETION: When you have enough data to answer the goal, complete immediately. Do not navigate to additional pages for "confirmation" if the data was already extracted via runScript or is visible in the current a11y tree. Include all extracted data in the completion result
 22. EXTRACT BEFORE NAVIGATING: On search results, directory listings, or any page showing multiple items, ALWAYS extract ALL needed data via runScript BEFORE clicking into individual items. This includes names, phone numbers, addresses, ratings, prices — anything visible on list cards. Use: document.querySelectorAll('.result-card, .listing, [class*="card"]') to grab everything at once. Many sites use anti-bot protection on detail pages but leave listing pages accessible. If you can answer the goal from list-level data, do so without navigating deeper. NEVER click into 3+ individual items when the data is on the list page
-23. FILTER vs SEARCH: When a goal asks to filter results (e.g., "under $50", "4+ stars"), look for filter controls (sliders, dropdowns, checkboxes in a sidebar or toolbar) rather than typing filter values into the search box. Search boxes are for keyword queries, not numeric filters. After applying a filter: (1) wait 2-3 seconds for results to update, (2) verify the filter took effect by checking the updated results, (3) extract the filtered data via runScript. Do NOT keep searching for more filter controls after one is applied — extract and complete
-24. HEAVY PAGE RECOVERY: If a page takes very long to load or seems stuck, do NOT wait — use runScript to check document.readyState and extract whatever content is already in the DOM. Partial data is better than a timeout. If the page is completely blank, try navigating to a simpler version (mobile site, search page) instead of waiting
+23. FILTER vs SEARCH: When a goal asks to filter results (e.g., "under $50", "4+ stars"), look for filter controls (sliders, dropdowns, checkboxes in a sidebar or toolbar) rather than typing filter values into the search box. Search boxes are for keyword queries, not numeric filters. After applying a filter: (1) wait 2-3 seconds for results to update, (2) verify the filter took effect by checking the updated results, (3) extract the filtered data via runScript. Do NOT keep searching for more filter controls after one is applied — extract and complete`;
+/** Heavy page rules (19-20, 24): injected when snapshot is large or turn count is high */
+const HEAVY_PAGE_RULES = `
+19. FORM FIELD TARGETING: Before typing, verify you are targeting the correct input field using its @ref from the ELEMENTS list. If multiple inputs are visible (e.g., search box + price filter), ensure you select the right one by checking its label or placeholder text in the a11y tree. Never assume focus — always specify the exact @ref
+20. SECTION NAVIGATION: When you need to find a specific section (e.g., rugby, sports, travel) and the nav links aren't in the truncated a11y tree, use runScript to discover navigation: JSON.stringify(Array.from(document.querySelectorAll('nav a, header a, [role="navigation"] a, .nav a')).slice(0, 30).map(a => ({text: a.textContent.trim(), href: a.href}))). Then navigate directly to the matching section URL
+24. HEAVY PAGE RECOVERY: If a page takes very long to load or seems stuck, do NOT wait — use runScript to check document.readyState and extract whatever content is already in the DOM. Partial data is better than a timeout. If the page is completely blank, try navigating to a simpler version (mobile site, search page) instead of waiting`;
+/** Reasoning framework and examples (always appended after rules) */
+const REASONING_SUFFIX = `
 
 REASONING FRAMEWORK — before choosing an action:
 1. What is the current state vs. the goal state? What is missing?
@@ -83,6 +92,12 @@ EXAMPLE 1 — Multi-step form fill (use actual refs from ELEMENTS, not these pla
 
 EXAMPLE 2 — Recovery after failure:
 {"plan":["Click the send button","Wait for response"],"currentStep":0,"action":{"action":"scroll","direction":"down","amount":300},"reasoning":"My last click failed because the element was not visible in the viewport. I can see from the screenshot that the send button is below the fold. Scrolling down to bring it into view before retrying.","expectedEffect":"The send button should become visible in the viewport"}`;
+/** Full static prompt (all rules) — used as default when config.systemPrompt is not set */
+const SYSTEM_PROMPT = CORE_RULES + SEARCH_RULES + DATA_EXTRACTION_RULES + HEAVY_PAGE_RULES + REASONING_SUFFIX;
+/** Pattern for detecting data-extraction keywords in goal text */
+const DATA_EXTRACTION_PATTERN = /\b(extract|list|find|data|price|pric|names?|rating|cost|count)\b/i;
+/** Pattern for detecting search-related roles in snapshot text */
+const SEARCH_SNAPSHOT_PATTERN = /^\s*-\s+(?:searchbox|combobox)\s/m;
 const FIRST_TURN_COMPACT_PROMPT = `You are a browser agent choosing the fastest safe next action.
 
 Return ONLY valid JSON with:
@@ -102,35 +117,9 @@ Rules:
 4. If a blocker is visible, resolve it first.
 5. Do not over-explore on the first turn.
 6. Respond with JSON only.`;
-const LINK_SCOUT_PROMPT = `You are a browser navigation scout.
-
-Your job is NOT to browse freely. Your only job is to pick the best next visible link from a short candidate list.
-
-You will receive:
-- the user goal
-- the current URL/title
-- the current page structure
-- a small ranked candidate list of visible links
-
-Choose the single best candidate that most directly advances the goal.
-Prefer:
-- first-party links already visible on the current page
-- links whose text matches the requested entity/content type
-- links that avoid unnecessary search detours
-
-Respond with ONLY a JSON object:
-{
-  "selector": "@ref",
-  "reasoning": "brief reason",
-  "confidence": 0.82
-}
-
-Rules:
-1. selector must exactly match one candidate ref
-2. choose only one candidate
-3. do not invent refs
-4. confidence must be 0 to 1
-5. if none are viable, choose the best available candidate anyway`;
+const LINK_SCOUT_PROMPT = `Pick the best link from CANDIDATES to advance the GOAL. Respond with ONLY JSON:
+{"selector":"@ref","reasoning":"brief reason","confidence":0.82}
+Rules: use exact candidate ref, pick one, confidence 0-1, prefer first-party and text-matching links.`;
 const DESIGN_AUDIT_PROMPT = `You are a senior product designer and UX engineer auditing a web application.
 
 Analyze the screenshot and accessibility tree for design quality, UX issues, and visual bugs.
@@ -253,6 +242,10 @@ export class Brain {
                 : { maxOutputTokens }),
         };
     }
+    /** Get a LLM model instance, optionally with provider/model override (e.g. for CAPTCHA fallback) */
+    async getLanguageModel(selection) {
+        return this.getModel(selection);
+    }
     /** Lazily create the LLM model instance based on provider config */
     async getModel(selection) {
         const providerName = selection?.provider || this.provider;
@@ -384,6 +377,32 @@ export class Brain {
         // Verification still routes to nav model (separate code path).
         return false;
     }
+    /**
+     * Build the system prompt dynamically, injecting conditional rule groups
+     * based on goal text, page snapshot content, and turn number.
+     * Saves ~800 tokens per turn on simple navigation tasks.
+     */
+    buildSystemPrompt(goal, state, turn) {
+        // If a custom systemPrompt was set via config, use it verbatim
+        if (this.systemPrompt !== SYSTEM_PROMPT)
+            return this.systemPrompt;
+        let prompt = CORE_RULES;
+        // Search rules: page has searchbox/combobox roles or URL contains /search
+        const snapshotSample = state.snapshot.length > 4000 ? state.snapshot.slice(0, 4000) : state.snapshot;
+        if (SEARCH_SNAPSHOT_PATTERN.test(snapshotSample) || /\/search\b/i.test(state.url)) {
+            prompt += SEARCH_RULES;
+        }
+        // Data extraction rules: goal mentions extraction-related keywords
+        if (DATA_EXTRACTION_PATTERN.test(goal)) {
+            prompt += DATA_EXTRACTION_RULES;
+        }
+        // Heavy page rules: large snapshot or late in the run
+        if (state.snapshot.length > 10_000 || turn > 10) {
+            prompt += HEAVY_PAGE_RULES;
+        }
+        prompt += REASONING_SUFFIX;
+        return prompt;
+    }
     /** Reset conversation history (call between scenarios) */
     reset() {
         this.history = [];
@@ -417,62 +436,135 @@ export class Brain {
     }
     /**
      * Compact conversation history: strip ELEMENTS blocks and screenshots
-     * from all but the most recent observation.
+     * from older observations, keeping the last 2 user messages intact.
      *
-     * Note: Aggressive one-line compression was tested (2026-03-08) and found
-     * counterproductive — the agent loses context about visited pages and
-     * wastes turns revisiting them. The current approach (strip snapshots,
-     * keep full text) is the empirically best balance.
+     * For older turns, replaces the full ELEMENTS block with a one-line
+     * summary showing element count and the selectors the agent actually
+     * used, extracted from the paired assistant response.
      */
     compactHistory() {
         if (this.history.length === 0)
             return [];
+        // Find indices of the last 2 user messages to keep intact
+        const userIndices = [];
+        for (let i = this.history.length - 1; i >= 0; i--) {
+            if (this.history[i].role === 'user') {
+                userIndices.push(i);
+                if (userIndices.length === 2)
+                    break;
+            }
+        }
+        const keepIntactFrom = userIndices.length > 0
+            ? userIndices[userIndices.length - 1]
+            : this.history.length;
         return this.history.map((msg, idx) => {
             if (msg.role !== 'user')
                 return msg;
-            // Keep the last user message intact
-            if (idx >= this.history.length - 2)
+            // Keep the last 2 user messages intact (full snapshot)
+            if (idx >= keepIntactFrom)
                 return msg;
+            // For older user messages, extract selectors from paired assistant response
+            const assistantMsg = idx + 1 < this.history.length ? this.history[idx + 1] : undefined;
+            const selectors = assistantMsg?.role === 'assistant'
+                ? this.extractSelectorsFromResponse(typeof assistantMsg.content === 'string' ? assistantMsg.content : '')
+                : [];
             // Handle multimodal content (array of parts)
             if (Array.isArray(msg.content)) {
                 const compacted = msg.content
-                    // Keep only text parts (strip screenshots from old messages)
                     .filter((part) => part.type === 'text')
                     .map((part) => ({
                     ...part,
-                    text: this.stripElements(part.text),
+                    text: this.summarizeElements(part.text, selectors),
                 }));
                 return { ...msg, content: compacted };
             }
             // Handle string content
             if (typeof msg.content === 'string') {
-                return { ...msg, content: this.stripElements(msg.content) };
+                return { ...msg, content: this.summarizeElements(msg.content, selectors) };
             }
             return msg;
         });
     }
-    stripElements(text) {
-        return text.replace(/ELEMENTS:\n[\s\S]*?(?=\n\n|What action should you take\?|$)/, (_match) => {
-            // Extract the snapshot text from the ELEMENTS block
-            const snapshotStart = _match.indexOf('\n');
+    /**
+     * Extract @ref selectors from an assistant JSON response.
+     */
+    extractSelectorsFromResponse(raw) {
+        const selectors = [];
+        try {
+            let text = raw.trim();
+            if (text.startsWith('```')) {
+                text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
+            }
+            const parsed = JSON.parse(text);
+            if (parsed.action?.selector)
+                selectors.push(parsed.action.selector);
+            if (Array.isArray(parsed.nextActions)) {
+                for (const na of parsed.nextActions) {
+                    if (na?.selector)
+                        selectors.push(na.selector);
+                }
+            }
+        }
+        catch {
+            // Best effort
+        }
+        return selectors;
+    }
+    /**
+     * Replace the ELEMENTS block with a one-line action-only summary.
+     */
+    summarizeElements(text, selectors) {
+        return text.replace(/ELEMENTS[^:\n]*:\n[\s\S]*?(?=\n\n|What action should you take\?|$)/, (match) => {
+            const snapshotStart = match.indexOf('\n');
             if (snapshotStart === -1)
                 return 'ELEMENTS:\n[previous snapshot]';
-            const snapshotText = _match.slice(snapshotStart + 1);
-            const compact = AriaSnapshotHelper.formatCompact(snapshotText);
-            if (compact.length > 0) {
-                return `ELEMENTS (compact):\n${compact}`;
-            }
-            return 'ELEMENTS:\n[previous snapshot]';
+            const snapshotText = match.slice(snapshotStart + 1);
+            const elementCount = (snapshotText.match(/\[ref=\w+\]/g) || []).length;
+            const selectorList = selectors.length > 0
+                ? selectors.join(', ')
+                : 'none';
+            return `ELEMENTS:\n[Page snapshot: ${elementCount} elements | agent used: ${selectorList}]`;
         });
     }
     async decide(goal, state, extraContext, turnInfo, options) {
         const useCompactFirstTurn = this.compactFirstTurn && turnInfo?.current === 1;
         const samePageAsPrevious = this.lastDecisionUrl === state.url;
+        const isFirstTurn = !turnInfo || turnInfo.current <= 1;
+        // Diff-only mode: on same-page turns with small diffs, send only changed
+        // elements instead of the full snapshot. Saves 40-80% of input tokens on
+        // form-fill / interaction-heavy pages where the page structure is stable.
+        const rawDiff = state.snapshotDiffRaw;
+        const diffChanges = rawDiff ? rawDiff.added.length + rawDiff.removed.length + rawDiff.changed.length : 0;
+        const diffTotal = rawDiff ? diffChanges + rawDiff.unchangedCount : 0;
+        const useDiffOnly = samePageAsPrevious
+            && !isFirstTurn
+            && rawDiff !== undefined
+            && diffChanges > 0
+            && diffTotal > 0
+            && diffChanges / diffTotal < 0.3;
         // Tighter snapshot budget on same-page turns — agent already saw the full page
         const snapshotBudget = samePageAsPrevious ? 8_000 : 16_000;
-        const visibleSnapshot = useCompactFirstTurn
-            ? compactFirstTurnSnapshot(state.snapshot)
-            : budgetSnapshot(state.snapshot, snapshotBudget);
+        let visibleSnapshot;
+        let elementsHeader;
+        if (useDiffOnly) {
+            // Build compact diff-only view: changed/added elements with refs
+            const lines = [];
+            if (rawDiff.added.length)
+                lines.push('ADDED:', ...rawDiff.added);
+            if (rawDiff.changed.length)
+                lines.push('CHANGED:', ...rawDiff.changed);
+            if (rawDiff.removed.length)
+                lines.push('REMOVED:', ...rawDiff.removed);
+            lines.push(`(${rawDiff.unchangedCount} elements unchanged — refs from previous turn still valid)`);
+            visibleSnapshot = lines.join('\n');
+            elementsHeader = 'ELEMENTS (diff-only, previous refs still valid)';
+        }
+        else {
+            visibleSnapshot = useCompactFirstTurn
+                ? compactFirstTurnSnapshot(state.snapshot)
+                : budgetSnapshot(state.snapshot, snapshotBudget);
+            elementsHeader = 'ELEMENTS';
+        }
         this.lastDecisionUrl = state.url;
         // Build user message with stable prefix (GOAL) for prompt caching,
         // then dynamic per-turn content (turn budget, page state, elements).
@@ -482,7 +574,7 @@ CURRENT PAGE:
 URL: ${state.url}
 Title: ${state.title}
 
-ELEMENTS:
+${elementsHeader}:
 ${visibleSnapshot}`;
         if (turnInfo) {
             const remaining = turnInfo.max - turnInfo.current;
@@ -498,8 +590,8 @@ ${visibleSnapshot}`;
                 textContent += ` — HALF BUDGET USED. If you have extracted useful data, try completing now. Do not navigate away from pages with relevant content without attempting completion first`;
             }
         }
-        // Append snapshot diff when available and compact (< 30% of full snapshot)
-        if (state.snapshotDiff && state.snapshotDiff.length < state.snapshot.length * 0.3) {
+        // Append snapshot diff only when NOT using diff-only mode (avoid redundant info)
+        if (!useDiffOnly && state.snapshotDiff && state.snapshotDiff.length < state.snapshot.length * 0.3) {
             textContent += `\n\nSNAPSHOT CHANGES (since last turn):\n${state.snapshotDiff}`;
         }
         if (extraContext) {
@@ -523,7 +615,10 @@ ${visibleSnapshot}`;
             ...this.compactHistory(),
             { role: 'user', content: userContent },
         ];
-        const result = await this.generate(useCompactFirstTurn ? FIRST_TURN_COMPACT_PROMPT : this.systemPrompt, messages, { provider: effectiveProvider, model: effectiveModel }, useCompactFirstTurn ? 500 : 1000);
+        const dynamicSystemPrompt = useCompactFirstTurn
+            ? FIRST_TURN_COMPACT_PROMPT
+            : this.buildSystemPrompt(goal, state, turnInfo?.current ?? 1);
+        const result = await this.generate(dynamicSystemPrompt, messages, { provider: effectiveProvider, model: effectiveModel }, useCompactFirstTurn ? 500 : 600);
         const raw = result.text;
         const tokensUsed = result.tokensUsed;
         if (!raw) {
@@ -601,18 +696,14 @@ Please evaluate the quality of this page/application.`;
     }
     async recommendLinkCandidate(goal, state, candidates, extraContext) {
         const topCandidates = candidates.slice(0, 5);
+        // Scout only needs candidates + context, not the full snapshot (saves 2-8k tokens)
         const lines = [
             `GOAL: ${goal}`,
             '',
-            'CURRENT PAGE:',
-            `URL: ${state.url}`,
-            `Title: ${state.title}`,
-            '',
-            'ELEMENTS:',
-            state.snapshot,
+            `PAGE: ${state.url} — ${state.title}`,
             '',
             'CANDIDATES:',
-            ...topCandidates.map((candidate, index) => `${index + 1}. ${candidate.ref} — ${candidate.text} (deterministic score ${candidate.score})`),
+            ...topCandidates.map((candidate, index) => `${index + 1}. ${candidate.ref} — ${candidate.text} (score ${candidate.score})`),
         ];
         if (extraContext) {
             lines.push('', extraContext);
@@ -686,30 +777,11 @@ Was the goal actually achieved? Analyze the current page state carefully.`;
         const verifyModel = this.adaptiveModelRouting && this.navModelName
             ? this.navModelName
             : undefined;
-        const result = await this.generate(`You are verifying whether a browser automation agent actually achieved its goal.
-
-Analyze the page state (screenshot + accessibility tree) and determine if the stated goal was accomplished.
-
-Check the page state and claimed result carefully:
-1. Does the current page state show the goal was completed?
-2. Are there error messages, incomplete forms, or missing elements?
-3. Does the URL match what you'd expect after goal completion?
-4. Is the claimed result consistent with what's visible on the page?
-5. CRITICAL — SUPPLEMENTAL TOOL EVIDENCE: If the claimed result includes "SUPPLEMENTAL TOOL EVIDENCE" or "SCRIPT RESULT" sections, this data was extracted programmatically from the actual page DOM via JavaScript. This evidence is VERIFIED and TRUSTWORTHY — treat it as equivalent to data visible on the current page. It can fully satisfy data requirements (titles, dates, prices, ratings, counts, URLs) even if the current page no longer shows that data. Do NOT reject a completion simply because the extracted data isn't visible in the current accessibility tree.
-6. MULTI-PAGE TASKS: For goals requiring data from multiple pages (e.g., "find X and extract Y"), the agent may have navigated through several pages collecting data via runScript. If the claimed result contains specific data points that match the SUPPLEMENTAL TOOL EVIDENCE, accept the completion even if the current page is a different page from where the data was extracted.
-
-Respond with ONLY a JSON object:
-{
-  "achieved": true,
-  "confidence": 0.9,
-  "evidence": ["The dashboard shows the new item", "URL changed to /success"],
-  "missing": []
-}
+        const result = await this.generate(`Verify whether the browser agent achieved its goal. Respond with ONLY JSON:
+{"achieved":true,"confidence":0.9,"evidence":["observation"],"missing":[]}
 
-- achieved: true if the goal is clearly met, false if not or uncertain
-      - confidence: 0.0 to 1.0 — how sure are you?
-      - evidence: specific observations supporting your judgment
-      - missing: what's still needed (empty array if achieved)`, [{ role: 'user', content: userContent }], verifyProvider && verifyModel ? { provider: verifyProvider, model: verifyModel } : undefined, 600);
+Check: page state matches goal, no errors, URL is expected, claimed result matches visible data.
+SUPPLEMENTAL TOOL EVIDENCE / SCRIPT RESULT in claimed results = verified DOM data, trustworthy even if page navigated away. Multi-page data collection is valid.`, [{ role: 'user', content: userContent }], verifyProvider && verifyModel ? { provider: verifyProvider, model: verifyModel } : undefined, 600);
         const raw = result.text;
         if (this.debug) {
             console.log('[Brain] Goal verification:', raw.slice(0, 300));
@@ -744,7 +816,7 @@ Respond with ONLY a JSON object:
      * Uses vision to analyze layout, typography, spacing, contrast, and UX.
      * Returns structured findings with categories and severity levels.
      */
-    async auditDesign(state, goal, checkpoints) {
+    async auditDesign(state, goal, checkpoints, systemPrompt) {
         const textContent = `GOAL: ${goal}
 
 CHECKPOINTS to verify:
@@ -759,7 +831,7 @@ ${state.snapshot}
 
 Audit this page for design quality, UX issues, and visual bugs.`;
         const userContent = this.buildUserContent(textContent, state.screenshot, true);
-        const result = await this.generate(DESIGN_AUDIT_PROMPT, [{ role: 'user', content: userContent }], undefined, 1500);
+        const result = await this.generate(systemPrompt ?? DESIGN_AUDIT_PROMPT, [{ role: 'user', content: userContent }], undefined, 4000);
         const raw = result.text;
         const tokensUsed = result.tokensUsed;
         if (this.debug) {
@@ -770,7 +842,21 @@ Audit this page for design quality, UX issues, and visual bugs.`;
             if (text.startsWith('```')) {
                 text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
             }
-            const parsed = JSON.parse(text);
+            // Extract JSON object if surrounded by non-JSON text or truncated
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch {
+                const start = text.indexOf('{');
+                const end = text.lastIndexOf('}');
+                if (start >= 0 && end > start) {
+                    parsed = JSON.parse(text.slice(start, end + 1));
+                }
+                else {
+                    throw new Error('No JSON object found');
+                }
+            }
             const VALID_CATEGORIES = new Set(['visual-bug', 'layout', 'contrast', 'alignment', 'spacing', 'typography', 'accessibility', 'ux']);
             const VALID_SEVERITIES = new Set(['critical', 'major', 'minor']);
             const findings = Array.isArray(parsed.findings)
@@ -892,12 +978,74 @@ Only include facts that are genuinely useful. Quality over quantity. Max 10 fact
         }
     }
 }
+/**
+ * Collapse consecutive runs of similar elements (same indent + role, names
+ * differing only by a trailing number/short suffix) into a single representative
+ * line with a count.  Reduces token cost on pages with long pagination, nav
+ * lists, or repeated product cards.
+ *
+ * Skips dialog/alertdialog (agent must see each one) and groups < 3 items.
+ */
+function deduplicateSnapshot(snapshot) {
+    const lines = snapshot.split('\n');
+    const out = [];
+    // Extract (indent, role) from a snapshot line. Returns null for non-element lines.
+    const parseLine = (line) => {
+        const m = line.match(/^(\s*-\s+)(\w+)\s+"([^"]*)"\s*\[ref=(\w+)\]/);
+        if (!m)
+            return null;
+        return { indent: m[1], role: m[2], name: m[3], ref: m[4], full: line };
+    };
+    // Strip trailing numbers/ordinals to get a "name stem" for grouping.
+    // "Page 1" and "Page 20" → "Page ", "Item #3" and "Item #42" → "Item #"
+    const nameStem = (name) => name.replace(/\d+/g, '#');
+    let i = 0;
+    while (i < lines.length) {
+        const parsed = parseLine(lines[i]);
+        // Non-element line or dialog/alertdialog — emit as-is
+        if (!parsed || /\b(?:dialog|alertdialog)\b/i.test(parsed.role)) {
+            out.push(lines[i]);
+            i++;
+            continue;
+        }
+        // Collect a consecutive run of same (indent, role) with similar name stems
+        const group = [parsed];
+        const stem = nameStem(parsed.name);
+        let j = i + 1;
+        while (j < lines.length) {
+            const next = parseLine(lines[j]);
+            if (!next ||
+                next.indent !== parsed.indent ||
+                next.role !== parsed.role ||
+                nameStem(next.name) !== stem)
+                break;
+            group.push(next);
+            j++;
+        }
+        if (group.length < 3) {
+            // Not enough to dedup — emit originals
+            for (const g of group)
+                out.push(g.full);
+        }
+        else {
+            // Emit first element with a summary of the rest
+            const last = group[group.length - 1];
+            out.push(`${parsed.full} (+${group.length - 1} similar: "${group[1].name}"\u2026"${last.name}")`);
+        }
+        i = j;
+    }
+    return out.join('\n');
+}
 /**
  * Cap snapshot size for non-first turns to control token cost on large pages.
  * Keeps the full snapshot when it fits within budget; otherwise truncates
  * non-interactive decorative lines first, then hard-caps with a notice.
  */
 function budgetSnapshot(snapshot, maxChars = 16_000) {
+    // Skip dedup on small snapshots — not enough repetition to justify the O(n) scan
+    if (snapshot.length > 6_000) {
+        snapshot = deduplicateSnapshot(snapshot);
+    }
     if (snapshot.length <= maxChars)
         return snapshot;
     // First pass: drop non-interactive lines (images, paragraphs, decorative text)