@kkeve/suite 0.0.13 → 0.0.17

package/dist/page-agent/agent.js

@@ -16,51 +16,16 @@
  *   const agent = new KevePageAgent(page, { maxSteps: 5 });
  *   const result = await agent.execute(step, expected, { learnedActionsHint, fnResult });
  */
-var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    var desc = Object.getOwnPropertyDescriptor(m, k);
-    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
-      desc = { enumerable: true, get: function() { return m[k]; } };
-    }
-    Object.defineProperty(o, k2, desc);
-}) : (function(o, m, k, k2) {
-    if (k2 === undefined) k2 = k;
-    o[k2] = m[k];
-}));
-var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
-    Object.defineProperty(o, "default", { enumerable: true, value: v });
-}) : function(o, v) {
-    o["default"] = v;
-});
-var __importStar = (this && this.__importStar) || (function () {
-    var ownKeys = function(o) {
-        ownKeys = Object.getOwnPropertyNames || function (o) {
-            var ar = [];
-            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
-            return ar;
-        };
-        return ownKeys(o);
-    };
-    return function (mod) {
-        if (mod && mod.__esModule) return mod;
-        var result = {};
-        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
-        __setModuleDefault(result, mod);
-        return result;
-    };
-})();
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KevePageAgent = void 0;
 exports.reactLoop = reactLoop;
 const llm_1 = require("@kkeve/core/llm");
 const zod_1 = require("zod");
-const fs = __importStar(require("node:fs"));
-const path = __importStar(require("node:path"));
-const hooks_1 = require("./hooks");
-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");
+const hooks_js_1 = require("./hooks.js");
+const tools_js_1 = require("./tools.js");
+const system_prompt_js_1 = require("./system-prompt.js");
+const playwright_page_js_1 = require("./playwright-page.js");
+const diagnostics_js_1 = require("./diagnostics.js");
 // ─── 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) {
@@ -154,33 +119,215 @@ class KevePageAgent {
     events = [];
     abortController = new AbortController();
     systemPrompt;
+    /** 目标应用 URL（原 process.env.KEVE_TARGET_URL） */
+    targetUrl;
+    getEnvFn;
+    saveScreenshotFn;
+    loadInitialImagesFn;
     /** 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 = [];
+    _browserDiagnostics = [];
+    _networkDiagnostics = [];
+    /** 本次 execute 内 LLM 推理累计耗时（ms） */
+    _aiReasoningMs = 0;
+    /** 本次 execute 内 LLM token 累计用量 */
+    _aiUsage = { llmCalls: 0, promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    /** 本次 execute 内工具操作累计耗时（ms） */
+    _actionMs = 0;
+    /** 本次 execute 起始时间，用于总耗时诊断 */
+    _executeStartedAt = 0;
+    _pageListenersSetup = false;
+    /** 页面级性能指标（execute 结束时一次性读取；读取失败则留空） */
+    _lastPageMetrics;
     constructor(page, options) {
         this.page = page;
         this.maxSteps = options?.maxSteps ?? 8;
-        this.systemPrompt = options?.customSystemPrompt || SYSTEM_PROMPT;
+        this.systemPrompt = options?.customSystemPrompt || system_prompt_js_1.SYSTEM_PROMPT;
         this.hooks = options?.hooks;
-        const cfg = (0, config_1.loadConfig)();
+        this.getEnvFn = options?.getEnv || (() => '');
+        this.targetUrl = options?.targetUrl || this.getEnvFn('KEVE_TARGET_URL') || '';
+        this.saveScreenshotFn = options?.saveScreenshot;
+        this.loadInitialImagesFn = options?.loadInitialImages;
+        const llmConfig = options?.llm || {
+            baseURL: this.getEnvFn('KEVE_LLM_BASE_URL'),
+            model: this.getEnvFn('KEVE_LLM_MODEL_NAME'),
+            apiKey: this.getEnvFn('KEVE_LLM_API_KEY'),
+        };
         this.llm = new llm_1.LLM({
-            baseURL: cfg.llm.base_url,
-            model: cfg.llm.model,
-            apiKey: cfg.llm.api_key || '',
+            baseURL: llmConfig.baseURL,
+            model: llmConfig.model,
+            apiKey: llmConfig.apiKey || '',
             temperature: 0.1,
             maxRetries: 3,
+            customFetch: llmConfig.customFetch,
         });
     }
+    /** 读取宿主注入的环境变量（Cypress 侧由 cy.env 转发，Playwright 侧即 process.env） */
+    getEnv(name) {
+        return this.getEnvFn(name) || '';
+    }
     /** Stop the current execution */
     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) => {
+            const level = msg.type();
+            const text = msg.text();
+            this._consoleMessages.push({ level, text });
+            if (this._consoleMessages.length > 200)
+                this._consoleMessages.shift();
+            this._browserDiagnostics.push({ level, text, at: Date.now(), kind: 'console' });
+            if (this._browserDiagnostics.length > 500)
+                this._browserDiagnostics.shift();
+        });
+        this.page.on('pageerror', (err) => {
+            const text = `Uncaught: ${err?.message || String(err)}`;
+            this._consoleMessages.push({ level: 'error', text });
+            this._browserDiagnostics.push({ level: 'error', text, at: Date.now(), kind: 'pageerror' });
+            if (this._browserDiagnostics.length > 500)
+                this._browserDiagnostics.shift();
+        });
+        // ── Network requests ──
+        this.page.on('request', (req) => {
+            const url = req.url();
+            const isStatic = (0, diagnostics_js_1.isStaticUrl)(url);
+            this._networkRequests.push({
+                _req: req,
+                method: req.method(),
+                url,
+                isStatic,
+                status: null,
+                startedAt: Date.now(),
+            });
+            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) {
+                    const item = this._networkRequests[i];
+                    const status = res.status();
+                    const durationMs = item.startedAt ? Date.now() - item.startedAt : undefined;
+                    item.status = status;
+                    item.durationMs = durationMs;
+                    this._networkDiagnostics.push({
+                        url: item.url,
+                        method: item.method,
+                        status,
+                        durationMs,
+                        isStatic: item.isStatic,
+                        at: item.startedAt,
+                    });
+                    if (this._networkDiagnostics.length > 500)
+                        this._networkDiagnostics.shift();
+                    break;
+                }
+            }
+        });
+        // 请求失败（DNS/超时/连接重置等）没有 response 事件，必须在 requestfailed 记录。
+        const onRequestFailed = (req) => {
+            const failure = req.failure?.();
+            const error = failure?.errorText || 'request failed';
+            let item;
+            for (let i = this._networkRequests.length - 1; i >= 0; i--) {
+                if (this._networkRequests[i]._req === req) {
+                    item = this._networkRequests[i];
+                    break;
+                }
+            }
+            const url = item?.url || req.url();
+            const durationMs = item?.startedAt ? Date.now() - item.startedAt : undefined;
+            this._networkDiagnostics.push({
+                url,
+                method: item?.method || req.method(),
+                status: 0,
+                durationMs,
+                error: (0, diagnostics_js_1.clipDiagnosticText)(error),
+                isStatic: item?.isStatic ?? (0, diagnostics_js_1.isStaticUrl)(url),
+                at: item?.startedAt,
+            });
+            if (this._networkDiagnostics.length > 500)
+                this._networkDiagnostics.shift();
+        };
+        // Playwright 的 AgentPage 契约只保证 on/emit，requestfailed 是原生事件。
+        // 用可选探测，避免 Cypress 占位实现或其他 AgentPage 实现因未知事件报错。
+        try {
+            this.page.on('requestfailed', onRequestFailed);
+        }
+        catch { /* 非 Playwright 实现可忽略 */ }
+        // ── 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 = [];
+        this._browserDiagnostics = [];
+        this._networkDiagnostics = [];
+        this._aiReasoningMs = 0;
+        this._aiUsage = { llmCalls: 0, promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+        this._actionMs = 0;
+        this._executeStartedAt = Date.now();
+        this._lastPageMetrics = undefined;
+        // 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;
@@ -195,7 +342,7 @@ class KevePageAgent {
         const maxSteps = options?.maxSteps ?? this.maxSteps;
         const systemPrompt = options?.customSystemPrompt || this.systemPrompt;
         // Inject context/learned hints as initial observations
-        const targetUrl = process.env.KEVE_TARGET_URL || '';
+        const targetUrl = this.targetUrl;
         if (targetUrl) {
             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.`);
         }
@@ -223,13 +370,13 @@ class KevePageAgent {
                     // ── Observe: get browser state (ariaSnapshot only — no per-step screenshot) ──
                     console.log('\x1b[34m\x1b[1m👀 Observing...\x1b[0m');
                     const snapshot = await this.page.ariaSnapshot({ mode: 'ai' });
-                    const url = this.page.url();
+                    const url = await this.page.url();
                     console.log(`  url: ${url.slice(0, 120)} | step ${stepCount + 1}/${maxSteps}`);
                     // ── Assemble messages (text-only per step; initial screenshots on step 0) ──
                     const userText = this.assembleUserPrompt(step, expected, snapshot, url, stepCount, maxSteps);
                     let userContent;
                     if (stepCount === 0) {
-                        const initialImages = this.loadInitialScreenshots(options);
+                        const initialImages = await this.loadInitialScreenshots(options);
                         userContent = initialImages.length > 0
                             ? [{ type: 'text', text: userText }, ...initialImages]
                             : userText;
@@ -244,7 +391,15 @@ class KevePageAgent {
                     // ── Think + Act: LLM decides ──
                     console.log('\x1b[34m\x1b[1m🧠 Thinking...\x1b[0m');
                     const macroTool = this.buildMacroTool();
-                    const llmResult = await this.llm.invoke(messages, macroTool, this.abortController.signal, { toolChoiceName: 'AgentOutput' });
+                    const llmStartedAt = Date.now();
+                    let llmResult;
+                    try {
+                        llmResult = await this.llm.invoke(messages, macroTool, this.abortController.signal, { toolChoiceName: 'AgentOutput' });
+                        this.recordAiUsage(llmResult.usage);
+                    }
+                    finally {
+                        this._aiReasoningMs += Date.now() - llmStartedAt;
+                    }
                     const macroInput = llmResult.toolCall.args;
                     const execResult = llmResult.toolResult;
                     const reflection = {
@@ -283,7 +438,10 @@ class KevePageAgent {
                         toolError: execResult.error,
                         snapshot,
                         screenshotPath: undefined,
+                        duration: execResult.duration,
                     };
+                    if (execResult.duration !== undefined)
+                        this._actionMs += execResult.duration;
                     this.events.push(stepEvent);
                     // If execution had error, add observation
                     if (execResult.error) {
@@ -307,8 +465,8 @@ class KevePageAgent {
                     if (actionName === 'done') {
                         // Capture done-time screenshot as goal-after evidence
                         try {
-                            const doneBuf = await this.page.screenshot({ type: 'png', timeout: 15000 });
-                            stepEvent.screenshotPath = this.saveScreenshotBuffer(doneBuf, stepCount, step);
+                            const doneShot = await this.page.screenshot({ type: 'png', timeout: 15000 });
+                            stepEvent.screenshotPath = await this.saveScreenshotBuffer(doneShot.base64, stepCount, step);
                         }
                         catch { /* non-critical */ }
                         // Extract conclusion: 4-level backoff
@@ -441,6 +599,12 @@ class KevePageAgent {
             }
         }
         finally {
+            // 页面级性能只能在用例收敛后读一次（LCP/longtask 需要缓冲已完成）
+            await this.capturePageMetrics();
+            if (taskResult) {
+                // 用完整诊断（含页面性能）覆盖此前构建的结果
+                taskResult.diagnostics = this.buildDiagnostics();
+            }
             // ── onAfterTask hook — may return partial overrides ──
             const hookResult = await hooks?.onAfterTask?.(this, taskResult);
             if (hookResult && taskResult) {
@@ -453,6 +617,75 @@ class KevePageAgent {
     pushObservation(content) {
         this.events.push({ type: 'observation', content });
     }
+    /**
+     * 读取页面级性能指标。
+     *
+     * Playwright 与 Cypress 都走同一段探针源码：Playwright 在真实页面上下文，
+     * Cypress 在 AUT 的 isolated world（navigation timing / performance entries
+     * 与主世界共享同一份 Performance 数据）。
+     */
+    async capturePageMetrics() {
+        try {
+            const raw = await this.page.evaluate((0, diagnostics_js_1.pagePerformanceProbeSource)());
+            if (raw && typeof raw === 'object') {
+                this._lastPageMetrics = raw;
+            }
+        }
+        catch {
+            // 性能指标是增强信息，读取失败不影响用例结论
+        }
+    }
+    /**
+     * 汇总当前执行期的运行诊断（含页面性能与质量信号）。
+     * 公开给 reactLoop 的异常兜底分支复用，避免中断时丢失已采集数据。
+     */
+    buildDiagnostics() {
+        const stepEvents = this.events.filter((e) => e.type === 'step');
+        const actionRecords = stepEvents.map(e => ({
+            name: e.toolName || 'unknown',
+            durationMs: e.duration,
+            error: !!e.toolError,
+        }));
+        // 重复动作：连续两个以上步骤产生相同工具输出时，累计重复次数。
+        let repeatedActionCount = 0;
+        let repeatRun = 0;
+        let prevOutput = '';
+        for (const event of stepEvents) {
+            const output = String(event.toolOutput || '').slice(0, 200);
+            if (output && output === prevOutput)
+                repeatRun += 1;
+            else
+                repeatRun = 0;
+            repeatedActionCount += repeatRun;
+            prevOutput = output;
+        }
+        return (0, diagnostics_js_1.buildRuntimeDiagnostics)({
+            totalMs: this._executeStartedAt ? Date.now() - this._executeStartedAt : 0,
+            aiReasoningMs: this._aiReasoningMs,
+            actionMs: this._actionMs,
+            actions: actionRecords,
+            consoleRecords: this._browserDiagnostics,
+            networkRecords: this._networkDiagnostics,
+            repeatedActionCount,
+            pageMetrics: this._lastPageMetrics,
+            aiUsage: this._aiUsage,
+        });
+    }
+    /** 累加单次 LLM 调用的 token 用量（重试中的失败请求不在返回结果里，无法计量） */
+    recordAiUsage(usage) {
+        if (!usage)
+            return;
+        this._aiUsage.llmCalls = (this._aiUsage.llmCalls || 0) + 1;
+        this._aiUsage.promptTokens = (this._aiUsage.promptTokens || 0) + (usage.promptTokens || 0);
+        this._aiUsage.completionTokens = (this._aiUsage.completionTokens || 0) + (usage.completionTokens || 0);
+        this._aiUsage.totalTokens = (this._aiUsage.totalTokens || 0) + (usage.totalTokens || 0);
+        if (usage.cachedTokens !== undefined) {
+            this._aiUsage.cachedTokens = (this._aiUsage.cachedTokens || 0) + usage.cachedTokens;
+        }
+        if (usage.reasoningTokens !== undefined) {
+            this._aiUsage.reasoningTokens = (this._aiUsage.reasoningTokens || 0) + usage.reasoningTokens;
+        }
+    }
     assembleUserPrompt(step, expected, snapshot, url, stepIndex, maxSteps) {
         let prompt = '';
         // <agent_state>
@@ -522,7 +755,7 @@ class KevePageAgent {
         return prompt;
     }
     buildMacroTool() {
-        const schema = (0, tools_1.packMacroToolSchema)();
+        const schema = (0, tools_js_1.packMacroToolSchema)();
         const signal = this.abortController.signal;
         return {
             AgentOutput: {
@@ -531,12 +764,12 @@ class KevePageAgent {
                 execute: async (input) => {
                     signal.throwIfAborted();
                     const toolName = String(input.tool || 'done');
-                    const toolDef = tools_1.tools.get(toolName);
+                    const toolDef = tools_js_1.tools.get(toolName);
                     if (!toolDef) {
                         return { toolName, output: '', error: `Unknown tool: ${toolName}` };
                     }
                     // Extract only the fields this tool needs from the flat input
-                    const shape = (0, tools_1.getZodShape)(toolDef.inputSchema);
+                    const shape = (0, tools_js_1.getZodShape)(toolDef.inputSchema);
                     const toolInput = {};
                     for (const key of Object.keys(shape)) {
                         if (input[key] !== undefined) {
@@ -559,35 +792,34 @@ class KevePageAgent {
             },
         };
     }
-    /** Save screenshot buffer to test artifacts (reuses already-captured buffer) */
-    saveScreenshotBuffer(buf, stepIndex, stepName) {
-        const taskDir = process.env.KEVE_TASK_DIR || '.keve';
-        const round = process.env.KEVE_ROUND || 'latest';
-        const screenshotsDir = path.join(taskDir, 'test-artifacts', `round-${round}`, 'screenshots');
-        fs.mkdirSync(screenshotsDir, { recursive: true });
-        const safeName = stepName.replace(/[^a-zA-Z0-9\u4e00-\u9fff]/g, '_').slice(0, 30);
-        const file = path.join(screenshotsDir, `agent-step${stepIndex}-${safeName}-${Date.now()}.png`);
-        fs.writeFileSync(file, buf);
-        return path.relative(taskDir, file);
+    /**
+     * Save screenshot base64 to test artifacts.
+     *
+     * 落盘能力由宿主注入：Playwright 侧写本地文件系统，Cypress 侧经 HTTP 桥落盘。
+     */
+    async saveScreenshotBuffer(pngBase64, stepIndex, stepName) {
+        if (!this.saveScreenshotFn)
+            return undefined;
+        try {
+            return await this.saveScreenshotFn(pngBase64, stepIndex, stepName);
+        }
+        catch {
+            return undefined;
+        }
     }
     /** Load initial screenshots (goal-before + fn-after) as ContentItem[] for step 0 multimodal input */
-    loadInitialScreenshots(options) {
-        const items = [];
-        const taskDir = process.env.KEVE_TASK_DIR || '.keve';
-        for (const relPath of [options?.goalScreenshotBefore, options?.fnAfterScreenshot]) {
-            if (!relPath)
-                continue;
-            try {
-                const absPath = path.resolve(taskDir, relPath);
-                const buf = fs.readFileSync(absPath);
-                items.push({
-                    type: 'image_url',
-                    image_url: { url: `data:image/png;base64,${buf.toString('base64')}`, detail: 'high' },
-                });
-            }
-            catch { /* non-critical */ }
+    async loadInitialScreenshots(options) {
+        if (!this.loadInitialImagesFn)
+            return [];
+        try {
+            return (await this.loadInitialImagesFn({
+                goalScreenshotBefore: options?.goalScreenshotBefore,
+                fnAfterScreenshot: options?.fnAfterScreenshot,
+            }));
+        }
+        catch {
+            return [];
         }
-        return items;
     }
     /**
      * Visual element location: uses LLM multimodal to identify element bbox in screenshot.
@@ -627,6 +859,7 @@ IMPORTANT: Respond in Chinese.`,
                     execute: async (args) => args,
                 },
             }, this.abortController.signal, { toolChoiceName: 'LocateResult' });
+            this.recordAiUsage(result.usage);
             const parsed = result.toolCall.args;
             const bbox = parsed.bbox || [];
             if (bbox.length === 4 && bbox.every(v => typeof v === 'number' && !isNaN(v) && v >= 0 && v <= 1000) && bbox[2] > bbox[0] && bbox[3] > bbox[1]) {
@@ -674,6 +907,7 @@ IMPORTANT:
                     execute: async (args) => args,
                 },
             }, this.abortController.signal, { toolChoiceName: 'AssertResult' });
+            this.recordAiUsage(result.usage);
             const parsed = result.toolCall.args;
             return {
                 passed: typeof parsed.passed === 'boolean' ? parsed.passed : false,
@@ -695,7 +929,16 @@ IMPORTANT:
             .filter((e) => e.type === 'step')
             .filter(e => e.screenshotPath)
             .map(e => e.screenshotPath);
-        return { success, data, events: this.events, finalSnapshot: snapshot, /* refinePatch, */ agentScreenshots: screenshotPaths.length ? screenshotPaths : undefined };
+        const diagnostics = this.buildDiagnostics();
+        return {
+            success,
+            data,
+            events: this.events,
+            finalSnapshot: snapshot,
+            diagnostics,
+            /* refinePatch, */
+            agentScreenshots: screenshotPaths.length ? screenshotPaths : undefined,
+        };
     }
 }
 exports.KevePageAgent = KevePageAgent;
@@ -704,16 +947,25 @@ exports.KevePageAgent = KevePageAgent;
  * Drop-in replacement for the old reactLoop function.
  * Creates a KevePageAgent, runs it, and maps the result.
  */
-async function reactLoop(page, step, expected, options = {}) {
-    const agent = new KevePageAgent(page, {
+async function reactLoop(
+// 接受原生 Playwright Page 或任意 AgentPage 实现（用 toAgentPage 的参数类型
+// 表达，避免在浏览器安全模块里引入 @playwright/test 的类型依赖）
+page, step, expected, options = {}) {
+    const agent = new KevePageAgent((0, playwright_page_js_1.toAgentPage)(page), {
         maxSteps: options.maxSteps ?? 20,
+        systemPrompt: options.systemPrompt,
+        targetUrl: options.targetUrl,
+        getEnv: options.getEnv,
+        saveScreenshot: options.saveScreenshot,
+        loadInitialImages: options.loadInitialImages,
+        llm: options.llm,
         hooks: {
             onAfterTask: async (_agent, result) => {
                 const partial = {};
                 // 1. Diagnostic hints for failures
                 if (!result.success) {
                     try {
-                        partial.diagnosticHints = await (0, hooks_1.extractDiagnosticHints)(_agent.page, result);
+                        partial.diagnosticHints = await (0, hooks_js_1.extractDiagnosticHints)(_agent.page, result);
                     }
                     catch { /* non-critical */ }
                 }
@@ -765,6 +1017,7 @@ async function reactLoop(page, step, expected, options = {}) {
             stepCount: partialEvents.length,
             finalSnapshot: '',
             events: agent.events,
+            diagnostics: agent.buildDiagnostics(),
             agentScreenshots: agent.events
                 .filter((e) => e.type === 'step')
                 .filter(e => e.screenshotPath)
@@ -791,6 +1044,7 @@ async function reactLoop(page, step, expected, options = {}) {
         expectedMet: result.success,
         conclusion: result.conclusion,
         finalSnapshot: result.finalSnapshot,
+        diagnostics: result.diagnostics,
         // refinePatch: result.refinePatch, // 已注释：scriptRefine 已禁用
         agentScreenshots: result.agentScreenshots,
     };