@tangle-network/browser-agent-driver 0.16.1 → 0.18.0

package/dist/brain/index.d.ts

@@ -5,7 +5,7 @@
  * Uses Vercel AI SDK for multi-provider support (OpenAI, Anthropic, Google, Codex CLI, Claude Code).
  */
 import type { ModelMessage, LanguageModel } from 'ai';
-import type { Action, PageState, AgentConfig, DesignFinding, GoalVerification } from '../types.js';
+import type { Action, PageState, AgentConfig, DesignFinding, GoalVerification, Plan } from '../types.js';
 export interface BrainDecision {
     action: Action;
     nextActions?: Action[];
@@ -190,6 +190,37 @@ export declare class Brain {
     }, options?: {
         forceVision?: boolean;
     }): Promise<BrainDecision>;
+    /**
+     * Gen 7: ONE LLM call generates a structured plan for the entire task.
+     *
+     * The runner executes the plan deterministically (no LLM between steps),
+     * falling back to per-action `decide()` only when verification fails.
+     * This is the architectural shift that breaks the "1 LLM call per
+     * action" assumption — a 9-action task becomes 1 plan call + 9
+     * deterministic executes instead of 9 LLM calls.
+     *
+     * Returns null when:
+     *   - the LLM response is unparseable JSON (fall through to per-action)
+     *   - the plan has zero steps
+     *   - any plan step has an invalid/unknown action shape
+     *
+     * The caller (BrowserAgent.run) treats null as "planner unavailable,
+     * use per-action loop".
+     */
+    plan(goal: string, state: PageState, options?: {
+        maxSteps?: number;
+        extraContext?: string;
+    }): Promise<{
+        plan: Plan | null;
+        raw: string;
+        durationMs: number;
+        tokensUsed?: number;
+        inputTokens?: number;
+        outputTokens?: number;
+        cacheReadInputTokens?: number;
+        cacheCreationInputTokens?: number;
+        parseError?: string;
+    }>;
     /**
      * Evaluate quality of the current page state.
      * Takes a screenshot and asks the LLM to rate the visual quality,

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

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

package/dist/brain/index.js

@@ -27,6 +27,8 @@ ACTIONS:
 - {"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": "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"}
 
@@ -60,7 +62,11 @@ RULES:
 11. After the app builds and a preview is visible, use "verifyPreview" to check for errors before completing
 12. BLOCKER-FIRST POLICY: if a modal, limit, quota, permission, or error dialog blocks progress, resolve THAT first before continuing the main goal
 13. For quota/limit blockers, use an unblock ladder: open manage path -> clean up old test resources if needed -> retry the original action
-14. If the same action triggers the same blocker twice, switch strategy immediately (different button/path), do not repeat blind retries`;
+14. If the same action triggers the same blocker twice, switch strategy immediately (different button/path), do not repeat blind retries
+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
@@ -91,7 +97,10 @@ EXAMPLE 1 — Multi-step form fill (use actual refs from ELEMENTS, not these pla
 {"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"}`;
+{"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;
 /** Pattern for detecting data-extraction keywords in goal text */
@@ -1004,6 +1013,224 @@ ${visibleSnapshot}`;
             modelUsed: effectiveModel,
         };
     }
+    /**
+     * Gen 7: ONE LLM call generates a structured plan for the entire task.
+     *
+     * The runner executes the plan deterministically (no LLM between steps),
+     * falling back to per-action `decide()` only when verification fails.
+     * This is the architectural shift that breaks the "1 LLM call per
+     * action" assumption — a 9-action task becomes 1 plan call + 9
+     * deterministic executes instead of 9 LLM calls.
+     *
+     * Returns null when:
+     *   - the LLM response is unparseable JSON (fall through to per-action)
+     *   - the plan has zero steps
+     *   - any plan step has an invalid/unknown action shape
+     *
+     * The caller (BrowserAgent.run) treats null as "planner unavailable,
+     * use per-action loop".
+     */
+    async plan(goal, state, options) {
+        const startedAt = Date.now();
+        const maxSteps = options?.maxSteps ?? 12;
+        const extraContext = options?.extraContext;
+        // Snapshot budget for the planner: keep it conservative — the planner
+        // prompt is itself substantial, and we want the LLM to focus on the
+        // STRUCTURE of the page rather than every leaf element.
+        const snapshot = budgetSnapshot(state.snapshot, 12_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.
+
+ACTION VERBS (same as the per-action prompt):
+- {"action": "click", "selector": "@REF"}
+- {"action": "type", "selector": "@REF", "text": "..."}
+- {"action": "press", "selector": "@REF", "key": "Enter"}
+- {"action": "select", "selector": "@REF", "value": "..."}
+- {"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": "complete", "result": "..."}
+- {"action": "abort", "reason": "..."}
+
+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?`;
+        const result = await this.generate(planSystemPrompt, [{ role: 'user', content: userText }], { provider: this.provider, model: this.modelName }, 
+        // 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,
+        };
+    }
     /**
      * Evaluate quality of the current page state.
      * Takes a screenshot and asks the LLM to rate the visual quality,
@@ -1318,6 +1545,7 @@ Only include facts that are genuinely useful. Quality over quantity. Max 10 fact
             'click', 'type', 'press', 'hover', 'select',
             'scroll', 'navigate', 'wait', 'evaluate', 'runScript',
             'verifyPreview', 'complete', 'abort',
+            'fill', 'clickSequence',
         ]);
         try {
             const parsed = JSON.parse(text);
@@ -1544,8 +1772,51 @@ function validateAction(actionType, data) {
             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 } : {}),
+            };
+        }
         default:
             throw new Error(`Unknown action type: ${actionType}`);
     }
 }
+/** 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;
+    }
+    return true;
+}
 //# sourceMappingURL=index.js.map