pi-browser-use 0.6.1 → 0.7.0

package/dist/tab-bridge.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Existing-mode tab broker bridge (spec section 18).
+ *
+ * Pi cannot drive the extension directly, and raw MCP `new_page` calls would
+ * create unmanaged foreground tabs — so tab creation goes through a tiny
+ * loopback HTTP bridge the extension polls:
+ *
+ * ```text
+ * Agent → BrowserSession.openPage(url) → ExistingSession
+ *   → POST /v1/request {url} → token
+ *   → extension polls GET /v1/pending → openPiTab(url) (inactive, grouped)
+ *   → extension POSTs /v1/complete {token, tabId}
+ *   → Pi waits for the token, then MCP selects the tab — never activating it
+ * ```
+ *
+ * Correlation is by unique token, never "first tab whose URL matches"
+ * (duplicate Gmail/GitHub tabs are common). Requests expire (default 2 min)
+ * so a dead extension cannot leak queue entries. Only Pi-owned tabs are
+ * tracked, so session-end cleanup never touches user tabs (spec 19).
+ *
+ * Security: binds 127.0.0.1 only and rejects non-loopback remotes.
+ */
+export declare const DEFAULT_BRIDGE_PORT = 31973;
+export interface TabRequest {
+    url: string;
+    token: string;
+    createdAt: number;
+}
+export interface TabCompletion {
+    token: string;
+    tabId?: number;
+    windowId?: number;
+    error?: string;
+    completedAt: number;
+}
+export interface TabBridgeOptions {
+    port?: number;
+    /** Pending requests older than this are dropped. Default 2 minutes. */
+    requestTtlMs?: number;
+    /** Completed entries kept for late waiters. Default 5 minutes. */
+    completionTtlMs?: number;
+}
+export declare class TabBridge {
+    private readonly options;
+    private server;
+    private pending;
+    private completed;
+    private readonly requestTtlMs;
+    private readonly completionTtlMs;
+    private sweepTimer;
+    constructor(options?: TabBridgeOptions);
+    port(): number | undefined;
+    baseUrl(): string;
+    start(): Promise<string>;
+    stop(): Promise<void>;
+    /** Enqueue an open-tab request; returns the correlation token. */
+    requestTab(url: string, token?: string): string;
+    /** Wait for the extension to complete `token` (throws on timeout/error). */
+    waitForTab(token: string, options?: {
+        timeoutMs?: number;
+        pollMs?: number;
+        signal?: AbortSignal;
+    }): Promise<TabCompletion>;
+    /** Tab IDs Pi created and still owns (session-end cleanup scope). */
+    ownedTabIds(): number[];
+    pendingCount(): number;
+    private sweep;
+    private json;
+    private handle;
+}
+//# sourceMappingURL=tab-bridge.d.ts.map

package/dist/tab-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tab-bridge.d.ts","sourceRoot":"","sources":["../src/tab-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH,eAAO,MAAM,mBAAmB,QAAQ,CAAA;AAExC,MAAM,WAAW,UAAU;IACzB,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,uEAAuE;IACvE,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,kEAAkE;IAClE,eAAe,CAAC,EAAE,MAAM,CAAA;CACzB;AAgCD,qBAAa,SAAS;IAQR,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,MAAM,CAAoB;IAClC,OAAO,CAAC,OAAO,CAAgC;IAC/C,OAAO,CAAC,SAAS,CAAmC;IACpD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAQ;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,UAAU,CAA4C;gBAEjC,OAAO,GAAE,gBAAqB;IAK3D,IAAI,IAAI,MAAM,GAAG,SAAS;IAK1B,OAAO,IAAI,MAAM;IAIX,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC;IAgBxB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAS3B,kEAAkE;IAClE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,MAAqB,GAAG,MAAM;IAO7D,4EAA4E;IACtE,UAAU,CACd,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE,GACtE,OAAO,CAAC,aAAa,CAAC;IAkBzB,qEAAqE;IACrE,WAAW,IAAI,MAAM,EAAE;IAMvB,YAAY,IAAI,MAAM;IAKtB,OAAO,CAAC,KAAK;IAUb,OAAO,CAAC,IAAI;YAKE,MAAM;CAmDrB"}

package/dist/tab-bridge.js

@@ -0,0 +1,198 @@
+/**
+ * Existing-mode tab broker bridge (spec section 18).
+ *
+ * Pi cannot drive the extension directly, and raw MCP `new_page` calls would
+ * create unmanaged foreground tabs — so tab creation goes through a tiny
+ * loopback HTTP bridge the extension polls:
+ *
+ * ```text
+ * Agent → BrowserSession.openPage(url) → ExistingSession
+ *   → POST /v1/request {url} → token
+ *   → extension polls GET /v1/pending → openPiTab(url) (inactive, grouped)
+ *   → extension POSTs /v1/complete {token, tabId}
+ *   → Pi waits for the token, then MCP selects the tab — never activating it
+ * ```
+ *
+ * Correlation is by unique token, never "first tab whose URL matches"
+ * (duplicate Gmail/GitHub tabs are common). Requests expire (default 2 min)
+ * so a dead extension cannot leak queue entries. Only Pi-owned tabs are
+ * tracked, so session-end cleanup never touches user tabs (spec 19).
+ *
+ * Security: binds 127.0.0.1 only and rejects non-loopback remotes.
+ */
+import { createServer } from 'node:http';
+import { randomUUID } from 'node:crypto';
+export const DEFAULT_BRIDGE_PORT = 31973;
+function isLoopback(remoteAddress) {
+    return (remoteAddress === '127.0.0.1' || remoteAddress === '::1' || remoteAddress === '::ffff:127.0.0.1');
+}
+function readJsonBody(req, limit = 64 * 1024) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on('data', (chunk) => {
+            size += chunk.length;
+            if (size > limit) {
+                reject(new Error('Request body too large.'));
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on('end', () => {
+            try {
+                resolve(JSON.parse(Buffer.concat(chunks).toString('utf8')));
+            }
+            catch {
+                reject(new Error('Invalid JSON body.'));
+            }
+        });
+        req.on('error', reject);
+    });
+}
+export class TabBridge {
+    options;
+    server;
+    pending = new Map();
+    completed = new Map();
+    requestTtlMs;
+    completionTtlMs;
+    sweepTimer;
+    constructor(options = {}) {
+        this.options = options;
+        this.requestTtlMs = options.requestTtlMs ?? 2 * 60 * 1000;
+        this.completionTtlMs = options.completionTtlMs ?? 5 * 60 * 1000;
+    }
+    port() {
+        const address = this.server?.address();
+        return typeof address === 'object' && address ? address.port : undefined;
+    }
+    baseUrl() {
+        return `http://127.0.0.1:${this.port()}`;
+    }
+    async start() {
+        if (this.server)
+            return this.baseUrl();
+        this.server = createServer((req, res) => {
+            void this.handle(req, res).catch(() => {
+                this.json(res, 500, { error: 'Internal bridge error.' });
+            });
+        });
+        await new Promise((resolve, reject) => {
+            this.server.on('error', reject);
+            this.server.listen(this.options.port ?? DEFAULT_BRIDGE_PORT, '127.0.0.1', () => resolve());
+        });
+        this.sweepTimer = setInterval(() => this.sweep(), 30_000);
+        this.sweepTimer.unref?.();
+        return this.baseUrl();
+    }
+    async stop() {
+        if (this.sweepTimer)
+            clearInterval(this.sweepTimer);
+        this.sweepTimer = undefined;
+        if (!this.server)
+            return;
+        const server = this.server;
+        this.server = undefined;
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    /** Enqueue an open-tab request; returns the correlation token. */
+    requestTab(url, token = randomUUID()) {
+        if (typeof url !== 'string' || url.length === 0)
+            throw new Error('Tab URL is required.');
+        this.sweep();
+        this.pending.set(token, { url, token, createdAt: Date.now() });
+        return token;
+    }
+    /** Wait for the extension to complete `token` (throws on timeout/error). */
+    async waitForTab(token, options) {
+        const timeoutMs = options?.timeoutMs ?? 30_000;
+        const pollMs = options?.pollMs ?? 100;
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            if (options?.signal?.aborted)
+                throw new Error('Tab wait aborted.');
+            const done = this.completed.get(token);
+            if (done) {
+                this.completed.delete(token);
+                if (done.error)
+                    throw new Error(`Extension failed to open tab: ${done.error}`);
+                return done;
+            }
+            await new Promise((resolve) => setTimeout(resolve, pollMs));
+        }
+        this.pending.delete(token);
+        throw new Error(`Timed out waiting for the extension to open the tab (token ${token}).`);
+    }
+    /** Tab IDs Pi created and still owns (session-end cleanup scope). */
+    ownedTabIds() {
+        return [...this.completed.values()]
+            .filter((c) => c.tabId !== undefined && !c.error)
+            .map((c) => c.tabId);
+    }
+    pendingCount() {
+        this.sweep();
+        return this.pending.size;
+    }
+    sweep() {
+        const now = Date.now();
+        for (const [token, req] of this.pending) {
+            if (now - req.createdAt > this.requestTtlMs)
+                this.pending.delete(token);
+        }
+        for (const [token, done] of this.completed) {
+            if (now - done.completedAt > this.completionTtlMs)
+                this.completed.delete(token);
+        }
+    }
+    json(res, status, body) {
+        res.writeHead(status, { 'content-type': 'application/json' });
+        res.end(JSON.stringify(body));
+    }
+    async handle(req, res) {
+        if (!isLoopback(req.socket.remoteAddress)) {
+            this.json(res, 403, { error: 'Tab bridge accepts loopback connections only.' });
+            return;
+        }
+        const url = new URL(req.url ?? '/', 'http://127.0.0.1');
+        if (req.method === 'GET' && url.pathname === '/v1/pending') {
+            this.sweep();
+            this.json(res, 200, { requests: [...this.pending.values()] });
+            this.pending.clear();
+            return;
+        }
+        if (req.method === 'POST' && url.pathname === '/v1/request') {
+            const body = (await readJsonBody(req));
+            if (typeof body.url !== 'string' || body.url.length === 0) {
+                this.json(res, 400, { error: 'Field "url" is required.' });
+                return;
+            }
+            const token = typeof body.token === 'string' && body.token.length > 0 ? body.token : randomUUID();
+            this.requestTab(body.url, token);
+            this.json(res, 200, { token });
+            return;
+        }
+        if (req.method === 'POST' && url.pathname === '/v1/complete') {
+            const body = (await readJsonBody(req));
+            if (typeof body.token !== 'string' || body.token.length === 0) {
+                this.json(res, 400, { error: 'Field "token" is required.' });
+                return;
+            }
+            this.completed.set(body.token, {
+                token: body.token,
+                tabId: typeof body.tabId === 'number' ? body.tabId : undefined,
+                windowId: typeof body.windowId === 'number' ? body.windowId : undefined,
+                error: typeof body.error === 'string' ? body.error : undefined,
+                completedAt: Date.now(),
+            });
+            this.json(res, 200, { ok: true });
+            return;
+        }
+        if (req.method === 'GET' && url.pathname === '/v1/health') {
+            this.json(res, 200, { ok: true });
+            return;
+        }
+        this.json(res, 404, { error: 'Unknown tab bridge route.' });
+    }
+}
+//# sourceMappingURL=tab-bridge.js.map

package/dist/tab-bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tab-bridge.js","sourceRoot":"","sources":["../src/tab-bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,YAAY,EAA0D,MAAM,WAAW,CAAA;AAChG,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAExC,MAAM,CAAC,MAAM,mBAAmB,GAAG,KAAK,CAAA;AAwBxC,SAAS,UAAU,CAAC,aAAiC;IACnD,OAAO,CACL,aAAa,KAAK,WAAW,IAAI,aAAa,KAAK,KAAK,IAAI,aAAa,KAAK,kBAAkB,CACjG,CAAA;AACH,CAAC;AAED,SAAS,YAAY,CAAC,GAAoB,EAAE,KAAK,GAAG,EAAE,GAAG,IAAI;IAC3D,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,MAAM,GAAa,EAAE,CAAA;QAC3B,IAAI,IAAI,GAAG,CAAC,CAAA;QACZ,GAAG,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE;YAC/B,IAAI,IAAI,KAAK,CAAC,MAAM,CAAA;YACpB,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;gBACjB,MAAM,CAAC,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC,CAAA;gBAC5C,GAAG,CAAC,OAAO,EAAE,CAAA;gBACb,OAAM;YACR,CAAC;YACD,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACpB,CAAC,CAAC,CAAA;QACF,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;YACjB,IAAI,CAAC;gBACH,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAA;YAC7D,CAAC;YAAC,MAAM,CAAC;gBACP,MAAM,CAAC,IAAI,KAAK,CAAC,oBAAoB,CAAC,CAAC,CAAA;YACzC,CAAC;QACH,CAAC,CAAC,CAAA;QACF,GAAG,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;IACzB,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,OAAO,SAAS;IAQS;IAPrB,MAAM,CAAoB;IAC1B,OAAO,GAAG,IAAI,GAAG,EAAsB,CAAA;IACvC,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAA;IACnC,YAAY,CAAQ;IACpB,eAAe,CAAQ;IAChC,UAAU,CAA4C;IAE9D,YAA6B,UAA4B,EAAE;QAA9B,YAAO,GAAP,OAAO,CAAuB;QACzD,IAAI,CAAC,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;QACzD,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,eAAe,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;IACjE,CAAC;IAED,IAAI;QACF,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,EAAE,OAAO,EAAE,CAAA;QACtC,OAAO,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAA;IAC1E,CAAC;IAED,OAAO;QACL,OAAO,oBAAoB,IAAI,CAAC,IAAI,EAAE,EAAE,CAAA;IAC1C,CAAC;IAED,KAAK,CAAC,KAAK;QACT,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,OAAO,EAAE,CAAA;QACtC,IAAI,CAAC,MAAM,GAAG,YAAY,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE;YACtC,KAAK,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;gBACpC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,wBAAwB,EAAE,CAAC,CAAA;YAC1D,CAAC,CAAC,CAAA;QACJ,CAAC,CAAC,CAAA;QACF,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,IAAI,CAAC,MAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;YAChC,IAAI,CAAC,MAAO,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,IAAI,mBAAmB,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAA;QAC7F,CAAC,CAAC,CAAA;QACF,IAAI,CAAC,UAAU,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,MAAM,CAAC,CAAA;QACzD,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,CAAA;QACzB,OAAO,IAAI,CAAC,OAAO,EAAE,CAAA;IACvB,CAAC;IAED,KAAK,CAAC,IAAI;QACR,IAAI,IAAI,CAAC,UAAU;YAAE,aAAa,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACnD,IAAI,CAAC,UAAU,GAAG,SAAS,CAAA;QAC3B,IAAI,CAAC,IAAI,CAAC,MAAM;YAAE,OAAM;QACxB,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;QAC1B,IAAI,CAAC,MAAM,GAAG,SAAS,CAAA;QACvB,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC,CAAA;IACrE,CAAC;IAED,kEAAkE;IAClE,UAAU,CAAC,GAAW,EAAE,QAAgB,UAAU,EAAE;QAClD,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,IAAI,KAAK,CAAC,sBAAsB,CAAC,CAAA;QACxF,IAAI,CAAC,KAAK,EAAE,CAAA;QACZ,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;QAC9D,OAAO,KAAK,CAAA;IACd,CAAC;IAED,4EAA4E;IAC5E,KAAK,CAAC,UAAU,CACd,KAAa,EACb,OAAuE;QAEvE,MAAM,SAAS,GAAG,OAAO,EAAE,SAAS,IAAI,MAAM,CAAA;QAC9C,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,GAAG,CAAA;QACrC,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAA;QACvC,OAAO,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ,EAAE,CAAC;YAC7B,IAAI,OAAO,EAAE,MAAM,EAAE,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAA;YAClE,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,CAAC,CAAA;YACtC,IAAI,IAAI,EAAE,CAAC;gBACT,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;gBAC5B,IAAI,IAAI,CAAC,KAAK;oBAAE,MAAM,IAAI,KAAK,CAAC,iCAAiC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;gBAC9E,OAAO,IAAI,CAAA;YACb,CAAC;YACD,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC,CAAA;QAC7D,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC1B,MAAM,IAAI,KAAK,CAAC,8DAA8D,KAAK,IAAI,CAAC,CAAA;IAC1F,CAAC;IAED,qEAAqE;IACrE,WAAW;QACT,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;aAChC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,KAAK,SAAS,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC;aAChD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAe,CAAC,CAAA;IAClC,CAAC;IAED,YAAY;QACV,IAAI,CAAC,KAAK,EAAE,CAAA;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAA;IAC1B,CAAC;IAEO,KAAK;QACX,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,CAAA;QACtB,KAAK,MAAM,CAAC,KAAK,EAAE,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;YACxC,IAAI,GAAG,GAAG,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,YAAY;gBAAE,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACzE,CAAC;QACD,KAAK,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC3C,IAAI,GAAG,GAAG,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,eAAe;gBAAE,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QACjF,CAAC;IACH,CAAC;IAEO,IAAI,CAAC,GAAmB,EAAE,MAAc,EAAE,IAAa;QAC7D,GAAG,CAAC,SAAS,CAAC,MAAM,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAA;QAC7D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAA;IAC/B,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,GAAoB,EAAE,GAAmB;QAC5D,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC;YAC1C,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,+CAA+C,EAAE,CAAC,CAAA;YAC/E,OAAM;QACR,CAAC;QACD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,GAAG,IAAI,GAAG,EAAE,kBAAkB,CAAC,CAAA;QACvD,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;YAC3D,IAAI,CAAC,KAAK,EAAE,CAAA;YACZ,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAA;YAC7D,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAA;YACpB,OAAM;QACR,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,QAAQ,KAAK,aAAa,EAAE,CAAC;YAC5D,MAAM,IAAI,GAAG,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,CAAuC,CAAA;YAC5E,IAAI,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,0BAA0B,EAAE,CAAC,CAAA;gBAC1D,OAAM;YACR,CAAC;YACD,MAAM,KAAK,GACT,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,UAAU,EAAE,CAAA;YACrF,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,CAAA;YAChC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,CAAC,CAAA;YAC9B,OAAM;QACR,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,MAAM,IAAI,GAAG,CAAC,QAAQ,KAAK,cAAc,EAAE,CAAC;YAC7D,MAAM,IAAI,GAAG,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,CAKpC,CAAA;YACD,IAAI,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBAC9D,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAC,CAAA;gBAC5D,OAAM;YACR,CAAC;YACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,KAAK,EAAE;gBAC7B,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,KAAK,EAAE,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;gBAC9D,QAAQ,EAAE,OAAO,IAAI,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS;gBACvE,KAAK,EAAE,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS;gBAC9D,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE;aACxB,CAAC,CAAA;YACF,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;YACjC,OAAM;QACR,CAAC;QACD,IAAI,GAAG,CAAC,MAAM,KAAK,KAAK,IAAI,GAAG,CAAC,QAAQ,KAAK,YAAY,EAAE,CAAC;YAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,CAAA;YACjC,OAAM;QACR,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,EAAE,EAAE,KAAK,EAAE,2BAA2B,EAAE,CAAC,CAAA;IAC7D,CAAC;CACF"}

package/extension/README.md

@@ -0,0 +1,33 @@
+# Pi extension — Existing-mode tab broker
+
+Load this unpacked extension into your daily Chrome to let Pi open
+background tabs in the collapsed `pi-browser-use` group (spec sections
+14–18). Without it, `browser_open_background_tab` fails clearly instead of
+opening unmanaged foreground tabs.
+
+## Install (load unpacked)
+
+1. Open `chrome://extensions`.
+2. Enable **Developer mode** (top right).
+3. **Load unpacked** → select this `extension/` directory.
+4. Confirm `pi-browser-use` appears and stays enabled.
+
+The broker polls Pi's loopback tab bridge (`http://127.0.0.1:31973` by
+default, override via `tabBridgePort` in `pi-browser-use` settings plus the
+extension's stored `piBridgeUrl`) for open-tab requests, creates each tab
+inactive in the `pi-browser-use` group, keeps the group collapsed, and
+reports back per-token so Pi selects the exact tab — never by URL matching.
+
+## Permissions
+
+- `tabs` / `tabGroups` — create inactive tabs, query the group by title,
+  enforce `collapsed: true`.
+- `storage` — optional `piBridgeUrl` override.
+- Loopback host access — bridge polling only; no remote hosts.
+
+## Notes
+
+- Group IDs are session-scoped: the broker always queries by title and
+  recreates the group when absent.
+- The broker never focuses windows or activates tabs; only an explicit
+  `bringToFront` from Pi (user-requested view / auth handoff) does that.

package/extension/background.js

@@ -0,0 +1,185 @@
+/**
+ * Pi Existing-mode tab broker (spec sections 14-18).
+ *
+ * All Pi-created tabs in the user's own Chrome must:
+ *   1. open inactive (active: false — never focus the browser),
+ *   2. live in a normal existing window (never a popup/devtools window),
+ *   3. enter the group named exactly "pi-browser-use",
+ *   4. leave that group collapsed,
+ *   5. never activate or focus any window as part of lookup/creation.
+ *
+ * Group IDs are valid for the current browser session only, so the group is
+ * always queried by title and recreated when absent — never persisted.
+ */
+
+const PI_GROUP_TITLE = 'pi-browser-use'
+
+/**
+ * Prefer the user's last-focused normal window without focusing anything.
+ * Window lookup is read-only: never mark a window focused during lookup.
+ */
+async function getTargetNormalWindow() {
+  const windows = await chrome.windows.getAll({ populate: false, windowTypes: ['normal'] })
+  // getAll does not guarantee focus order; getLastFocused is the closest
+  // signal, verified to be a normal window before use.
+  let lastFocused = null
+  try {
+    lastFocused = await chrome.windows.getLastFocused({ populate: false })
+  } catch {
+    lastFocused = null
+  }
+  if (lastFocused && lastFocused.type === 'normal' && lastFocused.id !== undefined) {
+    return lastFocused
+  }
+  const candidate = windows.find((w) => w.id !== undefined)
+  if (candidate) return candidate
+  // No normal window exists: create one. The new window keeps focus wherever
+  // the OS puts it; we never move focus afterwards.
+  return chrome.windows.create({ focused: false, type: 'normal' })
+}
+
+/**
+ * Create one Pi tab: inactive, grouped, group collapsed afterwards so the
+ * collapse state is deterministic even if the user expanded the group.
+ */
+async function openPiTab(url) {
+  const targetWindow = await getTargetNormalWindow()
+
+  const tab = await chrome.tabs.create({
+    windowId: targetWindow.id,
+    url,
+    active: false,
+  })
+
+  if (tab.id == null) {
+    throw new Error('Chrome did not return a tab ID')
+  }
+
+  const groups = await chrome.tabGroups.query({
+    title: PI_GROUP_TITLE,
+    windowId: targetWindow.id,
+  })
+
+  let groupId
+  if (groups.length > 0) {
+    groupId = groups[0].id
+    await chrome.tabs.group({ groupId, tabIds: [tab.id] })
+  } else {
+    groupId = await chrome.tabs.group({
+      tabIds: [tab.id],
+      createProperties: { windowId: targetWindow.id },
+    })
+  }
+
+  await chrome.tabGroups.update(groupId, {
+    title: PI_GROUP_TITLE,
+    collapsed: true,
+  })
+
+  return tab
+}
+
+/**
+ * Message contract for the ExistingSession handoff (spec section 18):
+ *   { type: 'pi-open-tab', url, token? } -> { ok: true, tabId, windowId, token? }
+ * The optional token lets Pi correlate the exact target without relying on
+ * "first tab whose URL matches" (duplicate URLs are common).
+ */
+chrome.runtime.onMessage.addListener((message, _sender, sendResponse) => {
+  if (!message || message.type !== 'pi-open-tab' || typeof message.url !== 'string') {
+    return false
+  }
+  openPiTab(message.url)
+    .then((tab) =>
+      sendResponse({
+        ok: true,
+        tabId: tab.id,
+        windowId: tab.windowId,
+        token: message.token ?? null,
+      })
+    )
+    .catch((error) =>
+      sendResponse({ ok: false, error: String(error && error.message ? error.message : error) })
+    )
+  // Poll now: a direct message means Pi is waiting on the bridge too.
+  void pollBridgeOnce().catch(() => {})
+  return true
+})
+
+/**
+ * Loopback bridge poller: Pi's tab-bridge server queues open-tab requests
+ * at GET /v1/pending and accepts per-token reports at POST /v1/complete.
+ * The bridge URL override lives in local storage (default loopback port).
+ */
+const PI_BRIDGE_DEFAULT_URL = 'http://127.0.0.1:31973'
+const PI_BRIDGE_POLL_MS = 2000
+let piBridgeUrlOverride = null
+
+try {
+  chrome.storage?.local.get('piBridgeUrl', (stored) => {
+    if (stored && typeof stored.piBridgeUrl === 'string' && stored.piBridgeUrl.length > 0) {
+      piBridgeUrlOverride = stored.piBridgeUrl
+    }
+  })
+} catch {
+  // Storage unavailable: the default loopback URL still applies.
+}
+
+async function pollBridgeOnce() {
+  const base = piBridgeUrlOverride ?? PI_BRIDGE_DEFAULT_URL
+  let pending
+  try {
+    const response = await fetch(`${base}/v1/pending`)
+    if (!response.ok) return
+    pending = await response.json()
+  } catch {
+    return // Bridge not running: stay quiet until the next poll.
+  }
+  const requests = Array.isArray(pending?.requests) ? pending.requests : []
+  for (const request of requests) {
+    if (!request || typeof request.url !== 'string' || typeof request.token !== 'string') continue
+    try {
+      const tab = await openPiTab(request.url)
+      await fetch(`${base}/v1/complete`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ token: request.token, tabId: tab.id, windowId: tab.windowId }),
+      })
+    } catch (error) {
+      try {
+        await fetch(`${base}/v1/complete`, {
+          method: 'POST',
+          headers: { 'content-type': 'application/json' },
+          body: JSON.stringify({
+            token: request.token,
+            error: String(error && error.message ? error.message : error),
+          }),
+        })
+      } catch {
+        // The completion report is best-effort; Pi times out and fails
+        // clearly rather than opening an unmanaged tab.
+      }
+    }
+  }
+}
+
+setInterval(() => {
+  void pollBridgeOnce().catch(() => {})
+}, PI_BRIDGE_POLL_MS)
+
+/**
+ * MV3 service workers are short-lived: setInterval dies permanently once the
+ * worker is evicted, so the fast poll above only covers the awake case. The
+ * repeating alarm wakes a suspended worker and guarantees a poll at least
+ * every minute (safe floor for the alarm cadence). Re-created on every
+ * startup since alarm persistence across restarts is not guaranteed.
+ */
+const PI_BRIDGE_ALARM = 'pi-bridge-poll'
+try {
+  chrome.alarms?.create(PI_BRIDGE_ALARM, { periodInMinutes: 1 })
+  chrome.alarms?.onAlarm.addListener((alarm) => {
+    if (alarm && alarm.name === PI_BRIDGE_ALARM) void pollBridgeOnce().catch(() => {})
+  })
+} catch {
+  // Alarms unavailable: the interval poll remains the only trigger.
+}

package/extension/manifest.json

@@ -0,0 +1,12 @@
+{
+  "manifest_version": 3,
+  "name": "Pi Browser Use — Existing-mode tab broker",
+  "version": "0.2.0",
+  "description": "Brokers Pi-created tabs into the collapsed pi-browser-use group without stealing focus.",
+  "permissions": ["tabs", "tabGroups", "storage", "alarms"],
+  "host_permissions": ["http://127.0.0.1/*"],
+  "background": {
+    "service_worker": "background.js"
+  },
+  "minimum_chrome_version": "89"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-browser-use",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "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",
@@ -39,6 +39,7 @@
   },
   "files": [
     "dist",
+    "extension",
     "skills",
     "README.md"
   ],

package/skills/auth-bootstrap/SKILL.md

@@ -29,6 +29,19 @@ cp -R ~/Library/Application\ Support/Google/Chrome/Default ~/.pi/browser-profile
 
 Same macOS user, so Keychain-bound cookies and passwords decrypt fine. Prefer the headed-once flow unless you have dozens of logins — clones carry sync state, extensions, and version skew that cause strange breakage. Never copy while Chrome runs; you'll corrupt both ends.
 
+## Google SSO says "browser or app may not be secure"
+
+Expected: Google rejects sign-in from automation-driven Chrome
+(`--enable-automation`, debugging pipe, fresh profile with no history).
+Don't fight it — use one of these instead:
+
+1. **Email + password** on the login form (no Google involved).
+2. **Your daily browser**, which Google already trusts (real history, no
+   automation flags). Point the session at it temporarily with
+   `mode: existing` and drive the flow there, then switch back.
+3. Complete SSO there once; the persistent profile keeps the resulting
+   Cloudflare session cookies either way.
+
 ## What not to do
 
 - **Paste passwords or TOTP codes into chat.** The agent never needs them — type directly in the headed window.

package/skills/browser-policy/SKILL.md

@@ -15,10 +15,10 @@ description: "Browser-use policy for Pi agents. Use before any browser_* tool ca
 
 ## Session modes
 
-- **Default: fresh headless** (`mode: fresh`). Ephemeral profile, no window, never steals focus. Use for public pages and smoke checks.
-- **Authenticated profile** (`mode: persistent`). Log in once in `~/.pi/browser-profile`; cookies persist. Use when the task needs your identity (private repos, Cloudflare dashboard). Both modes default headless — pass `headed: true` to watch, and warn the user before any headed launch.
-- **Existing Chrome** (`mode: existing`) is intrusive (drives the user's daily browser, sees all tabs). Avoid unless the user explicitly asks.
-- **Switch, don't restart**: `browser_switch_mode` moves between fresh and persistent mid-session. Start fresh; escalate to persistent on login walls; drop back to fresh for clean-room checks.
+- **Default: persistent headless** (`mode: persistent`). Pi's own browser on its dedicated profile (`~/.pi/browser-profile`): self-launched Chrome, no window, never steals focus, no consent popups. Log in once via `browser_setup`; cookies persist. Use for everything unless there's a reason not to. Pass `headed: true` to watch, and warn the user before any headed launch.
+- **Clean room** (`mode: fresh`). Ephemeral profile, thrown away each session. Use for anonymous checks, hostile links, and "does it render logged-out?" verifications — never for anything needing identity.
+- **Existing Chrome** (`mode: existing`) attaches to the user's running Chrome — intrusive (drives the daily browser, sees all tabs). Avoid unless the user explicitly asks. First attach shows Chrome's "Allow remote debugging?" consent popup (once per session — click Allow). Pi tabs must be opened with `browser_open_background_tab` (extension-brokered into the collapsed `pi-browser-use` group), never raw `browser_new_page`. Closing the last Pi tab dissolves the group automatically; `browser_close_page` refuses tabs Pi didn't open unless `force: true` was explicitly requested.
+- **Switch, don't restart**: `browser_switch_mode` moves between persistent, fresh, and existing mid-session. Start persistent; drop to fresh for clean-room checks; touch existing only when the user explicitly asks.
 - **Hard blocks escalate themselves**: login walls in fresh sessions suggest the switch call; login walls and bot challenges in authenticated sessions rebuild headed and prompt the human. Once per call, never looping, never in attached sessions — and a headed popup from a block is the one case where stealing focus is the job, not a bug.
 - **Visual analysis** (`browser_analyze_screenshot`, only when `visionModel` is configured) is for canvas/WebGL scenes and coordinate clicks the tree cannot describe — not a substitute for reading the snapshot first.
 
@@ -28,8 +28,33 @@ description: "Browser-use policy for Pi agents. Use before any browser_* tool ca
 
 Turnstile, device checks, SSO/2FA cannot be automated away. On hitting one: stop, report which profile is parked where, and ask the human to solve it once in that profile. Never loop retries against a challenge page.
 
+- First run: `browser_setup` opens the plain setup window; the human signs in and closes it.
+- Expired session: `browser_reauth` shuts headless Chrome down cleanly, opens headed verification, then resumes headless. `variant: plain` is the maximum-compatibility fallback for providers that reject instrumented browsers.
+- Site auth checks live in per-site skills (`gmail-auth` for Gmail); the browser layer only runs the headed/headless transitions.
+
+## Status and diagnostics
+
+- `browser_status`: plain-language state (profile readiness, execution mode, next step). Check it before assuming auth works — bootstrap initializes the profile, it never proves a site session.
+- `browser_doctor`: technical diagnostics (backend ownership, profile health, tab-bridge URL). Run it first when tools misbehave.
+
 ## Safety
 
 - Mutating actions (save, deploy, merge, delete) need explicit user approval.
 - Prefer `allowedUrlPattern` to cage the session to the task domains.
 - `redactNetworkHeaders` stays on; never paste secrets into pages.
+
+## Browser mode rules
+
+1. Prefer Persistent (the default) for everything: Pi's browser, invisible, no popups.
+2. Use Fresh only for anonymous/stateless browsing: hostile links, logged-out checks, clean-room reproductions.
+3. Persistent uses Pi's dedicated browser profile — never the user's daily Chrome data.
+4. If Persistent has never been initialized, launch the Pi Browser setup flow (headed once, human signs in, close the window).
+5. Never attempt to automate credentials, CAPTCHA, 2FA, passkeys, or security challenges that require the user.
+6. When authentication is required, request the headed authentication flow.
+7. After authentication, prefer restarting Persistent headless.
+8. If a site fails specifically because it is headless, retry using Persistent headed-background (per-origin; never downgrade every site).
+9. In headed-background mode, never request foreground focus unless the user explicitly asked to watch or Pi is handing over auth.
+10. Use Existing only when the user explicitly chose it or Persistent cannot provide the required existing browser/session state.
+11. In Existing mode, all new Pi tabs must be created through the Pi extension and placed in the collapsed `pi-browser-use` group.
+12. Never activate Pi-created Existing-mode tabs by default.
+13. Never close or modify unrelated user tabs; on session end close only Pi-owned tabs.

package/skills/gmail-auth/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: gmail-auth
+description: "Verify Gmail authentication in the persistent Pi browser profile. Use when a task needs the Gmail inbox, after browser_setup, or when Google shows a login or verification challenge."
+---
+
+# Gmail Auth
+
+Authentication state lives in this skill, not in a generic browser heuristic: only Gmail's inbox DOM proves the `mail.google.com` session is live. A signed-in Chrome profile and an authenticated Gmail session are different states — never conflate them.
+
+## Verify first
+
+```text
+browser_open_background_tab({ "url": "https://mail.google.com/" })
+browser_take_snapshot({ "pageId": <id> })
+```
+
+Or in persistent mode, navigate directly — the persistent profile is Pi's browser, no tab group needed.
+
+## Authenticated
+
+Inbox markers: `Inbox`, `Primary`, `Compose`, `Search mail`, conversation rows on a `mail.google.com` URL. Proceed with the task.
+
+## Login or challenge
+
+`accounts.google.com` URL (`signin`, `ServiceLogin`, `challenge`, `password`, `otp`, `verification`) or challenge copy (`Verify it's you`, `2-Step Verification`, `Enter your password`, `Choose an account to continue`) means human auth is required:
+
+```text
+browser_reauth({ "url": "https://mail.google.com/" })
+```
+
+Complete verification in the headed window, then resume headless. Never paste passwords, TOTP codes, or passkeys into chat — type directly in the window.
+
+If the provider rejects the instrumented window ("browser or app may not be secure"), retry with the maximum-compatibility variant:
+
+```text
+browser_reauth({ "url": "https://mail.google.com/", "variant": "plain" })
+```
+
+## Headless vs headed
+
+If Gmail works headed but not headless on the same profile, pin the fallback for this site only:
+
+```text
+browser_switch_mode({ "mode": "persistent", "headed": true, "rememberSite": true })
+```
+
+Never downgrade every site because one site rejects headless.
+
+## First run
+
+Empty profile (`browser_status` says `Setup required`): run `browser_setup` once, sign in, close the window. Bootstrap initializes the profile; this skill's inbox check is still what proves Gmail works.