@kkeve/suite 0.0.1 → 0.0.2

package/dist/page-agent/hooks.js

@@ -0,0 +1,218 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractDiagnosticHints = extractDiagnosticHints;
+/* scriptRefine \u5df2\u6ce8\u91ca \u2014 \u4ea7\u51fa\u65e0\u4e0b\u6e38\u6d88\u8d39\u4e14\u4e0d\u53d7 keveGoal \u8d85\u65f6\u63a7\u5236\uff0c\u8be6\u89c1 WW-02 \u6839\u56e0\u5206\u6790
+const REFINE_OUTPUT_SCHEMA = z.object({
+    analysis: z.string().describe('Brief analysis of what was missing in the original fn'),
+    patch: z.string().describe('Unified diff patch to fix the fn. Use standard git diff format.'),
+    confidence: z.number().min(0).max(100).describe('Confidence 0-100'),
+});
+
+const REFINE_SYSTEM_PROMPT = `You are a test script refinement assistant. You analyze test execution logs and generate git diff patches to improve test scripts.
+
+Given:
+1. The original test script file content
+2. The fn source code that was executed
+3. The gap description (what was missing)
+4. The Re-Act exploration actions (what AI did to fill the gap)
+
+Generate a unified diff patch that modifies the .keve.ts file to include the missing steps.
+Rules:
+- Only modify the fn body (the async () => { ... } callback inside keveGoal)
+- Add the operations that Re-Act discovered (scroll, click, waitFor, etc.)
+- Preserve the existing fn operations
+- Use Playwright native API (page.getByRole, page.locator, etc.)
+- Output standard unified diff format`;
+
+export interface RefineInput {
+    specFilePath: string;
+    step: string;
+    expected: string;
+    testTitle: string;
+    order: number;
+    fnSource: string;
+    gap: string;
+    reactActions: Array<{ tool: string; role?: string; name?: string; url?: string; text?: string; key?: string; evaluation?: string }>;
+}
+
+export async function scriptRefine(llm: any, input: RefineInput): Promise<string | null> {
+    if (!input.specFilePath || !fs.existsSync(input.specFilePath)) return null;
+    if (!input.reactActions?.length) return null;
+
+    const specContent = fs.readFileSync(input.specFilePath, 'utf-8');
+
+    const userMessage = `## Test Script File: ${input.specFilePath}
+
+\`\`\`typescript
+${specContent}
+\`\`\`
+
+## Executed fn:
+\`\`\`typescript
+${input.fnSource}
+\`\`\`
+
+## Gap (what was missing):
+${input.gap}
+
+## Re-Act Actions (what AI did to achieve the expected state):
+${JSON.stringify(input.reactActions, null, 2)}
+
+Generate a unified diff patch to fix the fn. Add the missing operations that Re-Act discovered.`;
+
+    const refineTool = {
+        RefineOutput: {
+            description: 'Output your script refinement as a unified diff patch.',
+            inputSchema: REFINE_OUTPUT_SCHEMA,
+            execute: async (args: any) => args,
+        },
+    };
+
+    try {
+        const llmResult = await llm.invoke(
+            [{ role: 'system', content: REFINE_SYSTEM_PROMPT }, { role: 'user', content: userMessage }],
+            refineTool,
+            new AbortController().signal,
+            { toolChoiceName: 'RefineOutput' },
+        );
+
+        const parsed = REFINE_OUTPUT_SCHEMA.parse(llmResult.toolCall.args);
+
+        // Save patch file
+        const taskDir = process.env.KEVE_TASK_DIR || '.keve';
+        const round = process.env.KEVE_ROUND || 'latest';
+        const refineDir = path.join(taskDir, 'test-artifacts', `round-${round}`, 'refine');
+        fs.mkdirSync(refineDir, { recursive: true });
+        const safeName = input.testTitle.replace(/[^a-zA-Z0-9\u4e00-\u9fff]/g, '_').slice(0, 40);
+        const patchFile = path.join(refineDir, `refine-${safeName}-step${input.order}.patch`);
+        fs.writeFileSync(patchFile, [
+            `# script-refine for: ${input.testTitle} / ${input.step}`,
+            `# Gap: ${input.gap.slice(0, 200)}`,
+            `# Analysis: ${parsed.analysis}`,
+            `# Confidence: ${parsed.confidence}%`,
+            ``,
+            parsed.patch,
+        ].join('\n'), 'utf-8');
+
+        console.log(`[script-refine] Generated patch: ${path.relative(taskDir, patchFile)}`);
+        console.log(`[script-refine] Analysis: ${parsed.analysis}`);
+        console.log(`[script-refine] Confidence: ${parsed.confidence}%`);
+
+        return patchFile;
+    } catch (err: any) {
+        console.warn(`[script-refine] Failed to generate patch: ${err.message}`);
+        return null;
+    }
+}
+// \u2500\u2500 scriptRefine \u6ce8\u91ca\u7ed3\u675f \u2500\u2500 */
+/**
+ * diagnostic.ts — Extract diagnostic hints from agent result + page state
+ *
+ * Called in onAfterTask hook to generate human-readable failure reasons.
+ * Inspects the agent's action history, final snapshot, and live page DOM
+ * to produce actionable diagnostic hints.
+ */
+/**
+ * Extract diagnostic hints from agent result and current page state.
+ * Only meaningful when result.success === false.
+ */
+async function extractDiagnosticHints(page, result) {
+    const hints = [];
+    // 1. From done action's text — AI's own failure reason
+    const doneEvent = result.events
+        .filter((e) => e.type === 'step')
+        .find(e => e.toolName === 'done');
+    if (doneEvent?.toolOutput) {
+        hints.push(doneEvent.toolOutput);
+    }
+    // 2. From finalSnapshot — key page state signals
+    if (result.finalSnapshot) {
+        const snapshot = String(result.finalSnapshot);
+        const disabledButtons = snapshot.match(/button\s+"[^"]+"\s+\[disabled\]/g);
+        if (disabledButtons) {
+            for (const db of disabledButtons) {
+                const label = db.match(/button\s+"([^"]+)"/)?.[1] || '';
+                hints.push(`按钮「${label}」为禁用(disabled)状态，当前用户可能无操作权限`);
+            }
+        }
+        if (/login|auth|signin|sso|cas/i.test(snapshot)) {
+            hints.push('页面被重定向到登录页，当前浏览器未登录或登录已过期');
+        }
+    }
+    // 3. Inspect live page DOM
+    try {
+        const currentUrl = page.url();
+        console.log(`[diagnostic] page.url() = ${currentUrl}`);
+        if (currentUrl === 'about:blank' || currentUrl === '') {
+            hints.push('Playwright 页面对象停留在 about:blank，AI 探索未导航到目标页面（LLM 不可用或未配置）');
+        }
+        else {
+            // 3a. Check disabled buttons
+            const disabledButtons = await page.locator('button[disabled], button.ant-btn-disabled, button[class*="disabled"]').allInnerTexts();
+            console.log(`[diagnostic] disabledButtons=${JSON.stringify(disabledButtons)}`);
+            if (disabledButtons.length) {
+                for (const text of disabledButtons) {
+                    const label = text.trim();
+                    if (label && !hints.some(h => h.includes(label))) {
+                        hints.push(`按钮「${label}」为禁用(disabled)状态，当前用户可能无操作权限`);
+                    }
+                }
+            }
+            // 3b. Check login redirect
+            if ((currentUrl.includes('sso') || currentUrl.includes('cas/login') || /login|auth|signin/i.test(currentUrl))
+                && !hints.some(h => h.includes('登录页'))) {
+                hints.push('页面被重定向到登录页，当前浏览器未登录或登录已过期');
+            }
+            // 3c. Overlay/modal/alert text
+            const overlaySelectors = [
+                '.ant-modal-body', '.ant-modal-confirm-content', '.ant-alert-message', '.ant-alert-description',
+                '.ant-notification-notice-message', '.ant-notification-notice-description',
+                '.ant-result-title', '.ant-result-subtitle', '.ant-empty-description',
+                '[class*="overlay"]', '[class*="mask"]', '[class*="forbidden"]', '[class*="ban-edit"]',
+                '[class*="disabled-mask"]', '[role="dialog"]', '[role="alert"]', '[role="alertdialog"]',
+                '.ant-modal-mask + .ant-modal-wrap',
+            ].join(', ');
+            const overlayTexts = await page.locator(overlaySelectors).allInnerTexts();
+            if (overlayTexts.length) {
+                for (const text of overlayTexts) {
+                    const t = text.trim();
+                    if (t && !hints.some(h => h.includes(t))) {
+                        hints.push(`页面显示提示: 「${t}」`);
+                    }
+                }
+            }
+            // 3d. Fallback: key lines from body
+            if (hints.length === 0 || !hints.some(h => h.includes('页面显示提示'))) {
+                try {
+                    const bodyText = await page.locator('body').innerText({ timeout: 3000 });
+                    const keyLines = bodyText.split('\n')
+                        .map(l => l.trim())
+                        .filter(l => l.length > 4 && l.length < 200 &&
+                        (l.includes('禁止') || l.includes('下线') || l.includes('无权') || l.includes('无法') ||
+                            l.includes('不存在') || l.includes('已删除') || l.includes('过期') || l.includes('失败') ||
+                            l.includes('错误') || l.includes('异常') || l.includes('提醒') || l.includes('通知')));
+                    for (const line of keyLines.slice(0, 3)) {
+                        if (!hints.some(h => h.includes(line))) {
+                            hints.push(`页面实际显示: 「${line}」`);
+                        }
+                    }
+                }
+                catch { /* ignore */ }
+            }
+            // 3e. Last resort: report page title
+            if (hints.length === 0) {
+                try {
+                    const pageTitle = await page.title();
+                    if (pageTitle) {
+                        hints.push(`当前页面标题: 「${pageTitle}」(URL: ${currentUrl})`);
+                    }
+                }
+                catch { /* ignore */ }
+            }
+        }
+    }
+    catch (e) {
+        console.log(`[diagnostic] page inspection failed: ${e.message}`);
+    }
+    return hints;
+}

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

@@ -0,0 +1,29 @@
+/**
+ * page-agent tools — Playwright-native action tools
+ *
+ * Design: Each tool has independent inputSchema + execute.
+ * Tools are registered in a Map, then packed into a MacroTool for LLM invocation.
+ *
+ * Element targeting: aria-ref via page.locator('aria-ref=xxx')
+ * - mode:'ai' snapshot provides [ref=f5e13] identifiers
+ * - aria-ref selector automatically penetrates iframe boundaries
+ */
+import { z } from 'zod';
+import type { KevePageAgent } from './agent';
+export interface ToolContext {
+    signal: AbortSignal;
+}
+export interface PageAgentTool<TParams = any> {
+    description: string;
+    inputSchema: z.ZodType<TParams>;
+    execute: (this: KevePageAgent, args: TParams, ctx: ToolContext) => Promise<string>;
+}
+export declare function tool<TParams>(options: PageAgentTool<TParams>): PageAgentTool<TParams>;
+export declare const tools: Map<string, PageAgentTool<any>>;
+export declare function getZodShape(schema: any): Record<string, any>;
+export declare function packMacroToolSchema(): z.ZodObject<{
+    evaluation_previous_goal: z.ZodOptional<z.ZodString>;
+    memory: z.ZodOptional<z.ZodString>;
+    next_goal: z.ZodOptional<z.ZodString>;
+}, z.core.$loose>;
+export type MacroToolInput = z.infer<ReturnType<typeof packMacroToolSchema>>;

package/dist/page-agent/tools.js

@@ -0,0 +1,297 @@
+"use strict";
+/**
+ * page-agent tools — Playwright-native action tools
+ *
+ * Design: Each tool has independent inputSchema + execute.
+ * Tools are registered in a Map, then packed into a MacroTool for LLM invocation.
+ *
+ * Element targeting: aria-ref via page.locator('aria-ref=xxx')
+ * - mode:'ai' snapshot provides [ref=f5e13] identifiers
+ * - aria-ref selector automatically penetrates iframe boundaries
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tools = void 0;
+exports.tool = tool;
+exports.getZodShape = getZodShape;
+exports.packMacroToolSchema = packMacroToolSchema;
+const zod_1 = require("zod");
+function tool(options) {
+    return options;
+}
+// ─── Tool Registry ────────────────────────────────────────────────────
+exports.tools = new Map();
+// --- done ---
+exports.tools.set('done', tool({
+    description: 'Complete the task with a test conclusion. Use this when the expected state is achieved, not achieved, or you are blocked.',
+    inputSchema: zod_1.z.object({
+        verdict: zod_1.z.enum(['pass', 'fail', 'blocked']).describe('Test verdict: "pass"=expected state achieved; "fail"=page accessible but expected not met; "blocked"=cannot continue (SSO, connection refused, etc.)'),
+        text: zod_1.z.string().describe('Summary of what was achieved, why it failed, or why blocked'),
+    }),
+    execute: async function (input) {
+        const icons = { pass: '✅', fail: '❌', blocked: '🚫' };
+        let verdict = input.verdict;
+        // 强制校验：verdict 缺失或非法时从 text 推断（MacroTool 扁平化导致 verdict 变 optional）
+        if (!icons[verdict]) {
+            console.warn(`[done] ⚠️ verdict missing or invalid ("${input.verdict}"), inferring from text`);
+            const t = String(input.text || '').toLowerCase();
+            if (t.includes('fail') || t.includes('failure') || t.includes('失败') || t.includes('不通过') || t.includes('未通过')) {
+                verdict = 'fail';
+            }
+            else if (t.includes('blocked') || t.includes('阻塞') || t.includes('阻止')) {
+                verdict = 'blocked';
+            }
+            else {
+                verdict = 'pass'; // 有 text 且无否定词 → 默认 pass
+            }
+        }
+        return `${icons[verdict]} Task ${verdict}: ${input.text}`;
+    },
+}));
+// --- click ---
+exports.tools.set('click', tool({
+    description: 'Click an element by its ref identifier from the accessibility tree. The aria-ref selector automatically penetrates iframe boundaries.',
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().describe('Element ref from the accessibility tree, e.g. "f5e13"'),
+    }),
+    execute: async function (input) {
+        const locator = this.page.locator(`aria-ref=${input.ref}`);
+        await locator.click({ timeout: 5000, force: true });
+        return `✅ Clicked element [ref=${input.ref}]`;
+    },
+}));
+// --- type ---
+exports.tools.set('type', tool({
+    description: 'Type text into an input element by its ref identifier. Clears existing content first. The aria-ref selector automatically penetrates iframe boundaries.',
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().describe('Element ref from the accessibility tree, e.g. "f5e91"'),
+        text: zod_1.z.string().describe('Text to type into the element'),
+        submit: zod_1.z.boolean().optional().describe('Whether to press Enter after typing'),
+    }),
+    execute: async function (input) {
+        const locator = this.page.locator(`aria-ref=${input.ref}`);
+        await locator.fill(input.text, { timeout: 5000, force: true });
+        if (input.submit)
+            await this.page.keyboard.press('Enter');
+        return `✅ Typed "${input.text.slice(0, 50)}" into element [ref=${input.ref}]${input.submit ? ' + Enter' : ''}`;
+    },
+}));
+// --- hover ---
+exports.tools.set('hover', tool({
+    description: 'Hover over an element by its ref identifier. The aria-ref selector automatically penetrates iframe boundaries.',
+    inputSchema: zod_1.z.object({
+        ref: zod_1.z.string().describe('Element ref from the accessibility tree, e.g. "f5e13"'),
+    }),
+    execute: async function (input) {
+        const locator = this.page.locator(`aria-ref=${input.ref}`);
+        await locator.hover({ timeout: 5000, force: true });
+        return `✅ Hovered over element [ref=${input.ref}]`;
+    },
+}));
+// --- pressKey ---
+exports.tools.set('pressKey', tool({
+    description: 'Press a keyboard key (Enter, Escape, Tab, ArrowDown, etc.)',
+    inputSchema: zod_1.z.object({
+        key: zod_1.z.string().describe('Key to press: Enter, Escape, Tab, ArrowDown, etc.'),
+    }),
+    execute: async function (input) {
+        await this.page.keyboard.press(input.key);
+        return `✅ Pressed key "${input.key}"`;
+    },
+}));
+// --- scroll ---
+exports.tools.set('scroll', tool({
+    description: 'Scroll the page vertically. Use when target content is off-screen.',
+    inputSchema: zod_1.z.object({
+        direction: zod_1.z.enum(['down', 'up']).default('down').describe('Scroll direction'),
+        amount: zod_1.z.number().optional().describe('Scroll amount in pixels (default 500)'),
+    }),
+    execute: async function (input) {
+        const pixels = input.amount ?? 500;
+        const dir = input.direction === 'down' ? 1 : -1;
+        await this.page.mouse.wheel(0, pixels * dir);
+        return `✅ Scrolled ${input.direction} ${pixels}px`;
+    },
+}));
+// --- wait ---
+exports.tools.set('wait', tool({
+    description: 'Wait for a specified duration (in milliseconds). Use when page is loading.',
+    inputSchema: zod_1.z.object({
+        time: zod_1.z.number().min(100).max(10000).describe('Wait time in milliseconds'),
+    }),
+    execute: async function (input) {
+        await this.page.waitForTimeout(input.time);
+        return `✅ Waited ${input.time}ms`;
+    },
+}));
+// --- navigate ---
+exports.tools.set('navigate', tool({
+    description: 'Navigate to a URL. Use KEVE_TARGET_URL (from test-cases.yaml principle) for the main application page. For other pages, use URLs from envVars (e.g., process.env.PAGE_KNOWLEDGE). Do NOT construct or guess URLs yourself.',
+    inputSchema: zod_1.z.object({
+        url: zod_1.z.string().describe('URL to navigate to. Use process.env.KEVE_TARGET_URL for the main page, or envVars for other declared pages. Supports absolute URLs or relative paths starting with /'),
+    }),
+    execute: async function (input) {
+        let url = input.url;
+        if (!url.startsWith('http://') && !url.startsWith('https://')) {
+            const base = process.env.KEVE_TARGET_URL || process.env.BASE_URL || '';
+            url = new URL(url, base).href;
+        }
+        await this.page.goto(url, { waitUntil: 'networkidle', timeout: 15000 });
+        return `✅ Navigated to ${url}`;
+    },
+}));
+// --- execute_javascript ---
+exports.tools.set('execute_javascript', tool({
+    description: 'READ-ONLY query tool: execute JavaScript in the BROWSER DOM context to retrieve precise values that screenshots and accessibility trees CANNOT provide — such as computed CSS styles (getComputedStyle), DOM measurements (offsetWidth, getBoundingClientRect), or element properties (checked, disabled, value).\n\n⚠️ EXECUTION CONTEXT: This runs inside the browser page via page.evaluate — it is a plain browser JavaScript sandbox. There is NO `page` object, NO Playwright API, NO `locator`, NO top-level `await`. Using `page.locator(...)`, `page.evaluate(...)`, `await`, or `async () => {}` wrappers will cause SyntaxError or return undefined.\n\nDo NOT use for: clicking, typing, navigating, form filling, or any page interaction — use click/type/navigate tools instead. Do NOT use for: assertions or logical checks — just return the raw value, you judge the result yourself. Do NOT use for: modifying page state (setting styles, cookies, localStorage, DOM mutations).',
+    inputSchema: zod_1.z.object({
+        script: zod_1.z.string().describe("JavaScript code to execute inside the browser DOM. MUST start with `return` to capture the result. Use `var` for variable declarations (NOT `const`/`let` — they cause SyntaxError in some evaluate contexts). Only browser DOM APIs: document.querySelector, window.getComputedStyle, etc.\n\n✅ Correct: 'return document.querySelector(\".x\").innerText'\n✅ Correct: 'var el = document.querySelector(\".x\"); return window.getComputedStyle(el).backgroundColor'\n❌ Wrong: 'page.locator(\".x\")' — no Playwright `page` object in browser context\n❌ Wrong: 'await page.locator(...)' — no `await` or `async`\n❌ Wrong: 'const el = ...' — use `var` instead of `const`/`let`\n❌ Wrong: 'async () => { ... }' — do NOT wrap in async function, returns undefined\n\nRead-only queries only."),
+    }),
+    execute: async function (input) {
+        try {
+            let script = input.script.trim();
+            // Auto-unwrap arrow function wrappers that Agent frequently generates:
+            //   async () => { ... return ... }  →  ... return ...
+            //   () => { ... return ... }        →  ... return ...
+            //   (async () => { ... })()        →  ... return ...
+            // These wrappers cause page.evaluate to return undefined because the
+            // arrow function is created but never invoked inside the IIFE.
+            const arrowMatch = script.match(/^(?:async\s+)?(?:\(\s*\)\s*|)\s*=>\s*\{([\s\S]*)\}\s*;?\s*$/);
+            if (arrowMatch) {
+                script = arrowMatch[1].trim();
+            }
+            // Also strip IIFE self-call: (async () => { ... })()
+            const iifeMatch = script.match(/^\(\s*(?:async\s+)?\(\s*\)\s*=>\s*\{([\s\S]*)\}\s*\)\s*\(\s*\)\s*;?\s*$/);
+            if (iifeMatch) {
+                script = iifeMatch[1].trim();
+            }
+            // Read-only guard: block DOM mutation APIs to prevent Agent from altering page state.
+            const writePatterns = [
+                /\b(?:document|element|el|node)\.\s*(?:remove|appendChild|insertBefore|replaceChild|removeChild|appendChild)\s*\(/,
+                /\b(?:document|element|el|node)\.\s*(?:innerHTML|outerHTML|textContent|innerText)\s*=/,
+                /\b(?:document|element|el|node)\.\s*(?:setAttribute|removeAttribute|classList)\s*\./,
+                /\b\.style\s*\.\s*\w+\s*=/,
+                /\blocation\s*(?:\.href\s*=|\.assign\s*\(|\.replace\s*\()/,
+                /\bwindow\s*\.\s*(?:close|stop|open)\s*\(/,
+                /\bdocument\.\s*(?:write|writeln|execCommand)\s*\(/,
+                /\blocalStorage\s*\.\s*set\s*\(/,
+                /\bsessionStorage\s*\.\s*set\s*\(/,
+                /\bdocument\.cookie\s*=/,
+                /\beval\s*\(/,
+            ];
+            for (const pattern of writePatterns) {
+                if (pattern.test(script)) {
+                    return `❌ JS execution blocked: write/mutation API detected. execute_javascript is read-only. Use click/type/navigate tools for interactions.`;
+                }
+            }
+            // Require explicit `return` — no auto-wrapping.
+            // Wrap in IIFE so `return` is valid (page.evaluate treats bare strings as expressions).
+            if (!/\breturn\b/.test(script)) {
+                return `❌ Script must start with 'return' to capture the result. Example: "return window.getComputedStyle(document.body).backgroundColor"`;
+            }
+            const wrapped = `(function() { ${script} })()`;
+            const result = await this.page.evaluate(wrapped);
+            const output = typeof result === 'object' && result !== null
+                ? JSON.stringify(result, null, 2)
+                : String(result ?? 'undefined');
+            return `✅ JS executed. Result: ${output}`;
+        }
+        catch (err) {
+            return `❌ JS execution error: ${err.message || String(err)}`;
+        }
+    },
+}));
+// --- visual_locate ---
+exports.tools.set('visual_locate', tool({
+    description: 'Locate and click an element by visual analysis of a screenshot. FALLBACK: only use after `click` fails 2+ times on the same element (non-standard ARIA role, invisible in accessibility tree, or element visible in screenshot but missing from accessibility tree). Provide a concise visual description of the element. It will screenshot the page, send it to a multimodal LLM to locate the element, then click at the predicted coordinates. After clicking, verify the effect on the next screenshot.',
+    inputSchema: zod_1.z.object({
+        description: zod_1.z.string().describe('Visual description of the element to find, e.g. "the dropdown button showing 当前Agent▼"'),
+    }),
+    execute: async function (input) {
+        // 1. Capture screenshot
+        let screenshotBase64;
+        try {
+            const buf = await this.page.screenshot({ type: 'png', timeout: 10000 });
+            screenshotBase64 = buf.toString('base64');
+        }
+        catch (e) {
+            throw new Error(`visual_locate screenshot failed: ${e.message}`);
+        }
+        // 2. Call LLM for visual element location
+        const locateResult = await this.visualLocateElement(screenshotBase64, input.description);
+        if (!locateResult.found || !locateResult.bbox || locateResult.bbox.length !== 4) {
+            return `❌ Visual locate failed: element "${input.description}" not found. ${locateResult.analysis || ''}`;
+        }
+        // 3. Convert normalized bbox (0-1000) to viewport pixel coordinates
+        const viewport = this.page.viewportSize() || { width: 1280, height: 720 };
+        const [x1, y1, x2, y2] = locateResult.bbox;
+        const centerX = Math.round(((x1 + x2) / 2) * viewport.width / 1000);
+        const centerY = Math.round(((y1 + y2) / 2) * viewport.height / 1000);
+        // 4. Click at coordinates (bypasses iframe boundaries)
+        await this.page.mouse.click(centerX, centerY);
+        return `✅ Visual locate & click: "${input.description}" at (${centerX}, ${centerY})`;
+    },
+}));
+// ── verify_expected fully removed (Phase 6) ──
+// LLM now sees screenshots via multimodal prompt and self-evaluates.
+// No separate verification tool or function needed — each step's screenshot
+// is injected into the LLM prompt directly, so LLM judges goal state itself.
+// ─── Zod schema helper (used by packMacroToolSchema & MacroTool execute) ──
+function getZodShape(schema) {
+    const def = schema?._def;
+    if (!def)
+        return schema?.shape || {};
+    const s = def.shape;
+    return typeof s === 'function' ? s() : (s || schema?.shape || {});
+}
+// ─── Pack tools into MacroTool schema for LLM ────────────────────────
+// Auto-derive flat schema from tools Map (like page-agent's #packMacroTool).
+// Key insight: z.union() is UNSTABLE with keve-core's safeParse.
+// Solution: merge all tool inputSchema fields into one flat object with `tool` enum.
+function packMacroToolSchema() {
+    // Collect tool names for enum
+    const toolNames = Array.from(exports.tools.keys());
+    // Collect all unique fields from all tool schemas
+    const fieldMap = new Map();
+    for (const [name, t] of exports.tools.entries()) {
+        // Unwrap ZodObject to get its shape
+        const shape = getZodShape(t.inputSchema);
+        for (const [key, val] of Object.entries(shape)) {
+            if (!fieldMap.has(key)) {
+                // First encounter — store the schema and add tool names to description
+                const zodField = val;
+                const desc = zodField._def?.description || '';
+                fieldMap.set(key, { schema: zodField.optional(), description: desc });
+            }
+            // If field already exists, just ensure description mentions both tools
+        }
+    }
+    // Build the flat schema
+    const reflectionFields = {
+        evaluation_previous_goal: zod_1.z.string().optional()
+            .describe('Concise one-sentence analysis of your last action. State success, failure, or uncertain.'),
+        memory: zod_1.z.string().optional()
+            .describe('1-3 concise sentences of key observations that will help in future steps.'),
+        next_goal: zod_1.z.string().optional()
+            .describe('State the next immediate goal and action to achieve it.'),
+    };
+    const actionFields = {
+        tool: zod_1.z.enum(toolNames).describe('The action tool to use'),
+    };
+    // Add all tool fields as optional
+    for (const [key, { schema, description }] of fieldMap.entries()) {
+        // Make all fields optional + add which tools use this field
+        const usedBy = Array.from(exports.tools.entries())
+            .filter(([_, t]) => {
+            const shape = getZodShape(t.inputSchema);
+            return key in shape;
+        })
+            .map(([name]) => name);
+        const enrichedDesc = usedBy.length > 1
+            ? `${description} (for ${usedBy.join('/')})`
+            : description;
+        actionFields[key] = schema.describe(enrichedDesc);
+    }
+    return zod_1.z.object({
+        ...reflectionFields,
+        ...actionFields,
+    }).passthrough(); // Allow extra LLM fields for stability
+}