pi-browser-use 0.6.0 → 0.7.0

package/README.md

@@ -4,10 +4,11 @@ Opinionated browser-use for the [Pi coding agent](https://pi.dev), powered by [`
 
 ## Why this exists
 
-- **Fresh headless by default** — isolated ephemeral profile, no window, never steals focus.
-- **Authenticated profile opt-in** — `sessionMode: persistent` persists `~/.pi/browser-profile` (log in once).
+- **Persistent Pi browser by default** — self-launched headless Chrome on `~/.pi/browser-profile` (log in once via `browser_setup`); MCP attaches over an ephemeral loopback port. No window, no focus steal, no consent popups.
+- **Fresh clean room on request** — `mode: fresh` for anonymous checks; nothing persists.
+- **Existing-Chrome escape hatch** — `mode: existing` brokers background tabs into the collapsed `pi-browser-use` group via the bundled extension (`extension/`).
 - **CLI-first policy bundled** — `skills/browser-policy` tells agents to prefer `gh` / `wrangler` / APIs and web fetching before driving the browser.
-- **Safer proxying** — `browser_`-prefixed tools, noisy/privileged tools excluded, sensitive network headers redacted.
+- **Safer proxying** — `browser_`-prefixed tools, noisy/privileged tools excluded, sensitive network headers redacted, background/focus-safe page defaults.
 
 Not affiliated with `@amaster.ai/pi-browser-use` or `@narumitw/pi-chrome-devtools`.
 
@@ -26,18 +27,20 @@ Settings key is `pi-browser-use` in `~/.pi/agent/settings.json` (user) or `.pi/s
 ```json
 {
   "pi-browser-use": {
-    "mode": "fresh",
+    "mode": "persistent",
     "headed": false,
     "visionModel": { "provider": "openai", "model": "gpt-4o" }
   }
 }
 ```
 
-| `mode`            | Behavior                                                    |
-| ----------------- | ----------------------------------------------------------- |
-| `fresh` (default) | Isolated clean room, thrown away each session               |
-| `persistent`      | Saved profile with your logins (`~/.pi/browser-profile`)    |
-| `existing`        | Attach to your running Chrome — intrusive, avoid by default |
+`persistent` is already the default; the snippet above pins it explicitly. There is no consent popup in this mode — Chrome's per-session "Allow remote debugging?" gate applies to `existing` only.
+
+| `mode`                 | Behavior                                                                     |
+| ---------------------- | ---------------------------------------------------------------------------- |
+| `persistent` (default) | Pi's own browser: saved profile with your logins (`~/.pi/browser-profile`)   |
+| `fresh`                | Isolated clean room, thrown away each session                                |
+| `existing`             | Attach to your running Chrome — consent popup each session, avoid by default |
 
 `headed: true` shows the window (both modes default headless); `existing` is always headed. `visionModel` enables `browser_analyze_screenshot`; omit it and the tool stays unregistered.
 
@@ -68,6 +71,7 @@ Per-project identity composes: user settings set the default, trusted project se
 | `viewport`             | `string`   | —          | Initial viewport, e.g. `1280x720`                                              |
 | `userDataDir`          | `string`   | —          | Custom profile dir (persistent mode defaults to `~/.pi/browser-profile`)       |
 | `autoConnect`          | `boolean`  | `false`    | Auto-attach to a local running Chrome (implies `existing`)                     |
+| `tabBridgePort`        | `number`   | `31973`    | Loopback port for the Existing-mode tab-broker bridge (`0` disables it)        |
 | `chromeArgs`           | `string[]` | —          | First-class Chrome flags, forwarded as `--chrome-arg=`                         |
 | `extraArgs`            | `string[]` | —          | Raw escape hatch, forwarded verbatim to `chrome-devtools-mcp`                  |
 | `visionModel`          | `object`   | —          | `{ provider, model }` from Pi's registry; enables `browser_analyze_screenshot` |
@@ -82,6 +86,8 @@ First-class `chromeArgs` only apply when `chrome-devtools-mcp` launches Chrome i
 
 Hosts where `process.execPath` is not a directly executable Node runtime can set `PI_BROWSER_USE_NODE` to the Node command used for the MCP subprocess.
 
+Persistent mode self-launches Pi-owned Chrome and attaches MCP via `browserUrl`. Set `PI_BROWSER_USE_LEGACY_PERSISTENT=1` to restore the pre-Phase-2 behavior (MCP launches Chrome itself).
+
 ## Tools
 
 Upstream `chrome-devtools-mcp` tools are proxied as `browser_*` (navigation, snapshot, click/fill/hover/drag/type, emulation, console, network, screenshots, dialogs, uploads, waits). Noisy, slow, or privileged ones (`lighthouse_audit`, performance traces, screencast, extension management) are excluded. On top, this package adds:
@@ -105,11 +111,27 @@ browser_save_artifact({ "pageId": 1, "kind": "screenshot", "annotate": true })
 
 ### `browser_switch_mode`
 
-Switch backends without restarting: `fresh` (isolated clean room) or `persistent` (saved profile with your logins). Both default to headless — pass `headed: true` to watch. Tabs do not transfer; call `browser_list_pages` after switching. Prefer fresh; escalate to persistent only on login walls.
+Switch backends without restarting: `fresh` (isolated clean room), `persistent` (Pi-owned Chrome on the saved profile with your logins), or `existing` (attach to your running Chrome). Fresh and persistent default to headless — pass `headed: true` to watch. Tabs do not transfer; call `browser_list_pages` after switching. Prefer fresh; escalate to persistent only on login walls. `rememberSite: true` pins the last-visited site's visibility (headless vs headed-background) for next time.
+
+### `browser_setup`
+
+First-run setup for the persistent profile: opens a plain headed Chrome window (no automation attached) for a human to sign in, and completes when the window closes. If the profile is already initialized it says so and points at `browser_reauth` instead.
+
+### `browser_status`
+
+Plain-language status — profile readiness, execution mode, next step — without touching any page. Bootstrap initializes the profile; it never proves a site session.
+
+### `browser_reauth`
+
+Reauthenticate the persistent profile: shuts headless Chrome down cleanly, opens a headed window for the human to verify, then resumes headless. `variant: plain` opens a dependency-free window for providers that reject instrumented browsers.
+
+### `browser_open_background_tab`
+
+Existing mode only: opens a URL as an inactive tab in the collapsed `pi-browser-use` group via the Pi extension (see `extension/`). Fails clearly when the extension bridge is unavailable — never a foreground tab.
 
 ### `browser_doctor`
 
-Self-diagnostics: effective mode, whether this session launches its own Chrome, profile health, and upstream tool availability. Run it first when browser tools misbehave — it touches no pages.
+Self-diagnostics: effective mode, backend ownership (Pi-owned vs MCP-launched vs attached), profile health, tab-bridge URL, and upstream tool availability. Run it first when browser tools misbehave — it touches no pages.
 
 ### `browser_analyze_screenshot`
 
@@ -129,6 +151,8 @@ Call `browser_list_pages` first, then pass its numeric `pageId` to page-scoped t
 
 ## Browser profile
 
+The persistent browser lives in a Chrome profile directory named `pi-browser-use` inside `~/.pi/browser-profile` (one-time automatic migration from legacy `Default`/`Profile 1` layouts while Chrome is stopped), so Pi's cookies and logins are always distinguishable on disk from anything else.
+
 On startup the default persistent profile is checked for accessibility. A root-owned or unreadable default (typically from running under `sudo`) is moved aside to `~/.pi/browser-profile.inaccessible-<timestamp>` so Chrome starts fresh instead of showing a preferences dialog. An explicit custom `userDataDir` in the same state fails fast with an ownership remediation hint. Never run the agent (or anything launching this browser) via `sudo`.
 
 ## Performance
@@ -138,6 +162,8 @@ On startup the default persistent profile is checked for accessibility. A root-o
 ## Bundled skills
 
 - `browser-policy` — CLI-first decision order, session modes, bot-wall and safety rules.
+- `gmail-auth` — Gmail inbox verification, challenge handling, headless/headed pinning.
+- `auth-bootstrap` — first-run login flow for the persistent profile.
 - `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, including the annotate flow.
@@ -154,6 +180,8 @@ On startup the default persistent profile is checked for accessibility. A root-o
 | `profile is already in use`        | Two sessions sharing one `userDataDir`                                                  | Use isolated mode or separate dirs per session                                       |
 | Stale uid errors                   | Page re-rendered after your snapshot                                                    | Take a fresh snapshot; ids invalidate on every action                                |
 | Vision tool missing                | No `visionModel` configured                                                             | Add it; otherwise use tree uids, or the global `vision` skill for vision-less models |
+| "Allow remote debugging?" popup    | Chrome 144+ consent gate for MCP auto-attach in Existing mode                           | Click Allow (once per Pi session); persistent mode never triggers it                 |
+| Pi tab closed the wrong tab        | Page IDs shift when tabs close — fixed                                                  | Existing `close_page` now refuses tabs Pi didn't open unless `force: true`           |
 
 ## License
 

package/dist/auth-verifiers.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Skill-level site authentication verifiers (spec section 6).
+ *
+ * There is intentionally no generic `isAuthenticated()` heuristic: each site
+ * presents different authenticated and unauthenticated states, so detection
+ * lives here per site. The browser subsystem only handles the resulting
+ * BrowserAuthRequired by switching Persistent into reauthentication.
+ *
+ * A verifier declares:
+ * - destination URL (where to check),
+ * - authenticated-state check,
+ * - login/challenge-state check.
+ * `ensureSiteAuthenticated` runs them against snapshot text and throws
+ * BrowserAuthRequired when a login/challenge is detected.
+ */
+export interface SiteAuthVerifier {
+    /** Stable provider id used in BrowserAuthRequired + status UX. */
+    provider: string;
+    /** Page to open for the auth check. */
+    destinationUrl: string;
+    /** True when the snapshot shows the authenticated state. */
+    isAuthenticated: (snapshotText: string, url: string) => boolean;
+    /** True when the snapshot shows a login/challenge wall. */
+    isLoginOrChallenge: (snapshotText: string, url: string) => boolean;
+}
+export interface AuthCheckPage {
+    url: string;
+    snapshotText: string;
+}
+export type AuthCheckResult = {
+    status: 'authenticated';
+} | {
+    status: 'auth-required';
+    provider: string;
+    url: string;
+} | {
+    status: 'unknown';
+};
+/** Classify one snapshot without side effects. */
+export declare function checkSiteAuth(verifier: SiteAuthVerifier, page: AuthCheckPage): AuthCheckResult;
+/** Gmail: inbox DOM vs Google login/challenge (never conflate Chrome-profile
+ * sign-in with a mail.google.com session — they are different states). */
+export declare const gmailVerifier: SiteAuthVerifier;
+/** GitHub: settings/profile page shows the username when signed in. */
+export declare const githubVerifier: SiteAuthVerifier;
+/** Registry of built-in verifiers, keyed by provider id. */
+export declare const BUILTIN_VERIFIERS: Record<string, SiteAuthVerifier>;
+export interface AuthBrowser {
+    openPage(url: string): Promise<{
+        url: string;
+        snapshotText: string;
+    }>;
+}
+/**
+ * Open the verifier destination, classify, and either return or throw
+ * BrowserAuthRequired. `unknown` is returned (not thrown) so callers can
+ * decide — an unrecognized page is not proof of a login wall.
+ */
+export declare function ensureSiteAuthenticated(browser: AuthBrowser, verifier: SiteAuthVerifier): Promise<AuthCheckResult>;
+//# sourceMappingURL=auth-verifiers.d.ts.map

package/dist/auth-verifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-verifiers.d.ts","sourceRoot":"","sources":["../src/auth-verifiers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,QAAQ,EAAE,MAAM,CAAA;IAChB,uCAAuC;IACvC,cAAc,EAAE,MAAM,CAAA;IACtB,4DAA4D;IAC5D,eAAe,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;IAC/D,2DAA2D;IAC3D,kBAAkB,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,OAAO,CAAA;CACnE;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,YAAY,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,MAAM,eAAe,GACvB;IAAE,MAAM,EAAE,eAAe,CAAA;CAAE,GAC3B;IAAE,MAAM,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,MAAM,EAAE,SAAS,CAAA;CAAE,CAAA;AAEzB,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,gBAAgB,EAAE,IAAI,EAAE,aAAa,GAAG,eAAe,CAM9F;AAwBD;0EAC0E;AAC1E,eAAO,MAAM,aAAa,EAAE,gBAc3B,CAAA;AAID,uEAAuE;AACvE,eAAO,MAAM,cAAc,EAAE,gBAU5B,CAAA;AAED,4DAA4D;AAC5D,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAG9D,CAAA;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACtE;AAED;;;;GAIG;AACH,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,WAAW,EACpB,QAAQ,EAAE,gBAAgB,GACzB,OAAO,CAAC,eAAe,CAAC,CAO1B"}

package/dist/auth-verifiers.js

@@ -0,0 +1,92 @@
+/**
+ * Skill-level site authentication verifiers (spec section 6).
+ *
+ * There is intentionally no generic `isAuthenticated()` heuristic: each site
+ * presents different authenticated and unauthenticated states, so detection
+ * lives here per site. The browser subsystem only handles the resulting
+ * BrowserAuthRequired by switching Persistent into reauthentication.
+ *
+ * A verifier declares:
+ * - destination URL (where to check),
+ * - authenticated-state check,
+ * - login/challenge-state check.
+ * `ensureSiteAuthenticated` runs them against snapshot text and throws
+ * BrowserAuthRequired when a login/challenge is detected.
+ */
+import { BrowserAuthRequired } from './session.js';
+/** Classify one snapshot without side effects. */
+export function checkSiteAuth(verifier, page) {
+    if (verifier.isAuthenticated(page.snapshotText, page.url))
+        return { status: 'authenticated' };
+    if (verifier.isLoginOrChallenge(page.snapshotText, page.url)) {
+        return { status: 'auth-required', provider: verifier.provider, url: page.url };
+    }
+    return { status: 'unknown' };
+}
+const GOOGLE_LOGIN_URL = /accounts\.google\.com\/(v\d+\/)?(signin|ServiceLogin|challenge|password|otp|verification)/i;
+const GOOGLE_LOGIN_QUERY = /[?&](flowEntry=ServiceLogin|flowName=WebLiteSignIn|service=mail)/i;
+const GOOGLE_CHALLENGE_COPY = /verify it'?s you|2-step verification|two-factor|enter your password|choose an account to continue|sign in to continue to gmail|to continue to gmail/i;
+/** Raw-DOM login redirect: Gmail serves a JS hop to accounts.google.com. */
+const GMAIL_LOGIN_BASE = /<base\s+href="https:\/\/accounts\.google\.com/i;
+/**
+ * Inbox markers. Deliberately excludes bare "primary": Google login pages
+ * embed it in CSS custom properties (--gm3-sys-color-primary), which caused
+ * a false authenticated verdict on real sign-in HTML (live-tested 2026-09).
+ */
+const GMAIL_INBOX_MARKERS = [
+    /inbox/i,
+    /compose/i,
+    /search mail/i,
+    /conversation view/i,
+    /sent mail/i,
+    /\bdrafts\b/i,
+];
+/** Gmail: inbox DOM vs Google login/challenge (never conflate Chrome-profile
+ * sign-in with a mail.google.com session — they are different states). */
+export const gmailVerifier = {
+    provider: 'google',
+    destinationUrl: 'https://mail.google.com/',
+    isAuthenticated: (text, url) => {
+        if (!/mail\.google\.com/i.test(url))
+            return false;
+        if (GOOGLE_LOGIN_URL.test(url) || GOOGLE_LOGIN_QUERY.test(url))
+            return false;
+        if (GMAIL_LOGIN_BASE.test(text) || GOOGLE_CHALLENGE_COPY.test(text))
+            return false;
+        return GMAIL_INBOX_MARKERS.filter((pattern) => pattern.test(text)).length >= 2;
+    },
+    isLoginOrChallenge: (text, url) => GOOGLE_LOGIN_URL.test(url) ||
+        GOOGLE_LOGIN_QUERY.test(url) ||
+        GMAIL_LOGIN_BASE.test(text) ||
+        GOOGLE_CHALLENGE_COPY.test(text),
+};
+const GITHUB_LOGIN_URL = /(^|\/)((login|session|auth)(\/|$|[?#]))/i;
+/** GitHub: settings/profile page shows the username when signed in. */
+export const githubVerifier = {
+    provider: 'github',
+    destinationUrl: 'https://github.com/settings/profile',
+    isAuthenticated: (text, url) => /github\.com\/settings\/profile/i.test(url) &&
+        /public profile|update profile|contributions|profile picture/i.test(text),
+    isLoginOrChallenge: (text, url) => /github\.com\/login/i.test(url) ||
+        GITHUB_LOGIN_URL.test(url) ||
+        (/sign in to github/i.test(text) && /username or email|password/i.test(text)),
+};
+/** Registry of built-in verifiers, keyed by provider id. */
+export const BUILTIN_VERIFIERS = {
+    google: gmailVerifier,
+    github: githubVerifier,
+};
+/**
+ * Open the verifier destination, classify, and either return or throw
+ * BrowserAuthRequired. `unknown` is returned (not thrown) so callers can
+ * decide — an unrecognized page is not proof of a login wall.
+ */
+export async function ensureSiteAuthenticated(browser, verifier) {
+    const page = await browser.openPage(verifier.destinationUrl);
+    const result = checkSiteAuth(verifier, page);
+    if (result.status === 'auth-required') {
+        throw new BrowserAuthRequired({ provider: result.provider, url: result.url });
+    }
+    return result;
+}
+//# sourceMappingURL=auth-verifiers.js.map

package/dist/auth-verifiers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth-verifiers.js","sourceRoot":"","sources":["../src/auth-verifiers.ts"],"names":[],"mappings":"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"}

package/dist/chrome-launcher.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Pi-owned Chrome process management (spec sections 3 and 4).
+ *
+ * Normal automation launches Chrome directly with the Pi profile and an
+ * ephemeral loopback remote-debugging port, then MCP attaches via
+ * `--browser-url`. This keeps one Chrome process per profile and avoids the
+ * default WebDriver launch path where authentication often breaks:
+ *
+ * ```text
+ * Google Chrome --user-data-dir="<pi-profile>"
+ *   --remote-debugging-port=<ephemeral> [--headless]
+ *        ↕
+ * chrome-devtools-mcp --browser-url=http://127.0.0.1:<port>
+ * ```
+ *
+ * Bootstrap (first-run auth) launches headed Chrome *without* MCP/Puppeteer
+ * so it looks like an ordinary manually launched browser.
+ */
+export interface ChromeLaunchOptions {
+    userDataDir: string;
+    /** Named profile directory inside userDataDir (e.g. pi-browser-use). */
+    profileDirectory?: string;
+    /** Ephemeral loopback port. Allocated automatically when omitted. */
+    port?: number;
+    headless?: boolean;
+    /** Extra Chrome flags appended after the managed ones. */
+    chromeArgs?: string[];
+    executablePath?: string;
+    /** How long to wait for the DevTools endpoint. Default 15s. */
+    readyTimeoutMs?: number;
+}
+export interface ChromeProcess {
+    readonly pid: number | undefined;
+    readonly port: number;
+    readonly browserUrl: string;
+    readonly userDataDir: string;
+    /** True once the process has exited. */
+    readonly exited: boolean;
+    /** Resolves when the process exits (bootstrap uses this: close → READY). */
+    waitForExit(): Promise<number | null>;
+    /** SIGTERM, then SIGKILL after `graceMs` if still alive. */
+    shutdown(graceMs?: number): Promise<void>;
+}
+/** Chrome/Chromium executable candidates by platform (stable first). */
+export declare function chromeExecutableCandidates(): string[];
+/** Resolve the Chrome executable: explicit path wins, else first candidate. */
+export declare function findChromeExecutable(executablePath?: string): string;
+/** Allocate a free loopback port (never hardcode 9222). */
+export declare function allocateEphemeralPort(): Promise<number>;
+/**
+ * Managed Chrome flags. Headed bootstrap omits `--headless` and debugging
+ * entirely when `debugPort` is 0 (plain manual browser, spec section 3).
+ */
+export declare function buildChromeArgs(options: {
+    userDataDir: string;
+    profileDirectory?: string;
+    port?: number;
+    headless?: boolean;
+    chromeArgs?: string[];
+}): string[];
+/** Poll the DevTools `/json/version` endpoint until it answers or times out. */
+export declare function waitForDevToolsEndpoint(port: number, options?: {
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+}): Promise<{
+    browserUrl: string;
+    webSocketDebuggerUrl: string;
+}>;
+/**
+ * Launch Pi-owned Chrome. The caller must hold the profile lock
+ * (see `profile-lock.ts`) for `userDataDir` before calling.
+ */
+export declare function launchChrome(options: ChromeLaunchOptions): Promise<ChromeProcess>;
+/**
+ * AppleScript that raises the exact Chrome process by pid. Unlike app-level
+ * `activate` (which may front the user's daily windows instead), this targets
+ * Pi-owned Chrome only. Foreground is reserved for explicit user-requested
+ * views and auth handoffs — never automation.
+ */
+export declare function buildFrontProcessScript(pid: number): string;
+/** Best-effort fronting of Pi-owned Chrome (macOS only). Returns success. */
+export declare function frontProcessByPid(pid: number | undefined, runner?: (cmd: string, args: string[]) => void): boolean;
+/**
+ * AppleScript that raises the Chrome window holding the marker URL.
+ * Pure (testable): execution lives with the caller. Foreground is reserved
+ * for explicit user-requested views and auth handoffs — never automation.
+ */
+export declare function buildFocusWindowScript(markerUrl: string): string;
+/**
+ * Launch the headed first-run/setup browser (spec section 3): same Pi
+ * profile, no MCP, no Puppeteer, no remote debugging — an ordinary manually
+ * launched Chrome. Resolves when the user closes the window.
+ */
+export declare function launchSetupBrowser(options: {
+    userDataDir: string;
+    profileDirectory?: string;
+    executablePath?: string;
+    chromeArgs?: string[];
+}): Promise<number | null>;
+//# sourceMappingURL=chrome-launcher.d.ts.map

package/dist/chrome-launcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chrome-launcher.d.ts","sourceRoot":"","sources":["../src/chrome-launcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAA;IACnB,wEAAwE;IACxE,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;IACrB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,+DAA+D;IAC/D,cAAc,CAAC,EAAE,MAAM,CAAA;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,wCAAwC;IACxC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAA;IACxB,4EAA4E;IAC5E,WAAW,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IACrC,4DAA4D;IAC5D,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1C;AAED,wEAAwE;AACxE,wBAAgB,0BAA0B,IAAI,MAAM,EAAE,CAsBrD;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAAC,cAAc,CAAC,EAAE,MAAM,GAAG,MAAM,CAepE;AAED,2DAA2D;AAC3D,wBAAgB,qBAAqB,IAAI,OAAO,CAAC,MAAM,CAAC,CAavD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB,GAAG,MAAM,EAAE,CAcX;AAED,gFAAgF;AAChF,wBAAsB,uBAAuB,CAC3C,IAAI,EAAE,MAAM,EACZ,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAA;CAAE,GACzD,OAAO,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,oBAAoB,EAAE,MAAM,CAAA;CAAE,CAAC,CAsB/D;AAgDD;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CA8BvF;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAM3D;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,MAAM,GAAG,SAAS,EACvB,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,GAC7C,OAAO,CAST;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAehE;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,OAAO,EAAE;IAChD,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB,cAAc,CAAC,EAAE,MAAM,CAAA;IACvB,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAYzB"}

package/dist/chrome-launcher.js

@@ -0,0 +1,268 @@
+/**
+ * Pi-owned Chrome process management (spec sections 3 and 4).
+ *
+ * Normal automation launches Chrome directly with the Pi profile and an
+ * ephemeral loopback remote-debugging port, then MCP attaches via
+ * `--browser-url`. This keeps one Chrome process per profile and avoids the
+ * default WebDriver launch path where authentication often breaks:
+ *
+ * ```text
+ * Google Chrome --user-data-dir="<pi-profile>"
+ *   --remote-debugging-port=<ephemeral> [--headless]
+ *        ↕
+ * chrome-devtools-mcp --browser-url=http://127.0.0.1:<port>
+ * ```
+ *
+ * Bootstrap (first-run auth) launches headed Chrome *without* MCP/Puppeteer
+ * so it looks like an ordinary manually launched browser.
+ */
+import { execFileSync, spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createServer } from 'node:net';
+/** Chrome/Chromium executable candidates by platform (stable first). */
+export function chromeExecutableCandidates() {
+    if (process.platform === 'darwin') {
+        return [
+            '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+            '/Applications/Chromium.app/Contents/MacOS/Chromium',
+            '/Applications/Google Chrome Beta.app/Contents/MacOS/Google Chrome Beta',
+            '/Applications/Google Chrome Canary.app/Contents/MacOS/Google Chrome Canary',
+        ];
+    }
+    if (process.platform === 'win32') {
+        return [
+            `${process.env['PROGRAMFILES'] ?? 'C:\\Program Files'}\\Google\\Chrome\\Application\\chrome.exe`,
+            `${process.env['PROGRAMFILES(X86)'] ?? 'C:\\Program Files (x86)'}\\Google\\Chrome\\Application\\chrome.exe`,
+        ];
+    }
+    return [
+        '/usr/bin/google-chrome-stable',
+        '/usr/bin/google-chrome',
+        '/usr/bin/chromium',
+        '/usr/bin/chromium-browser',
+        '/snap/bin/chromium',
+    ];
+}
+/** Resolve the Chrome executable: explicit path wins, else first candidate. */
+export function findChromeExecutable(executablePath) {
+    if (executablePath && executablePath.length > 0) {
+        if (!existsSync(executablePath)) {
+            throw new Error(`Chrome executable not found: ${executablePath}`);
+        }
+        return executablePath;
+    }
+    const envPath = process.env['CHROME_PATH']?.trim();
+    if (envPath && existsSync(envPath))
+        return envPath;
+    for (const candidate of chromeExecutableCandidates()) {
+        if (existsSync(candidate))
+            return candidate;
+    }
+    throw new Error('Chrome executable was not found. Install Google Chrome Stable or set executablePath.');
+}
+/** Allocate a free loopback port (never hardcode 9222). */
+export function allocateEphemeralPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.on('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            const port = typeof address === 'object' && address ? address.port : 0;
+            server.close((error) => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(port);
+            });
+        });
+    });
+}
+/**
+ * Managed Chrome flags. Headed bootstrap omits `--headless` and debugging
+ * entirely when `debugPort` is 0 (plain manual browser, spec section 3).
+ */
+export function buildChromeArgs(options) {
+    const args = [
+        `--user-data-dir=${options.userDataDir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+    ];
+    if (options.profileDirectory)
+        args.push(`--profile-directory=${options.profileDirectory}`);
+    if (options.port !== undefined && options.port > 0) {
+        args.push(`--remote-debugging-port=${options.port}`);
+        args.push('--remote-allow-origins=*');
+    }
+    if (options.headless === true)
+        args.push('--headless');
+    args.push(...(options.chromeArgs ?? []));
+    return args;
+}
+/** Poll the DevTools `/json/version` endpoint until it answers or times out. */
+export async function waitForDevToolsEndpoint(port, options) {
+    const timeoutMs = options?.timeoutMs ?? 15_000;
+    const fetchImpl = options?.fetchImpl ?? fetch;
+    const browserUrl = `http://127.0.0.1:${port}`;
+    const deadline = Date.now() + timeoutMs;
+    let lastError;
+    while (Date.now() < deadline) {
+        try {
+            const response = await fetchImpl(`${browserUrl}/json/version`);
+            if (response.ok) {
+                const info = (await response.json());
+                return { browserUrl, webSocketDebuggerUrl: info.webSocketDebuggerUrl ?? '' };
+            }
+            lastError = new Error(`DevTools endpoint answered ${response.status}`);
+        }
+        catch (error) {
+            lastError = error;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new Error(`Timed out waiting for Chrome DevTools on ${browserUrl} (${lastError instanceof Error ? lastError.message : String(lastError)})`);
+}
+class OwnedChromeProcess {
+    port;
+    browserUrl;
+    userDataDir;
+    child;
+    exitPromise;
+    exitedFlag = false;
+    constructor(child, port, browserUrl, userDataDir) {
+        this.port = port;
+        this.browserUrl = browserUrl;
+        this.userDataDir = userDataDir;
+        this.child = child;
+        this.exitPromise = new Promise((resolve) => {
+            child.on('exit', (code) => {
+                this.exitedFlag = true;
+                resolve(code);
+            });
+        });
+    }
+    get pid() {
+        return this.child.pid;
+    }
+    get exited() {
+        return this.exitedFlag || this.child.exitCode !== null;
+    }
+    waitForExit() {
+        return this.exitPromise;
+    }
+    async shutdown(graceMs = 3_000) {
+        if (this.exited)
+            return;
+        this.child.kill('SIGTERM');
+        const exited = await Promise.race([
+            this.exitPromise.then(() => true),
+            new Promise((resolve) => setTimeout(() => resolve(false), graceMs)),
+        ]);
+        if (!exited && !this.exited) {
+            this.child.kill('SIGKILL');
+            await this.exitPromise;
+        }
+    }
+}
+/**
+ * Launch Pi-owned Chrome. The caller must hold the profile lock
+ * (see `profile-lock.ts`) for `userDataDir` before calling.
+ */
+export async function launchChrome(options) {
+    const executable = findChromeExecutable(options.executablePath);
+    const port = options.port ?? (await allocateEphemeralPort());
+    const args = buildChromeArgs({
+        userDataDir: options.userDataDir,
+        profileDirectory: options.profileDirectory,
+        port,
+        headless: options.headless,
+        chromeArgs: options.chromeArgs,
+    });
+    const child = spawn(executable, args, { stdio: 'ignore', detached: false });
+    await new Promise((resolve, reject) => {
+        child.on('error', reject);
+        // Give spawn a tick to surface ENOENT-style failures before probing.
+        setTimeout(resolve, 50);
+    });
+    if (child.exitCode !== null) {
+        throw new Error(`Chrome exited immediately (code ${child.exitCode}).`);
+    }
+    try {
+        await waitForDevToolsEndpoint(port, { timeoutMs: options.readyTimeoutMs });
+    }
+    catch (error) {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            // Already gone; the endpoint error below is what matters.
+        }
+        throw error;
+    }
+    return new OwnedChromeProcess(child, port, `http://127.0.0.1:${port}`, options.userDataDir);
+}
+/**
+ * AppleScript that raises the exact Chrome process by pid. Unlike app-level
+ * `activate` (which may front the user's daily windows instead), this targets
+ * Pi-owned Chrome only. Foreground is reserved for explicit user-requested
+ * views and auth handoffs — never automation.
+ */
+export function buildFrontProcessScript(pid) {
+    return [
+        'tell application "System Events"',
+        `set frontmost of (first application process whose unix id is ${pid}) to true`,
+        'end tell',
+    ].join('\n');
+}
+/** Best-effort fronting of Pi-owned Chrome (macOS only). Returns success. */
+export function frontProcessByPid(pid, runner) {
+    if (pid === undefined || process.platform !== 'darwin')
+        return false;
+    try {
+        const run = runner ?? ((cmd, args) => void execFileSync(cmd, args));
+        run('osascript', ['-e', buildFrontProcessScript(pid)]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * AppleScript that raises the Chrome window holding the marker URL.
+ * Pure (testable): execution lives with the caller. Foreground is reserved
+ * for explicit user-requested views and auth handoffs — never automation.
+ */
+export function buildFocusWindowScript(markerUrl) {
+    const needle = markerUrl.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+    return [
+        'tell application "Google Chrome"',
+        'activate',
+        'repeat with w in every window',
+        'repeat with t in every tab of w',
+        `if (URL of t starts with "${needle}") then`,
+        'set index of w to 1',
+        'exit repeat',
+        'end if',
+        'end repeat',
+        'end repeat',
+        'end tell',
+    ].join('\n');
+}
+/**
+ * Launch the headed first-run/setup browser (spec section 3): same Pi
+ * profile, no MCP, no Puppeteer, no remote debugging — an ordinary manually
+ * launched Chrome. Resolves when the user closes the window.
+ */
+export async function launchSetupBrowser(options) {
+    const executable = findChromeExecutable(options.executablePath);
+    const args = buildChromeArgs({
+        userDataDir: options.userDataDir,
+        profileDirectory: options.profileDirectory,
+        chromeArgs: options.chromeArgs,
+    });
+    const child = spawn(executable, args, { stdio: 'ignore', detached: false });
+    return new Promise((resolve, reject) => {
+        child.on('error', reject);
+        child.on('exit', (code) => resolve(code));
+    });
+}
+//# sourceMappingURL=chrome-launcher.js.map