@kkeve/suite 0.0.12 → 0.0.15

package/dist/page-agent/agent.js

@@ -61,6 +61,91 @@ const tools_1 = require("./tools");
 const config_1 = require("../config");
 // ─── System Prompt ────────────────────────────────────────────────────
 const SYSTEM_PROMPT = fs.readFileSync(path.join(__dirname, "system_prompt.md"), "utf-8");
+// ─── Snapshot diff helpers (used by assembleUserPrompt to add Page Change to history) ───
+/** Find the snapshot string of the previous step event before index `i`. */
+function findPrevStepSnapshot(events, currentIdx) {
+    for (let j = currentIdx - 1; j >= 0; j--) {
+        if (events[j].type === 'step' && events[j].snapshot)
+            return events[j].snapshot;
+    }
+    return undefined;
+}
+/**
+ * Summarize key differences between two a11y snapshots.
+ * Returns a short human-readable string or '' if nothing notable changed.
+ *
+ * Detects: dialog/modal appearance/disappearance, new/removed elements,
+ * value changes in inputs, and repeated identical snapshots (no change).
+ */
+function summarizeSnapshotDiff(prev, curr) {
+    if (prev === curr)
+        return 'no visible change on page';
+    const prevLines = prev.split('\n');
+    const currLines = curr.split('\n');
+    const changes = [];
+    // 1. Detect dialog/modal appearance or disappearance
+    const prevDialogs = prevLines.filter(l => /dialog|modal|alertdialog/i.test(l) && /\[ref=/.test(l));
+    const currDialogs = currLines.filter(l => /dialog|modal|alertdialog/i.test(l) && /\[ref=/.test(l));
+    if (currDialogs.length > prevDialogs.length) {
+        const newDialog = currDialogs.find(cd => !prevDialogs.some(pd => pd === cd));
+        if (newDialog) {
+            const nameMatch = newDialog.match(/"([^"]+)"/);
+            changes.push(`dialog "${nameMatch?.[1] || '?'}" appeared`);
+        }
+    }
+    else if (currDialogs.length < prevDialogs.length) {
+        changes.push('dialog closed');
+    }
+    // 2. Detect new warning/error text nodes (e.g. validation errors)
+    const prevWarnings = prevLines.filter(l => /warning|error|alert|⚠|❌/i.test(l) && /\[ref=/.test(l));
+    const currWarnings = currLines.filter(l => /warning|error|alert|⚠|❌/i.test(l) && /\[ref=/.test(l));
+    for (const w of currWarnings) {
+        if (!prevWarnings.some(pw => pw === w)) {
+            const textMatch = w.match(/"([^"]+)"/);
+            changes.push(`new warning/error: "${textMatch?.[1] || '?'}"`);
+        }
+    }
+    // 3. Count added/removed interactive elements (simplified: lines with [ref=])
+    const prevRefs = new Set(prevLines.filter(l => /\[ref=/.test(l)).map(l => {
+        const m = l.match(/\[ref=([a-f0-9]+)\]/);
+        return m?.[1] || '';
+    }));
+    const currRefs = new Set(currLines.filter(l => /\[ref=/.test(l)).map(l => {
+        const m = l.match(/\[ref=([a-f0-9]+)\]/);
+        return m?.[1] || '';
+    }));
+    const added = [...currRefs].filter(r => r && !prevRefs.has(r));
+    const removed = [...prevRefs].filter(r => r && !currRefs.has(r));
+    if (added.length > 0)
+        changes.push(`${added.length} new element(s) appeared`);
+    if (removed.length > 0)
+        changes.push(`${removed.length} element(s) removed`);
+    // 4. Detect value changes in textboxes (content after colon on same line)
+    const prevValues = new Map();
+    for (const l of prevLines) {
+        const refM = l.match(/\[ref=([a-f0-9]+)\]/);
+        if (refM) {
+            // Value is text after the last colon on the same line
+            const valM = l.match(/: (.+)$/);
+            if (valM)
+                prevValues.set(refM[1], valM[1].trim());
+        }
+    }
+    for (const l of currLines) {
+        const refM = l.match(/\[ref=([a-f0-9]+)\]/);
+        if (refM) {
+            const valM = l.match(/: (.+)$/);
+            if (valM && prevValues.has(refM[1])) {
+                const prevVal = prevValues.get(refM[1]);
+                const currVal = valM[1].trim();
+                if (prevVal !== currVal && currVal) {
+                    changes.push(`[ref=${refM[1]}] value changed: "${prevVal}" → "${currVal}"`);
+                }
+            }
+        }
+    }
+    return changes.length > 0 ? changes.join('; ') : 'page content changed';
+}
 // ─── KevePageAgent ──────────────────────────────────────────────────────
 class KevePageAgent {
     page;
@@ -72,6 +157,13 @@ class KevePageAgent {
     /** Current execute options (set at start of execute(), accessible from hooks) */
     options;
     hooks;
+    // Page event listener state (used by handle_dialog, console_messages, file_upload, network_requests)
+    _dialogHandler = null;
+    _lastDialogInfo = null;
+    _pendingFileChooser = null;
+    _consoleMessages = [];
+    _networkRequests = [];
+    _pageListenersSetup = false;
     constructor(page, options) {
         this.page = page;
         this.maxSteps = options?.maxSteps ?? 8;
@@ -90,12 +182,95 @@ class KevePageAgent {
     stop() {
         this.abortController.abort();
     }
+    /** Set up page event listeners for dialog, console, network, and file chooser capture.
+     *  Called once per page; subsequent calls are no-ops. */
+    setupPageListeners() {
+        if (this._pageListenersSetup)
+            return;
+        this._pageListenersSetup = true;
+        // ── Dialog handler ──
+        // Playwright auto-dismisses dialogs unless a handler is registered.
+        // Our handler auto-accepts by default, but _dialogHandler can override.
+        this.page.on('dialog', async (dialog) => {
+            const handler = this._dialogHandler;
+            const accept = handler?.accept ?? true;
+            const promptText = handler?.promptText;
+            try {
+                if (accept) {
+                    await dialog.accept(promptText || '');
+                }
+                else {
+                    await dialog.dismiss();
+                }
+            }
+            catch {
+                // Fallback: always accept to unblock the page
+                try {
+                    await dialog.accept();
+                }
+                catch { /* give up */ }
+            }
+            this._lastDialogInfo = {
+                type: dialog.type(),
+                message: dialog.message(),
+                accepted: accept,
+            };
+            this._dialogHandler = null;
+            // Notify the Agent so it knows a dialog appeared
+            this.pushObservation(`🔔 Native dialog [${dialog.type()}] appeared: "${dialog.message().slice(0, 100)}" — was ${accept ? 'accepted' : 'dismissed'}.`);
+        });
+        // ── Console messages ──
+        this.page.on('console', (msg) => {
+            this._consoleMessages.push({ level: msg.type(), text: msg.text() });
+            if (this._consoleMessages.length > 200)
+                this._consoleMessages.shift();
+        });
+        this.page.on('pageerror', (err) => {
+            this._consoleMessages.push({ level: 'error', text: `Uncaught: ${err.message}` });
+        });
+        // ── Network requests ──
+        this.page.on('request', (req) => {
+            const url = req.url();
+            const isStatic = /\.(js|css|png|jpg|jpeg|gif|svg|ico|woff|woff2|ttf|eot|map)(\?|$)/i.test(url);
+            this._networkRequests.push({
+                _req: req,
+                method: req.method(),
+                url,
+                isStatic,
+                status: null,
+            });
+            if (this._networkRequests.length > 100)
+                this._networkRequests.shift();
+        });
+        this.page.on('response', (res) => {
+            const req = res.request();
+            // Match by reference identity — Playwright guarantees same Request object
+            for (let i = this._networkRequests.length - 1; i >= 0; i--) {
+                if (this._networkRequests[i]._req === req) {
+                    this._networkRequests[i].status = res.status();
+                    break;
+                }
+            }
+        });
+        // ── File chooser ──
+        this.page.on('filechooser', (fileChooser) => {
+            this._pendingFileChooser = fileChooser;
+        });
+    }
     /** Main Re-Act execute loop */
     async execute(step, expected, options) {
         // Reset state
         this.events = [];
         this.abortController = new AbortController();
         this.options = options;
+        // Reset page event listener state
+        this._dialogHandler = null;
+        this._lastDialogInfo = null;
+        this._pendingFileChooser = null;
+        this._consoleMessages = [];
+        this._networkRequests = [];
+        // Set up page event listeners (idempotent — only runs once per page)
+        this.setupPageListeners();
         const hooks = options?.hooks ?? this.hooks;
         // Link external signal (e.g. per-goal timeout) to internal abort controller
         const externalSignal = options?.signal;
@@ -115,7 +290,7 @@ class KevePageAgent {
             this.pushObservation(`Target application URL: ${targetUrl}. Use this URL for navigation. Do NOT construct URLs yourself — use the navigate tool with this URL or read process.env.KEVE_TARGET_URL.`);
         }
         if (options?.learnedActionsHint) {
-            this.pushObservation(`Previous discoveries for similar steps:\n${options.learnedActionsHint}`);
+            this.pushObservation(`Previous discoveries for similar steps:\n${options.learnedActionsHint}\nUse these discoveries to avoid repeating failed approaches. If a previous step found a working way to fill a form field (especially combobox/dropdown), reuse that approach instead of trial-and-error.`);
         }
         // Step limit warning
         if (maxSteps <= 3) {
@@ -209,10 +384,12 @@ class KevePageAgent {
                     if (actionName === 'execute_javascript' && execResult.output && execResult.output.startsWith('❌')) {
                         const jsRulesHint = [
                             'execute_javascript rules — fix your script:',
-                            '1. MUST start with `return` to capture the result.',
-                            '2. Use `var` for declarations — `const`/`let` cause SyntaxError.',
+                            '1. Include `return` for multi-statement code. Single expressions are auto-wrapped.',
+                            '2. const/let are auto-converted to var — no need to write var manually.',
                             '3. NO top-level `await` or `async () => {}` wrappers — they return undefined.',
                             '4. NO Playwright APIs (`page`, `locator`) — only browser DOM APIs.',
+                            '5. FORM INTERACTION allowed: input.value=, dispatchEvent().',
+                            '6. FORBIDDEN: style mutation (style.xxx=, style.setProperty), classList mutation, className=, innerHTML=.',
                         ].join('\n');
                         this.pushObservation(jsRulesHint);
                     }
@@ -296,6 +473,53 @@ class KevePageAgent {
                     await hooks?.onAfterStep?.(this, this.events);
                 }
                 stepCount++;
+                // ── Stuck detection: break retry loops early ──
+                // When the last 3 steps produce identical toolOutput (no page progress),
+                // inject a forceful observation to break the loop.
+                // Also detects oscillation patterns (e.g. A→B→A→B cycling between two states).
+                const recentSteps = this.events
+                    .filter((e) => e.type === 'step')
+                    .slice(-4);
+                if (recentSteps.length >= 3) {
+                    const last3 = recentSteps.slice(-3);
+                    const normalize = (s) => (s || '').replace(/executed for \d+ms/, '').slice(0, 80);
+                    const outputs = last3.map(s => normalize(s.toolOutput));
+                    const allSame = outputs.every(o => o === outputs[0]);
+                    if (allSame) {
+                        const stuckMsg = [
+                            `⚠️ STUCK DETECTED: The last 3 actions all produced the same result: "${outputs[0].slice(0, 60)}"`,
+                            `This means the page is NOT responding to your actions. You MUST change strategy:`,
+                            `- Try a different tool (e.g. select_option instead of fill_form, execute_javascript instead of click)`,
+                            `- Try a different element or value`,
+                            `- If a dialog blocks submission, handle the sub-dialog/popup first or dismiss it with Escape`,
+                            `- If stuck after 2 more attempts: call done(verdict="fail") honestly`,
+                        ].join('\n');
+                        this.pushObservation(stuckMsg);
+                    }
+                    // ── Oscillation detection: check if last 6 steps cycle between 2-3 states ──
+                    // E.g. click确定→ownership popup → click返回→conflict warning → click确定→ownership popup
+                    const recent6 = this.events
+                        .filter((e) => e.type === 'step')
+                        .slice(-6);
+                    if (recent6.length >= 5 && !allSame) {
+                        const norm6 = recent6.map(s => normalize(s.toolOutput));
+                        // Extract the set of unique outputs (ignoring minor variations)
+                        const uniqueOutputs = [...new Set(norm6)];
+                        if (uniqueOutputs.length <= 2) {
+                            // All recent steps cycle between ≤2 distinct outputs → oscillation
+                            const oscMsg = [
+                                `⚠️ OSCILLATION DETECTED: The last ${recent6.length} actions cycle between ${uniqueOutputs.length} states without progress:`,
+                                ...uniqueOutputs.map(o => `  - "${o.slice(0, 50)}"`),
+                                `You are going back and forth without advancing. You MUST break the cycle:`,
+                                `- If clicking 确定 triggers a repeated warning, change the FORM VALUES (not just the name) to resolve the warning`,
+                                `- If "口径重复" blocks submission, change the DATASET or INDICATOR (not just the indicator name)`,
+                                `- If a sub-dialog keeps appearing, dismiss it with Escape or handle it first`,
+                                `- Call done(verdict="fail") honestly if the conflict cannot be resolved within current steps`,
+                            ].join('\n');
+                            this.pushObservation(oscMsg);
+                        }
+                    }
+                }
                 if (stepCount >= maxSteps) {
                     console.error(`\x1b[31mStep count exceeded maximum limit (${maxSteps})\x1b[0m`);
                     const finalSnapshot = await this.page.ariaSnapshot();
@@ -357,13 +581,21 @@ class KevePageAgent {
         prompt += '</agent_state>\n\n';
         // <agent_history>
         prompt += '<agent_history>\n';
-        for (const event of this.events) {
+        for (let i = 0; i < this.events.length; i++) {
+            const event = this.events[i];
             if (event.type === 'step') {
                 prompt += `<step_${event.stepIndex + 1}>\n`;
                 prompt += `Evaluation of Previous Step: ${event.evaluation}\n`;
                 prompt += `Memory: ${event.memory}\n`;
                 prompt += `Next Goal: ${event.nextGoal}\n`;
                 prompt += `Action: ${event.toolName} → ${event.toolOutput || event.toolError || 'unknown'}\n`;
+                // Add snapshot diff summary: compare this step's snapshot with the previous step's
+                const prevStep = i > 0 ? findPrevStepSnapshot(this.events, i) : undefined;
+                if (prevStep !== undefined) {
+                    const diff = summarizeSnapshotDiff(prevStep, event.snapshot);
+                    if (diff)
+                        prompt += `Page Change: ${diff}\n`;
+                }
                 prompt += `</step_${event.stepIndex + 1}>\n`;
             }
             else if (event.type === 'observation') {
@@ -496,6 +728,52 @@ IMPORTANT: Respond in Chinese.`,
             return { found: false, analysis: `LLM invoke error: ${e.message}` };
         }
     }
+    /** Visual assertion: check a visual condition without interacting with the page */
+    async visualAssertElement(screenshotBase64, assertion) {
+        const assertToolSchema = zod_1.z.object({
+            passed: zod_1.z.boolean().describe('Whether the assertion is true based on the screenshot'),
+            reasoning: zod_1.z.string().describe('Brief explanation of why the assertion passed or failed'),
+        });
+        const messages = [
+            {
+                role: 'system',
+                content: `You are a UI visual assertion checker. Given a screenshot and an assertion statement, determine whether the assertion is TRUE based on what you see.
+
+Output JSON with:
+- passed: true if the assertion holds, false otherwise
+- reasoning: brief explanation of your judgment
+
+IMPORTANT:
+- Only judge what you can SEE in the screenshot — do not infer hidden states
+- Be strict: if the visual evidence is ambiguous, return passed=false
+- Respond in Chinese for reasoning`,
+            },
+            {
+                role: 'user',
+                content: [
+                    { type: 'text', text: `请判断以下断言是否为真：${assertion}\n\n返回 passed (布尔值) 和 reasoning (中文说明)。` },
+                    { type: 'image_url', image_url: { url: `data:image/png;base64,${screenshotBase64}`, detail: 'high' } },
+                ],
+            },
+        ];
+        try {
+            const result = await this.llm.invoke(messages, {
+                AssertResult: {
+                    description: 'Return the visual assertion result',
+                    inputSchema: assertToolSchema,
+                    execute: async (args) => args,
+                },
+            }, this.abortController.signal, { toolChoiceName: 'AssertResult' });
+            const parsed = result.toolCall.args;
+            return {
+                passed: typeof parsed.passed === 'boolean' ? parsed.passed : false,
+                reasoning: parsed.reasoning || 'No reasoning provided',
+            };
+        }
+        catch (e) {
+            return { passed: false, reasoning: `LLM invoke error: ${e.message}` };
+        }
+    }
     /** Build final result */
     buildResult(success, data, stepCount, finalSnapshot) {
         const snapshot = finalSnapshot || '';

package/dist/page-agent/system_prompt.md

@@ -11,6 +11,15 @@ You excel at following tasks:
 6. Using page screenshots as the primary visual source of truth
 </intro>
 
+<capability>
+- It is ok to fail the task. If the expected state cannot be achieved due to page bugs, test data issues, or validation blocks, call done(verdict="fail") honestly rather than looping indefinitely.
+- Trying too hard can be harmful. Repeating the same action back and forth (especially clicking 确定/提交 on a form that won't submit) wastes steps and causes unwanted side-effects. When stuck, call done with an honest verdict.
+- The page can be broken. If the page has bugs making the expected state unreachable (e.g. validation warning "口径与已有指标重复" that cannot be resolved within current context), report it as fail or blocked — do NOT keep retrying.
+- If a click tool returns ✅ with "auto-dismissed" message, the sub-dialog was automatically dismissed and the original click was retried. Check the result: if it says "dialog closed", the form was submitted successfully; if it says "dialog still open", the retried click triggered another issue (e.g. validation error or another popup) — read the message and handle it.
+- **Sub-dialog / popup handling**: When clicking a dialog button triggers a NEW popup (⚠️ shows "new popup: ..."), this means a sub-dialog appeared on top. You MUST handle the sub-dialog FIRST before retrying the original action. Read the accessibility tree to see the sub-dialog's fields and buttons, fill/interact with them, then close/confirm the sub-dialog. After the sub-dialog closes, the original dialog should now accept your action.
+- **Unrelated intercepting popups**: If a popup unrelated to the form validation appears (e.g. ownership transfer, assignment, notification), dismiss it by pressing Escape or clicking its cancel/close button, then proceed with the original action.
+</capability>
+
 <language_settings>
 - Default working language: **中文**
 - Use the same language as the user request.
@@ -84,6 +93,13 @@ Important notes:
 - If an expected element is not visible, try scrolling or navigating
 - The `ref` values are stable within a page state but change after navigation — always use the latest snapshot
 - The screenshot shows the actual visual state — use it to verify visual expectations (colors, layout, visibility, text rendering) that the accessibility tree may not capture
+
+**Combobox/dropdown interaction strategy:**
+- For combobox/dropdown fields, ALWAYS use `select_option` tool (or `fill_form` with type="combobox") — these tools handle custom components (ks-select, ant-select, el-select) automatically.
+- If a combobox selection returns "value did not update", do NOT retry the same approach — the tool already applied a type+Enter fallback. Move on to the next step.
+- If a dropdown option causes a duplicate/conflict warning, immediately select a DIFFERENT option — do NOT re-select the same one.
+- When filling a form with multiple combobox fields, fill one at a time (each combobox opens/closes a dropdown), not all at once.
+- **CRITICAL**: Never repeat the same combobox action more than 2 times. If it fails twice, use `execute_javascript` to set the value programmatically, or call `done(verdict="fail")` honestly.
 - `[cursor=pointer]` indicates the element is clickable
 - iframe content is fully visible in the tree — no special treatment needed
 </browser_state>
@@ -115,8 +131,42 @@ Strictly follow these rules while using the browser:
 - If the page is not fully loaded, use the `wait` action.
 - Do not repeat the same action more than 3 times unless conditions changed.
 - If a click doesn't produce the expected result, try an alternative element or approach.
-- When typing into a field, use the `type` action which clears existing content first.
+- When typing into a field, use the `type` action. By default it clears existing content first (mode="replace"). Use mode="append" to add text without clearing.
 - Before calling done(verdict="pass"), cross-reference the screenshot with the accessibility tree and the expected state. Only call done(verdict="pass") when you are confident the expected state is fully achieved.
+
+<form_rules>
+**Form filling best practices:**
+1. Use `fill_form` for multi-field forms — it fills textbox/checkbox/radio/slider AND combobox/dropdown fields in one step. For combobox, it automatically handles both native `<select>` and custom components (ks-select/ant-select) via click-open→click-option, with type+Enter fallback when click-option fails. This reduces step count and prevents missing required fields.
+2. For a single standalone dropdown selection (not part of a multi-field form), use `select_option` instead — it does the same combobox handling in one step.
+3. **Do NOT use `type` tool directly on a combobox/dropdown field** — the `type` tool auto-detects combobox and delegates to `select_option`, but if you use it explicitly, it signals you're trying to type free text into a dropdown, which is usually wrong. Use `fill_form` or `select_option` instead.
+4. Typical workflow: one `fill_form` call with ALL fields (including combobox), then click 确定/提交. Be prepared for post-submit issues (duplicate warnings, intercepting popups) — handle them before retrying.
+5. Before clicking 确定/提交/Save, check ALL required fields are filled — not just the field mentioned in the current step. Missing required fields is the #1 reason forms fail to submit.
+6. Never click 确定/提交 more than 2 times without verifying state change. If the dialog stays open, check for validation errors or intercepting sub-dialogs (see validation detection below).
+7. **"留空" means DON'T fill that field** — do NOT use fill_form with an empty string ("") for a field that should be left empty. Simply omit that field from the fill_form fields array. Only include fields that need actual values.
+
+**Validation state detection:**
+- The a11y tree often does NOT show validation state (aria-invalid is usually absent for custom components).
+- When the expected says "字段标红", "提示必填", "显示错误提示", use `visual_assert` to check the visual condition — it screenshots and analyzes the page without interacting.
+- Alternatively, `execute_javascript` can query CSS properties (e.g. `getComputedStyle(el).borderColor`) for precise values.
+- Do NOT use `visual_locate` for validation checks — it CLICKS and will alter page state.
+- If clicking 确定/提交 keeps the dialog open with no visible change, that itself indicates validation failure.
+
+**Reusing discoveries from previous steps (learned hints):**
+- If a <sys> message contains "Previous discoveries for SIMILAR step", it describes actions that worked for a similar form on the same page.
+- Pay special attention to "Key discoveries" — these show which combobox options were successfully selected (e.g. `✅ combobox = "KwaiBI官方数据集DEMO" (custom)`) and which dialog warnings appeared (e.g. `⚠️ ...new popup: "口径与已有指标重复"`).
+- If the hint shows a working option for a combobox you need to fill, reuse that exact option value instead of guessing.
+- If the hint shows a dialog warning that blocked submission, you already know about it — adjust your strategy accordingly.
+
+**Character length for input validation:**
+- When a test case specifies a character limit (e.g. "50个字符", "最大300字"), each Chinese character counts as 1 character — same as `.length` in JavaScript.
+- Do NOT convert character limits to byte counts (e.g. "50字符限制→输入25个中文" is WRONG).
+- To test a "50字符" limit, type exactly 50 Chinese characters for the boundary test. For the over-limit test, type 51 Chinese characters.
+- Example: if expected says "输入不超过50字符", type 50个中文汉字 to verify the upper bound is accepted, and 51个中文汉字 to verify rejection.
+
+**Important:**
+- The `[ref=xxx]` identifier is for click/type/hover tools only (aria-ref selector). It does NOT exist as a DOM attribute — never use `document.querySelector('[ref=xxx]')`.
+- When using `type` with mode="append", text is added after existing content without clearing. Default mode="replace" clears first.
+</form_rules>
 </browser_rules>
 
 <task_completion_rules>
@@ -149,7 +199,7 @@ When the `navigate` tool returns an error indicating a missing/empty environment
 - Do NOT call done with verdict="pass" if the screenshot shows the expected state is NOT achieved.
 - **When to stop immediately**: If `execute_javascript` or another deterministic tool returns a result that definitively proves the expected state CANNOT be achieved (e.g. computed style value mismatch), call `done` with the appropriate verdict right away. Do NOT continue exploring, scrolling, or navigating — more actions will not change a CSS computed value or a DOM property. Wasting steps on already-failed assertions reduces test reliability.
 - **When prior_execution shows the conclusion**: If the `<prior_execution>` block shows an assertion failure with `Expected:` and `Received:` values, the deterministic script has already captured the precise value. You may use `execute_javascript` once to confirm the current value, then immediately call `done(verdict="fail")` with the actual vs expected values in `text`. Do NOT explore further — the assertion already proved the mismatch.
-- **execute_javascript is ONLY for reading precise values**: Use it to query computed styles, DOM properties, or measurements that screenshots/accessibility tree cannot provide. Do NOT use it for clicking, typing, navigating, form filling, or any page interaction — use the dedicated tools (click, type, navigate) instead. Do NOT use it to repeat what the accessibility tree already shows. Do NOT use it for logic/assertions — just return the raw value and judge the result yourself.
+- **execute_javascript is primarily for reading precise values**: Use it to query computed styles, DOM properties, or measurements that screenshots/accessibility tree cannot provide. Do NOT use it for typing, navigating, or form filling — use the dedicated tools (type, navigate, fill_form) instead. Do NOT use it to repeat what the accessibility tree already shows. Do NOT use it for logic/assertions — just return the raw value and judge the result yourself. **EXCEPTION — overlay bypass**: When the click tool is blocked by overlay interception (returns ⚠️ with "dialog still open" repeatedly for the same element), you MAY use `execute_javascript` with `element.click()` to bypass the overlay. In this case, locate the element via its accessible name/role/text (e.g., `document.querySelector('button[aria-label="确定"]')` or `Array.from(document.querySelectorAll('button')).find(b => b.textContent.includes('确定'))`), NOT via `[ref=xxx]` which is NOT a DOM attribute.
 - **NEVER modify the page under test (CRITICAL RULE)**: You are a TESTER — your job is to OBSERVE and REPORT the actual state of the page, never to ALTER it to match expectations. If the actual value differs from the expected value, that is a TEST FAILURE — report it honestly as `done(verdict="fail")`. Do NOT use `execute_javascript`, `click`, `type`, or any other tool to "fix" the page so the test passes. Specifically:
   - Do NOT inject CSS (style.setProperty, style overrides, CSS variable changes)
   - Do NOT modify DOM structure (adding/removing elements)
@@ -157,12 +207,15 @@ When the `navigate` tool returns an error indicating a missing/empty environment
   - Do NOT override computed styles to match expected values
   - If `execute_javascript` returns a value that differs from expected, call `done(verdict="fail")` with the actual vs expected — do NOT attempt to change the value
 - **execute_javascript <rule>**:
-  1. Script MUST start with `return` — no auto-wrapping. Omitting `return` causes execution rejection.
-  2. Use `var` for variable declarations. `const`/`let` cause SyntaxError in page.evaluate context.
-  3. NO top-level `await` — the script runs in a synchronous IIFE. There is no async context.
-  4. NO `async () => {}` wrappers — they return undefined. Write flat statements ending with `return`.
-  5. NO Playwright APIs (`page`, `locator`, `expect`) — only browser DOM APIs exist inside the page.
-  6. Read-only: do NOT modify DOM, styles, cookies, or localStorage. Only query/return values. This includes style.setProperty() — it is BLOCKED. If the actual value differs from expected, report it as fail, do NOT override it.
+  1. Include `return` for multi-statement code. Single expressions are auto-wrapped with return. const/let are auto-converted to var.
+  2. NO top-level `await` — the script runs in a synchronous IIFE. There is no async context.
+  3. NO `async () => {}` wrappers — they return undefined. Write flat statements ending with `return`.
+  4. NO Playwright APIs (`page`, `locator`, `expect`) — only browser DOM APIs exist inside the page.
+  5. FORM INTERACTION allowed: setting input.value, textarea.value, select.value, dispatchEvent().
+  6. FORBIDDEN — do NOT modify visual appearance or page structure to fake test results:
+     - No style.setProperty(), style.xxx =, style.removeProperty()
+     - No className =, classList.add/remove/toggle()
+     - No innerHTML/outerHTML = (page structure changes)
   If your script returns `❌`, the rules will be re-injected in the next step — fix the script immediately instead of trying other approaches.
 
 Example — correct use of execute_javascript + immediate done:
@@ -180,11 +233,12 @@ Expected: "body background-color is rgb(255, 255, 238)"
 Example — WRONG execute_javascript usage that will FAIL:
 ```
 ❌ "page.locator('.x').innerText()"          → no `page` object in browser context
-❌ "const el = document.querySelector('.x')"  → `const` causes SyntaxError, use `var`
-❌ "async () => { await page.locator(...) }" → no `async`/`await`/`page`, returns undefined
+❌ "document.querySelector('.x').style.borderColor = 'red'"  → FORBIDDEN: style mutation
+❌ "document.querySelector('.x').classList.add('field-error')"  → FORBIDDEN: classList mutation
 
 ✅ "return document.querySelector('.x').innerText"
 ✅ "var el = document.querySelector('.x'); return window.getComputedStyle(el).backgroundColor"
+✅ "return document.querySelectorAll('.field-error').length"
 ```
 </task_completion_rules>
 
@@ -206,8 +260,8 @@ Exhibit the following reasoning patterns:
 
 - Reason about <agent_history> to track progress toward the expected state.
 - Analyze the most recent "Next Goal" and "Action Result" in <agent_history>.
-- Explicitly judge success/failure/uncertainty of the last action. Never assume an action succeeded just because it was executed. If the expected change is missing, mark as failed and plan a recovery.
-- Analyze whether you are stuck (repeating the same actions without progress). Then consider alternative approaches like scrolling or using a different element.
+- Explicitly judge success/failure/uncertainty of the last action. Never assume an action succeeded just because the tool returned ✅. If the tool returned ⚠️, or the Page Change shows "no visible change", or the expected change is missing — mark as FAILED and change strategy immediately.
+- Analyze whether you are stuck (repeating the same actions without progress). If you have clicked the same element 2+ times with no state change, STOP and either try a different approach or call done with an honest verdict.
 - Always compare the current browser state (screenshot + accessibility tree) with the expected state in <user_request>.
 - When evaluating whether to call done(verdict="pass"), use the screenshot as primary visual evidence. The accessibility tree is secondary — it may miss visual states.
 </reasoning_rules>
@@ -218,6 +272,8 @@ Here are examples of good output patterns:
 <evaluation_examples>
 "evaluation_previous_goal": "Clicked the submit button and form was submitted successfully. Screenshot confirms success dialog visible. Verdict: Success"
 "evaluation_previous_goal": "Attempted to click '编辑' but screenshot shows permission error tooltip. Verdict: Failed"
+"evaluation_previous_goal": "Clicked 确定 but tool returned ⚠️ dialog still open — form validation blocked submission. Verdict: Failed, need to fix form fields"
+"evaluation_previous_goal": "Clicked 确定 3 times but dialog stays open with '口径与已有指标重复' warning. Cannot resolve within current context. Verdict: Failed"
 "evaluation_previous_goal": "Screenshot shows the target page loaded with expected data in the table. Verdict: Success"
 </evaluation_examples>
 
@@ -237,9 +293,9 @@ You MUST output a JSON object with the following FLAT structure every step:
   "evaluation_previous_goal": "Concise one-sentence analysis of your last action. State success, failure, or uncertain. Reference the screenshot if it confirms or contradicts the expected state.",
   "memory": "1-3 concise sentences of key observations that will help in future steps.",
   "next_goal": "State the next immediate goal and action to achieve it.",
-  "tool": "The action tool name (click, type, hover, navigate, scroll, wait, done, visual_locate, etc.)",
+  "tool": "The action tool name (click, type, hover, navigate, scroll, wait, wait_for, done, drag, verify_value, handle_dialog, console_messages, file_upload, network_requests, resize_viewport, visual_locate, visual_assert, select_option, fill_form, pressKey, execute_javascript, etc.)",
   "ref": "Element ref from the accessibility tree, e.g. 'f5e13' (for click/type/hover)",
-  "text": "Text to type (for type) OR description for done/visual_locate",
+  "text": "Text to type (for type) OR description for done/visual_locate/visual_assert",
   ...other tool-specific fields...
 }