gsd-pi 2.33.1 → 2.34.0-dev.6769913

package/dist/resources/extensions/browser-tools/tools/assertions.js

@@ -0,0 +1,320 @@
+import { Type } from "@sinclair/typebox";
+import { StringEnum } from "@gsd/pi-ai";
+import { diffCompactStates, evaluateAssertionChecks, findAction, runBatchSteps, validateWaitParams, createRegionStableScript, parseThreshold, includesNeedle, } from "../core.js";
+import { getConsoleLogs, getCurrentRefMap, getLastActionBeforeState, getLastActionAfterState, setLastActionBeforeState, setLastActionAfterState, getActionTimeline, } from "../state.js";
+export function registerAssertionTools(pi, deps) {
+    // -------------------------------------------------------------------------
+    // browser_assert
+    // -------------------------------------------------------------------------
+    pi.registerTool({
+        name: "browser_assert",
+        label: "Browser Assert",
+        description: "Run one or more explicit browser assertions and return structured PASS/FAIL results. Prefer this for verification instead of inferring success from prose summaries.",
+        promptGuidelines: [
+            "Prefer browser_assert for browser verification instead of inferring success from summaries.",
+            "When finishing UI work, explicit browser assertions should usually be the final verification step.",
+            "Use checks for URL, text, selector state, value, and browser diagnostics whenever those signals are available.",
+        ],
+        parameters: Type.Object({
+            checks: Type.Array(Type.Object({
+                kind: Type.String({ description: "Assertion kind, e.g. url_contains, text_visible, selector_visible, value_equals, no_console_errors, no_failed_requests, request_url_seen, response_status, console_message_matches, network_count, console_count, no_console_errors_since, no_failed_requests_since" }),
+                selector: Type.Optional(Type.String()),
+                text: Type.Optional(Type.String()),
+                value: Type.Optional(Type.String()),
+                checked: Type.Optional(Type.Boolean()),
+                sinceActionId: Type.Optional(Type.Number()),
+            })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            try {
+                const { page: p } = await deps.ensureBrowser();
+                const target = deps.getActiveTarget();
+                const state = await deps.collectAssertionState(p, params.checks, target);
+                const result = evaluateAssertionChecks({ checks: params.checks, state });
+                return {
+                    content: [{ type: "text", text: `Browser assert\n\n${deps.formatAssertionText(result)}` }],
+                    details: { ...result, url: state.url, title: state.title },
+                    isError: !result.verified,
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `Browser assert failed: ${err.message}` }],
+                    details: { error: err.message },
+                    isError: true,
+                };
+            }
+        },
+    });
+    // -------------------------------------------------------------------------
+    // browser_diff
+    // -------------------------------------------------------------------------
+    pi.registerTool({
+        name: "browser_diff",
+        label: "Browser Diff",
+        description: "Report meaningful browser-state changes. By default compares the current page to the most recent tracked action state. Use this to understand what changed after a click, submit, or navigation.",
+        promptGuidelines: [
+            "Use browser_diff after ambiguous or high-impact actions when you need to know what changed.",
+            "Prefer browser_diff over requesting a broad new page inspection when the question is change detection.",
+        ],
+        parameters: Type.Object({
+            sinceActionId: Type.Optional(Type.Number({ description: "Optional action id to diff against. Uses that action's stored after-state when available." })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            try {
+                const { page: p } = await deps.ensureBrowser();
+                const target = deps.getActiveTarget();
+                const current = await deps.captureCompactPageState(p, { includeBodyText: true, target });
+                let baseline = null;
+                if (params.sinceActionId) {
+                    const actionTimeline = getActionTimeline();
+                    const action = findAction(actionTimeline, params.sinceActionId);
+                    baseline = action?.afterState ?? null;
+                }
+                if (!baseline) {
+                    baseline = getLastActionAfterState() ?? getLastActionBeforeState();
+                }
+                if (!baseline) {
+                    return {
+                        content: [{ type: "text", text: "Browser diff unavailable: no prior tracked browser state exists yet." }],
+                        details: { changed: false, changes: [], summary: "No prior tracked state" },
+                        isError: true,
+                    };
+                }
+                const diff = diffCompactStates(baseline, current);
+                return {
+                    content: [{ type: "text", text: `Browser diff\n\n${deps.formatDiffText(diff)}` }],
+                    details: diff,
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `Browser diff failed: ${err.message}` }],
+                    details: { error: err.message },
+                    isError: true,
+                };
+            }
+        },
+    });
+    // -------------------------------------------------------------------------
+    // browser_batch
+    // -------------------------------------------------------------------------
+    pi.registerTool({
+        name: "browser_batch",
+        label: "Browser Batch",
+        description: "Execute multiple explicit browser steps in one call. Prefer this for obvious action sequences like click → type → wait → assert to reduce round trips and token usage.",
+        promptGuidelines: [
+            "If the next 2-5 browser actions are obvious and low-risk, prefer browser_batch over multiple tiny browser calls.",
+            "Use browser_batch for explicit sequences like click → type → submit → wait → assert.",
+            "Keep browser_batch steps explicit; do not use it as a speculative planner.",
+        ],
+        parameters: Type.Object({
+            steps: Type.Array(Type.Object({
+                action: StringEnum(["navigate", "click", "type", "key_press", "wait_for", "assert", "click_ref", "fill_ref"]),
+                selector: Type.Optional(Type.String()),
+                text: Type.Optional(Type.String()),
+                url: Type.Optional(Type.String()),
+                key: Type.Optional(Type.String()),
+                condition: Type.Optional(Type.String()),
+                value: Type.Optional(Type.String()),
+                threshold: Type.Optional(Type.String()),
+                timeout: Type.Optional(Type.Number()),
+                clearFirst: Type.Optional(Type.Boolean()),
+                submit: Type.Optional(Type.Boolean()),
+                ref: Type.Optional(Type.String()),
+                checks: Type.Optional(Type.Array(Type.Object({
+                    kind: Type.String({ description: "Assertion kind, e.g. url_contains, text_visible, selector_visible, value_equals, no_console_errors, no_failed_requests, request_url_seen, response_status, console_message_matches, network_count, console_count, no_console_errors_since, no_failed_requests_since" }),
+                    selector: Type.Optional(Type.String()),
+                    text: Type.Optional(Type.String()),
+                    value: Type.Optional(Type.String()),
+                    checked: Type.Optional(Type.Boolean()),
+                    sinceActionId: Type.Optional(Type.Number()),
+                }))),
+            })),
+            stopOnFailure: Type.Optional(Type.Boolean({ description: "Stop after the first failing step (default: true)." })),
+            finalSummaryOnly: Type.Optional(Type.Boolean({ description: "Return only the compact final batch summary in content while keeping step results in details." })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            let actionId = null;
+            let beforeState = null;
+            try {
+                const { page: p } = await deps.ensureBrowser();
+                const target = deps.getActiveTarget();
+                beforeState = await deps.captureCompactPageState(p, { includeBodyText: true, target });
+                actionId = deps.beginTrackedAction("browser_batch", params, beforeState.url).id;
+                const executeStep = async (step, index) => {
+                    const stepTarget = deps.getActiveTarget();
+                    try {
+                        switch (step.action) {
+                            case "navigate": {
+                                await p.goto(step.url, { waitUntil: "domcontentloaded", timeout: 30000 });
+                                await p.waitForLoadState("networkidle", { timeout: 5000 }).catch(() => { });
+                                return { ok: true, action: step.action, url: p.url() };
+                            }
+                            case "click": {
+                                await stepTarget.locator(step.selector).first().click({ timeout: step.timeout ?? 8000 });
+                                await deps.settleAfterActionAdaptive(p);
+                                return { ok: true, action: step.action, selector: step.selector, url: p.url() };
+                            }
+                            case "type": {
+                                if (step.clearFirst) {
+                                    await stepTarget.locator(step.selector).first().fill("");
+                                }
+                                await stepTarget.locator(step.selector).first().fill(step.text ?? "", { timeout: step.timeout ?? 8000 });
+                                if (step.submit)
+                                    await p.keyboard.press("Enter");
+                                await deps.settleAfterActionAdaptive(p);
+                                return { ok: true, action: step.action, selector: step.selector, text: step.text };
+                            }
+                            case "key_press": {
+                                await p.keyboard.press(step.key);
+                                await deps.settleAfterActionAdaptive(p, { checkFocusStability: true });
+                                return { ok: true, action: step.action, key: step.key };
+                            }
+                            case "wait_for": {
+                                const timeout = step.timeout ?? 10000;
+                                const waitValidation = validateWaitParams({ condition: step.condition, value: step.value, threshold: step.threshold });
+                                if (waitValidation)
+                                    throw new Error(waitValidation.error);
+                                if (step.condition === "selector_visible")
+                                    await stepTarget.waitForSelector(step.value, { state: "visible", timeout });
+                                else if (step.condition === "selector_hidden")
+                                    await stepTarget.waitForSelector(step.value, { state: "hidden", timeout });
+                                else if (step.condition === "url_contains")
+                                    await p.waitForURL((url) => url.toString().includes(step.value), { timeout });
+                                else if (step.condition === "network_idle")
+                                    await p.waitForLoadState("networkidle", { timeout });
+                                else if (step.condition === "delay")
+                                    await new Promise((resolve) => setTimeout(resolve, parseInt(step.value ?? "1000", 10)));
+                                else if (step.condition === "text_visible") {
+                                    await stepTarget.waitForFunction((needle) => (document.body?.innerText ?? "").toLowerCase().includes(needle.toLowerCase()), step.value, { timeout });
+                                }
+                                else if (step.condition === "text_hidden") {
+                                    await stepTarget.waitForFunction((needle) => !(document.body?.innerText ?? "").toLowerCase().includes(needle.toLowerCase()), step.value, { timeout });
+                                }
+                                else if (step.condition === "request_completed") {
+                                    await deps.getActivePage().waitForResponse((resp) => resp.url().includes(step.value), { timeout });
+                                }
+                                else if (step.condition === "console_message") {
+                                    const needle = step.value;
+                                    const startTime = Date.now();
+                                    let found = false;
+                                    while (Date.now() - startTime < timeout) {
+                                        if (getConsoleLogs().find((entry) => includesNeedle(entry.text, needle))) {
+                                            found = true;
+                                            break;
+                                        }
+                                        await new Promise((resolve) => setTimeout(resolve, 100));
+                                    }
+                                    if (!found)
+                                        throw new Error(`Timed out waiting for console message matching "${needle}" (${timeout}ms)`);
+                                }
+                                else if (step.condition === "element_count") {
+                                    const threshold = parseThreshold(step.threshold ?? ">=1");
+                                    if (!threshold)
+                                        throw new Error(`element_count threshold is malformed: "${step.threshold}"`);
+                                    const selector = step.value;
+                                    const op = threshold.op;
+                                    const n = threshold.n;
+                                    await stepTarget.waitForFunction(({ selector, op, n }) => {
+                                        const count = document.querySelectorAll(selector).length;
+                                        switch (op) {
+                                            case ">=": return count >= n;
+                                            case "<=": return count <= n;
+                                            case "==": return count === n;
+                                            case ">": return count > n;
+                                            case "<": return count < n;
+                                            default: return false;
+                                        }
+                                    }, { selector, op, n }, { timeout });
+                                }
+                                else if (step.condition === "region_stable") {
+                                    const script = createRegionStableScript(step.value);
+                                    await stepTarget.waitForFunction(script, undefined, { timeout, polling: 200 });
+                                }
+                                else
+                                    throw new Error(`Unsupported wait condition: ${step.condition}`);
+                                return { ok: true, action: step.action, condition: step.condition, value: step.value };
+                            }
+                            case "assert": {
+                                const state = await deps.collectAssertionState(p, step.checks ?? [], stepTarget);
+                                const assertion = evaluateAssertionChecks({ checks: step.checks ?? [], state });
+                                return { ok: assertion.verified, action: step.action, summary: assertion.summary, assertion };
+                            }
+                            case "click_ref": {
+                                const parsedRef = deps.parseRef(step.ref);
+                                const currentRefMap = getCurrentRefMap();
+                                const node = currentRefMap[parsedRef.key];
+                                if (!node)
+                                    throw new Error(`Unknown ref: ${step.ref}`);
+                                const resolved = await deps.resolveRefTarget(stepTarget, node);
+                                if (!resolved.ok)
+                                    throw new Error(resolved.reason);
+                                await stepTarget.locator(resolved.selector).first().click({ timeout: step.timeout ?? 8000 });
+                                await deps.settleAfterActionAdaptive(p);
+                                return { ok: true, action: step.action, ref: step.ref };
+                            }
+                            case "fill_ref": {
+                                const parsedRef = deps.parseRef(step.ref);
+                                const currentRefMap = getCurrentRefMap();
+                                const node = currentRefMap[parsedRef.key];
+                                if (!node)
+                                    throw new Error(`Unknown ref: ${step.ref}`);
+                                const resolved = await deps.resolveRefTarget(stepTarget, node);
+                                if (!resolved.ok)
+                                    throw new Error(resolved.reason);
+                                if (step.clearFirst)
+                                    await stepTarget.locator(resolved.selector).first().fill("");
+                                await stepTarget.locator(resolved.selector).first().fill(step.text ?? "", { timeout: step.timeout ?? 8000 });
+                                if (step.submit)
+                                    await p.keyboard.press("Enter");
+                                await deps.settleAfterActionAdaptive(p);
+                                return { ok: true, action: step.action, ref: step.ref, text: step.text };
+                            }
+                            default:
+                                throw new Error(`Unsupported batch action: ${step.action}`);
+                        }
+                    }
+                    catch (err) {
+                        return { ok: false, action: step.action, index, message: err.message };
+                    }
+                };
+                const run = await runBatchSteps({
+                    steps: params.steps,
+                    executeStep,
+                    stopOnFailure: params.stopOnFailure !== false,
+                });
+                const batchEndTarget = deps.getActiveTarget();
+                const afterState = await deps.captureCompactPageState(p, { includeBodyText: true, target: batchEndTarget });
+                const diff = diffCompactStates(beforeState, afterState);
+                setLastActionBeforeState(beforeState);
+                setLastActionAfterState(afterState);
+                deps.finishTrackedAction(actionId, {
+                    status: run.ok ? "success" : "error",
+                    afterUrl: afterState.url,
+                    diffSummary: diff.summary,
+                    changed: diff.changed,
+                    error: run.ok ? undefined : run.summary,
+                    beforeState: beforeState,
+                    afterState,
+                });
+                const summary = `${run.summary}\n${run.stepResults.map((step, index) => `- ${index + 1}. ${step.action}: ${step.ok ? "PASS" : "FAIL"}${step.message ? ` (${step.message})` : ""}`).join("\n")}`;
+                return {
+                    content: [{ type: "text", text: params.finalSummaryOnly ? run.summary : `Browser batch\nAction: ${actionId}\n\n${summary}\n\nDiff:\n${deps.formatDiffText(diff)}` }],
+                    details: { actionId, diff, ...run },
+                    isError: !run.ok,
+                };
+            }
+            catch (err) {
+                if (actionId !== null) {
+                    deps.finishTrackedAction(actionId, { status: "error", afterUrl: deps.getActivePageOrNull()?.url() ?? "", error: err.message, beforeState: beforeState ?? undefined });
+                }
+                return {
+                    content: [{ type: "text", text: `Browser batch failed: ${err.message}` }],
+                    details: { error: err.message, actionId },
+                    isError: true,
+                };
+            }
+        },
+    });
+}

package/dist/resources/extensions/browser-tools/tools/codegen.js

@@ -0,0 +1,242 @@
+import { Type } from "@sinclair/typebox";
+import { getActionTimeline } from "../state.js";
+/**
+ * Test code generation — transform recorded browser session into a Playwright test script.
+ */
+export function registerCodegenTools(pi, deps) {
+    pi.registerTool({
+        name: "browser_generate_test",
+        label: "Browser Generate Test",
+        description: "Generate a runnable Playwright test script from the recorded action timeline. " +
+            "Transforms navigation, click, type, and assertion actions into standard Playwright test syntax. " +
+            "Uses stable selectors (role-based preferred). Writes the test file to a configurable path.",
+        parameters: Type.Object({
+            name: Type.Optional(Type.String({ description: "Test name (used for describe/test block and filename). Default: 'recorded-session'." })),
+            outputPath: Type.Optional(Type.String({
+                description: "Output file path for the generated test. Default: writes to session artifacts directory. " +
+                    "Use a path ending in .spec.ts for standard Playwright test convention.",
+            })),
+            includeAssertions: Type.Optional(Type.Boolean({ description: "Include assertion steps from the timeline (default: true)." })),
+        }),
+        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+            try {
+                await deps.ensureBrowser();
+                const timeline = getActionTimeline();
+                if (timeline.entries.length === 0) {
+                    return {
+                        content: [{ type: "text", text: "No actions recorded in the current session. Interact with pages first, then generate a test." }],
+                        details: { error: "no_actions" },
+                        isError: true,
+                    };
+                }
+                const testName = params.name ?? "recorded-session";
+                const includeAssertions = params.includeAssertions ?? true;
+                // Transform timeline entries into Playwright test code
+                const testLines = [];
+                const imports = new Set();
+                imports.add("test");
+                imports.add("expect");
+                testLines.push(`test.describe('${escapeString(testName)}', () => {`);
+                testLines.push(`  test('recorded session', async ({ page }) => {`);
+                let lastUrl = "";
+                let actionCount = 0;
+                for (const entry of timeline.entries) {
+                    if (entry.status === "error" && entry.tool !== "browser_assert")
+                        continue;
+                    const params = parseParamsSummary(entry.paramsSummary);
+                    switch (entry.tool) {
+                        case "browser_navigate": {
+                            const url = params.url;
+                            if (url && url !== lastUrl) {
+                                testLines.push(`    await page.goto(${quote(url)});`);
+                                lastUrl = url;
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        case "browser_click": {
+                            const selector = params.selector;
+                            if (selector) {
+                                testLines.push(`    await page.locator(${quote(selector)}).click();`);
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        case "browser_click_ref": {
+                            // Refs are session-specific — add comment
+                            testLines.push(`    // browser_click_ref: ${entry.paramsSummary} — replace with stable selector`);
+                            actionCount++;
+                            break;
+                        }
+                        case "browser_type": {
+                            const selector = params.selector;
+                            const text = params.text;
+                            if (selector && text) {
+                                testLines.push(`    await page.locator(${quote(selector)}).fill(${quote(text)});`);
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        case "browser_fill_ref": {
+                            testLines.push(`    // browser_fill_ref: ${entry.paramsSummary} — replace with stable selector`);
+                            actionCount++;
+                            break;
+                        }
+                        case "browser_key_press": {
+                            const key = params.key;
+                            if (key) {
+                                testLines.push(`    await page.keyboard.press(${quote(key)});`);
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        case "browser_select_option": {
+                            const selector = params.selector;
+                            const option = params.option;
+                            if (selector && option) {
+                                testLines.push(`    await page.locator(${quote(selector)}).selectOption(${quote(option)});`);
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        case "browser_set_checked": {
+                            const selector = params.selector;
+                            const checked = params.checked;
+                            if (selector) {
+                                testLines.push(`    await page.locator(${quote(selector)}).setChecked(${checked === "true"});`);
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        case "browser_hover": {
+                            const selector = params.selector;
+                            if (selector) {
+                                testLines.push(`    await page.locator(${quote(selector)}).hover();`);
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        case "browser_wait_for": {
+                            const condition = params.condition;
+                            const value = params.value;
+                            if (condition === "selector_visible" && value) {
+                                testLines.push(`    await expect(page.locator(${quote(value)})).toBeVisible();`);
+                                actionCount++;
+                            }
+                            else if (condition === "text_visible" && value) {
+                                testLines.push(`    await expect(page.locator('body')).toContainText(${quote(value)});`);
+                                actionCount++;
+                            }
+                            else if (condition === "url_contains" && value) {
+                                testLines.push(`    await page.waitForURL(${quote(`**/*${value}*`)});`);
+                                actionCount++;
+                            }
+                            else if (condition === "network_idle") {
+                                testLines.push(`    await page.waitForLoadState('networkidle');`);
+                                actionCount++;
+                            }
+                            else if (condition === "delay" && value) {
+                                testLines.push(`    await page.waitForTimeout(${value});`);
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        case "browser_assert": {
+                            if (!includeAssertions)
+                                break;
+                            // The assertion details are in verificationSummary
+                            if (entry.verificationSummary) {
+                                testLines.push(`    // Assertion: ${entry.verificationSummary}`);
+                            }
+                            actionCount++;
+                            break;
+                        }
+                        case "browser_scroll": {
+                            const direction = params.direction;
+                            const amount = params.amount ?? "300";
+                            const delta = direction === "up" ? `-${amount}` : amount;
+                            testLines.push(`    await page.mouse.wheel(0, ${delta});`);
+                            actionCount++;
+                            break;
+                        }
+                        case "browser_set_viewport": {
+                            const width = params.width;
+                            const height = params.height;
+                            if (width && height) {
+                                testLines.push(`    await page.setViewportSize({ width: ${width}, height: ${height} });`);
+                                actionCount++;
+                            }
+                            break;
+                        }
+                        default:
+                            // Skip tools that don't map to Playwright test actions
+                            break;
+                    }
+                }
+                testLines.push(`  });`);
+                testLines.push(`});`);
+                const importLine = `import { ${[...imports].join(", ")} } from '@playwright/test';`;
+                const fullTest = `${importLine}\n\n${testLines.join("\n")}\n`;
+                // Write to file
+                let outputPath;
+                if (params.outputPath) {
+                    outputPath = params.outputPath;
+                }
+                else {
+                    const safeName = deps.sanitizeArtifactName(testName, "recorded-session");
+                    outputPath = deps.buildSessionArtifactPath(`${safeName}.spec.ts`);
+                }
+                await deps.ensureSessionArtifactDir();
+                const { path: writtenPath, bytes } = await deps.writeArtifactFile(outputPath, fullTest);
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Test generated: ${writtenPath}\nActions: ${actionCount}\nTimeline entries processed: ${timeline.entries.length}\n\n${fullTest}`,
+                        }],
+                    details: {
+                        path: writtenPath,
+                        bytes,
+                        actionCount,
+                        timelineEntries: timeline.entries.length,
+                        testCode: fullTest,
+                    },
+                };
+            }
+            catch (err) {
+                return {
+                    content: [{ type: "text", text: `Test generation failed: ${err.message}` }],
+                    details: { error: err.message },
+                    isError: true,
+                };
+            }
+        },
+    });
+}
+function escapeString(s) {
+    return s.replace(/'/g, "\\'").replace(/\\/g, "\\\\");
+}
+function quote(s) {
+    // Use single quotes for simple strings, backtick for those with quotes
+    if (!s.includes("'"))
+        return `'${s}'`;
+    if (!s.includes("`"))
+        return `\`${s}\``;
+    return `'${s.replace(/'/g, "\\'")}'`;
+}
+/**
+ * Parse the paramsSummary string back into key-value pairs.
+ * Format: key="value", key=value, key=[N], key={...}
+ */
+function parseParamsSummary(summary) {
+    const result = {};
+    if (!summary)
+        return result;
+    const regex = /(\w+)=(?:"([^"]*(?:\\"[^"]*)*)"|([^,\s]+))/g;
+    let match;
+    while ((match = regex.exec(summary)) !== null) {
+        const key = match[1];
+        const value = match[2] ?? match[3];
+        result[key] = value;
+    }
+    return result;
+}