pi-browser-use 0.6.1 → 0.8.0

package/dist/shared-backend.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Shared-backend registry + per-agent page ownership (multi-agent support).
+ *
+ * Many Pi agents share one Pi-owned Chrome: the first backend writes
+ * `<profile>.backend.json` ({ pid, browserUrl, sessionId, startedAt });
+ * latecomers attach to that browserUrl instead of launching a second Chrome
+ * (the profile lock still forbids two processes — sharing is by attach).
+ *
+ * Tab separation is by ownership, not visuals: every page a Pi session opens
+ * (or Pi-navigates, in shared modes) is recorded in `<profile>.pages.json`
+ * with its owner session. Entries whose owner pid is dead are pruned
+ * lazily. The close guard refuses pages owned by another *live* session.
+ *
+ * Page-id routing (upstream `experimentalPageIdRouting`) plus explicit
+ * pageIds on every call keeps agents from driving each other's tabs; this
+ * registry adds the missing pieces: discovery, ownership, and cleanup scope.
+ */
+import type { McpPageEntry } from './existing-flow.js';
+export interface BackendAdvert {
+    pid: number;
+    browserUrl: string;
+    port: number;
+    sessionId: string;
+    startedAt: string;
+}
+export declare function backendAdvertPathFor(profileDir: string): string;
+/** This process's agent-session identity (one per extension load). */
+export declare function newSessionId(): string;
+/** Publish this backend for peer agents. Overwrites stale entries. */
+export declare function advertiseBackend(profileDir: string, advert: BackendAdvert): void;
+/** Read a live peer advert, or undefined (absent/corrupt/dead owner). */
+export declare function readLiveAdvert(profileDir: string): BackendAdvert | undefined;
+/** Withdraw our advert (backend shutdown). Best effort. */
+export declare function withdrawAdvert(profileDir: string, sessionId: string): void;
+export interface PageOwner {
+    sessionId: string;
+    pid: number;
+}
+export interface OwnedPage {
+    pageId: number;
+    url?: string;
+    title?: string;
+    owner: PageOwner;
+    openedAt: string;
+}
+export declare function pageRegistryPathFor(profileDir: string): string;
+/** Drop entries whose owner process is gone. */
+export declare function pruneDeadOwners(profileDir: string): OwnedPage[];
+/** Claim a page for a session (open or Pi-navigate). */
+export declare function claimPage(profileDir: string, page: McpPageEntry, owner: PageOwner, at?: string): void;
+/** Release one page (closed) or all of a session's pages (shutdown). */
+export declare function releasePages(profileDir: string, filter: {
+    pageId?: number;
+    sessionId?: string;
+}): void;
+/** Live sessions currently holding pages (peers to avoid disturbing). */
+export declare function livePeerSessions(profileDir: string): PageOwner[];
+export type CloseVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Shared-mode close verdict: our own or unclaimed pages may close; pages
+ * owned by another live session need explicit force. Stale ids fail safe
+ * with a re-list hint (ids shift when tabs close).
+ */
+export declare function checkSharedCloseAllowed(entries: McpPageEntry[], pageId: number, profileDir: string, self: PageOwner, ownedUrls: ReadonlySet<string>): CloseVerdict;
+//# sourceMappingURL=shared-backend.d.ts.map

package/dist/shared-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-backend.d.ts","sourceRoot":"","sources":["../src/shared-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAA;AAEtD,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE/D;AAWD,sEAAsE;AACtE,wBAAgB,YAAY,IAAI,MAAM,CAErC;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAGhF;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAgB5E;AAED,2DAA2D;AAC3D,wBAAgB,cAAc,CAAC,UAAU,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI,CAO1E;AAED,MAAM,WAAW,SAAS;IACxB,SAAS,EAAE,MAAM,CAAA;IACjB,GAAG,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,mBAAmB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAE9D;AAwBD,gDAAgD;AAChD,wBAAgB,eAAe,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,CAI/D;AAED,wDAAwD;AACxD,wBAAgB,SAAS,CACvB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE,SAAS,EAChB,EAAE,SAA2B,GAC5B,IAAI,CAIN;AAED,wEAAwE;AACxE,wBAAgB,YAAY,CAC1B,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GAC9C,IAAI,CAON;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,EAAE,CAMhE;AAED,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvE;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,YAAY,EAAE,EACvB,MAAM,EAAE,MAAM,EACd,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,SAAS,EACf,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,GAC7B,YAAY,CAyBd"}

package/dist/shared-backend.js

@@ -0,0 +1,152 @@
+/**
+ * Shared-backend registry + per-agent page ownership (multi-agent support).
+ *
+ * Many Pi agents share one Pi-owned Chrome: the first backend writes
+ * `<profile>.backend.json` ({ pid, browserUrl, sessionId, startedAt });
+ * latecomers attach to that browserUrl instead of launching a second Chrome
+ * (the profile lock still forbids two processes — sharing is by attach).
+ *
+ * Tab separation is by ownership, not visuals: every page a Pi session opens
+ * (or Pi-navigates, in shared modes) is recorded in `<profile>.pages.json`
+ * with its owner session. Entries whose owner pid is dead are pruned
+ * lazily. The close guard refuses pages owned by another *live* session.
+ *
+ * Page-id routing (upstream `experimentalPageIdRouting`) plus explicit
+ * pageIds on every call keeps agents from driving each other's tabs; this
+ * registry adds the missing pieces: discovery, ownership, and cleanup scope.
+ */
+import { existsSync, readFileSync, rmSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { randomUUID } from 'node:crypto';
+export function backendAdvertPathFor(profileDir) {
+    return `${profileDir}.backend.json`;
+}
+function isPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** This process's agent-session identity (one per extension load). */
+export function newSessionId() {
+    return randomUUID();
+}
+/** Publish this backend for peer agents. Overwrites stale entries. */
+export function advertiseBackend(profileDir, advert) {
+    mkdirSync(dirname(backendAdvertPathFor(profileDir)), { recursive: true });
+    writeFileSync(backendAdvertPathFor(profileDir), `${JSON.stringify(advert, null, 2)}\n`, 'utf8');
+}
+/** Read a live peer advert, or undefined (absent/corrupt/dead owner). */
+export function readLiveAdvert(profileDir) {
+    try {
+        const advert = JSON.parse(readFileSync(backendAdvertPathFor(profileDir), 'utf8'));
+        if (typeof advert?.browserUrl !== 'string' ||
+            typeof advert?.pid !== 'number' ||
+            !isPidAlive(advert.pid)) {
+            return undefined;
+        }
+        return advert;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Withdraw our advert (backend shutdown). Best effort. */
+export function withdrawAdvert(profileDir, sessionId) {
+    try {
+        const raw = JSON.parse(readFileSync(backendAdvertPathFor(profileDir), 'utf8'));
+        if (raw?.sessionId === sessionId)
+            rmSync(backendAdvertPathFor(profileDir), { force: true });
+    }
+    catch {
+        // Another backend already replaced it; leave it alone.
+    }
+}
+export function pageRegistryPathFor(profileDir) {
+    return `${profileDir}.pages.json`;
+}
+function readRegistry(profileDir) {
+    try {
+        const raw = JSON.parse(readFileSync(pageRegistryPathFor(profileDir), 'utf8'));
+        if (!Array.isArray(raw))
+            return [];
+        return raw.filter((entry) => typeof entry === 'object' &&
+            entry !== null &&
+            typeof entry.pageId === 'number' &&
+            typeof entry.owner?.sessionId === 'string' &&
+            typeof entry.owner?.pid === 'number');
+    }
+    catch {
+        return [];
+    }
+}
+function writeRegistry(profileDir, pages) {
+    mkdirSync(dirname(pageRegistryPathFor(profileDir)), { recursive: true });
+    writeFileSync(pageRegistryPathFor(profileDir), `${JSON.stringify(pages, null, 2)}\n`, 'utf8');
+}
+/** Drop entries whose owner process is gone. */
+export function pruneDeadOwners(profileDir) {
+    const live = readRegistry(profileDir).filter((entry) => isPidAlive(entry.owner.pid));
+    writeRegistry(profileDir, live);
+    return live;
+}
+/** Claim a page for a session (open or Pi-navigate). */
+export function claimPage(profileDir, page, owner, at = new Date().toISOString()) {
+    const pages = pruneDeadOwners(profileDir).filter((entry) => entry.pageId !== page.pageId);
+    pages.push({ pageId: page.pageId, url: page.url, title: page.title, owner, openedAt: at });
+    writeRegistry(profileDir, pages);
+}
+/** Release one page (closed) or all of a session's pages (shutdown). */
+export function releasePages(profileDir, filter) {
+    const pages = pruneDeadOwners(profileDir).filter((entry) => {
+        if (filter.pageId !== undefined && entry.pageId === filter.pageId)
+            return false;
+        if (filter.sessionId !== undefined && entry.owner.sessionId === filter.sessionId)
+            return false;
+        return true;
+    });
+    writeRegistry(profileDir, pages);
+}
+/** Live sessions currently holding pages (peers to avoid disturbing). */
+export function livePeerSessions(profileDir) {
+    const seen = new Map();
+    for (const entry of pruneDeadOwners(profileDir)) {
+        if (!seen.has(entry.owner.sessionId))
+            seen.set(entry.owner.sessionId, entry.owner);
+    }
+    return [...seen.values()];
+}
+/**
+ * Shared-mode close verdict: our own or unclaimed pages may close; pages
+ * owned by another live session need explicit force. Stale ids fail safe
+ * with a re-list hint (ids shift when tabs close).
+ */
+export function checkSharedCloseAllowed(entries, pageId, profileDir, self, ownedUrls) {
+    const target = entries.find((entry) => entry.pageId === pageId);
+    if (!target) {
+        return {
+            ok: false,
+            reason: `No page ${pageId} is currently open. Re-list pages; page IDs shift when tabs close.`,
+        };
+    }
+    const claim = pruneDeadOwners(profileDir).find((entry) => entry.pageId === pageId);
+    if (claim && claim.owner.sessionId !== self.sessionId) {
+        return {
+            ok: false,
+            reason: `Refusing to close page ${pageId} (${claim.owner.sessionId.slice(0, 8)}'s tab${target.title ? ` "${target.title}"` : ''}): ` +
+                `another live agent session owns it. Pass force:true only if the user explicitly asked for this exact tab.`,
+        };
+    }
+    const url = target.url ?? '';
+    if (claim || url === '' || ownedUrls.has(url))
+        return { ok: true };
+    return {
+        ok: false,
+        reason: `Refusing to close page ${pageId} (${target.title ?? url ?? 'unknown tab'}): ` +
+            `this session did not open it. Pass force:true only if the user explicitly asked for this exact tab.`,
+    };
+}
+//# sourceMappingURL=shared-backend.js.map

package/dist/shared-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared-backend.js","sourceRoot":"","sources":["../src/shared-backend.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACpF,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AACnC,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAWxC,MAAM,UAAU,oBAAoB,CAAC,UAAkB;IACrD,OAAO,GAAG,UAAU,eAAe,CAAA;AACrC,CAAC;AAED,SAAS,UAAU,CAAC,GAAW;IAC7B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAA;QACpB,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAA;IACd,CAAC;AACH,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,YAAY;IAC1B,OAAO,UAAU,EAAE,CAAA;AACrB,CAAC;AAED,sEAAsE;AACtE,MAAM,UAAU,gBAAgB,CAAC,UAAkB,EAAE,MAAqB;IACxE,SAAS,CAAC,OAAO,CAAC,oBAAoB,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACzE,aAAa,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AACjG,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,cAAc,CAAC,UAAkB;IAC/C,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CACvB,YAAY,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CACtC,CAAA;QAClB,IACE,OAAO,MAAM,EAAE,UAAU,KAAK,QAAQ;YACtC,OAAO,MAAM,EAAE,GAAG,KAAK,QAAQ;YAC/B,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,CAAC,EACvB,CAAC;YACD,OAAO,SAAS,CAAA;QAClB,CAAC;QACD,OAAO,MAAM,CAAA;IACf,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,2DAA2D;AAC3D,MAAM,UAAU,cAAc,CAAC,UAAkB,EAAE,SAAiB;IAClE,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAkB,CAAA;QAC/F,IAAI,GAAG,EAAE,SAAS,KAAK,SAAS;YAAE,MAAM,CAAC,oBAAoB,CAAC,UAAU,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAA;IAC7F,CAAC;IAAC,MAAM,CAAC;QACP,uDAAuD;IACzD,CAAC;AACH,CAAC;AAeD,MAAM,UAAU,mBAAmB,CAAC,UAAkB;IACpD,OAAO,GAAG,UAAU,aAAa,CAAA;AACnC,CAAC;AAED,SAAS,YAAY,CAAC,UAAkB;IACtC,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,mBAAmB,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,CAAY,CAAA;QACxF,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,CAAA;QAClC,OAAO,GAAG,CAAC,MAAM,CACf,CAAC,KAAK,EAAsB,EAAE,CAC5B,OAAO,KAAK,KAAK,QAAQ;YACzB,KAAK,KAAK,IAAI;YACd,OAAQ,KAAmB,CAAC,MAAM,KAAK,QAAQ;YAC/C,OAAQ,KAAmB,CAAC,KAAK,EAAE,SAAS,KAAK,QAAQ;YACzD,OAAQ,KAAmB,CAAC,KAAK,EAAE,GAAG,KAAK,QAAQ,CACtD,CAAA;IACH,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAA;IACX,CAAC;AACH,CAAC;AAED,SAAS,aAAa,CAAC,UAAkB,EAAE,KAAkB;IAC3D,SAAS,CAAC,OAAO,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;IACxE,aAAa,CAAC,mBAAmB,CAAC,UAAU,CAAC,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AAC/F,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,eAAe,CAAC,UAAkB;IAChD,MAAM,IAAI,GAAG,YAAY,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAA;IACpF,aAAa,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;IAC/B,OAAO,IAAI,CAAA;AACb,CAAC;AAED,wDAAwD;AACxD,MAAM,UAAU,SAAS,CACvB,UAAkB,EAClB,IAAkB,EAClB,KAAgB,EAChB,EAAE,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;IAE7B,MAAM,KAAK,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,IAAI,CAAC,MAAM,CAAC,CAAA;IACzF,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,EAAE,EAAE,CAAC,CAAA;IAC1F,aAAa,CAAC,UAAU,EAAE,KAAK,CAAC,CAAA;AAClC,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,YAAY,CAC1B,UAAkB,EAClB,MAA+C;IAE/C,MAAM,KAAK,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE;QACzD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM;YAAE,OAAO,KAAK,CAAA;QAC/E,IAAI,MAAM,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS,KAAK,MAAM,CAAC,SAAS;YAAE,OAAO,KAAK,CAAA;QAC9F,OAAO,IAAI,CAAA;IACb,CAAC,CAAC,CAAA;IACF,aAAa,CAAC,UAAU,EAAE,KAAK,CAAC,CAAA;AAClC,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,gBAAgB,CAAC,UAAkB;IACjD,MAAM,IAAI,GAAG,IAAI,GAAG,EAAqB,CAAA;IACzC,KAAK,MAAM,KAAK,IAAI,eAAe,CAAC,UAAU,CAAC,EAAE,CAAC;QAChD,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,SAAS,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IACpF,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAA;AAC3B,CAAC;AAID;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CACrC,OAAuB,EACvB,MAAc,EACd,UAAkB,EAClB,IAAe,EACf,SAA8B;IAE9B,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAA;IAC/D,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EAAE,WAAW,MAAM,oEAAoE;SAC9F,CAAA;IACH,CAAC;IACD,MAAM,KAAK,GAAG,eAAe,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,KAAK,MAAM,CAAC,CAAA;IAClF,IAAI,KAAK,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS,KAAK,IAAI,CAAC,SAAS,EAAE,CAAC;QACtD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,MAAM,EACJ,0BAA0B,MAAM,KAAK,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,SAAS,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,KAAK,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK;gBAC5H,2GAA2G;SAC9G,CAAA;IACH,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,GAAG,IAAI,EAAE,CAAA;IAC5B,IAAI,KAAK,IAAI,GAAG,KAAK,EAAE,IAAI,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;IAClE,OAAO;QACL,EAAE,EAAE,KAAK;QACT,MAAM,EACJ,0BAA0B,MAAM,KAAK,MAAM,CAAC,KAAK,IAAI,GAAG,IAAI,aAAa,KAAK;YAC9E,qGAAqG;KACxG,CAAA;AACH,CAAC"}

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":"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"}

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.