pi-browser-use 0.2.0 → 0.3.1

package/README.md

@@ -44,7 +44,18 @@ Hosts where `process.execPath` is not a directly executable Node runtime can set
 
 ## Page-scoped tools
 
-Call `browser_list_pages` first, then pass its numeric `pageId` to page-scoped tools. See `skills/browser-policy/SKILL.md` for the full agent policy.
+Call `browser_list_pages` first, then pass its numeric `pageId` to page-scoped tools. Click-family calls blocked by an overlay are retried once automatically after dismissing it with Escape. See `skills/browser-policy/SKILL.md` for the full agent policy.
+
+## Saved artifacts
+
+`browser_save_artifact` writes a screenshot or the rendered HTML to disk (default `~/.pi/browser-artifacts/`) and returns the path. Prefer it over inline captures for evidence, visual QA, and artifact sharing.
+
+## Bundled skills
+
+- `browser-policy` — CLI-first decision order, session modes, bot-wall and safety rules.
+- `playwright-handoff` — when to stop clicking and run a repo Playwright spec instead (npm-first, bun alternatives, no repo changes required).
+- `triage-console` — snapshot → console errors → failed network → screenshot.
+- `visual-qa` — viewport matrix and canvas/WebGL discipline.
 
 ## Vision model (optional)
 

package/dist/artifacts.d.ts

@@ -0,0 +1,10 @@
+export type ArtifactKind = 'screenshot' | 'html';
+export declare function defaultArtifactDir(): string;
+/** Resolve the destination file: explicit path wins, otherwise a timestamped file in the default dir. */
+export declare function resolveArtifactTarget(kind: ArtifactKind, path?: unknown): string;
+/** Pick the first image payload out of MCP content, if any. */
+export declare function pickImageData(content: unknown): {
+    data: string;
+    mimeType: string;
+} | undefined;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/artifacts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.d.ts","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,MAAM,CAAA;AAEhD,wBAAgB,kBAAkB,IAAI,MAAM,CAE3C;AAED,yGAAyG;AACzG,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,YAAY,EAAE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAGhF;AASD,+DAA+D;AAC/D,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAK9F"}

package/dist/artifacts.js

@@ -0,0 +1,21 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+export function defaultArtifactDir() {
+    return join(homedir(), '.pi', 'browser-artifacts');
+}
+/** Resolve the destination file: explicit path wins, otherwise a timestamped file in the default dir. */
+export function resolveArtifactTarget(kind, path) {
+    if (typeof path === 'string' && path.length > 0)
+        return path;
+    return join(defaultArtifactDir(), `page-${Date.now()}.${kind === 'html' ? 'html' : 'png'}`);
+}
+/** Pick the first image payload out of MCP content, if any. */
+export function pickImageData(content) {
+    if (!Array.isArray(content))
+        return undefined;
+    const found = content.find((item) => item.type === 'image' && item.data);
+    if (!found?.data)
+        return undefined;
+    return { data: found.data, mimeType: found.mimeType ?? 'image/png' };
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../src/artifacts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAA;AACjC,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAA;AAIhC,MAAM,UAAU,kBAAkB;IAChC,OAAO,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,mBAAmB,CAAC,CAAA;AACpD,CAAC;AAED,yGAAyG;AACzG,MAAM,UAAU,qBAAqB,CAAC,IAAkB,EAAE,IAAc;IACtE,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAC5D,OAAO,IAAI,CAAC,kBAAkB,EAAE,EAAE,QAAQ,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,EAAE,CAAC,CAAA;AAC7F,CAAC;AASD,+DAA+D;AAC/D,MAAM,UAAU,aAAa,CAAC,OAAgB;IAC5C,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,SAAS,CAAA;IAC7C,MAAM,KAAK,GAAI,OAAyB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,IAAI,CAAC,CAAA;IAC3F,IAAI,CAAC,KAAK,EAAE,IAAI;QAAE,OAAO,SAAS,CAAA;IAClC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,QAAQ,EAAE,KAAK,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAA;AACtE,CAAC"}

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAoBzD,UAAU,aAAa;IACrB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;IAChD,mBAAmB,CACjB,KAAK,EAAE,OAAO,GACb,OAAO,CACR;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAC/F,CAAA;CACF;AAED,UAAU,aAAa;IACrB,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAED,UAAU,EAAE;IACV,YAAY,CAAC,GAAG,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,OAAO,CAAA;QACnB,OAAO,EAAE,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,OAAO,EAClB,GAAG,CAAC,EAAE,aAAa,KAChB,OAAO,CAAC;YACX,OAAO,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;YACjF,OAAO,CAAC,EAAE,OAAO,CAAA;YACjB,OAAO,CAAC,EAAE,SAAS,CAAA;SACpB,CAAC,CAAA;KACH,GAAG,IAAI,CAAA;IACR,EAAE,CACA,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GACzF,IAAI,CAAA;CACR;AA8BD;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,EAAE,EAAE,EAAE,QAyFjD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAkCzD,UAAU,aAAa;IACrB,IAAI,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAA;IAChD,mBAAmB,CACjB,KAAK,EAAE,OAAO,GACb,OAAO,CACR;QAAE,EAAE,EAAE,IAAI,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;KAAE,GAAG;QAAE,EAAE,EAAE,KAAK,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAC/F,CAAA;CACF;AAED,UAAU,aAAa;IACrB,aAAa,CAAC,EAAE,aAAa,CAAA;CAC9B;AAED,UAAU,EAAE;IACV,YAAY,CAAC,GAAG,EAAE;QAChB,IAAI,EAAE,MAAM,CAAA;QACZ,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,UAAU,EAAE,OAAO,CAAA;QACnB,OAAO,EAAE,CACP,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,OAAO,EAClB,GAAG,CAAC,EAAE,aAAa,KAChB,OAAO,CAAC;YACX,OAAO,EAAE,KAAK,CAAC;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;aAAE,CAAC,CAAA;YACjF,OAAO,CAAC,EAAE,OAAO,CAAA;YACjB,OAAO,CAAC,EAAE,SAAS,CAAA;SACpB,CAAC,CAAA;KACH,GAAG,IAAI,CAAA;IACR,EAAE,CACA,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE;QAAE,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GACzF,IAAI,CAAA;CACR;AA8BD;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,EAAE,EAAE,EAAE,QA2KjD"}

package/dist/index.js

@@ -1,13 +1,20 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
 import { Type } from 'typebox';
 import { DevToolsClient } from './client.js';
 import { resolveConfig } from './config.js';
 import { isProjectTrusted, loadConfig } from './settings.js';
-import { augmentToolDescription, extractTextContent, postProcessToolResult, } from './tool-augment.js';
+import { augmentToolDescription, extractTextContent, looksOverlayBlocked, OVERLAY_RECOVERABLE, postProcessToolResult, } from './tool-augment.js';
+import { pickImageData, resolveArtifactTarget } from './artifacts.js';
 import { prepareBrowserProfile } from './profile.js';
 import { createRegistryVisionCaller, handleAnalyzeScreenshot, } from './vision.js';
 export { configToArgs, resolveConfig } from './config.js';
 // All upstream tools are re-exported with this prefix to avoid name collisions.
 const TOOL_PREFIX = 'browser_';
+async function callUpstream(client, name, params, signal) {
+    return (await client.callTool(name, params, signal));
+}
 // Noisy, slow, or privileged upstream tools; skipped during registration.
 const EXCLUDED_TOOLS = new Set([
     'lighthouse_audit',
@@ -79,12 +86,87 @@ export default function browserUseExtension(pi) {
                 parameters: Type.Unsafe(tool.inputSchema),
                 async execute(_toolCallId, params, signal) {
                     await ensureConnected(signal);
-                    const result = (await client.callTool(originalName, params, signal));
+                    const browser = client;
+                    let result = await callUpstream(browser, originalName, params, signal);
+                    if (result.isError &&
+                        OVERLAY_RECOVERABLE.has(originalName) &&
+                        looksOverlayBlocked(extractTextContent(result.content))) {
+                        // One recovery attempt: dismiss the overlay, then retry the
+                        // original call. Any failure here falls through to the
+                        // original error, which already carries a hint.
+                        try {
+                            const escapeArgs = typeof params.pageId === 'number'
+                                ? { pageId: params.pageId, key: 'Escape' }
+                                : { key: 'Escape' };
+                            await callUpstream(browser, 'press_key', escapeArgs, signal);
+                            result = await callUpstream(browser, originalName, params, signal);
+                        }
+                        catch {
+                            // Fall through to the original result below.
+                        }
+                    }
                     return { ...toToolContent(result, originalName), details: undefined };
                 },
             });
         }
     }
+    function registerSaveArtifactTool() {
+        const properties = {
+            kind: Type.Union([Type.Literal('screenshot'), Type.Literal('html')], {
+                description: 'Capture a viewport screenshot (PNG) or the full rendered HTML.',
+            }),
+            path: Type.Optional(Type.String({
+                description: 'Absolute destination path. Defaults to ~/.pi/browser-artifacts/<timestamp>.<png|html>.',
+            })),
+        };
+        if (config?.experimentalPageIdRouting === true) {
+            properties.pageId = Type.Number({
+                description: 'Numeric page ID returned by browser_list_pages.',
+            });
+        }
+        pi.registerTool({
+            name: `${TOOL_PREFIX}save_artifact`,
+            label: `${TOOL_PREFIX}save_artifact`,
+            description: 'Save a screenshot or the rendered HTML of the current page to disk and return its path. Prefer this over pulling image bytes into context when the capture is evidence (bug reports, visual QA, artifact sharing) rather than something you need to look at right now.',
+            parameters: Type.Object(properties),
+            async execute(_toolCallId, params, signal) {
+                await ensureConnected(signal);
+                const browser = client;
+                const kind = params.kind === 'html' ? 'html' : 'screenshot';
+                const pageId = typeof params.pageId === 'number' ? params.pageId : undefined;
+                const target = resolveArtifactTarget(kind, params.path);
+                if (kind === 'html') {
+                    const pageArgs = pageId === undefined ? {} : { pageId };
+                    const evaluated = (await browser.callTool('evaluate_script', {
+                        ...pageArgs,
+                        function: '() => document.documentElement.outerHTML',
+                    }, signal));
+                    const html = extractTextContent(evaluated.content);
+                    if (!html)
+                        throw new Error('Page HTML came back empty.');
+                    mkdirSync(dirname(target), { recursive: true });
+                    writeFileSync(target, html, 'utf8');
+                    return {
+                        content: [
+                            { type: 'text', text: `Saved page HTML (${html.length} chars) to ${target}` },
+                        ],
+                        details: undefined,
+                    };
+                }
+                const shotArgs = pageId === undefined ? {} : { pageId };
+                const shot = (await browser.callTool('take_screenshot', shotArgs, signal));
+                const image = pickImageData(shot.content);
+                if (!image)
+                    throw new Error('Screenshot came back without image data.');
+                mkdirSync(dirname(target), { recursive: true });
+                writeFileSync(target, Buffer.from(image.data, 'base64'));
+                return {
+                    content: [{ type: 'text', text: `Saved screenshot to ${target}` }],
+                    details: undefined,
+                };
+            },
+        });
+    }
     async function registerVisionTool(visionConfig) {
         const properties = {
             instruction: Type.Optional(Type.String({
@@ -119,6 +201,7 @@ export default function browserUseExtension(pi) {
         prepareBrowserProfile(config);
         client = new DevToolsClient(config);
         await registerUpstreamTools();
+        registerSaveArtifactTool();
         if (config.visionModel) {
             await registerVisionTool(config.visionModel);
         }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAgB,MAAM,SAAS,CAAA;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAC5C,OAAO,EAAE,aAAa,EAAyB,MAAM,aAAa,CAAA;AAClE,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,MAAM,eAAe,CAAA;AAC5D,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,qBAAqB,GACtB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAA;AACpD,OAAO,EACL,0BAA0B,EAC1B,uBAAuB,GAExB,MAAM,aAAa,CAAA;AAEpB,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAEzD,gFAAgF;AAChF,MAAM,WAAW,GAAG,UAAU,CAAA;AAE9B,0EAA0E;AAC1E,MAAM,cAAc,GAAG,IAAI,GAAG,CAAC;IAC7B,kBAAkB;IAClB,6BAA6B;IAC7B,yBAAyB;IACzB,wBAAwB;IACxB,kBAAkB;IAClB,iBAAiB;IACjB,mBAAmB;IACnB,iBAAiB;IACjB,kBAAkB;IAClB,0BAA0B;IAC1B,qBAAqB;CACtB,CAAC,CAAA;AAuCF,SAAS,aAAa,CACpB,MAGC,EACD,YAAoB;IAEpB,MAAM,WAAW,GAAG,kBAAkB,CAAC,MAAM,CAAC,OAAO,CAAC,CAAA;IACtD,MAAM,SAAS,GAAG,qBAAqB,CAAC,YAAY,EAAE,WAAW,CAAC,CAAA;IAClE,MAAM,OAAO,GAA6E,EAAE,CAAA;IAC5F,IAAI,SAAS,KAAK,WAAW,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAA;IACjD,CAAC;SAAM,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,IAAI;gBAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;QACxF,CAAC;IACH,CAAC;IACD,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;QACnB,KAAK,MAAM,IAAI,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;YAClC,IAAI,IAAI,CAAC,IAAI,KAAK,OAAO,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;gBACvC,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,WAAW,EAAE,CAAC,CAAA;YAC1F,CAAC;QACH,CAAC;IACH,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,EAAE,CAAC,CAAA;IAClE,OAAO,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,IAAa,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAA;AAC3E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,OAAO,UAAU,mBAAmB,CAAC,EAAM;IAChD,IAAI,MAAoC,CAAA;IACxC,IAAI,MAAkC,CAAA;IAEtC,KAAK,UAAU,eAAe,CAAC,MAAoB;QACjD,IAAI,CAAC,MAAM;YAAE,MAAM,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAA;QAChE,MAAM,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAA;IAClC,CAAC;IAED,KAAK,UAAU,qBAAqB;QAClC,MAAM,eAAe,EAAE,CAAA;QACvB,MAAM,aAAa,GAAG,MAAM,MAAO,CAAC,YAAY,EAAE,CAAA;QAClD,KAAK,MAAM,IAAI,IAAI,aAAa,EAAE,CAAC;YACjC,IAAI,cAAc,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC;gBAAE,SAAQ;YAC3C,MAAM,YAAY,GAAG,GAAG,WAAW,GAAG,IAAI,CAAC,IAAI,EAAE,CAAA;YACjD,MAAM,YAAY,GAAG,IAAI,CAAC,IAAI,CAAA;YAC9B,MAAM,WAAW,GAAG,sBAAsB,CAAC,YAAY,EAAE,IAAI,CAAC,WAAW,IAAI,EAAE,CAAC,CAAA;YAChF,EAAE,CAAC,YAAY,CAAC;gBACd,IAAI,EAAE,YAAY;gBAClB,KAAK,EAAE,YAAY;gBACnB,WAAW;gBACX,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,WAAsB,CAAC;gBACpD,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM;oBACvC,MAAM,eAAe,CAAC,MAAM,CAAC,CAAA;oBAC7B,MAAM,MAAM,GAAG,CAAC,MAAM,MAAO,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,MAAM,CAAC,CAGnE,CAAA;oBACD,OAAO,EAAE,GAAG,aAAa,CAAC,MAAM,EAAE,YAAY,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;gBACvE,CAAC;aACF,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED,KAAK,UAAU,kBAAkB,CAAC,YAA+B;QAC/D,MAAM,UAAU,GAA4B;YAC1C,WAAW,EAAE,IAAI,CAAC,QAAQ,CACxB,IAAI,CAAC,MAAM,CAAC;gBACV,WAAW,EACT,+FAA+F;aAClG,CAAC,CACH;SACF,CAAA;QACD,IAAI,MAAM,EAAE,yBAAyB,KAAK,IAAI,EAAE,CAAC;YAC/C,UAAU,CAAC,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;gBAC9B,WAAW,EAAE,iDAAiD;aAC/D,CAAC,CAAA;QACJ,CAAC;QACD,EAAE,CAAC,YAAY,CAAC;YACd,IAAI,EAAE,GAAG,WAAW,oBAAoB;YACxC,KAAK,EAAE,GAAG,WAAW,oBAAoB;YACzC,WAAW,EACT,6PAA6P;YAC/P,UAAU,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;YACnC,KAAK,CAAC,OAAO,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,GAAG;gBACvD,MAAM,eAAe,CAAC,MAAM,CAAC,CAAA;gBAC7B,IAAI,CAAC,GAAG,EAAE,aAAa;oBACrB,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAA;gBAC1E,MAAM,UAAU,GAAG,0BAA0B,CAAC,YAAY,EAAE,GAAG,CAAC,aAAa,CAAC,CAAA;gBAC9E,MAAM,MAAM,GAAG,OAAO,MAAM,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAA;gBAC5E,MAAM,MAAM,GAAG,MAAM,uBAAuB,CAC1C;oBACE,QAAQ,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,MAAO,CAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,GAAG,CAAC;iBACjE,EACD,UAAU,EACV,EAAE,WAAW,EAAE,OAAO,MAAM,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,EACzF,MAAM,CACP,CAAA;gBACD,OAAO,EAAE,GAAG,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,CAAA;YAC1C,CAAC;SACF,CAAC,CAAA;IACJ,CAAC;IAED,EAAE,CAAC,EAAE,CAAC,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,EAAE,EAAE;QAC3C,MAAM,GAAG,aAAa,CAAC,UAAU,CAAC,EAAE,GAAG,EAAE,GAAG,CAAC,GAAG,EAAE,cAAc,EAAE,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAA;QAC3F,qBAAqB,CAAC,MAAM,CAAC,CAAA;QAC7B,MAAM,GAAG,IAAI,cAAc,CAAC,MAAM,CAAC,CAAA;QACnC,MAAM,qBAAqB,EAAE,CAAA;QAC7B,IAAI,MAAM,CAAC,WAAW,EAAE,CAAC;YACvB,MAAM,kBAAkB,CAAC,MAAM,CAAC,WAAW,CAAC,CAAA;QAC9C,CAAC;IACH,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,EAAE,CAAC,kBAAkB,EAAE,KAAK,IAAI,EAAE;QACnC,IAAI,MAAM,EAAE,CAAC;YACX,MAAM,MAAM,CAAC,KAAK,EAAE,CAAA;YACpB,MAAM,GAAG,SAAS,CAAA;QACpB,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/tool-augment.d.ts

@@ -1,4 +1,6 @@
 export declare function augmentToolDescription(prefixedName: string, description: string): string;
 export declare function postProcessToolResult(originalName: string, text: string): string;
+export declare const OVERLAY_RECOVERABLE: Set<string>;
+export declare function looksOverlayBlocked(text: string): boolean;
 export declare function extractTextContent(content: unknown): string;
 //# sourceMappingURL=tool-augment.d.ts.map

package/dist/tool-augment.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-augment.d.ts","sourceRoot":"","sources":["../src/tool-augment.ts"],"names":[],"mappings":"AASA,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAGxF;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhF;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAS3D"}
+{"version":3,"file":"tool-augment.d.ts","sourceRoot":"","sources":["../src/tool-augment.ts"],"names":[],"mappings":"AASA,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAGxF;AAED,wBAAgB,qBAAqB,CAAC,YAAY,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAQhF;AAID,eAAO,MAAM,mBAAmB,aAS9B,CAAA;AAEF,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAEzD;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAS3D"}

package/dist/tool-augment.js

@@ -18,6 +18,21 @@ export function postProcessToolResult(originalName, text) {
     }
     return text;
 }
+// Click-family tools worth one automatic recovery attempt when an overlay
+// blocks them: dismiss with Escape, then retry once.
+export const OVERLAY_RECOVERABLE = new Set([
+    'click',
+    'click_at',
+    'fill',
+    'fill_form',
+    'press_key',
+    'type_text',
+    'hover',
+    'drag',
+]);
+export function looksOverlayBlocked(text) {
+    return /overlay|obscured|intercept|behind another element|not clickable|not visible/i.test(text);
+}
 export function extractTextContent(content) {
     if (!Array.isArray(content))
         return '';

package/dist/tool-augment.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-augment.js","sourceRoot":"","sources":["../src/tool-augment.ts"],"names":[],"mappings":"AAAA,MAAM,KAAK,GAA2B;IACpC,aAAa,EACX,mGAAmG;IACrG,YAAY,EAAE,+EAA+E;IAC7F,iBAAiB,EAAE,2DAA2D;IAC9E,qBAAqB,EAAE,gEAAgE;IACvF,qBAAqB,EAAE,0DAA0D;CAClF,CAAA;AAED,MAAM,UAAU,sBAAsB,CAAC,YAAoB,EAAE,WAAmB;IAC9E,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,CAAA;IAChC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,WAAW,aAAa,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,CAAA;AAC/D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,YAAoB,EAAE,IAAY;IACtE,IAAI,YAAY,KAAK,OAAO,IAAI,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzE,OAAO,GAAG,IAAI,oGAAoG,CAAA;IACpH,CAAC;IACD,IAAI,qCAAqC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClF,OAAO,GAAG,IAAI,kFAAkF,CAAA;IAClG,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAA;IACtC,OAAO,OAAO;SACX,MAAM,CACL,CAAC,IAAI,EAA2C,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAC7F;SACA,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;SACvE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAc,CAAC;SAClC,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC"}
+{"version":3,"file":"tool-augment.js","sourceRoot":"","sources":["../src/tool-augment.ts"],"names":[],"mappings":"AAAA,MAAM,KAAK,GAA2B;IACpC,aAAa,EACX,mGAAmG;IACrG,YAAY,EAAE,+EAA+E;IAC7F,iBAAiB,EAAE,2DAA2D;IAC9E,qBAAqB,EAAE,gEAAgE;IACvF,qBAAqB,EAAE,0DAA0D;CAClF,CAAA;AAED,MAAM,UAAU,sBAAsB,CAAC,YAAoB,EAAE,WAAmB;IAC9E,MAAM,IAAI,GAAG,KAAK,CAAC,YAAY,CAAC,CAAA;IAChC,OAAO,IAAI,CAAC,CAAC,CAAC,GAAG,WAAW,aAAa,IAAI,EAAE,CAAC,CAAC,CAAC,WAAW,CAAA;AAC/D,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,YAAoB,EAAE,IAAY;IACtE,IAAI,YAAY,KAAK,OAAO,IAAI,6BAA6B,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACzE,OAAO,GAAG,IAAI,oGAAoG,CAAA;IACpH,CAAC;IACD,IAAI,qCAAqC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QAClF,OAAO,GAAG,IAAI,kFAAkF,CAAA;IAClG,CAAC;IACD,OAAO,IAAI,CAAA;AACb,CAAC;AAED,0EAA0E;AAC1E,qDAAqD;AACrD,MAAM,CAAC,MAAM,mBAAmB,GAAG,IAAI,GAAG,CAAC;IACzC,OAAO;IACP,UAAU;IACV,MAAM;IACN,WAAW;IACX,WAAW;IACX,WAAW;IACX,OAAO;IACP,MAAM;CACP,CAAC,CAAA;AAEF,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,OAAO,8EAA8E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;AAClG,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAgB;IACjD,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC;QAAE,OAAO,EAAE,CAAA;IACtC,OAAO,OAAO;SACX,MAAM,CACL,CAAC,IAAI,EAA2C,EAAE,CAAC,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,CAC7F;SACA,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,IAAI,CAAC,IAAI,KAAK,QAAQ,CAAC;SACvE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAc,CAAC;SAClC,IAAI,CAAC,IAAI,CAAC,CAAA;AACf,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-use",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Opinionated browser-use for the Pi coding agent, powered by chrome-devtools-mcp (not Playwright). Fresh headless by default, authenticated persistent profile opt-in, CLI-first policy bundled.",
   "keywords": [
     "pi-package",

package/skills/playwright-handoff/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: playwright-handoff
+description: Decide when browser automation has hit its limits and hand off to a repo Playwright run instead. Use when a task needs request mocking, assertions, traces, repeatability, or CI parity that browser_* tools cannot provide.
+---
+
+# Playwright Handoff
+
+`browser_*` drives a real page well. It cannot do the following — hand these to Playwright instead of fighting the browser:
+
+- **Request mocking** (`page.route` → `route.fulfill` for API responses)
+- **Assertions with auto-retry** (`expect(locator).toBeVisible({ timeout })`)
+- **Traces, video, isolated contexts per test**
+- **Repeatable gates** that must pass in CI
+
+## Rule
+
+One failed browser attempt at the above is enough signal. Do not retry twice via `browser_*`; switch runners.
+
+## Running without touching the repo
+
+No install and no repo changes are required. Detect the runner first, then run a throwaway spec from `/tmp` against the already-running server or live URL:
+
+```bash
+command -v bun >/dev/null 2>&1 && echo HAS_BUN || echo NPM_ONLY
+```
+
+```bash
+# Repo already has Playwright (e.g. agent-hq, cortana): use it directly.
+bunx playwright test --config=playwright.config.ts --grep "<test name>"
+```
+
+```bash
+# Any other repo: npm cache + /tmp spec, zero repo mutation.
+npx -y @playwright/test test /tmp/smoke.spec.ts --reporter=list
+```
+
+```bash
+# Same via bun when available.
+bunx --package @playwright/test playwright test /tmp/smoke.spec.ts --reporter=list
+```
+
+First run on a machine downloads the browser once to the shared user cache (`~/.cache/ms-playwright`, ~170MB); every repo after that reuses it.
+
+## Minimal throwaway spec shape
+
+```ts
+// /tmp/smoke.spec.ts
+import { expect, test } from '@playwright/test'
+
+test('guest sees the workspace', async ({ page }) => {
+  await page.goto(process.env.SMOKE_URL ?? 'http://localhost:3000/')
+  await expect(page.getByRole('button', { name: 'User settings' })).toBeVisible({ timeout: 20000 })
+})
+```
+
+```bash
+SMOKE_URL=https://staging.example.com npx -y @playwright/test test /tmp/smoke.spec.ts
+```
+
+## Headless discipline
+
+ headed browsers pop windows and steal focus. Prefer headless for agent runs:
+
+```bash
+# npm / npx: headless is Playwright's default; keep it that way.
+# bun repos whose config defaults to headed on macOS (e.g. agent-hq):
+PLAYWRIGHT_HEADLESS=1 bunx playwright test --config=playwright.config.ts
+```
+
+Keep headed runs for human-watched perf validation only.
+
+## Reporting back
+
+Summarize pass/fail plus the failing assertion or trace path. Delete nothing from the repo — the only artifacts are `/tmp/*.spec.ts` and the shared browser cache.

package/skills/triage-console/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: triage-console
+description: Standard flow for diagnosing a broken page. Use when a site misbehaves, renders wrong, or throws — snapshot, console errors, failed network requests, then screenshot.
+---
+
+# Console Triage
+
+Run in order. Stop at the first step that explains the breakage; do not skip ahead to screenshots.
+
+## 1. Snapshot
+
+```text
+browser_list_pages({})
+browser_take_snapshot({ "pageId": <id> })
+```
+
+If the expected element is missing from the tree, the page likely failed to load data or JS — continue. If it is present but misbehaving, skip to step 4.
+
+## 2. Console errors
+
+```text
+browser_list_console_messages({ "pageId": <id> })
+```
+
+Read `error` entries first. A single `pageerror` often names the exact failing module. `warning` entries are context, not causes.
+
+## 3. Failed network
+
+```text
+browser_list_network_requests({ "pageId": <id> })
+```
+
+Look for non-2xx statuses, blocked URL patterns, CORS failures, and requests that never left `pending`. Correlate URLs with the console errors from step 2 before concluding.
+
+## 4. Screenshot (evidence, not diagnosis)
+
+Only now, and prefer saving over inlining:
+
+```text
+browser_save_artifact({ "pageId": <id>, "kind": "screenshot" })
+```
+
+Inline `browser_take_screenshot` only when you must look at the pixels yourself this turn.
+
+## Reporting
+
+One finding per cause, each with the exact console line or failing URL. If steps 1–3 are clean and the page still misbehaves, say so explicitly and hand off to `playwright-handoff` (mock the failing API, assert the render) instead of re-running triage.

package/skills/visual-qa/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: visual-qa
+description: Screenshot discipline for visual checks of WebGL/canvas scenes and layouts. Use when asked whether something "looks right", for before/after comparisons, or for viewport coverage.
+---
+
+# Visual QA
+
+The accessibility tree cannot see canvas pixels. That is the only reason to look at screenshots — exhaust the tree first.
+
+## Viewport matrix
+
+Cover at least two sizes; small viewports catch most layout regressions:
+
+```text
+browser_resize_page({ "pageId": <id>, "width": 1280, "height": 720 })
+browser_save_artifact({ "pageId": <id>, "kind": "screenshot" })
+browser_resize_page({ "pageId": <id>, "width": 390, "height": 844 })
+browser_save_artifact({ "pageId": <id>, "kind": "screenshot" })
+```
+
+Save, don't inline — `browser_save_artifact` returns paths. Inline `browser_take_screenshot` only for the frame you are judging this turn.
+
+## When the tree is blind (canvas/WebGL)
+
+1. `browser_analyze_screenshot` (requires `visionModel` config) for coordinates or element identification the tree cannot provide.
+2. Feed coordinates to `browser_click_at` — never guess pixels yourself.
+3. If the scene needs deterministic frames (animations, thumbnails), stop: that is `playwright-handoff` territory (`waitForFunction`, fixed timeouts, traces).
+
+## Failure bar
+
+A visual failure needs: what was expected, what rendered instead, the artifact path, and the viewport. "Looks off" without an artifact path is not a finding.
+
+## Pixel-flakiness notes
+
+- WebGL anti-aliasing and font rendering differ between headless (SwiftShader) and GPU browsers — compare like with like.
+- Allow one retry for animation timing before calling a failure.
+- Animations mid-frame are not bugs; wait for idle, then capture.