@kkeve/suite 0.0.6 → 0.0.9

package/dist/config.js

@@ -71,7 +71,7 @@ const DEFAULT_CONFIG = {
         timeout_ms: 1200000,
         retries: 0,
         reporter: 'json',
-        screenshot: 'only-on-failure',
+        screenshot: 'off',
     },
 };
 /**

package/dist/core/generateReport/reportData.d.ts

@@ -97,6 +97,8 @@ export interface StepReportItem {
     precondition?: string;
     order?: number;
     success?: boolean;
+    /** fn 执行前截图路径（goal-before，页面原始状态） */
+    goalScreenshotBefore?: string;
     /** 目标结果截图路径（keveGoal 执行后截图，来自 goalScreenshotPath / goalScreenshotAfter） */
     goalScreenshotPath?: string;
     /** 验证截图路径列表（agent 每步操作后截图，来自 verifyScreenshots / agentScreenshots） */

package/dist/core/generateReport/reportData.js

@@ -564,6 +564,7 @@ async function generateReportData(opts) {
                     order: s.order,
                     success: s.success,
                     conclusion: s.conclusion,
+                    goalScreenshotBefore: s.goalScreenshotBefore,
                     goalScreenshotPath: s.goalScreenshotPath || s.goalScreenshotAfter,
                     verifyScreenshots: s.verifyScreenshots || s.agentScreenshots,
                     actions: (s.actions || []).map((a) => ({

package/dist/core/keve-aspect.d.ts

@@ -4,13 +4,11 @@
  * Three phases: before → (goal body or rescue) → after
  * User-invisible: aspects are registered by the framework, not by test authors.
  *
- * Built-in aspects:
- * - screenshot-on-enter (before, order=10) — capture screenshot before goal
- * - react-rescue (rescue, order=0) — Re-Act loop when fn() throws
- * - expected-check (after, order=0) — verify expected state via aiAssert
- * - action-log-write (after, order=10) — append to action-log.jsonl
- * - learnedActions-update (after, order=20) — update in-memory cache
- * - screenshot-on-fail (after, order=30) — capture screenshot on failure
+ * Registered aspects:
+ * - learnedActions-update (after, order=20) — update in-memory cache on success
+ *
+ * 截图由 keveGoal 内部直接管理（goal-before / goal-after / agent 每步截图），
+ * 不通过 aspect 注册，避免截图时机与 agent 执行步骤脱节。
  */
 export type AspectPhase = 'before' | 'rescue' | 'after';
 export interface GoalContext {

package/dist/core/keve-aspect.js

@@ -5,13 +5,11 @@
  * Three phases: before → (goal body or rescue) → after
  * User-invisible: aspects are registered by the framework, not by test authors.
  *
- * Built-in aspects:
- * - screenshot-on-enter (before, order=10) — capture screenshot before goal
- * - react-rescue (rescue, order=0) — Re-Act loop when fn() throws
- * - expected-check (after, order=0) — verify expected state via aiAssert
- * - action-log-write (after, order=10) — append to action-log.jsonl
- * - learnedActions-update (after, order=20) — update in-memory cache
- * - screenshot-on-fail (after, order=30) — capture screenshot on failure
+ * Registered aspects:
+ * - learnedActions-update (after, order=20) — update in-memory cache on success
+ *
+ * 截图由 keveGoal 内部直接管理（goal-before / goal-after / agent 每步截图），
+ * 不通过 aspect 注册，避免截图时机与 agent 执行步骤脱节。
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.keveAspect = exports.KeveAspectRegistry = void 0;

package/dist/core/keve-test.js

@@ -160,6 +160,13 @@ exports.test = test_1.test.extend({
             };
             // Run before aspects
             await keve_aspect_1.keveAspect.runPhase('before', ctx);
+            // ── Capture goal-before screenshot (fn 之前的页面原始状态) ──
+            // 语义：记录"测试动作发生前"的页面，供报告 before/after 对照
+            let goalScreenshotBefore = '';
+            try {
+                goalScreenshotBefore = await captureScreenshot(page, options.step, goalMeta.order, 'before');
+            }
+            catch { /* non-critical */ }
             let result;
             const fnSource = fn?.toString() || undefined;
             let fnError;
@@ -173,27 +180,21 @@ exports.test = test_1.test.extend({
                     console.log(`[keveGoal] "${options.step}" fn error: ${fnError}`);
                 }
             }
-            // ── Capture "before" screenshot (page state before agent starts) ──
-            let goalScreenshotBefore = '';
-            try {
-                const buf = await page.screenshot({ type: 'png', timeout: 15000 });
-                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 = options.step.replace(/[^a-zA-Z0-9\u4e00-\u9fff]/g, '_').slice(0, 30);
-                const file = path.join(screenshotsDir, `goal-before-${goalMeta.order}-${safeName}-${Date.now()}.png`);
-                fs.writeFileSync(file, buf);
-                goalScreenshotBefore = path.relative(taskDir, file);
+            // ── Capture fn-after screenshot (fn 执行后的页面状态，传给 agent 说明执行前后) ──
+            let fnAfterScreenshot = '';
+            if (fn) {
+                try {
+                    fnAfterScreenshot = await captureScreenshot(page, options.step, goalMeta.order, 'after-fn');
+                }
+                catch { /* non-critical */ }
             }
-            catch { /* non-critical */ }
             // ── Hand off to agent: agent does Re-Act ──
             const learnedHint = learned_actions_1.learnedActions.getHint(options.step);
             let reactResult;
             let reactTimedOut = false;
             // ── Per-goal timeout: prevent one slow goal from exhausting the test timeout ──
-            // Default 120s per goal; total test timeout should be ≥ (goals × 120s + overhead)
-            const GOAL_TIMEOUT_MS = 120_000;
+            // Default 300s per goal; total test timeout should be ≥ (goals × 300s + overhead)
+            const GOAL_TIMEOUT_MS = 300_000;
             const goalTimeoutController = new AbortController();
             const goalTimeout = setTimeout(() => {
                 goalTimeoutController.abort();
@@ -206,6 +207,8 @@ exports.test = test_1.test.extend({
                     fnSource,
                     fnResult: fnError ? { error: fnError } : { success: true },
                     signal: goalTimeoutController.signal,
+                    goalScreenshotBefore: goalScreenshotBefore || undefined,
+                    fnAfterScreenshot: fnAfterScreenshot || undefined,
                 });
             }
             catch (reactErr) {
@@ -250,22 +253,19 @@ exports.test = test_1.test.extend({
             // 通过 Playwright attachment 流到 KeveReporter.onTestEnd
             // 注意：screenshotBase64 不再写入 attachment（截图已保存到文件系统，路径见 goalScreenshotBefore/goalScreenshotAfter）
             const diagnosticHints = reactResult.diagnosticHints || [];
+            // ── goalScreenshotAfter = agent done 时的截图（done-time screenshot） ──
+            // agent.ts 在 done 工具触发时截图并写入 stepEvent.screenshotPath，
+            // 这里复用该路径作为 goal-after 证据（与 agent 判定时刻一致，避免状态漂移）。
             let goalScreenshotAfter = '';
             try {
-                const buf = await page.screenshot({ type: 'png', timeout: 15000 });
-                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 = options.step.replace(/[^a-zA-Z0-9\u4e00-\u9fff]/g, '_').slice(0, 30);
-                const file = path.join(screenshotsDir, `goal-after-${goalMeta.order}-${safeName}-${Date.now()}.png`);
-                fs.writeFileSync(file, buf);
-                goalScreenshotAfter = path.relative(taskDir, file);
-                console.log(`[keveGoal] screenshot captured: ${buf.length} bytes (path: ${goalScreenshotAfter})`);
-            }
-            catch (e) {
-                console.log(`[keveGoal] screenshot failed: ${e.message}`);
+                const lastActionWithShot = [...(reactResult.actions || [])]
+                    .reverse()
+                    .find((a) => a.screenshotPath);
+                if (lastActionWithShot?.screenshotPath) {
+                    goalScreenshotAfter = lastActionWithShot.screenshotPath;
+                }
             }
+            catch { /* non-critical */ }
             await testInfo.attach('keveGoalResult', {
                 contentType: 'application/json',
                 body: Buffer.from(JSON.stringify({
@@ -362,3 +362,19 @@ exports.test = test_1.test.extend({
 // Register extended test with keve-decorators so @keveModel uses the correct test
 const keve_decorators_2 = require("./keve-decorators");
 (0, keve_decorators_2.setKeveTest)(exports.test);
+// ── 辅助函数 ──
+/**
+ * 截图并保存到 test-artifacts，返回相对 taskDir 的路径
+ * @param phase 'before' | 'after-fn' — 用于文件名前缀
+ */
+async function captureScreenshot(page, stepName, order, phase) {
+    const buf = await page.screenshot({ type: 'png', timeout: 15000 });
+    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一-鿿]/g, '_').slice(0, 30);
+    const file = path.join(screenshotsDir, `goal-${phase}-${order}-${safeName}-${Date.now()}.png`);
+    fs.writeFileSync(file, buf);
+    return path.relative(taskDir, file);
+}

package/dist/core/pw-config.js

@@ -88,7 +88,7 @@ export default defineConfig({
   use: {
     baseURL: ${baseURLLine},${cdp ? `\n    // CDP mode: login state preserved via connected Chrome` : `\n    storageState: path.resolve(projectRoot, '.auth/storage-state.json'),`}
     trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
+    screenshot: 'off',
     video: 'retain-on-failure',
     actionTimeout: 5000,${cdpBlock}
   },
@@ -136,7 +136,7 @@ export default defineConfig({
   use: {
     baseURL: ${baseURLLine},${cdp ? `\n    // CDP mode: login state preserved via connected Chrome` : `\n    storageState: resolve(projectRoot, '.auth', 'storage-state.json'),`}
     trace: 'on-first-retry',
-    screenshot: 'only-on-failure',
+    screenshot: 'off',
     video: 'retain-on-failure',
     actionTimeout: 5000,${cdpBlock}
   },

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

@@ -6,8 +6,10 @@
  *   - MacroTool: merge all tool schemas into one LLM output
  *   - History events: step/observation/error stream
  *   - Reflection-before-action: evaluation + memory + next_goal + action
- *   - Screenshot injected into LLM prompt as multimodal input — LLM self-evaluates visually
- *   - No external verification — LLM sees screenshot each step, judges goal state itself
+ *   - Per-step: ariaSnapshot text only (no screenshot) — Option C
+ *   - Initial screenshots (goal-before + fn-after) injected on step 0 as multimodal context
+ *   - Done-time screenshot captured as goal-after evidence
+ *   - On-demand screenshots via visual_locate tool (when element needs visual identification)
  *
  * Usage:
  *   const agent = new KevePageAgent(page, { maxSteps: 5 });
@@ -68,6 +70,10 @@ export interface AgentOptions {
     hooks?: AgentHooks;
     /** External abort signal (e.g. per-goal timeout). When aborted, internal abortController is also triggered. */
     signal?: AbortSignal;
+    /** goal-before 截图路径（相对 taskDir）— fn 执行前的页面原始状态 */
+    goalScreenshotBefore?: string;
+    /** fn-after 截图路径（相对 taskDir）— fn 执行后的页面状态 */
+    fnAfterScreenshot?: string;
 }
 export declare class KevePageAgent {
     readonly page: Page;
@@ -93,6 +99,8 @@ export declare class KevePageAgent {
     private buildMacroTool;
     /** Save screenshot buffer to test artifacts (reuses already-captured buffer) */
     private saveScreenshotBuffer;
+    /** Load initial screenshots (goal-before + fn-after) as ContentItem[] for step 0 multimodal input */
+    private loadInitialScreenshots;
     /**
      * Visual element location: uses LLM multimodal to identify element bbox in screenshot.
      * Returns normalized bbox (0-1000 scale) for coordinate-based clicking.
@@ -120,6 +128,8 @@ export declare function reactLoop(page: Page, step: string, expected: string, op
         success?: boolean;
     };
     signal?: AbortSignal;
+    goalScreenshotBefore?: string;
+    fnAfterScreenshot?: string;
 }): Promise<{
     actions: any[];
     expectedMet: boolean;

package/dist/page-agent/agent.js

@@ -7,8 +7,10 @@
  *   - MacroTool: merge all tool schemas into one LLM output
  *   - History events: step/observation/error stream
  *   - Reflection-before-action: evaluation + memory + next_goal + action
- *   - Screenshot injected into LLM prompt as multimodal input — LLM self-evaluates visually
- *   - No external verification — LLM sees screenshot each step, judges goal state itself
+ *   - Per-step: ariaSnapshot text only (no screenshot) — Option C
+ *   - Initial screenshots (goal-before + fn-after) injected on step 0 as multimodal context
+ *   - Done-time screenshot captured as goal-after evidence
+ *   - On-demand screenshots via visual_locate tool (when element needs visual identification)
  *
  * Usage:
  *   const agent = new KevePageAgent(page, { maxSteps: 5 });
@@ -133,37 +135,19 @@ class KevePageAgent {
                 await hooks?.onBeforeStep?.(this, stepCount);
                 try {
                     console.group(`step: ${stepCount}`);
-                    // ── Observe: get browser state ──
+                    // ── 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();
                     console.log(`  url: ${url.slice(0, 120)} | step ${stepCount + 1}/${maxSteps}`);
-                    // ── Capture screenshot (used for both LLM multimodal input and artifact save) ──
-                    let screenshotBuf;
-                    let screenshotBase64;
-                    try {
-                        screenshotBuf = await this.page.screenshot({ type: 'png', timeout: 10000 });
-                        screenshotBase64 = screenshotBuf.toString('base64');
-                    }
-                    catch (e) {
-                        // Retry once with longer timeout (font loading can be slow on some pages)
-                        try {
-                            await new Promise(r => setTimeout(r, 500));
-                            screenshotBuf = await this.page.screenshot({ type: 'png', timeout: 15000 });
-                            screenshotBase64 = screenshotBuf.toString('base64');
-                        }
-                        catch (e2) {
-                            console.log(`[agent] screenshot capture failed (non-critical): ${e2.message}`);
-                        }
-                    }
-                    // ── Assemble messages (multimodal: text + screenshot) ──
-                    const userText = this.assembleUserPrompt(step, expected, snapshot, url, stepCount, maxSteps, !!screenshotBase64);
+                    // ── Assemble messages (text-only per step; initial screenshots on step 0) ──
+                    const userText = this.assembleUserPrompt(step, expected, snapshot, url, stepCount, maxSteps);
                     let userContent;
-                    if (screenshotBase64) {
-                        userContent = [
-                            { type: 'text', text: userText },
-                            { type: 'image_url', image_url: { url: `data:image/png;base64,${screenshotBase64}`, detail: 'high' } },
-                        ];
+                    if (stepCount === 0) {
+                        const initialImages = this.loadInitialScreenshots(options);
+                        userContent = initialImages.length > 0
+                            ? [{ type: 'text', text: userText }, ...initialImages]
+                            : userText;
                     }
                     else {
                         userContent = userText;
@@ -192,15 +176,7 @@ class KevePageAgent {
                         console.log(`🎯: ${reflection.nextGoal.slice(0, 150)}`);
                     const actionName = execResult.toolName;
                     const actionInput = macroInput;
-                    // Save screenshot (reuse buffer already captured for LLM)
-                    let screenshotPath;
-                    if (screenshotBuf) {
-                        try {
-                            screenshotPath = this.saveScreenshotBuffer(screenshotBuf, stepCount, step);
-                        }
-                        catch { /* non-critical */ }
-                    }
-                    // Record step event
+                    // Record step event (screenshotPath set later for done actions)
                     if (execResult.error) {
                         console.log(`\x1b[31m\x1b[1m${actionName} (error: ${execResult.error.slice(0, 80)})\x1b[0m`);
                     }
@@ -221,15 +197,21 @@ class KevePageAgent {
                         toolOutput: execResult.output,
                         toolError: execResult.error,
                         snapshot,
-                        screenshotPath,
+                        screenshotPath: undefined,
                     };
                     this.events.push(stepEvent);
                     // If execution had error, add observation
                     if (execResult.error) {
                         this.pushObservation(`Action "${actionName}" failed: ${execResult.error}. Try a different approach.`);
                     }
-                    // ── Check: if "done", return directly with test conclusion ──
+                    // ── Check: if "done", capture done-time screenshot + return with test conclusion ──
                     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);
+                        }
+                        catch { /* non-critical */ }
                         // Extract conclusion: 4-level backoff
                         let conclusion;
                         const verdictField = actionInput?.verdict;
@@ -325,7 +307,7 @@ class KevePageAgent {
     pushObservation(content) {
         this.events.push({ type: 'observation', content });
     }
-    assembleUserPrompt(step, expected, snapshot, url, stepIndex, maxSteps, hasScreenshot) {
+    assembleUserPrompt(step, expected, snapshot, url, stepIndex, maxSteps) {
         let prompt = '';
         // <agent_state>
         prompt += '<agent_state>\n';
@@ -343,6 +325,18 @@ class KevePageAgent {
                 : '';
             prompt += `<prior_execution>\nA deterministic script was executed BEFORE your Re-Act loop.\n${resultLine}${sourceLine}\n</prior_execution>\n`;
         }
+        // <initial_screenshots>: only on first step, describe the before/after fn screenshots
+        if (stepIndex === 0 && (this.options?.goalScreenshotBefore || this.options?.fnAfterScreenshot)) {
+            prompt += '<initial_screenshots>\n';
+            if (this.options?.goalScreenshotBefore) {
+                prompt += 'goal-before: Screenshot of the page state BEFORE any test action (fn执行前的页面原始状态).\n';
+            }
+            if (this.options?.fnAfterScreenshot) {
+                prompt += 'fn-after: Screenshot of the page state AFTER the deterministic fn script executed (fn执行后的页面状态). Compare with goal-before to understand what fn changed.\n';
+            }
+            prompt += 'These screenshots are attached as images to give you visual context of the pre/post fn execution state. Use them to understand what fn did, then rely on the accessibility tree (ariaSnapshot) for per-step decisions.\n';
+            prompt += '</initial_screenshots>\n';
+        }
         prompt += '<step_info>\n';
         prompt += `Step ${stepIndex + 1} of ${maxSteps} max steps\n`;
         prompt += `Current URL: ${url}\n`;
@@ -370,9 +364,6 @@ class KevePageAgent {
         prompt += '<browser_state>\n';
         prompt += `Current URL: ${url}\n\n`;
         prompt += `Accessibility Tree (YAML):\n\`\`\`yaml\n${snapshot}\n\`\`\`\n`;
-        if (hasScreenshot) {
-            prompt += '\n<page_screenshot>\nA screenshot of the current page is provided as an image attached to this message. Use it as the primary visual source of truth for what is actually visible on the page. Cross-reference the screenshot with the accessibility tree to make accurate judgments — especially before calling done(success=true) to verify the expected state is truly achieved.\n</page_screenshot>\n';
-        }
         prompt += '</browser_state>\n\n';
         return prompt;
     }
@@ -425,6 +416,25 @@ class KevePageAgent {
         fs.writeFileSync(file, buf);
         return path.relative(taskDir, file);
     }
+    /** 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 */ }
+        }
+        return items;
+    }
     /**
      * Visual element location: uses LLM multimodal to identify element bbox in screenshot.
      * Returns normalized bbox (0-1000 scale) for coordinate-based clicking.
@@ -541,6 +551,8 @@ async function reactLoop(page, step, expected, options = {}) {
             fnSource: options.fnSource,
             fnResult: options.fnResult,
             signal: options.signal,
+            goalScreenshotBefore: options.goalScreenshotBefore,
+            fnAfterScreenshot: options.fnAfterScreenshot,
         });
     }
     catch (execErr) {

package/dist/page-agent/system_prompt.md

@@ -126,14 +126,20 @@ You must call the `done` action in one of these cases:
 The `done` action requires two fields:
 - `verdict`: Your test verdict, must be one of:
   - `"pass"`: The expected state described in <user_request> is fully achieved. Examine the screenshot carefully before deciding.
-  - `"fail"`: The page is accessible but the expected state is NOT achieved (e.g. text mismatch, wrong element state, visual difference).
-  - `"blocked"`: Cannot continue testing (e.g. SSO login redirect, connection refused, page not loading).
+  - `"fail"`: The page is accessible but the expected state is NOT achieved (e.g. text mismatch, wrong element state, visual difference). This indicates a **code defect**.
+  - `"blocked"`: Cannot continue testing. This covers BOTH environment issues (e.g. SSO login redirect, connection refused, page not loading) **AND permission-denied / no-access states** (e.g. page shows "您没有...编辑权限", "无访问权限", "暂无数据", "申请体验权限") where the **test account lacks the required access**. A permission-denied page is a **precondition issue**, not a code defect — use `"blocked"`, NOT `"fail"`.
+
+**Permission-denied → blocked (critical rule):**
+When the screenshot or accessibility tree shows a permission-denied / no-access message (e.g. "您没有数据知识库[...]的编辑权限", "无访问权限", "暂无数据", "申请体验权限"), this means the **test account does not have the required permission for the target resource**. This is a precondition issue, NOT an application bug.
+- Call `done(verdict="blocked")` immediately with the permission message in `text`.
+- Do NOT call `done(verdict="fail")` — the application is correctly enforcing access control, the code is NOT defective.
+- Do NOT try to navigate away to find another resource or "work around" the permission issue — the test must verify the **target resource specified in the precondition**, not a substitute.
 - `text`: Describe what you observed and why you reached this conclusion.
 
 Important:
 - Set `verdict` to `"pass"` ONLY if the expected state is fully achieved. Be honest and rigorous.
 - Set `verdict` to `"fail"` when the page works but does not match the expected state. Describe the mismatch in `text`.
-- Set `verdict` to `"blocked"` when the environment prevents testing (not the application's fault).
+- Set `verdict` to `"blocked"` when the environment prevents testing OR when the page shows a permission-denied / no-access state (test account lacks required access). Not the application's fault.
 - 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.

package/dist/page-agent/tools.js

@@ -22,9 +22,9 @@ function tool(options) {
 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.',
+    description: 'Complete the task with a test conclusion. Use this when the expected state is achieved, not achieved, or you are blocked. When the page shows a permission-denied / no-access message (e.g. "您没有...编辑权限", "无访问权限", "暂无数据") that is NOT caused by an application bug but by the test account lacking the required permission, use verdict="blocked" — this is a precondition issue, not a code defect. Only use verdict="fail" when the page IS accessible/functional but the expected UI state is not met.',
     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.)'),
+        verdict: zod_1.z.enum(['pass', 'fail', 'blocked']).describe('Test verdict: "pass"=expected state achieved; "fail"=page accessible but expected not met (code defect); "blocked"=cannot continue — includes SSO redirect, connection refused, AND permission-denied/no-access pages where the test account lacks the required access (precondition not met, NOT a code defect)'),
         text: zod_1.z.string().describe('Summary of what was achieved, why it failed, or why blocked'),
     }),
     execute: async function (input) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkeve/suite",
-  "version": "0.0.6",
+  "version": "0.0.9",
   "description": "AI-powered full-stack test agent CLI - static analysis, unit test, component test, E2E test, execute, evaluate, and report",
   "license": "MIT",
   "bin": {