@tangle-network/browser-agent-driver 0.33.3 → 0.34.0

package/dist/brain/index.js

@@ -4,411 +4,28 @@
  *
  * Uses Vercel AI SDK for multi-provider support (OpenAI, Anthropic, Google, Codex CLI, Claude Code).
  */
-import { generateText, streamText } from 'ai';
-import { AriaSnapshotHelper } from '../drivers/snapshot.js';
-import { resolveProviderApiKey, resolveProviderModelName, isClaudeCodeRoutedModel, shouldSendTemperature, ZAI_OPENAI_BASE_URL, ZAI_ANTHROPIC_BASE_URL, } from '../provider-defaults.js';
-import { buildFirstPartyBoundaryNote } from '../domain-policy.js';
-import { generateWithSandboxBackend } from '../providers/sandbox-backend.js';
-/** 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.
-
-ACTIONS:
-- {"action": "click", "selector": "@REF"}
-- {"action": "type", "selector": "@REF", "text": "text to type"}
-- {"action": "press", "selector": "@REF", "key": "Enter"} (or Tab, Escape, ArrowDown, etc.)
-- {"action": "hover", "selector": "@REF"}
-- {"action": "select", "selector": "@REF", "value": "option-value"}
-- {"action": "scroll", "direction": "up" | "down", "amount": 500} — add "selector": "@REF" to scroll a specific container
-- {"action": "navigate", "url": "https://..."}
-- {"action": "wait", "ms": 1000}
-- {"action": "evaluate", "criteria": "Is the layout professional? Are colors consistent?"}
-- {"action": "runScript", "script": "document.querySelector('.count').textContent"} — run JS in page context and get the result. Use for reading content not in the a11y tree (canvas, computed styles, hidden state).
-- {"action": "extractWithIndex", "query": "p, span, dd, code", "contains": "downloads"} — return a NUMBERED list of every visible element matching \`query\`, with each element's tag, full textContent, key attributes, and a stable selector. PREFER THIS OVER runScript when you need to find data inside the page but don't know the exact selector. The wide query (e.g. \`'p, span, strong'\`) finds candidates and the response shows the actual text so you can pick by content match. Optional \`contains\` filters matches to those whose text contains a substring (case-insensitive). After this action, your next turn can complete with the picked element's text or click its selector.
-- {"action": "verifyPreview"} — after the app builds, inspect the preview iframe. Returns URL, title, a11y tree, and errors. Use this AFTER you see a preview iframe on the page.
-- {"action": "fill", "fields": {"@t1": "Jordan", "@t2": "Rivera"}, "selects": {"@s1": "WA"}, "checks": ["@c1", "@c2"]} — BATCH fill multiple form fields, dropdowns, and checkboxes in ONE turn. Use this whenever you can see 2+ form fields you need to fill — it's dramatically faster than per-field type/click. fields/selects/checks are all optional but at least one must be non-empty.
-- {"action": "clickSequence", "refs": ["@r1", "@r2", "@r3"]} — click a known sequence of refs in order. Use for multi-step UI navigation chains where the click order is obvious from the page structure.
-- {"action": "complete", "result": "description of what was accomplished"}
-- {"action": "abort", "reason": "why you cannot continue"}
-
-SELECTOR FORMAT:
-- CRITICAL: Replace @REF with an actual ref from the ELEMENTS list below (e.g., @b3cee, @t1f2a)
-- NEVER invent or guess ref IDs — only use refs that appear as [ref=XXX] in the ELEMENTS list
-- Refs are deterministic — same element keeps the same ref across observations
-- Fallback: [data-testid="..."], [aria-label="..."], text="...", role=button[name="..."]
-
-RESPONSE FORMAT — respond with ONLY a JSON object:
-{
-  "plan": ["step 1", "step 2", ...],
-  "currentStep": 0,
-  "action": { "action": "click", "selector": "@REF_FROM_ELEMENTS" },
-  "nextActions": [{ "action": "type", "selector": "@REF_FROM_ELEMENTS", "text": "..." }],
-  "reasoning": "Why I chose this action based on what I see",
-  "expectedEffect": "What should change (e.g., 'URL should contain /chat/', 'modal should close')"
-}
-
-RULES:
-1. Respond with ONLY valid JSON, no markdown or extra text
-2. Use @ref selectors from the ELEMENTS list — they are stable across turns
-3. Include plan, currentStep, reasoning, and expectedEffect in every response
-4. Primary action must be in "action". Optional "nextActions" can contain up to 2 safe follow-ups (click/type/press/hover/select/scroll/wait) only when deterministic
-5. When the goal is achieved, use "complete" with a detailed result description
-6. If stuck after multiple attempts, use "abort" — don't loop forever
-7. LOOK at the screenshot — it shows visual state the a11y tree may miss
-8. If an action failed, try a DIFFERENT approach (different selector, different strategy)
-9. For complex goals, break them into clear plan steps and track progress
-10. Use "evaluate" when you need to assess visual quality, layout, or design
-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
-15. BATCH FILL FOR MULTI-FIELD FORMS: when you can see 2+ form fields that need to be filled, ALWAYS use a single "fill" action with all the fields at once instead of multiple type/click turns. A 5-field form takes 1 turn with fill, not 10 turns with type. Same for dropdowns (use selects map) and checkboxes (use checks array). The page rarely cares which order fields are filled — batch them.
-   - CRITICAL: every key in fields/selects/checks MUST be an @ref taken VERBATIM from the ELEMENTS list (e.g., "@t1f2a"), or a simple [data-testid="..."] selector copied from the DATA-TESTID SELECTORS section. NEVER invent CSS combinators like "[data-testid=\"x\"] input" or "@refXXX child". If a target doesn't appear in the snapshot, use single-step type/click for it instead.
-   - Date inputs (type="date") and spinbuttons (year/month/day) typically need single-step "type" actions, NOT batch fill. They have non-text input behavior that confuses Playwright's fill(). Skip them in your batch and handle them with type after.
-   - If a batch fill fails, do NOT retry the same batch on the next turn. The error message will tell you which target failed — switch to single-step type/click for that target and shrink your next batch to just the targets that work.`;
-/** 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`;
-/** Data extraction rules (18, 21-23, 25): 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, prefer extractWithIndex with a wide query (e.g. \`'p, span, dd, code, strong'\`) over runScript when you don't already see the value in the snapshot. extractWithIndex returns the actual textContent of every match so you can pick the right one by content. Use runScript only when you need a transformation the LLM can't do from text alone.
-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 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 BEFORE clicking into individual items. Use extractWithIndex with a wide query for unknown structure, or runScript with document.querySelectorAll('.result-card') if the structure is well-known. 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.
-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. Do NOT keep searching for more filter controls after one is applied — extract and complete
-25. EXTRACTWITHINDEX RECOVERY: If a previous runScript returned null/empty/{x:null} on an extraction task, the selector was wrong. DO NOT retry the same runScript or guess a similar selector — the LLM cannot guess CSS class names that aren't visible in the snapshot. Switch to extractWithIndex with a WIDE query: \`'p, span, dd, code, strong, em'\` plus a \`contains\` filter naming the expected text fragment (e.g. contains: "downloads" for npm download counts, contains: "callbackFn" for MDN method signatures). The response shows you the actual text per element so you can pick by content match. Pick-by-content beats pick-by-selector on pages where the planner couldn't see the data at plan time.`;
-/** 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`;
-/** URL-first navigation rules for complex forms and search pages.
- * Teaches the agent to construct search/results URLs from goal text
- * instead of fighting form UIs. Works on any site with URL parameters. */
-const URL_FIRST_RULES = `
-URL-FIRST NAVIGATION: When a search form is complex (date pickers, multi-step dropdowns, dynamic widgets), try constructing a results URL directly instead of interacting with the form.
-
-STRATEGY:
-1. Look at the current URL structure. Most search sites encode parameters: ?q=query, ?checkin=date, ?dest=city, etc.
-2. Construct a URL with the goal's parameters filled in. Use the site's own URL pattern.
-3. Navigate directly to that URL — skip the form entirely.
-4. If the URL doesn't work (wrong page, error), fall back to form interaction.
-
-HOW TO DISCOVER URL PATTERNS:
-- If you're on a search results page, the URL already shows the pattern. Modify the parameters for your goal.
-- Most sites accept ?q= or ?search= for keyword queries.
-- Travel sites typically use: checkin/checkout dates, destination/origin, adults count.
-- Use runScript to read window.location.href if the URL isn't visible in the snapshot.
-- ENCODED PARAMETERS: If a URL contains encoded parameters (base64, protobuf), you may be able to replicate them from a previous successful URL, but do NOT invent new encodings. If a navigate with encoded parameters lands on the wrong page, do not retry with a different encoding — it will waste turns.
-
-IMPORTANT EXCEPTIONS — some sites BLOCK direct URL navigation:
-- If a direct URL navigate lands on the homepage or an error page instead of results, the site blocks URL manipulation. STOP trying URLs and use the site's form/search UI instead.
-- After ONE failed URL attempt, switch to form interaction immediately. Do NOT retry different URL patterns — you will waste turns.
-
-FORM RESET DETECTION: Some sites (especially SPAs) silently reset form fields after filling. After batch-filling a form:
-1. Use runScript to verify values stuck: document.querySelector('[aria-label="From"]')?.value or similar.
-2. If fields reset to defaults (wrong city, blank dates), do NOT re-fill with the same approach — it will reset again.
-3. Instead, switch to keyboard-only interaction: click the field, type the value character by character, wait for autocomplete dropdown, press Enter to confirm. Then Tab to the next field.
-
-DATE PICKER STRATEGY: Calendar widgets often ignore programmatic fill/type. When a date field opens a calendar popup that blocks further input:
-1. Try typing the date directly into the field in the site's format (e.g., "Jan 25, 2026" or "01/25/2026"). Press Escape first if the calendar covers the input.
-2. If typing doesn't stick, use runScript to find clickable date elements: document.querySelectorAll('[data-iso],[aria-label*="January"],[aria-label*="25"]') and click the matching element.
-3. NEVER spend more than 4 turns on a single date field.
-
-WHY: Complex forms with date pickers, calendar widgets, and multi-step dropdowns consume many turns and often time out. A single "navigate" action replaces 5-10 form interaction turns. But only use this on sites that support it.`;
-/** 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?
-2. What is the smallest action that makes progress toward the goal?
-3. If multiple elements could match, prefer the one closest to the user-visible label
-4. If an action just failed, identify WHY it failed before trying again
-5. Ask: "Is there a blocker preventing progress right now?" If yes, clear blocker first, then continue goal plan
-
-EXAMPLE 1 — Multi-step form fill (use actual refs from ELEMENTS, not these placeholders):
-{"plan":["Navigate to signup page","Fill email field","Fill password field","Click submit","Verify success"],"currentStep":1,"action":{"action":"type","selector":"@REF","text":"user@example.com"},"reasoning":"I see the signup form with email input [ref=...] and password input [ref=...]. Starting with email since it is the first required field.","expectedEffect":"Email field should show 'user@example.com'"}
-
-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"}
-
-EXAMPLE 3 — Batch fill a multi-field form (one turn instead of ten):
-{"plan":["Fill all visible Personal Info fields","Click Next","Fill Contact step","Submit"],"currentStep":0,"action":{"action":"fill","fields":{"@firstname":"Jordan","@lastname":"Rivera","@dob":"1990-04-15"},"selects":{"@gender":"other"}},"reasoning":"Step 1 of the form has 3 text fields and 1 select all visible at once. Filling them in a single batch action saves 7 turns vs typing each individually.","expectedEffect":"All four Step 1 fields populated with the supplied values"}`;
-/** 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;
-// Vision-first system prompt for pure coordinate actions.
-const VISION_FIRST_PROMPT = `You are a browser automation agent. You operate by looking at screenshots and clicking on elements using pixel coordinates.
-
-The screenshot shows the current page state at 1024×768 resolution. You identify elements visually and specify where to click using (x, y) coordinates in this coordinate space.
-
-ACTIONS:
-- {"action": "clickAt", "x": 512, "y": 384} — click at pixel coordinates (x, y) in 1024×768 space
-- {"action": "typeAt", "x": 300, "y": 200, "text": "search query"} — click at coordinates then type text
-- {"action": "scroll", "direction": "up" | "down", "amount": 500}
-- {"action": "navigate", "url": "https://..."}
-- {"action": "wait", "ms": 1000}
-- {"action": "complete", "result": "description of what was accomplished"}
-- {"action": "abort", "reason": "why you cannot continue"}
-- {"action": "runScript", "script": "document.querySelector('.count').textContent"} — run JS in page context for data the screenshot can't show
-- {"action": "extractWithIndex", "query": "p, span, dd", "contains": "keyword"} — find text in the DOM by content match
-- {"action": "fanOut", "subGoals": [...]} — spawn up to 8 parallel sub-agents in separate tabs (same session/cookies). See FAN-OUT section below for full rules + worked example.
-
-FAN-OUT — PARALLEL INVESTIGATION:
-fanOut is the way to investigate N independent candidates in PARALLEL instead of serially. When the current page shows a list of candidates or you have a queue of independent sub-tasks, emit ONE fanOut action instead of processing them one at a time. The system spawns N sub-agents in fresh tabs of the same session; they run concurrently; their results are merged and returned to you as structured JSON in the NEXT turn's feedback.
-
-STRONGLY PREFER THE SHORTHAND FORM when every branch shares a URL + instruction template. It emits tiny JSON that can't malform:
-
-  {"action":"fanOut","baseUrl":"https://site.example/","goalTemplate":"Investigate {item} — report outcome","items":["X","Y","Z"]}
-
-The string {item} in goalTemplate is replaced with each array entry. Labels default to the item. This is the RIGHT shape for N>=3 branches.
-
-USE fanOut WHEN:
-- A search returned multiple results and each needs investigation (click in / extract / return verdict per row).
-- A batch job has ≥3 independent sub-tasks (screen multiple customers, check multiple products, compare multiple pages).
-- The task is obviously parallelizable and sequential execution would 3x+ the wall-clock time.
-
-DO NOT use fanOut for:
-- A truly sequential task where step 2 depends on step 1's outcome.
-- A single-target investigation (use regular click/type).
-- Cases where fewer than 3 branches would run (overhead not worth it).
-
-SHAPE:
-{
-  "action": "fanOut",
-  "subGoals": [
-    {
-      "url": "https://target.site/",
-      "goal": "Full natural-language instruction for this branch. Must be self-contained because the sub-agent starts from the url with no other context. End with 'Complete with a structured verdict of {schema}.'",
-      "label": "SHORT-LABEL-FOR-OVERLAY",
-      "maxTurns": 8
-    },
-    ... (1-8 entries)
-  ]
-}
-
-WORKED EXAMPLE (OFAC batch screening, after C-001 is done via regular actions):
-{
-  "action": "fanOut",
-  "subGoals": [
-    {"url":"https://sanctionssearch.ofac.treas.gov/","goal":"Click the Reset button, then type 'SMITH' into Last Name and 'JOHN' into First Name. Leave score at 95. Click Search. If 0 matches, complete with result 'CLEARED'. If 1+ exact matches with score 95-100, click the top row, read SDN program + list + DOB, complete with result 'POSITIVE MATCH: <program>/<list>'. Else complete with 'NEEDS REVIEW'.","label":"C-002 SMITH"},
-    {"url":"https://sanctionssearch.ofac.treas.gov/","goal":"Click Reset, type 'MADURO' into Last Name and 'NICOLAS' into First Name. Leave score at 95. Click Search. [same disposition rules]","label":"C-003 MADURO"},
-    ... (up to 8 per fanOut)
-  ]
-}
-
-AFTER fanOut RETURNS, you receive FAN-OUT RESULTS as feedback — a JSON payload with {label, success, verdict, turnsUsed} per branch. Update your progress ledger with each branch's verdict, then either fire another fanOut for the next batch OR complete() if all sub-tasks are done.
-
-EFFICIENCY: one fanOut with 8 branches running in parallel finishes in ~the time of ONE sequential customer (not 8×). For a 10-customer batch, prefer: C-001 sequential (learn the form) → fanOut C-002..C-009 (8 parallel) → C-010 sequential or 2nd fanOut. Target: ~12 parent turns instead of ~50.
-
-COORDINATE SYSTEM:
-- (0, 0) is the top-left corner of the viewport
-- (1024, 768) is the bottom-right corner
-- Click the CENTER of the target element, not its edge
-- For text inputs, click the middle of the input field
-- For buttons, click the center of the button text or icon
-
-RESPONSE FORMAT — respond with ONLY a JSON object:
-{
-  "plan": ["step 1", "step 2", ...],
-  "currentStep": 0,
-  "action": { "action": "clickAt", "x": 512, "y": 384 },
-  "reasoning": "I see [element description] at approximately (x, y). Clicking it to [purpose].",
-  "expectedEffect": "What should change after this action"
-}
-
-RULES:
-1. Respond with ONLY valid JSON, no markdown or extra text
-2. LOOK at the screenshot carefully — it is your primary information source
-3. Include plan, currentStep, reasoning, and expectedEffect in every response
-4. When the goal is achieved, use "complete" with a detailed result description
-5. If stuck after multiple attempts, use "abort" — don't loop forever
-6. If an action failed, try a DIFFERENT approach (different location, different strategy)
-7. For search: click the search box, type your query, then press Enter
-8. For navigation: click visible links or use the "navigate" action for direct URLs
-9. BLOCKER-FIRST: if a modal, cookie banner, or error dialog blocks progress, dismiss it first
-10. Use runScript or extractWithIndex when you need to extract data that isn't clearly visible in the screenshot
-11. BATCH: when filling forms, you can type in one field, then immediately use clickAt on the next field. Plan multiple actions per turn when they are sequential and obvious.
-12. VERIFY BEFORE COMPLETING: Before using "complete", re-read the GOAL and check: does your result ACTUALLY answer what was asked? If the goal asks for "5 beauty salons with ratings > 4.8" and you only found 3, do NOT complete — keep searching. If the goal asks for a specific date/price/name and your result doesn't contain it, do NOT complete. Premature completion with wrong data is worse than using another turn.
-13. DATE PICKER BYPASS: If you encounter a complex date picker widget (calendar popup, date spinner) that is hard to interact with, DO NOT spend multiple turns clicking through calendar months. Instead, use "navigate" to construct a URL with the date parameters encoded. For Google Flights: navigate to google.com/travel/flights with search params. For Booking: navigate to booking.com/searchresults with checkin/checkout params. URL-based date setting is faster and more reliable than fighting date picker UIs.
-
-REASONING FRAMEWORK:
-1. What do I see in the screenshot? Describe the visual layout.
-2. Where is the element I need to interact with? Estimate its (x, y) coordinates.
-3. What is the smallest action that makes progress toward the goal?
-4. If my last action failed, WHY did it fail? Try a different location or strategy.`;
-// Unified vision+DOM prompt. The model sees BOTH the screenshot AND
-// the ARIA snapshot with @refs. It can use EITHER coordinate actions (clickAt/
-// typeAt for visual targets) OR ref actions (click/type/fill for DOM elements).
-// This lets it pick the best tool per interaction: vision for visual layout,
-// DOM for precise form interaction.
-const UNIFIED_VISION_DOM_PROMPT = `You are a browser automation agent with TWO input modalities: a screenshot showing the visual page state, and a structured ELEMENTS list with interactive element refs.
-
-Use BOTH together:
-- The screenshot shows layout, visual state, images, icons — what a human sees
-- The ELEMENTS list shows interactive elements with @ref IDs for precise targeting
-
-ACTIONS — pick the best tool for each interaction:
-
-LABEL ACTIONS (PREFERRED — use the [N] numbered labels visible on the screenshot):
-- {"action": "clickLabel", "label": 3} — click element labeled [3] in the screenshot
-- {"action": "typeLabel", "label": 5, "text": "query"} — click [5] then type text
-The screenshot has numbered red badges on interactive elements. Use these labels — they're MORE ACCURATE than coordinate guessing.
-
-REF ACTIONS (use for form fields, buttons, links with clear @refs from ELEMENTS):
-- {"action": "click", "selector": "@REF"}
-- {"action": "type", "selector": "@REF", "text": "text"}
-- {"action": "press", "selector": "@REF", "key": "Enter"}
-- {"action": "select", "selector": "@REF", "value": "option"}
-- {"action": "fill", "fields": {"@REF1": "val1", "@REF2": "val2"}} — batch fill multiple form fields
-
-COORDINATE ACTIONS (fallback when no label or ref is available):
-- {"action": "clickAt", "x": 512, "y": 384} — click at pixel (x, y) in 1024×768 space
-- {"action": "typeAt", "x": 300, "y": 200, "text": "query"} — click + type
-
-SHARED ACTIONS:
-- {"action": "scroll", "direction": "up" | "down", "amount": 500}
-- {"action": "navigate", "url": "https://..."}
-- {"action": "wait", "ms": 1000}
-- {"action": "runScript", "script": "..."} — run JS in page context
-- {"action": "extractWithIndex", "query": "p, span", "contains": "keyword"}
-- {"action": "complete", "result": "description"}
-- {"action": "abort", "reason": "why"}
-
-WHEN TO USE WHICH (priority order):
-1. Element has a [N] label in the screenshot → use clickLabel/typeLabel (most accurate)
-2. Element has an @ref in ELEMENTS → use click/type/fill (fast and precise)
-3. Element is visible but has no label or ref → use clickAt/typeAt (coordinate fallback)
-- Date pickers, dropdown items rendered dynamically → use clickLabel if labeled, else clickAt
-
-RESPONSE FORMAT — respond with ONLY a JSON object:
-{
-  "plan": ["step 1", "step 2", ...],
-  "currentStep": 0,
-  "action": { "action": "click", "selector": "@REF" },
-  "nextActions": [{ "action": "type", "selector": "@REF2", "text": "query" }],
-  "reasoning": "Why I chose this action",
-  "expectedEffect": "What should change"
-}
-
-NOTE: "nextActions" is optional — include up to 3 safe follow-up actions (click, type, press, clickAt, typeAt, scroll) that are DETERMINISTIC given the current state. For example: click a search box THEN type a query. This saves turns.
-
-RULES:
-1. Respond with ONLY valid JSON
-2. Use @ref selectors from ELEMENTS when available — they are stable and precise
-3. Fall back to clickAt coordinates when the target has no ref or is visual-only
-4. LOOK at the screenshot — it shows visual state the ELEMENTS list may miss
-5. When the goal is achieved, use "complete" with a detailed result
-6. BLOCKER-FIRST: dismiss modals, cookie banners, login walls before continuing
-7. BATCH FILL: when 2+ form fields are visible with refs, use a single "fill" action
-8. If stuck after multiple attempts, use "abort"
-9. VERIFY BEFORE COMPLETING: Before using "complete", re-read the GOAL and check: does your result ACTUALLY answer what was asked? If the goal asks for specific data (prices, names, ratings, counts) and your result doesn't contain ALL of them, keep going. Premature completion with partial data is worse than using another turn.
-10. FORM RESET DETECTION: After batch-filling a form, verify values stuck via runScript. If fields reset to defaults, switch to keyboard-only: click field → type value → wait for autocomplete → press Enter → Tab to next. Do NOT re-fill with the same approach if it reset once.
-11. DATE PICKER STRATEGY: When a calendar popup opens over a date field:
-  a. Press Escape to dismiss, then type the date directly (e.g., "Jan 25, 2026").
-  b. If typing doesn't stick, use runScript to find clickable dates: document.querySelectorAll('[data-iso],[aria-label*="25"]').
-  c. NEVER spend more than 4 turns on a single date field.`;
-/** 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:
-{
-  "plan": ["step 1", "step 2"],
-  "currentStep": 0,
-  "action": { "action": "click", "selector": "@REF" },
-  "nextActions": [],
-  "reasoning": "brief reason",
-  "expectedEffect": "what should change"
-}
-
-Rules:
-1. Use exact @ref selectors from ELEMENTS. Never invent refs.
-2. Prefer the smallest high-signal action.
-3. On landing pages, prefer site search, primary navigation, or an obvious goal-matching link.
-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 = `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.
-
-CHECK FOR:
-- Layout: misaligned elements, broken grids, inconsistent spacing, overflow/clipping
-- Typography: inconsistent font sizes, poor hierarchy, text overflow, unreadable text
-- Colors: poor contrast (WCAG AA requires 4.5:1 for text), inconsistent color palette
-- Spacing: inconsistent padding/margins, crowded elements, excessive whitespace
-- Alignment: elements not vertically/horizontally aligned with their siblings
-- Accessibility: missing labels, unclear focus indicators, keyboard traps
-- UX: confusing navigation, hidden actions, missing feedback states, dead-end flows
-- Visual bugs: z-index issues, overlapping elements, broken images, rendering artifacts
-
-You will also receive CHECKPOINTS — specific conditions to verify. Include a finding for each checkpoint that fails.
-
-For each issue found, categorize it and rate its severity:
-- critical: blocks user flow or causes data loss
-- major: significantly impacts usability or looks unprofessional
-- minor: cosmetic issue, polish improvement
-
-RESPOND WITH ONLY a JSON object:
-{
-  "score": 7,
-  "findings": [
-    {
-      "category": "layout",
-      "severity": "major",
-      "description": "Navigation sidebar overlaps main content on narrower viewports",
-      "location": "Left sidebar, main content area",
-      "suggestion": "Add responsive breakpoint or collapse sidebar below 1024px"
-    }
-  ]
-}
-
-Categories: visual-bug, layout, contrast, alignment, spacing, typography, accessibility, ux
-Score: 1-3 = poor, 4-5 = needs work, 6-7 = acceptable, 8-9 = good, 10 = excellent`;
-const EVALUATE_PROMPT = `You are evaluating the quality of a web page or application output.
-
-Look at the screenshot and assess:
-1. Visual design quality (layout, spacing, colors, typography)
-2. Functionality completeness (does it match the intended goal?)
-3. Professional polish (would this be acceptable in production?)
-4. Accessibility (readable text, good contrast, clear labels)
-5. Responsiveness indicators (proper scaling, no overflow)
-
-Respond with ONLY a JSON object:
-{
-  "score": 8,
-  "assessment": "Brief overall assessment",
-  "strengths": ["strength 1", "strength 2"],
-  "issues": ["issue 1", "issue 2"],
-  "suggestions": ["improvement 1", "improvement 2"]
-}
-
-Score: 1-3 = poor, 4-5 = needs work, 6-7 = acceptable, 8-9 = good, 10 = excellent`;
-const JSON_TEXT_OUTPUT = {
-    name: 'json-text',
-    responseFormat: Promise.resolve({ type: 'json' }),
-    async parseCompleteOutput({ text }) {
-        return text;
-    },
-    async parsePartialOutput({ text }) {
-        return { partial: text };
-    },
-    createElementStreamTransform() {
-        return undefined;
-    },
-};
+import { generateText } from 'ai';
+import { SYSTEM_PROMPT } from './prompts.js';
+import { decideImpl, decideVisionImpl, parseDecision } from './decide.js';
+import { planImpl } from './plan.js';
+import { getModelImpl, getLanguageModelImpl, generateImpl, generationOptionsImpl, completeImpl, completeVisionImpl, } from './model-client.js';
+import { composeSystemPromptPartsImpl, buildSystemForDecideImpl, } from './system-prompt.js';
+import { evaluateImpl } from './tasks/evaluate.js';
+import { recommendLinkCandidateImpl } from './tasks/link-scout.js';
+import { verifyGoalCompletionImpl } from './tasks/goal-verification.js';
+import { auditDesignImpl } from './tasks/design-audit.js';
+import { extractKnowledgeImpl } from './tasks/knowledge.js';
+export { budgetSnapshot } from './snapshot-budget.js';
 export class Brain {
+    // Public fields below satisfy the extracted host interfaces (BrainModelHost,
+    // BrainSystemPromptHost). The free functions in model-client.ts and
+    // system-prompt.ts read them through those interfaces; `implements` makes
+    // tsc prove the surface is complete.
     modelCache = new Map();
     provider;
     modelName;
+    // Public fields below additionally satisfy the extracted task host interfaces
+    // (BrainLinkScoutHost, BrainGoalVerificationHost).
     adaptiveModelRouting;
     navModelName;
     navProvider;
@@ -420,6 +37,10 @@ export class Brain {
     visionEnabled;
     visionStrategy;
     observationMode;
+    // Force streaming input on claude-code so completeVision images are not dropped
+    // (the Claude Code SDK omits image parts without it). Off by default; set only
+    // by the vision-judge wiring. See AgentConfig.claudeCodeStreamingInput.
+    claudeCodeStreamingInput;
     llmTimeoutMs;
     compactFirstTurn;
     lastDecisionUrl;
@@ -459,6 +80,7 @@ export class Brain {
         this.visionEnabled = config.vision !== false;
         this.visionStrategy = config.visionStrategy ?? (this.visionEnabled ? 'always' : 'never');
         this.observationMode = config.observationMode ?? 'dom';
+        this.claudeCodeStreamingInput = config.claudeCodeStreamingInput === true;
         this.compactFirstTurn = config.compactFirstTurn === true;
         this.sandboxBackendType = config.sandboxBackendType;
         this.sandboxBackendProfile = config.sandboxBackendProfile;
@@ -480,449 +102,21 @@ export class Brain {
             this.adaptiveModelRouting = true; // enable routing when executor model is set
         }
     }
-    resolveModelName(provider, requestedModel) {
-        return resolveProviderModelName(provider, requestedModel, {
-            sandboxBackendType: provider === 'sandbox-backend' ? this.sandboxBackendType : undefined,
-        });
-    }
-    shouldSendTemperature(modelName = this.modelName) {
-        // Reasoning models reject an explicit temperature — see the shared
-        // capability check (GPT-5, o-series, Opus 4.8+, Kimi K2.6+, DeepSeek
-        // reasoner).
-        return shouldSendTemperature(modelName);
-    }
     generationOptions(maxOutputTokens, selection) {
-        const providerName = selection?.provider || this.provider;
-        const modelName = this.resolveModelName(providerName, selection?.model || this.modelName);
-        // CLI-spawning providers (codex-cli, claude-code, and zai-coding-plan
-        // when routed through claude-code) don't accept maxOutputTokens through
-        // the AI SDK shape — the subprocess controls its own output.
-        const isCliSpawning = providerName === 'codex-cli' ||
-            providerName === 'claude-code' ||
-            providerName === 'sandbox-backend' ||
-            (providerName === 'zai-coding-plan' && isClaudeCodeRoutedModel(modelName));
-        const omitsLegacyMaxTokens = providerName === 'cli-bridge' || /(^|\/)gpt-5(?:[.-]|$)/i.test(modelName);
-        return {
-            ...(this.shouldSendTemperature(modelName) ? { temperature: 0 } : {}),
-            ...(isCliSpawning || omitsLegacyMaxTokens ? {} : { maxOutputTokens }),
-            // forceReasoning routes the AI SDK to OpenAI's Responses API
-            // (`/v1/responses`). Most third-party OpenAI-compatible proxies
-            // (router.tangle.tools, LiteLLM, Together, vLLM, etc.) only implement
-            // /v1/chat/completions — Responses API requests come back 503 / 4xx
-            // and the SDK throws "Invalid JSON response". Disable on proxied
-            // openai routes; only OpenAI direct supports the Responses API today.
-            ...(providerName === 'openai'
-                && /(^|\/)gpt-5(?:[.-]|$)/i.test(modelName)
-                && !this.isProxiedOpenAI(providerName)
-                ? {
-                    providerOptions: {
-                        openai: {
-                            forceReasoning: true,
-                            maxCompletionTokens: maxOutputTokens,
-                        },
-                    },
-                }
-                : {}),
-        };
-    }
-    /**
-     * True iff we're hitting an OpenAI-compatible *proxy* (router.tangle.tools,
-     * LiteLLM, etc.) rather than OpenAI direct. Used to downshift to the lowest
-     * common denominator API surface — chat-completions, no Responses API,
-     * non-streaming — that every OpenAI-compatible proxy is guaranteed to serve.
-     *
-     * The single source of truth for "we're talking to a proxy, be conservative
-     * about API features"; both `createForceNonStreamingFetch()` and the
-     * `forceReasoning` gate route through this predicate.
-     */
-    isProxiedOpenAI(providerName) {
-        return providerName === 'openai' && Boolean(this.baseUrl);
+        return generationOptionsImpl(this, maxOutputTokens, selection);
     }
     /** Get a LLM model instance, optionally with provider/model override (e.g. for CAPTCHA fallback) */
     async getLanguageModel(selection) {
-        return this.getModel(selection);
+        return getLanguageModelImpl(this, selection);
     }
     /** Lazily create the LLM model instance based on provider config */
-    async getModel(selection) {
-        const providerName = selection?.provider || this.provider;
-        const modelName = this.resolveModelName(providerName, selection?.model || this.modelName);
-        const apiKey = resolveProviderApiKey(providerName, this.explicitApiKey);
-        const cacheKey = `${providerName}:${modelName}`;
-        const cached = this.modelCache.get(cacheKey);
-        if (cached)
-            return cached;
-        let model;
-        switch (providerName) {
-            case 'anthropic': {
-                const { createAnthropic } = await import('@ai-sdk/anthropic');
-                const provider = createAnthropic({
-                    apiKey,
-                    ...(this.baseUrl ? { baseURL: this.baseUrl } : {}),
-                });
-                model = provider(modelName);
-                break;
-            }
-            case 'google': {
-                const { createGoogleGenerativeAI } = await import('@ai-sdk/google');
-                const provider = createGoogleGenerativeAI({
-                    apiKey,
-                    ...(this.baseUrl ? { baseURL: this.baseUrl } : {}),
-                });
-                model = provider(modelName);
-                break;
-            }
-            case 'cli-bridge': {
-                const { createOpenAI } = await import('@ai-sdk/openai');
-                const rawUrl = this.baseUrl || process.env.CLI_BRIDGE_URL;
-                if (!rawUrl) {
-                    throw new Error('cli-bridge provider requires CLI_BRIDGE_URL or --base-url');
-                }
-                const baseURL = rawUrl.endsWith('/v1') ? rawUrl : `${rawUrl.replace(/\/+$/, '')}/v1`;
-                const provider = createOpenAI({
-                    apiKey: apiKey || '',
-                    baseURL,
-                });
-                model = provider.chat(modelName);
-                break;
-            }
-            case 'codex-cli': {
-                const { codexExec } = await import('ai-sdk-provider-codex-cli');
-                const env = {};
-                if (apiKey)
-                    env.OPENAI_API_KEY = apiKey;
-                model = codexExec(modelName, {
-                    allowNpx: process.env.CODEX_ALLOW_NPX !== '0',
-                    skipGitRepoCheck: true,
-                    ...(process.env.CODEX_CLI_PATH ? { codexPath: process.env.CODEX_CLI_PATH } : {}),
-                    ...(Object.keys(env).length > 0 ? { env } : {}),
-                });
-                break;
-            }
-            case 'claude-code': {
-                const { createClaudeCode } = await import('ai-sdk-provider-claude-code');
-                const env = {};
-                if (apiKey)
-                    env.ANTHROPIC_API_KEY = apiKey;
-                const provider = createClaudeCode({
-                    defaultSettings: {
-                        ...(process.env.CLAUDE_CODE_CLI_PATH ? { pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_CLI_PATH } : {}),
-                        permissionMode: 'default',
-                        allowDangerouslySkipPermissions: false,
-                        ...(this.debug ? { verbose: true } : {}),
-                        ...(this.debug
-                            ? {
-                                stderr: (chunk) => {
-                                    const line = chunk.trim();
-                                    if (line)
-                                        console.error(`[claude-code] ${line}`);
-                                },
-                            }
-                            : {}),
-                        ...(Object.keys(env).length > 0 ? { env } : {}),
-                    },
-                });
-                model = provider(modelName);
-                break;
-            }
-            case 'zai-coding-plan': {
-                // Z.ai coding plan: GLM models (glm-4.6, glm-4.5-air) at a fraction
-                // of Anthropic prices. Two backends:
-                //   1. Default — OpenAI-compatible endpoint, native GLM models
-                //   2. claude-code routed — spawn the Claude Code CLI subprocess
-                //      with ANTHROPIC_BASE_URL/AUTH_TOKEN env vars pointed at Z.ai's
-                //      Anthropic-compatible endpoint. The user gets the Claude Code
-                //      agent loop with Z.ai pricing.
-                if (!apiKey) {
-                    throw new Error('zai-coding-plan: API key required (set ZAI_API_KEY env var or pass --api-key)');
-                }
-                if (isClaudeCodeRoutedModel(modelName)) {
-                    const { createClaudeCode } = await import('ai-sdk-provider-claude-code');
-                    const env = {
-                        // Override Claude Code's API base + auth at the env-var level.
-                        // The CLI subprocess inherits these and routes all Anthropic
-                        // API calls to Z.ai's Anthropic-compatible endpoint.
-                        ANTHROPIC_BASE_URL: ZAI_ANTHROPIC_BASE_URL,
-                        ANTHROPIC_AUTH_TOKEN: apiKey,
-                        // Some Claude Code versions still read ANTHROPIC_API_KEY — set
-                        // both so we don't depend on which env var name wins.
-                        ANTHROPIC_API_KEY: apiKey,
-                    };
-                    const provider = createClaudeCode({
-                        defaultSettings: {
-                            ...(process.env.CLAUDE_CODE_CLI_PATH ? { pathToClaudeCodeExecutable: process.env.CLAUDE_CODE_CLI_PATH } : {}),
-                            permissionMode: 'default',
-                            allowDangerouslySkipPermissions: false,
-                            ...(this.debug ? { verbose: true } : {}),
-                            ...(this.debug
-                                ? {
-                                    stderr: (chunk) => {
-                                        const line = chunk.trim();
-                                        if (line)
-                                            console.error(`[zai-claude-code] ${line}`);
-                                    },
-                                }
-                                : {}),
-                            env,
-                        },
-                    });
-                    // The Claude Code SDK takes a model alias (sonnet/haiku/opus); when
-                    // the user passes a glm-* name we just hand it through — Claude
-                    // Code passes it as the model param to the upstream API, which is
-                    // Z.ai's Anthropic-compat endpoint that maps it to the right glm.
-                    // For 'claude-code'/'cc' we default to 'sonnet' which Z.ai aliases
-                    // to its strongest glm model under the coding plan.
-                    const ccModel = modelName === 'claude-code' || modelName === 'cc' ? 'sonnet' : modelName;
-                    model = provider(ccModel);
-                    break;
-                }
-                // Default path — direct OpenAI-compatible API to Z.ai. Z.ai's
-                // paas/v4 endpoint only implements `/chat/completions` (no
-                // `/responses`), so we MUST use `provider.chat(model)` rather than
-                // the bare `provider(model)` call which now defaults to the new
-                // OpenAI Responses API in @ai-sdk/openai v3+.
-                const { createOpenAI } = await import('@ai-sdk/openai');
-                const provider = createOpenAI({
-                    apiKey,
-                    baseURL: ZAI_OPENAI_BASE_URL,
-                });
-                model = provider.chat(modelName);
-                break;
-            }
-            default: {
-                // 'openai' or any OpenAI-compatible API (LiteLLM, Together, etc.).
-                // Same reason as the zai-coding-plan branch above: most third-party
-                // OpenAI-compatible proxies (LiteLLM, vLLM, Together) implement
-                // `/chat/completions` but not the new `/responses` API. Use the
-                // chat factory explicitly so we hit a path the upstream actually
-                // serves.
-                const { createOpenAI } = await import('@ai-sdk/openai');
-                const usingProxy = this.isProxiedOpenAI(providerName);
-                const provider = createOpenAI({
-                    apiKey: apiKey || '',
-                    ...(this.baseUrl ? { baseURL: this.baseUrl } : {}),
-                    // Proxy downshift — see isProxiedOpenAI(). Routes like
-                    // router.tangle.tools default chat-completions to SSE when the
-                    // client omits `stream`, and the AI SDK's generateText errors with
-                    // "Invalid JSON response" on SSE. Force stream: false on every
-                    // chat-completions body. Paired with the forceReasoning gate in
-                    // generationOptions() so all "talk to a proxy" downshifts share
-                    // one predicate.
-                    ...(usingProxy ? { fetch: createForceNonStreamingFetch() } : {}),
-                });
-                model = provider.chat(modelName);
-                break;
-            }
-        }
-        this.modelCache.set(cacheKey, model);
-        return model;
-    }
-    async generate(system, messages, selection, maxOutputTokens = 800) {
-        const providerName = selection?.provider || this.provider;
-        const modelName = this.resolveModelName(providerName, selection?.model || this.modelName);
-        // Sandbox backend doesn't accept structured system messages — flatten.
-        const systemForSandbox = typeof system === 'string'
-            ? system
-            : system.map(m => m.content).join('\n\n');
-        if (providerName === 'sandbox-backend') {
-            const result = await generateWithSandboxBackend({
-                system: systemForSandbox,
-                messages,
-                model: modelName,
-                timeoutMs: this.llmTimeoutMs,
-                debug: this.debug,
-                backendType: this.sandboxBackendType,
-                backendProfile: this.sandboxBackendProfile,
-                backendModelProvider: this.sandboxBackendProvider,
-            });
-            return { text: result.text };
-        }
-        const model = await this.getModel({
-            provider: providerName,
-            model: modelName,
-        });
-        // Anthropic supports structured system messages with cache_control. For
-        // every other provider, flatten back to a string — they ignore the array
-        // form's per-message provider options anyway, and some (claude-code,
-        // codex-cli) wrap their own subprocess CLI which only takes plain text.
-        const systemForRequest = providerName === 'anthropic' || typeof system === 'string'
-            ? system
-            : systemForSandbox;
-        const generationSettings = {
-            model,
-            system: systemForRequest,
-            messages,
-            ...(providerName === 'cli-bridge' ? { output: JSON_TEXT_OUTPUT } : {}),
-            ...this.generationOptions(maxOutputTokens, { provider: providerName, model: modelName }),
-            abortSignal: AbortSignal.timeout(this.llmTimeoutMs),
-        };
-        const result = providerName === 'cli-bridge'
-            ? await (async () => {
-                const streamed = streamText(generationSettings);
-                const [text, usage, providerMetadata] = await Promise.all([
-                    streamed.text,
-                    streamed.totalUsage,
-                    streamed.providerMetadata,
-                ]);
-                return { text, usage, providerMetadata };
-            })()
-            : await generateText(generationSettings);
-        // Extract prompt-cache stats from the AI SDK's PROVIDER-AGNOSTIC fields:
-        //   result.usage.inputTokenDetails.{cacheReadTokens, cacheWriteTokens}
-        //
-        // These flow uniformly from every provider that supports prompt caching:
-        //   - OpenAI (gpt-5.4, gpt-4.1-mini): AUTOMATIC server-side caching for
-        //     >1024 token prefixes, no markers needed. Returns cached_tokens.
-        //   - Anthropic (claude-*): EXPLICIT cache_control markers required (we
-        //     set them in buildSystemForDecide). Returns cache_read_input_tokens.
-        //   - ZAI / GLM (zai-coding-plan via OpenAI-compatible endpoint): AUTOMATIC
-        //     server-side caching, returns cached_tokens in prompt_tokens_details.
-        //   - Google Gemini: explicit `cachedContent` ID-based caching (different
-        //     paradigm — not currently exercised).
-        //
-        // The unified inputTokenDetails fields mean we get cache observability
-        // for free across providers without per-provider extraction code.
-        const inputDetails = result.usage?.inputTokenDetails;
-        let cacheReadInputTokens = typeof inputDetails?.cacheReadTokens === 'number'
-            ? inputDetails.cacheReadTokens
-            : undefined;
-        let cacheCreationInputTokens = typeof inputDetails?.cacheWriteTokens === 'number'
-            ? inputDetails.cacheWriteTokens
-            : undefined;
-        // Fallback: some providers expose cache stats only via providerMetadata.
-        // Anthropic uses cacheReadInputTokens / cacheCreationInputTokens directly,
-        // OpenAI sometimes lands cached_tokens under providerMetadata.openai.
-        if (cacheReadInputTokens === undefined || cacheCreationInputTokens === undefined) {
-            const meta = result.providerMetadata;
-            const anthropicMeta = meta?.anthropic;
-            const openaiMeta = meta?.openai;
-            if (cacheReadInputTokens === undefined) {
-                const fromAnthropic = typeof anthropicMeta?.cacheReadInputTokens === 'number'
-                    ? anthropicMeta.cacheReadInputTokens
-                    : undefined;
-                const fromOpenAI = typeof openaiMeta?.cachedPromptTokens === 'number'
-                    ? openaiMeta.cachedPromptTokens
-                    : undefined;
-                cacheReadInputTokens = fromAnthropic ?? fromOpenAI;
-            }
-            if (cacheCreationInputTokens === undefined) {
-                const fromAnthropic = typeof anthropicMeta?.cacheCreationInputTokens === 'number'
-                    ? anthropicMeta.cacheCreationInputTokens
-                    : undefined;
-                cacheCreationInputTokens = fromAnthropic;
-            }
-        }
-        return {
-            text: result.text,
-            tokensUsed: result.usage?.totalTokens,
-            inputTokens: result.usage?.inputTokens ?? undefined,
-            outputTokens: result.usage?.outputTokens ?? undefined,
-            cacheReadInputTokens,
-            cacheCreationInputTokens,
-        };
-    }
-    /**
-     * Classify whether this turn should use the nav (cheap) model for decide().
-     *
-     * Empirically tested: routing early navigation turns to gpt-4.1-mini causes
-     * worse decisions that cascade into longer runs (more turns = more total cost).
-     * gpt-5.4 without routing is cheaper overall because it navigates more efficiently.
-     *
-     * Current strategy: nav model is ONLY used for verification (see verifyGoalCompletion),
-     * not for decide(). The flag is kept for future experiments with better routing signals.
-     */
-    shouldUseNavigationModel(state, extraContext, turnInfo) {
-        if (!this.adaptiveModelRouting || !this.navModelName)
-            return false;
-        // Use the navigation model for DOM-only same-page turns. Keep the primary
-        // model for first turns, new pages, and error recovery.
-        const isFirstTurn = !turnInfo || turnInfo.current <= 1;
-        const samePageAsPrevious = this.lastDecisionUrl === state.url;
-        const hasError = extraContext?.includes('REJECTED') || extraContext?.includes('ERROR');
-        if (isFirstTurn || !samePageAsPrevious || hasError)
-            return false;
-        return true;
+    getModel(selection) {
+        return getModelImpl(this, selection);
     }
-    /**
-     * 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) {
-        return this.composeSystemPromptParts(goal, state, turn).join('');
-    }
-    /**
-     * Same as buildSystemPrompt but returns the parts so the caller can decide
-     * how to send them. For Anthropic, decide() ships them as a SystemModelMessage[]
-     * with cache_control on the stable CORE_RULES prefix; other providers join.
-     *
-     * The first slot is ALWAYS CORE_RULES (or the user's custom override) so the
-     * cache breakpoint placement is deterministic. Extension-supplied rules are
-     * appended AFTER REASONING_SUFFIX so the cached prefix stays byte-stable
-     * across turns.
-     */
-    composeSystemPromptParts(goal, state, turn) {
-        if (this.systemPrompt !== SYSTEM_PROMPT)
-            return [this.systemPrompt];
-        const parts = [CORE_RULES];
-        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)) {
-            parts.push(SEARCH_RULES);
-            if (this.extensionRules?.search) {
-                parts.push(`\n\nUSER RULES (search):\n${this.extensionRules.search}`);
-            }
-        }
-        if (DATA_EXTRACTION_PATTERN.test(goal)) {
-            parts.push(DATA_EXTRACTION_RULES);
-            if (this.extensionRules?.dataExtraction) {
-                parts.push(`\n\nUSER RULES (data extraction):\n${this.extensionRules.dataExtraction}`);
-            }
-        }
-        if (state.snapshot.length > 10_000 || turn > 10) {
-            parts.push(HEAVY_PAGE_RULES);
-            if (this.extensionRules?.heavy) {
-                parts.push(`\n\nUSER RULES (heavy page):\n${this.extensionRules.heavy}`);
-            }
-        }
-        parts.push(REASONING_SUFFIX);
-        // Global user rules + matching per-domain rules. Both are appended AFTER
-        // REASONING_SUFFIX so they don't pollute the byte-stable cached prefix.
-        if (this.extensionRules?.global) {
-            parts.push(`\n\nUSER RULES (global):\n${this.extensionRules.global}`);
-        }
-        if (this.extensionDomainRules) {
-            const domainRules = this.matchDomainRules(state.url);
-            if (domainRules) {
-                parts.push(`\n\nUSER RULES (domain match):\n${domainRules}`);
-            }
-        }
-        // Macros live AFTER the cached prefix so registering new macros
-        // doesn't bust the Anthropic cache.
-        if (this.macroPromptBlock) {
-            parts.push(`\n\n${this.macroPromptBlock}`);
-        }
-        return parts;
-    }
-    /**
-     * Find the per-domain extra rules whose domain key matches the URL host.
-     * Multiple matches are concatenated in registration order.
-     */
-    matchDomainRules(url) {
-        if (!this.extensionDomainRules)
-            return undefined;
-        let host;
-        try {
-            host = new URL(url).hostname;
-        }
-        catch {
-            return undefined;
-        }
-        const matches = [];
-        for (const [domain, rules] of Object.entries(this.extensionDomainRules)) {
-            if (host.includes(domain) && rules.extraRules) {
-                matches.push(rules.extraRules);
-            }
-        }
-        return matches.length > 0 ? matches.join('\n\n') : undefined;
+    // Public so the extracted task impls (src/brain/tasks/*) can reach it through
+    // their host interfaces. The class still owns the single transport funnel.
+    generate(system, messages, selection, maxOutputTokens = 800) {
+        return generateImpl(this, system, messages, selection, maxOutputTokens);
     }
     /**
      * Inject extension-supplied rules. Called by the runner after loading
@@ -937,6 +131,9 @@ export class Brain {
     setMacroPromptBlock(block) {
         this.macroPromptBlock = block ?? '';
     }
+    composeSystemPromptParts(goal, state, turn) {
+        return composeSystemPromptPartsImpl(this, goal, state, turn);
+    }
     /**
      * Build the system prompt for `decide()` in the form best suited to the
      * active provider:
@@ -949,25 +146,7 @@ export class Brain {
      * is opt-in via the default prompt path only.
      */
     buildSystemForDecide(goal, state, turn, providerName) {
-        const parts = this.composeSystemPromptParts(goal, state, turn);
-        if (providerName !== 'anthropic' || this.systemPrompt !== SYSTEM_PROMPT || parts.length === 0) {
-            return parts.join('');
-        }
-        // Anthropic path: first slot is CORE_RULES (cached), remaining parts ship
-        // as a separate uncached system message so the prefix stays byte-stable
-        // across turns and the cache hits.
-        const corePart = {
-            role: 'system',
-            content: parts[0],
-            providerOptions: {
-                anthropic: {
-                    cacheControl: { type: 'ephemeral' },
-                },
-            },
-        };
-        if (parts.length === 1)
-            return [corePart];
-        return [corePart, { role: 'system', content: parts.slice(1).join('') }];
+        return buildSystemForDecideImpl(this, goal, state, turn, providerName);
     }
     /** Reset conversation history (call between scenarios) */
     reset() {
@@ -1021,6 +200,8 @@ export class Brain {
      * Build the user message content parts — text + optional screenshot.
      * Multimodal when vision is enabled and screenshot is available.
      */
+    // Public so the extracted task impls (src/brain/tasks/*) can reach it through
+    // their host interfaces.
     buildUserContent(text, screenshot, forceVision = false) {
         const shouldUseVision = !!screenshot && (this.visionStrategy === 'always'
             || (this.visionStrategy === 'auto' && forceVision));
@@ -1036,327 +217,8 @@ export class Brain {
             },
         ];
     }
-    /**
-     * Compact conversation history: strip ELEMENTS blocks and screenshots
-     * from older observations, keeping the last 2 user messages intact.
-     *
-     * 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;
-        // Three-tier compression:
-        //   Zone 1 (intact):         last 2 turns — full content
-        //   Zone 2 (standard):       turns 3-5 back — ELEMENTS stripped from user msgs
-        //   Zone 3 (deep compact):   turns 6+ back — both user and assistant ultra-compacted
-        // Keep enough older history for long multi-step travel workflows.
-        const deepCompactBefore = Math.max(0, this.history.length - 10);
-        return this.history.map((msg, idx) => {
-            // Zone 1: keep recent turns intact
-            if (idx >= keepIntactFrom)
-                return msg;
-            // Zone 3: ultra-compact for very old messages (user + assistant)
-            if (idx < deepCompactBefore) {
-                if (msg.role === 'assistant') {
-                    const raw = typeof msg.content === 'string' ? msg.content : '';
-                    return { ...msg, content: this.deepCompactAssistant(raw) };
-                }
-                if (msg.role === 'user') {
-                    return { ...msg, content: this.deepCompactUser(msg) };
-                }
-                return msg;
-            }
-            // Zone 2: standard compact — strip ELEMENTS from user messages only
-            if (msg.role !== 'user')
-                return msg;
-            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
-                    .filter((part) => part.type === 'text')
-                    .map((part) => ({
-                    ...part,
-                    text: this.summarizeElements(part.text, selectors),
-                }));
-                return { ...msg, content: compacted };
-            }
-            // Handle string content
-            if (typeof msg.content === 'string') {
-                return { ...msg, content: this.summarizeElements(msg.content, selectors) };
-            }
-            return msg;
-        });
-    }
-    deepCompactUser(msg) {
-        const text = typeof msg.content === 'string'
-            ? msg.content
-            : Array.isArray(msg.content)
-                ? msg.content
-                    .filter((p) => p.type === 'text')
-                    .map((p) => p.text)
-                    .join('\n')
-                : '';
-        const urlMatch = text.match(/URL:\s*(\S+)/);
-        const titleMatch = text.match(/Title:\s*(.+?)(?:\n|$)/);
-        const url = urlMatch?.[1] ?? 'unknown';
-        const title = titleMatch?.[1]?.slice(0, 80) ?? '';
-        return `[Prior turn — URL: ${url}${title ? ` | ${title}` : ''}]`;
-    }
-    deepCompactAssistant(raw) {
-        try {
-            let text = raw.trim();
-            if (text.startsWith('```')) {
-                text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-            }
-            const parsed = JSON.parse(text);
-            const action = parsed.action?.action ?? 'unknown';
-            const selector = parsed.action?.selector ?? '';
-            const parts = [action];
-            if (selector)
-                parts.push(selector);
-            if (parsed.action?.url)
-                parts.push(parsed.action.url.slice(0, 120));
-            return `[${parts.join(' → ')}]`;
-        }
-        catch {
-            return raw.slice(0, 100) + (raw.length > 100 ? '…' : '');
-        }
-    }
-    /**
-     * 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 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) {
-        // Vision-first and hybrid modes delegate to the vision path.
-        if (this.observationMode === 'vision' || this.observationMode === 'hybrid') {
-            return this.decideVision(goal, state, extraContext, turnInfo);
-        }
-        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; new pages keep enough
-        // content for extraction from docs/spec pages.
-        const snapshotBudget = samePageAsPrevious ? 8_000 : 24_000;
-        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).
-        let textContent = `GOAL: ${goal}
-
-CURRENT PAGE:
-URL: ${state.url}
-Title: ${state.title}
-
-${elementsHeader}:
-${visibleSnapshot}`;
-        if (turnInfo) {
-            const remaining = turnInfo.max - turnInfo.current;
-            const budgetUsed = turnInfo.current / turnInfo.max;
-            textContent += `\n\nTURN: ${turnInfo.current}/${turnInfo.max} (${remaining} remaining)`;
-            if (remaining === 1) {
-                textContent += ` — FINAL TURN: return a terminal action only (complete or abort)`;
-            }
-            else if (remaining <= 3) {
-                textContent += ` — RUNNING LOW, avoid exploratory navigation; prioritize completing the goal or aborting with a clear blocker reason`;
-            }
-            else if (budgetUsed >= 0.5) {
-                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 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) {
-            textContent += `\n\n${extraContext}`;
-        }
-        textContent += '\n\nWhat action should you take?';
-        const userContent = this.buildUserContent(textContent, state.screenshot, options?.forceVision === true);
-        const useNavModel = this.shouldUseNavigationModel(state, extraContext, turnInfo);
-        const effectiveProvider = useNavModel ? (this.navProvider || this.provider) : this.provider;
-        const effectiveModel = useNavModel ? (this.navModelName || this.modelName) : this.modelName;
-        if (this.debug) {
-            const turnNum = Math.floor(this.history.length / 2) + 1;
-            const usingVision = !!state.screenshot && (this.visionStrategy === 'always' || (this.visionStrategy === 'auto' && options?.forceVision === true));
-            console.log(`[Brain] Turn ${turnNum} | URL: ${state.url} | Vision: ${usingVision}`);
-            if (this.adaptiveModelRouting) {
-                const mode = useNavModel ? 'nav-model' : 'primary-model';
-                console.log(`[Brain] Model route: ${mode} (${effectiveProvider}/${effectiveModel}) turn=${turnInfo?.current}/${turnInfo?.max}`);
-            }
-        }
-        const messages = [
-            ...this.compactHistory(),
-            { role: 'user', content: userContent },
-        ];
-        const dynamicSystemPrompt = useCompactFirstTurn
-            ? FIRST_TURN_COMPACT_PROMPT
-            : this.buildSystemForDecide(goal, state, turnInfo?.current ?? 1, effectiveProvider);
-        const modelOpts = { provider: effectiveProvider, model: effectiveModel };
-        // Bump output budget near max turns so data-heavy completions don't truncate
-        const nearingEnd = turnInfo && turnInfo.current >= turnInfo.max - 3;
-        const maxTokens = useCompactFirstTurn ? 500 : nearingEnd ? 1200 : 600;
-        const result = await this.generate(dynamicSystemPrompt, messages, modelOpts, maxTokens);
-        let raw = result.text;
-        let tokensUsed = result.tokensUsed;
-        let inputTokens = result.inputTokens;
-        let outputTokens = result.outputTokens;
-        let cacheReadInputTokens = result.cacheReadInputTokens;
-        let cacheCreationInputTokens = result.cacheCreationInputTokens;
-        if (!raw) {
-            throw new Error('Brain.decide: LLM returned empty response — possible rate limit or model error');
-        }
-        if (this.debug) {
-            console.log('[Brain] Response:', raw.slice(0, 300));
-        }
-        let parsed = this.parse(raw);
-        // On malformed JSON, retry with minimal context (current page + correction
-        // hint) instead of burning a full turn. Costs ~7K tokens vs ~25K for a
-        // full-history retry on the next turn.
-        if (parsed.reasoning?.startsWith('Malformed LLM JSON response') && !useCompactFirstTurn) {
-            if (this.debug) {
-                console.log('[Brain] Malformed JSON — retrying with format hint');
-            }
-            const retryMessages = [
-                { role: 'user', content: userContent },
-                { role: 'assistant', content: raw },
-                { role: 'user', content: 'Your previous response was not valid JSON. Respond with ONLY a valid JSON object matching the required schema.' },
-            ];
-            try {
-                const retryResult = await this.generate(dynamicSystemPrompt, retryMessages, modelOpts, maxTokens);
-                if (retryResult.text) {
-                    const retryParsed = this.parse(retryResult.text);
-                    if (!retryParsed.reasoning?.startsWith('Malformed LLM JSON response')) {
-                        raw = retryResult.text;
-                        parsed = retryParsed;
-                    }
-                    else if (this.baseUrl) {
-                        // Both the initial parse and the format-hint retry failed while a
-                        // custom LLM_BASE_URL is set. Strong signal the gateway is
-                        // returning a shape the scout can't consume (e.g. SSE streams,
-                        // non-JSON wrappers). Surface the likely cause instead of
-                        // burning silent retries turn after turn.
-                        console.error(`[Brain] scout_json_parse_failed: LLM_BASE_URL=${this.baseUrl} returned a response the scout could not parse even after a format-hint retry. ` +
-                            `Suggestion: switch to an Anthropic-native endpoint, or verify the gateway supports non-streaming chat/completions with { "response_format": { "type": "json_object" } }.`);
-                    }
-                    tokensUsed = (tokensUsed ?? 0) + (retryResult.tokensUsed ?? 0);
-                    inputTokens = (inputTokens ?? 0) + (retryResult.inputTokens ?? 0);
-                    outputTokens = (outputTokens ?? 0) + (retryResult.outputTokens ?? 0);
-                    if (retryResult.cacheReadInputTokens !== undefined) {
-                        cacheReadInputTokens = (cacheReadInputTokens ?? 0) + retryResult.cacheReadInputTokens;
-                    }
-                    if (retryResult.cacheCreationInputTokens !== undefined) {
-                        cacheCreationInputTokens = (cacheCreationInputTokens ?? 0) + retryResult.cacheCreationInputTokens;
-                    }
-                }
-            }
-            catch {
-                // Retry failed — fall through with original wait(1000) fallback
-            }
-        }
-        // Store in history
-        this.history.push({ role: 'user', content: userContent });
-        this.history.push({ role: 'assistant', content: raw });
-        // Trim old history
-        const maxMessages = this.maxHistoryTurns * 2;
-        if (this.history.length > maxMessages) {
-            this.history = this.history.slice(-maxMessages);
-        }
-        return {
-            ...parsed,
-            raw,
-            tokensUsed,
-            inputTokens,
-            outputTokens,
-            cacheReadInputTokens,
-            cacheCreationInputTokens,
-            modelUsed: effectiveModel,
-        };
+        return decideImpl(this, goal, state, extraContext, turnInfo, options);
     }
     /**
      * Vision-first decision path. The screenshot is the primary
@@ -1365,120 +227,7 @@ ${visibleSnapshot}`;
      * coordinate-based actions (clickAt, typeAt) in 1024×768 virtual space.
      */
     async decideVision(goal, state, extraContext, turnInfo) {
-        this.lastDecisionUrl = state.url;
-        // Adaptive observation: on same-page hybrid turns, send only changed
-        // elements when the diff is small.
-        const isHybrid = this.observationMode === 'hybrid';
-        const samePageAsPrevious = this.lastDecisionUrl === state.url;
-        const isFirstTurn = !turnInfo || turnInfo.current <= 1;
-        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 = isHybrid && samePageAsPrevious && !isFirstTurn
-            && rawDiff !== undefined && diffChanges > 0 && diffTotal > 0
-            && diffChanges / diffTotal < 0.4;
-        let textContent = `GOAL: ${goal}
-
-CURRENT PAGE:
-URL: ${state.url}
-Title: ${state.title}`;
-        if (isHybrid && state.snapshot) {
-            if (useDiffOnly) {
-                // Diff-focused: only what changed since last turn
-                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)`);
-                textContent += `\n\nPAGE CHANGES (what changed after your last action — this is the important part):\n${lines.join('\n')}`;
-            }
-            else {
-                // Progressive budget reduction: more turns on same page = less snapshot
-                // needed (agent has already seen the full page, rely on screenshot + diff).
-                const sameTurnCount = samePageAsPrevious ? (turnInfo?.current || 0) : 0;
-                const snapshotBudget = samePageAsPrevious
-                    ? (sameTurnCount >= 8 ? 2_500 : 4_000) // aggressive after 8+ same-page turns
-                    : 6_000;
-                const snap = budgetSnapshot(state.snapshot, snapshotBudget);
-                textContent += `\n\nELEMENTS:\n${snap}`;
-            }
-        }
-        if (turnInfo) {
-            const remaining = turnInfo.max - turnInfo.current;
-            textContent += `\n\nTURN: ${turnInfo.current}/${turnInfo.max} (${remaining} remaining)`;
-            if (remaining === 1) {
-                textContent += ` — FINAL TURN: return a terminal action only (complete or abort)`;
-            }
-            else if (remaining <= 3) {
-                textContent += ` — RUNNING LOW, prioritize completing the goal or aborting`;
-            }
-        }
-        if (extraContext) {
-            textContent += `\n\n${extraContext}`;
-        }
-        textContent += '\n\nLook at the screenshot. What action should you take?';
-        // Screenshot is required for vision-first mode
-        if (!state.screenshot) {
-            return {
-                action: { action: 'wait', ms: 500 },
-                reasoning: 'No screenshot available for vision-first mode — waiting for page to render',
-                raw: '{"action":{"action":"wait","ms":500}}',
-            };
-        }
-        const userContent = [
-            { type: 'text', text: textContent },
-            { type: 'image', image: state.screenshot, mediaType: 'image/jpeg' },
-        ];
-        // Strip old screenshots from history; the current screenshot is the only
-        // image the model needs for this turn.
-        const compacted = this.compactHistory().map((msg) => {
-            if (msg.role !== 'user' || !Array.isArray(msg.content))
-                return msg;
-            const textOnly = msg.content
-                .filter((part) => part.type === 'text');
-            if (textOnly.length === msg.content.length)
-                return msg;
-            return { ...msg, content: textOnly };
-        });
-        const messages = [
-            ...compacted,
-            { role: 'user', content: userContent },
-        ];
-        // Vision turns stay on the main model because smaller model routes can
-        // count image tokens differently and exhaust the token budget.
-        const modelOpts = { provider: this.provider, model: this.modelName };
-        const nearingEnd = turnInfo && turnInfo.current >= turnInfo.max - 3;
-        const maxTokens = nearingEnd ? 1200 : 600;
-        // Hybrid mode uses the unified prompt with both action vocabularies.
-        const systemPrompt = isHybrid ? UNIFIED_VISION_DOM_PROMPT : VISION_FIRST_PROMPT;
-        const result = await this.generate(systemPrompt, messages, modelOpts, maxTokens);
-        const raw = result.text;
-        if (!raw) {
-            throw new Error('Brain.decideVision: LLM returned empty response');
-        }
-        if (this.debug) {
-            console.log('[Brain/Vision] Response:', raw.slice(0, 300));
-        }
-        const parsed = this.parse(raw);
-        this.history.push({ role: 'user', content: userContent });
-        this.history.push({ role: 'assistant', content: raw });
-        const maxMessages = this.maxHistoryTurns * 2;
-        if (this.history.length > maxMessages) {
-            this.history = this.history.slice(-maxMessages);
-        }
-        return {
-            ...parsed,
-            raw,
-            tokensUsed: result.tokensUsed,
-            inputTokens: result.inputTokens,
-            outputTokens: result.outputTokens,
-            cacheReadInputTokens: result.cacheReadInputTokens,
-            cacheCreationInputTokens: result.cacheCreationInputTokens,
-            modelUsed: this.modelName,
-        };
+        return decideVisionImpl(this, goal, state, extraContext, turnInfo);
     }
     /**
      * Generate a structured plan for the entire task with one LLM call.
@@ -1494,224 +243,7 @@ Title: ${state.title}`;
      * use per-action loop".
      */
     async plan(goal, state, options) {
-        const startedAt = Date.now();
-        const maxSteps = options?.maxSteps ?? 12;
-        const extraContext = options?.extraContext;
-        // Planner snapshots keep enough context for extraction tasks, especially
-        // docs/spec pages with data in `<dl>`, `<code>`, and `<pre>` blocks.
-        const snapshot = budgetSnapshot(state.snapshot, 24_000);
-        const planSystemPrompt = `You are a planning engine for a browser automation agent.
-
-Given a user goal and the current page state, your job is to generate a complete, ordered plan of actions that the agent will execute deterministically without re-entering you between steps. After each step, the runner verifies your stated post-condition. If verification fails the runner falls back to a per-action loop, so your job is to write a plan that requires the FEWEST steps and where every step's post-condition is reliably observable.
-
-KEY PRINCIPLES:
-
-1. PREFER BATCH VERBS. The driver supports batch \`fill\` (fill N text fields, set N selects, check N checkboxes in ONE action) and \`clickSequence\` (N sequential clicks). Use these aggressively. A 19-field form should be 2-4 fill steps, not 19 type steps.
-
-   CRITICAL EXCLUSION: DO NOT INCLUDE ANY SPINBUTTON OR DATE INPUT IN YOUR PLAN. AT ALL. Period. If you see \`spinbutton\` in the snapshot (year, month, day, hour, minute spinners) or any input that looks like a date/time picker, OMIT it from your plan completely. Playwright's locator.fill() and locator.click() both time out on these elements, and your plan will deviate and fall back to the per-action loop. The per-action fallback knows how to handle them. Just LEAVE THEM OUT. Your plan should silently skip those elements and continue with the rest of the task as if they don't exist. The runner WILL handle them after your plan completes — you do not need to plan a step for them.
-
-2. ASSUME THE SNAPSHOT IS COMPLETE. The agent will execute your plan deterministically — you only get to see the page state ONCE (now). All @refs you emit must come from the ELEMENTS list below. Do not invent refs. If you don't see an element you'd need, do NOT plan a step for it — leave a gap and the runner will recover.
-
-3. POST-CONDITIONS MUST BE OBSERVABLE. Each step's expectedEffect should describe a concrete change the runner can see in the next snapshot: a URL change, a new visible element, a status text update. Vague effects like "form is filled" are useless because verification can't check them. Use concrete strings: "Status text shows 'Account Created!'" or "URL contains /confirm/".
-
-4. NAVIGATION CHANGES THE PAGE. Once you emit a \`navigate\`, \`click\` on a Next button, or any action that loads a new page, the @refs from the current snapshot are NO LONGER VALID. After such an action, your subsequent steps cannot rely on the same refs — they must use natural-language post-conditions until the runner falls back to per-action mode and observes the new page.
-
-5. MAX ${maxSteps} STEPS. If the task genuinely requires more, plan the first ${maxSteps} and let the runner replan from the resulting state.
-
-6. ONLY EMIT \`complete\` IF THE FINAL POST-CONDITION IS GENUINELY VERIFIABLE FROM THE PRIOR STEP'S expectedEffect. Do NOT fabricate success. If you cannot reliably know from the initial state alone whether the task succeeded (e.g. you can't predict whether a server submission will succeed, you don't know what the success message will say, or the form has multi-step navigation past your visibility), simply STOP planning at the last step you're confident about. The runner will fall through to the per-action loop after your plan exhausts and that loop will continue toward completion. It is BETTER to plan 5 confident steps and let the per-action loop finish than to plan 12 speculative steps with a fabricated complete at the end.
-
-7. EXTRACTION TASKS: when the goal asks you to READ, EXTRACT, REPORT, or RETURN values from the page (numbers, text, lists, structured data), the LAST step of your plan MUST be \`runScript\`. Do NOT emit a \`complete\` step after the runScript with literal values in \`result\`, because at planning time you cannot know what runScript will return — any values you write would be fabricated. The runner has a deterministic substitution path: it will use the runScript output as the final result, OR fall through to per-action mode where the LLM can see the script output. Either way is fine. The wrong move is to put placeholder JSON like \`{"x":null,"y":null}\` or \`"<from prior step>"\` in the complete result; the runner detects and replaces those, but it's cleaner if you simply omit the complete step. RIGHT: \`[{action:runScript, script:"..."}]\`. WRONG: \`[{action:runScript,...}, {action:complete, result:"{x:null}"}]\`.
-
-ACTION VERBS (same as the per-action prompt):
-- {"action": "click", "selector": "@REF"} — use when the element has a ref in ELEMENTS
-- {"action": "type", "selector": "@REF", "text": "..."} — type into a ref element
-- {"action": "press", "selector": "@REF", "key": "Enter"}
-- {"action": "select", "selector": "@REF", "value": "..."}
-- {"action": "clickAt", "x": 512, "y": 384} — click at pixel coordinates (use when you can see the element in the screenshot but it has no ref)
-- {"action": "typeAt", "x": 300, "y": 200, "text": "..."} — click at coordinates then type
-- {"action": "scroll", "direction": "up"|"down", "amount": 500}
-- {"action": "navigate", "url": "..."}
-- {"action": "wait", "ms": 1000}
-- {"action": "fill", "fields": {"@a": "v1", "@b": "v2"}, "selects": {"@c": "v3"}, "checks": ["@d", "@e"]}
-- {"action": "clickSequence", "refs": ["@a", "@b", "@c"]}
-- {"action": "runScript", "script": "document.querySelector('.x').textContent"}
-- {"action": "extractWithIndex", "query": "p, span, dd, code", "contains": "downloads"} — return a NUMBERED list of visible elements matching the query with their full textContent. Use this for extraction tasks where the data lives in obscurely-classed wrappers (npm download counts, MDN \`<dl>/<dt>/<dd>\` content, Python docs \`<code>\` blocks, W3C spec content) and the planner cannot guarantee a precise selector. The next step (in plan or per-action mode) reads the result and picks the right index. STRONGLY PREFER THIS OVER runScript on ANY extraction task where the snapshot doesn't already show the value verbatim.
-- {"action": "complete", "result": "..."}
-- {"action": "abort", "reason": "..."}
-
-${URL_FIRST_RULES}
-
-RESPONSE FORMAT — respond with ONLY this JSON:
-{
-  "reasoning": "1-2 sentence strategy summary",
-  "steps": [
-    {
-      "action": { "action": "fill", "fields": { "@t1": "Jordan", "@t2": "Rivera" } },
-      "expectedEffect": "First name and last name fields are populated",
-      "rationale": "Step 1 of the multi-step form: batch-fill all visible Personal Info text fields"
-    },
-    ...
-  ],
-  "finalResult": "Account creation form completed and confirmation visible"
-}
-
-DO NOT include any prose outside the JSON. DO NOT use markdown code blocks. The runner parses your response with JSON.parse() and will fall through to the per-action loop on parse failure.`;
-        // Replan path: when the runner re-enters plan() after a previous plan
-        // deviated, it injects a deviation summary. The system prompt is byte-
-        // stable so prompt cache still hits — only the user message changes.
-        const userText = `GOAL: ${goal}
-
-CURRENT PAGE:
-URL: ${state.url}
-Title: ${state.title}
-
-ELEMENTS:
-${snapshot}
-${extraContext ? `\n${extraContext}\n` : ''}
-What is the complete plan?`;
-        // In vision-capable modes, include the screenshot so the planner can use
-        // visual layout when the DOM does not capture form structure.
-        const isVisionPlanner = (this.observationMode === 'hybrid' || this.observationMode === 'vision') && !!state.screenshot;
-        const userContent = isVisionPlanner
-            ? [
-                { type: 'text', text: userText },
-                { type: 'image', image: state.screenshot, mediaType: 'image/jpeg' },
-            ]
-            : userText;
-        // Planner can use its own model override.
-        const planModelOpts = this.plannerModel
-            ? { provider: (this.plannerProvider || this.provider), model: this.plannerModel }
-            : { provider: this.provider, model: this.modelName };
-        const result = await this.generate(planSystemPrompt, [{ role: 'user', content: userContent }], planModelOpts, 
-        // Plans need more output tokens than decide() — a 10-step plan with
-        // batch fills + rationale per step is comfortably over 1000 tokens.
-        2_500).catch((err) => ({
-            text: '',
-            tokensUsed: undefined,
-            inputTokens: undefined,
-            outputTokens: undefined,
-            cacheReadInputTokens: undefined,
-            cacheCreationInputTokens: undefined,
-            _error: err instanceof Error ? err.message : String(err),
-        }));
-        const durationMs = Date.now() - startedAt;
-        const raw = result.text;
-        if (!raw) {
-            return {
-                plan: null,
-                raw: '',
-                durationMs,
-                parseError: result._error ?? 'empty response',
-            };
-        }
-        // Reuse the same JSON tolerance as decide(): strip markdown fences,
-        // then JSON.parse. On parse failure, return null and let the runner
-        // fall through.
-        let body = raw.trim();
-        if (body.startsWith('```')) {
-            body = body.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(body);
-        }
-        catch (err) {
-            return {
-                plan: null,
-                raw,
-                durationMs,
-                tokensUsed: result.tokensUsed,
-                inputTokens: result.inputTokens,
-                outputTokens: result.outputTokens,
-                cacheReadInputTokens: result.cacheReadInputTokens,
-                cacheCreationInputTokens: result.cacheCreationInputTokens,
-                parseError: err instanceof Error ? err.message : String(err),
-            };
-        }
-        if (!Array.isArray(parsed.steps) || parsed.steps.length === 0) {
-            return {
-                plan: null,
-                raw,
-                durationMs,
-                tokensUsed: result.tokensUsed,
-                inputTokens: result.inputTokens,
-                outputTokens: result.outputTokens,
-                cacheReadInputTokens: result.cacheReadInputTokens,
-                cacheCreationInputTokens: result.cacheCreationInputTokens,
-                parseError: 'plan has zero steps',
-            };
-        }
-        // Validate each step. Each must have a parseable action and a non-empty
-        // expectedEffect string. We use the same validateAction helper that the
-        // per-action parser uses, so the action shapes stay consistent.
-        const steps = [];
-        for (const [idx, rawStep] of parsed.steps.entries()) {
-            if (!rawStep || typeof rawStep !== 'object') {
-                return {
-                    plan: null,
-                    raw,
-                    durationMs,
-                    tokensUsed: result.tokensUsed,
-                    inputTokens: result.inputTokens,
-                    outputTokens: result.outputTokens,
-                    cacheReadInputTokens: result.cacheReadInputTokens,
-                    cacheCreationInputTokens: result.cacheCreationInputTokens,
-                    parseError: `step ${idx + 1}: not an object`,
-                };
-            }
-            const stepObj = rawStep;
-            const actionRaw = stepObj.action;
-            if (!actionRaw || typeof actionRaw !== 'object') {
-                return {
-                    plan: null,
-                    raw,
-                    durationMs,
-                    parseError: `step ${idx + 1}: missing action`,
-                };
-            }
-            const actionData = actionRaw;
-            const actionType = actionData.action;
-            if (typeof actionType !== 'string') {
-                return {
-                    plan: null,
-                    raw,
-                    durationMs,
-                    parseError: `step ${idx + 1}: action.action must be a string`,
-                };
-            }
-            let action;
-            try {
-                action = validateAction(actionType, actionData);
-            }
-            catch (err) {
-                return {
-                    plan: null,
-                    raw,
-                    durationMs,
-                    parseError: `step ${idx + 1}: ${err instanceof Error ? err.message : String(err)}`,
-                };
-            }
-            const expectedEffect = typeof stepObj.expectedEffect === 'string' && stepObj.expectedEffect.length > 0
-                ? stepObj.expectedEffect
-                : 'page state advances after this action';
-            const rationale = typeof stepObj.rationale === 'string' ? stepObj.rationale : undefined;
-            steps.push({ action, expectedEffect, ...(rationale ? { rationale } : {}) });
-        }
-        const plan = {
-            steps: steps.slice(0, maxSteps),
-            ...(typeof parsed.finalResult === 'string' ? { finalResult: parsed.finalResult } : {}),
-            ...(typeof parsed.reasoning === 'string' ? { reasoning: parsed.reasoning } : {}),
-        };
-        return {
-            plan,
-            raw,
-            durationMs,
-            tokensUsed: result.tokensUsed,
-            inputTokens: result.inputTokens,
-            outputTokens: result.outputTokens,
-            cacheReadInputTokens: result.cacheReadInputTokens,
-            cacheCreationInputTokens: result.cacheCreationInputTokens,
-        };
+        return planImpl(this, goal, state, options);
     }
     /**
      * Evaluate quality of the current page state.
@@ -1719,104 +251,10 @@ What is the complete plan?`;
      * design, and professional polish.
      */
     async evaluate(state, goal) {
-        const textContent = `GOAL that was being worked on: ${goal}
-
-CURRENT PAGE:
-URL: ${state.url}
-Title: ${state.title}
-
-Please evaluate the quality of this page/application.`;
-        const userContent = this.buildUserContent(textContent, state.screenshot, true);
-        const result = await this.generate(EVALUATE_PROMPT, [{ role: 'user', content: userContent }], undefined, 800);
-        const raw = result.text;
-        const tokensUsed = result.tokensUsed;
-        if (this.debug) {
-            console.log('[Brain] Evaluation:', raw.slice(0, 300));
-        }
-        try {
-            let text = raw.trim();
-            if (text.startsWith('```')) {
-                text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-            }
-            const parsed = JSON.parse(text);
-            const rawScore = typeof parsed.score === 'number' ? parsed.score : 5;
-            return {
-                score: Math.max(1, Math.min(10, rawScore)),
-                assessment: parsed.assessment ?? 'No assessment provided',
-                strengths: Array.isArray(parsed.strengths) ? parsed.strengths : [],
-                issues: Array.isArray(parsed.issues) ? parsed.issues : [],
-                suggestions: Array.isArray(parsed.suggestions) ? parsed.suggestions : [],
-                raw,
-                tokensUsed,
-            };
-        }
-        catch {
-            return {
-                score: 5,
-                assessment: 'Failed to parse evaluation response',
-                strengths: [],
-                issues: [],
-                suggestions: [],
-                raw,
-                tokensUsed,
-            };
-        }
+        return evaluateImpl(this, state, goal);
     }
     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}`,
-            '',
-            `PAGE: ${state.url} — ${state.title}`,
-            '',
-            'CANDIDATES:',
-            ...topCandidates.map((candidate, index) => `${index + 1}. ${candidate.ref} — ${candidate.text} (score ${candidate.score})`),
-        ];
-        if (extraContext) {
-            lines.push('', extraContext);
-        }
-        lines.push('', 'Choose the single best next visible link.');
-        const userContent = this.buildUserContent(lines.join('\n'), state.screenshot, this.scoutUseVision);
-        const provider = this.scoutProvider || this.navProvider || this.provider;
-        const model = this.scoutModelName || this.navModelName || this.modelName;
-        const result = await this.generate(LINK_SCOUT_PROMPT, [{ role: 'user', content: userContent }], { provider, model }, 300);
-        const raw = result.text;
-        const tokensUsed = result.tokensUsed;
-        try {
-            let text = raw.trim();
-            if (text.startsWith('```')) {
-                text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-            }
-            const parsed = JSON.parse(text);
-            const selector = typeof parsed.selector === 'string' ? parsed.selector.trim() : '';
-            const candidate = topCandidates.find((entry) => entry.ref === selector);
-            if (!candidate) {
-                throw new Error('invalid scout selector');
-            }
-            return {
-                selector,
-                reasoning: typeof parsed.reasoning === 'string' ? parsed.reasoning : 'No scout reasoning provided.',
-                confidence: typeof parsed.confidence === 'number'
-                    ? Math.max(0, Math.min(1, parsed.confidence))
-                    : 0.5,
-                raw,
-                tokensUsed,
-            };
-        }
-        catch {
-            const fallback = topCandidates[0];
-            if (!fallback) {
-                throw new Error('recommendLinkCandidate requires at least one candidate');
-            }
-            return {
-                selector: fallback.ref,
-                reasoning: 'Scout fallback: selected the top deterministic candidate after parse failure.',
-                confidence: 0.5,
-                raw,
-                tokensUsed,
-            };
-        }
+        return recommendLinkCandidateImpl(this, goal, state, candidates, extraContext);
     }
     /**
      * Verify whether the goal was actually achieved.
@@ -1824,59 +262,7 @@ Please evaluate the quality of this page/application.`;
      * Uses a fresh LLM call (no conversation history) to avoid self-confirmation bias.
      */
     async verifyGoalCompletion(state, goal, claimedResult) {
-        const siteBoundaryNote = buildFirstPartyBoundaryNote(goal, state.url);
-        const textContent = `GOAL: ${goal}
-
-AGENT'S CLAIMED RESULT: ${claimedResult}
-
-CURRENT PAGE:
-URL: ${state.url}
-Title: ${state.title}
-
-ELEMENTS:
-${budgetSnapshot(state.snapshot)}${siteBoundaryNote ? `\n\n${siteBoundaryNote}` : ''}
-
-Was the goal actually achieved? Analyze the current page state carefully.`;
-        const userContent = this.buildUserContent(textContent, state.screenshot, true);
-        // Verifier can use its own model, then the navigation model, then main.
-        const verifyProvider = this.verifierProvider
-            ? this.verifierProvider
-            : (this.adaptiveModelRouting && this.navModelName ? (this.navProvider || this.provider) : undefined);
-        const verifyModel = this.verifierModel
-            || (this.adaptiveModelRouting && this.navModelName ? this.navModelName : undefined);
-        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":[]}
-
-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));
-        }
-        try {
-            let text = raw.trim();
-            if (text.startsWith('```')) {
-                text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-            }
-            const parsed = JSON.parse(text);
-            return {
-                achieved: parsed.achieved === true,
-                confidence: typeof parsed.confidence === 'number'
-                    ? Math.max(0, Math.min(1, parsed.confidence))
-                    : 0.5,
-                evidence: Array.isArray(parsed.evidence) ? parsed.evidence : [],
-                missing: Array.isArray(parsed.missing) ? parsed.missing : [],
-            };
-        }
-        catch {
-            // Parse failure — assume not verified (conservative)
-            return {
-                achieved: false,
-                confidence: 0,
-                evidence: [],
-                missing: ['Failed to parse goal verification response'],
-            };
-        }
+        return verifyGoalCompletionImpl(this, state, goal, claimedResult);
     }
     /**
      * Audit design quality of the current page state.
@@ -1884,92 +270,7 @@ SUPPLEMENTAL TOOL EVIDENCE / SCRIPT RESULT in claimed results = verified DOM dat
      * Returns structured findings with categories and severity levels.
      */
     async auditDesign(state, goal, checkpoints, systemPrompt) {
-        const textContent = `GOAL: ${goal}
-
-CHECKPOINTS to verify:
-${checkpoints.map((c, i) => `${i + 1}. ${c}`).join('\n')}
-
-CURRENT PAGE:
-URL: ${state.url}
-Title: ${state.title}
-
-ELEMENTS:
-${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(systemPrompt ?? DESIGN_AUDIT_PROMPT, [{ role: 'user', content: userContent }], undefined, 8000);
-        const raw = result.text;
-        const tokensUsed = result.tokensUsed;
-        if (this.debug) {
-            console.log('[Brain] Design audit:', raw.slice(0, 300));
-        }
-        try {
-            let text = raw.trim();
-            if (text.startsWith('```')) {
-                text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-            }
-            // 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 VALID_BLAST = new Set(['page', 'section', 'component', 'system']);
-            const clampScore = (n) => typeof n === 'number' ? Math.max(1, Math.min(10, n)) : undefined;
-            const findings = Array.isArray(parsed.findings)
-                ? parsed.findings.map((f) => ({
-                    category: (VALID_CATEGORIES.has(f.category) ? f.category : 'ux'),
-                    severity: (VALID_SEVERITIES.has(f.severity) ? f.severity : 'minor'),
-                    description: String(f.description ?? ''),
-                    location: String(f.location ?? ''),
-                    suggestion: String(f.suggestion ?? ''),
-                    ...(f.cssSelector ? { cssSelector: String(f.cssSelector) } : {}),
-                    ...(f.cssFix ? { cssFix: String(f.cssFix) } : {}),
-                    // Optional ROI fields.
-                    ...(clampScore(f.impact) !== undefined ? { impact: clampScore(f.impact) } : {}),
-                    ...(clampScore(f.effort) !== undefined ? { effort: clampScore(f.effort) } : {}),
-                    ...(VALID_BLAST.has(f.blast)
-                        ? { blast: f.blast }
-                        : {}),
-                    // Layer 2 — preserve raw patches array (untyped passthrough). The
-                    // parsePatches/validatePatch pipeline in build-result.ts converts
-                    // these into typed, validated Patch objects.
-                    ...(Array.isArray(f.patches) ? { rawPatches: f.patches } : {}),
-                }))
-                : [];
-            const designSystemScore = parsed.designSystemScore && typeof parsed.designSystemScore === 'object'
-                ? parsed.designSystemScore
-                : undefined;
-            const rawScore = typeof parsed.score === 'number' ? parsed.score : 5;
-            return {
-                score: Math.max(1, Math.min(10, rawScore)),
-                findings,
-                raw,
-                tokensUsed,
-                designSystemScore,
-            };
-        }
-        catch (err) {
-            return {
-                score: 5,
-                findings: [],
-                raw,
-                tokensUsed,
-                parseError: err instanceof Error ? err.message : String(err),
-            };
-        }
+        return auditDesignImpl(this, state, goal, checkpoints, systemPrompt);
     }
     /**
      * Extract reusable knowledge from a completed trajectory.
@@ -1977,49 +278,7 @@ Audit this page for design quality, UX issues, and visual bugs.`;
      * and app quirks from a successful run.
      */
     async extractKnowledge(trajectoryText, domain) {
-        const result = await this.generate(`You are analyzing a browser automation trajectory to extract reusable knowledge.
-Extract facts that would help an agent complete similar tasks faster next time.
-
-Respond with ONLY a JSON array of facts:
-[
-  {"type": "timing", "key": "page-load", "value": "wait 3000ms after navigation for content to hydrate"},
-  {"type": "selector", "key": "send-button", "value": "[data-testid='chat-send-button'] is the reliable send button selector"},
-  {"type": "pattern", "key": "auth-flow", "value": "Click sign-in → fill email → fill password → click submit → wait for redirect"},
-  {"type": "quirk", "key": "lazy-loading", "value": "File tree loads asynchronously — wait for entries before asserting"}
-]
-
-Types:
-- timing: wait durations, delays that are necessary
-- selector: reliable selectors for important elements
-- pattern: multi-step interaction sequences
-- quirk: app-specific behaviors or gotchas
-
-Only include facts that are genuinely useful. Quality over quantity. Max 10 facts.`, [{
-                role: 'user',
-                content: `Domain: ${domain}\n\nTrajectory:\n${trajectoryText}`,
-            }], undefined, 800);
-        try {
-            let text = result.text.trim();
-            if (text.startsWith('```')) {
-                text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-            }
-            const parsed = JSON.parse(text);
-            if (!Array.isArray(parsed))
-                return [];
-            const VALID_TYPES = new Set(['timing', 'selector', 'pattern', 'quirk']);
-            return parsed
-                .filter((f) => VALID_TYPES.has(f.type) &&
-                typeof f.key === 'string' &&
-                typeof f.value === 'string')
-                .map((f) => ({
-                type: f.type,
-                key: f.key,
-                value: f.value,
-            }));
-        }
-        catch {
-            return [];
-        }
+        return extractKnowledgeImpl(this, trajectoryText, domain);
     }
     /**
      * Generic text-completion entry point for non-agent uses (GEPA reflective
@@ -2030,490 +289,25 @@ Only include facts that are genuinely useful. Quality over quantity. Max 10 fact
      * the configured provider/model.
      */
     async complete(system, user, options = {}) {
-        const result = await this.generate(system, [{ role: 'user', content: user }], undefined, options.maxOutputTokens ?? 1500);
-        return { text: result.text, tokensUsed: result.tokensUsed };
+        return completeImpl(this, system, user, options);
     }
-    parse(raw) {
-        let text = raw.trim();
-        // Strip markdown code blocks
-        if (text.startsWith('```')) {
-            text = text.replace(/^```(?:json)?\n?/, '').replace(/\n?```$/, '');
-        }
-        const VALID_ACTIONS = new Set([
-            'click', 'type', 'press', 'hover', 'select',
-            'scroll', 'navigate', 'wait', 'evaluate', 'runScript',
-            'extractWithIndex',
-            'verifyPreview', 'complete', 'abort',
-            'fill', 'clickSequence',
-            'clickAt', 'typeAt',
-            'clickLabel', 'typeLabel',
-            // Macro dispatch. The driver validates the macro name at execute time.
-            'macro',
-            // Parallel fan-out. Runner handles dispatch; validator checks shape.
-            'fanOut',
-        ]);
-        // Parse strategy: exact → first-{/last-} extraction.
-        // Some OpenAI-compat gateways (router.tangle.tools, LiteLLM proxies, etc.)
-        // wrap model output in prose preambles ("Here's your response:\n{...}")
-        // that markdown-fence stripping doesn't catch. Fall back to extracting the
-        // outermost object literal before giving up.
-        let parsed = null;
-        let parseError = '';
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch (err) {
-            parseError = err instanceof Error ? err.message : String(err);
-            const firstBrace = text.indexOf('{');
-            const lastBrace = text.lastIndexOf('}');
-            if (firstBrace >= 0 && lastBrace > firstBrace) {
-                try {
-                    parsed = JSON.parse(text.slice(firstBrace, lastBrace + 1));
-                    parseError = '';
-                }
-                catch { /* fall through to retry fallback */ }
-            }
-        }
-        if (!parsed) {
-            return {
-                // Do not hard-abort the scenario on transient JSON formatting issues.
-                // Waiting one turn lets the loop continue and recover on the next model call.
-                action: { action: 'wait', ms: 1000 },
-                reasoning: `Malformed LLM JSON response (${parseError}). Retrying next turn.`,
-            };
-        }
-        try {
-            const actionObj = parsed.action && typeof parsed.action === 'object' ? parsed.action : parsed;
-            const actionType = typeof parsed.action === 'string' ? parsed.action : actionObj?.action;
-            if (!actionType) {
-                throw new Error('Missing action field');
-            }
-            if (!VALID_ACTIONS.has(actionType)) {
-                throw new Error(`Unknown action "${actionType}". Valid: ${[...VALID_ACTIONS].join(', ')}`);
-            }
-            const actionData = parsed.action && typeof parsed.action === 'object'
-                ? parsed.action
-                : parsed;
-            const action = validateAction(actionType, actionData);
-            return {
-                action,
-                nextActions: parseNextActions(parsed, VALID_ACTIONS),
-                reasoning: (parsed.reasoning || parsed.thought || parsed.thinking),
-                plan: Array.isArray(parsed.plan) ? parsed.plan : undefined,
-                currentStep: typeof parsed.currentStep === 'number' ? parsed.currentStep : undefined,
-                expectedEffect: (parsed.expectedEffect || parsed.expected_effect),
-            };
-        }
-        catch (err) {
-            const validationError = err instanceof Error ? err.message : String(err);
-            return {
-                action: { action: 'wait', ms: 1000 },
-                reasoning: `Malformed LLM JSON response (${validationError}). Retrying next turn.`,
-            };
-        }
-    }
-}
-/**
- * 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, '#');
-    // Structural fingerprint for a block of lines (element + its children).
-    // Used for card-level dedup: two hotel cards have different names but the
-    // same structure (listitem > link + img + text + text + button).
-    const structuralFingerprint = (startIdx, baseIndent) => {
-        const roles = [];
-        let j = startIdx;
-        while (j < lines.length) {
-            const p = parseLine(lines[j]);
-            if (!p) {
-                j++;
-                continue;
-            }
-            // Stop when we hit an element at the same or shallower indent (sibling or parent)
-            if (j > startIdx && p.indent.length <= baseIndent.length)
-                break;
-            roles.push(p.role);
-            j++;
-        }
-        return { fp: roles.join(','), endIdx: j };
-    };
-    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;
-        }
-        // Try block-level dedup first: look for consecutive sibling blocks
-        // with the same structural fingerprint (same child-role sequence).
-        // This catches card patterns like Booking hotel results, Allrecipes cards.
-        if (/\b(?:listitem|article|group|region)\b/i.test(parsed.role)) {
-            const { fp: firstFp, endIdx: firstEnd } = structuralFingerprint(i, parsed.indent);
-            if (firstEnd > i + 2 && firstFp.includes(',')) { // non-trivial block
-                const blocks = [
-                    { start: i, end: firstEnd, firstLine: lines[i] },
-                ];
-                let scanIdx = firstEnd;
-                while (scanIdx < lines.length) {
-                    const nextParsed = parseLine(lines[scanIdx]);
-                    if (!nextParsed || nextParsed.indent !== parsed.indent || nextParsed.role !== parsed.role)
-                        break;
-                    const { fp: nextFp, endIdx: nextEnd } = structuralFingerprint(scanIdx, nextParsed.indent);
-                    if (nextFp !== firstFp)
-                        break;
-                    blocks.push({ start: scanIdx, end: nextEnd, firstLine: lines[scanIdx] });
-                    scanIdx = nextEnd;
-                }
-                if (blocks.length >= 3) {
-                    // Emit first 2 blocks fully, summarize the rest
-                    for (let b = 0; b < Math.min(2, blocks.length); b++) {
-                        for (let k = blocks[b].start; k < blocks[b].end; k++) {
-                            out.push(lines[k]);
-                        }
-                    }
-                    const remaining = blocks.length - 2;
-                    out.push(`${parsed.indent}... [${remaining} more similar ${parsed.role} blocks with same structure]`);
-                    i = blocks[blocks.length - 1].end;
-                    continue;
-                }
-            }
-        }
-        // Line-level dedup: consecutive runs of same (indent, role, name stem)
-        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 to control token cost on large pages.
- * Keeps the full snapshot when it fits within budget; otherwise preserves:
- *   1. Interactive elements with refs (buttons, inputs, links — for action targets)
- *   2. Content lines: term/definition/code/pre/paragraph (for extraction tasks
- *      like MDN, Python docs, W3C spec where the value the agent needs lives in
- *      a `<dl>/<code>/<pre>` block, not in an interactive element)
- *
- * New-page callers use a larger default budget; same-page callers can pass a
- * tighter budget after the model has already seen the full snapshot once.
- */
-export function budgetSnapshot(snapshot, maxChars = 24_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: separate keep-set (interactive + content lines) from decorative.
-    // Content roles (term, definition, code, pre, paragraph) carry text the LLM
-    // needs for extraction tasks. They have no [ref=] but the text is the data.
-    const lines = snapshot.split('\n');
-    const interactive = [];
-    const content = [];
-    const decorative = [];
-    for (const line of lines) {
-        if (/\b(?:button|link|textbox|combobox|menuitem|checkbox|radio|select|heading|dialog|alertdialog)\b/i.test(line) && /\[ref=/.test(line)) {
-            interactive.push(line);
-        }
-        else if (/^\s*-\s+(?:term|definition|code|pre|paragraph)\b/i.test(line)) {
-            content.push(line);
-        }
-        else {
-            decorative.push(line);
-        }
-    }
-    // If interactive + content fits, use both with a truncation note
-    const keepSet = interactive.concat(content);
-    const keepText = keepSet.join('\n');
-    if (keepText.length <= maxChars) {
-        return keepText + `\n... [${decorative.length} decorative elements omitted for brevity]`;
-    }
-    // Second pass: when interactive + content still exceed budget, prioritize:
-    // 1. inputs (searchbox/textbox/combobox) — essential for form tasks
-    // 2. headings + dialogs — structural navigation
-    // 3. content lines (term/definition/code/pre) — extraction data
-    // 4. bulk links/buttons — main content
-    const priority = [];
-    const bulk = [];
-    for (const line of interactive) {
-        if (/\b(?:searchbox|textbox|combobox|heading|dialog|alertdialog)\b/i.test(line)) {
-            priority.push(line);
-        }
-        else {
-            bulk.push(line);
-        }
-    }
-    // Content lines come right after priority interactive (they're the extraction
-    // data) and before bulk links/buttons.
-    const priorityWithContent = priority.concat(content);
-    const priorityText = priorityWithContent.join('\n');
-    const remaining = maxChars - priorityText.length - 80; // reserve space for note
-    if (remaining > 0) {
-        const bulkText = bulk.join('\n');
-        const trimmedBulk = bulkText.slice(0, remaining);
-        const bulkKept = trimmedBulk.lastIndexOf('\n') > 0
-            ? trimmedBulk.slice(0, trimmedBulk.lastIndexOf('\n'))
-            : trimmedBulk;
-        return priorityText + '\n' + bulkKept +
-            `\n... [${interactive.length - priority.length - bulkKept.split('\n').length} interactive + ${decorative.length} decorative elements omitted]`;
-    }
-    // Hard cap: take the first maxChars of the full snapshot
-    return snapshot.slice(0, maxChars) + '\n... [snapshot truncated — large page]';
-}
-function compactFirstTurnSnapshot(snapshot) {
-    const compact = AriaSnapshotHelper.formatCompact(snapshot);
-    const basis = compact.length > 0 ? compact : snapshot;
-    const maxChars = 4000;
-    if (basis.length <= maxChars)
-        return basis;
-    return `${basis.slice(0, maxChars)}\n... [snapshot truncated for first-turn fast path]`;
-}
-function parseNextActions(parsed, validActions) {
-    if (!Array.isArray(parsed.nextActions)) {
-        return undefined;
-    }
-    const nextActions = [];
-    for (const entry of parsed.nextActions.slice(0, 3)) {
-        if (!entry || typeof entry !== 'object')
-            continue;
-        const rawEntry = entry;
-        const actionType = typeof rawEntry.action === 'string' ? rawEntry.action : undefined;
-        if (!actionType || !validActions.has(actionType))
-            continue;
-        try {
-            nextActions.push(validateAction(actionType, rawEntry));
-        }
-        catch {
-            // Best effort: ignore malformed follow-up action.
-        }
-    }
-    return nextActions.length > 0 ? nextActions : undefined;
-}
-/**
- * Runtime validation of LLM-parsed action objects.
- * Ensures required fields are present and correctly typed per action variant.
- * Throws on missing/invalid fields so the caller can abort gracefully.
- */
-function validateAction(actionType, data) {
-    const requireStr = (field) => {
-        const v = data[field];
-        if (typeof v !== 'string' || !v)
-            throw new Error(`${actionType} action requires "${field}" (string)`);
-        return v;
-    };
-    const optStr = (field) => {
-        const v = data[field];
-        return typeof v === 'string' ? v : '';
-    };
-    const num = (v, fallback) => (typeof v === 'number' ? v : fallback);
-    switch (actionType) {
-        case 'click':
-            return { action: 'click', selector: requireStr('selector') };
-        case 'type':
-            return { action: 'type', selector: requireStr('selector'), text: optStr('text') };
-        case 'press':
-            return { action: 'press', selector: requireStr('selector'), key: requireStr('key') };
-        case 'hover':
-            return { action: 'hover', selector: requireStr('selector') };
-        case 'select':
-            return { action: 'select', selector: requireStr('selector'), value: optStr('value') };
-        case 'scroll':
-            return {
-                action: 'scroll',
-                direction: data.direction === 'up' ? 'up' : 'down',
-                ...(data.amount != null ? { amount: num(data.amount, 500) } : {}),
-            };
-        case 'navigate':
-            return { action: 'navigate', url: requireStr('url') };
-        case 'wait':
-            return { action: 'wait', ms: num(data.ms, 1000) };
-        case 'evaluate':
-            return { action: 'evaluate', criteria: optStr('criteria') };
-        case 'runScript':
-            return { action: 'runScript', script: requireStr('script') };
-        case 'extractWithIndex': {
-            const query = requireStr('query');
-            const contains = typeof data.contains === 'string' ? data.contains : '';
-            return {
-                action: 'extractWithIndex',
-                query,
-                ...(contains ? { contains } : {}),
-            };
-        }
-        case 'verifyPreview':
-            return { action: 'verifyPreview' };
-        case 'complete':
-            return { action: 'complete', result: optStr('result') };
-        case 'abort':
-            return { action: 'abort', reason: optStr('reason') || 'No reason provided' };
-        case 'fill': {
-            // Multi-field batch fill — at least one of fields/selects/checks must be non-empty
-            const fields = isStringRecord(data.fields) ? data.fields : undefined;
-            const selects = isStringRecord(data.selects) ? data.selects : undefined;
-            const checks = Array.isArray(data.checks) && data.checks.every((c) => typeof c === 'string')
-                ? data.checks
-                : undefined;
-            const fieldCount = (fields ? Object.keys(fields).length : 0)
-                + (selects ? Object.keys(selects).length : 0)
-                + (checks ? checks.length : 0);
-            if (fieldCount === 0) {
-                throw new Error('fill action requires at least one of "fields" (object), "selects" (object), or "checks" (string[])');
-            }
-            return {
-                action: 'fill',
-                ...(fields ? { fields } : {}),
-                ...(selects ? { selects } : {}),
-                ...(checks ? { checks } : {}),
-            };
-        }
-        case 'clickSequence': {
-            const refs = Array.isArray(data.refs) && data.refs.every((r) => typeof r === 'string')
-                ? data.refs
-                : null;
-            if (!refs || refs.length === 0) {
-                throw new Error('clickSequence action requires "refs" (string[]) with at least one entry');
-            }
-            return {
-                action: 'clickSequence',
-                refs,
-                ...(typeof data.intervalMs === 'number' ? { intervalMs: data.intervalMs } : {}),
-            };
-        }
-        // Vision-first coordinate actions.
-        case 'clickAt':
-            return { action: 'clickAt', x: num(data.x, 0), y: num(data.y, 0) };
-        case 'typeAt':
-            return { action: 'typeAt', x: num(data.x, 0), y: num(data.y, 0), text: optStr('text') };
-        // Set-of-Marks label-based actions.
-        case 'clickLabel':
-            return { action: 'clickLabel', label: num(data.label, 0) };
-        case 'typeLabel':
-            return { action: 'typeLabel', label: num(data.label, 0), text: optStr('text') };
-        // Macro invocation. The driver validates the name and required args at
-        // execute time; macros without params may omit args.
-        case 'macro': {
-            const args = {};
-            if (data.args && typeof data.args === 'object' && !Array.isArray(data.args)) {
-                for (const [k, v] of Object.entries(data.args)) {
-                    if (typeof v === 'string')
-                        args[k] = v;
-                }
-            }
-            return {
-                action: 'macro',
-                name: requireStr('name'),
-                ...(Object.keys(args).length > 0 ? { args } : {}),
-            };
-        }
-        case 'fanOut': {
-            // Accept either explicit subGoals[] or the shorthand
-            // baseUrl+goalTemplate+items trio. resolveSubGoals() in
-            // runner/fan-out.ts expands shorthand → subGoals at execute time.
-            const subGoals = Array.isArray(data.subGoals)
-                ? data.subGoals
-                    .filter((s) => s && typeof s === 'object')
-                    .map((s) => ({
-                    url: typeof s.url === 'string' ? s.url : '',
-                    goal: typeof s.goal === 'string' ? s.goal : '',
-                    ...(typeof s.label === 'string' ? { label: s.label } : {}),
-                    ...(typeof s.maxTurns === 'number' ? { maxTurns: s.maxTurns } : {}),
-                }))
-                    .filter((s) => s.url && s.goal)
-                : undefined;
-            const baseUrl = typeof data.baseUrl === 'string' ? data.baseUrl : undefined;
-            const goalTemplate = typeof data.goalTemplate === 'string' ? data.goalTemplate : undefined;
-            const items = Array.isArray(data.items) && data.items.every((i) => typeof i === 'string')
-                ? data.items
-                : undefined;
-            const hasExplicit = subGoals && subGoals.length > 0;
-            const hasShorthand = baseUrl && goalTemplate && items && items.length > 0;
-            if (!hasExplicit && !hasShorthand) {
-                throw new Error('fanOut action requires either "subGoals" (array of {url,goal}) or the shorthand trio "baseUrl" + "goalTemplate" + "items" (non-empty string[])');
-            }
-            return {
-                action: 'fanOut',
-                ...(hasExplicit ? { subGoals } : {}),
-                ...(hasShorthand ? { baseUrl, goalTemplate, items } : {}),
-                ...(typeof data.summarize === 'string' ? { summarize: data.summarize } : {}),
-            };
-        }
-        default:
-            throw new Error(`Unknown action type: ${actionType}`);
+    /**
+     * Multimodal sibling of {@link complete}: a single round-trip with a system
+     * prompt, a user prompt, and one-or-more already-encoded images. The narrow
+     * vision seam the reference-grounded taste judge binds to (one Brain per
+     * `{ provider, model }` ref), built on the same private `generate` so it goes
+     * through the existing provider abstraction — any vision-capable backend works.
+     *
+     * Images arrive ENCODED (`{ image, mediaType }`, base64/data); the disk read +
+     * mediaType inference live in the judge's `createBrainVisionModel` adapter, so
+     * this method does no IO. It is NOT `auditDesign` — the page-audit seam stays
+     * off-limits to taste comparison by contract.
+     */
+    async completeVision(system, user, images, options = {}) {
+        return completeVisionImpl(this, system, user, images, options);
     }
-}
-/** Type guard: value is a Record<string, string> */
-function isStringRecord(value) {
-    if (!value || typeof value !== 'object' || Array.isArray(value))
-        return false;
-    for (const v of Object.values(value)) {
-        if (typeof v !== 'string')
-            return false;
+    parse(raw) {
+        return parseDecision(raw);
     }
-    return true;
-}
-/**
- * Build a fetch replacement that forces `"stream": false` on chat completions
- * bodies for OpenAI-compatible gateways that default to SSE streaming.
- */
-function createForceNonStreamingFetch() {
-    return async (input, init) => {
-        if (init?.body && typeof init.body === 'string') {
-            const body = init.body;
-            // Cheap content-sniff so we only rewrite chat-completions shaped bodies,
-            // not arbitrary POSTs the caller might make (embeddings, etc.).
-            if (body.includes('"messages"') && body.includes('"model"')) {
-                try {
-                    const parsed = JSON.parse(body);
-                    if (parsed.stream === undefined || parsed.stream === true) {
-                        parsed.stream = false;
-                        init = { ...init, body: JSON.stringify(parsed) };
-                    }
-                }
-                catch {
-                    // Non-JSON body — pass through unchanged.
-                }
-            }
-        }
-        return fetch(input, init);
-    };
 }
 //# sourceMappingURL=index.js.map