@kkeve/suite 0.0.12 → 0.0.13

package/dist/core/keve-test.js

@@ -87,9 +87,10 @@ keve_aspect_1.keveAspect.register({
     phase: 'after',
     order: 20,
     async execute(ctx, result) {
-        if (!result?.actions?.length || !result.success)
+        if (!result?.actions?.length)
             return;
-        learned_actions_1.learnedActions.add(ctx.step, result.actions);
+        const url = ctx.page.url();
+        learned_actions_1.learnedActions.add(ctx.step, result.actions, url, result.success);
     },
 });
 // ─── (diagnostic extraction moved to page-agent/diagnostic.ts, called via onAfterTask hook) ──
@@ -202,7 +203,8 @@ exports.test = test_1.test.extend({
                 catch { /* non-critical */ }
             }
             // ── Hand off to agent: agent does Re-Act (OR shortcut to blocked if fnBlocked) ──
-            const learnedHint = learned_actions_1.learnedActions.getHint(options.step);
+            const currentUrl = page.url();
+            const learnedHint = learned_actions_1.learnedActions.getHint(options.step, currentUrl);
             let reactResult;
             let reactTimedOut = false;
             if (fnBlocked) {

package/dist/core/learned-actions.d.ts

@@ -4,21 +4,50 @@
  * When one keveGoal's Re-Act loop discovers a working action sequence,
  * other goals in the same round can use those discoveries as hints.
  *
- * Key format: "${step}" — the step description
- * Value: ActionLogEntry[] — the successful action sequence
+ * v2: Fuzzy matching by token Jaccard similarity + page URL pattern.
+ *     Exact match is tried first; if no hit, fuzzy search across all entries.
  */
+interface CacheEntry {
+    step: string;
+    actions: any[];
+    url?: string;
+    success: boolean;
+}
 export declare class LearnedActions {
     private cache;
-    /** Store discovered actions for a step */
-    add(step: string, actions: any[]): void;
-    /** Retrieve discovered actions for a step */
+    /** Store discovered actions for a step (with optional page URL for context matching)
+     *  @param success Whether the step succeeded — failed entries are stored with warnings only
+     */
+    add(step: string, actions: any[], url?: string, success?: boolean): void;
+    /** Retrieve discovered actions for a step (exact match) */
     get(step: string): any[] | undefined;
-    /** Get a JSON hint string for injecting into Re-Act prompt */
-    getHint(step: string): string | undefined;
+    /** Tokenize a Chinese/mixed step description for fuzzy matching.
+     *  Uses bigram (character pair) extraction for Chinese — more granular than
+     *  whitespace splitting, captures shared sub-phrases like "指标标准名称".
+     */
+    private tokenize;
+    /** Compute Jaccard similarity between two token sets */
+    private jaccard;
+    /** Find the best matching cached entry for a given step description */
+    private findBestMatch;
+    /** Get a hint string for injecting into Re-Act prompt.
+     *  1. Exact match → direct reuse
+     *  2. Fuzzy match by token similarity → similar step reuse
+     *  3. Same-page fallback → if same URL path, use the most recent successful entry
+     */
+    getHint(step: string, currentUrl?: string): string | undefined;
+    /** Extract path portion of URL for same-page matching (ignore query/hash) */
+    private extractPath;
+    /** Format a hint from a cache entry's actions.
+     *  Success: action sequence summary + key discoveries
+     *  Failure: warnings/blockers only — avoid misleading Agent into reusing failed paths
+     */
+    private formatHint;
     /** Get all cached entries */
-    getAll(): Map<string, any[]>;
+    getAll(): Map<string, CacheEntry>;
     /** Clear all cached entries (typically at round start) */
     clear(): void;
 }
 /** Global singleton for same-round sharing */
 export declare const learnedActions: LearnedActions;
+export {};

package/dist/core/learned-actions.js

@@ -5,51 +5,243 @@
  * When one keveGoal's Re-Act loop discovers a working action sequence,
  * other goals in the same round can use those discoveries as hints.
  *
- * Key format: "${step}" — the step description
- * Value: ActionLogEntry[] — the successful action sequence
+ * v2: Fuzzy matching by token Jaccard similarity + page URL pattern.
+ *     Exact match is tried first; if no hit, fuzzy search across all entries.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.learnedActions = exports.LearnedActions = void 0;
 class LearnedActions {
     cache = new Map();
-    /** Store discovered actions for a step */
-    add(step, actions) {
-        // Only store successful action sequences (ending with expected met)
+    /** Store discovered actions for a step (with optional page URL for context matching)
+     *  @param success Whether the step succeeded — failed entries are stored with warnings only
+     */
+    add(step, actions, url, success = true) {
         if (actions.length > 0) {
-            this.cache.set(step, actions);
+            this.cache.set(step, { step, actions, url, success });
         }
     }
-    /** Retrieve discovered actions for a step */
+    /** Retrieve discovered actions for a step (exact match) */
     get(step) {
-        return this.cache.get(step);
+        return this.cache.get(step)?.actions;
     }
-    /** Get a JSON hint string for injecting into Re-Act prompt */
-    getHint(step) {
-        const actions = this.cache.get(step);
-        if (!actions || actions.length === 0)
-            return undefined;
-        // Summarize: only include action type + role/name, not full snapshot
+    /** Tokenize a Chinese/mixed step description for fuzzy matching.
+     *  Uses bigram (character pair) extraction for Chinese — more granular than
+     *  whitespace splitting, captures shared sub-phrases like "指标标准名称".
+     */
+    tokenize(text) {
+        // 1. Split by delimiters to get chunks
+        const chunks = text
+            .replace(/[，。、；：""''（）【】《》\s,.;:!?/\\|]+/g, ' ')
+            .split(' ')
+            .filter(t => t.length > 0);
+        // 2. For each chunk, extract character bigrams (for Chinese sub-phrase matching)
+        //    AND keep the original chunk (for exact chunk matches)
+        const tokens = [];
+        for (const chunk of chunks) {
+            tokens.push(chunk.toLowerCase());
+            // Generate bigrams: sliding window of 2 chars
+            for (let i = 0; i < chunk.length - 1; i++) {
+                tokens.push(chunk.substring(i, i + 2).toLowerCase());
+            }
+        }
+        return tokens;
+    }
+    /** Compute Jaccard similarity between two token sets */
+    jaccard(a, b) {
+        const setA = new Set(a.map(t => t.toLowerCase()));
+        const setB = new Set(b.map(t => t.toLowerCase()));
+        const intersection = [...setA].filter(t => setB.has(t)).length;
+        const union = new Set([...setA, ...setB]).size;
+        return union === 0 ? 0 : intersection / union;
+    }
+    /** Find the best matching cached entry for a given step description */
+    findBestMatch(step) {
+        const tokens = this.tokenize(step);
+        let bestEntry;
+        let bestScore = 0;
+        // Threshold: 18% token overlap — low enough to catch "填写其他必填项" vs "必填项填入合法值",
+        // high enough to avoid completely unrelated steps matching
+        const THRESHOLD = 0.18;
+        for (const [, entry] of this.cache) {
+            const entryTokens = this.tokenize(entry.step);
+            const score = this.jaccard(tokens, entryTokens);
+            if (score > bestScore && score >= THRESHOLD) {
+                bestScore = score;
+                bestEntry = entry;
+            }
+        }
+        return bestEntry;
+    }
+    /** Get a hint string for injecting into Re-Act prompt.
+     *  1. Exact match → direct reuse
+     *  2. Fuzzy match by token similarity → similar step reuse
+     *  3. Same-page fallback → if same URL path, use the most recent successful entry
+     */
+    getHint(step, currentUrl) {
+        // 1. Try exact match first (prefer success entries over failures)
+        const exact = this.cache.get(step);
+        if (exact?.actions.length) {
+            const hint = this.formatHint(exact.step, exact.actions, false, exact.success);
+            if (hint)
+                return hint;
+        }
+        // 2. Fuzzy match by step description similarity (prefer success, but include failures)
+        const best = this.findBestMatch(step);
+        if (best?.actions.length) {
+            const hint = this.formatHint(best.step, best.actions, true, best.success);
+            if (hint)
+                return hint;
+        }
+        // 3. Same-page fallback: if on the same URL path as a cached entry, use the most
+        //    relevant one (highest Jaccard, even if below fuzzy threshold).
+        //    Minimum Jaccard = 0.08 to avoid completely unrelated steps on the same page.
+        if (currentUrl) {
+            const urlPath = this.extractPath(currentUrl);
+            let bestSamePage;
+            let bestSamePageScore = 0;
+            const SAME_PAGE_MIN = 0.08;
+            const stepTokens = this.tokenize(step);
+            for (const [, entry] of this.cache) {
+                if (entry.url && this.extractPath(entry.url) === urlPath) {
+                    const entryTokens = this.tokenize(entry.step);
+                    const score = this.jaccard(stepTokens, entryTokens);
+                    if (score > bestSamePageScore && score >= SAME_PAGE_MIN) {
+                        bestSamePageScore = score;
+                        bestSamePage = entry;
+                    }
+                }
+            }
+            if (bestSamePage?.actions.length) {
+                const hint = this.formatHint(bestSamePage.step, bestSamePage.actions, true, bestSamePage.success);
+                if (hint)
+                    return hint;
+            }
+        }
+        return undefined;
+    }
+    /** Extract path portion of URL for same-page matching (ignore query/hash) */
+    extractPath(url) {
+        try {
+            const u = new URL(url);
+            return u.pathname;
+        }
+        catch {
+            return url;
+        }
+    }
+    /** Format a hint from a cache entry's actions.
+     *  Success: action sequence summary + key discoveries
+     *  Failure: warnings/blockers only — avoid misleading Agent into reusing failed paths
+     */
+    formatHint(sourceStep, actions, isFuzzy, success) {
+        if (!success) {
+            // Failed step — surface warnings/blockers AND combobox conflict info
+            const discoveries = [];
+            for (const a of actions) {
+                const out = a.toolOutput || '';
+                if (out.startsWith('⚠️'))
+                    discoveries.push(out.slice(0, 120));
+                // Also capture combobox "重复" conflicts — valuable for later goals to avoid same data
+                if (out.includes('重复') || out.includes('duplicate') || out.includes('conflict')) {
+                    discoveries.push(`DATA CONFLICT: ${out.slice(0, 120)}`);
+                }
+            }
+            if (discoveries.length === 0)
+                return undefined;
+            const prefix = isFuzzy
+                ? `Previous FAILED step SIMILAR to "${sourceStep}"`
+                : `Previous FAILED step "${sourceStep}"`;
+            return `${prefix} — avoid these approaches. Blocked by: ${discoveries.slice(-3).map(d => `[${d}]`).join('; ')}`;
+        }
+        // Success — full action sequence + discoveries (existing logic)
+        // Extract stable element identity from toolOutput (not from action fields which lack role/name)
         const summary = actions
-            .filter(a => a.action.tool !== 'done')
+            .filter(a => a.action?.tool !== 'done' && a.tool !== 'done')
             .map(a => {
-            const act = a.action;
+            const act = a.action || a;
+            const out = a.toolOutput || '';
             if (act.tool === 'navigate')
                 return `navigate(${act.url})`;
-            if (act.tool === 'click')
-                return `click(${act.role} "${act.name}")`;
-            if (act.tool === 'type')
-                return `type(${act.role} "${act.name}", "${act.text}"${act.submit ? ', Enter' : ''})`;
+            if (act.tool === 'click') {
+                // Parse toolOutput: "✅ Clicked [ref=e688] button \"新增指标\"" → "button 新增指标"
+                // or: "⚠️ Clicked [ref=e2843] button \"确定\" — dialog still open" → "button 确定"
+                const descMatch = out.match(/Clicked \[ref=\w+\]\s+(\S+\s+"[^"]*"|\S+)/);
+                if (descMatch) {
+                    // descMatch[1] = 'button "新增指标"' or 'button "确定"' or 'element'
+                    const clean = descMatch[1].replace(/"/g, '').trim();
+                    return `click(${clean})`;
+                }
+                return `click(?)`;
+            }
+            if (act.tool === 'type') {
+                // Parse toolOutput for stable type info
+                const typeMatch = out.match(/✅ (replace|append) "([^"]*)" into element \[ref=\w+\]/);
+                if (typeMatch)
+                    return `type("${typeMatch[2].slice(0, 30)}"${typeMatch[1] === 'append' ? ', append' : ''})`;
+                // Combobox selection
+                const cbMatch = out.match(/✅ Selected "([^"]*)" in combobox/);
+                if (cbMatch)
+                    return `select("${cbMatch[1].slice(0, 30)}")`;
+                return `type(?)`;
+            }
+            if (act.tool === 'fill_form') {
+                // Extract filled fields from multi-line toolOutput
+                // Lines look like: "✅ textbox [e2755] = "测试指标标准名称"" or "✅ combobox [e2800] = "KwaiBI官方数据集DEMO" (custom)"
+                const fields = [];
+                for (const line of out.split('\n')) {
+                    const fieldMatch = line.match(/✅ (\w+) \[\w+\] = "?([^"]*?)"?\s*(\(custom\))?$/);
+                    if (fieldMatch && fieldMatch[2]) {
+                        const fType = fieldMatch[1];
+                        const fVal = fieldMatch[2].slice(0, 25);
+                        fields.push(`${fType}="${fVal}"`);
+                    }
+                }
+                return fields.length ? `fill_form(${fields.join(', ')})` : 'fill_form(...)';
+            }
+            if (act.tool === 'select_option') {
+                const selMatch = out.match(/✅ Selected "([^"]*)"/);
+                if (selMatch)
+                    return `select_option("${selMatch[1].slice(0, 30)}")`;
+                return `select_option(?)`;
+            }
             if (act.tool === 'hover')
-                return `hover(${act.role} "${act.name}")`;
+                return `hover(${act.role || ''} "${act.name || ''}")`;
             if (act.tool === 'pressKey')
                 return `pressKey(${act.key})`;
             if (act.tool === 'scroll')
                 return `scroll(${act.direction})`;
             if (act.tool === 'wait')
                 return `wait(${act.time}ms)`;
+            if (act.tool === 'execute_javascript') {
+                const jsResult = out.match(/✅ JS executed\. Result: (.+)/);
+                if (jsResult)
+                    return `js(→ ${jsResult[1].slice(0, 40)})`;
+                return 'js(?)';
+            }
             return act.tool;
         });
-        return `Previous successful actions for "${step}": ${summary.join(' → ')}`;
+        // Extract key toolOutput lines — discoveries that other goals need to know
+        // Focus on: combobox option results (✅/❌), dialog warnings (⚠️), validation messages
+        const discoveries = [];
+        for (const a of actions) {
+            const out = a.toolOutput || '';
+            // Combobox option selection results (most valuable for form reuse)
+            if (out.includes('combobox') && (out.includes('(custom)') || out.includes('could not find option'))) {
+                discoveries.push(out.slice(0, 120));
+            }
+            // Dialog warnings that blocked submission
+            if (out.startsWith('⚠️')) {
+                discoveries.push(out.slice(0, 120));
+            }
+        }
+        // Limit to 5 most important discoveries
+        const discoveryLines = discoveries.length > 0
+            ? `\nKey discoveries: ${discoveries.slice(-5).map(d => `[${d}]`).join('; ')}`
+            : '';
+        const prefix = isFuzzy
+            ? `Previous successful actions for SIMILAR step "${sourceStep}"`
+            : `Previous successful actions for "${sourceStep}"`;
+        return `${prefix}: ${summary.join(' → ')}${discoveryLines}`;
     }
     /** Get all cached entries */
     getAll() {

package/dist/page-agent/agent.d.ts

@@ -110,6 +110,11 @@ export declare class KevePageAgent {
         bbox?: number[];
         analysis?: string;
     }>;
+    /** Visual assertion: check a visual condition without interacting with the page */
+    visualAssertElement(screenshotBase64: string, assertion: string): Promise<{
+        passed: boolean;
+        reasoning: string;
+    }>;
     /** Build final result */
     private buildResult;
 }

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;
@@ -115,7 +200,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 +294,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 +383,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 +491,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 +638,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 || '';